ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • Python »
  • 3.7.2 Documentation »

Python Documentation contents

  • What's New in Python
    • 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
        • Development Runtime 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
      • 最適化
      • Other CPython Implementation Changes
      • 非推奨の 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
      • Porting to Python 3.7
        • Changes in Python Behavior
        • Python API の変更
        • C API の変更
        • CPython バイトコードの変更
        • Windows-only Changes
        • その他の CPython の実装の変更
      • Notable changes in Python 3.7.1
      • Notable changes in Python 3.7.2
    • 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
        • 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
    • 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 メンテナンスリリースで追加された新機能
        • Two new environment variables for debug mode
        • 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 3.7.2 final
        • ライブラリ
        • ビルド
        • C API
      • Python 3.7.2 release candidate 1
        • セキュリティ
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • macOS
        • IDLE
        • Tools/Demos
        • C API
      • Python 3.7.1 final
        • ライブラリ
      • Python 3.7.1 release candidate 2
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • macOS
        • C API
      • Python 3.7.1 release candidate 1
        • セキュリティ
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • macOS
        • IDLE
        • Tools/Demos
        • C API
      • Python 3.7.0 final
        • ライブラリ
        • C API
      • Python 3.7.0 release candidate 1
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • ビルド
        • Windows
        • IDLE
      • Python 3.7.0 beta 5
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • macOS
        • IDLE
      • Python 3.7.0 beta 4
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • macOS
        • IDLE
        • Tools/Demos
      • Python 3.7.0 beta 3
        • セキュリティ
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • macOS
        • IDLE
        • Tools/Demos
        • C API
      • Python 3.7.0 beta 2
        • セキュリティ
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • macOS
        • IDLE
        • Tools/Demos
      • Python 3.7.0 beta 1
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • macOS
        • C API
      • Python 3.7.0 alpha 4
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • Windows
        • Tools/Demos
        • C API
      • Python 3.7.0 alpha 3
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • macOS
        • IDLE
        • Tools/Demos
        • C API
      • Python 3.7.0 alpha 2
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • ビルド
        • IDLE
        • C API
      • Python 3.7.0 alpha 1
        • セキュリティ
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • IDLE
        • Tools/Demos
        • C API
      • Python 3.6.6 final
      • Python 3.6.6 release candidate 1
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • macOS
        • IDLE
        • Tools/Demos
        • C API
      • Python 3.6.5 final
        • テスト
        • ビルド
      • Python 3.6.5 release candidate 1
        • セキュリティ
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • macOS
        • IDLE
        • Tools/Demos
        • C API
      • Python 3.6.4 final
      • Python 3.6.4 release candidate 1
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • macOS
        • IDLE
        • Tools/Demos
        • C API
      • Python 3.6.3 final
        • ライブラリ
        • ビルド
      • Python 3.6.3 release candidate 1
        • セキュリティ
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • IDLE
        • Tools/Demos
      • Python 3.6.2 final
      • Python 3.6.2 release candidate 2
        • セキュリティ
      • Python 3.6.2 release candidate 1
        • Core and Builtins
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • IDLE
        • C API
        • ビルド
        • ドキュメント
        • Tools/Demos
        • テスト
        • Windows
      • Python 3.6.1 final
        • Core and Builtins
        • ビルド
      • Python 3.6.1 release candidate 1
        • Core and Builtins
        • ライブラリ
        • IDLE
        • Windows
        • C API
        • ドキュメント
        • テスト
        • ビルド
      • Python 3.6.0 final
      • Python 3.6.0 release candidate 2
        • Core and Builtins
        • Tools/Demos
        • Windows
        • ビルド
      • Python 3.6.0 release candidate 1
        • Core and Builtins
        • ライブラリ
        • C API
        • ドキュメント
        • Tools/Demos
      • Python 3.6.0 beta 4
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
      • Python 3.6.0 beta 3
        • Core and Builtins
        • ライブラリ
        • Windows
        • ビルド
        • テスト
      • Python 3.6.0 beta 2
        • Core and Builtins
        • ライブラリ
        • Windows
        • C API
        • ビルド
        • テスト
      • Python 3.6.0 beta 1
        • Core and Builtins
        • ライブラリ
        • IDLE
        • C API
        • テスト
        • ビルド
        • Tools/Demos
        • Windows
      • Python 3.6.0 alpha 4
        • Core and Builtins
        • ライブラリ
        • IDLE
        • テスト
        • Windows
        • ビルド
      • Python 3.6.0 alpha 3
        • Core and Builtins
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • IDLE
        • C API
        • ビルド
        • Tools/Demos
        • ドキュメント
        • テスト
      • Python 3.6.0 alpha 2
        • Core and Builtins
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • IDLE
        • ドキュメント
        • テスト
        • Windows
        • ビルド
        • Windows
        • C API
        • Tools/Demos
      • Python 3.6.0 alpha 1
        • Core and Builtins
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • IDLE
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • Tools/Demos
        • C API
      • Python 3.5.5 final
      • Python 3.5.5 release candidate 1
        • セキュリティ
        • Core and Builtins
        • ライブラリ
      • Python 3.5.4 final
        • ライブラリ
      • Python 3.5.4 release candidate 1
        • セキュリティ
        • Core and Builtins
        • ライブラリ
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • C API
      • Python 3.5.3 final
      • Python 3.5.3 release candidate 1
        • Core and Builtins
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • IDLE
        • C API
        • ドキュメント
        • テスト
        • Tools/Demos
        • Windows
        • ビルド
      • Python 3.5.2 final
        • Core and Builtins
        • テスト
        • IDLE
      • Python 3.5.2 リリース候補 1
        • Core and Builtins
        • セキュリティ
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • セキュリティ
        • ライブラリ
        • IDLE
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • Tools/Demos
        • Windows
      • Python 3.5.1 最終版
        • Core and Builtins
        • Windows
      • Python 3.5.1 release candidate 1
        • Core and Builtins
        • ライブラリ
        • IDLE
        • ドキュメント
        • テスト
        • ビルド
        • Windows
        • Tools/Demos
      • Python 3.5.0 final
        • ビルド
      • Python 3.5.0 release candidate 4
        • ライブラリ
        • ビルド
      • Python 3.5.0 release candidate 3
        • Core and Builtins
        • ライブラリ
      • Python 3.5.0 release candidate 2
        • Core and Builtins
        • ライブラリ
      • Python 3.5.0 release candidate 1
        • Core and Builtins
        • ライブラリ
        • IDLE
        • ドキュメント
        • テスト
      • Python 3.5.0 beta 4
        • Core and Builtins
        • ライブラリ
        • ビルド
      • Python 3.5.0 beta 3
        • Core and Builtins
        • ライブラリ
        • テスト
        • ドキュメント
        • ビルド
      • Python 3.5.0 beta 2
        • Core and Builtins
        • ライブラリ
      • Python 3.5.0 beta 1
        • Core and Builtins
        • ライブラリ
        • IDLE
        • テスト
        • ドキュメント
        • Tools/Demos
      • Python 3.5.0 alpha 4
        • Core and Builtins
        • ライブラリ
        • ビルド
        • テスト
        • Tools/Demos
        • C API
      • Python 3.5.0 alpha 3
        • Core and Builtins
        • ライブラリ
        • ビルド
        • テスト
        • Tools/Demos
      • Python 3.5.0 alpha 2
        • Core and Builtins
        • ライブラリ
        • ビルド
        • C API
        • Windows
      • Python 3.5.0 alpha 1
        • Core and Builtins
        • ライブラリ
        • IDLE
        • ビルド
        • C API
        • ドキュメント
        • テスト
        • 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. 文字列型 (string)
        • 3.1.3. リスト型 (list)
      • 3.2. プログラミングへの第一歩
    • 4. その他の制御フローツール
      • 4.1. if Statements
      • 4.2. for Statements
      • 4.3. range() 関数
      • 4.4. break and continue Statements, and else Clauses on Loops
      • 4.5. pass Statements
      • 4.6. 関数を定義する
      • 4.7. 関数定義についてもう少し
        • 4.7.1. デフォルトの引数値
        • 4.7.2. キーワード引数
        • 4.7.3. 任意引数リスト
        • 4.7.4. 引数リストのアンパック
        • 4.7.5. ラムダ式
        • 4.7.6. ドキュメンテーション文字列
        • 4.7.7. 関数のアノテーション
      • 4.8. 間奏曲: コーディングスタイル
    • 5. データ構造
      • 5.1. リスト型についてもう少し
        • 5.1.1. リストをスタックとして使う
        • 5.1.2. リストをキューとして使う
        • 5.1.3. リストの内包表記
        • 5.1.4. ネストしたリストの内包表記
      • 5.2. The del statement
      • 5.3. タプルとシーケンス
      • 5.4. 集合型
      • 5.5. 辞書型 (dictionary)
      • 5.6. ループのテクニック
      • 5.7. 条件についてもう少し
      • 5.8. シーケンスとその他の型の比較
    • 6. モジュール (module)
      • 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. 定義済みクリーンアップ処理
    • 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.1.3. OpenSolaris
      • 2.2. Python のビルド
      • 2.3. Python に関係するパスとファイル
      • 2.4. その他
      • 2.5. エディタと IDE
    • 3. Windows で Python を使う
      • 3.1. 完全版インストーラ
        • 3.1.1. インストール手順
        • 3.1.2. MAX_PATH の制限を除去する
        • 3.1.3. インストーラの GUI なしでインストールする
        • 3.1.4. ダウンロード不要なインストール
        • 3.1.5. インストール後の変更
      • 3.2. Microsoft ストアパッケージ
        • 3.2.1. 既知の問題
      • 3.3. nuget.org パッケージ
      • 3.4. 埋め込み可能なパッケージ
        • 3.4.1. Python アプリケーション
        • 3.4.2. Python の埋め込み
      • 3.5. 別のバンドル
      • 3.6. Python を構成する
        • 3.6.1. 補足: 環境変数の設定
        • 3.6.2. Python 実行ファイルを見つける
      • 3.7. Windows の Python ランチャ
        • 3.7.1. 最初に
          • 3.7.1.1. コマンドラインから起動する
          • 3.7.1.2. 仮想環境 (Virtual environments)
          • 3.7.1.3. スクリプトから起動する
          • 3.7.1.4. ファイルの関連付けから起動する
        • 3.7.2. シェバン (shebang) 行
        • 3.7.3. シェバン行の引数
        • 3.7.4. カスタマイズ
          • 3.7.4.1. INI ファイルによるカスタマイズ
          • 3.7.4.2. デフォルトのPythonバージョンのカスタマイズ
        • 3.7.5. 診断
      • 3.8. モジュールの検索
      • 3.9. 追加のモジュール
        • 3.9.1. PyWin32
        • 3.9.2. cx_Freeze
        • 3.9.3. WConio
      • 3.10. Windows 上で Python をコンパイルする
      • 3.11. ほかのプラットフォーム
    • 4. Macintosh で Python を使う
      • 4.1. MacPython の入手とインストール
        • 4.1.1. Python スクリプトの実行方法
        • 4.1.2. GUI でスクリプトを実行
        • 4.1.3. Configuration
      • 4.2. IDE
      • 4.3. 追加の Python パッケージのインストール
      • 4.4. Mac での GUI プログラミング
      • 4.5. Mac 上の Python アプリケーションの配布
      • 4.6. 他のリソース
  • 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. 予約済みの識別子種 (reserved classes of identifiers)
      • 2.4. リテラル
        • 2.4.1. 文字列およびバイト列リテラル
        • 2.4.2. 文字列リテラルの結合 (concatenation)
        • 2.4.3. フォーマット済み文字列リテラル
        • 2.4.4. 数値リテラル
        • 2.4.5. 整数リテラル
        • 2.4.6. 浮動小数点数リテラル
        • 2.4.7. 虚数 (imaginary) リテラル
      • 2.5. 演算子
      • 2.6. デリミタ (delimiter)
    • 3. データモデル
      • 3.1. オブジェクト、値、および型
      • 3.2. 標準型の階層
      • 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.2.4.1. __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.6. 呼び出し可能オブジェクトをエミュレートする
        • 3.3.7. コンテナをエミュレートする
        • 3.3.8. 数値型をエミュレートする
        • 3.3.9. with文とコンテキストマネージャ
        • 3.3.10. 特殊メソッド検索
      • 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. 組み込みと制限付きの実行
        • 4.2.4. 動的な機能とのやりとり
      • 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. __main__ に対する特別な考慮
        • 5.7.1. __main__.__spec__
      • 5.8. 取り掛かり中の問題
      • 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. 条件式 (Conditional Expressions)
      • 6.13. ラムダ (lambda)
      • 6.14. 式のリスト
      • 6.15. 評価順序
      • 6.16. 演算子の優先順位
    • 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. The assert statement
      • 7.4. The pass statement
      • 7.5. The del statement
      • 7.6. The return statement
      • 7.7. The yield statement
      • 7.8. The raise statement
      • 7.9. The break statement
      • 7.10. The continue statement
      • 7.11. The import statement
        • 7.11.1. future 文 (future statement)
      • 7.12. The global statement
      • 7.13. The nonlocal statement
    • 8. 複合文 (compound statement)
      • 8.1. The if statement
      • 8.2. The while statement
      • 8.3. The for statement
      • 8.4. The try statement
      • 8.5. The with statement
      • 8.6. 関数定義
      • 8.7. クラス定義
      • 8.8. コルーチン
        • 8.8.1. コルーチン関数定義
        • 8.8.2. The async for statement
        • 8.8.3. The async with statement
    • 9. トップレベル要素
      • 9.1. 完全な Python プログラム
      • 9.2. ファイル入力
      • 9.3. 対話的入力
      • 9.4. 式入力
    • 10. 完全な文法仕様
  • Python 標準ライブラリ
    • はじめに
      • Notes on availability
    • 組み込み関数
    • 組み込み定数
      • site モジュールで追加される定数
    • 組み込み型
      • 真理値判定
      • Boolean Operations --- and, or, not
      • 比較
      • 数値型 int, float, complex
        • 整数型におけるビット単位演算
        • 整数型における追加のメソッド
        • 浮動小数点数に対する追加のメソッド
        • 数値型のハッシュ化
      • イテレータ型
        • ジェネレータ型
      • シーケンス型 --- list, tuple, range
        • 共通のシーケンス演算
        • イミュータブルなシーケンス型
        • ミュータブルなシーケンス型
        • リスト型 (list)
        • タプル型 (tuple)
        • range
      • テキストシーケンス型 --- str
        • 文字列メソッド
        • printf 形式の文字列書式化
      • バイナリシーケンス型 --- bytes, bytearray, memoryview
        • バイトオブジェクト
        • bytearray オブジェクト
        • bytes と bytearray の操作
        • printf 形式での bytes の書式化
        • メモリビュー
      • set（集合）型 --- set, frozenset
      • マッピング型 --- dict
        • 辞書ビューオブジェクト
      • コンテキストマネージャ型
      • その他の組み込み型
        • モジュール (module)
        • クラスおよびクラスインスタンス
        • 関数
        • メソッド
        • コードオブジェクト
        • 型オブジェクト
        • ヌルオブジェクト
        • Ellipsis オブジェクト
        • NotImplemented オブジェクト
        • ブール値
        • 内部オブジェクト
      • 特殊属性
    • 組み込み例外
      • 基底クラス
      • 具象例外
        • OS 例外
      • 警告
      • 例外のクラス階層
    • テキスト処理サービス
      • string --- 一般的な文字列操作
        • 文字列定数
        • カスタムの文字列書式化
        • 書式指定文字列の文法
          • 書式指定ミニ言語仕様
          • 書式指定例
        • テンプレート文字列
        • ヘルパー関数
      • re --- 正規表現操作
        • 正規表現のシンタックス
        • モジュールコンテンツ
        • 正規表現オブジェクト
        • マッチオブジェクト
        • 正規表現の例
          • ペアの確認
          • scanf() をシミュレートする
          • search() vs. match()
          • 電話帳を作る
          • テキストの秘匿
          • 全ての副詞を見つける
          • 全ての副詞とその位置を見つける
          • Raw 文字列記法
          • トークナイザを書く
      • difflib --- 差分の計算を助ける
        • SequenceMatcherオブジェクト
        • SequenceMatcher の例
        • Differ オブジェクト
        • Differ の例
        • difflib のコマンドラインインタフェース
      • textwrap --- テキストの折り返しと詰め込み
      • unicodedata --- Unicode データベース
      • stringprep --- インターネットのための文字列調製
      • readline --- GNU readline のインタフェース
        • 初期化ファイル
        • 行バッファ
        • 履歴ファイル
        • 履歴リスト
        • 開始フック
        • 補完
        • 使用例
      • rlcompleter --- GNU readline向け補完関数
        • Completerオブジェクト
    • バイナリデータ処理
      • struct --- バイト列をパックされたバイナリデータとして解釈する
        • 関数と例外
        • 書式文字列
          • バイトオーダ、サイズ、アラインメント
          • 書式指定文字
          • 使用例
        • クラス
      • codecs --- codec レジストリと基底クラス
        • 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 --- 基本的な日付型および時間型
        • 利用可能なデータ型
        • timedelta オブジェクト
        • date オブジェクト
        • datetime オブジェクト
        • time オブジェクト
        • tzinfo オブジェクト
        • timezone オブジェクト
        • strftime() と strptime() の振る舞い
      • calendar --- 一般的なカレンダーに関する関数群
      • collections --- コンテナデータ型
        • ChainMap オブジェクト
          • ChainMap の例とレシピ
        • Counter オブジェクト
        • deque オブジェクト
          • deque のレシピ
        • defaultdict オブジェクト
          • defaultdict の使用例
        • namedtuple() 名前付きフィールドを持つタプルのファクトリ関数
        • OrderedDict オブジェクト
          • OrderedDict の例とレシピ
        • UserDict オブジェクト
        • UserList オブジェクト
        • UserString オブジェクト
      • collections.abc --- コレクションの抽象基底クラス
        • コレクション抽象基底クラス
      • heapq --- ヒープキューアルゴリズム
        • 基本的な例
        • 優先度キュー実装の注釈
        • 理論
      • bisect --- 配列二分法アルゴリズム
        • ソート済みリストの探索
        • その他の使用例
      • array --- 効率のよい数値アレイ
      • weakref --- 弱参照
        • 弱参照オブジェクト
        • 使用例
        • ファイナライザオブジェクト
        • ファイナライザと __del__() メソッドとの比較
      • types --- 動的な型生成と組み込み型に対する名前
        • 動的な型生成
        • 標準的なインタプリタ型
        • 追加のユーティリティクラスと関数
        • コルーチンユーティリティ関数
      • copy --- 浅いコピーおよび深いコピー操作
      • pprint --- データ出力の整然化
        • PrettyPrinter オブジェクト
        • 使用例
      • reprlib --- もう一つの repr() の実装
        • Reprオブジェクト
        • Reprオブジェクトをサブクラス化する
      • enum --- 列挙型のサポート
        • モジュールコンテンツ
        • Enum の作成
        • 列挙型メンバーおよびそれらの属性へのプログラム的アクセス
        • 列挙型メンバーと値の重複
        • 番号付けの値が同一であることの確認
        • 値の自動設定を使う
        • イテレーション
        • 比較
        • 列挙型で許されるメンバーと属性
        • Restricted Enum subclassing
        • Pickle 化
        • 機能 API
        • 派生列挙型
          • IntEnum
          • IntFlag
          • Flag
          • その他
        • 興味深い例
          • 値の省略
            • auto を使う
            • object を使う
            • 解説文字列を使う
            • 独自の __new__() を使う
          • OrderedEnum
          • DuplicateFreeEnum
          • Planet
          • TimePeriod
        • Enum はどう違うのか?
          • Enum クラス
          • Enum メンバー (インスタンス)
          • 細かい点
            • __dunder__ 名のサポート
            • _sunder_ 名のサポート
            • Enum メンバー型
            • Enum クラスとメンバーの真偽値
            • メソッド付きの Enum クラス
            • Flag のメンバーの組み合わせ
    • 数値と数学モジュール
      • numbers --- 数の抽象基底クラス
        • 数値塔
        • 型実装者のための注意事項
          • さらに数のABCを追加する
          • 算術演算の実装
      • math --- 数学関数
        • 数論および数表現の関数
        • 指数関数と対数関数
        • 三角関数
        • 角度変換
        • 双曲線関数
        • 特殊関数
        • 定数
      • cmath --- 複素数のための数学関数
        • 極座標変換
        • 指数関数と対数関数
        • 三角関数
        • 双曲線関数
        • 類別関数
        • 定数
      • decimal --- 十進固定及び浮動小数点数の算術演算
        • クイックスタートチュートリアル
        • Decimal オブジェクト
          • 論理引数
        • Context オブジェクト
        • 定数
        • 丸めモード
        • シグナル
        • 浮動小数点数に関する注意
          • 精度を上げて丸め誤差を抑制する
          • 特殊値
        • スレッドを使った処理
        • レシピ
        • Decimal FAQ
      • fractions --- 有理数
      • random --- 擬似乱数を生成する
        • 保守 (bookkeeping) 関数
        • 整数用の関数
        • シーケンス用の関数
        • 実数分布
        • 他の生成器
        • 再現性について
        • 例とレシピ
      • statistics --- 数理統計関数
        • 平均及び中心位置の測度
        • 分散の測度
        • 関数の詳細
        • 例外
    • 関数型プログラミング用モジュール
      • itertools --- 効率的なループ実行のためのイテレータ生成関数
        • Itertool関数
        • Itertools レシピ
      • functools --- 高階関数と呼び出し可能オブジェクトの操作
        • partial オブジェクト
      • operator --- 関数形式の標準演算子
        • 演算子から関数への対応表
        • インプレース演算子
    • ファイルとディレクトリへのアクセス
      • pathlib --- オブジェクト指向のファイルシステムパス
        • 基本的な使い方
        • 純粋パス
          • 全般的な性質
          • 演算子
          • 個別の構成要素へのアクセス
          • メソッドとプロパティ
        • 具象パス
          • メソッド
        • os モジュールにあるツールとの対応付け
      • os.path --- 共通のパス名操作
      • fileinput --- 複数の入力ストリームをまたいだ行の繰り返し処理をサポートする
      • stat --- stat() の結果を解釈する
      • filecmp --- ファイルおよびディレクトリの比較
        • dircmp クラス
      • tempfile --- 一時ファイルやディレクトリの作成
        • 使用例
        • 非推奨の関数と変数
      • glob --- Unix 形式のパス名のパターン展開
      • fnmatch --- Unix ファイル名のパターンマッチ
      • linecache --- テキストラインにランダムアクセスする
      • shutil --- 高水準のファイル操作
        • ディレクトリとファイルの操作
          • copytree の例
          • rmtree の例
        • アーカイブ化操作
          • アーカイブ化の例
        • 出力ターミナルのサイズの取得
      • macpath --- Mac OS 9 のパス操作関数
    • データの永続化
      • pickle --- Python オブジェクトの直列化
        • 他の Python モジュールとの関係
          • marshal との比較
          • json との比較
        • データストリームの形式
        • モジュールインタフェース
        • pickle 化、非 pickle 化できるもの
        • クラスインスタンスの pickle 化
          • 外部オブジェクトの永続化
          • ディスパッチテーブル
          • 状態を持つオブジェクトの扱い
        • グローバル変数を制限する
        • 性能
        • 使用例
      • copyreg --- pickle サポート関数を登録する
        • 使用例
      • shelve --- Python オブジェクトの永続化
        • 制限事項
        • 使用例
      • marshal --- 内部使用向けの Python オブジェクト整列化
      • dbm --- Unix "データベース" へのインタフェース
        • dbm.gnu --- GNU による dbm 拡張
        • dbm.ndbm --- ndbm に基づくインタフェース
        • dbm.dumb --- 可搬性のある DBM 実装
      • sqlite3 --- SQLite データベースに対する DB-API 2.0 インタフェース
        • モジュールの関数と定数
        • Connection オブジェクト
        • カーソルオブジェクト
        • Row オブジェクト
        • 例外
        • SQLite と Python の型
          • はじめに
          • 追加された Python の型を SQLite データベースに格納するために適合関数を使う
            • オブジェクト自身で適合するようにする
            • 適合関数を登録する
          • SQLite の値を好きな Python 型に変換する
          • デフォルトの適合関数と変換関数
        • トランザクション制御
        • sqlite3 の効率的な使い方
          • ショートカットメソッドを使う
          • 位置ではなく名前でカラムにアクセスする
          • コネクションをコンテキストマネージャーとして利用する
        • 既知の問題
          • マルチスレッド
    • データ圧縮とアーカイブ
      • zlib --- gzip 互換の圧縮
      • gzip --- gzip ファイルのサポート
        • 使い方の例
      • bz2 --- bzip2 圧縮のサポート
        • ファイルの圧縮/解凍
        • 逐次圧縮および展開
        • 一括圧縮/解凍
      • lzma --- LZMA アルゴリズムを使用した圧縮
        • 圧縮ファイルへの読み書き
        • メモリ上での圧縮と展開
        • その他
        • カスタムフィルタチェインの指定
        • 使用例
      • zipfile --- ZIP アーカイブの処理
        • ZipFile オブジェクト
        • PyZipFile オブジェクト
        • ZipInfo オブジェクト
        • コマンドラインインターフェイス
          • コマンドラインオプション
      • tarfile --- tar アーカイブファイルの読み書き
        • TarFile オブジェクト
        • TarInfo オブジェクト
        • コマンドラインインターフェイス
          • コマンドラインオプション
        • 使用例
        • サポートしている tar フォーマット
        • Unicode に関する問題
    • ファイルフォーマット
      • csv --- CSV ファイルの読み書き
        • モジュールコンテンツ
        • Dialect クラスと書式化パラメータ
        • reader オブジェクト
        • writer オブジェクト
        • 使用例
      • configparser --- 設定ファイルのパーサー
        • クイックスタート
        • サポートされるデータ型
        • 代替値
        • サポートするINI ファイルの構造
        • 値の補間
        • マップ型プロトコルアクセス
        • パーサーの振る舞いをカスタマイズする
        • レガシーな API の例
        • ConfigParser オブジェクト
        • RawConfigParser オブジェクト
        • 例外
      • netrc --- netrc ファイルの処理
        • netrc オブジェクト
      • xdrlib --- XDR データのエンコードおよびデコード
        • Packer オブジェクト
        • Unpacker オブジェクト
        • 例外
      • plistlib --- Mac OS X .plist ファイルの生成と解析
        • 使用例
    • 暗号関連のサービス
      • hashlib --- セキュアハッシュおよびメッセージダイジェスト
        • ハッシュアルゴリズム
        • SHAKE 可変長ダイジェスト
        • 鍵導出
        • BLAKE2
          • ハッシュオブジェクトの作成
          • 定数
          • 使用例
            • 簡単なハッシュ化
            • Using different digest sizes
            • Keyed hashing
            • Randomized hashing
            • Personalization
            • ツリーモード
          • クレジット:
      • hmac --- メッセージ認証のための鍵付きハッシュ化
      • secrets --- 機密を扱うために安全な乱数を生成する
        • 乱数
        • トークンの生成
          • トークンは何バイト使うべきか？
        • その他の関数
        • レシピとベストプラクティス
    • 汎用オペレーティングシステムサービス
      • os --- 雑多なオペレーティングシステムインタフェース
        • ファイル名、コマンドライン引数、および環境変数
        • プロセスのパラメーター
        • ファイルオブジェクトの生成
        • ファイル記述子の操作
          • ターミナルのサイズの問い合わせ
          • ファイル記述子の継承
        • ファイルとディレクトリ
          • Linux 拡張属性
        • プロセス管理
        • スケジューラーへのインターフェイス
        • 雑多なシステム情報
        • 乱数
      • io --- ストリームを扱うコアツール
        • 概要
          • テキスト I/O
          • バイナリ I/O
          • Raw I/O
        • 高水準のモジュールインターフェイス
          • インメモリー ストリーム
        • クラス階層
          • I/O 基底クラス
          • 生ファイルI/O
          • バッファ付きストリーム
          • テキスト I/O
        • 性能
          • バイナリ I/O
          • テキスト I/O
          • マルチスレッディング
          • リエントラント性
      • time --- 時刻データへのアクセスと変換
        • 関数
        • Clock ID Constants
        • Timezone Constants
      • argparse --- コマンドラインオプション、引数、サブコマンドのパーサー
        • 使用例
          • パーサーを作る
          • 引数を追加する
          • 引数を解析する
        • ArgumentParser オブジェクト
          • prog
          • usage
          • description
          • epilog
          • parents
          • formatter_class
          • prefix_chars
          • fromfile_prefix_chars
          • argument_default
          • allow_abbrev
          • conflict_handler
          • add_help
        • add_argument() メソッド
          • name または flags
          • action
          • nargs
          • const
          • default
          • type
          • choices
          • required
          • help
          • metavar
          • dest
          • Action クラス
        • parse_args() メソッド
          • オプション値の文法
          • 不正な引数
          • - を含む引数
          • 引数の短縮形 (先頭文字でのマッチング)
          • sys.argv 以外
          • Namespace オブジェクト
        • その他のユーティリティ
          • サブコマンド
          • FileType オブジェクト
          • 引数グループ
          • 相互排他
          • パーサーのデフォルト値
          • ヘルプの表示
          • 部分解析
          • ファイル解析のカスタマイズ
          • 終了メソッド
          • Intermixed parsing
        • optparse からのアップグレード
      • getopt --- C 言語スタイルのコマンドラインオプションパーサ
      • logging --- Python 用ロギング機能
        • ロガーオブジェクト
        • ロギングレベル
        • ハンドラオブジェクト
        • フォーマッタオブジェクト
        • フィルタオブジェクト
        • LogRecord オブジェクト
        • LogRecord 属性
        • LoggerAdapter オブジェクト
        • スレッドセーフ性
        • モジュールレベルの関数
        • モジュールレベル属性
        • warnings モジュールとの統合
      • logging.config --- ロギングの環境設定
        • 環境設定のための関数
        • 環境設定辞書スキーマ
          • 辞書スキーマの詳細
          • 増分設定
          • オブジェクトの接続
          • ユーザ定義オブジェクト
          • 外部オブジェクトへのアクセス
          • 内部オブジェクトへのアクセス
          • インポート解決とカスタムインポーター
        • 環境設定ファイルの書式
      • logging.handlers --- ロギングハンドラ
        • StreamHandler
        • FileHandler
        • NullHandler
        • WatchedFileHandler
        • BaseRotatingHandler
        • RotatingFileHandler
        • TimedRotatingFileHandler
        • SocketHandler
        • DatagramHandler
        • SysLogHandler
        • NTEventLogHandler
        • SMTPHandler
        • MemoryHandler
        • HTTPHandler
        • QueueHandler
        • QueueListener
      • getpass --- 可搬性のあるパスワード入力機構
      • curses --- 文字セル表示を扱うための端末操作
        • 関数
        • Window オブジェクト
        • 定数
      • curses.textpad --- curses プログラムのためのテキスト入力ウィジェット
        • Textbox オブジェクト
      • curses.ascii --- ASCII 文字に関するユーティリティ
      • curses.panel --- curses のためのパネルスタック拡張
        • 関数
        • Panel オブジェクト
      • platform --- 実行中プラットフォームの固有情報を参照する
        • クロスプラットフォーム
        • Java プラットフォーム
        • Windows プラットフォーム
          • Win95/98 固有
        • Mac OS プラットフォーム
        • Unix プラットフォーム
      • errno --- 標準の errno システムシンボル
      • ctypes --- Pythonのための外部関数ライブラリ
        • ctypesチュートリアル
          • 動的リンクライブラリをロードする
          • ロードしたdllから関数にアクセスする
          • 関数を呼び出す
          • 基本データ型
          • 続・関数を呼び出す
          • 自作のデータ型とともに関数を呼び出す
          • 要求される引数の型を指定する (関数プロトタイプ)
          • 戻り値の型
          • ポインタを渡す(または、パラメータの参照渡し)
          • 構造体と共用体
          • 構造体/共用体アライメントとバイトオーダー
          • 構造体と共用体におけるビットフィールド
          • 配列
          • ポインタ
          • 型変換
          • 不完全型
          • コールバック関数
          • dllからエクスポートされた値へアクセスする
          • びっくり仰天
          • 可変サイズのデータ型
        • ctypesリファレンス
          • 共有ライブラリを見つける
          • 共有ライブラリをロードする
          • 外部関数
          • 関数プロトタイプ
          • ユーティリティー関数
          • データ型
          • 基本データ型
          • 構造化データ型
          • 配列とポインタ
    • 並行実行
      • threading --- スレッドベースの並列処理
        • スレッドローカルデータ
        • Thread オブジェクト
        • Lock オブジェクト
        • RLock オブジェクト
        • Condition オブジェクト
        • Semaphore オブジェクト
          • Semaphore の例
        • Event オブジェクト
        • Timer オブジェクト
        • バリアオブジェクト
        • Using locks, conditions, and semaphores in the with statement
      • multiprocessing --- プロセスベースの並列処理
        • はじめに
          • Process クラス
          • コンテキストと開始方式
          • プロセス間でのオブジェクト交換
          • プロセス間の同期
          • プロセス間での状態の共有
          • ワーカープロセスのプールを使用
        • リファレンス
          • Process クラスと例外
          • パイプ (Pipe) とキュー (Queue)
          • その他
          • Connection オブジェクト
          • 同期プリミティブ
          • 共有 ctypes オブジェクト
            • multiprocessing.sharedctypes モジュール
          • マネージャー
            • カスタマイズされたマネージャー
            • リモートマネージャーを使用する
          • Proxy オブジェクト
            • クリーンアップ
          • プロセスプール
          • リスナーとクライアント
            • アドレスフォーマット
          • 認証キー
          • ログ記録
          • multiprocessing.dummy モジュール
        • プログラミングガイドライン
          • すべての開始方式について
          • 開始方式が spawn および forkserver の場合
        • 使用例
      • concurrent パッケージ
      • concurrent.futures -- 並列タスク実行
        • Executor オブジェクト
        • ThreadPoolExecutor
          • ThreadPoolExecutor の例
        • ProcessPoolExecutor
          • ProcessPoolExecutor の例
        • Future オブジェクト
        • モジュール関数
        • 例外クラス
      • subprocess --- サブプロセス管理
        • subprocess モジュールを使う
          • よく使われる引数
          • Popen コンストラクター
          • 例外
        • セキュリティで考慮すべき点
        • Popen オブジェクト
        • Windows Popen ヘルパー
          • Windows Constants
        • 古い高水準 API
        • 古い関数を subprocess モジュールで置き換える
          • /bin/sh シェルのバッククォートを置き換える
          • シェルのパイプラインを置き換える
          • os.system() を置き換える
          • os.spawn 関数群を置き換える
          • os.popen(), os.popen2(), os.popen3() を置き換える
          • popen2 モジュールの関数群を置き換える
        • レガシーなシェル呼び出し関数
        • 注釈
          • Windows における引数シーケンスから文字列への変換
      • sched --- イベントスケジューラ
        • スケジューラオブジェクト
      • queue --- 同期キュークラス
        • キューオブジェクト
        • SimpleQueue Objects
      • _thread --- 低水準の スレッド API
      • _dummy_thread --- _thread の代替モジュール
      • dummy_threading --- threading の代替モジュール
    • contextvars --- コンテキスト変数
      • コンテキスト変数
      • Manual Context Management
      • asyncio support
    • Networking and Interprocess Communication
      • asyncio --- Asynchronous I/O
        • コルーチンと Task
          • コルーチン
          • Awaitables
          • Running an asyncio Program
          • Creating Tasks
          • Sleeping
          • Running Tasks Concurrently
          • Shielding From Cancellation
          • Timeouts
          • Waiting Primitives
          • Scheduling From Other Threads
          • Introspection
          • Task Object
          • Generator-based Coroutines
        • Streams
          • StreamReader
          • StreamWriter
          • 使用例
            • ストリームを使った TCP Echo クライアント
            • ストリームを使った TCP Echo サーバー
            • HTTP ヘッダーの取得
            • ストリームを使ってデータを待つオープンソケットの登録
        • Synchronization Primitives
          • Lock
          • Event
          • Condition
          • Semaphore
          • BoundedSemaphore
        • Subprocesses
          • Creating Subprocesses
          • 定数
          • Interacting with Subprocesses
            • Subprocess and Threads
            • 使用例
        • キュー
          • Queue
          • Priority Queue
          • LIFO Queue
          • 例外
          • 使用例
        • 例外
        • Event Loop
          • Event Loop Methods
            • Running and stopping the loop
            • Scheduling callbacks
            • Scheduling delayed callbacks
            • Creating Futures and Tasks
            • Opening network connections
            • Creating network servers
            • Transferring files
            • TLS Upgrade
            • Watching file descriptors
            • Working with socket objects directly
            • DNS
            • Working with pipes
            • Unix signals
            • Executing code in thread or process pools
            • エラーハンドリング API
            • Enabling debug mode
            • Running Subprocesses
          • Callback Handles
          • Serverオブジェクト
          • Event Loop Implementations
          • 使用例
            • call_soon() を使った Hello World
            • call_later() で現在の日時を表示する
            • 読み込みイベント用ファイル記述子の監視
            • SIGINT および SIGTERM 用のシグナルハンドラーの設定
        • Future
          • Future Functions
          • Future Object
        • Transports and Protocols
          • トランスポート
            • Transports Hierarchy
            • Base Transport
            • Read-only Transports
            • Write-only Transports
            • Datagram Transports
            • Subprocess Transports
          • プロトコル
            • Base Protocols
            • Base Protocol
            • Streaming Protocols
            • Buffered Streaming Protocols
            • Datagram Protocols
            • Subprocess Protocols
          • 使用例
            • TCP Echo Server
            • TCP Echo Client
            • UDP Echo Server
            • UDP Echo Client
            • Connecting Existing Sockets
            • loop.subprocess_exec() and SubprocessProtocol
        • Policies
          • Getting and Setting the Policy
          • Policy Objects
          • Process Watchers
          • Custom Policies
        • Platform Support
          • All Platforms
          • Windows
            • Subprocess Support on Windows
          • macOS
        • 高水準の API インデックス
          • タスク
          • キュー
          • Subprocesses
          • Streams
          • Synchronization
          • 例外
        • Low-level API Index
          • Obtaining the Event Loop
          • Event Loop Methods
          • トランスポート
          • プロトコル
          • Event Loop Policies
        • Developing with asyncio
          • Debug Mode
          • Concurrency and Multithreading
          • Running Blocking Code
          • ログ記録
          • Detect never-awaited coroutines
          • Detect never-retrieved exceptions
      • socket --- 低水準ネットワークインターフェイス
        • ソケットファミリー
        • モジュールの内容
          • 例外
          • 定数
          • 関数
            • ソケットの作成
            • その他の関数
        • socket オブジェクト
        • ソケットタイムアウトの注意事項
          • タイムアウトと connect メソッド
          • タイムアウトと accept メソッド
        • 使用例
      • ssl --- ソケットオブジェクトに対する TLS/SSL ラッパー
        • 関数、定数、例外
          • ソケットの作成
          • コンテキストの作成
          • 例外
          • 乱数生成
          • 証明書の取り扱い
          • 定数
        • SSL ソケット
        • SSL コンテキスト
        • 証明書
          • 証明書チェイン
          • CA 証明書
          • 秘密鍵と証明書の組み合わせ
          • 自己署名証明書
        • 使用例
          • SSLサポートをテストする
          • クライアントサイドの処理
          • サーバサイドの処理
        • ノンブロッキングソケットについての注意事項
        • メモリ BIO サポート
        • SSL セッション
        • セキュリティで考慮すべき点
          • 最善のデフォルト値
          • 手動での設定
            • 証明書の検証
            • プロトコルのバージョン
            • 暗号の選択
          • マルチプロセス化
        • TLS 1.3
        • LibreSSL support
      • select --- I/O 処理の完了を待機する
        • /dev/poll ポーリングオブジェクト
        • エッジおよびレベルトリガポーリング (epoll) オブジェクト
        • ポーリングオブジェクト
        • kqueue オブジェクト
        • kevent オブジェクト
      • selectors --- 高水準の I/O 多重化
        • はじめに
        • クラス
        • 使用例
      • asyncore --- 非同期ソケットハンドラ
        • asyncoreの例: 簡単なHTTPクライアント
        • 基本的な echo サーバーの例
      • asynchat --- 非同期ソケットコマンド/レスポンスハンドラ
        • asynchat 使用例
      • signal --- 非同期イベントにハンドラを設定する
        • 一般的なルール
          • Python のシグナルハンドラの実行
          • シグナルとスレッド
        • モジュールの内容
        • 使用例
        • Note on SIGPIPE
      • mmap --- メモリマップファイル
    • インターネット上のデータの操作
      • email --- 電子メールと MIME 処理のためのパッケージ
        • email.message: 電子メールメッセージの表現
        • email.parser: 電子メールメッセージのパース
          • FeedParser API
          • Parser API
          • 追記事項
        • email.generator: MIME 文書の生成
        • email.policy: ポリシーオブジェクト
        • email.errors: 例外及び欠陥クラス
        • email.headerregistry: カスタムヘッダーオブジェクト
        • email.contentmanager: MIME 内容の管理
          • Content Manager Instances
        • email: 使用例
        • email.message.Message: Representing an email message using the compat32 API
        • email.mime: メールと MIME オブジェクトを一から作成
        • email.header: 国際化されたヘッダ
        • email.charset: 文字集合の表現
        • email.encoders: エンコーダ
        • email.utils: 多方面のユーティリティ
        • email.iterators: イテレータ
      • json --- JSON エンコーダおよびデコーダ
        • 基本的な使い方
        • エンコーダとデコーダ
        • 例外
        • 標準への準拠と互換性
          • 文字エンコーディング
          • 無限および NaN の数値
          • オブジェクト中に重複した名前の扱い
          • トップレベルの非オブジェクト、非配列の値の扱い
          • 実装の制限
        • コマンドラインインターフェイス
          • コマンドラインオプション
      • mailcap --- mailcap ファイルの操作
      • mailbox --- 様々な形式のメールボックス操作
        • Mailbox オブジェクト
          • Maildir
          • mbox
          • MH
          • Babyl
          • MMDF
        • Message objects
          • MaildirMessage
          • mboxMessage
          • MHMessage
          • BabylMessage
          • MMDFMessage
        • 例外
        • 使用例
      • mimetypes --- ファイル名を MIME 型へマップする
        • Mime 型オブジェクト
      • base64 --- Base16, Base32, Base64, Base85 データの符号化
      • binhex --- binhex4 形式ファイルのエンコードおよびデコード
        • 注釈
      • binascii --- バイナリデータと ASCII データとの間での変換
      • quopri --- MIME quoted-printable 形式データのエンコードおよびデコード
      • uu --- uuencode形式のエンコードとデコード
    • 構造化マークアップツール
      • html --- HyperText Markup Language のサポート
      • html.parser--- HTML および XHTML のシンプルなパーサー
        • HTML パーサーアプリケーションの例
        • HTMLParser メソッド
        • 使用例
      • html.entities --- HTML 一般実体の定義
      • XMLを扱うモジュール群
        • XML の脆弱性
        • defusedxml および defusedexpat パッケージ
      • xml.etree.ElementTree --- ElementTree XML API
        • チュートリアル
          • XML 木構造と要素
          • XML の解析
          • 非ブロックパースのためのプル API
          • 関心ある要素の検索
          • XML ファイルの編集
          • XML 文書の構築
          • 名前空間のある XML の解析
          • その他の情報
        • XPath サポート
          • 使用例
          • サポートされている XPath 構文
        • リファレンス
          • 関数
          • Element オブジェクト
          • ElementTree オブジェクト
          • QName オブジェクト
          • TreeBuilder オブジェクト
          • XMLParser オブジェクト
          • XMLPullParser オブジェクト
          • 例外
      • xml.dom --- 文書オブジェクトモデル (DOM) API
        • モジュールコンテンツ
        • DOM 内のオブジェクト
          • DOMImplementation オブジェクト
          • Node オブジェクト
          • NodeList オブジェクト
          • DocumentType オブジェクト
          • Document オブジェクト
          • Element オブジェクト
          • Attr オブジェクト
          • NamedNodeMap Objects
          • Comment オブジェクト
          • Text オブジェクトおよび CDATASection オブジェクト
          • ProcessingInstruction オブジェクト
          • 例外
        • 適合性
          • 型の対応付け
          • アクセサメソッド
      • xml.dom.minidom --- 最小限の DOM の実装
        • DOM オブジェクト
        • DOM の例
        • minidom と DOM 標準
      • xml.dom.pulldom --- 部分的な DOM ツリー構築のサポート
        • DOMEventStream オブジェクト
      • xml.sax --- SAX2 パーサのサポート
        • SAXException オブジェクト
      • xml.sax.handler --- SAX ハンドラの基底クラス
        • ContentHandler オブジェクト
        • DTDHandler オブジェクト
        • EntityResolver オブジェクト
        • ErrorHandler オブジェクト
      • xml.sax.saxutils --- SAX ユーティリティ
      • xml.sax.xmlreader --- XML パーサのインタフェース
        • XMLReader オブジェクト
        • IncrementalParser オブジェクト
        • Locator オブジェクト
        • InputSource オブジェクト
        • Attributes インタフェース
        • AttributesNS インタフェース
      • xml.parsers.expat --- Expat を使った高速な XML 解析
        • XMLParser オブジェクト
        • ExpatError 例外
        • 使用例
        • 内容モデルの記述
        • Expat エラー定数
    • インターネットプロトコルとサポート
      • webbrowser --- 便利なウェブブラウザコントローラー
        • ブラウザコントローラーオブジェクト
      • cgi --- CGI (ゲートウェイインタフェース規格) のサポート
        • はじめに
        • cgi モジュールを使う
        • 高水準インタフェース
        • 関数
        • セキュリティへの配慮
        • CGI スクリプトを Unix システムにインストールする
        • CGI スクリプトをテストする
        • CGI スクリプトをデバッグする
        • よくある問題と解決法
      • cgitb --- CGI スクリプトのトレースバック管理機構
      • wsgiref --- WSGI ユーティリティとリファレンス実装
        • wsgiref.util -- WSGI 環境のユーティリティ
        • wsgiref.headers -- WSGI レスポンスヘッダツール群
        • wsgiref.simple_server -- シンプルな WSGI HTTP サーバ
        • wsgiref.validate --- WSGI 準拠チェッカー
        • wsgiref.handlers -- サーバ／ゲートウェイのベースクラス
        • 使用例
      • urllib --- URL を扱うモジュール群
      • urllib.request --- URL を開くための拡張可能なライブラリ
        • 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 --- URL を解析して構成要素にする
        • URL の解析
        • ASCII エンコードバイト列の解析
        • 構造化された解析結果
        • URL のクオート
      • urllib.error --- urllib.request が投げる例外
      • urllib.robotparser --- robots.txt のためのパーザ
      • http --- HTTP モジュール群
        • HTTP ステータスコード
      • http.client --- HTTP プロトコルクライアント
        • HTTPConnection オブジェクト
        • HTTPResponse オブジェクト
        • 使用例
        • HTTPMessage オブジェクト
      • ftplib --- FTPプロトコルクライアント
        • FTP オブジェクト
        • FTP_TLS オブジェクト
      • poplib --- POP3 プロトコルクライアント
        • POP3 オブジェクト
        • POP3 の例
      • imaplib --- IMAP4 プロトコルクライアント
        • IMAP4 オブジェクト
        • IMAP4 の使用例
      • nntplib --- NNTP プロトコルクライアント
        • NNTP オブジェクト
          • 属性
          • メソッド
        • ユーティリティー関数
      • smtplib --- SMTP プロトコルクライアント
        • SMTP オブジェクト
        • SMTP 使用例
      • smtpd --- SMTP サーバー
        • SMTPServer オブジェクト
        • DebuggingServer オブジェクト
        • PureProxy オブジェクト
        • MailmanProxy Objects
        • SMTPChannel オブジェクト
      • telnetlib --- Telnet クライアント
        • Telnet オブジェクト
        • Telnet Example
      • uuid --- UUID objects according to RFC 4122
        • 使用例
      • socketserver --- ネットワークサーバのフレームワーク
        • サーバ生成に関するノート
        • Serverオブジェクト
        • Request Handler Objects
        • 使用例
          • socketserver.TCPServer の例
          • socketserver.UDPServer の例
          • 非同期処理の Mix-in
      • http.server --- HTTP サーバ
      • http.cookies --- HTTPの状態管理
        • Cookieオブジェクト
        • Morselオブジェクト
        • 使用例
      • http.cookiejar --- HTTP クライアント用の Cookie 処理
        • CookieJar および FileCookieJar オブジェクト
        • FileCookieJar のサブクラスと web ブラウザとの連携
        • CookiePolicy オブジェクト
        • DefaultCookiePolicy オブジェクト
        • Cookieオブジェクト
        • 使用例
      • xmlrpc --- XMLRPC サーバーとクライアントモジュール
      • xmlrpc.client --- XML-RPC クライアントアクセス
        • ServerProxy オブジェクト
        • DateTime オブジェクト
        • Binary オブジェクト
        • Fault オブジェクト
        • ProtocolError オブジェクト
        • MultiCall オブジェクト
        • 補助関数
        • クライアントのサンプル
        • クライアントとサーバーの利用例
      • xmlrpc.server --- 基本的なXML-RPCサーバー
        • SimpleXMLRPCServer オブジェクト
          • SimpleXMLRPCServer の例
        • CGIXMLRPCRequestHandler
        • XMLRPC サーバの文書化
        • DocXMLRPCServer オブジェクト
        • DocCGIXMLRPCRequestHandler
      • ipaddress --- IPv4/IPv6 操作ライブラリ
        • 便利なファクトリ関数
        • IP アドレス
          • Address オブジェクト
          • 文字列と整数への変換
          • 演算子
            • 比較演算子
            • 算術演算
        • IP ネットワーク定義
          • プリフィックス, ネットマスク、ホストマスク
          • Network オブジェクト
          • 演算子
            • 論理演算子
            • イテレーション
            • Networks as containers of addresses
        • インターフェイスオブジェクト
          • 演算子
            • 論理演算子
        • その他のモジュールレベル関数
        • Custom Exceptions
    • マルチメディアサービス
      • audioop --- 生の音声データを操作する
      • aifc --- AIFFおよびAIFCファイルの読み書き
      • sunau --- Sun AUファイルの読み書き
        • AU_read オブジェクト
        • AU_write オブジェクト
      • wave --- WAVファイルの読み書き
        • Wave_read オブジェクト
        • Wave_write オブジェクト
      • chunk --- IFFチャンクデータの読み込み
      • colorsys --- 色体系間の変換
      • imghdr --- 画像の形式を決定する
      • sndhdr --- サウンドファイルの識別
      • ossaudiodev --- OSS互換オーディオデバイスへのアクセス
        • オーディオデバイスオブジェクト
        • ミキサデバイスオブジェクト
    • 国際化
      • gettext --- 多言語対応に関する国際化サービス
        • GNU gettext API
        • クラス形式の API
          • NullTranslations クラス
          • GNUTranslations クラス
          • Solaris メッセージカタログ機構のサポート
          • Catalog コンストラクタ
        • プログラムやモジュールを国際化する
          • モジュールを地域化する
          • アプリケーションを地域化する
          • 動作中 (on the fly) に言語を切り替える
          • 翻訳処理の遅延解決
        • 謝辞
      • locale --- 国際化サービス
        • ロケールの背景、詳細、ヒント、助言および補足説明
        • Python 拡張の作者と、Python を埋め込むようなプログラムに関して
        • メッセージカタログへのアクセス
    • プログラムのフレームワーク
      • turtle --- タートルグラフィックス
        • はじめに
        • Turtle および Screen のメソッドの概観
          • Turtle のメソッド
          • TurtleScreen/Screen のメソッド
        • RawTurtle/Turtle のメソッドと対応する関数
          • Turtle の動き
          • Turtle の状態を知る
          • 設定と計測
          • Pen の制御
            • 描画状態
            • 色の制御
            • 塗りつぶし
            • さらなる描画の制御
          • タートルの状態
            • 可視性
            • 見た目
          • イベントを利用する
          • 特別な Turtle のメソッド
          • Compound shapes
        • TurtleScreen/Screen のメソッドと対応する関数
          • ウィンドウの制御
          • アニメーションの制御
          • スクリーンイベントを利用する
          • Input methods
          • 設定と特殊なメソッド
          • Screen 独自のメソッド、TurtleScreen から継承したもの以外
        • Public classes
        • ヘルプと設定
          • ヘルプの使い方
          • ドキュメント文字列の翻訳
          • Screen および Turtle の設定方法
        • turtledemo --- デモスクリプト
        • python 2.6からの変更点
        • python 3.0からの変更点
      • cmd --- 行指向のコマンドインタープリタのサポート
        • Cmdオブジェクト
        • Cmd の例
      • shlex --- 単純な字句解析
        • shlex オブジェクト
        • 解析規則
        • Improved Compatibility with Shells
    • Tk を用いたグラフィカルユーザインターフェイス
      • tkinter --- Tcl/Tk の Python インタフェース
        • Tkinter モジュール
        • Tkinter お助け手帳
          • この節の使い方
          • 簡単な Hello World プログラム
        • Tcl/Tk を (本当に少しだけ) 見渡してみる
        • 基本的な Tk プログラムと Tkinter との対応関係
        • Tk と Tkinter はどのように関わっているのか
        • 簡単なリファレンス
          • オプションの設定
          • Packer
          • Packer のオプション
          • ウィジェット変数を関連付ける
          • ウィンドウマネージャ
          • Tk オプションデータ型
          • バインドとイベント
          • index パラメータ
          • 画像
        • ファイルハンドラ
      • tkinter.ttk --- Tk のテーマ付きウィジェット
        • Ttk を使う
        • Ttk ウィジェット
        • ウィジェット
          • 標準オプション
          • スクロール可能ウィジェットのオプション
          • ラベルオプション
          • 互換性オプション
          • ウィジェットの状態
          • ttk.Widget
        • コンボボックス
          • オプション
          • 仮想イベント
          • ttk.Combobox
        • Spinbox
          • オプション
          • 仮想イベント
          • ttk.Spinbox
        • ノートブック
          • オプション
          • タブオプション
          • タブ識別子
          • 仮想イベント
          • ttk.Notebook
        • プログレスバー
          • オプション
          • ttk.Progressbar
        • セパレータ
          • オプション
        • サイズグリップ
          • プラットフォーム固有のメモ
          • バグ
        • ツリービュー
          • オプション
          • 要素オプション
          • タグオプション
          • カラム識別子
          • 仮想イベント
          • ttk.Treeview
        • Ttk スタイル
          • レイアウト
      • tkinter.tix --- Tkの拡張ウィジェット
        • Tixを使う
        • Tixウィジェット
          • 基本ウィジェット
          • ファイルセレクタ
          • 階層的リストボックス
          • 表的リストボックス
          • 管理ウィジェット
          • 画像タイプ
          • その他のウィジェット
          • ジオメトリマネジャを作る
        • Tixコマンド
      • tkinter.scrolledtext --- スクロールするテキストウィジェット
      • 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 ウィンドウ)
          • コンテキストメニュー
        • 編集とナビゲーション
          • Editor windows
          • Key bindings
          • 自動的な字下げ
          • 補完 (Completions)
          • 呼び出しヒント (Calltips)
          • Python Shell ウィンドウ
          • テキストの色
        • スタートアップとコードの実行
          • コマンドラインの使い方
          • Startup failure
          • Running user code
          • User output in Shell
          • Developing tkinter applications
          • サブプロセスを起こさずに起動する
        • ヘルプとお好み設定
          • Help sources
          • Setting preferences [お好み設定]
          • IDLE on macOS
          • Extensions [拡張]
      • 他のグラフィカルユーザインタフェースパッケージ
    • 開発ツール
      • typing --- 型ヒントのサポート
        • 型エイリアス
        • NewType
        • 呼び出し可能オブジェクト
        • ジェネリクス
        • ユーザー定義のジェネリック型
        • Any 型
        • クラス、関数、およびデコレータ
      • pydoc --- ドキュメント生成とオンラインヘルプシステム
      • doctest --- 対話的な実行例をテストする
        • 簡単な利用法: docstring 中の実行例をチェックする
        • 簡単な利用法: テキストファイル中の実行例をチェックする
        • doctest のからくり
          • どの docstring が検証されるのか?
          • docstring 内の実行例をどのように認識するのか?
          • 実行コンテキストとは何か?
          • 例外はどう扱えばよいか?
          • オプションフラグ
          • ディレクティブ (Directives)
          • 警告
        • 基本 API
        • 単体テスト API
        • 拡張 API
          • DocTest オブジェクト
          • Example オブジェクト
          • DocTestFinder オブジェクト
          • DocTestParser オブジェクト
          • DocTestRunner オブジェクト
          • OutputChecker オブジェクト
        • デバッグ
        • アドバイス
      • unittest --- ユニットテストフレームワーク
        • 基本的な例
        • コマンドラインインターフェイス
          • コマンドラインオプション
        • テストディスカバリ
        • テストコードの構成
        • 既存テストコードの再利用
        • テストのスキップと予期された失敗
        • サブテストを利用して繰り返しテストの区別を付ける
        • クラスと関数
          • テストクラス
            • 非推奨のエイリアス
          • テストのグループ化
          • テストのロードと起動
            • load_tests プロトコル
        • クラスとモジュールのフィクスチャ
          • setUpClass と tearDownClass
          • setUpModule と tearDownModule
        • シグナルハンドリング
      • unittest.mock --- モックオブジェクトライブラリ
        • クイックガイド
        • Mock クラス
          • 呼び出し
          • 属性の削除
          • Mock の名前と name 属性
          • 属性として設定されるモック
        • patcher
          • patch
          • patch.object
          • patch.dict
          • patch.multiple
          • patch のメソッド: start と stop
          • ビルトインをパッチする
          • TEST_PREFIX
          • patch デコレータをネストする
          • どこにパッチするか
          • デスクリプタやプロキシオブジェクトにパッチする
        • MagicMock と magic method のサポート
          • magick method をモックする
          • Magic Mock
        • ヘルパー
          • sentinel
          • DEFAULT
          • call
          • create_autospec
          • ANY
          • FILTER_DIR
          • mock_open
          • autospec を使う
          • Sealing mocks
      • unittest.mock --- 入門
        • Mock を使う
          • Mock のパッチ用メソッド
          • オブジェクトのメソッド呼び出しに対するモック
          • クラスをモックする
          • モックに名前をつける
          • 全ての呼び出しのトラッキング
          • 戻り値や属性を設定する
          • モックから例外を発生させる
          • side_effect の関数と iterable
          • 既存のオブジェクトから Mock を作る
        • patch デコレータ
        • さらなる例
          • chained call をモックする
          • 部分的なモック
          • ジェネレータ method をモックする
          • 同じパッチを全てのメソッドに適用する
          • Mocking Unbound Methods
          • モックで複数回の呼び出しをチェックする
          • ミュータブルな引数に対処する
          • 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 --- Python 用回帰テストパッケージ
        • test パッケージのためのユニットテストを書く
        • コマンドラインインタフェースを利用してテストを実行する
      • test.support --- テストのためのユーティリティ関数
      • test.support.script_helper --- Utilities for the Python execution tests
    • デバッグとプロファイル
      • bdb --- デバッガーフレームワーク
      • faulthandler --- Python tracebackのダンプ
        • tracebackのダンプ
        • フォールトハンドラの状態
        • タイムアウト後にtracebackをダンプする
        • ユーザシグナルに対してtracebackをダンプする
        • ファイル記述子の問題
        • 使用例
      • pdb --- Python デバッガ
        • デバッガコマンド
      • Python プロファイラ
        • プロファイラとは
        • かんたんユーザマニュアル
        • リファレンスマニュアル -- profile と cProfile
        • Stats クラス
        • 決定論的プロファイリングとは
        • 制限事項
        • キャリブレーション (補正)
        • カスタムな時刻取得用関数を使う
      • timeit --- 小さなコード断片の実行時間計測
        • 基本的な例
        • Python インターフェイス
        • コマンドラインインターフェイス
        • 使用例
      • trace --- Python 文実行のトレースと追跡
        • コマンドラインからの使用
          • 主要なオプション
          • 修飾的オプション
          • フィルターオプション
        • プログラミングインターフェース
      • tracemalloc --- メモリ割り当ての追跡
        • 使用例
          • 上位10を表示する
          • 差を計算する
          • メモリブロックのトレースバックを取得する
          • top を整形化する
        • API
          • 関数
          • DomainFilter
          • Filter
          • Frame
          • Snapshot
          • Statistic
          • StatisticDiff
          • Trace
          • Traceback
    • ソフトウェア・パッケージと配布
      • distutils --- Python モジュールの構築とインストール
      • ensurepip --- pip インストーラのブートストラップ
        • コマンドラインインターフェイス
        • モジュール API
      • venv --- 仮想環境の作成
        • 仮想環境の作成
        • API
        • EnvBuilder を拡張する例
      • zipapp --- Manage executable Python zip archives
        • 基本的な例
        • コマンドラインインターフェイス
        • Python API
        • 使用例
        • インタープリタの指定
        • Creating Standalone Applications with zipapp
          • Making a Windows executable
          • Caveats
        • The Python Zip Application Archive Format
    • Python ランタイムサービス
      • sys --- システムパラメータと関数
      • sysconfig --- Python の構成情報にアクセスする
        • 構成変数
        • インストールパス
        • その他の関数
        • sysconfig をスクリプトとして使う
      • builtins --- 組み込みオブジェクト
      • __main__ --- トップレベルのスクリプト環境
      • warnings --- 警告の制御
        • 警告カテゴリ
        • 警告フィルタ
          • Describing Warning Filters
          • Default Warning Filter
          • Overriding the default filter
        • 一時的に警告を抑制する
        • 警告のテスト
        • Updating Code For New Versions of Dependencies
        • 利用可能な関数
        • 利用可能なコンテキストマネージャー
      • dataclasses --- データクラス
        • モジュールレベルのデコレータ、クラス、関数
        • 初期化後の処理
        • クラス変数
        • 初期化限定変数
        • 凍結されたインスタンス
        • 継承
        • デフォルトファクトリ関数
        • 可変なデフォルト値
        • 例外
      • contextlib --- Utilities for with-statement contexts
        • ユーティリティ
        • 例とレシピ
          • 可変数個のコンテキストマネージャーをサポートする
          • __enter__ メソッドからの例外をキャッチする
          • __enter__ 実装内のクリーンアップ
          • try-finally + flag 変数パターンを置き換える
          • コンテキストマネージャーを関数デコレーターとして使う
        • Single use, reusable and reentrant context managers
          • Reentrant context managers
          • Reusable context managers
      • abc --- 抽象基底クラス
      • atexit --- 終了ハンドラ
        • atexit の例
      • traceback --- スタックトレースの表示または取得
        • TracebackException オブジェクト
        • StackSummary オブジェクト
        • FrameSummary オブジェクト
        • トレースバックの例
      • __future__ --- future 文の定義
      • gc --- ガベージコレクタインターフェース
      • inspect --- 活動中のオブジェクトの情報を取得する
        • 型とメンバー
        • ソースコードの情報取得
        • Signature オブジェクトで呼び出し可能オブジェクトを内省する
        • クラスと関数
        • インタープリタスタック
        • 属性の静的なフェッチ
        • ジェネレータおよびコルーチンの現在の状態
        • Code Objects Bit Flags
        • コマンドラインインターフェイス
      • site --- サイト固有の設定フック
        • readline の設定
        • モジュールの内容
    • カスタム Python インタプリタ
      • code --- インタプリタ基底クラス
        • 対話的なインタプリタオブジェクト
        • 対話的なコンソールオブジェクト
      • codeop --- Pythonコードをコンパイルする
    • モジュールのインポート
      • zipimport --- Zip アーカイブからモジュールを import する
        • zipimporter オブジェクト
        • 使用例
      • pkgutil --- パッケージ拡張ユーティリティ
      • modulefinder --- スクリプト中で使われているモジュールを検索する
        • ModuleFinder の使用例
      • runpy --- Python モジュールの位置特定と実行
      • importlib --- The implementation of import
        • はじめに
        • 関数
        • importlib.abc -- インポートに関連する抽象基底クラス
        • importlib.resources -- Resources
        • importlib.machinery -- インポータおよびパスフック
        • importlib.util -- インポータのためのユーティリティコード
        • 使用例
          • プログラムからのインポート
          • モジュールがインポートできるか確認する
          • ソースファイルから直接インポートする
          • インポーターのセットアップ
          • Approximating importlib.import_module()
    • Python言語サービス
      • parser --- Python 解析木にアクセスする
        • ST オブジェクトを作成する
        • ST オブジェクトを変換する
        • ST オブジェクトに対する問い合わせ
        • 例外とエラー処理
        • ST オブジェクト
        • 例: compile() のエミュレーション
      • ast --- 抽象構文木
        • Node クラス
        • 抽象文法 (Abstract Grammar)
        • ast ヘルパー
      • symtable --- コンパイラの記号表へのアクセス
        • 記号表の生成
        • 記号表の検査
      • symbol --- Python 解析木と共に使われる定数
      • token --- Python 解析木と共に使われる定数
      • keyword --- Python キーワードチェック
      • tokenize --- Pythonソースのためのトークナイザ
        • 入力のトークナイズ
        • コマンドラインからの使用
        • 使用例
      • tabnanny --- あいまいなインデントの検出
      • pyclbr --- Python クラスブラウザサポート
        • Function オブジェクト
        • クラスオブジェクト
      • py_compile --- Python ソースファイルのコンパイル
      • compileall --- Python ライブラリをバイトコンパイル
        • コマンドラインでの使用
        • パブリックな関数
      • dis --- Python バイトコードの逆アセンブラ
        • バイトコード解析
        • 解析関数
        • Python バイトコード命令
        • 命令コードコレクション
      • pickletools --- pickle 開発者のためのツール群
        • コマンドラインの使い方
          • コマンドラインオプション
        • プログラミングインターフェース
    • 各種サービス
      • formatter --- 汎用の出力書式化機構
        • formatter インタフェース
        • formatter 実装
        • writer インタフェース
        • writer 実装
    • MS Windows 固有のサービス
      • msilib --- Microsoft インストーラーファイルの読み書き
        • データベースオブジェクト
        • ビューオブジェクト
        • サマリー情報オブジェクト
        • レコードオブジェクト
        • エラー
        • CAB オブジェクト
        • ディレクトリオブジェクト
        • フィーチャー
        • GUI クラス
        • 事前に計算されたテーブル
      • msvcrt --- MS VC++実行時システムの有用なルーチン群
        • ファイル操作関連
        • コンソール I/O 関連
        • その多の関数
      • winreg --- Windows レジストリへのアクセス
        • 関数
        • 定数
          • HKEY_* 定数
          • アクセス権限
            • 64-bit 特有のアクセス権
          • 値の型
        • レジストリハンドルオブジェクト
      • winsound --- Windows 用の音声再生インタフェース
    • Unix 固有のサービス
      • posix --- 最も一般的な POSIX システムコール群
        • ラージファイルのサポート
        • 注目すべきモジュールの内容
      • pwd --- パスワードデータベースへのアクセスを提供する
      • spwd --- シャドウパスワードデータベース
      • grp --- グループデータベースへのアクセス
      • crypt --- Unix パスワードをチェックするための関数
        • ハッシュ化方式
        • モジュール属性
        • モジュール関数
        • 使用例
      • termios --- POSIX スタイルの端末制御
        • 使用例
      • tty --- 端末制御のための関数群
      • pty --- 擬似端末ユーティリティ
        • 使用例
      • fcntl --- fcntl および ioctl システムコール
      • pipes --- シェルパイプラインへのインタフェース
        • テンプレートオブジェクト
      • resource --- リソース使用状態の情報
        • リソースの制限
        • リソースの使用状態
      • nis --- Sun の NIS (Yellow Pages) へのインタフェース
      • syslog --- Unix syslog ライブラリルーチン群
        • 使用例
          • シンプルな例
    • 取って代わられたモジュール群
      • optparse --- コマンドラインオプション解析器
        • 背景
          • 用語集
          • オプションとは何か
          • 位置引数とは何か
        • チュートリアル
          • オプション・アクションを理解する
          • store アクション
          • ブール値 (フラグ) オプションの処理
          • その他のアクション
          • デフォルト値
          • ヘルプの生成
            • オプションをグループ化する
          • バージョン番号の出力
          • optparse のエラー処理法
          • 全てをつなぎ合わせる
        • リファレンスガイド
          • parserを作る
          • パーザへのオプション追加
          • オプションの定義
          • オプション属性
          • 標準的なオプション・アクション
          • 標準のオプション型
          • 引数を解析する
          • オプション解析器への問い合わせと操作
          • オプション間の衝突
          • クリーンアップ
          • その他のメソッド
        • オプション処理コールバック
          • callbackオプションの定義
          • コールバック関数はどのように呼び出されるか
          • コールバック中で例外を送出する
          • コールバックの例 1: ありふれたコールバック
          • コールバックの例 2: オプションの順番をチェックする
          • コールバックの例 3: オプションの順番をチェックする (汎用的)
          • コールバックの例 4: 任意の条件をチェックする
          • コールバックの例5: 固定引数
          • コールバックの例6: 可変個の引数
        • optparse の拡張
          • 新しい型の追加
          • 新しいアクションの追加
      • imp --- import 内部へのアクセス
        • 使用例
    • ドキュメント化されていないモジュール
      • プラットフォーム固有のモジュール
  • 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. distutils による C および C++ 拡張モジュールのビルド
        • 4.2. 拡張モジュールの配布
      • 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)
    • 安定 ABI (Stable Appliction Binary Interface)
    • 超高水準レイヤ
    • 参照カウント
    • 例外処理
      • 出力とクリア
      • 例外の送出
      • 警告
      • エラーインジケータの問い合わせ
      • シグナルハンドリング
      • 例外クラス
      • 例外オブジェクト
      • Unicode 例外オブジェクト
      • 再帰の管理
      • 標準例外
      • Standard Warning Categories
    • ユーティリティ
      • オペレーティングシステム関連のユーティリティ
      • システム関数
      • プロセス制御
      • モジュールのインポート
      • データ整列化 (data marshalling) のサポート
      • 引数の解釈と値の構築
        • 引数を解析する
          • 文字列とバッファ
          • 数
          • その他のオブジェクト
          • API 関数
        • 値の構築
      • 文字列の変換と書式化
      • リフレクション
      • codec レジストリとサポート関数
        • コーデック検索API
        • Unicode エラーハンドラ用レジストリ API
    • 抽象オブジェクトレイヤ (abstract objects layer)
      • オブジェクトプロトコル (object protocol)
      • 数値型プロトコル (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)
        • 型オブジェクト
        • None オブジェクト
      • 数値型オブジェクト (numeric object)
        • 整数型オブジェクト (integer object)
        • Boolean オブジェクト
        • 浮動小数点型オブジェクト (floating point object)
        • 複素数オブジェクト (complex number object)
          • C 構造体としての複素数
          • Python オブジェクトとしての複素数型
      • シーケンスオブジェクト (sequence object)
        • バイトオブジェクト
        • bytearray オブジェクト
          • 型チェックマクロ
          • ダイレクト API 関数
          • マクロ
        • Unicode オブジェクトと codec
          • Unicode オブジェクト
            • Unicode 型
            • Unicode 文字プロパティ
            • Unicode 文字列の生成とアクセス
            • 廃止予定の Py_UNICODE API群
            • ロケールエンコーディング
            • ファイルシステムエンコーディング
            • 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)
        • コードオブジェクト
      • その他のオブジェクト
        • ファイルオブジェクト
        • モジュールオブジェクト (module object)
          • Cモジュールの初期化
            • 一段階初期化
            • 多段階初期化
            • 低水準モジュール作成関数
            • サポート関数
          • モジュール検索
        • イテレータオブジェクト (iterator object)
        • デスクリプタオブジェクト (descriptor object)
        • スライスオブジェクト (slice object)
        • Ellipsis オブジェクト
        • memoryview オブジェクト
        • 弱参照オブジェクト
        • カプセル
        • ジェネレータオブジェクト
        • コルーチンオブジェクト
        • コンテキスト変数オブジェクト
        • DateTime オブジェクト
    • 初期化 (initialization)、終了処理 (finalization)、スレッド
      • Python 初期化以前
      • グローバルな設定変数
      • インタプリタの初期化と終了処理
      • プロセスワイドのパラメータ
      • スレッド状態 (thread state) とグローバルインタプリタロック (global interpreter lock)
        • 拡張コード内で GIL を解放する
        • Python 以外で作られたスレッド
        • 高レベルAPI
        • 低レベルAPI
      • サブインタプリタサポート
        • バグと注意事項
      • 非同期通知
      • プロファイルとトレース (profiling and tracing)
      • 高度なデバッガサポート (advanced debugger support)
      • スレッドローカルストレージのサポート
        • スレッド固有ストレージ (Thread Specific Storage, TSS) API
          • 動的メモリ確保
          • メソッド
        • スレッドローカルストレージ (TLS) API
    • メモリ管理
      • 概要
      • 生メモリインタフェース
      • メモリインタフェース
      • Object allocators
      • Default Memory Allocators
      • メモリアロケータをカスタマイズする
      • pymalloc アロケータ
        • pymalloc アリーナアロケータのカスタマイズ
      • tracemalloc C API
      • 使用例
    • オブジェクト実装サポート (object implementation support)
      • オブジェクトをヒープ上にメモリ確保する
      • 共通のオブジェクト構造体 (common object structure)
      • 型オブジェクト
      • 数値オブジェクト構造体
      • マップオブジェクト構造体
      • シーケンスオブジェクト構造体
      • バッファオブジェクト構造体 (buffer object structure)
      • async オブジェクト構造体
      • 循環参照ガベージコレクションをサポートする
    • API と ABI のバージョニング
  • Python モジュールの配布
    • 重要用語集
    • オープンソースライセンス化とコラボレーション
    • ツールのインストール
    • ガイドを読む
    • どうすればいいの...？
      • ... 私のプロジェクトの名前はどう選べばいいですか?
      • ... バイナリの拡張を作って配布したいのですが?
  • Python モジュールのインストール
    • 重要用語集
    • 基本的な使い方
    • どうすればいいの...？
      • ... pip を 3.4 より前のバージョンの Python でインストールするには？
      • ... パッケージを現在のユーザ用のみにインストールするには？
      • ... 科学技術計算用の Python パッケージをインストールするには？
      • ... インストールされた複数のバージョンの Python を並行して使うには？
    • よくあるインストールに関する問題
      • Linux で、システムの Python 内にインストールする
      • pip がインストールされていない
      • バイナリの拡張のインストール
  • Python HOWTO
    • Python 2 から Python 3 への移植
      • 短い説明
      • 詳細
        • Python 2.6 とそれ以前のサポートを落とす
        • あなたの setup.py ファイルに、相応しいサポートバージョンを明記することを忘れないこと
        • 良いテストカバレッジを確保する。
        • Python 2 と 3 の違いを学びましょう。
        • コードをアップデートする。
          • 除算
          • テキスト対バイナリデータ
          • バージョン検出ではなく機能検出を使う
        • 互換性オプション
        • どの依存性があなたの移行を阻んでいるのかチェックする
        • あなたの setup.py ファイルを更新して Python 3 互換を謳う
        • 継続的インテグレーションを使って互換性を維持し続ける。
        • Consider using optional static type checking
    • Python 3 への拡張モジュール移植
      • 条件コンパイル
      • オブジェクト API の変更
        • str/unicode の統合
        • long/int の統合
      • モジュールの初期化と状態情報
      • CObject の Capsule への変更
      • その他のオプション
    • Python で Curses プログラミング
      • curses ってなに?
        • Python の curses module
      • curses アプリケーションの起動と終了
      • ウィンドウとパッド
      • テキストの表示
        • 属性とカラー
      • ユーザ入力
      • より多くの情報
    • デスクリプタ HowTo ガイド
      • 概要
      • 定義と導入
      • デスクリプタプロトコル
      • デスクリプタの呼び出し
      • デスクリプタの例
      • プロパティ
      • 関数とメソッド
      • 静的メソッドとクラスメソッド
    • 関数型プログラミング 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 を使ったコンテキスト情報の伝達
      • 複数のプロセスからの単一ファイルへのログ記録
      • ファイルをローテートする
      • 別の format スタイルを利用する
      • LogRecord のカスタマイズ
      • QueueHandler を継承する - ZeroMQ を使う例
      • QueueListener のサブクラスを作る - ZeroMQ を使う例
      • 辞書ベースで構成する例
      • rotator と namer を使ってログローテートをカスタマイズする
      • より手の込んだ multiprocessing の例
      • SysLogHandler に送るメッセージに BOM を挿入する
      • 構造化ログを実装する
      • handler を dictConfig() を使ってカスタマイズする
      • 固有の書式化スタイルをアプリケーション全体で使う
        • LogRecord ファクトリを使う
        • カスタムなメッセージオブジェクトを使う
      • filter を dictConfig() を使ってカスタマイズする
      • 例外の書式化をカスタマイズする
      • ロギングメッセージを喋る
      • ロギングメッセージをバッファリングし、条件に従って出力する
      • 設定によって時刻を UTC(GMT) で書式化する
      • ロギングの選択にコンテキストマネージャを使う
    • 正規表現 HOWTO
      • はじめに
      • 単純なパターン
        • 文字のマッチング
        • 繰り返し
      • 正規表現を使う
        • 正規表現をコンパイルする
        • バックスラッシュ感染症
        • マッチの実行
        • モジュールレベルの関数
        • コンパイルフラグ
      • パターンの能力をさらに
        • さらなる特殊文字
        • グルーピング
        • 取り出さないグループと名前つきグループ
        • 先読みアサーション (Lookahead Assertions)
      • 文字列を変更する
        • 文字列の分割
        • 検索と置換
      • よくある問題
        • 文字列メソッドを利用する
        • match() 対 search()
        • 貪欲 (greedy) 対非貪欲 (non-greedy)
        • re.VERBOSE の利用
      • フィードバック
    • ソケットプログラミング HOWTO
      • ソケット
        • 歴史
      • ソケットの作成
        • IPC
      • ソケットの利用
        • バイナリデータ
      • 切断
        • ソケットが死ぬと
      • ノンブロッキングソケット
    • ソート HOW TO
      • ソートの基本
      • Key 関数
      • operator モジュール関数
      • 昇順と降順
      • ソートの安定性と複合的なソート
      • デコレート-ソート-アンデコレートを利用した古いやり方
      • cmp パラメータを利用した古い方法
      • 残りいくつかとまとめ
    • Unicode HOWTO
      • Unicode 入門
        • 文字コードの歴史
        • 定義
        • エンコーディング
        • 参考資料
      • Python の Unicode サポート
        • 文字列型
        • バイト列への変換
        • Python ソースコード内の Unicode リテラル
        • Unicode プロパティ
        • Unicode 正規表現
        • 参考資料
      • Unicode データを読み書きする
        • Unicode ファイル名
        • Unicode 対応のプログラムを書くための Tips
          • ファイルエンコーディングの変換
          • 不明なエンコーディングのファイル
        • 参考資料
      • 謝辞
    • urllib パッケージを使ってインターネット上のリソースを取得するには
      • はじめに
      • URL を取得する
        • データ
        • ヘッダ
      • 例外を処理する
        • URLError
        • HTTPError
          • エラーコード
        • エラーをラップする
          • その1
          • その2
      • info と geturl
      • Openers と Handlers
      • Basic 認証
      • プロキシ
      • ソケットとレイヤー
      • 脚注
    • Argparse チュートリアル
      • コンセプト
      • 基礎
      • 位置引数の入門
      • Optional引数の導入
        • 短いオプション
      • 位置引数とOptional引数の併用
      • もうちょっとだけ学ぶ
        • 競合するオプション
      • 結び
    • ipaddressモジュールの紹介
      • アドレス/ネットワーク/インターフェースオブジェクトの作成
        • IPバージョンについての注意
        • IPホストアドレス
        • ネットワークを定義する
        • ホストインタフェース
      • アドレス/ネットワーク/インタフェースオブジェクト
      • アドレスのリストとしてのネットワーク
      • 比較
      • 他のモジュールでIPアドレスを使用する
      • インスタンスの生成に失敗した場合にさらに詳細を取得する
    • Argument Clinic How-To
      • Argument Clinic の目的
      • 基本的な概念と使用法
      • 関数を変換してみよう
      • 高度なトピック
        • シンボルのデフォルト値
        • Argument Clinic が生成した関数と変数をリネームする
        • PyArg_UnpackTuple による関数の変換
        • オプション群
        • Using real Argument Clinic converters, instead of "legacy converters"
        • Py_buffer
        • Advanced converters
        • 引数のデフォルト値
        • NULL デフォルト値
        • デフォルト値として指定された式
        • Using a return converter
        • 既存関数の複製
        • Python コードの呼び出し
        • "self converter" の利用
        • カスタムコンバータを書く
        • カスタム return コンバータを書く
        • METH_O と METH_NOARGS
        • tp_new と tp_init functions
        • Clinic 出力の変更とリダイレクト
        • #ifdef トリック
        • Python ファイル内での Argument Clinic の利用
    • DTrace と SystemTap で CPython を測定する
      • 静的マーカーの有効化
      • 静的 DTrace プローブ
      • 静的 SystemTap マーカー
      • 利用可能な静的マーカー
      • SystemTap Tapset
      • 使用例
  • Python よくある質問
    • 一般 Python FAQ
      • 一般情報
      • 現実世界での Python
    • プログラミング FAQ
      • 一般的な質問
      • コア言語
      • 数と文字列
      • 性能
      • シーケンス(タプル/リスト)
      • 辞書型 (dictionary)
      • オブジェクト
      • モジュール (module)
    • デザインと歴史 FAQ
      • Python はなぜ文のグループ化にインデントを使うのですか？
      • なぜ単純な算術演算が奇妙な結果になるのですか？
      • なんで浮動小数点数の計算はこんなに不正確なんですか？
      • なぜ Python の文字列はイミュータブルなのですか？
      • なぜメソッドの定義や呼び出しにおいて 'self' を明示しなければならないのですか？
      • 式中で代入ができないのはなぜですか？
      • Python にメソッドを使う機能 (list.index() 等) と関数を使う機能 (len(list) 等) があるのはなぜですか？
      • join() がリストやタプルのメソッドではなく文字列のメソッドなのはなぜですか？
      • 例外はどれくらい速いのですか？
      • Python に switch や case 文がないのはなぜですか？
      • OS 特有のスレッド実装に依らずにインタプリタでスレッドをエミュレートすることはできないのですか？
      • なぜラムダ式は文を含むことができないのですか?
      • Python は C やその他の言語のように機械語にコンパイルできますか？
      • Python はメモリをどのように管理するのですか？
      • CPython はなぜ伝統的なガベージコレクションスキームを使わないのですか？
      • なぜ CPython の終了時にすべてのメモリが解放されるわけではないのですか？
      • なぜタプルとリストという別のデータ型が用意されているのですか？
      • How are lists implemented in CPython?
      • How are dictionaries implemented in CPython?
      • なぜ辞書のキーはイミュータブルでなくてはならないのですか？
      • なぜ list.sort() はソートされたリストを返さないのですか？
      • Python ではどのようにインタフェース仕様を特定し適用するのですか？
      • なぜ goto が無いのですか？
      • なぜ raw 文字列 (r-strings) はバックスラッシュで終わってはいけないのですか？
      • 属性の代入に "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 ソースにタブを勝手に挿入しないようにするにはどうしますか？
      • ブロックすることなく押鍵を検出するにはどうしますか？
    • グラフィックユーザインタフェース FAQ
      • 一般的な GUI の質問
      • Python のプラットフォーム非依存の 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.7.2
      • 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
    • 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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • Python »
  • 3.7.2 Documentation »
© 著作権 2001-2019, Python Software Foundation.
Python Software Foundation は非営利団体です。 寄付
最終更新: 02/21/2019 バグを見つけたら?
このドキュメントは Sphinx 1.8.4 を使って作成されました。


  • モジュール |
  • Python »
  • 3.7.2 Documentation »

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 the top-level script is run.
 | _dummy_thread | Drop-in replacement for the _thread module.
 | _thread | Low-level threading API.
 | 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.
 | asynchat | Support for asynchronous command/response protocols.
 | asyncio | Asynchronous I/O.
 | asyncore | A base class for developing asynchronous socket handling services.
 | atexit | Register and execute cleanup functions.
 | audioop | Manipulate raw audio data.
 | b |
 | base64 | RFC 3548: Base16, Base32, Base64 Data Encodings; Base85 and Ascii85
 | bdb | Debugger framework.
 | binascii | Tools for converting between binary and various ASCII-encoded binary representations.
 | binhex | Encode and decode files in binhex4 format.
 | 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's reinterpretation of dbm.
 | dbm.ndbm (Unix) | The standard "database" interface, based on ndbm.
 | decimal | Implementation of the General Decimal Arithmetic Specification.
 | difflib | Helpers for computing differences between objects.
 | dis | Disassembler for Python bytecode.
- | distutils | Support for building and installing Python modules into an existing Python installation.
 | distutils.archive_util | Utility functions for creating archive files (tarballs, zip files, ...)
 | distutils.bcppcompiler |
 | distutils.ccompiler | Abstract CCompiler class
 | distutils.cmd | This module provides the abstract base class Command. This class is subclassed by the modules in the distutils.command subpackage.
 | distutils.command | This subpackage contains one module for each standard Distutils command.
 | distutils.command.bdist | Build a binary installer for a package
 | distutils.command.bdist_dumb | Build a "dumb" installer - a simple archive of files
 | distutils.command.bdist_msi | Build a binary distribution as a Windows MSI file
 | distutils.command.bdist_packager | Abstract base class for packagers
 | distutils.command.bdist_rpm | Build a binary distribution as a Redhat RPM and SRPM
 | distutils.command.bdist_wininst | Build a Windows installer
 | distutils.command.build | Build all files of a package
 | distutils.command.build_clib | Build any C libraries in a package
 | distutils.command.build_ext | Build any extensions in a package
 | distutils.command.build_py | Build the .py/.pyc files of a package
 | distutils.command.build_scripts | Build the scripts of a package
 | distutils.command.check | Check the metadata of a package
 | distutils.command.clean | Clean a package build area
 | distutils.command.config | Perform package configuration
 | distutils.command.install | Install a package
 | distutils.command.install_data | Install data files from a package
 | distutils.command.install_headers | Install C/C++ header files from a package
 | distutils.command.install_lib | Install library files from a package
 | distutils.command.install_scripts | Install script files from a package
 | distutils.command.register | Register a module with the Python Package Index
 | distutils.command.sdist | Build a source distribution
 | distutils.core | The core Distutils functionality
 | distutils.cygwinccompiler |
 | distutils.debug | Provides the debug flag for distutils
 | distutils.dep_util | Utility functions for simple dependency checking
 | distutils.dir_util | Utility functions for operating on directories and directory trees
 | distutils.dist | Provides the Distribution class, which represents the module distribution being built/installed/distributed
 | distutils.errors | Provides standard distutils exceptions
 | distutils.extension | Provides the Extension class, used to describe C/C++ extension modules in setup scripts
 | distutils.fancy_getopt | Additional getopt functionality
 | distutils.file_util | Utility functions for operating on single files
 | distutils.filelist | The FileList class, used for poking about the file system and building lists of files.
 | distutils.log | A simple logging mechanism, 282-style
 | distutils.msvccompiler | Microsoft Compiler
 | distutils.spawn | Provides the spawn() function
 | distutils.sysconfig | Low-level access to configuration information of the Python interpreter.
 | distutils.text_file | provides the TextFile class, a simple interface to text files
 | distutils.unixccompiler | UNIX C Compiler
 | distutils.util | Miscellaneous other utility functions
 | distutils.version | implements classes that represent module version numbers.
 | doctest | Test pieces of code within docstrings.
 | dummy_threading | Drop-in replacement for the threading module.
 | 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.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.
 | formatter | 非推奨: Generic output formatter and device interface.
 | 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.
 | 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 |
 | imaplib | IMAP4 protocol client (requires sockets).
 | imghdr | Determine the type of image contained in a file or byte stream.
 | imp | 非推奨: Access the implementation of the import statement.
- | importlib | The implementation of the import machinery.
 | importlib.abc | Abstract base classes related to import
 | importlib.machinery | Importers and path hooks
 | importlib.resources | Package resource reading, opening, and access
 | 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 | This module 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 |
 | macpath | Mac OS 9 path manipulation functions.
 | 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.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 |
 | parser | Access parse trees for Python source code.
 | 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 Mac OS X 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 (Linux) | Pseudo-Terminal Handling for Linux.
 | 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 class 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.
 | smtpd | A SMTP server implementation in Python.
 | 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.
 | symbol | Constants representing internal nodes of the parse tree.
 | symtable | Interface to the compiler's internal symbol tables.
 | sys | Access system-specific parameters and functions.
 | 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.support | Support for Python's regression test suite.
 | test.support.script_helper | Support for Python's script execution 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.scrolledtext (Tk) | Text widget with a vertical scroll bar.
 | 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.
 | 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.
 | 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.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.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.

ナビゲーション

  • 索引
  • モジュール |
  • Python »
  • 3.7.2 Documentation »


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

What's New in Python

この"What's New in Python"という一連の文書はPythonのメジャーバージョンにおける最も重要な変更点を紹介します。新しくリリースされた後でも最新の状態であり続けたい人にとって必読のものです。

  • What's New In Python 3.7
    • 概要 -- リリースハイライト
    • 新しい機能
    • その他の言語変更
    • 新たなモジュール
    • 改良されたモジュール
    • C API の変更
    • Build Changes
    • 最適化
    • Other CPython Implementation Changes
    • 非推奨の Python の挙動
    • 非推奨の Python モジュール、関数、メソッド
    • C API の非推奨の関数ならびに型
    • サポート対象プラットフォームからの除外
    • API と機能の削除
    • Module Removals
    • Windows-only Changes
    • Porting to Python 3.7
    • Notable changes in Python 3.7.1
    • Notable changes in Python 3.7.2
  • 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
  • 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 の改善
    • 削除されたモジュール、非推奨となったモジュール
    • 謝辞

"変更履歴" は、 Misc/NEWS.d ディレクトリ以下の内容から ビルドされたファイル の HTML 版で、現在のバージョンの Python への すべての 重要な変更が載っています。

  • 変更履歴
    • Python 3.7.2 final
    • Python 3.7.2 release candidate 1
    • Python 3.7.1 final
    • Python 3.7.1 release candidate 2
    • Python 3.7.1 release candidate 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 リリース候補 1
    • Python 3.5.1 最終版
    • 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.7

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

What's New In Python 3.7

編集者: Elvis Pranskevichus <elvis@magic.io>

この記事では 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
  • 新しい開発用実行時モード
  • PEP 565 、 DeprecationWarning の取り扱いの改善

C API の改善:

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

ドキュメントの改善:

  • PEP 545 、 Python ドキュメント翻訳
  • 新しいドキュメント翻訳: 日本語 、 フランス語 、 韓国語 。

このリリースの特色は、多くの領域での特筆すべきパフォーマンスの改善です。 最適化 節に詳細な一覧があります。

1つ前にリリースされた Python との互換性に影響を持つ変更の一覧については、 Porting to Python 3.7 節を参照してください。

新しい機能

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

Python における型ヒントの到来により、 PEP 3107 で追加され PEP 526 でさらに改善されたアノテーションの機能について、使い勝手に関する 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 4.0 でデフォルトになります。

参考

PEP 563 -- アノテーションの遅延評価
PEP written and implemented by Łukasz Langa.

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

Python 3 シリーズにおける継続中の課題は、"7-bit ASCII" テキストのエンコーディングが何であるかと仮定して、取り扱う賢明なデフォルトの方針です。現在は、非 Windows のプラットフォームではデフォルトの C ロケールつまり POSIX ロケールを使っていると暗黙的に判断されます。

PEP 538 はインタープリタのデフォルトのコマンドラインインターフェースを更新し、新しく加わった PYTHONCOERCECLOCALE 環境変数のドキュメントにある通り、自動的にロケールを UTF-8 に基づいた利用可能なロケールへ強制します。 この方法で LC_CTYPE を自動的に設定すると、コアのインタープリタと (readline などの) ロケールを考慮する C 拡張はデフォルトのテキストエンコーディングとして ASCII ではなく UTF-8 を使うことになります。

PEP 11 にあるプラットフォームのサポート定義も、適切に設定された非 ASCII に基づくロケールだけにテキスト処理の完全なサポートを制限するよう更新されました。

この変更の一部として、強制対象として定義されたのロケール (現時点では C.UTF-8, C.utf8, UTF-8) を使っているときの stdin と stdout のデフォルトのエラーハンドラは (strict ではなく) surrogateescape になります。 stderr のデフォルトのエラーハンドラは、ロケールに関係無く引き続き backslashreplace です。

デフォルトではロケールの強制は暗黙に行われますが、ロケールが関係する結合における問題のデバッグを支援するために、 PYTHONCOERCECLOCALE=warn を設定することで (stderr に直接出力される) 明示的な警告を要求できます。 この設定を有効にしていると、コアのインタプリタの初期化時にレガシーな C ロケールが有効なままの場合、 Python 実行器が警告を出力します。

PEP 538 のロケール強制には、(非 Python アプリケーションや古いバージョンの Python で動くのも含めた) 子プロセスに加え (GNU readline などの) 影響を受ける拡張モジュールにも利益がある一方、適切な対象ロケールが実行するシステムに存在することを要求するという負の面もあります。 (例えば、RHEL/CentOS 7 で起きているように) 適切な対象ロケールで利用可能なものが無いケースにきちんと対処するために、 Python 3.7 には PEP 540: 強制 UTF-8 実行モード も実装されています。

参考

PEP 538 -- レガシーな 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 CPython 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'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 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 -- 新しい 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 -- 組み込みの 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 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 -- 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 -- モジュールの __getattr__ と __dir__
PEP written and implemented by Ivan Levkivskyi

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

モダンなシステムの時計の分解能は、 time.time() 関数やそれに類する関数が返す浮動小数点数の精度を越えることがあります。 精度を失わないように、 PEP 564 により既存の時間関数の 6 つの新しい "ナノ秒" 版が time モジュールに追加されました:

  • time.clock_gettime_ns()
  • time.clock_settime_ns()
  • time.monotonic_ns()
  • time.perf_counter_ns()
  • time.process_time_ns()
  • time.time_ns()

新しい関数は、整数値としてナノ秒単位の数値を返します。

計測 によると、 Linux と Windows では time.time_ns() の分解能はおおよそ time.time() の 3 倍ということが示されています。

参考

PEP 564 -- ナノ秒単位の分解能を持つ新しい時間関数の追加
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 -- Show DeprecationWarning in __main__
PEP written and implemented by Nick Coghlan

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

当初 PEP 484 は、 CPython のインタプリタのコア部分に どんな 変更も施さないような方法で設計されていました。 今では型ヒントと typing モジュールはコミュニティに広く使われるようになったため、この制限は取り除かれました。 この PEP では、2 つの特殊メソッド __class_getitem__() と __mro_entries__ が導入され、これらのメソッドはほとんどのクラスと typing にある特別な構成物に使われています。 その結果、型に関する様々な操作の速度が最大で 7 倍にまでなり、ジェネリック型はメタクラスの衝突を起こさずに使えるようになり、 typing にずっとあったいくつかのバグが修正されました。

参考

PEP 560 -- 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 and content-based build systems.

PEP 552 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 -- Deterministic pycs
PEP written and implemented by Benjamin Peterson

PEP 545: Python Documentation Translations

PEP 545 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 -- Python ドキュメント翻訳
PEP written and implemented by Julien Palard, Inada Naoki, and Victor Stinner.

Development Runtime Mode: -X dev

The new -X dev command line option or the new PYTHONDEVMODE environment variable can be used to enable CPython's development mode. When in development mode, CPython performs additional runtime checks that are too expensive to be enabled by default. See -X dev documentation for the full description of the effects of this mode.

その他の言語変更

  • 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 and bpo-18896.)
  • bytes.fromhex() and bytearray.fromhex() now ignore all ASCII whitespace, not only spaces. (Contributed by Robert Xiao in 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.)
  • ImportError now displays module name and module __file__ path when from ... import ... fails. (Contributed by Matthias Bussonnier in bpo-29546.)
  • Circular imports involving absolute imports with binding a submodule to a name are now supported. (Contributed by Serhiy Storchaka in bpo-30024.)
  • object.__format__(x, '') is now equivalent to str(x) rather than format(str(self), ''). (Contributed by Serhiy Storchaka in 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.)
  • 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.)
  • The new -X importtime option or the PYTHONPROFILEIMPORTTIME environment variable can be used to show the timing of each module import. (Contributed by Victor Stinner in 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 -- コンテキスト変数
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 -- データクラス
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.

参考

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

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

  • 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 for more details. (Contributed by Yury Selivanov in 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.)

  • The new loop.start_tls() method can be used to upgrade an existing connection to TLS. (Contributed by Yury Selivanov in 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.)

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

  • The new provisional BufferedProtocol class allows implementing streaming protocols with manual control over the receive buffer. (Contributed by Yury Selivanov in 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.)

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

  • The new loop.sock_sendfile() coroutine method allows sending files using os.sendfile when possible. (Contributed by Andrew Svetlov in 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 and Srinivas Reddy Thatiparthy in 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.)

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

  • The loop.create_datagram_endpoint() method gained support for Unix sockets. (Contributed by Quentin Dawans in 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.)

  • The new Handle.cancelled() method returns True if the callback was cancelled. (Contributed by Marat Sharafutdinov in bpo-31943.)

  • The asyncio source has been converted to use the async/await syntax. (Contributed by Andrew Svetlov in 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.)

  • Loop methods which accept socket paths now support passing path-like objects. (Contributed by Yury Selivanov in 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.)

  • Exceptions occurring in cancelled tasks are no longer logged. (Contributed by Yury Selivanov in bpo-30508.)

  • New WindowsSelectorEventLoopPolicy and WindowsProactorEventLoopPolicy classes. (Contributed by Yury Selivanov in 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.)

calendar

HTMLCalendar クラスに、作成された HTML カレンダーの CSS クラスのカスタマイズを容易にするクラス属性が新しく加わりました。 (Contributed by Oz Tiram in bpo-30095.)

collections

collections.namedtuple() がデフォルト値をサポートするようになりました。 (Contributed by Raymond Hettinger in 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.)

concurrent.futures

ProcessPoolExecutor と ThreadPoolExecutor が新しいコンストラクタ引数 initializer と initargs をサポートするようになりました。 (Contributed by Antoine Pitrou in bpo-21423.)

ProcessPoolExecutor が新しい mp_context 引数を通して multiprocessing の context を受け取れるようになりました。 (Contributed by Thomas Moreau in bpo-31540.)

contextlib

The new nullcontext() is a simpler and faster no-op context manager than ExitStack. (Contributed by Jesse-Bakker in bpo-10049.)

The new asynccontextmanager(), AbstractAsyncContextManager, and AsyncExitStack have been added to complement their synchronous counterparts. (Contributed by Jelle Zijlstra in bpo-29679 and bpo-30241, and by Alexander Mohr and Ilya Kulakov in 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.)

crypt

The crypt module now supports the Blowfish hashing method. (Contributed by Serhiy Storchaka in bpo-31664.)

The mksalt() function now allows specifying the number of rounds for hashing. (Contributed by Serhiy Storchaka in 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.)

The tzinfo class now supports sub-minute offsets. (Contributed by Alexander Belopolsky in 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.)

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

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

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

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

functools

functools.singledispatch() now supports registering implementations using type annotations. (Contributed by Łukasz Langa in 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.)

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

http.client

HTTPConnection and HTTPSConnection now support the new blocksize argument for improved upload throughput. (Contributed by Nir Soffer in 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.)

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

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

idlelib と IDLE

自動補完におけるいくつもの修正。 (Contributed by Louie Lu in 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.)

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.) The sample can be edited to include other characters. (Contributed by Serhiy Storchaka in 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.)

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, bpo-33768, and 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.)

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

上で挙げた変更は 3.6 のメンテナンスリリースにバックポートされました。

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

importlib.reload() now raises ModuleNotFoundError if the module lacks a spec. (Contributed by Garvit Khatri in 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.)

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 and INADA Naoki in 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.)

itertools

itertools.islice() now accepts integer-like objects as start, stop, and slice arguments. (Contributed by Will Roberts in 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.)

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

The new StreamHandler.setStream() method can be used to replace the logger stream after handler creation. (Contributed by Vinay Sajip in 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.)

math

新しい math.remainder() 関数が IEEE 754 方式の剰余演算で実装されています。 Contributed by Mark Dickinson in 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.)

msilib

The new Database.Close() method can be used to close the MSI database. (Contributed by Berker Peksag in 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.)

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

Non-daemonic threads created by Process are now joined on process exit. (Contributed by Antoine Pitrou in bpo-18966.)

os

os.fwalk() now accepts the path argument as bytes. (Contributed by Serhiy Storchaka in bpo-28682.)

os.scandir() gained support for file descriptors. (Contributed by Serhiy Storchaka in 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.)

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

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

os.dup2() now returns the new file descriptor. Previously, None was always returned. (Contributed by Benjamin Peterson in 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.)

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

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

pdb command line now accepts -m module_name as an alternative to script file. (Contributed by Mario Corchero in 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 of .pyc files when they are created eagerly. (Contributed by Bernhard M. Wiedemann in 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.)

queue

The new SimpleQueue class is an unbounded FIFO queue. (Contributed by Antoine Pitrou in 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.)

re.split() now supports splitting on a pattern like r'\b', '^$' or (?=-) that matches an empty string. (Contributed by Serhiy Storchaka in 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.)

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

Compiled regular expression and match objects can now be copied using copy.copy() and copy.deepcopy(). (Contributed by Serhiy Storchaka in 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.)

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

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

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 and Nathaniel J. Smith in 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.)

Sockets now auto-detect family, type and protocol from file descriptor by default. (Contributed by Christian Heimes in 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.)

The database argument of sqlite3.connect() now accepts any path-like object, instead of just a string. (Contributed by Anders Lorentsen in bpo-31843.)

ssl

ssl モジュールはホスト名またはIPアドレスをチェックするために今は:func:~ssl.match_hostname`モジュールの代わりにOpenSSLの組み込みAPIを使用しています。値はTLSハンドシェイク中に検証されます。今やホスト名のチェックの失敗を含むあらゆる証明書の検証エラーは、:exc:`~ssl.SSLCertVerificationError を発生させ、適切なTLSアラートメッセージとともにハンドシェイクを中止します。新しい例外には追加の情報が含まれています。ホスト名の検証は SSLContext.host_flags. (Contributed by Christian Heimes in 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.)

match_hostname() no longer supports partial wildcards like www*.example.org. SSLContext.host_flags has partial wildcard matching disabled by default. (Contributed by Mandeep Singh in bpo-23033 and Christian Heimes in 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.)

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

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, bpo-20995, bpo-29136, bpo-30622 and 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)

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

Added 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 bpo-34670.)

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

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

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

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

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

sys

The new sys.breakpointhook() hook function is called by the built-in breakpoint(). (Contributed by Barry Warsaw in bpo-31353.)

On Android, the new sys.getandroidapilevel() returns the build-time Android API version. (Contributed by Victor Stinner in 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.)

time

PEP 564 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.)

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

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

types

The new WrapperDescriptorType, MethodWrapperType, MethodDescriptorType, and ClassMethodDescriptorType classes are now available. (Contributed by Manuel Krebber and Guido van Rossum in bpo-29377, and Serhiy Storchaka in bpo-32265.)

The new types.resolve_bases() function resolves MRO entries dynamically as specified by PEP 560. (Contributed by Ivan Levkivskyi in bpo-32717.)

unicodedata

The internal unicodedata database has been upgraded to use Unicode 11. (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.)

unittest.mock

The sentinel attributes now preserve their identity when they are copied or pickled. (Contributed by Serhiy Storchaka in 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.)

urllib.parse

urllib.parse.quote() has been updated from RFC 2396 to RFC 3986, adding ~ to the set of characters that are never quoted by default. (Contributed by Christian Theune and Ratnadeep Debnath in 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.)

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

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

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, bpo-32043, and 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.)

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

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

xmlrpc.server

SimpleXMLRPCDispatcher.register_function can now be used as a decorator. (Contributed by Xiang Zhang in 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.)

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

zipfile

ZipFile now accepts the new compresslevel parameter to control the compression level. (Contributed by Bo Bayles in bpo-21417.)

Subdirectories in archives created by ZipFile are now stored in alphabetical order. (Contributed by Bernhard M. Wiedemann in 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.)

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

The new Py_RETURN_RICHCOMPARE macro eases writing rich comparison functions. (Contributed by Petr Victorin in bpo-23699.)

The new Py_UNREACHABLE macro can be used to mark unreachable code paths. (Contributed by Barry Warsaw in 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.)

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

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

The result of PyUnicode_AsUTF8AndSize() and PyUnicode_AsUTF8() is now of type const char * rather of char *. (Contributed by Serhiy Storchaka in 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.)

Added functions PySlice_Unpack() and PySlice_AdjustIndices(). (Contributed by Serhiy Storchaka in 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.)

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

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

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

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 Porting to 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.)

Py_DecodeLocale(), Py_EncodeLocale() now use the UTF-8 encoding when the UTF-8 mode is enabled. (Contributed by Victor Stinner in bpo-29240.)

PyUnicode_DecodeLocaleAndSize() and PyUnicode_EncodeLocale() now use the current locale encoding for surrogateescape error handler. (Contributed by Victor Stinner in 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.)

Build Changes

Support for building --without-threads has been removed. The threading module is now always available. (Contributed by Antoine Pitrou in 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.)

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

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, bpo-29507, bpo-29452, and 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, and Ivan Levkivskyi in 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.)

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.)
  • asyncio.Future callback management has been optimized. (Contributed by Yury Selivanov in bpo-32348.)
  • asyncio.gather() is now up to 15% faster. (Contributed by Yury Selivanov in 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.)
  • The performance overhead of asyncio debug mode has been reduced. (Contributed by Antoine Pitrou in 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.)

sorted() and list.sort() have been optimized for common cases to be up to 40-75% faster. (Contributed by Elliot Gorokhovsky in bpo-28685.)

dict.copy() is now up to 5.5 times faster. (Contributed by Yury Selivanov in 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.)

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

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

date.fromordinal() and date.fromtimestamp() are now up to 30% faster in the common case. (Contributed by Paul Ganssle in 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.)

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

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

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

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)

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 and 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)

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)

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

The math.erf() and math.erfc() functions now use the (faster) C library implementation on most platforms. (Contributed by Serhiy Storchaka in bpo-26121.)

Other CPython Implementation Changes

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

非推奨の 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.)

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

非推奨の 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.)

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

The asyncio.Task.current_task() and asyncio.Task.all_tasks() methods have been deprecated. (Contributed by Andrew Svetlov in 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.)

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

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

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

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)

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

macpath

The macpath is now deprecated and will be removed in Python 3.8. (Contributed by Chi Hsuan Yen in 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.)

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

ssl

ssl.wrap_socket() is deprecated. Use ssl.SSLContext.wrap_socket() instead. (Contributed by Christian Heimes in 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.)

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

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

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

PyOS_AfterFork() has been deprecated. Use PyOS_BeforeFork(), PyOS_AfterFork_Parent() or PyOS_AfterFork_Child() instead. (Contributed by Antoine Pitrou in 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 provides an example of using the SSL compatibility testing infrastructure 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 splitunc() function in the ntpath module was deprecated in Python 3.1, and has now been removed. Use the splitdrive() function 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.)
  • 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.)
  • The unused distutils install_misc command has been removed. (Contributed by Eric N. Vander Weele in 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.)

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

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

Porting to Python 3.7

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

Changes in Python Behavior

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

  • PEP 479 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.)

  • object.__aiter__() methods can no longer be declared as asynchronous. (Contributed by Yury Selivanov in 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 and 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 and 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 and 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.)

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

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

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

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

  • The struct.Struct.format type is now str instead of bytes. (Contributed by Victor Stinner in 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.)

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

  • repr for datetime.timedelta has changed to include the keyword arguments in the output. (Contributed by Utkarsh Upadhyay in 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 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.)

  • 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 and 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.)

  • tracemalloc.Traceback frames are now sorted from oldest to most recent to be more consistent with traceback. (Contributed by Jesse Bakker in 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.)

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

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

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

  • Struct.format is now a str instance instead of a bytes instance. (Contributed by Victor Stinner in bpo-21071.)

  • ast.literal_eval() is now stricter. Addition and subtraction of arbitrary numbers are no longer allowed. (Contributed by Serhiy Storchaka in 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.)

  • collections.ChainMap now preserves the order of the underlying mappings. (Contributed by Raymond Hettinger in 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.)

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

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

CPython バイトコードの変更

There are two new opcodes: LOAD_METHOD and CALL_METHOD. (Contributed by Yury Selivanov and INADA Naoki in bpo-26110.)

The STORE_ANNOTATION opcode has been removed. (Contributed by Mark Shannon in 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.)

その他の CPython の実装の変更

In preparation for potential future changes to the public CPython runtime initialization API (see PEP 432 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, 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.)

Notable changes in 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). 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.

xml.dom.minidom and xml.sax modules no longer process external entities by default. See also bpo-17239.

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

Notable changes in 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.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • What's New in Python »


What's New In Python 3.6

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

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日にリリースされました。 全詳細については 変更履歴 をご覧ください。

参考

PEP 494 - Python 3.6 リリーススケジュール

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

新たな文法機能:

  • PEP 498、フォーマット済み文字列リテラル。
  • PEP 515、数値リテラル内のアンダースコア。
  • PEP 526、変数アノテーションの文法。
  • PEP 525、非同期ジェネレータ。
  • PEP 530: 非同期内包表記

新たなライブラリーモジュール:

  • secrets: PEP 506 -- 標準ライブラリーに Secrets モジュールを追加.

CPython の実装の改善:

  • dict 型は、 Raymond Hettinger の提案に基づき、 PyPy dict implementation と同様の よりコンパクトな表現 を使うように再実装されました。 その結果、 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 for the rationale.
  • hashlib および ssl モジュールは OpenSSL 1.1.0 をサポートしました。
  • ssl モジュールのデフォルトの設定と機能群が改善されました。
  • hashlib モジュールで BLAKE2, SHA-3, SHAKE ハッシュアルゴリズムと scrypt() キー導出関数がサポートされるようになりました。

Windows の改善:

  • PEP 528 and PEP 529, Windows filesystem and console encoding changed to 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 は新たな種類の文字列リテラル、すなわち 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 -- Literal String Interpolation.
PEP written and implemented by Eric V. Smith.

Feature documentation.

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

PEP 484 は関数の仮引数の型アノテーション、型ヒント、の標準を導入しました。この PEP は Python に、クラス変数およびインスタンス変数を含む変数の型アノテーションの構文を追加しました:

primes: List[int] = []

captain: str  # Note: no initial value!

class Starship:
    stats: Dict[str, int] = {}

関数アノテーションと同様に、Python インタープリタは変数アノテーションに特定の意味を付加せず、クラスやモジュールの __annotations__ 属性に保存するだけです。

静的型付け言語の変数定義とは対照的に、アノテーションシンタックスの目的は抽象構文木および __annotations__ 属性を通じて、サードパーティツールやライブラリーに型の構造化されたメタデータを指定する簡単な方法を提供することです。

参考

PEP 526 -- Syntax for variable annotations
PEP written by Ryan Gonzalez, Philip House, Ivan Levkivskyi, Lisa Roach, and Guido van Rossum. Implemented by Ivan Levkivskyi.

Tools that use or will use the new syntax: mypy, pytype, PyCharm, etc.

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

PEP 515 により、可読性向上のために数値リテラル内でアンダースコアを使えるようになりました。例えば:

>>> 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 -- Underscores in Numeric Literals
PEP written by Georg Brandl and Serhiy Storchaka.

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

PEP 492 で 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 -- Asynchronous Generators
PEP written and implemented by Yury Selivanov.

PEP 530: 非同期内包表記

PEP 530 によりリスト、セット、辞書内包表記ならびにジェネレータ式内での 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 -- Asynchronous Comprehensions
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 -- Simpler customization of class creation
PEP written and implemented by Martin Teichmann.

Feature documentation

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

PEP 487 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 -- Simpler customization of class creation
PEP written and implemented by 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 -- Adding a file system path protocol
PEP written by Brett Cannon and Koos Zevenhoven.

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

世界の大抵の場所で、地域時計が1日繰り下げられることがこれまでありましたし、これからもあるでしょう。そういった時に、同じ日に同じ時間を指す区間があります。そういった状況では地域時計が表示する (あるいは Python の datetime インスタンスが格納する) 情報では、時間内の特定の瞬間を識別することはできません。

PEP 495 は時間内の地域時間が同じ二つの瞬間を区別するために、新たな 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 -- Local Time Disambiguation
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 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 -- Change Windows console encoding to 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 -- Preserving Class Attribute Definition Order
PEP written and implemented by Eric Snow.

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

関数シグニチャにおける **kwargs は挿入順序を保存するマッピングであることが保証されるようになりました。

参考

PEP 468 -- Preserving Keyword Argument Order
PEP written and implemented by Eric Snow.

新たな dict 実装

The dict type now uses a "compact" representation based on a proposal by Raymond Hettinger which was first implemented by PyPy. 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. Idea originally suggested by Raymond Hettinger.)

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 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 -- 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 and 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, 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.)
  • 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.)
  • 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.)
  • 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.)

新たなモジュール

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

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.

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.)
  • 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, to provide a faster asyncio.Future implementation. (Contributed by Yury Selivanov in bpo-27041.)
  • New loop.get_exception_handler() method to get the current exception handler. (Contributed by Yury Selivanov in bpo-27040.)
  • 新しい StreamReader.readuntil() メソッドで、区切りとなるバイトの並びが出てくるまでストリームからデータを読み取れるようになりました。 (Contributed by Mark Korenberg.)
  • The performance of StreamReader.readexactly() has been improved. (Contributed by Mark Korenberg in 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.)
  • Future.set_exception will now raise TypeError when passed an instance of the StopIteration exception. (Contributed by Chris Angelico in 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.)
  • TCP_NODELAY flag is now set for all TCP transports by default. (Contributed by Yury Selivanov in bpo-27456.)
  • New loop.shutdown_asyncgens() to properly close pending asynchronous generators before closing the loop. (Contributed by Yury Selivanov in 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 and 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.)

cmath

The new cmath.tau (τ) constant has been added. (Contributed by Lisa Roach in bpo-12345, see PEP 628 for details.)

新たに定数が追加されました。 math.inf と math.nan に対応する cmath.inf と cmath.nan。複素数の repr が使用する書式に対応する cmath.infj と cmath.nanj。 (Contributed by Mark Dickinson in 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.)

The new Reversible abstract base class represents iterable classes that also provide the __reversed__() method. (Contributed by Ivan Levkivskyi in bpo-25987.)

The new AsyncGenerator abstract base class represents asynchronous generators. (Contributed by Yury Selivanov in 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.)

The verbose and rename arguments for namedtuple() are now keyword-only. (Contributed by Raymond Hettinger in bpo-25628.)

Recursive collections.deque instances can now be pickled. (Contributed by Serhiy Storchaka in 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.)

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

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

The datetime.strftime() and date.strftime() methods now support ISO 8601 date directives %G, %u and %V. (Contributed by Ashley Anderson in 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.)

The datetime.combine() now accepts an optional tzinfo argument. (Contributed by Alexander Belopolsky in 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.)

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

The email.mime classes now all accept an optional policy keyword. (Contributed by Berker Peksag in 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.)

エンコーディング

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

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

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

fileinput

hook_encoded() now supports the errors argument. (Contributed by Joseph Hackman in bpo-25788.)

hashlib

hashlib supports OpenSSL 1.1.0. The minimum recommend version is 1.0.2. (Contributed by Christian Heimes in 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 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. 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.)

http.client

HTTPConnection.request() and endheaders() both now support chunked encoding request bodies. (Contributed by Demian Brecht and Rolf Krahl in 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. 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.)

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

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

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.) The sample can be edited to include other characters. (Contributed by Serhiy Storchaka in 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, bpo-33768, and 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.)

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

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

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

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)

json

json.load() と json.loads() は、バイナリ入力をサポートしました。エンコード済みのJSON は、 UTF-8, UTF-16, UTF-32のいずれかを返すべきです。 (Contributed by Serhiy Storchaka in bpo-17909.)

logging

新しく WatchedFileHandler.reopenIfNeeded() メソッドが追加され、ログファイルを再オープンする必要があるかどうかをチェックする機能が追加れました。(Contributed by Marian Horban in bpo-24884.)

math

The tau (τ) constant has been added to the math and cmath modules. (Contributed by Lisa Roach in bpo-12345, see PEP 628 for details.)

multiprocessing

Proxy Objects returned by multiprocessing.Manager() can now be nested. (Contributed by Davin Potts in 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.)

On Linux, os.urandom() now blocks until the system urandom entropy pool is initialized to increase the security. See the PEP 524 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)

pathlib

pathlib は path-like objects <path-like object>`をサポートしました。 (Contributed by Brett Cannon in :issue:`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.)

pickletools

pickletools.dis() now outputs the implicit memo index for the MEMOIZE opcode. (Contributed by Serhiy Storchaka in bpo-25382.)

pydoc

The pydoc module has learned to respect the MANPAGER environment variable. (Contributed by Matthias Klose in 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.)

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

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

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

Match objects now support index-like objects as group indices. (Contributed by Jeroen Demeyer and Xiang Zhang in 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.)

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

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

sqlite3

sqlite3.Cursor.lastrowid は、 REPLACE 文をサポートしました。 (Contributed by Alex LordThorsen in bpo-16864.)

socket

The ioctl() function now supports the SIO_LOOPBACK_FAST_PATH control code. (Contributed by Daniel Stokes in bpo-26536.)

The getsockopt() constants SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, and SO_PASSSEC are now supported. (Contributed by Christian Heimes in bpo-26907.)

The setsockopt() now supports the setsockopt(level, optname, None, optlen: int) form. (Contributed by Christian Heimes in 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 with support from Victor Stinner.)

New Linux constants TCP_USER_TIMEOUT and TCP_CONGESTION were added. (Contributed by Omar Sandoval, issue: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.)

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

ssl

ssl supports OpenSSL 1.1.0. The minimum recommend version is 1.0.2. (Contributed by Christian Heimes in 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 and bpo-27766.)

SSLContext has better default configuration for options and ciphers. (Contributed by Christian Heimes in 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 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.)

Server and client-side specific TLS protocols for SSLContext were added. (Contributed by Christian Heimes in bpo-28085.)

statistics

A new harmonic_mean() function has been added. (Contributed by Steven D'Aprano in 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.)

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

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

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

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

telnetlib

Telnet is now a context manager (contributed by Stéphane Wirtel in 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.)

timeit now warns when there is substantial (4x) variance between best and worst times. (Contributed by Serhiy Storchaka in 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).

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

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

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

The typing.ContextManager class has been added for representing contextlib.AbstractContextManager. (Contributed by Brett Cannon in bpo-25609.)

The typing.Collection class has been added for representing collections.abc.Collection. (Contributed by Ivan Levkivskyi in bpo-27598.)

The typing.ClassVar type construct has been added to mark class variables. As introduced in PEP 526, 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.)

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

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

unicodedata

The unicodedata module now uses data from Unicode 9.0.0. (Contributed by Benjamin Peterson.)

unittest.mock

Mock クラスは、次の改善が行われました。

  • Mock.assert_called() と Mock.assert_called_once() は、mockオブジェクトが呼ばれたかどうかを確認します。 (Contributed by Amit Saha in 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.)

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

urllib.robotparser

RobotFileParser now supports the Crawl-delay and Request-rate extensions. (Contributed by Nikolay Bogoychev in bpo-16099.)

venv

venv は、新しいパラメータ `--prompt`` を受け入れました。このパラメータは、 仮想環境を表すプリフィックスを指定します。 (Proposed by Łukasz Balcerzak and ported to 3.6 by Stéphane Wirtel in 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 and 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.)

winsound

Allowed keyword arguments to be passed to Beep, MessageBeep, and PlaySound (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.)

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

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

zlib

The compress() and decompress() functions now accept keyword arguments. (Contributed by Aviv Palivoda in bpo-26243 and Xiang Zhang in 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 and bpo-28050.)
  • The asyncio.Future class now has an optimized C implementation. (Contributed by Yury Selivanov and INADA Naoki in bpo-26081.)
  • The asyncio.Task class now has an optimized C implementation. (Contributed by Yury Selivanov in 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).
  • 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).
  • 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).
  • 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).
  • bytes % args is now up to 2 times faster. (Contributed by Victor Stinner in bpo-25349).
  • bytearray % args is now between 2.5 and 5 times faster. (Contributed by Victor Stinner in bpo-25399).
  • Optimize bytes.fromhex() and bytearray.fromhex(): they are now between 2x and 3.5x faster. (Contributed by Victor Stinner in bpo-25401).
  • Optimize bytes.replace(b'', b'.') and bytearray.replace(b'', b'.'): up to 80% faster. (Contributed by Josh Snider in 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).
  • pickle.load() and pickle.loads() are now up to 10% faster when deserializing many small objects (Contributed by Victor Stinner in 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).
  • Optimized glob() and iglob() functions in the glob module; they are now about 3--6 times faster. (Contributed by Serhiy Storchaka in 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).
  • xml.etree.ElementTree parsing, iteration and deepcopy performance has been significantly improved. (Contributed by Serhiy Storchaka in bpo-25638, bpo-25873, and 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.)

ビルドならびに 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 and 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.
  • 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.)
  • 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.)
  • PyArg_ParseTupleAndKeywords() now supports positional-only parameters. Positional-only parameters are defined by empty names. (Contributed by Serhiy Storchaka in 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.)
  • The new PyErr_SetImportErrorSubclass() function allows for specifying a subclass of ImportError to raise. (Contributed by Eric Snow in 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.)
  • The new PyOS_FSPath() function returns the file system representation of a path-like object. (Contributed by Brett Cannon in 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 により導入され、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.)

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

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

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

asynchat

asynchat は asyncio により非推奨になりました。 (Contributed by Mariatta in bpo-25002.)

asyncore

asyncore は asyncio により非推奨になりました。 (Contributed by Mariatta in 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.)

distutils

The undocumented extra_path argument to the 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 for details.

grp

getgrgid() の非整数の引数のサポートは非推奨になりました。 (Contributed by Serhiy Storchaka in 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 and 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.)

ssl

OpenSSLの0.9.8, 1.0.0 ,1.0.1 は非推奨となっており、長い間サポートされていません。将来的に:mod: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.)

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

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.)
  • 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.
  • 非推奨の 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.)

Python API の変更

  • open() will no longer allow combining the 'U' mode flag with '+'. (Contributed by Jeff Balogh and John O'Connor in 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 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.

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

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

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

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

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

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

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

  • type.__new__ をオーバーライドしていない:class:type のサブクラスは、オブジェクトの型を得るのに１引数形式を利用することができません。

  • As part of PEP 487, 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.)

  • The DictReader now returns rows of type OrderedDict. (Contributed by Steve Holden in 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.)

  • The verbose and rename arguments for namedtuple() are now keyword-only. (Contributed by Raymond Hettinger in bpo-25628.)

  • On Linux, ctypes.util.find_library() now looks in LD_LIBRARY_PATH for shared libraries. (Contributed by Vinay Sajip in 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.)

  • The mmap.write() function now returns the number of bytes written like other write methods. (Contributed by Jakub Stasiak in bpo-26335.)

  • The pkgutil.iter_modules() and pkgutil.walk_packages() functions now return ModuleInfo named tuples. (Contributed by Ramchandra Apte in 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.)

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

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.
  • Py_Exit() (and the main interpreter) now override the exit status with 120 if flushing buffered data failed. See 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 and 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 and Serhiy Storchaka in 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.)
  • 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, and Serhiy Storchaka in bpo-27213, 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.)

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

(Contributed by Victor Stinner in bpo-23404.)

バージョン 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.

(Contributed by Victor Stinner in 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 and 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.)

Notable changes in Python 3.6.7

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • What's New in Python »


What's New In Python 3.5

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

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日にリリースされました。 全詳細については 変更履歴 をご覧ください。

参考

PEP 478 - 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.)
  • memoryview クラスが、(複数次元の場合を含んだ) タプルの添字をサポートするようになりました。 (bpo-23632 におけるAntoine Pitrouによる貢献です。)
  • ジェネレータに gi_yieldfrom 属性が新しく追加され、これは yield from 式で反復処理されるオブジェクトを返します。 (Contributed by Benno Leslie and Yury Selivanov in bpo-24450.)
  • 新たな例外 RecursionError が最長再帰深度に到達した際に送出されるようになりました。 (Contributed by Georg Brandl in bpo-19235.)

CPython の実装の改善:

  • LC_TYPE ロケールが POSIX ロケール (C ロケール) のとき、 sys.stdin および sys.stdout は strict エラーハンドラではなく surrogateescape を使うようになりました。 (Contributed by Victor Stinner in 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 を参照してください。この変更は CPython 3.4 と 2.7 にもバックポートされました。)
  • 潜在的なインジェクション攻撃からの防御のために、HTTP クッキーの解析がより厳密に行われるようになりました。 (Contributed by Antoine Pitrou in bpo-22796.)

Windows の改善:

  • Windows のインストーラが新しくなり古い MSI を置き換えました。さらに詳しい情報は Windows で Python を使う をご覧ください。
  • Windows のビルドに Microsoft Visual C++ 14.0 を使うようになっています。拡張モジュールも同じものを使うべきです。

以降は、たくさんのほかの小さな改善、CPython での最適化、非推奨リスト、潜在的な移植性問題を含む、ユーザ向けの変更の包括的なリストになっています。

新しい機能

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

PEP 492 で 待機可能オブジェクト、コルーチン関数、非同期イテレーション、非同期コンテクストマネージャ が追加され、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 -- コルーチン、 async 構文と await 構文
PEP written and implemented by Yury Selivanov.

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

PEP 465 により @ 行列の乗算のための中置演算子が追加されました。 現在のところ 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 -- 行列乗算専用の中置演算子
PEP written by Nathaniel J. Smith; implemented by Benjamin Peterson.

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

PEP 448 によって、 * イテラブルアンパック演算子と ** 辞書アンパック演算子の利用方法が拡張されました。 関数呼び出し で任意の数のアンパックで使えるようになりました:

>>> 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 -- 追加可能なアンパックへの一般化
PEP written by Joshua Landau; implemented by Neil Girdhar, Thomas Wouters, and Joshua Landau.

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

PEP 461 によって、 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 -- bytes と bytearray への % 書式化の追加
PEP written by Ethan Furman; implemented by Neil Schemenauer and Ethan Furman.

PEP 484 - 型ヒント

関数アノテーション構文はバージョン 3.0 ( PEP 3107) から Python の仕様になりましたが、アノテーションのセマンティクスは未定義のままでした。

経験的に、関数アノテーションの使用の大半は関数の引数と返り値の型ヒントを提供するためのものです。 標準ライブラリーが型アノテーションの基本的な定義とツールを持てば、Python ユーザに有益であることは明白となりました。

PEP 484 は 暫定モジュール を導入し、標準的な定義とツール、ならびにアノテーションが利用できない状況についての慣例を提供しています。

例えば、こちらは引数と返り値の型がアノテーションで定義されている簡単な関数です:

def greeting(name: str) -> str:
    return 'Hello ' + name

これらのアノテーションは実行時に通常の __annotations__ 属性より利用出来ますが、 実行時に型を自動的にチェックすることはありません。 その代わり、独立したオフラインの型チェッカ (例えば mypy) を使って要望通りにソースコードの解析を行うことが出来るでしょう。

型システムはユニオン、一般型、そして Any という全ての型と互換な (すなわち代入可能) 特殊型をサポートしています。

参考

  • typing モジュールのドキュメント
  • PEP 484 -- 型ヒント
    PEP 著 Guido van Rossum, Jukka Lehtosalo, Łukasz Langa; 実装 Guido van Rossum。
  • PEP 483 -- 型ヒントの理論
    PEP written by Guido van Rossum

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

PEP 471 により新しいディレクトリ反復関数 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 -- os.scandir() 関数 -- より良く、速いディレクトリイテレータ
PEP 著・実装 Ben Hoyt 補佐 Victor Stinner。

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

システムコール、すなわち I/O の待機がシグナルによって中断される際は常に、エラーコード errno.EINTR で戻ります。 以前は、 Python はそのような場合には InterruptedError を送出していました。 つまり、Python アプリケーションを書く際には、開発者には二つの選択肢がありました:

  1. InterruptedError を無視する。
  2. 呼び出し箇所の全てで InterruptedError を処理し、中断されたシステムコールの再開を試みる。

最初の選択肢では、アプリケーションは断続的に失敗します。 二つ目の選択肢では、定型処理を大量に追加せねばならず、コードの可読性が著しく下がります。 次の2つを比べてみてください:

print("Hello World")

および:

while True:
    try:
        print("Hello World")
        break
    except InterruptedError:
        continue

PEP 475 は 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();
  • 特殊ケース: os.close() と os.dup2() は EINTR エラーを無視するようになりました; そのシステムコールは再試行されません (この論拠については PEP を参照してください);
  • 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 -- EINTR で失敗したシステムコールの再試行
Antoine Pitrou の協力のもと、 PEP および実装は Charles-François Natali と Victor Stinner によって書かれました (『フレンチ・コネクション』)。

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

Python 3.4 以前では、ジェネレータと StopIteration の組み合わせが驚くような動作をし、分かりづらいバグを隠すことがありました。 以前は、ジェネレータ関数内でうっかり StopIteration が送出されると、そのジェネレータの反復処理をしているループ構造が終端に達したと解釈されていました。

PEP 479 によってジェネレータのこの振る舞いが変更されました: ジェネレータ内部で 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

Without a __future__ import, a PendingDeprecationWarning will be raised whenever a StopIteration exception is raised inside a generator.

参考

PEP 479 -- ジェネレータ内の StopIteration の処理の変更
PEP written by Chris Angelico and Guido van Rossum. Implemented by Chris Angelico, Yury Selivanov and Nick Coghlan.

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

PEP 485 により、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 -- A function for testing approximate equality
PEP written by Christopher Barker; implemented by Chris Barker and Tal Einat.

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

PEP 486 により、 Windows ランチャー ( PEP 397 を参照してください) が有効になっている仮想環境を認識するようになりました。 デフォルトのインタプリタを使っていて、 VIRTUAL_ENV 環境変数が設定されているときは、仮想環境のインタプリタが使われます。

参考

PEP 486 -- Python ランチャーが仮想環境を認識する
PEP written and implemented by Paul Moore.

PEP 488: PYO ファイルの廃止

PEP 488 は .pyo ファイルという概念を廃止しました。 つまり、.pyc ファイルは最適化されていないバイトコードと最適化されたバイトコードの両方を指すということです。 バイトコードファイルを何度も再生成する必要がないよう、バイトコードが最適化されたときは .pyc ファイルは任意の opt- タグを名前に持つようになりました。 この副作用で、-O と -OO のいずれかで実行した場合でも、バイトコードのファイル名が衝突しないようになりました。 それにより、-O および -OO で生成したバイトコードは同時に存在できるようになりました。 importlib.util.cache_from_source() にの API は更新され、この変更に役立ちます。

参考

PEP 488 -- PYO ファイルの廃止
PEP written and implemented by Brett Cannon.

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

PEP 489 により拡張モジュールの初期化方式が更新され、 Python 3.4 で PEP 451 によって導入された2段階でモジュールを読み込む仕組みが活用できるようになりました。

この変更によって、新しい仕組みを使うことを選択した拡張モジュールのインポートの動作が、 Python のソースコードやバイトコードでできたモジュールにかなり近くなり、これまで ASCII に制限されていたモジュール名に任意の識別子が使えるようになりました。

参考

PEP 489 -- 拡張モジュールの多段階初期化
PEP 著 Petr Viktorin, Stefan Behnel, Nick Coghlan; 実装 Petr Viktorin.

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

  • "namereplace" エラーハンドラが追加されました。"backslashreplace" エラーハンドラはデコードと変換で動くようになりました。 (Contributed by Serhiy Storchaka in bpo-19676 and bpo-22286.)
  • -b オプションが bytes と int の比較に影響するようになりました。 (Contributed by Serhiy Storchaka in bpo-23681.)
  • 新たなカザフ語 kz1048 及びタジク語 koi8_t コーデックス。 (Contributed by Serhiy Storchaka in bpo-22682 and bpo-22681.)
  • プロパティのドキュメンテーション文字列が書き込み可能になりました。これは特に collections.namedtuple() のドキュメンテーション文字列で有用です。 (Contributed by Berker Peksag in bpo-24064.)
  • 相対インポートに関する循環インポートがサポートされました。(Contributed by Brett Cannon and Antoine Pitrou in bpo-17636.)

新たなモジュール

typing

新たな typing 暫定 モジュールは関数の型アノテーションの標準的な定義とツールを提供します。 詳しくは 型ヒント を参照してください。

zipapp

新たな zipapp モジュール ( PEP 441 で仕様定義) は実行可能な Python Zip アプリケーションを作成するための API とコマンドラインツールを提供します。 Python Zip アプリケーションは Python 2.6 の bpo-1739468 で導入されましたが、それ以降もあまり知られていませんでした。

この新しいモジュールを使ったアプリケーションのバンドル方法は単純で、 __main__.py ファイルを含む全てのファイルをディレクトリ myapp に置き、次のように実行します:

$ python -m zipapp myapp
$ python myapp.pyz

モジュールの実装は bpo-23491 の Paul Moore による貢献です。

参考

PEP 441 -- Python ZIP アプリケーションのサポートの改善 <whatsnew-zipapp>`

改良されたモジュール

argparse

ArgumentParser クラスは、allow_abbrev を False に設定することでロングオプションの 短縮使用 を無効化できるようになりました。 (Contributed by Jonathan Paugh, Steven Bethard, paul j3 and Daniel Eriksson in bpo-14910.)

asyncio

asyncio モジュールは 暫定的 なので、Python 3.5 で導入された全ての変更は Python 3.4.x にバックポートされました。

Python 3.4.0 以後の asyncio モジュールの重要な変更点:

  • New debugging APIs: loop.set_debug() and loop.get_debug() methods. (Contributed by Victor Stinner.)
  • proactor イベントループが SSL をサポートしました。 (Contributed by Antoine Pitrou and Victor Stinner in bpo-22560.)
  • A new loop.is_closed() method to check if the event loop is closed. (Contributed by Victor Stinner in bpo-21326.)
  • A new loop.create_task() to conveniently create and schedule a new Task for a coroutine. The create_task method is also used by all asyncio functions that wrap coroutines into tasks, such as asyncio.wait(), asyncio.gather(), etc. (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.)
  • New loop.set_task_factory() and loop.get_task_factory() methods to customize the task factory that loop.create_task() method uses. (Contributed by 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, 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.)

cgi

FieldStorage クラスが context manager プロトコルをサポートするようになりました。 (Contributed by Berker Peksag in bpo-20289.)

cmath

新たな関数 isclose() は近似的に等しいかどうかを判断する方法を提供します。 (Contributed by Chris Barker and Tal Einat in bpo-24270.)

コード

InteractiveInterpreter.showtraceback() メソッドが、対話的インタープリタのように連なったスタックトレース全体を表示するようになりました。 (Contributed by Claudiu Popa in bpo-17442.)

collections

collections.OrderedDict が C で実装されました。 これにより 4倍 から 100 倍高速になりました。 (Contributed by Eric Snow in bpo-16991.)

OrderedDict.items(), OrderedDict.keys(), OrderedDict.values() ビューが reversed() イテレーションをサポートしました。 (Contributed by Serhiy Storchaka in bpo-19505.)

deque クラスが index()、 insert()、 copy() を定義し、+ と * 演算をサポートしました。 これにより deque インスタンスは MutableSequence と認識され、list との代替性が向上しました。 (Contributed by Raymond Hettinger in bpo-23704.)

namedtuple() で生成されたドキュメンテーション文字列が更新可能となりました:

Point = namedtuple('Point', ['x', 'y'])
Point.__doc__ += ': Cartesian coodinate'
Point.x.__doc__ = 'abscissa'
Point.y.__doc__ = 'ordinate'

(Contributed by Berker Peksag in 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.)

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

新たに Generator 抽象基底クラスが追加されました。 (Contributed by Stefan Behnel in bpo-24018.)

新たに Awaitable, Coroutine, AsyncIterator, AsyncIterable 抽象基底クラスが追加されました。 (Contributed by Yury Selivanov in bpo-24184.)

古い Python のバージョンでは、新しい ABC のバックポートが外部の PyPI パッケージ で利用出来ます。

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

Another new option, -r, allows controlling the maximum recursion level for subdirectories. (Contributed by Claudiu Popa in 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.)

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

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

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

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

csv

writerow() メソッドは、シーケンスだけでなく、 任意のイテラブルをサポートしました。(Contributed by Serhiy Storchaka in bpo-23171.)

curses

The new update_lines_cols() function updates the LINES and COLS environment variables. This is useful for detecting manual screen resizing. (Contributed by Arnon Yaari in bpo-4254.)

dbm

dumb.open always creates a new database when the flag has the value "n". (Contributed by Claudiu Popa in 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.)

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

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

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

doctest

DocTestSuite() 関数が、 module がドキュメンテーション文字列(docstrings)を含まない場合に ValueError を送出するのではなく空の unittest.TestSuite を返すようになりました。 (Contributed by Glenn Jones in 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.)

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

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 and used with an SMTP server that supports the RFC 6531 SMTPUTF8 extension. (Contributed by R. David Murray in bpo-24211.)

The mime.text.MIMEText constructor now accepts a charset.Charset instance. (Contributed by Claude Paroz and Berker Peksag in 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.)

faulthandler

関数 enable(), register(), dump_traceback(), dump_traceback_later() が、ファイル様オブジェクトだけでなくファイル記述子を受け取るようになりました。 (Contributed by Wei Wu in bpo-23566.)

functools

lru_cache() 機構の多くが C で実装されました。これにより速度が大幅に向上しました。 (Contributed by Matt Joiner, Alexey Kachayev, and Serhiy Storchaka in bpo-14373.)

glob

iglob() 関数と glob() 関数は、 "**" パターンを使ったサブディレクトリの再帰的な検索をサポートしました。(Contributed by Serhiy Storchaka in bpo-13968.)

gzip

GzipFile コンストラクタの mode 引数が排他的作成を要求する "x" を受け取るようになりました。 (Contributed by Tim Heaney in 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.)

http

新しい HTTPStatus のenum は、HTTPステータスコードのセットで、その理由句と詳細な説明は、英語で記載されています。(Contributed by Demian Brecht in 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.)

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

The imaplib module now supports RFC 5161 (ENABLE Extension) and RFC 6855 (UTF-8 Support) via the IMAP4.enable() method. A new IMAP4.utf8_enabled attribute tracks whether or not RFC 6855 support is enabled. (Contributed by Milan Oberkirch, R. David Murray, and Maciej Szulik in 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.)

imghdr

The what() function now recognizes the OpenEXR format (contributed by Martin Vignali and Claudiu Popa in bpo-20295), and the WebP format (contributed by Fabrice Aneche and Claudiu Popa in 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.)

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

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

inspect

Both the Signature and Parameter classes are now picklable and hashable. (Contributed by Yury Selivanov in bpo-20726 and 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.)

A new class method Signature.from_callable() makes subclassing of Signature easier. (Contributed by Yury Selivanov and Eric Snow in 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.)

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 and bpo-24400.)

The stack(), trace(), getouterframes(), and getinnerframes() functions now return a list of named tuples. (Contributed by Daniel Shahaf in 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.)

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

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

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

JSON decoder now raises JSONDecodeError instead of ValueError to provide better context information about the error. (Contributed by Serhiy Storchaka in 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.)

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

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

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

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

math

math モジュールに定数 inf および nan が追加されました。 (Contributed by Mark Dickinson in bpo-23185.)

新たな関数 isclose() は近似的に等しいことを調べる方法を提供します。 (Contributed by Chris Barker and Tal Einat in bpo-24270.)

新たに関数 gcd() が追加されました。 関数 fractions.gcd() は非推奨です。 (Contributed by Mark Dickinson and Serhiy Storchaka in bpo-22486.)

multiprocessing

sharedctypes.synchronized() オブジェクトが コンテクストマネージャ プロトコルをサポートするようになりました。 (Contributed by Charles-François Natali in bpo-21565.)

operator

attrgetter(), itemgetter(), and methodcaller() objects now support pickling. (Contributed by Josh Rosenberg and Serhiy Storchaka in bpo-22955.)

行列乗算を行う matmul() 関数と imatmul() 関数が新しく追加されました。 (Contributed by Benjamin Peterson in 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.)

Windows において、新たに stat_result.st_file_attributes 属性が利用可能です。これは Windows API の GetFileInformationByHandle() から返る BY_HANDLE_FILE_INFORMATION 構造体のメンバ dwFileAttributes に対応します。 (Contributed by Ben Hoyt in bpo-21719.)

urandom() 関数が、Linux 3.17 以降ではシステムコール getrandom() を、OpenBSD 5.6 以降ではシステムコール getentropy() を使うようになりました。これは /dev/urandom を使う必要性をなくし、潜在的には起こり得たファイル記述子を使い果たすことによる失敗を避けることに繋がります。 (Contributed by Victor Stinner in bpo-22181.)

新たな関数 get_blocking() および set_blocking() により、ファイル記述子のブロッキングモード (O_NONBLOCK) の取得と設定が出来るようになりました。 (Contributed by Victor Stinner in bpo-22054.)

truncate() と ftruncate() が Windows でサポートされるようになりました。 (Contributed by Steve Dower in 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.)

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

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

There is a new Path.expanduser() method to expand ~ and ~user prefixes. (Contributed by Serhiy Storchaka and Claudiu Popa in 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.)

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

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

poplib

A new POP3.utf8() command enables RFC 6856 (Internationalized Email) support, if a POP server supports it. (Contributed by Milan OberKirch in 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.)

The number of capturing groups in regular expressions is no longer limited to 100. (Contributed by Serhiy Storchaka in 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.)

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

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

selectors

The new DevpollSelector supports efficient /dev/poll polling on Solaris. (Contributed by Giampaolo Rodola' in 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.)

The make_archive() function now supports the xztar format. (Contributed by Serhiy Storchaka in bpo-5411.)

signal

Windows において、 set_wakeup_fd() 関数がソケットハンドルもサポートするようになりました。 (Contributed by Victor Stinner in 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.)

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

The SMTPServer class now advertises the 8BITMIME extension ( RFC 6152) 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.)

The SMTPServer class now also supports the SMTPUTF8 extension ( RFC 6531: 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.)

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

smtplib

A new SMTP.auth() method provides a convenient way to implement custom authentication mechanisms. (Contributed by Milan Oberkirch in 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.)

Both the SMTP.sendmail() and SMTP.send_message() methods now support RFC 6531 (SMTPUTF8). (Contributed by Milan Oberkirch and R. David Murray in bpo-22027.)

sndhdr

関数 what() と whathdr() が namedtuple() で返すようになりました。 (Contributed by Claudiu Popa in bpo-18615.)

socket

Functions with timeouts now use a monotonic clock, instead of a system clock. (Contributed by Victor Stinner in 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.)

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

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

ssl

メモリ BIO サポート

(Contributed by Geert Jansen in 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.)

Where OpenSSL support is present, the ssl module now implements the Application-Layer Protocol Negotiation TLS extension as described in RFC 7301.

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

The SSLSocket class now implements a SSLSocket.sendfile() method. (Contributed by Giampaolo Rodola' in 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.)

The cert_time_to_seconds() function now interprets the input time as UTC and not as local time, per RFC 5280. Additionally, the return value is always an int. (Contributed by Akira Li in 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.)

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

The match_hostname() function now supports matching of IP addresses. (Contributed by Antoine Pitrou in 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; by Lucas Sinclair, Jessica McKellar, and Serhiy Storchaka in bpo-13583.)

subprocess

新たに run() 関数が追加されました。 run() は指定されたコマンドを実行し CompletedProcess オブジェクトを返します。 オブジェクトは終了したプロセスを記述します。 新たな API はより一貫的で、古いバージョンとの互換性を必要としない Python コードでサブプロセスを起動するのに推奨される方法です。 (Contributed by Thomas Kluyver in 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.)

A new is_finalizing() function can be used to check if the Python interpreter is shutting down. (Contributed by Antoine Pitrou in 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.)

tarfile

open() 関数の mode 引数が排他的作成を要求する "x" を受け取るようになりました。 (Contributed by Berker Peksag in 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.)

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

threading

Lock.acquire() と RLock.acquire() の両メソッドがタイムアウトの管理に単調時計を使用するようになりました。 (Contributed by Victor Stinner in bpo-22043.)

time

monotonic() 関数が常に利用出来るようになりました。 (Contributed by Victor Stinner in bpo-22043.)

timeit

新たなコマンドラインオプション -u 又は --unit=U を使用してタイマーの出力の単位を指定できます。 サポートされたオプションは usec, msec, sec です。 (Contributed by Julian Gindi in bpo-18983.)

timeit() 関数に引数 globals が追加されました。 これによりコードが実行される名前空間を指定します。 (Contributed by Ben Roberts in 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.)

traceback

New walk_stack() and walk_tb() functions to conveniently traverse frame and traceback objects. (Contributed by Robert Collins in bpo-17911.)

New lightweight classes: TracebackException, StackSummary, and FrameSummary. (Contributed by Robert Collins in 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.)

types

新たに coroutine() 関数が追加されました。 ジェネレータ と ジェネレータ様 オブジェクトを awaitable に変換します。 (Contributed by Yury Selivanov in bpo-24017.)

新たに型 CoroutineType が追加されました。 async def 関数で作られた coroutine オブジェクトに使われます。 (Contributed by Yury Selivanov in bpo-24400.)

unicodedata

unicodedata モジュールは Unicode 8.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.)

Unittest discovery errors now are exposed in the TestLoader.errors attribute of the TestLoader instance. (Contributed by Robert Collins in bpo-19746.)

A new command line option --locals to show local variables in tracebacks. (Contributed by Robert Collins in 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.)
  • A new Mock.assert_not_called() method to check if the mock object was called. (Contributed by Kushal Das in bpo-21262.)

The MagicMock class now supports __truediv__(), __divmod__() and __matmul__() operators. (Contributed by Johannes Baiter in bpo-20968, and Håkan Lövdahl in bpo-23581 and 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.)

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 and Akshit Khurana in 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.)

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

The parse.urljoin() was updated to use the RFC 3986 semantics for the resolution of relative URLs, rather than RFC 1808 and RFC 2396. (Contributed by Demian Brecht and Senthil Kumaran in 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.)

xmlrpc

client.ServerProxy クラスが コンテクストマネージャ プロトコルをサポートするようになりました。 (Contributed by Claudiu Popa in bpo-20627.)

client.ServerProxy コンストラクタは任意の ssl.SSLContext インスタンスを受け取るようになりました。 (Contributed by Alex Gaynor in bpo-22960.)

xml.sax

SAX パーサは xmlreader.InputSource オブジェクトの文字ストリームをサポートしました。 (Contributed by Serhiy Storchaka in bpo-2175.)

parseString() が str インスタンスを受け取るようになりました。 (Contributed by Serhiy Storchaka in bpo-10590.)

zipfile

ZIP output can now be written to unseekable streams. (Contributed by Serhiy Storchaka in bpo-23252.)

ZipFile.open() メソッドの mode 引数が排他的作成を要求する "x" を受け取るようになりました。 (Contributed by Serhiy Storchaka in bpo-21717.)

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

モジュール mmap, ossaudiodev, socket, ssl, codecs 内の多くの関数が、書き込み可能な bytes 様オブジェクト を受け付けるようになりました。 (Contributed by Serhiy Storchaka in 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.)

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

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, bpo-21487, bpo-20826, bpo-23266.)

Pickling of ipaddress objects was optimized to produce significantly smaller output. (Contributed by Serhiy Storchaka in bpo-23133.)

io.BytesIO の多くの操作が 50% から 100% 速くなりました。 (Contributed by Serhiy Storchaka in bpo-15381 and David Wilson in 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 and bpo-23344.)

UTF-32 エンコーダが 3 から 7 倍速くなりました。 (Contributed by Serhiy Storchaka in bpo-15027.)

正規表現のパースが最高で 10% 速くなりました。 (Contributed by Serhiy Storchaka in 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.)

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

メソッドのキャッシュが少し改良されました。ベンチマークによっては性能が最高で 5% 向上しました。 (Contributed by Antoine Pitrou in bpo-22847.)

random モジュールのオブジェクトのメモリ使用量が 64-bit ビルドで 50% 減少しました。 (Contributed by Serhiy Storchaka in bpo-23488.)

property() ゲッタの呼び出しが最高で 25% 速くなりました。 (Contributed by Joe Jevnik in bpo-23910.)

fractions.Fraction のインスタンス化が最高で 30% 速くなりました。 (Contributed by Stefan Behnel in 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.)

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

新たな calloc 関数が追加されました:

  • PyMem_RawCalloc(),
  • PyMem_Calloc(),
  • PyObject_Calloc().

(Contributed by Victor Stinner in bpo-21233.)

新たなエンコーディング/デコーディングヘルパ関数:

  • Py_DecodeLocale() (_Py_char2wchar() の代わり),
  • Py_EncodeLocale() (_Py_wchar2char() の代わり).

(Contributed by Victor Stinner in bpo-18395.)

A new PyCodec_NameReplaceErrors() function to replace the unicode encode error with \N{...} escapes. (Contributed by Serhiy Storchaka in bpo-19676.)

A new PyErr_FormatV() function similar to PyErr_Format(), but accepts a va_list argument. (Contributed by Antoine Pitrou in bpo-18711.)

A new PyExc_RecursionError exception. (Contributed by Georg Brandl in bpo-19235.)

New PyModule_FromDefAndSpec(), PyModule_FromDefAndSpec2(), and PyModule_ExecDef() functions introduced by PEP 489 -- multi-phase extension module initialization. (Contributed by Petr Viktorin in bpo-24268.)

New PyNumber_MatrixMultiply() and PyNumber_InPlaceMatrixMultiply() functions to perform matrix multiplication. (Contributed by Benjamin Peterson in bpo-21176. See also PEP 465 for details.)

The PyTypeObject.tp_finalize slot is now part of the stable ABI.

Windows でのビルドには今では Microsoft Visual C++ 14.0 が必要です。 Visual Studio 2015 の一部として入手できます。

いくつかのプラットフォームにおいて、拡張モジュールのファイル名にプラットフォームについての情報をタグとして含むようになりました (タグはオプショナルであり、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 により導入され、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 により、CPython 3.5 ではこの OS をもはや公式にはサポートしません。

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

formatter モジュールは完全に非推奨になり、Python 3.6 で削除される予定です。

asyncio.async() 関数は ensure_future() により非推奨になりました。

smtpd モジュールは過去において、常に email メッセージの DATA 部を utf-8 コーデックを使ってデコードしてきました。この振る舞いは今では SMTPServer への新しい decode_data キーワード引数で制御出来ます。この引数のデフォルトは True となっていますが、デフォルト値の使用は非推奨です。この警告メッセージを避けるために decode_data の値として適切な値を明示してください。

http.cookies.Morsel オブジェクトの key, value, coded_value に対して直接代入することは非推奨です。 set() メソッドを使うようにしてください。また、 set() のドキュメントされていなかった LegalChars パラメータは非推奨となり、無視されます。

string.Formatter クラスの format() メソッドに対し、キーワード引数 format_string としてフォーマット文字列を渡すことは非推奨となりました。 (Contributed by Serhiy Storchaka in bpo-23671.)

関数 platform.dist() と platform.linux_distribution() が非推奨となりました。Linux ディストリビューションが自分自身を記述する方法があまりにも多様なため、この機能は外部パッケージに任せることとなりました(訳注: ここでは distro のことを指している)。 (Contributed by Vajrasky Kok and Berker Peksag in bpo-1322.)

inspect.Signature の、以前からドキュメントされていなかったメソッド from_function と from_builtin は非推奨です。新しい Signature.from_callable() を代わりに使ってください。 (Contributed by Yury Selivanov in bpo-24248.)

inspect.getargspec() 関数は非推奨となり、Python 3.6 で削除されることが予定されています。 (See 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.)

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

'\' と ASCII 文字からなる認識出来ない特殊シーケンスが正規表現内と置き換えパターン内で使われた場合に、非推奨警告を出すようになりました。Python 3.6 では禁止されるようになります。 (Contributed by Serhiy Storchaka in bpo-23622.)

unittest.TestLoader.loadTestsFromModule() メソッドのドキュメントされておらず非公式の use_load_tests デフォルト引数は非推奨となり、無視されます。 (Contributed by Robert Collins and Barry A. Warsaw in bpo-16662.)

削除

API と機能の削除

時代遅れとなり、以前に既に非推奨となった以下の API と機能が削除されました:

  • email パッケージの __version__ 属性は削除されました。email パッケージが標準ライブラリとは別々にリリースされていたのは遥か昔の話であり、ここのところ何回かのリリースにいたっては __version__ 文字列が更新されていませんでした。
  • 3.4 で非推奨となっていた ftplib モジュール内の内部クラス Netrc が削除されました。 (Contributed by Matt Chaput in bpo-6623.)
  • .pyo ファイルのコンセプトは削除されました。
  • 暫定 asyncio モジュールで 3.4.4 で非推奨となった JoinableQueue は削除されました。 (Contributed by A. Jesse Jiryu Davis in 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: Python シグナルハンドラが例外を送出しなければ、システムコールがシグナルに中断された場合に、 InterruptedError を送出せずにシステムコールを再試行するようになりました。
  • Python 3.5 以前は、 time オブジェクトは UTC で深夜を表すときに偽とみなされていました。 この挙動は分かりにくく、エラーの元となると考えられ、Python 3.5 で削除されました。 全詳細については bpo-13936 を参照してください。
  • ssl.SSLSocket.send() メソッドは非ブロッキングソケット使用時にオペレーションがブロックされると、 ssl.SSLWantReadError か ssl.SSLWantWriteError のどちらかを送出するようになりました。以前は 0 を返していました。 (Contributed by Nikolaus Rath in bpo-20951.)
  • ジェネレータの __name__ 属性の値として、以前は code オブジェクトの名前から取っていましたが、関数名からセットされるようになりました。code の方が所望の場合は gen.gi_code.co_name から取得してください。ジェネレータは新たに __qualname__ 属性も持つようになりました。これはジェネレータの正規名であり、ジェネレータの表現をする際 (repr(gen)) にこれを用いるようになりました。 (Contributed by Victor Stinner in bpo-21205.)
  • 非推奨だった HTMLParser の "strict" モードが削除されました。つまりソースコード上から HTMLParser クラスの "strict" 引数、 HTMLParser.error() メソッド、 HTMLParserError 例外が削除されました。 (Contributed by Ezio Melotti in bpo-15114.) HTMLParser の convert_charrefs 引数のデフォルトが True となりました。 (Contributed by Berker Peksag in 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.)
  • 既に存在していないディレクトリをカレントディレクトリとして指していた場合に、 find_spec() は以前は FileNotFoundError 例外を送出していましたが、そうではなく None を返却するようになりました。この際 sys.path_importer_cache に None を キャッシュはしません 。これは典型的なケースとは違います(訳注: msg231477)。 (bpo-22834)
  • http.client モジュールと http.server モジュールに散らばっていた HTTP ステータスコードと対応するメッセージを、共通の HTTPStatus enum としてまとめ直しました。http.client 、 http.server にあったもとの値も後方互換性のために残してあります。 (Contributed by Demian Brecht in 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.)
  • re.split() 関数は常に空のパターンマッチを無視してきました。ですからパターン "x*" はパターン "x+" と同じように動作し、パターン "\b" は決して動作しませんでした。今後は re.split() はパターンが空文字列に合致しうる場合に警告を出します。互換性のためには空文字列とはマッチしえないパターンを使ってください(たとえば "x*" ではなく "x+" を使ってください)。空文字列としかマッチしえないパターン(例えば "\b")はエラーとなります。 (Contributed by Serhiy Storchaka in bpo-22818.)
  • http.cookies.Morsel 辞書風インターフェイスのそれ自身での一貫性を持たせるようにしました: morsel の比較に key と value を考慮するようにし、 copy() は dict を返さずに Morsel インスタンスを返すようにし、 update() は更新する辞書内のいずれかのキーが不正(訳注: RFC 2109 として不正なキーのことで、update 以外のインターフェイスでは変更前も拒絶される)であれば例外を投げるようにしています。加えて、ドキュメントされていない set() の LegalChars パラメータは非推奨となり、また指定しても無視されます。 (Contributed by Demian Brecht in bpo-2211.)
  • PEP 488 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.
  • socket モジュールが、linux 3.6 以降で CAN_RAW_FD_FRAMES 定数をエクスポートするようになりました。
  • RFC 5280 に基づき、 ssl.cert_time_to_seconds() 関数が入力の時刻をローカル時刻ではなく UTC として解釈するようになりました。また、戻り値は常に int となります。 (Contributed by Akira Li in 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.)
  • inspect.getdoc() 関数が基底クラスから継承したドキュメンテーション文字列を返すようになりました。その継承したドキュメンテーション文字列が相応しいのであれば、もはやそれを繰り返して記述する必要はありません。継承されたそれを抑制するには、空の文字列を記述しなければなりません(もしくは然るべきドキュメンテーションを埋めれば良いです)。この変更は pydoc モジュールと help() 関数の出力に影響します。 (Contributed by Serhiy Storchaka in bpo-15582.)
  • ネストされた functools.partial() 呼び出しは平坦化されるようになりました。以前の振る舞いに依存していたのであれば functools.partial() オブジェクトに属性を追加するか、または functools.partial() をサブクラス化することで出来ます。 (--訳注: 後半が意味がある内容を言ってるようには思えません。「以前の振る舞い」とはおそらく partial オブジェクトの func 属性が functools.partial そのものになることを指していて、「似たことをしたければ partial オブジェクトに別の属性を付ければりゃいんじゃね?」程度の無責任な代替案を言ってるだけのような気がします。そもそも後者の「サブクラス化」は出来ないと思いますし。 --) (Contributed by Alexander Belopolsky in bpo-7830.)

C API の変更

  • PyMemoryViewObject 構造体の (非公開の) format メンバが削除されました。 memoryobject.h 内のこの構造体に関係する部分に依存している全ての拡張は再ビルドしなければなりません。
  • PyMemAllocator 構造体が PyMemAllocatorEx にリネームされた上で calloc フィールドが追加されました。
  • ドキュメントされておらず、また、参照をリークしていた PyObject_REPR マクロが削除されました。オブジェクトの repr() をフォーマットするには PyUnicode_FromFormat() 的な関数でフォーマット文字 %R を使ってください。(Contributed by Serhiy Storchaka in bpo-22453.)
  • __module__ 属性の欠落は pickle 化とイントロスペクションを壊してしまうので、 __module__ 属性のない組み込み型で DeprecationWarning を引き起こすようにしました。将来これは AttributeError にするかもしれません。(Contributed by Serhiy Storchaka in bpo-20204.)
  • PEP 492 実装の一部として、 PyTypeObject の tp_reserved スロットが tp_as_async スロットで置き換えられました。新しい型、構造体、関数については コルーチンオブジェクト を参照してください。

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

(Contributed by Victor Stinner in bpo-23404.)

バージョン 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.

(Contributed by Victor Stinner in bpo-23404.)

バージョン 3.5.4 で変更.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • What's New in Python »


What's New In Python 3.4

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

What's New In Python 3.4

著者: R. David Murray <rdmurray@bitdance.com> (編集者)

この記事では 3.3 と比較した Python 3.4 の新機能を解説します。 Python 3.4 は2014年3月16日にリリースされました。全詳細については 変更履歴 をご覧ください。

参考

PEP 429 -- Python 3.4 リリーススケジュール

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

新たな文法機能:

  • Python 3.4 に追加された新しい文法機能はありません。

その他の新しい機能:

  • pip が常に利用可能であることが保障されるようになりました ( PEP 453)。
  • 新しく作成されたファイル記述子が継承不可能 （non-inheritable） になりました ( PEP 446)。
  • 隔離モード (isolated mode) の為のコマンドラインオプション (bpo-16499)。
  • 非テキストエンコーディングでの Codec 処理の改良 (複数の issue に関係).
  • インポートシステムのための ModuleSpec 型 ( PEP 451). (インポーターの作者に影響します)
  • marshal フォーマットが よりコンパクトで効率的に なりました (bpo-16475)。

新たなライブラリモジュール:

  • asyncio: 非同期 IO のための新たな暫定 API ( PEP 3156)。
  • ensurepip: pip インストーラのブートストラップ ( PEP 453)。
  • enum: 列挙型のサポート ( PEP 435)。
  • pathlib: オブジェクト指向のファイルシステムパス ( PEP 428)。
  • selectors: 高水準で効率的な I/O の多重化、select モジュールプリミティブを基にしています ( PEP 3156 の一部)。
  • statistics: 基礎的な 数値的に安定な統計ライブラリ ( PEP 450)。
  • tracemalloc: Python のメモリ割り当てのトレース ( PEP 454)。

大幅に改善されたライブラリモジュール:

  • functools の シングルディスパッチジェネリック関数 ( PEP 443)。
  • pickle の新しい プロトコル 4 ( PEP 3154).
  • multiprocessing が Unix で os.fork の使用を避けるオプションを持つようになりました (bpo-8713)。
  • email にサブモジュール contentmanager が追加され、また、 Message のサブクラス (EmailMessage) が追加されました。これは MIME 処理を簡単にします 。 (bpo-18891)
  • inspect と pydoc が以前よりも遥かに幅広い種類の callable オブジェクトを正しくイントロスペクション出来るようになり、これは Python help() システムを改善することになりました。
  • ipaddress モジュール API は安定だと宣言されました。

セキュリティの改善:

  • 安全で取り替え可能なハッシュアルゴリズム ( PEP 456)。
  • ファイル記述子が子プロセスにリークするのを防ぐために 新しく作成されたファイル記述子が継承不可になりました ( PEP 446)。
  • 隔離モード (isolated mode) のための新たなコマンドラインオプション (bpo-16499)。
  • multiprocessing が Unix で os.fork の使用を避けるオプション を持つようになりました。 子プロセスとのデータ共有を避けるため spawn と forkserver はより安全です。
  • Windows での multiprocessing 子プロセスはもはや、必要なものを除いて親の継承可能なハンドルを継承しません。
  • 新たな関数 hashlib.pbkdf2_hmac() は PKCS#5 パスワードベースの鍵導出関数２ を提供します。
  • 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)。
  • PEP 442 を活用することで、ほとんどのケースで モジュールのグローバルがファイナライゼーション中に None がセットされることはなくなりました (bpo-18214)。
  • 設定可能なメモリアロケータ ( PEP 445)。
  • Argument Clinic ( PEP 436)。

以降は、たくさんのほかの小さな改善、CPython での最適化、非推奨リスト、潜在的な移植性問題を含む、ユーザ向けの変更の包括的なリストになっています。

新しい機能

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

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

新しい ensurepip モジュール( PEP 453 で定義されています)は標準のクロスプラットフォームのメカニズムで、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 の通りプラットフォームのパッケージャは、プラットフォームでのそれらインストールの単純明快な手段を自身が提供する(普通システムのパッケージマネージャ)からと言う理由で、デフォルトでのこれらコマンドのインストールを選択しないかもしれません。

注釈

Python 2 と Python 3 の共存インストールでの衝突を避けるために、 ensurepip を直接呼び出した場合のデフォルトでは、バージョン付けされた pip3, pip3.4 コマンドだけがインストールされます。バージョン付けのない pip コマンドもインストールしたければ、 --default-pip オプションが必要です。 pyvenv と Windows インストーラは修飾のない pip コマンドがそれら環境で利用可能となるように保障しますし、また、複数の Python がインストールされたシステムで曖昧さを避けようと直接コマンドを呼び出す代わりに、 pip は -m スイッチ経由でいつでも呼び出せます。

ドキュメントの変更

この変更の一部は、 Python モジュールのインストール と Python モジュールの配布 セクションがより手短な始め方として完全にデザインし直されたことと、FAQ ドキュメントです。ほとんどのパッケージングについてのドキュメンテーションは Python Packaging User Guide が保守している Python Packaging Authority に移動されて、独立したプロジェクトのドキュメンテーションになっています。

ですが、この移行は現在のところまだ少し不完全ですので、これらのガイドのレガシーなバージョンは Python モジュールのインストール (旧版) と Python モジュールの配布 (レガシーバージョン) に残してあります。

参考

PEP 453 -- Python インストールの際の明示的なpipのブートストラッピング
PEP は Donald Stufft と Nick Coghlan によって書かれ、Donald Stufft, Nick Coghlan, Martin von Löwis, Ned Deily により実装されました。

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

PEP 446 により、新規作成するファイル記述子は 継承不可 (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 -- 新規作成されたファイル記述子を継承不可にする
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 のマッピングからは除外されたままだった。---) つまり、バイナリデータの 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, bpo-17827, bpo-17828 and bpo-19619.)

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

PEP 451 は、インポート機構がロードに使うモジュールに関する情報 (つまりモジュールの仕様) のカプセル化を提供します。これはインポートの実装とインポート関連 API の両方を単純化するのに役立ちます。この変更は、 いくつかの将来のインポート関連の改善 の足掛かりでもあります。

この PEP による公な側面での変化は完全に後方互換です。さらにそれらは、インポーターの作者以外にとっては透過的であるはずです。鍵となるファインダとローダのメソッドはまだ動作し続けますが非推奨となりました。新しいインポータは PEP に記述された新メソッドを使うべきです。既存のインポータは新メソッドを実装するように更新すべきです。置き換えられるべきメソッドとその代わりとなるメソッドのリストについては 非推奨 を参照してください。

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

  • Unicode データベースを UCD バージョン 6.3 にアップグレードしました。
  • min() と max() にキーワードオンリー引数 default が追加されました。これにはイテラブルが要素なしであると評価される場合に返す値を指定出来ます。 (Contributed by Julian Berman in bpo-18111.)
  • モジュールオブジェクトが weakref 可能になりました。
  • モジュールの __file__ 属性 (と関連する値) にはデフォルトでは常に絶対パスを含むようになりました。ただし、スクリプトがコマンドラインから相対パスを使って直接実行された際の __main__.__file__ は唯一の例外です。 (Contributed by Brett Cannon in 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.)
  • 新規ドイツ語 EBCDIC codec cp273. (Contributed by Michael Bierenfeld and Andrew Kuchling in bpo-1097797.)
  • 新規ウクライナ語 codec cp1125. (Contributed by Serhiy Storchaka in bpo-19668.)
  • bytes.join() と bytearray.join() が引数として任意のバッファオブジェクトを受け取れるようになりました。 (Contributed by Antoine Pitrou in bpo-15958.)
  • int コンストラクタの base 引数に、 __index__ メソッドを持つ任意のオブジェクトを渡せるようになりました。(Contributed by Mark Dickinson in bpo-16772.) (---訳注: Python API の変更 に同じ bpo-16772 を発端とする変更が書かれているのでそちらも参照して下さい。 ---)
  • フレームオブジェクトに、ローカル変数への全ての参照をフレームからクリアするメソッド clear() が追加されました。(Contributed by Antoine Pitrou in bpo-17934.)
  • memoryview が Sequence として登録され、また、組み込み関数 reversed() をサポートするようになりました。 (Contributed by Nick Coghlan and Claudiu Popa in bpo-18690 and bpo-19078.)
  • Argument Clinic の導入、 inspect と pydoc になされた他の変更の結果、多くの場合で help() が報告するシグニチャが修正・改善されました。
  • __length_hint__() が、公式な言語仕様の一部になりました (see PEP 424)。 (Contributed by Armin Ronacher in bpo-16148.)

新たなモジュール

asyncio

asyncio モジュールが追加されました ( PEP 3156 で定義されています)。これは Python のための標準的で抜き挿し可能なイベントループモデルを、標準ライブラリに信頼出来る非同期 I/O サポートを追加することで提供し、また、ほかのイベントループ実装を標準ライブラリと相互運用することを容易にします。

Python 3.4 では、このモジュールは 暫定 API であるとみなされています。

参考

PEP 3156 -- 非同期 IO サポートの再起動: "asyncio" モジュール
PEP written and implementation led by Guido van Rossum. (訳注: PEP タイトルの「Asynchronous IO Support Rebooted: the "asyncio" Module」は PEP 3153 の焼き直しのため。)

ensurepip

新規の ensurepip モジュールは PEP 453 実装のための本質的な基盤です。通常はエンドユーザはこのモジュールを弄ぶ必要はありません。ですが、 pip のインストレーションや仮想環境に対する自動ブートストラップを拒否していた場合には、手動でそれをブートストラップするのに使えます。

ensurepip は pip のバンドルされたコピーを含んでいて、これは CPython リリースの最初のリリース候補時点での最新です (このことはメンテナンスリリース、feature リリースの両方に適用されます)。 ensurepip 自身はインターネットアクセスしません。依存パッケージ解決のためのインターネットアクセスを要するならばそれは ensurepip 実行の後の pip で行いますし、 pip そのもののアップグレードも pip 自身で行います。(そのようなアップグレード版 pip は個別のインストールパッケージとみなされて、Python がアンインストールされても削除されないことを付記しておきます。)

このモジュールが「 ensure (保障する) 」を名前に冠するのは、 pip がインストール済みならば何もしないからです。このモジュールは --upgrade オプションを持ちますが、これは既存のインストール版 pip がこのモジュールにバンドルされたコピーよりも古い場合に、バンドルされたコピー版 pip をインストールします。

enum

enum モジュール ( PEP 435 にて定義) は標準の列挙型実装を提供します。これにより (socket のような) ほかのモジュールが、不透明な整数定数を後方互換を保ったまま列挙値に置き換えることによって、より情報に富むエラーメッセージを提供したり、より良いデバッグサポートを行えるようになります。

参考

PEP 435 -- 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 -- pathlib モジュール -- オブジェクト指向のファイルシステムパス
PEP written and implemented by Antoine Pitrou.

selectors

新規モジュール selectors ( PEP 3156 の一部として作成されました)　は、高水準で効率的な I/O の多重化を行います。これは select モジュールプリミティブに基いています。

statistics

新規モジュール statistics ( PEP 450 で定義) は統計を扱う中核機能のいくつかを標準ライブラリで直接提供します。このモジュールはデータ系列の平均、中央値、最頻値、分散、標準偏差の計算をサポートします。

参考

PEP 450 -- 標準ライブラリに統計モジュールを追加
PEP written and implemented by Steven D'Aprano

tracemalloc

新たな tracemalloc モジュール ( PEP 454 で定義) は Python が割り当てたメモリブロックをトレースするためのデバッグツールです。 以下の情報を提供します:

  • オブジェクトが割り当てられた場所をトレースする
  • ファイル名ごと、及び行ごとに割り当てられたメモリブロックの以下の統計を取ります：総サイズ、ブロック数、割り当てられたブロックの平均サイズ
  • メモリリークを検出するために2つのスナップショットの差を計算します。

参考

PEP 454 -- Python メモリ割り当てをトレースするための tracemalloc モジュールの追加
PEP written and implemented by Victor Stinner

改良されたモジュール

abc

新規関数 abc.get_cache_token() は、オブジェクトグラフ内での変化の影響を受けるキャッシュをいつ無効化すれば良いかを知るために使えます。 (Contributed by Łukasz Langa in bpo-16832.)

新規クラス ABC はそのメタクラスとして ABCMeta を持ちます。この ABC を基底クラスとして使うことは metaclass=abc.ABCMeta を指定するのと本質的に同じ効果を持ちますが、少ないタイプ数で単純に書ける上に読みやすいものになります。(Contributed by Bruno Dupuis in bpo-16049.)

aifc

getparams() メソッドがプレインなタプルではなく namedtuple を返すようになりました。 (Contributed by Claudiu Popa in bpo-17818.)

aifc.open() がコンテキスト管理プロトコルをサポートするようになりました: with ブロックで使うと戻り値オブジェクトの close() メソッドがブロックの終了時に自動的に呼び出されます。 (Contributed by Serhiy Storchacha in bpo-16486.)

writeframesraw() メソッドと writeframes() メソッドが bytes-like object を受け付けるようになりました。 (Contributed by Serhiy Storchaka in bpo-8311.)

argparse

FileType クラスが encoding 引数、 errors 引数を受け付けるようになりました。これは open() にそのまま渡されます。 (Contributed by Lucas Maystre in bpo-11175.)

audioop

audioop は 24 ビットサンプルをサポートするようになりました。 (Contributed by Serhiy Storchaka in bpo-12866.)

新規関数 byteswap() はビッグエンディアンのサンプル、リトルエンディアンのサンプルの相互変換を行います。 (Contributed by Serhiy Storchaka in bpo-19641.)

全ての audioop 関数が今では任意の bytes-like object を受け付けます。文字列は許容されません。文字列では以前から動作しませんでしたが、ただちに例外を投げるように変更されました。 (Contributed by Serhiy Storchaka in bpo-16685.)

base64

base64 のエンコード・デコード関数が任意の bytes-like object オブジェクトを受け取れるようになりました。以前は bytes または bytearray インスタンスである必要がありました。 (Contributed by Nick Coghlan in 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.)

collections

ChainMap.new_child() メソッドが、チェーンに追加する子マップを指定する m 引数を取るようになりました。これにより、以前は組み込み辞書が必ず maps の先頭になっていましたが、カスタムマッピング型も使えるようになります。(Contributed by Vinay Sajip in bpo-16613.)

colorsys

RGB --- YIQ 変換の係数の桁数が FCC NTSC version に合うように広げられました。結果としての変化は 1% 未満のはずで、また、ほかの処理系での結果とより合致するでしょう。 (Contributed by Brian Landers and Serhiy Storchaka in bpo-14323.)

contextlib

新規コンテキストマネージャ contextlib.suppress によって、意図して単独ステートメントからの例外を抑制しているというコードの意図をはっきりと読み手に伝えることが出来ます。 (Contributed by Raymond Hettinger in bpo-15806 and Zero Piraeus in bpo-19266.)

新規コンテキストマネージャ contextlib.redirect_stdout() は、ユーティリティスクリプトにて、その出力を sys.stdout に書き出す一方でその向き先を変えれない頑固な API の扱いを簡単にしてくれます。これを使うと、 sys.stdout 出力をなにかほかのストリームに振り替えたり、あるいは io.StringIO と組み合わせて文字列化したり出来ます。後者などは特に便利で、たとえば元々はコマンドラインインターフェイスとして実装された関数からの出力を取り込む、などということが出来ます。このコンテキストマネージャはユーティリティスクリプト以外では使わない方が肝要です。というのもこれは sys.stdout の大域的な状態に影響を与えてしまうからです。 (Contributed by Raymond Hettinger in bpo-15805.)

contextlib ドキュメントにも改善が行われ、コンテキストマネージャを単独で使うのと再利用したり再入可能(リエントラント)するのとの違いについての 議論 が追加されました。

dbm

dbm.open() がコンテキスト管理プロトコルをサポートするようになりました: with ブロックで使うとデータベースオブジェクトの close メソッドがブロックの終了時に自動的に呼び出されます。 (Contributed by Claudiu Popa and Nick Coghlan in 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 and Claudiu Popa in bpo-17916.)

新規関数 stack_effect() は与えられた opcode (命令コード) と引数の Python スタックへの effect を計算します。この情報は他からは得られません。 (Contributed by Larry Hastings in bpo-19722.) (---訳注: PyCompile_OpcodeStackEffect として C API として曝した上で Python からアクセス出来るようにしたものらしいです。 stackdepth_walk での使用箇所 参照。---)

doctest

新規 オプションフラグ の FAIL_FAST により、テスト実行を最初の失敗検出で終了させることが出来ます。 (Contributed by R. David Murray and Daniel Urban in bpo-16522.)

doctest コマンドラインインターフェイスは argparse を使うようになりました。2 つの新オプション -o と -f が追加されています。 -o によりコマンドラインから doctest オプション を指定することが出来ます。 -f は -o FAIL_FAST の速記法です (unittest CLI でサポートされる似たオプション サポートされる同じオプション に似せるためです)。 (Contributed by R. David Murray in bpo-11390.)

doctest はいまや、拡張モジュールの __doc__ 文字列から doctest を見つけることが出来ます。 (Contributed by Zachary Ware in bpo-3158.)

email

as_string() メソッドが、その文字列表現を生成するのに使うデフォルトポリシーを上書き出来る policy 引数を取るようになりました。つまり Message を作り直したり flattern メソッドの書式化パラメータのためだけに generator を使うことなしに、 as_string をより多くの状況で使えるということになります。(Contributed by R. David Murray in bpo-18600.)

as_bytes() メソッドが追加されました。これは as_string が文字列表現を生成するのと似たやり方で、メッセージの bytes 表現を生成します。これは maxheaderlen 引数を取りませんが、 unixfrom 引数と policy 引数を取ります。 Message の __bytes__() がこれを呼び出すようにしたので、 bytes(mymsg) は今や直感に反しない結果、つまり完全にフォーマットされたメッセージを生成します。(Contributed by R. David Murray in bpo-18600.)

Message.set_param() メソッドにキーワード引数 replace が追加されました。真を渡すとヘッダリスト内のその位置を変更せずに関連ヘッダを更新します。後方互換のためにデフォルトは False です。 (Contributed by R. David Murray in 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.)

filecmp

clear_cache() 関数が追加されました。 filecmp は os.stat() 情報をキャッシュして最後の比較時点からのファイルの変化をみていますが、このキャッシュをクリアします。これはたとえば、ファイルシステムのタイムスタンプフィールドの解像度未満の時間差で再比較したい場合に使えるでしょう。(Contributed by Mark Levitt in bpo-18149.)

dircmp() 関数に与える ignore パラメータのデフォルト値を、新規のモジュール属性 DEFAULT_IGNORES で指定出来るようになりました。無視するディレクトリのリストで指定してください。(Contributed by Eli Bendersky in bpo-15442.)

functools

新たな partialmethod() デスクリプタは、ちょうど普通の callable に対して partial() がするように、デスクリプタへの引数部分適用を可能にします。この新しいデスクリプタをクラス定義内で使うと、簡単に (partial() インスタンスを含む) 任意の callable を普通のインスタンスメソッドのように振舞わせることも出来ます。(Contributed by Alon Horev and Nick Coghlan in bpo-4331.)

新たな singledispatch() デコレータは、Python 標準ライブラリにシングルディスパッチのジェネリック関数のサポートを追加します。オブジェクト指向プログラミングは共通データ集合についての複数操作をまとめあげてクラスに押し込めようとしますが、ジェネリック関数は 異なった 種類のデータに対して動作させたい操作の複数実装をひとつにまとめあげる考え方です。(---訳注: ここで「ジェネリック関数」と呼んでいるものを他の言語との類推で理解しようとすると、「呼び出す側目線」では同じで、「呼び出される側」目線では違うかもしれません。例えば C++ ユーザは「template の特殊化」もしくは「型ごとのオーバロード」との類推で理解してください。---)

参考

PEP 443 -- シングルディスパッチのジェネリック関数
PEP written and implemented by Łukasz Langa.

total_ordering() は基となる比較関数が NotImplemented を値として返すのをサポートするようになりました。 (Contributed by Katie Miller in bpo-10042.) (---訳注: functools.py のコメント 参照。---)

partial() 関数のピュア Python 版が標準ライブラリに追加されました。CPython の場合は C による高速版で置き換えられますが、ほかの Python 実装で利用出来ます。 (Contributed by Brian Thorne in bpo-12428.)

gc

新規関数 get_stats() は、インタプリタが開始してからの、世代ごと回収統計を持つ辞書の、3 世代ぶんのリストを返します。(Contributed by Antoine Pitrou in bpo-16351.)

glob

新規関数 escape() は、glob 的な展開がなされないようにして字句通りの合致をするように、ファイル名に含まれる特殊文字をエスケープする手段となります。(Contributed by Serhiy Storchaka in bpo-8402.)

hashlib

新たな関数 hashlib.pbkdf2_hmac() は PKCS#5 パスワードベースの鍵導出関数２ を提供します。 (Contributed by Christian Heimes in bpo-18582.)

hashlib のハッシュオブジェクトの name 属性が、公式にサポートされるインターフェイスになりました。これは CPython の hashlib には以前から存在していました (ただしサポートされるハッシュの名前を必ずしも小文字で返してはいませんでした) が、公開インターフェイスとしていなかったために、ほかのいくつかの Python 実装では以前はサポートされていませんでした。(Contributed by Jason R. Coombs in bpo-18532.)

hmac

hmac は、 new() の key 引数として bytearray と bytes を許容するようになり、また、 new() 関数と update() メソッドの両方への msg パラメータとして、 hashlib モジュールがサポートする任意の型を許容するようになりました。(Contributed by Jonas Borgström in bpo-18240.)

hmac.new() 関数への digestmod 引数には、hashlib が認識する任意のハッシュダイジェスト名を渡せるようになりました。これとともに、 digestmod のデフォルトとして MD5 を使う現在の振る舞いは非推奨です。将来のバージョンの Python ではこれのデフォルト値はなくなり、指定が必須になります。 (Contributed by Christian Heimes in bpo-17276.)

block_size 属性と name 属性 (と digest_size 属性の公式ドキュメント) の追加をもって、 hmac モジュールは完全に PEP 247 API を遵守するものとなりました。 (Contributed by Christian Heimes in bpo-18775.)

html

新規関数 unescape() は HTML5 文字参照を対応する Unicode 文字に変換します。 (Contributed by Ezio Melotti in bpo-2927.)

HTMLParser が新規キーワード引数 convert_charrefs を受け取ります。これが True の場合に、全ての文字参照が自動的に変換されます。後方互換性の問題から今はこのデフォルトを False にしてありますが、将来バージョンの Python でこれを True に変えます。ですから値は明示的にセットしてこの新しい機能を使うように更新しておくと良いです。(Contributed by Ezio Melotti in bpo-13633.)

HTMLParser の strict 引数が非推奨となりました。 (Contributed by Ezio Melotti in bpo-15114.)

http

send_error() がオプショナルなパラメータ explain を受け付けるようになりました。指定されると、拡張のエラー説明を提供するにあたって、ハードコードされたデフォルトの代わりに使われます。この拡張のエラー説明は error_message_format 属性を使ってフォーマットされて、エラーレスポンスのメッセージボディとして送信されます。(Contributed by Karl Cow in bpo-12921.)

http.server の コマンドラインインターフェイス に -b/--bind オプションが追加されました。これは特定のアドレスで listen することを指示します。 (Contributed by Malte Swart in 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.)

InspectLoader では get_code() メソッドへのデフォルト実装追加も行われました。とはいえ性能面の理由より、通常はデフォルト実装をオーバライドすることが望ましいです。 (Contributed by Brett Cannon in bpo-18072.)

imp モジュール撤廃に向けて、 imp にあった reload が importlib reload() 関数に移動しました。 (Contributed by Berker Peksag in bpo-18193.)

importlib.util に MAGIC_NUMBER 属性が追加されました。これはバイトコードのバージョン番号へのアクセスを提供します。これは非推奨の imp モジュールにある get_magic() 関数を置き換えるものです。 (Contributed by Brett Cannon in bpo-18192.)

撤廃されるモジュール imp での同名関数を置き換える新規関数として、 importlib.util 関数の cache_from_source() と source_from_cache() が追加されました。 (Contributed by Brett Cannon in bpo-18194.)

importlib ブートストラップ NamespaceLoader が InspectLoader ABC に従うようになりました。つまりこれにより runpy と python -m が名前空間パッケージに対して使えるようになりました。(Contributed by Brett Cannon in bpo-18058.) (訳注: 3.3 以降の名前空間パッケージについては What's New In Python 3.3 ( PEP 420) 参照。)

importlib.util に decode_source() 関数が追加されました。 universal newlines 処理を使って bytes からソースをデコードします。 InspectLoader.get_source() メソッドを実装するのに便利です。

importlib.machinery.ExtensionFileLoader に get_filename() メソッドが追加されました。これは本来実装されるべきものでしたが見落とされていました。(Contributed by Eric Snow in bpo-19152.)

inspect

inspect モジュールに、ソースコードおよびモジュール・クラス・関数についてのその他情報を手早く表示するための、基礎的な コマンドラインインターフェイス が追加されました。 (Contributed by Claudiu Popa and Nick Coghlan in bpo-18626.)

新規の unwrap() で、 functools.wraps() (やラッパー関数に __wrapped__ 属性をセットするその他 API) で作られたラッパー関数のチェインを、簡単にほどくことが出来ます。 (Contributed by Daniel Urban, Aaron Iles and Nick Coghlan in bpo-13266.) (---訳注: 「簡単に」の意味するところについて、 Python API の変更 に記述されている functools.update_wrapper() と functools.wraps() の変更も参照して下さい。---)

新規 enum モジュールが実装されたことを受け inspect モジュールは、カスタム __dir__ メソッドに対する、またメタクラスを介して提供される動的クラス属性に対する、ずっと良いサポートを提供出来るようになりました。 (Contributed by Ethan Furman in bpo-18929 and bpo-19030.)

getfullargspec() と getargspec() が signature() API を使うようになりました。このことで、以前より遥かに幅広い callable をサポートするようになっています。それには __signature__ 属性を含むもの、 Argument Clinic で提供されるメタデータを含むもの、あるいは functools.partial() オブジェクト、なども含まれます。 signature() そのものとは違い、今でも getfullargspec(), getargspec() は __wrapped__ 属性を無視し、そして束縛されたメソッドで最初に束縛された引数を報告するので、それが望みでないならば signature() を直接使うようにあなたのコードを更新する必要があります。(Contributed by Yury Selivanov in 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.) (---訳注: duck type はここでは「 types.FunctionType であることを要求しない」の意味。 _signature_is_functionlike 参照。 ---)

ipaddress

ipaddress は Python 3.3 で標準ライブラリに 暫定 API として追加されました。Python 3.4 リリースで、この但し書きは削除されました: ipaddress は今や安定 API とみなされ、今後は通常の標準ライブラリの後方互換性維持要件に従います。

新規のプロパティ is_global は、アドレスが routeable である場合に True を返します。 (Contributed by Peter Moody in bpo-17400.) (---訳注: リファレンスマニュアルでは routeable という表現ではなく「アドレスがパブリックネットワークに割り当てられている場合」。---)

logging

TimedRotatingFileHandler に atTime パラメータが追加されました。ロールオーバ対象となる日付での時刻を指定します。 (Contributed by Ronald Oussoren in bpo-9556.)

SocketHandler と DatagramHandler が Unix ドメインソケットをサポートするようになりました (port に None をセットすることで)。 (Contributed by Vinay Sajip in commit ce46195b56a9 .)

fileConfig() が fname パラメータとして configparser.RawConfigParser のサブクラスを許容するようになりました。これはロギングの設定がアプリケーション全体の設定の一部に過ぎない場合や、 fileConfig() に渡す前にアプリケーションが設定を修正するような場合でも設定ファイルを使用することを容易にします。(Contributed by Vinay Sajip in bpo-16110.)

logging.config.listen() 関数経由でソケットから受信したロギング設定データを、処理前に検証出来るようになりました。新規のキーワード引数 verify に検証関数を渡すことで可能です。(Contributed by Vinay Sajip in bpo-15452.)

marshal

marshal のバージョンが 3 に上げられました。新バージョンを実装しているコードは、intern された文字列をただ一つのコピーだけ記録しておきデシリアライズでその intern を維持するという Python 2 での振舞いを復活させつつ、「ただ一つのコピー」を文字列型のみならず任意のオブジェクト型に (再帰参照の処理も含め) 拡張しています。これは .pyc ファイルのサイズを削減し、また、 .pyc (または .pyo) ファイルからロードされる際にモジュールが占めるメモリ量を削減します。(Contributed by Kristján Valur Jónsson in bpo-16475, with additional speedups by Antoine Pitrou in bpo-19219.)

mmap

mmap オブジェクトが weakref 可能になりました。 (Contributed by Valerie Lambert in 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.)

multiprocessing には、子プロセスがどのように作られるかを決定する context のコンセプトが追加されています。新規関数 get_context() は指定した開始方式を使うコンテキストを返します。コンテキストは multiprocessing モジュール自身と同じ API を持っているので、コンテキスト内で操作する Pool や他のオブジェクトを、それを使って作成することが出来ます。コンテキストによって、フレームワークとアプリケーションあるいは同じアプリケーションの別の部分が相互に干渉しあわないようにして multiprocessing を使うことが出来ます。(Contributed by Richard Oudkerk in bpo-18999.)

昔からの fork 開始方式を除き、子プロセスはもはや必要のないハンドル・ファイル記述子をその親から継承しません。 (part of bpo-8713).

multiprocessing が開始方式に spawn または forkserver を使う場合に、子プロセスで適切に __main__ を初期化するために runpy (これが -m スイッチを実装しています) に頼るようになりました。これは、 multiprocessing と -m コマンドラインスイッチ・明示的な相対インポートを組み合わせると子プロセスが不可解に失敗していたような、いくつかの際どい問題を解決します。 (Contributed by Nick Coghlan in bpo-19946.)

operator

新規関数 length_hint() は、言語仕様となった特殊メソッド __length_hint__() の PEP 424 公式仕様の一環として、それがどのように使われるのかについて詳述する実装を提供します。(Contributed by Armin Ronacher in bpo-16148.)

参照実装として、また Python 実装の代替として用いることが出来る、 operator モジュールのピュア Python 版が書かれました。 (Contributed by Zachary Ware in 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.)

os.path.samestat() が Windows プラットフォームでも動作するようになりました (また、 os.path.samefile() の実装は Unix と Windows で共有されました)。 (Contributed by Brian Curtin in bpo-11939.)

os.path.ismount() が Windows において、ドライブルートよりも下にあるマウントポイントを認識するようになりました。 (Contributed by Tim Golden in bpo-9035.)

os.open() が新たな 2 つのフラグを、それを提供しているプラットフォームでサポートするようになりました。 O_PATH (未オープンファイル記述子)、 O_TMPFILE (名前なし一時ファイル; Python 3.4.0 リリース時点では、 uapi ヘッダを持っているカーネルバージョン 3.11 以降の Linux システムでのみ利用可能) です。 (Contributed by Christian Heimes in bpo-18673 and Benjamin Peterson, respectively.)

pdb

pdb が、ジェネレータ、 yield 、 yield from をより価値ある方法で処理するように強化されました。これは asyncio ベースのプログラムをデバッグする際にとりわけ助けとなります。 (Contributed by Andrew Svetlov and Xavier de Gaye in 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.)

pickle

pickle で新 pickle プロトコル 4 が追加されました (デフォルトにはされていません)。この新プロトコルは、入れ子のクラスや巨大な文字列・コンテナやキーワードオンリー引数を取る __new__() メソッドを持つクラスなどにまつわるシリアライズの問題など、以前のプロトコルに存在していた数多くの問題を措置しています。ほかにもいくつか効率面での改善が入っています。

参考

PEP 3154 -- Pickle プロトコル 4
PEP written by Antoine Pitrou and implemented by Alexandre Vassalotti.

plistlib

plistlib が、ほかのシリアライズ化プロトコルを扱う標準ライブラリでのお決まりのパターンに従った新 API を追加しました。 load(), dump(), loads(), dumps() です。(なので旧 API は非推奨です。) また、既にサポートされている XML plist フォーマット (FMT_XML) に加えてバイナリ plist フォーマット(FMT_BINARY) のサポートも追加されました。 (Contributed by Ronald Oussoren and others in bpo-14455.)

poplib

poplib に 2 つの新規メソッドが追加されました。 capa() は POP サーバにより公表された機能リストを返します。 stls() は平文 POP3 セッションを、POP サーバがサポートしていれば暗号化された POP3 セッションに切り替えます。 (Contributed by Lorenzo Catucci in bpo-4473.)

pprint

pprint モジュールの、 PrettyPrinter クラス、 pformat() 関数、 pprint() 関数に、新規オプション compact が追加されました。これは出力方法を制御するもので、今のところのこれの True での振舞いは、個々の (インデントされた) 行を width 幅で出来るだけ多くのシーケンスの要素が収まるように出力します。 (Contributed by Serhiy Storchaka in bpo-19132.)

長い文字列が Python の普通の行継続構文で折り返されるようになりました。 (Contributed by Antoine Pitrou in 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.)

pydoc モジュールはもはや既に束縛済みのメソッドでは self パラメータを表示しません。それよりも、与えられた callable の正確な現在のシグニチャを常に表示しようとします。 (Contributed by Larry Hastings in bpo-20710.)

pydoc に直接なされた変更に加え、背後の inspect モジュールの改善が、カスタム __dir__ メソッドやさまざまなデスクリプタの扱いについての振る舞いの大幅な改善に寄与しました。

組み込み help() は pydoc モジュールに基いているので、上記変更は help() の振る舞いにも影響します。

re

fullmatch() 関数と regex.fullmatch() メソッドが追加されました。これはパターンを合致する文字列の両端に固定します。コード変更や既存の正規表現になにか代わりとなるものを追加したりする際に、末尾に $ を入れ忘れるといった類のバグは気付きにくいものです。これらの関数で、合致すべき終端をはっきり伝えることが出来ます。 (Contributed by Matthew Barnett in bpo-16203.)

正規表現オブジェクト の repr にパターンとフラグを含めるようになりました。 match オブジェクト の repr に start、end と合致した部分文字列を含むようになりました。 (Contributed by Hugo Lopes Tavares and Serhiy Storchaka in bpo-13592 and bpo-17087.)

resource

新規関数 prlimit() は、指定プロセスのリソースリミットの問い合わせとセットを、一度の呼び出しで行えます。カーネルバージョン 2.6.36 以降で glibc 2.13 以降の Linux プラットフォームで利用可能です。 (Contributed by Christian Heimes in bpo-16595.)

Linux カーネル 2.6.36 以降のプラットフォームで、いくつかの Linux 固有の定数も追加されました: RLIMIT_MSGQUEUE, RLIMIT_NICE, RLIMIT_RTPRIO, RLIMIT_RTTIME, RLIMIT_SIGPENDING. (Contributed by Christian Heimes in bpo-19324.)

FreeBSD バージョン 9 以降のプラットフォームで、いくつかの FreeBSD 固有の定数が追加されました: RLIMIT_SBSIZE, RLIMIT_SWAP, RLIMIT_NPTS. (Contributed by Claudiu Popa in bpo-19343.)

select

epoll がコンテキスト管理プロトコルをサポートするようになりました: with ブロックで使うと close() メソッドがブロックの終了時に自動的に呼び出されます。 (Contributed by Serhiy Storchaka in bpo-16488.)

devpoll オブジェクトに、メソッド fileno() とメソッド close() 、それに属性 closed が追加されました。 (Contributed by Victor Stinner in bpo-18794.)

shelve

Shelf instances may now be used in with statements, and will be automatically closed at the end of the with block. (Contributed by Filip Gruszczyński in bpo-13896.)

shutil

copyfile() が、コピー元とコピー先が同じファイルの場合に Error の限定されたサブクラスである SameFileError を投げるようになりました。これにより、アプリケーションはこの特定のエラーでそれに相応しいアクションを取れます。 (Contributed by Atsuo Ishimoto and Hynek Schlawack in bpo-1492704.)

smtpd

SMTPServer クラスと SMTPChannel クラスが asynchat.async_chat の map 引数に垂れ流すための map キーワード引数を受け取るようになりました。これでアプリケーションはグローバルなソケットマップを汚さずに済みます。 (Contributed by Vinay Sajip in bpo-11959.) (---訳注: 正確にはここでの変更は SMTPChannel は asynchat.async_chat.__init__(self, conn, map=map) 、SMTPServer は asyncore.dispatcher.__init__(self, map=map) です。グローバルなソケットマップを汚さない、というのは SMTPServer の方にだけその具体の意味が書かれていて、 map を指定しない場合は asyncore のグローバルマップを使う、ということで、これが今回のこの変更前に無条件で行われていたことです。 changeset 84047:ed498f477549 参照。---)

smtplib

SMTPException が OSError のサブクラスになりました。これによって、とにかくエラーが起こったのだということにしか関心がないコードが、ソケット階層でのエラーと SMTP プロトコル階層の両エラーを一撃の try/except 文で捕捉出来るようになりました。 (Contributed by Ned Jackson Lovely in bpo-2118.)

socket

socket モジュールはそれをサポートしているプラットフォームで CAN_BCM プロトコルをサポートするようになりました。 (Contributed by Brian Thorne in bpo-15359.)

ソケットオブジェクトで 継承可能フラグ を制御出来るようになりました。 get_inheritable() で取得し、 set_inheritable() でセットします。

定数値の socket.AF_* と socket.SOCK_* が、新規の enum モジュールを使った列挙値になりました。つまりデバッグなどで魑魅魍魎な整数ではなく徳高い名前で表示されるということです。

AF_LINK 定数が BSD と OSX で利用可能になりました。

inet_pton() と inet_ntop() が Windows でサポートされるようになりました。 (Contributed by Atsuo Ishimoto in bpo-7171.)

sqlite3

connect() 関数に新規の真偽値パラメータ uri が追加されました。これを真にセットすると database パラメータを URI として解釈させることが出来ます。 (SQLite の URI のドキュメント を参照してください)。 (Contributed by poq in 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.)

新規関数 create_default_context() は、互換性とセキュリティの間の程よいバランスとなるよう調整された SSLContext を得るための標準手段として追加されました。それらの設定は SSLContext コンストラクタが与えるデフォルトよりも厳しく、そして将来的にセキュリティにおけるベストプラクティスによる要請が変化すれば、事前予告なしで調整されるかもしれません。SSL をサポートする標準ライブラリの使用においての新しいベストプラクティスとして、 SSLContext を得るのには create_default_context() を使うことが推奨です。必要に応じ、対応する標準ライブラリ API の context 引数に渡すためにそれを使うよう修正してください。(Contributed by Christian Heimes in bpo-19689.)

SSLContext のメソッド load_verify_locations() にオプショナル引数 cadata が追加されました。これには PEM あるいは DER エンコードの証明書を直接指定できます。前者の場合は文字列で、後者では bytes-like object で指定します。(Contributed by Christian Heimes in bpo-18138.)

関数 get_default_verify_paths() が追加されました。これは set_default_verify_paths() メソッドが OpenSSL デフォルトの cafile と capath をセットするのに使うパスと環境変数から成る名前付きタプルを返します。デフォルトの検証にまつわる問題をデバッグするのに使えるでしょう。(Contributed by Christian Heimes in bpo-18143.)

SSLContext の新規メソッド cert_store_stats() はロードされた X.509 証明書、 X.509 CA 証明書、証明書失効リスト (crl) を報告し、また、新規メソッド get_ca_certs() はロードされた CA 証明書のリストを返します。(Contributed by Christian Heimes in bpo-18147.)

OpenSSL 0.9.8 以降が利用可能な場合に、 SSLContext で属性 verify_flags を指定出来るようになりました。これは証明書の検証プロセスをコントロールします。定数 VERIFY_DEFAULT, VERIFY_CRL_CHECK_LEAF, VERIFY_CRL_CHECK_CHAIN, VERIFY_X509_STRICT を組み合わせてセットします。OpenSSL は頼まない限りは証明書失効リスト(CRLs) の検証はしません。 (Contributed by Christien Heimes in bpo-8813.)

SSLContext の新規メソッド load_default_certs() は、プラットフォームによって異なるデフォルトの場所から “認証局” (CA=certification authority) 証明書ファイル一式をロードします。クライアントがサーバを検証するための TLS web サーバ証明の証明書をロード (purpose= SERVER_AUTH) することも、サーバがクライアント証明書を検証するのに用いる証明書をロード (purpose= CLIENT_AUTH) することも出来ます。(Contributed by Christian Heimes in bpo-19292.)

Windows だけで利用出来る関数が 2 つ追加されました。 enum_certificates() と enum_crls() で Windows のシステム証明書ストアから、証明書、証明書の情報、CRLs (certification revocation=証明書失効リスト) を抽出出来ます。(Contributed by Christian Heimes in bpo-17134.)

新規メソッド ssl.SSLContext.set_servername_callback() によるサーバサイド SNI (Server Name Indication) サポートが追加されました。 (Contributed by Daniel Black in bpo-8109.)

SSLSocket.getpeercert() が返す辞書に X509v3 拡張アイテムを含むようになりました: crlDistributionPoints, caIssuers, OCSP URI。 (Contributed by Christian Heimes in bpo-18379.)

stat

stat モジュールが C 実装 _stat に基くようになりました。C 実装は、標準化されておらずプラットフォーム依存となる値のほとんどを取り込むために必要とされました。 (Contributed by Christian Heimes in bpo-11016.)

モジュールは新たに filemode() フラグの S_IFDOOR, S_IFPORT, S_IFWHT をサポートします。 (Contributed by Christian Hiemes in bpo-11016.)

struct

関数 iter_unpack と、コンパイル済フォーマットでのメソッド struct.Struct.iter_unpack() が追加されました。これは、与えられたデータフォーマットの繰り返しインスタンスを含むバッファを逐次的にアンパックします。 (Contributed by Antoine Pitrou in bpo-17804.)

subprocess

check_output() が input 引数を受け付けるようになりました。これは実行するコマンドにとっての stdin を供給するのに使われます (訳注: run() のドキュメント参照)。 (Contributed by Zack Weinberg in bpo-16624.)

getstatus() と getstatusoutput() が Windows でも動作するようになりました。ただしこの変更は実際には、不注意で 3.3.4 に対して既に行われました。 (Contributed by Tim Golden in bpo-10197.)

sunau

getparams() メソッドがプレインなタプルではなく namedtuple を返すようになりました。 (Contributed by Claudiu Popa in bpo-18901.)

sunau.open() がコンテキスト管理プロトコルをサポートするようになりました: with ブロックで使うと戻り値オブジェクトの close メソッドがブロックの終了時に自動的に呼び出されます。 (Contributed by Serhiy Storchaka in bpo-18878.)

24 ビットサンプルの出力をサポートしました。つまり AU_write.setsampwidth() に 24 ビットに対応する値をセット出来ます。 (Contributed by Serhiy Storchaka in bpo-19261.)

writeframesraw() メソッドと writeframes() メソッドが bytes-like object を受け付けるようになりました。 (Contributed by Serhiy Storchaka in bpo-8311.)

sys

新規関数 sys.getallocatedblocks() は、現在インタプリタによりアロケートされているブロック数を返します (デフォルトの --with-pymalloc 設定での CPython では、これは PyObject_Malloc() API によるアロケーションです)。これはメモリリークの追跡に、とりわけテストスイートで自動化されている場合はなおさら有用です。 (Contributed by Antoine Pitrou in bpo-13390.)

Python インタプリタが tut-interactive で開始する際に sys モジュールの属性 __interactivehook__ をチェックするようになりました。この属性があると、対話モード開始直前にその設定値が引数なしで呼び出されます。このチェックは PYTHONSTARTUP ファイルが読み込まれたあとで行われるので、そのファイル内でセット出来ます。 site モジュールは readline をサポートするプラットフォームではタブ補完と (~/.python-history への) 履歴保存を有効にする関数を __interactivehook__ にセットします 。この (新たな) 振る舞いがお気に召さなければ、 PYTHONSTARTUP, sitecustomize, usercustomize のいずれかで sys からこの属性を削除 (あるいはほかのなにか callable をセット) してください。 (Contributed by Éric Araujo and Antoine Pitrou in bpo-5845.)

tarfile

tarfile モジュールはスクリプトや直接 -m で呼ばれた場合、簡単な コマンドラインインターフェイス をサポートするようになりました。 これにより tar ファイルアーカイブの作成や解凍が可能です。 (Contributed by Berker Peksag in bpo-13477.)

textwrap

TextWrapper に 2 つ新しい制御変数が追加されていて、これらは属性値であり、コンストラクタ引数に渡せます。それぞれ max_lines が最大出力行数、 placeholder が max_lines により切り詰める場合に出力の最終行に置くテキストです。これら機能を使った新規のコンビニエンス関数 shorten() が追加されています。これは入力に含まれる全ての空白文字を単一の空白に置き換え、また幅 width に収めて、切り詰める場合は末尾を placeholder (デフォルトで [...]) で置き換えて、単一行で返します。(Contributed by Antoine Pitrou and Serhiy Storchaka in bpo-18585 and bpo-18725.)

threading

メインスレッドを表現する Thread オブジェクトを、新規関数 main_thread() で得られるようになりました。通常の条件であればこれは Python インタプリタを開始したスレッドになります。 (Contributed by Andrew Svetlov in bpo-18882.)

traceback

新規関数 traceback.clear_frames() は、トレースバックオブジェクトを受け取って、それが参照している全てのフレーム内のローカル変数をクリアすることで、メモリ消費量を削減します。 (Contributed by Andrew Kuchling in bpo-1565525.)

types

新規デスクリプタ DynamicClassAttribute() は、そのアクセスがインスタンスからの場合には普通に振舞いつつクラスからのアクセスでは クラス の __getattr__ メソッドに振り向ける属性、これを定義する手段を提供します。このことにより、インスタンス上ではアクティブなプロパティを持ち、クラス上では同名の仮想的属性を持つ、といったことが出来ます (Enum がこれの実例になっています)。 (Contributed by Ethan Furman in bpo-19030.)

urllib

urllib.request が新規クラス DataHandler を介して data: URL をサポートするようになりました。 (Contributed by Mathias Panzenböck in bpo-16423.)

Request クラスで使われる HTTP メソッドを、サブクラスで method 属性をセットすることにより指定出来るようになりました。 (Contributed by Jason R Coombs in 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, Daniel Wozniak in bpo-17485, and Damien Brecht and Senthil Kumaran in bpo-17272.)

HTTPError オブジェクトに、エラーに関係する HTTP レスポンスヘッダへのアクセスを提供する headers 属性が追加されました。 (Contributed by Berker Peksag in bpo-15701.)

unittest

TestCase クラスに新規コンテキストマネージャ subTest() が追加されました。これは with ブロックを「サブテスト化」するコンテキストマネージャを生成します。このコンテキストマネージャにより、テストメソッドで例えばループ内で subTest コンテキストマネージャを呼び出すことで動的にサブテストを作れます。単一のテストメソッドでこれによる「個別に識別され」「個別にカウントされる」テスト群を不定数ぶん生成出来て、そしてそれらはいずれかが失敗したとしても全てが実行されます。例えば以下:

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

unittest.main() の defaultTest に、テスト名からなるイテラブルを渡せるようになりました。以前は文字列で単一のテスト名を渡せるだけでした。 (Contributed by Jyrki Pulliainen in bpo-15132.)

テストディスカバリ最中に発生する SkipTest (これはテストファイル内のモジュールレベルで起こせます) を、エラーとしてではなくスキップとして報告するようになりました。 (Contributed by Zach Ware in bpo-16935.)

discover() が発見したファイルをソートするようになったので、一貫したテスト順でテスト出来ます。 (Contributed by Martin Melin and Jeff Ramnani in bpo-16709.)

TestSuite がその実行完了次第すぐに、テスト成功していれば、テストへの参照を取り除くようになりました。ガーベージコレクションを行う Python インタプリタ上ではこの振る舞いによって、テストへの参照を保持しているものが他にない場合のテストのガーベージコレクトを可能にします。この振る舞いは TestSuite をサブクラス化して何もしない _removeTestAtIndex を定義することで上書き出来ます。 (Contributed by Tom Wardill, Matt McClure, and Andrew Svetlov in bpo-11798.)

テストアサーションの新規コンテキストマネージャ assertLogs() が追加されました。これはコードブロックが logging を使ってログメッセージを発行しているか確認します。デフォルトでは任意のロガーからの INFO 以上のプライオリティを持つメッセージを取れますが、ロガー名と最小プライオリティの両方とも指定可能です。コンテキストマネージャからの戻りオブジェクトに対して、ログされた LogRecord とフォーマットされたメッセージの両方あるいはどちらかを問い合わせることが出来ます。 (Contributed by Antoine Pitrou in bpo-18937.)

テストディスカバリが名前空間パッケージで動作するようになりました。 (Contributed by Claudiu Popa in bpo-17457.)

unittest.mock オブジェクトが、呼び出しが合致する際に仕様としてのシグニチャを検査するようになりました。これはつまり、以前は位置引数だけの合致だったものが、位置引数と名前の両方で合致できるようになったということです。(Contributed by Antoine Pitrou in bpo-17015.)

mock_open() オブジェクトに readline メソッドと readlines メソッドが追加されました。 (Contributed by Toshio Kuratomi in bpo-17467.)

venv

venv に csh と fish シェルの有効化スクリプトが追加されました。 (Contributed by Andrew Svetlov in bpo-15417.)

EnvBuilder クラスとコンビニエンス関数 create() が新規キーワード引数 with_pip を取るようになりました。デフォルトは False です。これは EnvBuilder が仮想環境に pip がインストールされていることを保証するかどうかを制御します。(Contributed by Nick Coghlan in bpo-19552 as part of the PEP 453 implementation.)

wave

getparams() メソッドがプレインなタプルではなく namedtuple を返すようになりました。 (Contributed by Claudiu Popa in bpo-17487.)

wave.open() がコンテキスト管理プロトコルをサポートするようになりました。 (Contributed by Claudiu Popa in bpo-17616.)

wave は シーク不能なファイルへの書き出しが出来るように なりました。 (Contributed by David Jones, Guilherme Polo, and Serhiy Storchaka in bpo-5202.)

writeframesraw() メソッドと writeframes() メソッドが bytes-like object を受け付けるようになりました。 (Contributed by Serhiy Storchaka in bpo-8311.)

weakref

新規 WeakMethod クラスは、インスタンスメソッドへの弱参照をシミュレートします。 (Contributed by Antoine Pitrou in bpo-14631.)

新規クラス finalize は、弱参照自身のライフサイクルを注意深く管理する必要性なしに、オブジェクトがガーベージコレクトされる際に呼び出されるコールバックを登録することを可能にします。 (Contributed by Richard Oudkerk in bpo-15528.)

ref に関連付いたコールバック (あれば) を、新規属性 __callback__ で取得出来るようになりました。(Contributed by Mark Dickinson in bpo-17643.)

xml.etree

ノンブロッキングなアプリケーションでの XML ドキュメントの解析に、新規パーサ XMLPullParser を利用出来ます。実例は 非ブロックパースのためのプル API をみてください。 (Contributed by Antoine Pitrou in 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.)

zipfile

PyZipFile クラスの writepy() メソッドに filterfunc オプションが追加されました。これはアーカイブにどのディレクトリ・ファイルを加えるのかをコントロールするのに使うことが出来ます。例えばテスト用ファイルをアーカイブから除外する、などということが出来ます。(Contributed by Christian Tismer in bpo-19274.)

ZipFile クラスと PyZipfile クラスの allowZip64 パラメータのデフォルトが True に変更されました。 (Contributed by William Mallard in bpo-17201.)

CPython の実装の変更

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

PEP 445 は、CPython インタープリタのメモリ割り当てをカスタマイズするために新たな C 水準のインターフェイスを追加しました。

参考

PEP 445 -- Python メモリアロケータをカスタマイズするための新 API 追加
PEP written and implemented by Victor Stinner.

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

PEP 442 は、 CPython でのオブジェクトのファイナライゼーションにまつわる現在の制限と奇癖を取り除きます。これによって、 __del__() メソッドを持つオブジェクトと finally 節を持つジェネレータが、それらが循環参照に含まれる場合もファイナライズ出来ます。(---訳注: ジェネレータの例については bpo-17468 から派生した bpo-17807 での修正 changeset 83688:c89febab4648 の Lib/test/test_generators.py に追加されたテスト参照。---)

この変更の一環で、モジュールのグローバルは、ほとんどのケースではインタプリタのシャットダウン中に強制的に None がセットされることはなくなり、代わりに循環ガーベージコレクタの通常のオペレーションに委ねます。このことは、循環 GC が最初に導入されて以来悩みの種だった、普通 __del__ メソッドを巻き込んだ「インタプリタシャットダウン時エラーの類」全体を回避します。(---訳注: bpo-18214 (superseder for bpo-812369), changeset 84936:79e2f5bbc30c ---)

参考

PEP 442 -- オブジェクトの安全なファイナライゼーション
PEP written and implemented by Antoine Pitrou.

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

PEP 456 は、Python のハッシュアルゴリズムで行われた以前のセキュリティ修正作業 --- これは公に曝されている辞書検索に裏打ちされた API が標的になるかもしれない、特定の DOS 攻撃に対処するものです --- に追従するものです (この改善の現在ラウンドの事の起こりについては bpo-14621 を見てください)。この PEP では、 CPython のハッシュのコードをパッケージャが異なるハッシュアルゴリズムへの差し替えを容易にするために一元化し、そして Python のデフォルト実装としては 64 ビットデータ型を持つプラットフォームで SipHash に乗り換えます。以前の FNV アルゴリズムと比較したどんなパフォーマンスの差異も、些細なものです。

この PEP は sys.hash_info 構造化シーケンスに、現在実行しているバイナリで使われているハッシュアルゴリズムを記述するためのフィールドを追加します。これら以外にはこの PEP が既存の CPython API を何か置き換えることはありません。

PEP 436: Argument Clinic

「Argument Clinic」( PEP 436) は 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 -- 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.) (---訳注: 安定 ABI, 制限 API については What's New In Python 3.2 ( PEP 384) を参照。---)
  • 初期化前処理 API の Py_SetStandardStreamEncoding() が追加されました。これにより CPython インタプリタを埋め込むアプリケーションは、標準ストリームに対して確実に特定のエンコーディングとエラーハンドラを使わせることが出来ます。(Contributed by Bastien Montagne and Nick Coghlan in bpo-16129.)
  • 文字列引数を変更することのない Python C API のほとんどが、 char * ではなく適切に const char * として宣言されました。 (Contributed by Serhiy Storchaka in bpo-1772673.)
  • Python インタプリタが利用出来ない場合 (例えばクロスコンパイルのシナリオ) であっても使える、シェルで書き直したバージョンの python-config が追加されました。
  • PyUnicode_FromFormat() が %s, %A, %U, %V, %S, %R についての幅と精度の指定をサポートするようになりました。 (Contributed by Ysj Ray and Victor Stinner in bpo-7330.)
  • 既存の PyStructSequence_InitType() 関数を補うものとして、 PyStructSequence_InitType2() が追加されました。違いは、これは成功時に 0 、失敗時に -1 を返すことです。
  • CPython のソースを、最近の GCC と clang のアドレスサニティチェック機能を使ってコンパイル出来るようにしました: 小さなオブジェクト用アロケータで起こっていた偽の警報を黙らせました。 (Contributed by Dhiru Kholia in bpo-18596.)
  • Windows ビルドに アドレス空間配置のランダム化 と データ実行防止 を使うようにしました。 (Contributed by Christian Heimes in bpo-16632.)
  • operator.length_hint() と等価な C API 関数 PyObject_LengthHint() が追加されました。 (Contributed by Armin Ronacher in bpo-16148.)

その他の改善

  • python コマンドに新規 オプション の -l が追加されました。これは「隔離モード (isolated mode)」で Python を実行します。これが意味するのは、 sys.path がスクリプトディレクトリもユーザの site-packages ディレクトリも含まず、また、全ての PYTHON* 環境変数が無視される、というものです (ので暗黙で -s と -E を含んでいるということです)。ほかの制限についても将来適用されるでしょう。その目標はユーザ環境からスクリプト実行を隔離することです。例えばこれは Python がシステムスクリプトとして実行される場合に適切なものです。ほとんどの POSIX システムではシステムスクリプトの #! 行で指定できますし、そうすべきです。(Contributed by Christian Heimes in bpo-16499.)
  • readline をサポートするプラットフォームで、対話インタプリタでの Tab キーでの補完がデフォルトで有効になりました。履歴もデフォルトで有効となり、 ~/.python-history に書き込まれ (そしてそこから読み込まれ) ます。 (Contributed by Antoine Pitrou and Éric Araujo in bpo-5845.)
  • Python インタプリタの --version での起動時、標準エラーではなく標準出力にバージョン情報を出力するようになりました (bpo-18338)。同じ変更は argparse モジュールに対して (bpo-18920)、また、スクリプトとして呼び出せる機能を持つモジュールに対して (bpo-18922) も行われました。
  • CPython の Windows インストーラが、拡張子を登録する際に PATHEXT に .py を追加するようになりました。これをするとユーザは、 Windows コマンドプロンプトから Python スクリプトを、 .py 拡張子なしでその名前だけタイプして実行出来ます。 (Contributed by Paul Moore in bpo-18569.)
  • 新たな make ターゲットの coverage-report の追加。これは python をビルドし、テストスイートを実行し、 gcov と lcov を用いて C 言語のコードベースのカバレッジレポートを HTML で生成します。
  • python 回帰テストスイート への -R オプションが、 sys.getallocatedblocks() を使ったメモリアロケーションのリークもチェックするようになりました。(Contributed by Antoine Pitrou in bpo-13390.) (---訳注: リファレンスマニュアルにオプション説明はないので、 python -m test --help を参照して下さい。---)
  • python -m が名前空間パッケージで動くようになりました。
  • stat モジュールが C で実装されました。これは以前問題であった Python モジュール内で値をハードコードすることなく、定数を C ヘッダファイルから取りこめることを意味しています。(---訳注: bpo-11016 、特に msg127114 以降参照。---)
  • 単一の OS モジュール (POSIX の .so と Windows の .dll) からの複数 Python モジュールのロードを正しく行えるようになりました (以前は黙ってファイル内の最初のモジュールだけが返されていました)。 (Contributed by Václav Šmilauer in bpo-16421.)
  • 新しい命令コード LOAD_CLASSDEREF が追加されました。これは __prepare__ のある種の使い方で起こりうる、クラス本体内の自由変数のロードでのバグを修正するために導入されました。(Contributed by Benjamin Peterson in bpo-17853.)
  • Victor Stinner が、彼の PEP 445 ベースの pyfailmalloc ツールを用いて数多くのメモリエラー関連のクラッシュを特定し、そして修正しました。 (bpo-18408, bpo-18520)
  • pyvenv コマンドに、シンボリックリンクがデフォルトのシステムでもそうせずにコピーを使うようにするための --copies オプションが追加されました。 (Contributed by Vinay Sajip in bpo-18807.)
  • pyvenv コマンドにはさらに、そうしなければ自動的に仮想環境に pip がブートストラップされてしまうのを抑制するための、 --without-pip オプションが追加されました。(Contributed by Nick Coghlan in bpo-19552 as part of the PEP 453 implementation.)
  • 環境変数 PYTHONIOENCODING の値内で、エンコーディング名を省略出来るようになりました。つまり、デフォルトエンコーディングを変更することなしにエラーハンドラだけをセット出来ます。 (Contributed by Serhiy Storchaka in bpo-18818.)
  • bz2、lzma、gzip モジュールの open 関数が x (排他的作成) モードをサポートするようになりました。 (Contributed by Tim Heaney and Vajrasky Kok in bpo-19201, bpo-19222, and bpo-19223.)

大幅な最適化

  • UTF-32 デコーダが3-4倍速くなりました。 (Contributed by Serhiy Storchaka in bpo-14625.)
  • 集合に対するハッシュ衝突のコストが削減されました。ハッシュテーブルの個々の検査 (probe) で、ハッシュテーブル全体を通したランダムな検査を行う前に、連続する隣接したキー/ハッシュペアをチェックするようになりました。これは、キャッシュ局所性を利用して衝突解決のコストを減らします。この衝突解決戦略は、リニア検査とオープンアドレッシング法のハイブリッドとして説明できます。追加的なリニア検査の数はデフォルトでは 9 です。この値は、コンパイル時に LINEAR_PROBES を定義することで任意の値に変更できます。リニア検査を完全に無効にするには LINEAR_PROBES=0 を設定してください。 (Contributed by Raymond Hettinger in bpo-18771.)
  • インタプリタの起動が約 30% 高速化されました。この速度向上は、いくつかの手段によってもたらされました。インタプリタは起動時により少数のモジュールをロードするようになりました。例えば re, collections, locale モジュール、およびそれらの依存モジュールは、デフォルトではインポートされません。 marshal モジュールは、コンパイルされた Python コードをより高速にロードできるように改善されました。 (Contributed by Antoine Pitrou, Christian Heimes and Victor Stinner in bpo-19219, bpo-19218, bpo-19209, bpo-19205 and bpo-9548.)
  • bz2.BZ2File が大半の場合 Python2 のバージョン以上に速くなりました。lzma.LZMAFile も最適化されました。(Contributed by Serhiy Storchaka and Nadeem Vawda in bpo-16034.)
  • random.getrandbits() が (通常使用される) 小さな整数に対して20%-40% 早くなりました。 (Contributed by Serhiy Storchaka in bpo-16674.)
  • 文字列のストレージ形式を変更したことにより、文字列のピックル化は非常に速くなりました。(Contributed by Victor Stinner and Antoine Pitrou in bpo-15596.)
  • io.FileIO.readall() の性能問題が解決されました。これは特に Windows に影響し、 subprocess を通して大量のデータをパイプで渡しているケースでかなり速度向上します。 (Contributed by Richard Oudkerk in bpo-15758.)
  • html.escape() が10倍速くなりました。(Contributed by Matt Bryant in bpo-18020.)
  • Windows において、 obmalloc で CRT の malloc の代わりにネイティブの VirtualAlloc を使うようになりました。人工的なベンチマーク結果は、メモリー消費が 3% 減ったことを示しています。
  • os.urandom() は、複数のスレッドから並行して実行された時に多数のファイル記述子が使われることを避けるために、遅延オープンされる永続的なファイル記述子を使うようになりました。 (Contributed by Antoine Pitrou in bpo-18756.)

非推奨

このセクションでは、Python 3.4 で非推奨となり Python 3.5 以降で削除予定となる、様々な API とその他機能性についてをカバーします。(全てではありませんが) ほとんどのケースで、非推奨に対する警告を (たとえば -Wd を使って) 有効にしたインタプリタ起動時、非推奨 API を使うと DeprecationWarning を励起します。

Python API の非推奨項目

  • PEP 451: インポートシステムのための ModuleSpec 型 にて述べたとおり、多数の importlib メソッドと関数が非推奨となりました。 importlib.find_loader() は importlib.util.find_spec() に取って代わられました; importlib.machinery.PathFinder.find_module() は importlib.machinery.PathFinder.find_spec() に取って代わられました; importlib.abc.MetaPathFinder.find_module() は importlib.abc.MetaPathFinder.find_spec() に取って代わられました; importlib.abc.PathEntryFinder.find_loader() と find_module() は importlib.abc.PathEntryFinder.find_spec() に取って代わられました; 全ての xxxLoader ABC load_module メソッド (importlib.abc.Loader.load_module(), importlib.abc.InspectLoader.load_module(), importlib.abc.FileLoader.load_module(), importlib.abc.SourceLoader.load_module()) はもう実装されるべきではなく、代わりにローダは exec_module メソッド (importlib.abc.Loader.exec_module(), importlib.abc.InspectLoader.exec_module(), importlib.abc.SourceLoader.exec_module()) を実装して残りはインポートシステムに任せなければなりません; そして importlib.abc.Loader.module_repr(), importlib.util.module_for_loader(), importlib.util.set_loader(), importlib.util.set_package() は、インポートシステムによって自動的に処理される内容となったため、もはや必要ありません。
  • imp モジュールは撤廃保留中です。Python 2 と 3 でのコードベースの互換性を維持するために、モジュール削除は現在のところスケジュールされてはいません。
  • 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 が解決するまでは削除はされません。
  • site モジュールは "site-python" ディレクトリが存在すればこれを sys.path に加えていましたが、これは非推奨となりました。 (bpo-19375)

削除

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

以下の OS 向けのソースとビルドツールは削除されました。

  • OS/2 (bpo-16135)。
  • Windows 2000 (changeset e52df05b496a)。
  • COMSPEC が command.com を指している Windows システム (bpo-14470).
  • VMS (bpo-16136)。

API と機能の削除

時代遅れとなり、以前に既に非推奨となった以下の API と機能が削除されました:

  • 保守されていなかった Misc/TextMate と Misc/vim ディレクトリは削除されました (代わりに何が使えるかの提案は devguide をみてください --- 訳注: おそらく Additional Resources に挙げられている wiki を指している ---)。
  • makefile のマクロ SO は削除されました (これは SHLIB_SUFFIX マクロと EXT_SUFFIX マクロで置き換えられました) (bpo-16754)。
  • PyThreadState.tick_counter フィールドは削除されました。これは Python 3.2 で「新しい GIL」が導入された際に意味をなくしていました。 (bpo-19199).
  • PyLoader と PyPycLoader が importlib から削除されました。 (Contributed by Taras Lyapun in 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.)
  • inspect.Signature: 位置依存オンリー (positional-only) パラメータを示すのに今では正当な名前が必要です。
  • object 自身の object.__format__() はもはや空でないフォーマット文字列を受け付けず、 TypeError を投げます。空でない文字列を渡すことは既に Python 3.2 で非推奨となっていました。この変更は以前は動作した (そして正しくない) コードが、オブジェクトが __format__ メソッドを得ることで処理に失敗し始めていた状況を防ぐ目的でなされました。この変更が意味することはあなたのコードにとって、それを処理する __format__ メソッドを持たないオブジェクトに s フォーマットコードを使うと TypeError を起こしうるようになった、ということです。背景については 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)

コードの整理

  • pydoc モジュールで、使用されておらず文書化もされていなかった内部的な Scanner クラスが削除されました。
  • ひどく壊れていた OSX システムで呼ばれる可能性があるのみだった platform モジュールの非公開関数 _mac_ver_lookup, _mac_ver_gstalt, _bcd2str とあわせて、非公開かつ実質的に未使用だった _gestalt モジュールが削除されました。 (see 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.)
  • 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.)
  • importlib.util.module_for_loader() がリロードを適切にサポートするために、 __loader__ と __package__ を無条件にセットするようになりました。これが望む振る舞いでないならば、これら属性を手動でセットする必要があるでしょう。モジュールの管理には importlib.util.module_to_load() を使うことが出来ます。(---訳注: 最後の「You can use importlib.util.module_to_load() for module management.」が意味不明。モジュールのプライベート _module_to_load がコンテキストマネージャとして定義されているので、それのことかもしれません。---)
  • インポートがリロードの際に無条件に関連属性 (例えば __name__, __loader__, __package__, __file__, __cached__) をリセットするようになりました。これは、3.3 以前のリロードの際にモジュールを再発見する振る舞いと同じものを復元するものであるということを注記しておきます。 (bpo-19413)
  • 凍結パッケージ (frozen package) はもはや __path__ にパッケージ名を含むリストをセットせず、空リストをセットします。この以前の振る舞いは、凍結パッケージと同じ名前を持つディレクトリが存在する場合のサブモジュールのインポートで、インポートシステムが間違ったことを起こしうるものでした。モジュールがパッケージなのかそうでないのかを決める正しい方法は、 hasattr(module, '__path__') を使うことです。 (bpo-18065)
  • 凍結モジュール (frozen module) はもはや __file__ 属性を定義しません。それらはどこかはっきりとした場所からロードされたのではないのですから、凍結モジュールにこの属性をセットすることは、意味的に間違っているのです。モジュールが凍結コード由来であることを知る必要があれば、モジュールの __spec__.location に 'frozen' がセットされているかどうかでわかりますし、ローダが importlib.machinery.FrozenImporter のサブクラスかどうかをチェックするか、Python 2 との互換性が必要であれば、 imp.is_frozen() が使えます。
  • py_compile.compile() が書き込み先ファイルパスがシンボリックリンクか非レギュラーファイルの場合に FileExistsError を投げるようになりました。これは、警告の役割を果たすためです、インポートがファイルパスの元のファイルタイプが何かによらずに、それらファイルをレギュラーファイルで上書きすることの。
  • ソースコードをロードしようとして SyntaxError かもしくは UnicodeDecodeError を引き起こした場合に、 importlib.abc.SourceLoader.get_source() はそれを ImportError に読み替えて投げることをしなくなりました。 ImportError はそうあるべきなのに見つからない場合にのみ投げられるべきなので、ソースコードが見つかったけれども正しくない構造である場合の意味にまで及ぶのは、手を伸ばし過ぎで過負荷です。ImportError を捕捉していたコードで今後とも構文エラーとデコーディングの問題を無視したいと望むならば、これら 3 つ全ての例外を捕捉するようにしてください。 (訳注: changeset 84172:e353f64dfd95 )
  • functools.update_wrapper() と functools.wraps() が、たとえその関数も __wrapped__ を持っていたとしても正しくその関数が包まれるように __wrapped__ 属性値をセットするようになりました。つまり __wrapped__ 属性は、以前のようにチェイン内の全ての __wrapped__ 属性が最も内側の関数を参照するのではなく、デコレートされた関数の積み上げを正しくリンクするようになったということです。以前の振る舞いが意図されたものであると思い込んでいたイントロスペクションライブラリの作者は、チェインの中の最初の関数 (__wrapped__ 属性を持たない) にアクセスするのに inspect.unwrap() を使えます。(---訳注: 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))。 (bpo-18416)
  • HTTPConnection と HTTPSConnection から strict 引数が削除されたことは、残りの引数をキーワード引数としてではなく位置引数として使っていたなら意味が変わってしまいます。非推奨警告に注意を払ってきたのであれば、あなたのコードは既に全てのオプショナル引数をキーワードで渡しているはずです。
  • from __future__ import ... ステートメントの間に文字列が含まれる場合に 常に SyntaxError となるようになりました。以前はモジュールの docstring が先頭にある場合とない場合で振る舞いが違っていて、ない場合にこのエラーが意図せず無視される場合がありました。この修正は CPython を言語仕様に準拠させるものです。Jython と PyPy では既にこれが行われています。 (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.) 注意: この修正は後方互換性を保てないので本来メンテナンスリリースの Python 3.3 には入るべきではなかったのですが、不注意で Python 3.3.3 にも行われてしまいました。
  • file 属性が cgi.FieldStorage インスタンスがガーベージコレクトされる際に自動的にクローズされるようになりました。FieldStorage インスタンスを生き永らえさせずにそのファイルオブジェクトを cgi.FieldStorage から切り離して取り出していたなら、 cgi.FieldStorage インスタンス全体を記憶しておくか、あるいは cgi.FieldStorage インスタンスがガーベージコレクトされる前にファイル内容を読み込んでおくかしてください。
  • クローズ済みの SSL ソケットに対する read や write 呼び出しで、以前のようなミステリアスな AttributeError ではなく、役に立つ ValueError を投げるようになりました。 (bpo-9177)
  • slice.indices() が巨大な値で OverflowError を起こすことはなくなりました。この修正からの流れで slice.indices() は負の値に対して ValueError を投げるようになっています。以前はこれは馬鹿げた値を返していました。 (bpo-14794)
  • 特殊メソッド __complex__ が複素数ではなく float を返す実装をしているオブジェクトを渡すと cmath 関数ではエラーとなり、 complex コンストラクタでは受け容れられていましたが、これはいずれも TypeError となるように改められました。(bpo-16290.)
  • 3.2 と 3.3 での int コンストラクタが base パラメータとして誤って float を許容してしまっていました。それをわざわざやっているとも思えないですが、そうしていたなら今後は TypeError になります。 (bpo-16772)
  • キーワードオンリー引数へのデフォルト値が、通常のキーワード引数へのデフォルト値評価の あとで 評価されるようになりました。前ではなく。望むらくは誰一人以前のバギーな振る舞いに頼っちゃうおバカなコードを書いていませんように。願います。 (bpo-16967)
  • 古いスレッド状態が fork() 後にクリアされるようになりました。これにより、以前は不適切に永遠に生き残ってしまっていたいくつかのシステムリソース (たとえば、スレッドローカル記憶内に維持されたデータベース接続) が解放されるようになります。 (bpo-17094.)
  • __annotations__ 辞書内のパラメータ名が __kwdefaults__ と同じように適切にマングル化されるようになりました。 (Contributed by Yury Selivanov in bpo-20625.)
  • hashlib.hash.name が識別子を常に小文字で返すようになりました。以前はいくつかの組み込みハッシュが大文字名を持っていましたが、公式インターフェイスであることから、命名に一貫性を持たせるようにしました。 (bpo-18532)
  • unittest.TestSuite がその実行後にテストへの参照を取り除くようになったので、テスト集合を再実行するのに TestSuite を再利用してテストをまとめあげていると、テスト失敗するかもしれません。テストスイートはそのような方法で再利用すべきではありません。そのようなことをすればテスト実行間で状態が残ってしまうので、 unittest 設計の狙いであるテストの独立性を破壊してしまいます。とはいえ、独立性の欠如を受け容れてもいいと思うのであれば、 TestSuite をサブクラス化して何もしない _removeTestAtIndex を定義することで、古い振る舞いは復元出来ます (TestSuite.__iter__() 参照)。 (bpo-11798)
  • unittest がコマンドライン解析に argparse を使うようになりました。このことで、以前は動作していた不当なコマンド形式で許されなくなったものがあります。理屈から言えばこれは後方互換性の問題ではないはずです。許されなくなったコマンド形式は意味をなしていなかったものですから、使われていたとは思えません。
  • 関数 re.split(), re.findall(), re.sub() と、 match オブジェクトのメソッド group(), groups() は、操作対象が bytes-like object である場合に常に bytes オブジェクトを返すようになりました。以前は戻り値型は入力型に合わせられていました。戻り値の型がたとえば bytearray になることに依存していたのであれば、コードを修正する必要があります。
  • audioop 関数が文字列を入力として渡すと即座にエラーを投げるようにしました。以前は不規則に後々の処理でようやく失敗していました。 (bpo-16685)
  • HTMLParser の新規引数 convert_charrefs は現在は後方互換性維持のために False をデフォルトとしていますが、最終的には True がデフォルトになります。あなたのコードでは HTMLParser の全ての呼び出しでこれをキーワード引数として明示することをお勧めします。 (bpo-13633)
  • hmac.new() 関数の digestmod 引数からデフォルト値が消える予定です。ので、 hmac.new() 呼び出しは常に digestmod を明示するように修正すべきです。 (bpo-17276)
  • sysconfig.get_config_var() にキー SO を渡すことと sysconfig.get_config_vars() の呼び出し結果から SO キーを探すことは非推奨です。このキーは文脈依存の EXT_SUFFIX または SHLIB_SUFFIX で置き換えられるべきです。 (bpo-19555)
  • open 系関数にモード U を使っていたコードは修正すべきです。 U は Python 3 では無力であり、いずれはこれの使用は例外を投げるようになる予定です。使う関数に依存しますが、 newline 引数を使うか、あるいは必要であればストリームを TextIOWrapper でラップしてその newline 引数を使うことで、その古い Python 2 の振る舞いと同等なものを実現出来ます。 (bpo-15204)
  • スクリプト内から pyvenv を使っていて、pip がインストール されない ことを望むならば、コマンド呼び出しに --without-pip を追加しなければなりません。
  • indent を明示した場合の json.dump() と json.dumps() のデフォルトの振る舞いが変更されました。要素を区切るカンマが行末に来る場合の後ろに、空白を追加しなくなりました。これはその出力のテストを空白に繊細な比較をすることで行っている場合にだけ問題になります。 (bpo-16333)
  • doctest が拡張モジュールの __doc__ 文字列から doctest を見つけるようになったので、doctest のテストディスカバリが拡張モジュールを含んでいてその中で doctest のようにみえるものが含まれていると、テスト実行時にこれまで見かけたことのないテスト失敗を目にするかもしれません。 (bpo-3158)
  • collections.abc モジュールが、Python スタートアップの改善の一環で少々リファクタリングが行われました。これの結果として collections は自動で collections.abc をインポートしなくなりました。もしもこの (文書化されていなかった) 暗黙でのインポートに依存していたのであれば、 import collections.abc として明示的にインポートを追加する必要があります。 (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)
  • PyThread_set_key_value() が必ず値をセットするようになりました。Python 3.3 ではこの関数はキーが既存 (で現在値が NULL ポインタでない) の場合には何もしませんでした。
  • PyFrameObject 構造体のフィールド f_tstate (thread state) が、バグをフィックスするために削除されました: 論拠については 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 »


What's New In Python 3.3

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

What's New In Python 3.3

この記事では 3.2 と比較した Python 3.3 の新機能を解説します。 Python 3.3 は2012年9月29日にリリースされました。全詳細については 変更履歴 をご覧ください。

参考

PEP 398 - 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 - Python Virtual Environments
PEP written by Carl Meyer; implementation by Carl Meyer and Vinay Sajip

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

__init__.py マーカーファイルを必要としないパッケージディレクトリと、複数のモジュールパスをネイティブでサポートします( PEP 420 に記載された様々なサードパーティでの名前空間のアプローチに影響されています)

参考

PEP 420 - Implicit Namespace Packages
PEP written by Eric V. Smith; implementation by Eric V. Smith and Barry Warsaw

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

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.)
  • 1 次元配列型での任意のスライスがサポートされています。たとえば負の step を与えて memoryview を逆順に並べ替えることが O(1) オーダで出来るようになりました。

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

参考

PEP 3118 - Revising the Buffer Protocol

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

Unicode 文字列型が、複数の内部表現 (1、2 または 4 バイトで表現される Unicode 序数(ordinal) の最大値依存) を、表現される文字列内でサポートするように変更されました (訳注: 以前までは Python のビルド時に固定で決めていました)。このことは全てのシステムにおいて、一般のケースでは空間効率の良い表現をしながらも UCS-4 へのフルアクセスを与えます。既存の API との互換性のために複数の表現が並行で存在することになりますが、徐々にこの互換性はなくされていくはずです。

Python 側にはこの変更による不都合は何もないはずです。

C API 側では PEP 393 は完全に後方互換です。レガシーな API は最低 5 年は残されるはずです。レガシー API を使うアプリケーションはメモリ削減の効能が完全には得られないか、あるいは最悪の場合には少し余計なメモリを使うかもしれません。これは Python がそれぞれの文字列の二つのバージョン (レガシーなフォーマットと新しい効率的な格納方法) を維持する必要があるかもしれないからです

機能性

PEP 393 でなされた変更は以下の通りです:

  • 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)。
  • ./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 - 文字列の柔軟な表現 (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.)

参考

PEP 397 - 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 - 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 - サブジェネレータへの委譲構文
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 - 例外コンテクストの抑制
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 - 明示的なユニコードリテラル
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 - クラスと関数の正規名 (qualified name)
PEP written and implemented by Antoine Pitrou.

PEP 412: キー共有辞書

オブジェクト属性を記憶するのに使われる辞書が、内部記憶域の一部 (キーとそれに対応するハッシュ値) を互いに共有出来るようになりました。これにより、組み込みでない型のインスタンスをたくさん作るプログラムのメモリ消費が少なくなります。

参考

PEP 412 - キー共有辞書
PEP written and implemented by Mark Shannon.

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

新たに追加された関数 inspect.signature() は、Python 呼び出し可能オブジェクト (callable) を調べることを簡単で直接的なものにしてくれます。幅広い callable をサポートしています:デコレートされているかどうかによらず関数、クラス、 functools.partial() オブジェクト。新たに追加されたクラス群 inspect.Signature, inspect.Parameter, inspect.BoundArguments は、アノテーション、デフォルト値、パラメータの種類、束縛されている引数などのような呼び出しシグニチャについての情報を保持し、これによって、デコレータを書いたりあるいは呼び出しシグニチャや引数を検証したり改訂したりするコードを書くことが、非常に単純になります。

参考

PEP 362: - 関数シグニチャオブジェクト
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 をサポートするために importlib により使われます。組み込みのインポートシステムのために importlib を使う全ての Python 実装が、モジュールのキャッシュの振る舞いを制御するのに cache_tag を利用できます。

SimpleNamespace

sys.implementation の実現に伴って Python に新たな型 types.SimpleNamespace が導入されることとなりました。 dict のようなマッピングベースの名前空間とは対照的に、 SimpleNamespace は object のような属性ベースです。ですが object とは違って SimpleNamespace インスタンスは書き込み可能です。つまり普通の属性アクセスを通じて名前空間に追加したり削除したり修正したりできます。

参考

PEP 421 - sys.implementation の追加
PEP written and implemented by Eric Snow.

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

bpo-2377 [Replace __import__ w/ importlib.__import__ (__import__ を importlib.__import__ で置き換える)]、 bpo-13959 [Re-implement parts of imp in pure Python (imp の一部をピュア Python で再実装する)]、 bpo-14605 [Make import machinery explicit (インポート機構を明示的なものにする)]、 bpo-14646 [Require loaders set __loader__ and __package__ (ローダーが __loader__ と __package__ をセットするのを必須とする)]。

__import__() 関数を importlib.__import__() によって実現するようにしました。これは PEP 302 の「第二段階」を完了させるものです。この変更には複数の恩恵があります。まず最初にこれはインポートの機構を、C コードの奥深くで暗黙に秘密裏に行うのではなく、より透明化します。このことで、Python 3.3 をサポートする全ての Python VM で単一の実装を用いることが出来るようになり、インポートのセマンティクスにおける VM 固有の逸脱と決別する助けともなります。そしてこれはインポート機構の保守をより容易とし、将来起こりうる進化を促します。

一般のユーザにとっては、セマンティクスにおいて目に見える変化はないはずです。今時点でインポートを操作したりインポート呼び出しをプログラム的に行っている場合は、このドキュメントの Python コードの移植 でカバーしているコードの修正が必要になるかもしれません。

新たな API

この変更による一番大きな恩恵の一つは、インポート文の動作に何が介在するのかについて露になったことです。つまりかつては様々なインポータが暗黙で行っていたことが、今では完全に importlib パッケージの一部として公開されています。

importlib.abc で定義される抽象基底クラスは meta path finder と path entry finder の差異を正確に表現するように拡張されて、それぞれ順に importlib.abc.MetaPathFinder と importlib.abc.PathEntryFinder が導入されました。古い ABC である importlib.abc.Finder は後方互換性のためだけに残されますが、何かのメソッドの必要性を強制したりはしません。

ファインダ (finder) の側面からは、 importlib.machinery.FileFinder がモジュールのソースファイルおよびバイトコードファイルの検索に使われる機構を公開しています。以前はこのクラスは sys.path_hooks の暗黙のメンバでした。

ローダ (loader) については、新規の抽象基底クラス importlib.abc.FileLoader が、モジュールのコードを格納する機構としてのファイルシステムを使うローダを書く助けとなります。ソースファイルのローダ (importlib.machinery.SourceFileLoader)、ソースを持たないバイトコードのためのローダ (importlib.machinery.SourcelessFileLoader)、そして拡張モジュールのためのローダ (importlib.machinery.ExtensionFileLoader) が今では直接的に利用出来ます。

ImportError には属性 name と path が追加されて、これには提供すべき関連データがある場合にセットされます。インポート失敗時のメッセージも、これまでのようにモジュール名の末尾だけを与えるのではなく、モジュールの完全名を提供するようになりました。

importlib.invalidate_caches() 関数が sys.path_importer_cache 内にキャッシュされている全てのファインダの同名メソッドを呼び出すようになりました。これにより必要に応じて記憶されている状態をクリーンアップ出来ます。

目に見える変化

潜在的に必要となるかもしれないコード修正については、 Python コードの移植 セクションを参照してください。

importlib によって公開されるものが拡がったことによる、インポートについてのほかの目に見える変化があります。最大の変化は sys.meta_path と sys.path_hooks が、インポートで使われる meta path finder と path entry hook の全てを格納するようになったことです。以前はファインダは直接的に公開されるのではなく、インポートの C コード内に暗黙のものとして隠されていました。このことによって、今では望めば要件に合うようファインダを取り除いたり順序を変えたりといったことが簡単に行えるようになっています。

もう一つの変化は、モジュール生成時に使われたローダを格納する __loader__ 属性を、全てのモジュールが持つようになったことです。 PEP 302 はローダの実装においてこの属性をセットすることを必須とするよう更新されました。ですので今後サードパーティのローダが更新されれば、この属性の存在に依存出来るようになります。ですがそのときが来るまでは、インポート処理がモジュールのロードの後処理としてセットします。

さらにローダが PEP 366 よりの __package__ 属性を設定することも期待出来るようになりました。繰り返しになりますがインポート処理自身が既にこれを全てのローダで importlib より行っていて、また、インポート処理自身がこの属性をロードの後処理としてセットしています。

sys.path_hooks にファインダが見つからない場合に、 sys.path_importer_cache に None が挿入されるようになりました。 imp.NullImporter は sys.path_hooks に直接的に公開されないため、これはファインダが見つからないことの表現値としては当てにならないものになりました。

全てのほかの変更は、Python 3.3 へのコードの更新の際に考慮すべきセマンティクスの変更に関係しています。ですのでそららについて、このドキュメントの Python コードの移植 セクションを読むべきです。

(Implementation by Brett Cannon)

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

  • Unicode name aliases と named sequences のサポートが追加されました。 unicodedata.lookup() と '\N{...}' の両方が name aliases の解決を行い、 unicodedata.lookup() は named sequences の解決も行います。

    (Contributed by Ezio Melotti in bpo-12753.)

  • Unicode データベースを UCD バージョン 6.1.0 にアップグレードしました。

  • range() オブジェクトどうしの等値性比較が、それぞれの range オブジェクトによって生成されるシーケンスの等値性を反映して行われるようになりました (bpo-13201)。

  • bytes と bytearray オブジェクトのメソッド count(), find(), rfind(), index(), rindex() が、第一引数に 0 から 255 の整数を受け付けるようになりました。

    (Contributed by Petri Lehtinen in bpo-12170.)

  • bytes と bytearray オブジェクトのメソッド rjust(), ljust(), center() が、 fill 引数として bytearray を受け付けるようになりました (Contributed by Petri Lehtinen in bpo-12380.)。

  • list と bytearray に新規メソッド copy(), clear() が追加されました (bpo-10516)。これに伴い MutableSequence にも clear() メソッドが追加されました (bpo-11388)。

  • raw bytes リテラルとして br"..." だけでなく rb"..." とも書けるようになりました。

    (Contributed by Antoine Pitrou in bpo-13748.)

  • dict.setdefault() が与えられたキーのルックアップを一度しか行わないようになったので、組み込み型でのこれの使用はアトミックになります。(訳注: 外部観察可能な変化で説明すると、以前はこの呼び出しが、キーの2回の __hash__、__eq__ 呼び出しを引き起こしていたものが、1回になった。)

    (Contributed by Filip Gruszczyński in bpo-13521.)

  • 関数呼び出しが関数シグニチャに合致しない場合のエラーメッセージがかなり改善されました。

    (Contributed by Benjamin Peterson.)

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

以前のバージョンの CPython では、常に大域的なインポートロックを当てにしていました。このことは意図せず頭痛の種を持ち込むこと繋がっていました。たとえば、モジュールをインポートすることで副作用として異なるスレッドでのコード実行を引き起こす際に起こる、デッドロックといったことです。不恰好な回避策がときどき採用されてきました。C API 関数 PyImport_ImportModuleNoBlock() などです。

Python 3.3 ではモジュールのインポートでは、モジュール単位でのロックを採用しています。このことによって複数スレッドからの指定モジュールのインポートは (モジュールが不完全な初期化のまま曝されるのを防いで) 正しく直列化されて、前述の頭痛の種は取り除かれています。

(Contributed by Antoine Pitrou in bpo-9260.)

組み込みの関数と型

  • open() に新規パラメータ opener が追加されました。背後のファイルオブジェクトのファイル記述子は opener を (file, flags) で呼び出して得られます。これは例えば os.O_CLOEXEC のようなカスタムなフラグを用いるのに使えます。 / 'x' モードが追加されました。排他的作成として開きます。ファイルが既存の場合は失敗します。
  • print(): flush キーワード引数が追加されました。flush キーワード引数が真の場合ストリームは強制的にフラッシュされます。
  • hash(): ハッシュのランダム化がデフォルトで有効になりました。 object.__hash__() と環境変数 PYTHONHASHSEED を参照してください。
  • str 型に casefold() メソッドが追加されました。文字列の casefold されたコピーを返します。casefold された文字列は、大文字小文字に関係ないマッチに使えます。例えば 'ß'.casefold() は 'ss' を返します。
  • シーケンスについてのドキュメントを大幅に書き換えました。バイナリのシーケンスとテキストのシーケンスについての区別についてより良い説明を加え、また、個々の組み込みシーケンスに関して個別のドキュメントを提供しています (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.)

lzma

新たに追加された lzma モジュールは LZMA アルゴリズムを用いたデータの圧縮と解凍を提供します。.xz および .lzma ファイル形式もサポートされています。

(Contributed by Nadeem Vawda and Per Øyvind Karlsen in 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.)

abc.ABCMeta.register() が登録されたサブクラスを返すようになりました。つまりクラスデコレータとして使うことができるようになったということです (bpo-10868)。

array

array モジュールに型コード q と Q による long long 型サポートが追加されました。

(Contributed by Oren Tirosh and Hirokazu Yamamoto in bpo-1172711.)

base64

base64 モジュールのモダンなインターフェイスのほうのデコード関数が、ASCII 文字のみで構成された Unicode 文字列を受け付けるようになりました。たとえば base64.b64decode('YWJj') は b'abc' を返します。 (Contributed by Catalin Iacob in bpo-13641.)

binascii

a2b_ 関数が、バイナリオブジェクトだけでなく ASCII 文字のみで構成された Unicode 文字列を入力として受け付けるようになりました。 (Contributed by Antoine Pitrou in bpo-13637.)

bz2

bz2 モジュールが最初から書き直されました。その過程で新機能がいくつか追加されました。

  • 新たな bz2.open() 関数: bzip2 で圧縮されたファイルをバイナリかテキストモードで開きます。

  • bz2.BZ2File が、コンストラクタの fileobj 引数で、任意のファイル様オブジェクトの読み書きが出来るようになりました。

    (Contributed by Nadeem Vawda in bpo-5863.)

  • bz2.BZ2File と bz2.decompress() が (pbzip2 ツールで生成されたような) マルチストリームの入力を展開出来るようになりました。同時に bz2.BZ2File は、 'a' (追記) モードを使ってこのタイプの圧縮ファイルを作るのに使えるようになりました。

    (Contributed by Nir Aides in bpo-1625.)

  • bz2.BZ2File が、 io.BufferedIOBase API で規定されているメソッドや属性のうち、 detach() と truncate() を除くすべてを実装するようになりました。

codecs

mbcs コーデックが、全ての Windows バージョンでエラーハンドラ replace と ignore を正しく処理するように書き換えられました。 mbcs コーデックは以前は、エンコードでは replace のみ、デコードでは ignore のみでしたが、これにより全てのエラーハンドラがサポートされます。

新たに Windows のみ用のコーデック cp65001 が追加されました (bpo-13216)。これは Windows コードページ 65001 (Windows UTF-8, CP_UTF8) です。例えばこれはコンソール出力のコードページが (例えば chcp 65001 コマンドを使って) cp65001 にセットされている場合に sys.stdout で使われます。

マルチバイト CJK デコーダの再同期が高速になりました。これは不正なバイトシーケンスが最初のバイトであれば無視するだけです。例えば b'\xff\n'.decode('gb2312', 'replace') は文字置き換えののちに \n を返すようになっています。

(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)

unicode_internal コーデックは非推奨となりました。

collections

新たに追加されたクラス ChainMap は、複数のマッピングをひとまとまりに扱えるようにします。 (Written by Raymond Hettinger for bpo-11089, made public in bpo-11297.)

抽象基底クラス群は新しいモジュール collections.abc に移動しました。抽象コレクションと具象コレクションを識別しやすくするためです。これをインポートしている既存のコードを維持するために、 ABC の別名群が collections モジュール内に残されています。 (bpo-11085)

Counter クラスが、単項 + 演算子、単項 - 演算子、インプレイス演算子の +=, -=, |=, &= をサポートするようになりました。(Contributed by Raymond Hettinger in bpo-13121.)

contextlib

コンテキストマネージャをプログラム的に操作することと、これと類似のクリーンアップの機能性について、ExitStack が今後は確かな基礎を提供します。かつての (非推奨となり削除された) contextlib.nested API とは違って、この新しい API は、コンテキストマネージャがリソースを (たとえばファイルオブジェクトなどを) __init__ メソッドで獲得したのか、あるいは (たとえば threading モジュールからの同期オブジェクトを) __enter__ メソッドで獲得したのかとは無関係に正しく動作するように設計されました。

(bpo-13585)

crypt

crypt モジュールに、 salt として使う追加の crypt フォーマット (ハッシュ化メソッド) と mksalt() 関数が追加されました。

(bpo-10924)

curses

  • curses モジュールが ncursesw ライブラリとリンクしている場合に、 Unicode 文字列や Unicode 文字が渡されれば Unicode 関数 (例えば waddwstr())、それ以外の場合はバイト列用関数 (例えば waddstr()) を呼び出すようにしました。
  • Unicode 文字列をエンコードするのに utf-8 ではなく locale のエンコーディングを使うようになりました。(---訳注: 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.) (---訳注: 最初の2つはおそらく bpo-12567 --)

datetime

  • naive な datetime インスタンスと aware な datetime インスタンスの等価比較で、 TypeError を投げずに False を返すようになりました。 (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 - decimal 算術演算の、高速なネイティブ 実装の統合
C-module and libmpdec written by Stefan Krah.

decimal モジュールの新しい C バージョンは高速な libmpdec と統合します。それは任意精度で正しい丸めを行う 10 進浮動小数点数算術演算を行います。libmpdec は IBM の「General Decimal Arithmetic Specification」に従っています。

性能向上は、データベースアプリケーションで 10 倍から、数値計算が中心的なアプリケーションで 100 倍まで幅があります。この数字は、 10進数の浮動小数点計算において使われる標準的な精度における期待値です。精度はユーザが変更可能なので、正確な数字は変わる可能性があります。例えば、整数 bignum 計算では、違いはかなりより大きくなるかもしれません。

以下の表は説明のためのものです。ベンチマークは http://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 の混合の厳密なセマンティクスを有効に出来ます。(---訳注: 使用例が クイックスタートチュートリアル にあります。---)
  • Python がスレッド無しでコンパイルされている場合、C 版は自動的にコストがかかるスレッドローカルなコンテキスト機構を使用不可にします。この場合、 HAVE_THREADS が False にセットされます。

API の変更

  • C モジュールはマシンアーキテクチャに依存する以下のコンテキストの制限を持ちます:

    32-bit | 64-bit
    MAX_PREC | 425000000 | 999999999999999999
    MAX_EMAX | 425000000 | 999999999999999999
    MIN_EMIN | -425000000 | -999999999999999999

  • コンテキストの雛形 (DefaultContext, BasicContext, ExtendedContext) では Emax と Emin の絶対値が 999999 に変更されました。

  • decimal.py の Decimal コンストラクタは上記のコンテキスト制限に無知で、任意の指数や精度で正確に変換しようとします。C 版は内部の制限を持っていますので、次の規則が使われます: 可能ならば値は正確に変換され、そうでない場合 InvalidOperation が送出されて結果が NaN となります。後者のケースは丸めあるいは不正確な値を得るために create_decimal() を使うことでいつでも可能です。(---訳注: わかりにくい表現ですがコンテキストで InvalidOperation をトラップしていれば結果が NaN で受け取れて(そうでなければ InvalidOperation が投げられて)、その制御は create_decimal で明示的に行える、ということを言っています。---)

  • decimal.py の power() 関数は「always correctly-rounded (必ず適切に丸められる)」です。C 版ではこれの意味は関数 exp() と ln() に関してであり、最終的な結果においては「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.)
  • FTP_TLS クラスに、制御チャネルを平文に戻すための ccc() 関数が追加されました。これは、固定ポートで開くことなく非セキュア FTP で NAT を処理する方法を知っているファイアウォールを利用するのに有用となりえます。(Contributed by Giampaolo Rodolà in bpo-12139.)
  • 新規メソッド ftplib.FTP.mlsd() は機械で読めるディレクトリリスティングのフォーマットを提供し、 ftplib.FTP.nlst() と ftplib.FTP.dir() に取って代わるものとなりました。(Contributed by Giampaolo Rodolà in bpo-11072.)

functools

functools.lru_cache() デコレータにキーワード引数 typed を指定出来るようになりました (デフォルトは False です)。これは異なった型の等値比較のキャッシュ値を別々のキャッシュスロットに置くかどうかを決めます。(Contributed by Raymond Hettinger in bpo-13227.)

gc

ガーベージコレクタが回収前後に呼び出すコールバックを登録出来るようになりました。新規属性 callbacks リストに登録します。

hmac

タイミング解析によるダイジェストに対する サイドチャンネル攻撃 からの防御のために、 compare_digest() 関数が追加されました。(Contributed by Nick Coghlan and Christian Heimes in bpo-15061.)

http

http.server.BaseHTTPRequestHandler がヘッダをバッファするようになり、 end_headers() 呼び出し時に一度に全てをまとめて書き出すようになりました。新規のメソッド flush_headers() は、集積したヘッダを送信する場合の管理に直接使うことが出来ます。(Contributed by Andrew Schaaf in bpo-3709.)

http.server が正当な HTML 4.01 strict 出力を生成するようになりました。 (Contributed by Ezio Melotti in bpo-13295.)

http.client.HTTPResponse にメソッド readinto() が追加されました。つまりこのクラスを io.RawIOBase のように扱えるということです。 (Contributed by John Kuhn in bpo-13464.)

html

html.parser.HTMLParser が壊れたマークアップをエラーなしで解析出来るようになりました。これによりコンストラクタの strict 引数と HTMLParseError 例外が撤廃されました。この壊れたマークアップを解析出来る能力は数多くのバグフィックスからの結果であり、それらは Python 2.7/3.2 の最新バグフィックスリリースでも利用可能です。(Contributed by Ezio Melotti in bpo-15114, and bpo-14538, bpo-13993, bpo-13960, bpo-13358, bpo-1745761, bpo-755670, bpo-13357, bpo-12629, bpo-1200313, bpo-670664, bpo-13273, bpo-12888, bpo-7311.)

html.entities モジュールに、HTML5 名前付き文字参照と Unicode 文字(列) とを対応付ける html5 辞書が追加されました (例: html5['gt;'] == '>')。この辞書は既に HTMLParser が使っています。 (Contributed by Ezio Melotti in bpo-11113 and bpo-15156.)

imaplib

IMAP4_SSL コンストラクタが SSLContext パラメータを受け取るようになりました。これはセキュアなチャネルのパラメータを制御します。

(Contributed by Sijin Joseph in bpo-8808.)

inspect

getclosurevars() 関数が追加されました。この関数は、指定した関数の関数本体から参照されている現在束縛されている全ての名前と、それら名前が解決された場所 (訳注: globals, builtins など) を報告します。これにより、ステートフルなクロージャに依存するコードをテストするのに、正しい内部状態を検証するのが容易になります。

(Contributed by Meador Inge and Nick Coghlan in bpo-13062.)

getgeneratorlocals() 関数が追加されました。この関数は、指定したジェネレータのスタックフレーム内のローカル変数の、現在束縛されているものを報告します。これにより、ジェネレータをテストするのに、正しい内部状態を検証するのが容易になります。

(Contributed by Meador Inge in bpo-15153.)

io

open() 関数に排他的作成に使用する新たな 'x' モードが追加されました。ファイルが既に存在する場合は FileExistsError を送出します。 C11 fopen() の 'x' モードに基づいています。

(Contributed by David Townshend in 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.)

mmap

read() メソッドの他のファイルライクなオブジェクトとの互換性が増しました。引数が省略されるか None の場合に、ファイルの現在位置からマッピングの末尾までのバイト列を返すようになっています。(Contributed by Petri Lehtinen in bpo-12021.)

multiprocessing

関数 multiprocessing.connection.wait() が追加されました。これは複数の (接続やソケット、パイプのような) オブジェクトをタイムアウト付きでポーリングします。(Contributed by Richard Oudkerk in bpo-12328.)

プロセス間で　(訳注: Connection.send() と Connection.recv() で) multiprocessing.Connection オブジェクトを相互に転送出来るようになりました。 (Contributed by Richard Oudkerk in bpo-4892.)

multiprocessing.Process がキーワード引数 daemon を取るようになりました。これは親プロセスから daemon フラグを継承するデフォルトの振る舞いをオーバライドします (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.)

nntplib

nntplib.NNTP クラスがコンテキスト管理プロトコルをサポートするようになりました。with ブロックを抜ける際に無条件に NNTP 接続をクローズします (クローズ処理で発生する socket.error は無視されます)。:

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

os

  • os モジュールに pipe2() 関数が追加されました。これはフラグ O_CLOEXEC と O_NONBLOCK を (論理和指定で) セットしたパイプをアトミックに作ることが出来ます。これはマルチスレッドプログラムでの競合状態を避けるために特に有用です。

  • os モジュールに sendfile() 関数が追加されました。これはあるファイル (またはソケット) 記述子からのコピーを、効率的な「ゼロコピー」で行います。「ゼロコピー」という言い回しは、これは二つの記述子間でのデータのコピー全てが完全にカーネルによって行われる、という事実について指しています。データコピーにユーザ空間のバッファは使われません。 sendfile() は例えばファイルのダウンロードのような、ディスク上のファイルとネットワークソケット間での効率的なデータコピーに使うことが出来ます。

    (Patch submitted by Ross Lagerwall and Giampaolo Rodolà in bpo-10882.)

  • シンボリックリンク攻撃や一時ファイル、一時ディレクトリにまつわる問題のような競合状態を避けるには、ファイル名の代わりにファイル記述子を操作することがより信頼出来ます (そして高速でもあります)。 Python 3.3 はファイル記述子で動作するよう既存関数の強化と新規関数の追加を行ないました。 (bpo-4761, bpo-10755 and 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.)

  • 新規関数 os.replace() は変更先の上書きにおいてクロスプラットフォームな方法でファイル名変更を行えます。既存の os.rename() では、変更先が既存のファイルの場合に POSIX では上書き、Windows ではエラーとなります。(Contributed by Antoine Pitrou in bpo-8828.)

  • stat 系関数 (stat(), fstat(), lstat()) がファイルのタイムスタンプのナノ秒精度を読み取れるようになりました。これと対となる utime() もファイルのタイムスタンプをナノ秒精度で書き出せるようになりました。 (Contributed by Larry Hastings in bpo-14127.)

  • 新規関数 os.get_terminal_size() はファイル記述子が接続しているターミナルウィンドウのサイズを取得します。 shutil.get_terminal_size() も参照して下さい。 (Contributed by Zbigniew Jędrzejewski-Szmek in bpo-13609.)

  • Linux 拡張属性をサポートするための新たな関数 (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): 指定したユーザが属するグループ ID のリストを返します。
  • times() および uname(): 戻り値の型がタプルから属性名のついたタプルライクオブジェクトに変更されました。
  • いくつかのプラットフォームにおいて、 lseek() 関数で使う追加の定数をサポートするようになりました。 os.SEEK_HOLE や os.SEEK_DATA などです。
  • 新規の定数 RTLD_LAZY, RTLD_NOW, RTLD_GLOBAL, RTLD_LOCAL, RTLD_NODELETE, RTLD_NOLOAD, RTLD_DEEPBIND が、それをサポートしているプラットフォームで利用可能になりました。これらは sys.setdlopenflags() 関数で使います。これら定数は ctypes モジュールと DLFCN で定義されている同じような定数を置き換えるものです。(Contributed by Victor Stinner in bpo-13226.)
  • クロスプラットフォームのサポートを簡単にするために、非 Windows 環境でも os.symlink() がキーワード引数 target_is_directory を受け付けるようになりました (単に無視します)。

pdb

Tab キーでの補完がコマンド名だけでなくその引数に対しても使えるようになりました。例えば break コマンドに対しては、関数、ファイル名が補完されます。

(Contributed by Georg Brandl in bpo-14210)

pickle

pickle.Pickler オブジェクトに pickler ごとのリダクション関数を設定する、オプショナルな dispatch_table 属性が追加されました。

(Contributed by Richard Oudkerk in bpo-14166.)

pydoc

Tk GUI と serve() 関数は pydoc モジュールから削除されました。 pydoc -g と serve() は Python 3.2 から既に非推奨となっていました。

re

str 正規表現が \u および \U エスケープをサポートしました。

(Contributed by Serhiy Storchaka in bpo-3665.)

sched

  • run() が blocking パラメータを取るようになりました。 これを偽にセットすると、このメソッドは既に実行予定時間になっているイベント (もしあれば) を実行してすぐに戻ります。 これは scheduler を非ブロッキングなアプリケーションで使いたい場合に有用です。 (Contributed by Giampaolo Rodolà in bpo-13449.) (---訳注: 原文の表現がわかりにくいですが、これは blocking=False 時はスケジュールされた時間になっているタスクがあれば通常は delayfunc を呼び出すところをそうせずに、一番早く次の予定時間に達するタスクの予定時間までの時間差を返します。---)
  • scheduler クラスをマルチスレッド環境で安全に使えるようになりました。 (Contributed by Josiah Carlson and Giampaolo Rodolà in bpo-8684.)
  • scheduler クラスのコンストラクタでのパラメータ timefunc と delayfunc が省略可能になりました。それぞれデフォルトで順に time.time(), time.sleep() が使われます。 (Contributed by Chris Clark in bpo-13245.)
  • enter() と enterabs() の argument パラメータが省略可能になりました。 (Contributed by Chris Clark in bpo-13245.)
  • enter() と enterabs() が kwargs パラメータを受け付けるようになりました。 (Contributed by Chris Clark in bpo-13245.)

select

Solaris とその派生プラットフォームにおいて、新規クラス select.devpoll が追加されました。これはハイパフォーマンスな非同期ソケットを /dev/poll 経由で提供するものです。 (Contributed by Jesús Cea Avión in bpo-6397.)

shlex

これまで pipes モジュールにいて文書化もされてこなかったヘルパー関数 quote が、 shlex に移動の上で文書化されました。この quote() は、文字列内でシェルによって何か特別な意味を与えられている全ての文字を適切にエスケープします。

shutil

  • 新たな関数:
    • disk_usage(): ディスクの利用状況について、トータル、使用中、空きの容量を返します。 (Contributed by Giampaolo Rodolà in bpo-12442.)
    • chown(): 指定された path のユーザ、グループの両方あるいは一方を変更します。ユーザ、グループは名前もしくは数値での ID (uid, gid) で指定します。(Contributed by Sandro Tosi in bpo-12191.)
    • shutil.get_terminal_size(): インタプリタが接続しているターミナルウィンドウのサイズを取得します。 (Contributed by Zbigniew Jędrzejewski-Szmek in bpo-13609.)
  • copy2() と copystat() がファイルのタイムスタンプを、それをサポートするプラットフォームではナノ秒精度も維持するようになりました。また、Linux ではこれらは「拡張属性 (extended attributes)」もコピーするようになりました。 (Contributed by Larry Hastings in bpo-14127 and bpo-15238.)
  • いくつかの関数がオプショナルな symlinks 引数を取るようになりました。これが真の場合、シンボリックリンクの指す先を解決するのではなくシンボリックそのものに対しての操作をします (そうすることが必要であればシンボリックリンク作成もします)。(Contributed by Hynek Schlawack in bpo-12715.)
  • ファイルシステムをまたがったファイルのコピーの際に、 move() がシンボリックリンクを POSIX の move コマンドが行うのと同じやり方で扱うようになりました。つまりターゲットのファイルの中身をコピーするのではなくシンボリックリンクを再作成します。(Contributed by Jonathan Niehof in bpo-9993.) また、 move() は dst 引数を戻り値として返すようになりました。
  • os.open() と os.unlink() が新パラメータ dir_fd をサポートしているプラットフォームでは、 rmtree() は今では シンボリックリンク攻撃に耐性を持ちます。 (Contributed by Martin von Löwis and Hynek Schlawack in bpo-4489.)

signal

  • signal モジュールに新規関数が追加されました:
    • pthread_sigmask(): これを呼び出すスレッドにセットされているシグナルマスクを取り出したり変更したりします (Contributed by Jean-Paul Calderone in bpo-8407);
    • pthread_kill(): スレッドにシグナルを送ります;
    • sigpending(): 保留中のシグナルを調べます;
    • sigwait(): シグナルを待ちます;
    • sigwaitinfo(): シグナルを待ちますが、それについての詳細情報を返します;
    • sigtimedwait(): sigwaitinfo() と似ていますがタイムアウト指定できます。
  • シグナルハンドラは wakeup ファイル記述子に以前は \0 を書き込んでいましたが、シグナル番号を 1 バイト整数として書き込むようにしました。これにより、一つ以上のシグナルを待った上でどのシグナルが発生したのかあとから調べるといったことが出来ます。
  • signal.signal() と signal.siginterrupt() は RuntimeError ではなく OSError を投げるようになりました: OSError は errno 属性を持っています。

smtpd

smtpd モジュールが RFC 5321 (extended SMTP) と RFC 1870 (size extension) をサポートするようになりました。標準により、これら拡張を有効にするための必要十分条件はクライアントがセッションを EHLO コマンドで開始することです。

(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)

smtplib

クラス SMTP, SMTP_SSL, LMTP に新しいキーワード引数 source_address が追加されました。 (host, port) の形で指定し、これは外に向かうソケットを作成する際に bind() 呼び出し内でのソースアドレスとして用いられます。(Contributed by Paulo Scardine in bpo-11281.)

SMTP がコンテキスト管理プロトコルをサポートするようになったので SMTP のインスタンスを with 文で使えます。 (Contributed by Giampaolo Rodolà in bpo-11289.)

SMTP_SSL コンストラクタと starttls() メソッドが SSLContext パラメータを受け取るようになりました。これはセキュアなチャネルのパラメータを制御します。 (Contributed by Kasun Herath in bpo-8809.)

socket

  • socket クラスが、前提となるプラットフォームがサポートしていれば従属的なデータを処理する追加のメソッドを公開しました:

    • sendmsg()
    • recvmsg()
    • recvmsg_into()

    (Contributed by David Watson in 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.)

  • socket クラスが PF_RDS プロトコルファミリ (https://en.wikipedia.org/wiki/Reliable_Datagram_Sockets および https://oss.oracle.com/projects/rds/) をサポートするようになりました。

  • socket クラスが OS X で PF_SYSTEM プロトコルファミリをサポートするようになりました。 (Contributed by Michael Goderbauer in bpo-13777.)

  • Unix システムにおいて新規関数 sethostname() により、呼び出しプロセスが十分な特権を持っていればホスト名をセット出来ます。(Contributed by Ross Lagerwall in bpo-10866.)

socketserver

BaseServer がオーバライド可能な service_actions() メソッドを持つようになり、これは serve_forever() によりサービスループ内で呼び出されます。 ForkingMixIn がこれをゾンビ化した子プロセスのクリーンアップに使っています。 (Contributed by Justin Warkentin in bpo-11109.)

sqlite3

sqlite3.Connection の新規のメソッド set_trace_callback() を使うと sqlite3 により処理されるすべての sql コマンドの足跡 (トレース) をキャプチャ出来ます。(Contributed by Torsten Landschoff in bpo-11688.)

ssl

  • ssl モジュールに新たに 2 つの乱数生成関数が追加されました:

    • RAND_bytes(): 暗号学的に強固な擬似乱数バイト列を生成します。
    • RAND_pseudo_bytes(): 擬似乱数バイト列を生成します。

    (Contributed by Victor Stinner in bpo-12049.)

  • ssl モジュールがより粒度の細かい例外階層を公開するようになり、これにより様々な種類のエラーを調べることが容易になります。 (Contributed by Antoine Pitrou in bpo-11183.)

  • load_cert_chain() が password 引数を受け付けるようになりました。これは秘密鍵が暗号化されている場合に使われます。 (Contributed by Adam Simpkins in bpo-12803.)

  • ディフィー・ヘルマン鍵共有の、通常のものと楕円曲線ベースのもの両方が load_dh_params() メソッドと set_ecdh_curve() メソッドを通じてサポートされるようになりました。(Contributed by Antoine Pitrou in bpo-13626 and bpo-13627.)

  • SSL ソケットに新規メソッド get_channel_binding() が追加されました。これは SCRAM-SHA-1-PLUS (訳注: RFC 5802 など参照) のようなある種の認証メカニズムの実装で拡張されることを想定したものです。(Contributed by Jacek Konieczny in bpo-12551.)

  • compression() メソッドが追加されたので、SSL ソケットで使われている SSL 圧縮アルゴリズムを問い合わせることが出来ます。また、新規の属性 OP_NO_COMPRESSION で圧縮を無効に出来ます。(Contributed by Antoine Pitrou in bpo-13634.)

  • ssl.SSLContext.set_npn_protocols() による Next Protocol Negotiation 拡張のサポートが追加されました。 (Contributed by Colin Marc in bpo-14204.)

  • 属性 library と reason が追加されたので、SSL のエラーは以前よりもっと簡単に調べることが出来るようになりました。(Contributed by Antoine Pitrou in bpo-14837.)

  • get_server_certificate() 関数が IPv6 をサポートするようになりました。 (Contributed by Charles-François Natali in bpo-11811.)

  • 新規属性 OP_CIPHER_SERVER_PREFERENCE は SSLv3 サーバソケットに対し、暗号の優先順位をクライアントのものではなくサーバのものを使うようにします。 (bpo-13635)

stat

ドキュメントされていなかった tarfile.filemode 関数が stat.filemode() に移動されました。これはファイルモードを '-rwxrwxrwx' 形式の文字列に変換するのに使えます。

(Contributed by Giampaolo Rodolà in bpo-14807.)

struct

struct モジュールが新たに ssize_t (コード n)、 size_t (コード N) をサポートするようになりました。 (Contributed by Antoine Pitrou in bpo-3163.)

subprocess

POSIX プラットフォームにおいて、コマンド文字列として bytes オブジェクトを渡せるようになりました。 (Contributed by Victor Stinner in bpo-8513.)

新規定数 DEVNULL は、プラットフォームに依存しない方法で出力を抑制するのに使えます。 (Contributed by Ross Lagerwall in bpo-5870.)

sys

sys モジュールに、スレッドの実装に関する情報が格納された 構造体シーケンス を保持する thread_info が追加されました。 (bpo-11223)

tarfile

tarfile が lzma モジュールにより lzma エンコーディングをサポートするようになりました (Contributed by Lars Gustäbel in bpo-5689.)。

tempfile

tempfile.SpooledTemporaryFile の truncate() メソッドが size 引数を受け取るようになりました。 (Contributed by Ryan Kelly in bpo-9957.)

textwrap

textwrap モジュールに indent() が追加されました。これはテキストのブロック内の選択行に共通のプレフィクスを追加する簡単な方法になります。(bpo-13857)

threading

いずれもかつてインスタンスを返すファクトリ関数であった threading.Condition, threading.Semaphore, threading.BoundedSemaphore, threading.Event, threading.Timer がクラスになったので、サブクラス化出来るようになりました。 (Contributed by Éric Araujo in bpo-10968.)

threading.Thread コンストラクタがキーワード引数 daemon を取るようになりました。これは親スレッドから daemon フラグを継承するデフォルトの振る舞いをオーバライドします (bpo-6064)。

かつての非公開関数 _thread.get_ident が公開関数 threading.get_ident() として利用可能となっています。これは標準ライブラリにおいて多数の _thread モジュールへの直接アクセスを取り除く結果になりました。 _thread.get_ident を使っているサードパーティのコードも同じように、新しく公開化されたインターフェイスに乗り換えるべきです。

time

PEP 418 が time モジュールに新たな関数を追加しました:

  • get_clock_info(): クロックの情報を取得します。
  • monotonic(): 単調なクロック (逆行しない)、システムクロックの更新の影響を受けません。
  • perf_counter(): 短期間の計測のために利用可能な最高の解像度を持つパフォーマンスカウンタです。
  • process_time(): 現在のプロセスの system と user CPU 時間の和です。

その他の新たな関数:

  • 関数 clock_getres(), clock_gettime(), clock_settime() と、これに使われる定数群 CLOCK_xxx の追加。 (Contributed by Victor Stinner in bpo-10278.)

クロスプラットフォーム間での一貫性を改善するために、 sleep() が負の値を渡すと ValueError を投げるように変更されています。以前から POSIX システムではエラーでしたが、Windows の場合に無限に sleep していました。

types

新規クラス types.MappingProxyType の追加: 読み出し専用のマッピングのプロキシです。 (bpo-14386)

新規関数 types.new_class() と types.prepare_class() は PEP 3115 準拠の動的な型の生成サポートを提供します。(bpo-14588)

unittest

メソッド assertRaises(), assertRaisesRegex(), assertWarns(), assertWarnsRegex() が、コンテキストマネージャとして使われる際にキーワード引数 msg を受け付けるようになりました。 (Contributed by Ezio Melotti and Winston Ewert in bpo-10775.)

unittest.TestCase.run() が TestResult オブジェクトを返すようになりました。

urllib

Request クラスが get_method() で使われる method 引数を受け付けるようになりました。これはどの HTTP メソッドが使われるべきかを指定します。例えば以下は 'HEAD' リクエストを送信します:

>>> urlopen(Request('https://www.python.org', method='HEAD'))

(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, the latter by Matthias Klose in bpo-14493.)

xml.etree.ElementTree

xml.etree.ElementTree モジュールはデフォルトで C 実装による高速版をインポートするようになりました; もう明示的に xml.etree.cElementTree をインポートする必要はありません (cElementTree モジュールは後方互換のために残されますが非推奨となりました)。また、 Element クラスの iter 系のメソッドに最適化が施されました (C で再実装されました)。また、このモジュールのドキュメントは大幅に改善されて、実例が追加され、さらに詳細なリファレンスになりました。

zlib

新規属性 zlib.Decompress.eof が追加されました。これにより適切に作られたストリームなのか不完全だったり切り捨てられたものなのかを区別することが出来ます。 (Contributed by Nadeem Vawda in bpo-12646.)

新規属性 zlib.ZLIB_RUNTIME_VERSION は実行時にロードされた背後の zlib ライブラリのバージョン文字列です。 (Contributed by Torsten Landschoff in bpo-12306.)

最適化

大きな性能向上がありました:

  • PEP 393 により、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, bpo-14738 and bpo-15026.)

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

Python のビルド過程と C API の変更は以下の通りです:

  • 新しい PEP 3118 関連の関数:
    • PyMemoryView_FromMemory()
  • PEP 393 により追加された新たな 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 列挙型での PyUnicode_KIND: 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)。

非推奨

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

保守する者がいないため OS/2 ならびに VMS はもはやサポートされません。

保守の負担のため WIndows 2000 および COMSPEC を command.com に設定している Windows プラットフォームはもはやサポートされません。

3.2 で非推奨だった OSF のサポートが完全に削除されました。

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

  • object 型そのものの object.__format__() に空でない文字列が渡すことは非推奨となりました。Python 3.4 ではこれは TypeError となります (bpo-9856)。
  • PEP 393 により、 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)。
  • bpo-13374: os モジュールにある Windows のバイト列 API は非推奨となりました。ANSI コードページに依存しないようにしてあらゆるファイル名をサポートするために、バイト列文字列のファイル名ではなく Unicode ファイル名を使ってください。
  • 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 で Py_UNICODE は非推奨になり、Python 4 で削除されます。この型を使用している全ての関数は非推奨です。

型 Py_UNICODE および Py_UNICODE* を使用しているユニコード関数ならびにメソッド:

  • PyUnicode_FromUnicode: PyUnicode_FromWideChar() または PyUnicode_FromKindAndData() を使用してください
  • PyUnicode_AS_UNICODE, PyUnicode_AsUnicode(), PyUnicode_AsUnicodeAndSize(): PyUnicode_AsWideCharString() を使用してください
  • PyUnicode_AS_DATA: PyUnicode_READ および PyUnicode_WRITE とともに PyUnicode_DATA を使用してください
  • PyUnicode_GET_SIZE, PyUnicode_GetSize(): PyUnicode_GET_LENGTH または PyUnicode_GetLength() を使用してください
  • PyUnicode_GET_DATA_SIZE: PyUnicode_GET_LENGTH(str) * PyUnicode_KIND(str) を使用してください (既存の文字列でのみうまくいきます)
  • PyUnicode_AsUnicodeCopy(): PyUnicode_AsUCS4Copy() または PyUnicode_AsWideCharString() を使用してください
  • PyUnicode_GetMax()

Py_UNICODE* 文字列を操作する関数ならびにマクロ:

  • Py_UNICODE_strlen: PyUnicode_GetLength() または PyUnicode_GET_LENGTH を使用してください
  • Py_UNICODE_strcat: PyUnicode_CopyCharacters() または PyUnicode_FromFormat() を使用してください
  • Py_UNICODE_strcpy, Py_UNICODE_strncpy, Py_UNICODE_COPY: PyUnicode_CopyCharacters() または PyUnicode_Substring() を使用してください
  • Py_UNICODE_strcmp: PyUnicode_Compare() を使用してください
  • Py_UNICODE_strncmp: PyUnicode_Tailmatch() を使用してください
  • Py_UNICODE_strchr, Py_UNICODE_strrchr: PyUnicode_FindChar() を使用してください
  • Py_UNICODE_FILL: PyUnicode_Fill() を使用してください
  • Py_UNICODE_MATCH

エンコーダ:

  • PyUnicode_Encode(): PyUnicode_AsEncodedObject() を使用してください
  • PyUnicode_EncodeUTF7()
  • PyUnicode_EncodeUTF8(): PyUnicode_AsUTF8() または PyUnicode_AsUTF8String() を使用してください
  • PyUnicode_EncodeUTF32()
  • PyUnicode_EncodeUTF16()
  • PyUnicode_EncodeUnicodeEscape:() PyUnicode_AsUnicodeEscapeString() を使用してください
  • PyUnicode_EncodeRawUnicodeEscape:() PyUnicode_AsRawUnicodeEscapeString() を使用してください
  • PyUnicode_EncodeLatin1(): PyUnicode_AsLatin1String() を使用してください
  • PyUnicode_EncodeASCII(): PyUnicode_AsASCIIString() を使用してください
  • PyUnicode_EncodeCharmap()
  • PyUnicode_TranslateCharmap()
  • PyUnicode_EncodeMBCS(): (CP_ACP code_page とともに) PyUnicode_AsMBCSString() または PyUnicode_EncodeCodePage() を使用してください
  • PyUnicode_EncodeDecimal(), PyUnicode_TransformDecimalToASCII()

非推奨の機能

array モジュールの 'u' 書式化コードは非推奨となりました。Python 4 ではほかの (Py_UNICODE) API と一緒に削除されるでしょう。

Python 3.3 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

Python コードの移植

  • ハッシュのランダム化がデフォルトで有効になりました。これを無効にするには環境変数 PYTHONHASHSEED を 0 にセットして下さい。 object.__hash__() メソッドも参照して下さい。
  • bpo-12326: Linux では、 sys.platform はもはやメジャーバージョン番号を含みません。 これは今では常に 'linux' です。以前はこれは Python のビルドに使われた Linux バージョンに依存した 'linux2' や 'linux3' でした。 sys.platform == 'linux2' などとするのではなく、 sys.platform.startswith('linux') とするか、古い Python バージョンのサポートが不要であれば直接的に sys.platform == 'linux' として下さい。
  • bpo-13847, bpo-14180: time および datetime: タイムスタンプが範囲外の場合に、 ValueError ではなく OverflowError を送出するようになりました。また、C 関数の gmtime() あるいは localtime() が失敗した場合には OSError を送出するようになりました。
  • インポートで使われるデフォルトのファインダが、特定のディレクトリに何が含まれるのかについてのキャッシュを利用するようになっています。実行中に Python ソースファイルやバイトコードファイルを作ったら、キャッシュをクリアしてファインダが新しく作られたファイルに気付けるように、 importlib.invalidate_caches() を呼ぶ必要があることに注意してください。
  • ImportError がインポートを試みたモジュール名として完全名を使うようになっています。ImportError のメッセージをチェックする doctest は、モジュール名をその末尾の名前ではなく完全な名前を使うように更新する必要があります。
  • __import__() の引数 index のデフォルトが -1 ではなく 0 となり、また、もはや負の値はサポートされません。デフォルト値が -1 で残されたのは(訳注: つまり絶対、相対インポートの両方を試みるようにしたのは) PEP 328 を実装した際の過失でした。絶対インポートに先立って相対インポートを実行する振る舞いがまだ必要なのであれば、index を 1 にして相対インポートを実行して、その後で index 0 のインポートをするようにしてください。そうなのですが、 __import__() を直接呼び出すのではなく、 importlib.import_module() を使うことが望ましいやり方です。
  • __import__() の index に、トップレベルモジュールに対して 0 でなく 1 を与えることは今では許されません。例えば __import__('sys', level=1) はエラーです。
  • sys.meta_path と sys.path_hooks にデフォルトでファインダが含まれるようになったので、これらリストの操作で list.append() してきたのであれば、今後はおそらくほとんどは list.insert() が相応しいでしょう。
  • ファインダが見つからない場合に sys.path_importer_cache に None が挿入されるようになったので、ファインダを持たないパスの辞書エントリをクリアするには、後方互換性を保つためには imp.NullImporter を値に持つエントリと None を値に持つエントリ の両方を 削除する必要があります。古い Python バージョンと比較して、暗黙のファインダを使うことを示すのに sys.path_importer_cache に None を再挿入するという追加のオーバヘッドが必要となりますが、意味的には何の変更もないはずです。
  • importlib.abc.Finder が find_module() 実装を強制することで行われていた抽象化は撤廃されています。そのメソッドを実装するサブクラスに依存していたならば、メソッドの存在を先にチェックするようにしてください。ですが、 path entry finders とともに動作させるのに、 find_loader() を最初にチェックしたくなるかもしれません。
  • pkgutil は、内部的に importlib を使うように変更されました。このことは、 PEP 302 インポートエミュレーションの古い振る舞いが本物のインポートシステムの振る舞いに合わせるのに失敗していた数多くの特殊ケースの問題を取り除きます。インポートエミュレーションそのものはまだ存在しますが、今では非推奨です。 pkgutil.iter_importers() 関数と pkgutil.walk_packages() 関数は標準インポートフックを特別に扱うので、ファインダの iter_modules() メソッドは標準ではないにも関わらず、まだサポートされます。
  • email.header.decode_header() によってなされる解析に長い間存在していた RFC 非準拠のバグ (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)
  • poplib.POP3.quit() メソッドもほかの全ての poplib のメソッドと同じく、今ではプロトコルエラーを送出し得ます。 quit が poplib.error_proto エラーを送出しないことをあてにしていたコードは、 quit でのエラーが特定のアプリケーションにとって問題となるようであれば、修正の必要があるかもしれません (bpo-11291)。
  • Python 2.4 から非推奨となっていた、 email.parser.Parser への strict 引数はついに削除されました。
  • 非推奨となっていたメソッド unittest.TestCase.assertSameElements は削除されました。
  • 非推奨となっていた変数 time.accept2dyear は削除されました。
  • 非推奨となっていた Context._clamp 属性が decimal モジュールから削除されました。以前に既にこれは公開属性 clamp に置き換えられていました (bpo-8540 参照)。
  • 文書化されていなかった内部ヘルパクラス SSLFakeFile が smtplib モジュールより削除されました。この機能はずっと以前から socket.socket.makefile() によって直接的に提供されています。
  • Windows では time.sleep() に負値を与えた場合に無限に眠っていましたが、今ではこれは例外を送出します。POSIX ではこれは以前より常に例外です。
  • 定数 ast.__version__ は削除されました。AST バージョンに依拠して何かしらの決定をする必要があるのであれば、 sys.version_info を使ってください。
  • threading モジュールの、非公開クラスをサブクラス化するファクトリ関数を迂回していたコードは、今では公開クラスになったので修正の必要があります。
  • threading モジュール内の文書化されていなかったデバッグ機構を削除してコードを単純化しました。このことが製品コードに影響することがあってはなりませんが、これと連携していたアプリケーションデバッグフレームワークのケースがありうるので、言及しておきます (bpo-13550)。

C コードの移植

  • バッファ API 変更の一環で、文書化されてこなかった Py_buffer 構造体のメンバ smalltable が削除され、また、 PyMemoryViewObject のレイアウトが変更されました。

    memoryobject.h あるいは object.h での関係する部分に依存する全ての拡張は、再ビルドが必要です。

  • PEP 393 により、 Py_UNICODE 型とこの型を使う全ての関数は非推奨となりました (ただし最低 5 年は利用可能なまま保たれます)。Unicode オブジェクトの構築とアクセスに低水準 Unicode API をこれまで使っていて、PEP 393 によって提供されるメモリフットプリント削減の恩恵を受けたければ、新しい 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.)

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

  • -Q コマンドラインスイッチとそれに関係するものは削除されました。 sys.flags.division_warning をチェックしているコードは修正する必要があります。

    (bpo-10998, contributed by Éric Araujo.)

  • -S スイッチ付きで python を開始すると、 import site がモジュール検索パスにサイト固有のパスを追加しなくなります。以前のバージョンではそれをしていました。

    (bpo-11591, contributed by Carl Meyer with editions by Éric Araujo.)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • What's New in Python »


What's New In Python 3.2

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

What's New In Python 3.2

著者: Raymond Hettinger

この記事では 3.1 と比較した Python 3.2 の新機能を解説します。 幾つかの新機能と例にフォ－カスしています。全詳細については Misc/NEWS をご覧ください。

参考

PEP 392 - 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 - 安定 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 - 新しいコマンドライン解析モジュール
PEP written by Steven Bethard.

optparse からのアップグレード に optparse との違いが詳しく書かれています。

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

logging モジュールではこれまで 2 つの設定手段がありました。一つはそれぞれのオプションごとに関数呼び出しをするスタイルで、もう一つは configparser フォーマットで保存された外部ファイル駆動のスタイルです。これらには JSON や YAML ファイルといったものから設定したりする柔軟性はなく、あるいはコマンドラインからロガーのオプションを指定するのに必要とされる、インクリメンタルな設定をサポートする柔軟性もありませんでした。

もっと柔軟な設定をサポートするために、新たに 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 - 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 - Futures -- 計算の非同期な実行
PEP written by Brian Quinlan.

threadpoolexecutor-example はスレッド並列でウェブページを取得する実例コードです。

ProcessPoolExecutor の実例を 並列で素数計算するコード例 として挙げています。

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

バイトコードを .pyc ファイルとしてキャッシュする Python の方法は、複数の Python インタプリタ環境ではうまく働きませんでした。一つのインタプリタがもう一つのインタプリタによって作られたキャッシュファイルに出会うと、そのインタプリタはソースを再コンパイルしてキャッシュファイルを上書きするわけですから、これではキャッシュの価値は台無しです。

「pyc ファイト」問題は、複数バージョンの Python を載せる Linux ディストリビューションにありふれたこととなったよりももっと表立って来ました。これら衝突は Unladen Swallow のような 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__ # doctest: +SKIP
'c:/py32/lib/__pycache__/collections.cpython-32.pyc'

  • キャッシュファイル名を一意にするためのインタプリタ実装ごとのタグは imp モジュールからアクセス出来ます:

    >>> import imp
>>> imp.get_tag() # doctest: +SKIP
'cpython-32'

  • インポートされたファイルからソースファイル名を推測しようとするスクリプトは、以前より賢くなる必要があります。もはや ".pyc" ファイル名から末尾の "c" を取り除くだけでは不十分です。そうではなくて imp モジュール内の新規関数を使いましょう:

    >>> 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') # doctest: +SKIP
'c:/py32/lib/__pycache__/collections.cpython-32.pyc'

  • py_compile と compileall モジュールはこの新命名規則とターゲットディレクトリを反映するよう更新されました。 compileall のコマンドラインからの起動には新しいオプションが追加されました。 -i はコンパイルするファイルとディレクトリのリストを指定します。 -b はバイトコードファイルを __pycache__ ではなく伝統的な場所に書き出します。

  • importlib.abc モジュールはバイトコードファイルのロードのための新しい 抽象基底クラス で更新されました。古くなった ABC PyLoader と PyPycLoader は非推奨となりました (Python 3.1 との互換性を保つための方法はドキュメントに含まれています)。

参考

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 - 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) を区別します。

ネイティブ文字列 は常に str 型ですが、コードポイント U+0000 から U+00FF までの間に制限され、これは Latin-1 エンコーディングを使ったバイト列に変換可能です。これら文字列は環境変数辞書のキーと値や、 start_response() 関数内でのレスポンスヘッダとステータスで使われます。これらはエンコーディングに関して RFC 2616 に従わなければなりません。つまりこれらは ISO-8859-1 文字であるか、 RFC 2047 MIME エンコーディングを使わなければなりません。

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 で表現出来る文字セットであることを暗黙で仮定しているようです。---)
  • アプリケーションから生み出される値と write() メソッドで送信される値は、バイト列文字列でなければなりません。 start_response() 関数と環境変数はネイティブ文字列を使わなければなりません。これら 2 つは混ぜこぜには出来ません。

CGI-to-WSGI 経路やほかの CGI スタイルのプロトコルへの経路を書くサーバ実装者にとっては、彼らのユーザは前提としているプラットフォームの慣習がどうであれネイティブ文字列を使って環境変数にアクセス出来なければなりません。この溝への橋渡しのために、 wsgiref モジュールに新規関数 wsgiref.handlers.read_environ() が追加されました。これは CGI 変数を os.environ からネイティブ文字列に変換して、新しい辞書として返します。

参考

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

  • 新たに追加された 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.)

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

  • hasattr() 関数は getattr() を呼び出して例外が起こるかどうかをみることで実現しています。このテクニックは、クラス辞書にない何かを __getattr__() あるいは __getattribute__() で動的に作るようなメソッドを検出するのに必要なものです。ですが以前は hasattr はあらゆる例外を捕捉してしまっていて、本物の誤りを隠してしまう可能性がありました。 hasattr は AttributeError だけを捕捉するように改められ、ほかの例外はそのままにするようにしました:

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

  • 浮動小数点数または複素数に対する 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.)

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

  • 以前は、入れ子になったブロック内である名前が自由変数として現れる場合、局所名前空間からその名前を削除することは不正でした。

    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 を参照してください。)

  • 内部実装に使っている structsequence がタプルのサブタイプを作るようになっています。これが何を意味するかと言えば、 os.stat(), time.gmtime(), sys.version_info が返すような C 構造体が named tuple のように働き、またこれはタプルを期待する関数やメソッドに渡せる、ということです。これは C 構造体に、対応するピュア Python に等しい柔軟性をもたらす大きな前進です:

    >>> import sys
>>> isinstance(sys.version_info, tuple)
True
>>> 'Version %d.%d.%d %s(%d)' % sys.version_info # doctest: +SKIP
'Version 3.2.0 final(0)'

    (Suggested by Arfrever Frehtes Taifersar Arahesis and implemented by Benjamin Peterson in bpo-8413.)

  • Warnings are now easier to control using the PYTHONWARNINGS environment variable as an alternative to using -W at the command line:

    $ export PYTHONWARNINGS='ignore::RuntimeWarning::,once::UnicodeWarning::'

    (Suggested by Barry Warsaw and implemented by Philip Jenvey in bpo-7301.)

  • 新たな警告カテゴリ ResourceWarning が追加されました。これはリソース消費やクリーンアップについての潜在的な問題が検出されると発行されます。これは通常のリリースビルドではデフォルトでは黙殺しますが、 warnings モジュールで意味付けを変更 (訳注: 警告フィルタ 参照) するかコマンドラインオプションで有効に出来ます。

    ResourceWarning はインタプリタがシャットダウンする時点で gc.garbage リストが空でない場合に発行されます。その際に gc.DEBUG_UNCOLLECTABLE がセットされていれば、全ての回収不能オブジェクトが印字されます。このことによりプログラマは、自身のコードがオブジェクトのファイナライズに問題を抱えていることに気付くことが出来ます。

    A ResourceWarning is also issued when a file object is destroyed without having been explicitly closed. While the deallocator for such object ensures it closes the underlying operating system resource (usually, a file descriptor), the delay in deallocating the object could produce various issues, especially under Windows. Here is an example of enabling the warning from the command line:

    $ 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 and bpo-477863.)

  • range オブジェクトが index メソッド、 count メソッドをサポートするようになりました。これは、もっと多くのオブジェクトに 抽象基底クラス collections.Sequence を完全に実装しようとする取り組みの一環です。結果として言語はより統一的な API を持つようになりました。加えて range オブジェクトは今やスライシングをサポートし、負のインデクス、 sys.maxsize を超えるインデクスもサポートします。このことは range とリストの相互運用性を高めます。

    >>> 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, by Alexander Belopolsky in bpo-2690, and by Nick Coghlan in bpo-10889.)

  • Py2.x から callable() 組み込み関数が復活しました。 この関数は isinstance(x, collections.Callable) のように式内で 抽象基底クラス を使用するよりも、簡潔で可読性の高い手段を提供します:

    >>> callable(max)
True
>>> callable(20)
False

    (bpo-10518 を参照してください。)

  • Python のインポート機構が、パス名に非 ASCII 文字を含むディレクトリにインストールされたモジュールをロードできるようになりました。これはユーザ名に非 ASCII 文字を含むユーザにとっての、ホームディレクトリにまつわる腹立たしい問題を解決しました。

(Required extensive work by Victor Stinner in bpo-9425.)

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

Python の標準ライブラリは保守の努力と質の向上を大きく受けています。

Python 3.2 での最大のニュースは、 email パッケージ、 mailbox モジュール、 nntplib モジュールが Python 3 の bytes/text モデルで正しく動作するようになったことです。エンコーディングが色々混ざったメッセージを正しく処理出来るようになったのは初めてのことです。

標準ライブラリ全体を通じて、エンコーディング問題とテキスト対バイト列問題に関してより注意深い配慮がなされました。とりわけオペレーティングシステムとの連携では、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 エンコードであると見做されます。

  • 新規クラス 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 and bpo-10321.)

elementtree

xml.etree.ElementTree パッケージと xml.etree.cElementTree の対応するものがバージョン 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() 代わりに list(elem) を使用してください。
  • xml.etree.ElementTree.getiterator() 代わりに Element.iter を使用してください。

アップデートの詳細については Fredrik Lundh のウェブサイト にある Introducing ElementTree を参照してください。

(Contributed by Florent Xicluna and Fredrik Lundh, 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:        # doctest: +SKIP
...     get_phone_number(name)        # cached lookup

    効果的なキャッシュサイズを選択する助けとなるよう、ラップされた関数はキャッシュの統計を追跡する道具にもなっています:

    >>> get_phone_number.cache_info()     # doctest: +SKIP
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, recipe 577479, bpo-10586, and bpo-10593.)

  • functools.wraps() デコレータが元の callable 関数を指し示す __wrapped__ 属性を追加するようになりました。これにより包まれた関数を調べることができます。定義されていれば __annotations__ もコピーされます。また、元の callable に定義されていないかもしれない __doc__ のような欠けた属性を潔くスキップするようにしました。

    上の例の場合、キャッシュは元の関数を復元することで削除できます:

    >>> get_phone_number = get_phone_number.__wrapped__    # uncached function

    (By Nick Coghlan and Terrence Cole; bpo-9567, bpo-3445, and 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)) # doctest: +SKIP

    ソートの例と簡単なチュートリアルは ソート HOW TO を参照して下さい。

    (Contributed by Raymond Hettinger.)

itertools

  • itertools モジュールに、 APL の scan 演算子や NumPy の 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 (訳注: 結果を [min, max] に収める演算) を行う既存の -= 演算子に加え、新しく追加された subtract() メソッドは通常の減算を行います。前者は要素数に正しか持たない 多重集合 に用いるのに適していて、後者は要素数に負を許容するユースケースにより適しています。

    >>> 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 を一般化したもので、それは 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 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, section 3.6.

(Contributed by Kristján Valur Jónsson with an API review by Jeffrey Yasskin in 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'

    いくつもの関数が今では日付範囲を大きく拡張しています。 time.accept2dyear が偽である場合、 time.asctime() 関数は C int の任意の整数を年として受け付け、 time.mktime() と time.strftime() は対応する OS 関数でサポートされる完全な範囲を受け付けます。(---訳注: 「全ての」と言っていない通りです。たとえば time.asctime(time.localtime(32535304320)) がたとえ使えなくても time.asctime((3002, 1, 1, 9, 32, 0, 3, 1, 0)) は許されます。---)

(Contributed by Alexander Belopolsky and Victor Stinner in bpo-1289118, bpo-5094, bpo-6641, bpo-2706, bpo-1777412, bpo-8013, and bpo-10827.)

math

math モジュールがアップデートされ、C99 標準に触発されて6つの新たな関数が追加されました。

The isfinite() function provides a reliable and fast way to detect special values. It returns True for regular numbers and False for Nan or Infinity:

>>> 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() 関数は確率積分、すなわち 誤差関数 を返します。 相補誤差関数 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() 関数は階乗を連続的に拡張したものです。詳細は ガンマ関数 を参照してください。ガンマ関数は階乗に関係しているため、小さな 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.)

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

reprlib

カスタムコンテナの __repr__() メソッドを書く際には、メンバがそのコンテナ自身を参照するケースを処理し忘れやすいものです。 list や set といったPython の組み込みオブジェクトでは、表現文字列の再帰部分内で自己参照を "..." と表示することで処理しています。

そうした __repr__() メソッドを書く助けとなるように、 reprlib モジュールに新規デコレータ recursive_repr() が追加されました。これは __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'>

(Contributed by Raymond Hettinger in bpo-9826 and 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")

ロギングイベントが発生する前に設定がセットアップされていない場合は、 WARNING レベル以上について sys.stderr に向けられた StreamHandler をデフォルトで使うようになりました。以前はこの場合は logging.raiseExceptions 属性の設定に従って、例外が発生するか黙って捨てられるかのいずれかでした。この新しいデフォルトの振る舞いは、ハンドラを属性 logging.lastResort にセットすることで実現しています。

The use of filters has been simplified. Instead of creating a Filter object, the predicate can be any Python callable that returns True or False.

ほかにも柔軟性を高め、設定を単純化する数多くの改善がありました。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, and the new method suggested by Ed Abraham in 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.)

decimal と fractions

Mark Dickinson は、異なる数値データの型が実際の値が等しい場合は常に同じハッシュ値を持つことを保証する、エレガントで効率的なスキームを作り上げました (bpo-8188):

assert hash(Fraction(3, 2)) == hash(1.5) == \
       hash(Decimal("1.5")) == hash(complex(1.5, 0))

いくつかのハッシュ化の詳細が、新規属性 sys.hash_info で公開されました。これはハッシュ値のビット幅、数値ハッシュ計算に利用される素数の法 (prime modulus)、 infinity (無限大) と nan (非数) に対して返されるハッシュ値、複素数の虚部を表すための乗数について記述しています:

>>> sys.hash_info # doctest: +SKIP
sys.hash_info(width=64, modulus=2305843009213693951, inf=314159, nan=0, imag=1000003)

種々の数値型の相互操作性についての制限の初期の決断は緩和されました。　Decimal('1.1') + float('1.1') のように、算術式内で暗黙に混合することは、今でもサポートされません (そして賢明でもありません)。これは後者 (float('1.1')) は二進浮動小数点数を構築する過程で情報を損失するからです。しかしながら既存の浮動小数点数値は損失なく十進もしくは有理数表現のどちらかに変換出来るので、それらのコンストラクタに浮動小数点数を渡せるようにして型違いの比較をサポートすることは理に適います。

  • decimal.Decimal コンストラクタに float オブジェクトを直接渡せるようになりました。これにより from_float() メソッドを使う必要はなくなりました (bpo-8257)。
  • 型違いの比較はいまでは完全にサポートされたので、 Decimal オブジェクトを直接 float や fractions.Fraction と比較出来ます (bpo-2531 and bpo-8188)。

同じ変更が fractions.Fraction にもなされたので、 from_float() も from_decimal() も、もはや必要ありません (bpo-8294):

>>> from decimal import Decimal
>>> from fractions import Fraction
>>> Decimal(1.1)
Decimal('1.100000000000000088817841970012523233890533447265625')
>>> Fraction(1.1)
Fraction(2476979795053773, 2251799813685248)

decimal モジュールへのもう一つの有用な変更は Context.clamp 属性がいまではパブリックになったことです。これは IEEE 754 で規定された固定幅十進交換形式に対応するコンテキストを作成するのに有用です。 (see 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, and by Georg Brandl in bpo-8046 and bpo-1286.)

FTP_TLS クラスが context パラメータを受け取れるようになりました。これには ssl.SSLContext オブジェクトを渡します。これは SSL コンフィグレーションオプション、証明書、秘密鍵を単一の (たぶん長生きの) 構造にまとめあげてくれるものです。

(Contributed by Giampaolo Rodolà; bpo-8806.)

popen

os.popen() ならびに subprocess.Popen() 関数が自動的にファイル記述子を閉じる with 文をサポートしました。

(Contributed by Antoine Pitrou and Brian Curtin in bpo-7461 and bpo-10554.)

select

select モジュールに新規定数属性 PIPE_BUF が公開されました。これは select.select() がパイプが書き込み準備が出来ていると主張した場合に、操作がブロックされないことが保障される最小バイト数です。

>>> import select
>>> select.PIPE_BUF  # doctest: +SKIP
512

(Available on Unix systems. Patch by Sébastien Sablé in 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; and by Antoine Pitrou, Nir Aides and Brian Curtin in bpo-9962, bpo-1675951, bpo-7471 and bpo-2846.)

さらに zipfile.ZipExtFile はアーカイブ内に格納されるファイルを表現するように内部的に書き換えられました。その新しい実装は顕著に高速となり、また io.BufferedReader 内に包めばさらにスピードアップ出来ます。またこれは、 read や readline 呼び出しを挟み込むと誤った結果となっていた問題も解決します。

(Patch submitted by Nir Aides in bpo-7610.)

tarfile

TarFile クラスは今ではコンテキストマネージャとして使えます。加えて、その add() メソッドに新しいオプション filter が追加されました。これはファイルをアーカイブに追加するかどうかを制御し、また、ファイルのメタデータを編集するのにも使えます。

The new filter option replaces the older, less flexible exclude parameter which is now deprecated. If specified, the optional filter parameter needs to be a keyword argument. The user-supplied filter function accepts a TarInfo object and returns an updated TarInfo object, or if it wants the file to be excluded, the function can return 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.)

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

ast

The ast module has a wonderful a general-purpose tool for safely evaluating expression strings using the Python literal syntax. The ast.literal_eval() function serves as a secure alternative to the builtin eval() function which is easily abused. Python 3.2 adds bytes and set literals to the list of supported types: strings, bytes, numbers, tuples, lists, dicts, sets, booleans, and 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'

いくつかの OS では環境変数内のエンコードされたバイト列に直接アクセス出来ます。もしそうであれば os.supports_bytes_environ 定数は真です。

エンコードされた環境変数への直接アクセス (可能な場合) には、新規関数 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 つの新機能があります。

  • sqlite3.Connection.in_transit 属性は、未コミットの変更のためのアクティブなトランザクションがあると真になります。
  • sqlite3.Connection.enable_load_extension() メソッドと sqlite3.Connection.load_extension() メソッドにより ".so" ファイルから SQLite 拡張をロードできます。良く知られた拡張の一つとして、SQLite と一緒に配布されている全文検索拡張があります。

(Contributed by R. David Murray and Shashwat Anand; 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.)
  • socket.create_connection() がコンテキスト管理プロトコルをサポートするようになりました。with ブロックを抜ける際に無条件にソケットをクローズします (クローズ処理で発生する socket.error は無視されます)。 (Contributed by Giampaolo Rodolà; bpo-9794.) (---訳注: リファレンスもそうなのですが、「 socket.create_connection() が with をサポート」というのは実態とは違うんじゃないかと思います(この関数のユーザからは同じにみえたとしても)。実際には socket.socket がコンテキストマネージャをサポートしています。 socket.py 参照。--)

ssl

ssl モジュールは、セキュアな (暗号化され、認証された) インターネット接続のために共通の要求を満足するための数多くの機能を追加しています:

  • 新規クラス SSLContext は、プロトコル設定や証明書、秘密鍵やそのた色々なオプションのような、永続的 SSL データの容器として働きます。その中のメソッド wrap_socket() を使うと、 SSL コンテキストから SSL ソケットを作れます。
  • 新規関数 ssl.match_hostname() はより高水準なプロトコルのためのサーバの身元検証を、HTTPS のルール ( RFC 2818 より) を実装することでサポートします。これはほかのプロトコルにも適切なものです。
  • 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.
  • 最新版の OpenSSL にリンクしていれば、 ssl モジュールは TLS プロトコルに対する Server Name Indication 拡張 (訳注: SNI, RFC 4366) をサポートします。これは単一の IP ポートで異なった証明書を使った複数「バーチャルホスト」をもたらすものです。この拡張はクライアントモードでのみサポートされ、 ssl.SSLContext.wrap_socket() の server_hostname を渡すことで活性化されます。
  • ssl モジュールに色々オプションが追加されました。例えば OP_NO_SSLv2 は安全でなく時代遅れの SSLv2 を無効にします。
  • 拡張はOpenSSL の全ての暗号とメッセージダイジェストアルゴリズムをロードします。SSL 証明書の中に検証できないものがある場合、"unknown algorithm" エラーを報告します。
  • 使われている OpenSSL のバージョンを、モジュール属性 ssl.OPENSSL_VERSION (文字列)、 ssl.OPENSSL_VERSION_INFO (5-タプル)、および ssl.OPENSSL_VERSION_NUMBER (整数) から取れるようになりました。

(Contributed by Antoine Pitrou in bpo-8850, bpo-1589, bpo-8322, bpo-5639, bpo-4870, bpo-8484, and bpo-8321.)

nntp

nntplib モジュールが改造されて、より良い bytes とテキストについての意味付けを行うようになり、またより実用的な API になりました。これら実装は nntplib の Python 3.1 版との互換性を破壊しますが、もともとそれら自身にいくぶん機能不全がありました。

セキュアな接続のサポートも追加されています。(nntplib.NNTP_SSL を使う) 暗黙の TLS、(nntplib.NNTP.starttls() を使う) 明示的な TLS ともにサポートされます。

(Contributed by Antoine Pitrou in bpo-9360 and Andrew Vant in 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.)

imaplib

標準 IMAP4 接続での明示的な TLS 使用を新規メソッド imaplib.IMAP4.starttls で出来るようになりました。

(Contributed by Lorenzo M. Catucci and Antoine Pitrou, 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 内の 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). 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.)

  • unittest.case.TestCase クラスが引数なしでインスタンス化できるようになったので、対話プロンプトからお試ししてみるのが以前より簡単です。

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

    もう一つの新メソッド assertCountEqual() は 2 つのイテラブルを比較して、要素の出現回数が同じか (順序に関わらず同じ要素が同じ数だけ出現するかどうか) をテストします:

    def test_anagram(self):
    self.assertCountEqual('algorithm', 'logarithm')

    (Contributed by Raymond Hettinger.)

  • unittest モジュールの大事な特長は、テスト失敗時の有意義な診断を生成するよう腐心してくれることです。可能ならば失敗は期待値と実際の出力との差分と一緒に記録されます。これは失敗したテスト実行の解析に特に役に立ちますが、差分は時々とてつもなく大きくもなりますので、新たに追加した属性 maxDiff に差分の最大長をセットすることで表示を制御できるようになりました。

  • さらにモジュールのメソッド名に数多くのクリーンアップを行いました。

    たとえば assertRegexpMatches() は看板を偽っていて本当は re.match() など呼び出したりはせず re.search() でテストしていたので、 assertRegex() にリネームされました。なおほかの正規表現を使うメソッドも今では "Regexp" ではなく短い様式 "Regex" で命名されています。 -- これはほかの unittest 実装で使われている命名と合致し、Python re モジュールの古い命名に合致し、また、曖昧さのないキャメルケースです。

    (Contributed by Raymond Hettinger and implemented by Ezio Melotti.)

  • 一貫性を向上させるために、長年使用されたメソッドエイリアスが推奨名に対し非推奨になりました:

    以前の名前 | 推奨名
    assert_() | assertTrue()
    assertEquals() | assertEqual()
    assertNotEquals() | assertNotEqual()
    assertAlmostEquals() | assertAlmostEqual()
    assertNotAlmostEquals() | assertNotAlmostEqual()

    同様に、Python 3.1 で非推奨になった TestCase.fail* メソッドは Python 3.3 で削除されるはずです。 unittest ドキュメント 非推奨のエイリアス を参照してください。

    (Contributed by Ezio Melotti; bpo-9424.)

  • assertDictContainsSubset() メソッドは非推奨となりました。というのもこれは引数順を誤って実装されていたからです。これは TestCase().assertDictContainsSubset({'a':1, 'b':2}, {'a':1}) のようなテストが失敗した場合に、デバッグを困難にする見間違いを起こしやすいものでした。

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

poplib

POP3_SSL クラスが context パラメータを受け取れるようになりました。これには ssl.SSLContext オブジェクトを渡します。これは SSL コンフィグレーションオプション、証明書、秘密鍵を単一の (たぶん長生きの) 構造にまとめあげてくれるものです。

(Contributed by Giampaolo Rodolà; bpo-8807.)

asyncore

asyncore.dispatcher に handle_accepted() が追加されています。これは新しくリモート側の端点との接続が実際に確立した際に (sock, addr) ペアを伴って呼び出されます。これは古い handle_accept() を置き換えるものとして使われるでしょう。またユーザが直接 accept() を呼び出す必要もなくなります。

(Contributed by Giampaolo Rodolà; bpo-6706.)

tempfile

tempfile モジュールに新たなコンテクストマネージャ TemporaryDirectory が追加されました。一時ディレクトリの確実な後片付けを容易に行えます:

with tempfile.TemporaryDirectory() as tmpdirname:
    print('created temporary dir:', tmpdirname)

(Contributed by Neil Schemenauer and Nick Coghlan; bpo-5178.)

inspect

  • inspect モジュールに新たな関数 getgeneratorstate() が追加されました。これで簡単にジェネレータイテレータの現在状態を識別出来ます (---訳注: generator-iterator という用語を使っている箇所は Python ドキュメント全体通して多くはないのですが 2.x の The yield statement 説明中に登場します。ジェネレータと同じ意味です。なお 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.)

  • 動的な属性を活性化することなく検索するのをサポートするために、 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.)

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

dbm

全データベースモジュールが get() と setdefault() メソッドをサポートしました。

(Suggested by Ray Allen in 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'

Conveniently, some of site's functionality is accessible directly from the command-line:

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

sysconfig

新しい sysconfig モジュールは、プラットフォームやインストレーションごとに変わるインストールパスや環境設定変数への、直接的なアクセスを提供します。

このモジュールはプラットフォームとバージョンの情報へのシンプルなアクセス関数を持っています:

  • get_platform() は linux-i586 や macosx-10.6-ppc といった値を返します。
  • get_python_version() は Python バージョンを文字列で "3.2" のように返します。

また、 distutils で使われる、名前のついた 7 つのスキームのうちどれか一つに対応するパスと変数にもアクセス出来ます。それらには posix_prefix, posix_home, posix_user, nt, nt_user, os2, os2_home が含まれます:

  • get_paths() は現在のインストールスキームに関するインストールパスを含むディレクトリ名を作ります。
  • get_config_vars() はプラットフォーム依存変数の辞書を返します。

There is also a convenient command-line interface:

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 コマンドを含むことができます。
  • Pdb クラスのコンストラクタが nosigint 引数を取るようになっています。
  • 新コマンド: l(list), ll(long list), source はソースコードを出力します。
  • 新コマンド: display, undisplay は、変更があった場合の式の値の表示/非表示を切り替えます。
  • 新コマンド: interact は現在のスコープで見つかったグローバルおよびローカル名を含む対話型インタプリタを開始します。
  • ブレイクポイントをブレイクポイント番号指定でクリア出来ます。

(Contributed by Georg Brandl, Antonio Cuni and Ilya Sandler.)

configparser

configparser モジュールが、デフォルトパーサとそれがサポートする INI 構文の使い勝手とわかりやすさを改善するために修正されました。元のクラス ConfigParser が削除されて、代わりに昔から推奨だった SafeConfigParser が新しい ConfigParser になりました。インラインコメントはデフォルトでオフに変更され、また、単一の設定ソース内ではセクションとオプションの重複を禁止しています。

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 にて記述されている IPv6 アドレスをサポートするようになりました:

>>> import urllib.parse
>>> urllib.parse.urlparse('http://[dead:beef:cafe:5417:affe:8FA3:deaf:feed]/foo/') # doctest: +NORMALIZE_WHITESPACE
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/') # doctest: +NORMALIZE_WHITESPACE
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, bpo-5468, and 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.)

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

マルチスレッディング

  • 並列に走る Python スレッドの直列実行のメカニズム (一般に GIL あるいは Global Interpreter Lock として知られるもの) が書き換えられました。取り立てて目標とされたのが、より予測可能なインターバルの切り替えと、ロックの競合と多数の続くシステムコールによるオーバヘッドを削減することでした。スレッド切り替えを許す "check interval" の考え方は捨て去られ、秒で表された絶対的時間間隔に置き換わりました。このパラメータは sys.setswitchinterval() で調整可能です。今のところこのデフォルトは 5 ミリ秒です。

    この実装に関するさらなる詳細は python-dev mailing-list message で読むことが出来ます (ただしこのメッセージで言っている "priority requests" は含められませんでした)。

    (Contributed by Antoine Pitrou.)

  • 通常のロックと再帰的なロックが、acquire() メソッドでオプションで timeout 引数を受け取るようになりました。 (Contributed by Antoine Pitrou; bpo-7316.)

  • 同様に、threading.Semaphore.acquire() にも timeout 引数が追加されました。 (Contributed by Torsten Landschoff; bpo-850728.)

  • 通常のロックと再帰的なロックの獲得に、 Pthreads を使用するプラットフォームでシグナルが割り込めるようになりました。これでロック獲得時にデッドロックしていた Python プログラムは、プロセスに SIGINT (ほとんどのシェルでは Ctrl+C で) を繰り返し送ることで殺せます。(Contributed by Reid Kleckner; 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).

  • pickle モジュールを用いたデータのシリアライズ・デシリアライズが数倍速くなりました。

    (Contributed by Alexandre Vassalotti, Antoine Pitrou and the Unladen Swallow team in bpo-9410 and bpo-3873.)

  • The Timsort algorithm 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.)

  • 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 and by Raymond Hettinger and Antoine Pitrou in bpo-10314.)

  • 再帰的ロック (threading.RLock() API により生成) は C で実装されたことにより、以前の純粋な Python 実装より10から15倍速くなり、通常のロックと同じくらいになりました。

    (Contributed by Antoine Pitrou; 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 and bpo-7462.)

  • Integer to string conversions now work two "digits" at a time, reducing the number of division and modulo operations.

    (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). The array.repeat() method has a faster implementation (bpo-1569291 by Alexander Belopolsky). The BaseHTTPRequestHandler has more efficient buffering (bpo-3709 by Andrew Schaaf). The operator.attrgetter() function has been sped-up (bpo-10160 by Christos Georgiou). And ConfigParser loads multi-line arguments a bit faster (bpo-7113 by Łukasz Langa).

Unicode 文字列型

Python が Unicode 6.0.0 でアップデートされました。この更新は標準に 2,000 を超える新たな文字を追加し、これにはモバイルフォンにとって大事な 絵文字 記号も含まれます。

さらに、更新された標準は二つの Kannada 文字 (U+0CF1, U+0CF2) と一つの New Tai Lue 数値文字 (U+19DA) の文字特性を置き換えました。前者は識別子内での使用が適格となり、後者は不適格となります。さらに詳しい情報は Unicode Character Database Changes をみてください。

Codecs

cp720 アラビア DOS エンコードがサポートされました (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 スタイルの表からリンクが張られていて、これで要約がわかりますし、ドキュメント全体を読む必要なく記憶を呼び覚ますことが出来ます。

  • ある種のケースではピュア Python のソースコードが文書化の助手として便利に働いてくれますので、今では多くのモジュールがソースコードの最新バージョンへのクイックリンクを客演させています。例えば functools モジュールのドキュメントは先頭にこのようにクイックリンクを置いています:

    ソースコード Lib/functools.py.

    (Contributed by Raymond Hettinger; see rationale.)

  • ドキュメントには今ではもっと実例とレシピが含まれています。特に re モジュールのものには大掛かりなセクション 正規表現の例 があります。同じように itertools では新しい Itertools レシピ で更新され続けます。

  • datetime モジュールは今ではピュア Python による補助実装を持っています。機能に違いはありません。これは読みやすい代替の実装を提供するだけのものです。

    (Contributed by Alexander Belopolsky in bpo-9528.)

  • 保守されていなかった Demo ディレクトリは削除されました。いくつかのデモはドキュメントに統合され、いくつかは Tools/demo ディレクトリに移動し、ほかのものは一緒に削除されました。

    (Contributed by Georg Brandl in bpo-7962.)

IDLE

  • IDLE のフォーマットメニューに、ソースコードから末尾の空白を取り除くことが出来るオプションが追加されました。

    (Contributed by Raymond Hettinger; bpo-5150.)

  • Mac OS X 上の IDLE が Carbon AquaTk と Cocoa AquaTk の両方で動くようになりました。

    (Contributed by Kevin Walzer, Ned Deily, and Ronald Oussoren; bpo-6075.)

コードリポジトリ

http://svn.python.org 上の既存の Subversion コードリポジトリに加え、https://hg.python.org/ の Mercurial リポジトリが追加されました。

3.2 のリリース後に、主要なリポジトリを Mercurial に移行する計画があります。 この分散バージョン管理システムによってコミュニティメンバが容易に外部 changeset を作成したり共有したりすることが出来ます。 詳細は PEP 385 を参照してください。

新しいバージョン管理システムの使い方を学ぶには tutorial by Joel Spolsky や Guide to Mercurial Workflows を参照してください。

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

Python のビルド過程と C API の変更は以下の通りです:

  • スクリプト idle, pydoc, 2to3 が make altinstall 時にバージョン固有のサフィックスを付けてインストールされるようになりました (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.)

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

  • オプション --with-wctype-functions は削除されました。今では組み込みの Unicode データベースが全ての関数のために使われます。

    (Contributed by Amaury Forgeot D'Arc; 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.)

  • 新規マクロ Py_VA_COPY は可変引数リストの状態をコピーします。これは C99 の va_copy と等価ですが、全ての Python プラットフォームで利用出来ます (bpo-2443)。(---訳注: 全ての Python プラットフォーム、というよりは、プラットフォームの C コンパイラに関係なく、ということ。---)

  • 新規 C API 関数 PySys_SetArgvEx() を使うと埋め込みインタプリタの sys.argv をセット出来ますが、既存の PySys_SetArgv() と違って sys.path を更新しないことも出来ます (bpo-5753)。

  • PyEval_CallObject はマクロ形式でのみ利用可能となりました。関数宣言は後方互換のために残されていましたが削除されました。 -- マクロは 1997 年に導入されています (bpo-8276)。

  • PyLong_AsLongAndOverflow() の姉妹品の PyLong_AsLongLongAndOverflow() 関数が追加されました。両方とも Python int を C ネイティブの固定幅型に変換しますが、変換が幅に合わないことを検出します (bpo-7767)。

  • PyUnicode_CompareWithASCIIString() 関数が、Python 文字列が NUL 終端である場合に「 等しくない 」を返すようになりました。

  • 新しい関数 PyErr_NewExceptionWithDoc() は PyErr_NewException() と似ていますが、ドキュメンテーション文字列を受け付けます。これは C 拡張に、対応するピュア Python と同じ自己文書化 (self-documenting) 能力を与えます (bpo-7033)。

  • --with-valgrind オプションとともにコンパイル時、 Valgrind のもとでの実行時に自動的に pymalloc アロケータが無効になるようになりました。ほかの状況では pymalloc は有利ですが、Valgrind 配下での実行時のメモリリーク検出では無効化したほうが良い結果が得られます (bpo-2422)。

  • PyArg_Parse 関数から書式文字列 O? が削除されました。これはもう使われていませんし、今まで一度も文書化されたことはありません (bpo-8837)。

ほかにも C API に対する小さな変更が多数行われました。完全なリストは Misc/NEWS ファイルにあります。

Also, there were a number of updates to the Mac OS X build, see 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. See https://www.python.org/download/mac/tcltk/ for additional details.

Python 3.2 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

  • configparser モジュールに大掃除が行われました。最も大きな変更は、古い ConfigParser クラスを長年推奨の代替だった SafeConfigParser に置き換えたことです。加えて多くの小さな非互換があります:

    • 補間 (interpolation) の構文は今では get() と set() の操作で検証されます。デフォルトの補間スキームでは、パーセント記号を使ったただ二つのトークンのみが正当です: %(name)s と %% 、後者はエスケープされたパーセント記号自身。
    • set() メソッドと add_section() メソッドは今ではその値が実際に文字列かどうかを検証します。以前はサポートされない型が意図せず持ち込まれる可能性がありました。
    • 単一ソースからのセクションまたはオプションの複製 (重複) に対し、今では DuplicateSectionError もしくは DuplicateOptionError を投げます。以前は重複は黙って以前のエントリを上書きしていました。
    • インラインコメントは今ではデフォルトで無効なので、 ; 文字を安全に値のなかで使えます。
    • コメントを字下げ出来るようになっています。このことにより、値が継続行となる場合の後続行の字下げ開始位置に ; または # を置くには、補間を使う必要があります。こうすればコメントのプレフィクス文字が値内に現れて誤ってコメントと解釈されるのを防げます。
    • "" は今では合法な値なので、もはや自動的に空文字列に変換されることはありません。空文字列のためには行内で "option =" と書いてください。

  • nntplib モジュールが大幅に更新され、3.1 API とはしばしば互換性がありません。

  • bytearray オブジェクトはもうファイル名には使えません。代わりに bytes に変換しなければいけません。

  • array.tostring() と array.fromstring() がそれぞれ array.tobytes() と array.frombytes() に名称変更されました。言ってることとやってることを合わせるためです。古い名前は非推奨となりました。 (bpo-8990 参照。)

  • PyArg_Parse*() 系関数:

    • 書式文字列 "t#" の削除: 代わりに "s#" もしくは "s*" を使ってください。
    • 書式文字列 "w" および "w#" の削除: 代わりに "w*" を使ってください。

  • Python 3.1 で非推奨となった PyCObject が削除されました。不透明な C ポインタを Python オブジェクトにラップするには PyCapsule を代わりに使ってください。この新しい型は、型安全に情報を渡すための良く定義されたインターフェイスを持ち、また、デストラクタの呼び出しのシグネチャの複雑さが小さくなっています。

  • sys.setfilesystemencoding() 関数は削除されました。設計に欠陥があったからです。

  • random.seed() 関数とメソッドが、salt に文字列やバイト列を与えた場合に内部で sha512 ハッシュ関数を使うようになりました。Python 3.1 シーケンスを再現するのに以前のバージョンの seed が必要であれば、 version 引数を 1 にしてください。 random.seed(s, version=1) のように。

  • 以前にそれぞれの静的メソッド bytes.maketrans() と bytearray.maketrans() に置き換えられたために非推奨となった string.maketrans() 関数が削除されました。この変更は、 string によってサポートされるのがどちらの型なのかにまつわる混乱を解決します。今や str, bytes, bytearray は、その適切な型の中間変換テーブルを持つそれぞれの maketrans 、 translate メソッドを持っています。

    (Contributed by Georg Brandl; bpo-5675.)

  • 以前に非推奨となった contextlib.nested() が削除されました。普通の with が複数のコンテクストマネージャを許容するように強化されたからです。これは (組み込みなので) 高速であり、複数コンテクストマネージャのうち一つが例外を送出した際にそれらのファイナライズをとても上手く処理します:

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

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

  • The xml.etree.ElementTree class now raises an xml.etree.ElementTree.ParseError when a parse fails. Previously it raised an 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.)

  • タイムアウトモード時の SSL ソケットでタイムアウトした場合に、汎用の SSLError ではなく socket.timeout を投げるようになりました。

    (Contributed by Antoine Pitrou, bpo-10272.)

  • 紛らわしい関数 PyEval_AcquireLock() と PyEval_ReleaseLock() が公式に非推奨となりました。スレッド状態に関知する API (例えば PyEval_SaveThread() と PyEval_RestoreThread()) を代わりに使うべきです。

  • セキュリティリスクがあるので asyncore.handle_accept() は非推奨となり、それを置き換える新しい関数 asyncore.handle_accepted() が追加されました。

    (Contributed by Giampaolo Rodola in bpo-6706.)

  • 新しい GIL 実装によって、 Py_Initialize() の前に PyEval_InitThreads() を呼び出すことはもう出来なくなりました。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • What's New in Python »


What's New In Python 3.1

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

What's New In Python 3.1

著者: Raymond Hettinger

この記事では 3.0 と比較した Python 3.1 の新機能を解説します。

PEP 372: 順序付き辞書

通常の Python 辞書は、 key/value ペアを不定の順序でイテレートします。何年にもわたり、いろいろな人が key の挿入順を保存する辞書の別実装を書いてきました。その経験に基づき、新しい OrderedDict クラスが導入されました。

OrderedDict API は通常の辞書と同じインタフェースを提供していますが、 key/value をイテレートするときに key が最初に挿入された順番になることが保証されています。新しいエントリが既存のエントリを上書きした場合は、元の挿入順序が保持されます。エントリを削除して再挿入すると、順序は一番最後に移動します。

The standard library now supports use of ordered dictionaries in several modules. The configparser module uses them by default. This lets configuration files be read, modified, and then written back in their original order. The _asdict() method for collections.namedtuple() now returns an ordered dictionary with the values appearing in the same order as the underlying tuple indices. The json module is being built-out with an object_pairs_hook to allow OrderedDicts to be built by the decoder. Support was also added for third-party tools like PyYAML.

参考

PEP 372 - 順序付き辞書
PEP written by Armin Ronacher and Raymond Hettinger. Implementation written by Raymond Hettinger.

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

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

  • format() 文字列のフィールドに自動的に番号が振られるようになりました:

    >>> 'Sir {} of {}'.format('Gallahad', 'Camelot')
'Sir Gallahad of Camelot'

    以前は、文字列は 'Sir {0} of {1}' のようにフィールドに番号を振らなければなりませんでした。

    (Contributed by Eric Smith; bpo-5237.)

  • string.maketrans() 関数は撤廃され、それぞれの静的メソッド bytes.maketrans() と bytearray.maketrans() に置き換えられました。この変更は、 string によってサポートされるのがどちらの型なのかにまつわる混乱を解決します。今や str, bytes, bytearray は、その適切な型の中間変換テーブルを持つそれぞれの maketrans 、 translate メソッドを持っています。

    (Contributed by Georg Brandl; 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)

    新しいシンタックスによって contextlib.nested() はもう必要ではなくなり、非推奨になりました。

    (Georg Brandl と Mattias Brändström の貢献; appspot issue 53094.)

  • round(x, n) は x が整数の場合、整数を返すようになりました。以前は浮動小数点を返していました:

    >>> round(1123, -2)
1100

    (Contributed by Mark Dickinson; 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)

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

  • シーケンスまたはイテラブル内にある一意な要素を数え上げるのに便利な collections.Counter クラスが追加されました:

    >>> Counter(['red', 'blue', 'red', 'green', 'blue', 'blue'])
Counter({'blue': 3, 'red': 2, 'green': 1})

    (Contributed by Raymond Hettinger; bpo-1696199.)

  • Tk のテーマ付きウィジェットへのアクセスを提供する、新しい tkinter.ttk モジュールが追加されました。 tkinter.ttk の基本的なアイディアは、拡張可能性のためにウィジェットの動作を実装するコードと見た目を記述するコードを分離することです。

    (Contributed by Guilherme Polo; 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 の同名機能の模倣品です。また、既存の 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.)

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

  • コマンドラインスイッチ -m をサポートしている runpy がパッケージの実行をサポートするようになりました。パッケージ名が与えられると __main__ サブモジュールを探し出して実行します。

    (Contributed by Andi Vajda; bpo-4195.)

  • pdb モジュールが zipimport (あるいはなにかほかの PEP 302 準拠ローダ) でロードされたモジュールのソースコードにアクセスでき、表示できるようになりました。

    (Contributed by Alexander Belopolsky; bpo-4201.)

  • functools.partial オブジェクトが pickle 化出来るようになりました。

(Suggested by Antoine Pitrou and Jesse Noller. Implemented by Jack Diederich; bpo-5228.)

  • シンボルのための pydoc ヘルプトピックが追加されました。これで対話環境で help('@') などが期待通りの働きをします (---訳注: 実装としては pydoc_data パッケージのこと。 pydoc_data/topics.py に docstring からは生成出来ない、シンボルについてのドキュメントが収められています ---)。

    (Contributed by David Laban; 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

    加えて、いくつもの新たなアサーションメソッドが追加されました。 assertSetEqual(), assertDictEqual(), assertDictContainsSubset(), assertListEqual(), assertTupleEqual(), assertSequenceEqual(), assertRaisesRegexp(), assertIsNone(), and assertIsNotNone() などです。

    (Contributed by Benjamin Peterson and Antoine Pitrou.)

  • io モジュールに seek() メソッドのための3つの新しい定数が追加されました: 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.)

  • nntplib および imaplib モジュールが IPv6 をサポートしました。

    (Contributed by Derek Morr; bpo-1655 and 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.)

  • 新規モジュール importlib が追加されました。 import 文とその相棒の __import__() 関数の、完全で移植性が高いピュア Python 参照実装を提供しています。これはインポートで行う動作の文書化と定義における、確かな前進です。

    (Contributed by Brett Cannon.)

最適化

大きな性能向上がありました:

  • The new I/O library (as defined in 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.)

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

  • UTF-8, UTF-16 ならびに LATIN-1 のデコーディングが2から4倍速くなりました。

    (Antoine Pitrou と Amaury Forgeot d'Arc の貢献, 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 which is defined in terms of Unicode.

    (Contributed by Bob Ippolito and converted to Py3.1 by Antoine Pitrou and Benjamin Peterson; 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.)

IDLE

  • IDLE のフォーマットメニューに、ソースコードから末尾の空白を取り除くことが出来るオプションが追加されました。

    (Contributed by Roger D. Serwy; 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-digis が追加されました。 これにより上記のデフォルトを上書き出来ます。

    この変更は性能向上以外ではエンドユーザには分からないはずですが、例外が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.)

  • PyLong_AsUnsignedLongLong() 関数は負の pylong に対し TypeError ではなく OverflowError を送出するようになりました。

    (Contributed by Mark Dickinson and Lisandro Dalcrin; bpo-5175.)

  • PyNumber_Int() が非推奨になりました。代わりに PyNumber_Long() を使用してください。

    (Contributed by Mark Dickinson; bpo-4910.)

  • 非推奨の関数 PyOS_ascii_strtod() および PyOS_ascii_atof() を置き換えるために新しく PyOS_string_to_double() 関数が追加されました。

    (Contributed by Mark Dickinson; bpo-5914.)

  • PyCObject API を置き換えるものとして、 PyCapsule が追加されました。主な違いとしては、新しい型は、型安全に情報を渡すための良く定義されたインターフェイスを持ち、また、デストラクタの呼び出しのシグネチャの複雑さが小さくなっています。古い型は問題のある API で、今では非推奨です。

    (Contributed by Larry Hastings; 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
**********************************************************************

  • The automatic name remapping in the pickle module for protocol 2 or lower can make Python 3.1 pickles unreadable in Python 3.0. One solution is to use protocol 3. Another solution is to set the fix_imports option to False. See the discussion above for more details.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • What's New in Python »


What's New In Python 3.0

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

What's New In Python 3.0

著者: Guido van Rossum

この記事では 2.6 と比較した Python 3.0 での新機能を解説します。 Python 3.0、あるいは "Python 3000"、 "Py3K" は初めて 意図的に後方非互換にした Python のリリースです。 通常のリリースよりも多くの変更があり、全ての Python ユーザにとって重要です。 しかし、変更について理解したら Python に実際にはそれほど変更がないことが分かるでしょう。 全体的に見れば、よく知られた悩みの種が概ね解決され、昔の粗雑なものが取り除かれています。

この記事は全ての新機能を完璧な仕様を示そうとはしませんが、便利な概要については説明しようとしています。 全詳細については Python 3.0 のドキュメントや、本編で引かれている多くの PEP を参照してください。 特定の機能の実装や設計原理について完全に理解したいなら、通常のドキュメントよりも詳しいことが書いてある PEP を見るとよいでしょう。 しかし、一旦機能が完全に実装されると、普通 PEP は最新の状態に保たれないことに注意してください。

この文書で全項目に触れるべきなのですが、時間の制約のためそうではありません。 いつもの新リリースのように、 ソース配布の Misc/NEWS には些細な変更についても詳細な情報があります。

よくある悩みの種

このセクションは Python 2.5 に慣れていたら躓いてしまいそうな少数の変更の一覧です。

print関数

print 文は print() 関数に置き換えられ、古い print 文の特殊な文法の殆どがキーワード引数で置き換えられています ( 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="")

which produces:

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: Essentially, long renamed to int. That is, there is only one built-in integral type, named int; but it behaves mostly like the old long type.
  • PEP 238: 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: 文字列への repr() はもう非 ASCII 文字をエスケープしません。ただし、制御文字、Unicode 標準で印字不可状態のコードポイントは今でもエスケープされます。
  • PEP 3120: ソースのエンコードのデフォルトが UTF-8 になりました。
  • PEP 3131: 非 ASCII 文字を識別子として使用することが出来るようになりました。 (そうはいっても標準ライブラリは、コメント内での貢献者の名前以外では ASCII だけのままです。)
  • StringIO および cStringIO モジュールは廃止されました。その代わり io モジュールをインポートして、テキストやデータには io.StringIO や io.BytesIO を使用してください。
  • Unicode HOWTO を参照してください。Python 3.0 向けに更新されました。

構文の変更の概要

このセクションは Python 3.0 における全ての 構文の 変更についての簡単な概要です。

新たな構文

  • PEP 3107: 関数引数と戻り値のアノテーション。これは関数のパラメータと戻り値へのアノテーションを付ける標準的な手段を提供します (訳注: annotation を強いて訳せば「注釈」)。そのようなアノテーションには、実行時に __annotations__ 属性を調べること以外には何の意味付けもされていません。メタクラスやデコレータ、フレームワークを通じた実験を促進することが意図されています。

  • PEP 3102: キーワードオンリー (keyword-only) 引数。パラメータリスト中で *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: nonlocal statement. Using nonlocal x you can now assign directly to a variable in an outer (but non-global) scope. nonlocal is a new reserved word.

  • PEP 3132: 拡張されたイテレータのアンパック。 a, b, *rest = some_sequence のようなことを書けるようになりました。 *rest, a = stuff も出来ます。 rest オブジェクトは常に (空かもしれなくても) リストです; 右辺には任意のイテラブルを置けます。例えば:

    (a, *rest, b) = range(5)

    これは a に 0 を、 b に 4 を、そして rest に [1, 2, 3] をセットします。

  • Dictionary comprehensions: {k: v for k, v in stuff} means the same thing as dict(stuff) but is more flexible. (This is PEP 274 vindicated. :-)

  • セットリテラル、例えば {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 と PEP 3134: 新たな raise 文のシンタックス: raise [expr [from expr]]。以下を参照してください。

  • as and with are now reserved words. (Since 2.6, actually.)

  • True、False、および None が予約語になりました。(2.6 では既に None が部分的に制限されていました)

  • Change from except exc, var to except exc as var. See PEP 3110.

  • 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: タプル引数のアンパックが削除されました. 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 * はモジュールレベルでのみ許され、関数内での使用は許されません。
  • The only acceptable syntax for relative imports is from .[module] import name. All import forms not starting with . are interpreted as absolute imports. ( PEP 328)
  • 古い形式のクラスはサポートされません。

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 を参照してください。 ここでは要約を示します:

  • Many old modules were removed. Some, like gopherlib (no longer used) and md5 (replaced by hashlib), were already deprecated by PEP 4. Others were removed as a result of the removal of support for various platforms such as Irix, BeOS and Mac OS 9 (see PEP 11). Some modules were also selected for removal in Python 3.0 due to lack of use or because a better replacement exists. See PEP 3108 for an exhaustive list.

  • bsddb3 パッケージが削除されました。テストの不安定性と Berkeley DB のリリーススケジュールにより、中心標準ライブラリでの存在が中心開発者の大きな負担になっていることが徐々に分かってきたためです。しかしながら bsddb3 パッケージはまだ残っていて、https://www.jcea.es/programacion/pybsddb.htm で外部的に保守されています。

  • Some modules were renamed because their old name disobeyed PEP 8, or for various other reasons. Here's the list:

    以前の名前 | 新しい名前
    _winreg | winreg
    ConfigParser | configparser
    copy_reg | copyreg
    Queue | queue
    SocketServer | socketserver
    markupbase | _markupbase
    repr | reprlib
    test.test_support | test.support

  • Python 2.x でのよくあるパターンは、ピュア Python で実装した版とともに、オプショナルで、C 拡張として実装した「加速装置付き (accelerated)」版を持つ、というものです。例えば pickle と cPickle がそうです。それらモジュールの個々のユーザにとって、accelerated 版をインポートしてみてダメならピュア Python 版を使う、というのも重荷となるものです。Python 3.0 では、 accelerated 版はピュア Python 版の実装の詳細と考えます。ユーザは常に標準バージョンをインポートすべきです。これ自身が accelerated 版のインポートを試みてダメならピュア Python 版を使うようになっています。 pickle / cPickle のペアがこの対象になりました。 profile モジュールは 3.1 でこれが予定されています。 StringIO モジュールは io モジュール内のクラスに変更されました。

  • 関連のあるモジュールのいくつかはパッケージにまとめられ、ふつうサブモジュール名は単純化されました。結果として以下のようなパッケージが出来ました:

    • 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 で取り上げられていない標準ライブラリーの他の変更:

  • sets は廃止されました。組み込みの set() クラスを使用してください。
  • 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() は削除されました。
  • thread モジュールの整理: acquire_lock() ならびに release_lock() は廃止されました。代わりに acquire() ならびに release() を使用してください。
  • random モジュールの整理: jumpahead() API は削除されました。
  • new モジュールは廃止されました。
  • 関数 os.tmpnam()、os.tempnam() および os.tmpfile() は tempfile のため削除されました。
  • tokenize モジュールはバイトでも機能するように変更されました。メインのエントリポイントは generate_tokens から tokenize.tokenize() になりました。
  • string.letters とその仲間 (string.lowercase と string.uppercase) は廃止されました。代わりに string.ascii_letters 等を使用してください。(削除された理由は string.letters とその仲間にロケール固有の挙動があったためです。そのようなものに対して、いつでも使えそうな "定数" として魅力的に名付けるのは良い考えとは言えません。)
  • モジュール __builtin__ が builtins にリネームされました (アンダースコアの削除と 's' の追加)。 大半の大域名前空間における __builtins__ 変数は変更されていません。 組み込みを変更するには __builtins__ でなく builtins を使わなければなりません。

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

  • 組み込みの新しい文字列書式化操作で、文字列の % 演算子を置き換えるものです。(しかしながら % 演算子はまだサポートされます; Python 3.1 で非推奨となり、将来のいつかの時点で削除されます。) 完全な詳細は PEP 3101 をお読み下さい。 (--- 訳注: Python 2.6 で既にあった変更 での対応する記述に書いた訳注を参照。---)

例外に関する変更

例外の送出や捕捉を行う API は整理され、 強力な新機能が追加されました:

  • PEP 352: All exceptions must be derived (directly or indirectly) from BaseException. This is the root of the exception hierarchy. This is not new as a recommendation, but the requirement to inherit from BaseException is new. (Python 2.6 still allowed classic classes to be raised, and placed no restriction on what you can catch.) As a consequence, string exceptions are finally truly and utterly dead.

  • ほとんど全ての例外は、実際は Exception を継承すべきです。 BaseException は最上位で扱われるべき例外、例えば SystemExit や KeyboardInterrupt の基底クラスとしてのみ使われるべきでしす。上記カテゴリーを除く全ての例外を処理するのに推奨されるイディオムは except Exception です。

  • StandardError は削除されました。

  • 例外はシーケンスとして振る舞わなくなりました。代わりに args 属性を使用してください。

  • PEP 3109: 例外の送出。 raise Exception, args ではなく raise Exception(args) としなければなりません。 加えて、トレースバックを明示的に指定することはもう出来ません。 そう しなければならない 場合は、代わりに __traceback__ 属性に直接割り当てることが出来ます (下記参照).

  • PEP 3110: 例外の捕捉。 except SomeException, variable ではなく except SomeException as variable としなければなりません。 その上 except ブロックがある場合 variable は明示的に削除されます。

  • PEP 3134: 例外の連鎖。 暗黙の連鎖と明示的な連鎖の2つの場合があります。 暗黙の連鎖は例外が except や finally 処理ブロックで送出されたときに起こります。 この原因は大抵処理ブロック内のバグです。 これを 二次的な (secondary) 例外と呼びます。 この場合 (処理中の) 元々の例外は二次的な例外の __context__ 属性に保存されます。 明示的な連鎖は以下の構文で起こします:

    raise SecondaryException() from primary_exception

    (primary_exception は例外オブジェクトを生成する任意の式です。たぶんどこかで以前捕捉した例外でしょう。) 今の場合、一次的 (primary) な例外は二次的例外の __cause__ 属性に保存されます。未捕捉の例外が起こった際に表示されるトレースバックは __cause__ と __context__ 属性を渡り歩き、そして一次的例外を一番上に置いて、連鎖のそれぞれの構成要素ごとにトレースバックを分けて表示します。(Java ユーザにはこの振る舞いは御馴染みでしょう。)

  • PEP 3134: 例外オブジェクトがトレースバックを __traceback__ 属性に格納するようになりました。 つまり、例外オブジェクトが例外関連の全情報を持つようになったということです。 sys.exc_info() を使う理由は (削除されていませんが) あまりありません。

  • 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: 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__() は __bool__() に改名されました。

組み込み

  • PEP 3135: 新しくなった super() 。今では super() は引数なしで呼び出せます。(これが class 内で定義される通常のインスタンスメソッド内であると仮定して) 正しいクラスとインスタンスが自動的に選択されます。引数ありの場合の super() の振る舞いには変更はありません。
  • PEP 3111: raw_input() が input() にリネームされました。つまり、新しい input() 関数は sys.stdin から行を読み、末尾の改行を取り除いて返します。入力が時期尚早に終わってしまったら EOFError になります。昔の input() の振る舞いが欲しければ eval(input()) としてください。
  • 新しい組み込み関数 next() が追加されました。 オブジェクトの __next__() メソッドを呼び出します。
  • round() 関数の丸めの戦略と戻り値の型が変更されました。ど真ん中の場合に、四捨五入ではなく最近接偶数への丸めをするようになりました。(例えば round(2.5) は今では 2 を返します。 3 ではなく。) (---訳注: 丸めモードについては Wikipedia 参照。---) 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 ループのほうがより可読性が高いでしょう。
  • reload() は削除されました。 imp.reload() を使用してください。
  • dict.has_key() は削除されました -- 代わりに in 演算子を使用してください。

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

時間がないため、以下のC APIへの変更点のリストは かなり 不完全です。

  • Mac OS 9, BeOS, RISCOS, Irix, Tru64 に限らず、いくつものプラットフォームのサポートが打ち切られました。
  • PEP 3118: 新たなバッファ API。
  • PEP 3121: 例外モジュールの初期化と最終化
  • PEP 3123: PyObject_HEAD を標準的な C に一致。
  • 制限付き実行 の C API サポートはこれ以上されません。
  • PyNumber_Coerce()、PyNumber_CoerceEx()、PyMember_Get()、および PyMember_Set() C APIs は削除されました。
  • 新たな C API PyImport_ImportModuleNoBlock()、PyImport_ImportModule() のように動きますが、インポートロックでブロックしません (代わりにエラーを返します)。
  • ブール変換の C 水準のスロットとメソッドがリネームされました: nb_nonzero が nb_bool になりました。
  • C API から METH_OLDARGS と WITH_CYCLE_GC が削除されました。

性能

3.0 の可搬化 (generalization) による正味の結果は、Python 3.0 を pystone ベンチマークすると Python 2.5 より 10% 遅くなる、というものでした。これはどうやら小さい整数についての特殊処理を削除したことに一番大きな要因があるようです。これには改善の余地がありますが、それは 3.0 リリース以降でしょう!

Python 3.0 への移植

(---訳注: 今では独立したクックブック Python 2 から Python 3 への移植 があるのでそちらをご覧下さい。---) 既存の Python 2.5 や 2.6 のソースコードを Python 3.0 に移植する最良の策は以下の通りです:

  1. (必須:) 優秀なテストカバレッジから始めてください。
  2. Python 2.6 に移植します。Python 2.x を Python 2.(x+1) に移植する普通の作業以上のことをしてはいけません。確実に全てのテストを通してください。
  3. (Still using 2.6:) Turn on the -3 command line switch. This enables warnings about features that will be removed (or change) in 3.0. Run your test suite again, and fix code that you get warnings about until there are no warnings left, and all your tests still pass.
  4. 2to3 をあなたのソースコードツリーに対して走らせます (このツールの詳細については 2to3 - Python 2 から 3 への自動コード変換 をみてください)。Python 3.0 で変換結果のコードを走らせます。何か問題が残っていれば手動で修正し、修正後も全てのテストをパスするようにします。

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 以降) で変更なしで動作するものを必要とすることは、残念ながらまだ多いでしょう (あなたが作っているのがライブラリであるならば)。これについては Python 2 から Python 3 への移植 に少し書かれています。 ---)

C 拡張を Python 3.0 に移植するには、 Python 3 への拡張モジュール移植 を参照してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • What's New in Python »


What's New in Python 2.7

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

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 に記述されています。

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 は 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 両方のユーザをサポートしたいと願うライブラリやフレームワークの開発者向けに、さまざまなツールやガイドがあります。これらは、相応しいアプローチを決めたりある種複雑な技術的詳細の管理をする手助けとなるでしょう。まず手始めには Python 2 から Python 3 への移植 HOWTO ガイドをご覧になることをお奨めします。

Deprecation Warnings の扱いの変更

Python 2.7 では開発者向けの警告をデフォルトで抑止するポリシーが取られました。 DeprecationWarning とそれを継承した警告は、指定されない限りは無視され、アプリケーションのユーザーがその警告を見ないですむようになりました。この変更は Python 3.2 ブランチにも適用されました。 (stdlib-sig で討議され、 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 ではサポートされず、 warning になります。
  • -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 だけが比較されます。

OrderedDict の実装はこうなっています。 key の2重リンクリストを管理し、新しい key が挿入されるときにリストに新しい key を追加します。2つ目の辞書が key を対応するリストノードにマップします。なので、削除時にリンクリストを操作する必要はなく、コストは O(1) に保たれています。

標準ライブラリのいくつかのモジュールで、順序付き辞書の利用がサポートされています。

  • ConfigParser モジュールはデフォルトで順序付き辞書を使います。設定ファイルを読み込み、編集した後、元の順序で書きなおすことができます。
  • collections.namedtuple() の _asdict() メソッドは、タプルの順序と同じ順序の順序付き辞書を返すようになりました。
  • json モジュールのデコーダーが OrderedDict をビルドするのをサポートするために、 JSONDecoder クラスのコンストラクタに object_pairs_hook 引数が追加されました。 PyYAML などの外部のライブラリでもサポートされています。

参考

PEP 372 - 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 - 1000区切りのための書式指定子
PEP written by Raymond Hettinger; implemented by Eric Smith.

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

コマンドライン引数の解析のための argparse モジュールが、 optparse モジュールのより強力な代替として追加されました。

これにより、 Python はコマンドライン引数の解析のために3つの異なるモジュール、 getopt, optparse, argparse を持つことになります。 getopt モジュールは C言語用ライブラリの getopt() 関数に似せてあるので、あとで C 言語で書き直すかもしれないプログラムのプロトタイプを Python で書く場合に役に立ちます。 optparse は冗長になってしまいましたが、まだたくさんのスクリプトが利用していて、それらのスクリプトを自動的に更新する手段が無いので、削除される予定はありません。(argparse API を optparse のインタフェースに適合させる方法も検討されましたが、多くの複雑さと難点のために却下されました)

古いバージョンの 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 - argparse コマンドライン解析モジュール
PEP written and implemented by Steven Bethard.

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

logging モジュールは非常に柔軟です。アプリケーションは logging のサブシステムのツリーを定義できます。このツリーの各ロガーはいくつかのメッセージをフィルターし、異なるフォーマットを行い、メッセージを沢山の種類のハンドラーに渡します。

この柔軟性は、多くの設定を必要とします。オブジェクトを生成してプロパティを設定する Python コードを書くこともできますが、複雑なセットアップをしようとすると退屈なコードを書かないといけなくなります。 logging は設定ファイルのパースを行う fileConfig() 関数を提供していますが、このファイルフォーマットはフィルターの設定をサポートしていませんし、プログラムで生成するのはさらに面倒になります。

Python 2.7 は logging の設定のために辞書を使う dictConfig() 関数を追加しました。いろいろな入力から辞書を作成する方法があります。コードで作ったり、 JSON ファイルをパースしたり、YAMLのパーサーをインストールしてあればそれを使うことができます。詳しい情報は 環境設定のための関数 を参照してください。

以下は、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') と同じになります。
  • LoggerAdapter クラスに meth:~logging.LoggerAdapter.isEnabledFor メソッドが追加されました。 level を引数に取り、ベースの logger がその重要度レベルのメッセージを処理するかどうかを返します。

参考

PEP 391 - logging の辞書ベースの設定
PEP written and implemented by Vinay Sajip.

PEP 3106: 辞書 View

辞書の keys(), values(), items() メソッドは Python 3.x では動作が代わり、完全に実体化されたリストの代わりに、 view と呼ばれるオブジェクトを返すようになりました。

Python 2.7 では、 keys(), values(), items() の動作を変えてしまうと、既存の大量のコードが動かなくなってしまうので、Python 3.x と同じ動作に合わせることはできません。なので、 Python 3.x のメソッドと同じ動作をするメソッドを、別の viewkeys(), viewvalues(), 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 - Revamping dict.keys(), .values() and .items()
PEP written by Guido van Rossum. Backported to 2.7 by Alexandre Vassalotti; 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 - 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.

その他の言語変更

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.

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

  • The with statement can now use multiple context managers in one statement. Context managers are processed from left to right and each one is treated as beginning a new with statement. This means that:

    with A() as a, B() as b:
    ... suite of statements ...

    は、以下と同じです

    with A() as a:
    with B() as b:
        ... suite of statements ...

    contextlib.nested() 関数は非常に似た機能を提供していたので、もう必要なくなり廃止予定となりました。

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

  • 多倍長整数や通常の整数から浮動小数点への変換でも丸め処理が変更され、元の数に一番近い浮動小数点値が返されるようになりました。これは浮動小数点へ完全に変換できる小さい整数では問題になりませんが、桁数に対して精度がどうしても足りない場合に関係します。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.)

    この丸めの動作により、整数同士の true division (from __future__ import division) の結果もより正確になりました。 (Also implemented by Mark Dickinson; bpo-1811.)

  • 複素数に対する暗黙の型強制は削除されました。インタプリタは complex オブジェクトに対して __coerce__() メソッドを呼び出そうとしません。 (Removed by Meador Inge and Mark Dickinson; 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.)

    複素数が format() をサポートするようになりました。デフォルトでは右寄せになります。精度やカンマ区切りの指定は、実部と虚部のそれぞれに対して適用されます。アラインの指定は 1.5+3j のような複素数全体に対して適用されます。 (Contributed by Eric Smith; bpo-1588 and bpo-7988.)

    'F' 書式符号は常に大文字を使って出力するようになり、 'INF' や 'NAN' が出力されるようになりました。 (Contributed by Eric Smith; bpo-3382.)

    低レベルな変更: object.__format__() メソッドは PendingDeprecationWarning を発生させるようになりました。 object に対する __format__() メソッドはオブジェクトを文字列表現に変換してそれをフォーマットするからです。以前は、このメソッドは書式文字列を受け取り文字列表現を返していましたが、この仕様は Python コードのミスを隠してしまう可能性がありました。アライメントや精度のようなフォーマット指定情報を渡した時、そのなにかそのオブジェクトに合ったフォーマットがあることを期待しているはずなのに、 object.__format__() メソッドはそれを無視します。 (Fixed by Eric Smith; bpo-7994.)

  • int() と long() 型に bit_length メソッドが追加されました。このメソッドはその値を2進数で表現したときに何ビット必要になるかを返します:

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

  • The import statement will no longer try an absolute import if a relative import (e.g. from .os import sep) fails. This fixes a bug, but could possibly break certain import statements that were only working by accident. (Fixed by Meador Inge; bpo-7902.)

  • ビルトインの unicode 型のサブクラスが __unicode__() メソッドをオーバーライドできるようになりました。(Implemented by Victor Stinner; bpo-1583863.)

  • bytearray 型の translate() メソッドが第一引数に None を受け入れるようになりました。 (Fixed by Georg Brandl; bpo-4759.)

  • @classmethod や @staticmethod を使ってクラスメソッドやスタティックメソッドを作成した時、そのラッパーオブジェクトがラップ対象となる関数を __func__ 属性で公開するようになりました。(Contributed by Amaury Forgeot d'Arc, after a suggestion by George Sakkis; bpo-5982.)

  • __slots__ を利用して属性を制限した場合に、設定されていない属性を del したときに AttributeError にならなかったのを修正しました。 (Fixed by Benjamin Peterson; bpo-7604.)

  • 2つの新しいエンコーディングが追加されました: "cp720" は主にアラビア文字に使われます。 "cp858" は cp850 の一種ですが、ユーロ記号を追加しています。 (CP720 contributed by Alexander Belchenko and Amaury Forgeot d'Arc in bpo-1616979; CP858 contributed by Tim Hatch in bpo-8016.)

  • file オブジェクトは、POSIX環境に置いてディレクトリを開こうとした時に発生する IOError 例外に filename 属性を設定するようになりました。 (noted by Jan Kaliszewski; bpo-4764) また、読み出し専用のファイルに対する書き込みを、Cライブラリ側のエラー検出・報告に頼るのではなく、明示的にチェックするようになりました。 (fixed by Stefan Krah; bpo-5677).

  • Python の字句解析機は改行をそれ自身に変換するようになりました。それにより、組み込みの compile() 関数がどの改行コードを利用したコードでも受け付けるようになりました。また、コードの終端の改行も不要になりました。

  • 関数宣言中の余分な丸括弧は Python 3.x では不正になりました。つまり、 def f((x)): pass はsyntax errorになります。 Python3 警告モードでは、 Python 2.7 はこの利用方法について警告を出すようになりました。 (Noted by James Lingard; bpo-7362.)

  • 古いスタイルのクラスのオブジェクトに対して弱参照を作れるようになりました。新スタイルクラスには以前から弱参照を利用できます。(Fixed by Antoine Pitrou; bpo-8268.)

  • モジュールオブジェクトがGCされたとき、モジュールの辞書は、他にその辞書への参照を持っているものがない場合にのみクリアされるようになりました。(bpo-7140).

インタプリタの変更

新しい環境変数 PYTHONWARNINGS を使って警告を制御できるようになりました。この環境変数には、 -W スイッチに使われる警告の設定を、カンマ区切りの文字列として指定します。 (Contributed by Brian Curtin; bpo-7301.)

例えば、以下の設定は警告が発生するたびにそれを表示しますが、 Cookie モジュールからの警告はエラーにします。 (環境変数を設定するための文法はOSとシェルに依存します)

export PYTHONWARNINGS=all,error:::Cookie:0

最適化

いくつかの場面でパフォーマンスが向上しています。

  • with 文の初期セットアップを行うための新しいオペコードが追加されました。 __enter__() と __exit__() メソッドの検索を行います。 (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.)

  • GCが循環参照になりえないシンプルなコンテナ型の追跡を避けるようになりました。 Python 2.7 では、アトミックな型(整数、文字列など)のみを含むタプルと辞書は追跡されません。推移的に、アトミックな型のみを含むタプルを含む辞書も、同じく追跡されません。これにより、GCによって巡回されチェックされるオブジェクトの数が減るので、 GCのコストを減らすことができます。 (Contributed by Antoine Pitrou; bpo-4688.)

  • 多倍長整数の内部格納方式が、 2**15 ベースと 2**30 ベースのどちらかをビルド時に選択するようになりました。以前は常に 2**15 ベースで格納していました。 2**30 ベースにすると 64bit マシンに置いては確実にパフォーマンスが向上しますが、 32bit マシンではパフォーマンスが向上する場合も低下する場合もあります。なので、デフォルトでは 64bit マシンでは 2**30 ベースで、 32bit マシンでは 2**15 ベースになるようになります。 Unix では新しい configure オプションとして --enable-big-digits が追加され、このデフォルトの選択をオーバーライドできるようになっています。

    この変更はパフォーマンスの向上以外の形ではユーザーに見えないはずですが、 1つだけ例外があります。テストとデバッグを目的として、 sys.long_info というデータが追加され、内部フォーマットとして digit あたりのビット数と、それに使うCのデータ型のバイト数の情報を提供します:

    >>> import sys
>>> sys.long_info
sys.long_info(bits_per_digit=30, sizeof_digit=4)

    (Contributed by Mark Dickinson; bpo-4258.)

    その他の変更により、多倍長整数オブジェクトのサイズは数バイト小さくなりました。 32bit システムでは 2byte, 64bit システムでは 6byte 小さくなりました。 (Contributed by Mark Dickinson; bpo-5260.)

  • 多倍長整数の除算アルゴリズムが、内部のループの軽量化や乗算からシフト演算への置き換え、不要なイテレーションの削除により高速化されました。いくつかのベンチマークによると、多倍長整数の剰余演算は 50% から 150% 高速化されています。 (Contributed by Mark Dickinson; bpo-5512.) ビット演算も高速化されています。(initial patch by Gregory Smith; bpo-1087418)

  • % の実装が、左側のオペランドが文字列型かどうかをチェックしてその場合の処理を特殊化しました。これにより文字列に対して % を頻繁に使う、テンプレートライブラリなどのアプリケーションのパフォーマンスが1--3%向上します。 (Implemented by Collin Winter; bpo-5176.)

  • if 条件付きのリスト内包表記がより高速なバイトコードにコンパイルされるようになりました。(Patch by Antoine Pitrou, back-ported to 2.7 by Jeffrey Yasskin; bpo-4715.)

  • 整数や多倍長整数から10進文字列への変換を、任意の基数をサポートした汎用の変換関数を使う代わりに10進数に特殊化した処理を行うことで高速化しました。 (Patch by Gawain Bolton; bpo-6713.)

  • 文字列等(str, unicode, bytearray) の split(), replace(), rindex(), rpartition(), rsplit() メソッドが、1文字ずつのスキャンの代わりに高速な逆方向スキャンアルゴリズムを使うようになりました。これにより、場合によっては10倍レベルの高速化になります。(Added by Florent Xicluna; bpo-7462 and bpo-7622.)

  • pickle と cPickle モジュールが、属性名に使われている文字列を自動的にインターンするようになりました。これにより unpickle 後のオブジェクトのメモリ使用量が減ります。(Contributed by Jake McGuire; bpo-5084.)

  • cPickle モジュールが辞書に対する特殊化を行い、 pickle にかかる時間をおよそ半分に減らしました。 (Contributed by Collin Winter; bpo-5670.)

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

全てのリリースに置いて、 Python の標準ライブラリはたくさんの改良とバグ修正がされてきました。ここでは一部の注目に値する変更を、モジュール名で辞書順ソートしてリストアップしています。もっと完全な変更リストが見たければ、ソースツリー内の Misc/NEWS ファイルか、全ての完全な詳細が入っている Subversion のログを参照してください。

  • bdb モジュールの基底デバッガクラス Bdb に、モジュールをスキップする機能が追加されました。コンストラクタは django.* のような glob スタイルのパターンをもった iterable を引数として受け取ります。デバッガはパターンのどれかにマッチするスタックフレームにステップインしません。 (Contributed by Maru Newby after a suggestion by Senthil Kumaran; bpo-5142.)

  • binascii モジュールが buffer API をサポートするようになり、 memoryview インスタンスやその他のバッファオブジェクトともに利用できるようになりました。 (Backported from 3.x by Florent Xicluna; bpo-7703.)

  • bsddb モジュールが pybsddb パッケージ の 4.7.2devel9 から 4.8.4 に更新されました。新しいバージョンはより Python 3.x との互換性がよくなり、いくつかのバグ修正と、いくつかの新しい BerkeleyDB のフラグとメソッドが追加されています。 (Updated by Jesús Cea Avión; bpo-8156. The pybsddb changelog can be read at http://hg.jcea.es/pybsddb/file/tip/ChangeLog.)

  • bz2 モジュールの BZ2File がコンテキストマネージャープロトコルをサポートするようになりました。これにより、 with bz2.BZ2File(...) as f: といった書き方ができます。 (Contributed by Hagen Fürstenau; 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.

    新しいクラス 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.)

    Mapping 抽象基底クラスが、他の Mapping でない型と比較されたときに NotImplemented を返すようになりました。(Fixed by Daniel Stutzbach; bpo-8729.)

  • ConfigParser モジュールのパーサークラスのコンストラクタが allow_no_value 引数を受け取るようになりました。これはデフォルトでは False です。真の場合、値のないオプションが利用できるようになります。例えば:

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

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

  • cookielib モジュールが不正な、値が整数値ではないバージョンフィールドを持つ cookie を無視するようになりました。(Fixed by John J. Lee; bpo-3924.)

  • copy モジュールの deepcopy() 関数が、束縛ずみインスタンスメソッドを正しくコピーするようになりました。(Implemented by Robert Collins; bpo-1515.)

  • ctypes モジュールが、ポインタとして宣言された引数に対して None が渡された場合常に C の NULL ポインタに変換するようになりました。(Changed by Thomas Heller; bpo-4606.) 基盤となっている libffi ライブラリ が 3.0.9 にアップデートされ、いくつかのプラットフォームにおけるいろいろな問題が修正されました。(Updated by Matthias Klose; bpo-8142.)

  • 新しいメソッド: datetime モジュールの timedelta クラスに total_seconds() メソッドが追加されました。これはその期間の秒数を返します。(Contributed by Brian Quinlan; bpo-5788.)

  • 新しいメソッド: Decimal クラスに、浮動小数点数から Decimal への正確な変換を行う from_float() クラスメソッドが追加されました。この正確な変換は、浮動小数点数が示す値に一番近い近似となる10進数を求めます。なので、このメソッドを使ったとしてもある程度の誤差は残ります。例えば、 Decimal.from_float(0.1) は Decimal('0.1000000000000000055511151231257827021181583404541015625') を返します。 (Implemented by Raymond Hettinger; bpo-4796.)

    Decimal のインスタンスと浮動小数点数の比較は、オペランドの値に応じた賢い結果を返すようになりました。以前はこの比較は Python のデフォルトのオブジェクト比較にフォールバックし、オペランドの型に応じて不定な結果が返されていました。ただし、 Decimal と浮動小数点数を加算などの他の演算で組み合わせることはいまでも許可されていません。浮動小数点数と Decimal の間の変換方法を明示的に指定するべきです。(Fixed by Mark Dickinson; bpo-2531.)

    Decimal のコンストラクタが浮動小数点数を受け入れるようになりました。 (added by Raymond Hettinger; bpo-8257) また、アラビア・インド数字などの、ヨーロッパ以外の Unicode 文字も受け入れるようになりました。 (contributed by Mark Dickinson; bpo-6595).

    Context クラスのほとんどのメソッドが Decimal インスタンスと同じく整数を受け入れるようになりました。例外は canonical() と is_canonical() メソッドだけです。 (Patch by Juan José Conti; bpo-7633.)

    Decimal インスタンスを文字列の format() メソッドで利用した場合、デフォルトのアライメントが左揃えから、数値型に適した右揃えに変更されました。 (Changed by Mark Dickinson; bpo-6857.)

    signaling NaN (あるいは sNAN) との比較は、暗黙に比較演算に応じて真偽値を返すのではなく、 InvalidOperation 例外を発生させるようになりました。 Quiet NaN (あるいは NaN) はハッシュ可能になりました。 (Fixed by Mark Dickinson; bpo-7279.)

  • difflib モジュールの出力が、ファイル名を含むヘッダのセパレータにスペースではなくタブ文字を使うようになり、最近の diff/patch ツールとの互換性が高くなりました。(Fixed by Anatoly Techtonik; bpo-7585.)

  • Distutils sdist コマンドが、 MANIFEST.in や setup.py ファイルが変更されていなくても、ユーザーが作成したかもしれない新しいファイルが含まれるようにするために、毎回 MANIFEST ファイルを再生成するようになりました。 (Fixed by Tarek Ziadé; bpo-8688.)

  • doctest モジュールの IGNORE_EXCEPTION_DETAIL フラグが、テストされている例外を含むモジュールの名前を無視するようになりました。 (Patch by Lennart Regebro; bpo-7490.)

  • email モジュールの Message クラスが Uniode値のペイロードを受け入れるようになり、自動的に output_charset で指定されたエンコーディングに変換するようになりました。 (Added by R. David Murray; bpo-1368247.)

  • Fraction クラスが、コンストラクタの引数として、 1つの float 値、 Decimal インスタンス、 2つの有理数を受け入れるようになりました。(Implemented by Mark Dickinson; rationals added in bpo-5812, and float/decimal in bpo-8294.)

    fraction と complex 数の間の順序比較演算 (<, <=, >, >=)が TypeError 例外を発生させるようになりました。これは過失を修正し、 Fraction を他の数値型とマッチさせます。

  • 新しいクラス: FTP_TLS が ftplib に追加されました。認証とその後の制御・データ転送をTLSカプセル化することでセキュアなFTP接続を提供します。 (Contributed by Giampaolo Rodola; bpo-2054.)

    バイナリデータのアップロードを行う storbinary() に rest 引数が追加され、アップロードのリスタートができるようになりました。 (patch by Pablo Mouzo; bpo-6845.)

  • 新しいクラスデコレータ: functools モジュールに total_ordering() が追加されました。 __eq__() と、 __lt__(), __le__(), __gt__(), __ge__() のいづれか1つを定義したクラスを受け取り、残りの比較メソッドを生成します。 __cmp__() メソッドが Python 3.x では廃止されたので、順序のあるクラスを定義するのを簡単にするためにこのデコレータがあります。(Added by Raymond Hettinger; 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.)

  • gzip モジュールの GzipFile がコンテキストマネージャープロトコルをサポートしました。 with gzip.GzipFile(...) as f: と書くことができます。(contributed by Hagen Fürstenau; bpo-3860 また、 io.BufferedIOBase ABC を実装しています。なので、より高速な処理のために io.BufferedReader でラップすることができます。 (contributed by Nir Aides; bpo-7471). さらに、コンストラクタにオプションのタイムスタンプを指定することで、 gzip ファイル内の変更時間レコードをオーバーライドすることができるようになりました。 (Contributed by Jacques Frechet; bpo-4272.)

    gzip ファイルフォーマットのファイルは最後にゼロバイトによるパディングができるようになりました。 gzip モジュールは末尾のゼロバイトを消費します。(Fixed by Tadek Pietraszek and Brian Curtin; bpo-2846.)

  • 新しい属性: hashlib モジュールに algorithms 属性が追加されました。これはサポートしているアルゴリズムを含むタプルです。 Python 2.7 では、 hashlib.algorithms は ('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512') が含まれています。 (Contributed by Carl Chenet; bpo-7418.)

  • httplib モジュールで使われているデフォルトの HTTPResponse クラスがバッファリングをサポートし、HTTPレスポンスをより高速に読み込めるようになりました。 (Contributed by Kristján Valur Jónsson; bpo-4879.)

    HTTPConnection と HTTPSConnection クラスが source_address 引数として (host, port) の2要素タプルを受け取るようになりました。これは接続のソースアドレスとして利用されます。 (Contributed by Eldon Ziegler; bpo-3972.)

  • ihooks モジュールが相対 import をサポートしました。 ihooks import をカスタマイズするための古いモジュールで、 Python 2.0 で追加された imputil モジュールに取って変わられていることに注意してください。 (Relative import support added by Neil Schemenauer.)

  • imaplib モジュールが IPv6 アドレスをサポートするようになりました。 (Contributed by Derek Morr; 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.

  • 更新されたモジュール: io ライブラリが、Python 3.1 に同梱されるバージョンに更新されました。 3.1 では、I/O ライブラリは完全に C で書き直され、処理されるタスクに依って 2 から 20 倍速くなりました。元の Python バージョンは _pyio モジュールに改名されました。

    結果の軽微な変更: io.TextIOBase クラスは、エンコーディングやデコーディングのエラーに使われるエラー設定 ('strict', 'replace', 'ignore' のいずれか) を与える errors 属性を持つようになりました。

    io.FileIO クラスは、無効なファイルディスクリプタを渡されたときに OSError を送出するようになりました。(Implemented by Benjamin Peterson; bpo-4991.) truncate() メソッドは、ファイル位置を保存するようになりました。以前は、ファイル位置を新しいファイルの末尾に変更しました。(Fixed by Pascal Chambon; 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.)

    itertools.combinations() および itertools.product() は、以前は入力のイテレート可能オブジェクトより大きい r に ValueError を返していました。これは仕様エラーと認められ、空のイテレータを返すようになりました。(Fixed by Raymond Hettinger; bpo-4816.)

  • 更新されたモジュール: json モジュールが、エンコーディングやデコーディングを高速化する C 拡張を含んだ、 simplejson パッケージのバージョン 2.0.9 にアップグレードされました。 (Contributed by Bob Ippolito; bpo-4136.)

    新しい collections.OrderedDict 型をサポートするために、 json.load() はオプションとして、任意のオブジェクトリテラルに対して呼び出され、ペアのリストにデコードする object_pairs_hook パラメタを追加しました。(Contributed by Raymond Hettinger; bpo-5381.)

  • mailbox モジュールの Maildir クラスは、読み込むディレクトリのタイムスタンプを記録し、その後に更新時刻が変わった場合にのみ再読み込みするようになりました。これは不必要なディレクトリ走査を避けることでパフォーマンスを向上させます。(Fixed by A.M. Kuchling and Antoine Pitrou; bpo-1607951, bpo-6896.)

  • 新しい関数: math モジュールは、誤差関数と相補誤差関数 erf() および erfc() 、 e**x - 1 を exp() から 1 を引くのよりも高い精度で計算する expm1() 、ガンマ関数 gamma() 、そしてガンマ関数の自然対数 lgamma() を追加しました。 (Contributed by Mark Dickinson and nirinA raseliarison; bpo-3366.)

  • multiprocessing モジュールの Manager* クラスに、サブプロセスの開始時に呼び出される呼び出し可能オブジェクトと、それに渡される引数群を渡すことができるようになりました。 (Contributed by lekma; bpo-5585.)

    ワーカプロセスのプールを制御する Pool クラスに、オプションの maxtasksperchild パラメタが追加されました。ワーカプロセスはこれで指定された数のタスクを処理したら、退出して Pool に新しいワーカーを開始させます。これは、タスクがメモリその他のリソースをリークし得るときや、ワーカをとても大きくしてしまうようなタスクがあるときに便利です。 (Contributed by Charles Cazabon; bpo-6963.)

  • nntplib モジュールは、IPv6 アドレスをサポートするようになりました。 (Contributed by Derek Morr; 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. Support for initgroups added by Jean-Paul Calderone; bpo-7333.)

    os.fork() 関数は、子プロセス中で import ロックを再初期化するようになりました。これは、Solaris における fork() がスレッドから呼び出された時の問題を修正します。(Fixed by Zsolt Cserna; bpo-7242.)

  • os.path モジュールの、 normpath() および abspath() 関数は、Unicode を保存するようになりました。入力パスが Unicode なら、戻り値も Unicode 文字列になります。 (normpath() fixed by Matt Giuca in bpo-5827; abspath() fixed by Ezio Melotti in bpo-3426.)

  • pydoc モジュールは、Python が使う様々なシンボルのヘルプを追加しました。例えば、 help('<<') や help('@') とできるようになりました。(Contributed by David Laban; 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.)

  • 新しい関数: shutil モジュールの make_archive() は、ファイル名、アーカイブ型 (zip または tar-format)、およびディレクトリパスを取って、そのディレクトリの内容を含むアーカイブを生成します。(Added by Tarek Ziadé.)

    shutil の copyfile() および copytree() 関数は、名前付きパイプのコピーを求められたときに SpecialFileError 例外を送出する様になりました。以前は、コードは、名前付きパイプを、通常のファイルのように読み込み用に開いて扱い、いつまでもブロックしていました。 (Fixed by Antoine Pitrou; bpo-3002.)

  • signal モジュールは、シグナルハンドラを本当に必要でない限り再インストールしなくなりました。これで、EINTR シグナルを確実に捕えられないバグが修正されました。(Fixed by Charles-Francois Natali; bpo-8354.)

  • 新しい関数: site モジュールの、新しい関数群は様々なサイトおよびユーザに特有のパスを返します。 getsitepackages() は、全てのグローバル site-packages ディレクトリを含むリストを返します。 getusersitepackages() は、ユーザの site-packages ディレクトリのパスを返します。そして、 getuserbase() は、データの保存に使えるディレクトリへのパスを与える、 USER_BASE 環境変数の値を返します。 (Contributed by Tarek Ziadé; bpo-6693.)

    site モジュールは sitecustomize モジュールが import されたときに例外を報告するようになり、 KeyboardInterrupt 例外が捕捉されて飲み込まれることはなくなりました。 (Fixed by Victor Stinner; bpo-3137.)

  • create_connection() 関数は、接続に使われるソースアドレスを与える (host, port) の 2-タプル、 source_address パラメタを追加しました。 (Contributed by Eldon Ziegler; bpo-3972.)

    recv_into() および recvfrom_into() メソッドは、バッファ API をサポートするオブジェクト、最も便利なのは bytearray や memoryview 、に書きこむようになりました。 (Implemented by Antoine Pitrou; bpo-8104.)

  • SocketServer モジュールの TCPServer クラスは、ソケットタイムアウトと Nagle アルゴリズムの無効化をサポートするようになりました。 disable_nagle_algorithm クラス属性は、デフォルトで False です。上書きされて真になると、新しいリクエスト接続は、TCP_NODELAY オプションを設定され、一つの TCP パケットにたくさんの小さな送信がバッファリングされることを防ぎます。 timeout クラス属性は、リクエストソケットに適用されるタイムアウトを秒で保持できます。その時間内にリクエストが受け付けられなければ、 handle_timeout() が呼び出され、 handle_request() が返されます。(Contributed by Kristján Valur Jónsson; bpo-6192 and bpo-6267.)

  • 更新されたモジュール: sqlite3 モジュールが pysqlite パッケージ のバージョン 2.6.0 にアップデートされました。バージョン 2.6.0 はいくつかのバグ修正を含み、共有ライブラリから SQLite 拡張をロードできるようになりました。拡張を有効にするには enable_load_extension(True) メソッドを呼び出し、そして特定の共有ライブラリをロードするには load_extension() を呼び出してください。 (Updated by Gerhard Häring.)

  • ssl モジュールの SSLSocket オブジェクトは、バッファ API をサポートするようになりました。これは、テストスイートの障害を修正します (fix by Antoine Pitrou; bpo-7133)。また、OpenSSL の SSL_MODE_AUTO_RETRY を自動的に設定することで、 recv() 演算によって SSL 再ネゴシエーションを引き起こすエラーコードが返されるのを防ぎます (fix by Antoine Pitrou; bpo-8222)。

    The ssl.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. (Added by Antoine Pitrou; bpo-8322.)

    その他の変更により、拡張はOpenSSL の全ての暗号とメッセージダイジェストアルゴリズムをロードし、それらすべてが利用できるようにします。SSL 証明書の中には検証できないものもあり、"unknown algorithm" エラーを報告します。 (Reported by Beda Kosata, and fixed by Antoine Pitrou; bpo-8484.)

    OpenSSL の、使われるバージョンは、モジュール属性 ssl.OPENSSL_VERSION (文字列)、 ssl.OPENSSL_VERSION_INFO (5-タプル)、および ssl.OPENSSL_VERSION_NUMBER (整数) として利用できるようになりました。 (Added by Antoin Pitrou; bpo-8321.)

  • struct モジュールは、値が特定の整数フォーマットコード (bBhHiIlLqQ のいずれか) に対して大きすぎるときに、オーバーフローエラーを静かに無視しなくなりました。これは必ず struct.error 例外を送出するようになりました。 (Changed by Mark Dickinson; bpo-1523.) pack() 関数は、非整数を変換してパックするのに、 __int__() メソッドを試したりエラーを報告したりする前に、 __index__() の使用も試すようになりました。 (Changed by Mark Dickinson; 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.)

    subprocess モジュールは、 EINTR シグナルを受け取り次第内部システムコールを最施行するようになりました。(Reported by several people; final patch by Gregory P. Smith in bpo-1068268.)

  • 新しい関数: symtable モジュールの is_declared_global() は、明示的に global と宣言された引数には真、暗示的に global である引数には偽を返します。(Contributed by Jeremy Hylton.)

  • syslog モジュールは、識別子として、以前デフォルトであった 'python' の値ではなく、 sys.argv[0] の値を使うようになりました。 (Changed by Sean Reifschneider; bpo-8451.)

  • sys.version_info の値は、属性名 major, minor, micro, releaselevel, および serial を持つ名前付きタプルになりました。 (Contributed by Ross Light; bpo-4285.)

    sys.getwindowsversion() もまた、属性名 major, minor, build, platform, service_pack, service_pack_major, service_pack_minor, suite_mask, および product_type を持つ名前付きタプルを返します。(Contributed by Brian Curtin; bpo-7766.)

  • tarfile モジュールのデフォルトエラー処理が変更され、致命的なエラーを抑制しないようになりました。デフォルトのエラーレベルは以前は 0 で、エラーはメッセージとしてデバッグログに書き込まれるだけでしたが、デバッグログはデフォルトでは活性化されていないため、エラーは顧みられませんでした。デフォルトのエラーレベルは 1 になり、エラーがあれば例外が送出されます。 (Changed by Lars Gustäbel; bpo-7357.)

    tarfile は、tar ファイルに追加される TarInfo オブジェクトのフィルタリングをサポートするようになりました。 add() を呼び出したとき、オプションの呼び出し可能オブジェクトである filter 引数を与えることができます。 filter オブジェクトには、ファイルが追加される度に TarInfo を渡され、これを変形して返せます。このオブジェクトが None を返したら、そのファイルは結果のアーカイブから除かれます。これは既存の exclude 引数より強力で、それゆえこれは非推奨となります。(Added by Lars Gustäbel; bpo-6856.) TarFile クラスはまた、コンテキストマネージャプロトコルもサポートするようになりました。(Added by Lars Gustäbel; bpo-7232.)

  • threading.Event クラスの wait() メソッドは、終了時に内部フラグを返すようになりました。 wait() は内部フラグが真になるまでブロックすることを想定されているため、この関数は通常真を返すことになります。この戻り値は、タイムアウトが与えられ、オペレーションがタイムアウトした時のみ偽になります。 (Contributed by Tim Lesher; bpo-1674032.)

  • unicodedata モジュールに提供される Unicode データベースは、どの文字が数字や空白文字か、または改行を表すかを決定するために、内部で使われるようになりました。このデータベースはまた、 Unihan.txt データファイルからの情報も含みます (patch by Anders Chrigström and Amaury Forgeot d'Arc; bpo-1571184)。また、バージョン 5.2.0 にアップデートされました (updated by Florent Xicluna; bpo-8024)。

  • urlparse モジュールの urlsplit() は、未知の URL スキームを RFC 3986 に応じた方法で処理します。 URL が "<something>://..." の形式なら、 :// の前のテキストを、それがモジュールの知らない作り物のスキームであってさえ、スキームとして扱います。この変更は、古い働きを使って動作していたコードを破壊することがあります。例えば、Python 2.6.4 や 2.5 は以下を返します:

    >>> 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 では、これは普通のタプルではなく名前付きタプルを返すので、実際は微妙に異なる出力をします。)

    urlparse モジュールは、 RFC 2732 で定義された IPv6 リテラルアドレスもサポートします (contributed by Senthil Kumaran; 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.)

  • エレメントツリーライブラリ、 xml.etree は、 (<?xml-stylesheet href="#style1"?> のような) 命令や (<!-- comment --> のような) コメントを処理する XML を出力するとき、アンパサンドや山括弧をエスケープしなくなりました。 (Patch by Neil Muller; bpo-2746.)

  • xmlrpclib と SimpleXMLRPCServer によって提供される XML-RPC クライアントおよびサーバは、HTTP/1.1 keep-alive をサポートし、場合によっては gzip エンコーディングを使って XML の送受を圧縮することで、パフォーマンスが向上しました。gzip 圧縮は SimpleXMLRPCRequestHandler の encode_threshold 属性によって制御されます。これはバイト数で、これより大きな応答は圧縮されます。 (Contributed by Kristján Valur Jónsson; bpo-6267.)

  • zipfile モジュールの ZipFile は、コンテキストマネジメントプロトコルをサポートし、 with zipfile.ZipFile(...) as f: と書けるようになりました。 (Contributed by Brian Curtin; bpo-5511.)

    zipfile は、空のディレクトリのアーカイブ化をサポートするようになり、これを正しく解凍します。(Fixed by Kuba Wieczorek; bpo-4710.) アーカイブ内のファイルの読み込みが速くなり、 read() および readline() の割り込みが正しく働くようになりました。(Contributed by Nir Aides; bpo-7610.)

    is_zipfile() 関数は、以前受け付けられていたパス名に加え、ファイルオブジェクトも受け付けるようになりました。 (Contributed by Gabriel Genellina; bpo-4756.)

    writestr() メソッドは、 ZipFile コンストラクタで指定されたデフォルトの圧縮メソッドをオーバライドする、オプションの compress_type パラメタを追加しました。 (Contributed by Ronald Oussoren; 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.htm. Some screenshots of the Python/Ttk code in use are at https://code.google.com/archive/p/python-ttk/wikis/Screenshots.wiki.

ttk モジュールは Guilherme Polo によって書かれ、 bpo-2983 に追加されました。 Tile.py と呼ばれる別バージョン Tile.py は、 Martin Franklin によって書かれ、Kevin Walzer によってメンテナンスされているもので、組み込みが bpo-2618 で提案されましたが、著者は Guilherme Polo の作品のほうがより包括的であると主張しました。

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

unittest モジュールが大幅に改善されました。多くの新機能が追加されました。それらの機能のほとんどは、特に注釈のない限り、 Michael Foord によって実装されました。このモジュールの改善された版は、 Python バージョン 2.4 から 2.6 で使うために、 https://pypi.org/project/unittest2 から unittest2 パッケージとして別にダウンロードできます。

When used from the command line, the module can automatically discover tests. It's not as fancy as py.test or nose, 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.)

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

進捗メッセージは、verbose モードで実行したとき、期待された失敗に 'x' を、期待されない成功に 'u' を表示するようになりました。(Contributed by Benjamin Peterson.)

テストケースは、テストをスキップするために SkipTest 例外を送出します。(bpo-1034053).

assertEqual(), assertTrue(), および assertFalse() 失敗のメッセージは、提供する情報量が増えました。 TestCase クラスの longMessage 属性を真に設定すると、失敗時に、標準のエラーメッセージと追加して提供したメッセージの両方が表示されます。(Added by Michael Foord; bpo-5663.)

assertRaises() メソッドは、実行する呼び出し可能オブジェクトを与えずに呼び出されたとき、コンテキストハンドラを返すようになりました。例えば、こう書くことができます:

with self.assertRaises(KeyError):
    {}['foo']

(Implemented by Antoine Pitrou; bpo-4444.)

モジュールレベルおよびクラスレベルの設定と、ティアダウンフィクスチャがサポートされました。モジュールは、 setUpModule() および tearDownModule() 関数を含むことができます。クラスは setUpClass() および tearDownClass() メソッドを含むことができ、これらは (@classmethod や透過なものを使って) クラスメソッドとして定義しなければなりません。これらの関数とメソッドは、テストランナーが別のモジュールやクラスのテストケースに切り替えるときに呼び出されます。

メソッド addCleanup() および doCleanups() が追加されました。 addCleanup() で、無条件に呼び出されるクリーンアップ関数を (setUp() が失敗したら setUp() の後に、そうでなければ tearDown() の後に) 追加できるようにします。これにより、テスト中のリソースの配置と解放が簡潔になります。(bpo-5679).

より特化したテストを提供するメソッドがいくつか追加されました。これらのメソッドの多くは、Google のエンジニアたちによってそのテストスイートのために書かれました。Gregory P. Smith, Michael Foord, and GvR が、これを unittest の Python 版にマージしました。

  • assertIsNone() および assertIsNotNone() はひとつの式を取り、その結果が None であるか、またはないかを確かめます。
  • assertIs() および assertIsNot() は、2 つの値を取り、その評価が同一のオブジェクトであるか、またはないかを確かめます。 (Added by Michael Foord; bpo-2578.)
  • assertIsInstance() および assertNotIsInstance() は、結果のオブジェクトが特定のクラス、またはタプルにあるクラスのいずれかのインスタンスであるかを調べます。(Added by Georg Brandl; bpo-7031.)
  • assertGreater(), assertGreaterEqual(), assertLess(), および assertLessEqual() は、二つの量を比較します。
  • assertMultiLineEqual() は 2 つの文字列を比較し、等しくなければ、2 文字列の差分をハイライトする有益な比較を表示します。この比較は、Unicode 文字列が assertEqual() で比較されるときのデフォルトに使われるようになりました。
  • assertRegexpMatches() および assertNotRegexpMatches() は、第一引数が第二引数として与えられた正規表現にマッチする、またはしない文字列であるかどうかを調べます。 (bpo-8038)
  • assertRaisesRegexp() は、特定の式が送出されるかを調べ、そしてまたその式の文字列表現が与えられた正規表現にマッチするかを調べます。
  • assertIn() および assertNotIn() は、 first が second に属するか、または属さないかを調べます。
  • assertItemsEqual() は、2 つの与えられたシーケンスが同じ要素を含むかを調べます。
  • assertSetEqual() は、2 つの集合が等しいか比較し、エラーの場合のみ、集合間の差分を報告します。
  • 同様に、 assertListEqual() および assertTupleEqual() は、指定された型を比較し、差分を説明しますが、完全な値を表示するとはかぎりません。これらのメソッドは、リストやタプルを assertEqual() で比較するときにデフォルトで使われるようになりました。より一般的には、 assertSequenceEqual() は 2 つのシーケンスを比較し、必要なら両方のシーケンスが特定の型であるかを調べます。
  • assertDictEqual() は、二つの辞書を比較し、差分を報告します。これは、辞書を assertEqual() で比較するときにデフォルトで使われるようになりました。 assertDictContainsSubset() は、 first に属するキー/値の対の全てが second に現れるかを調べます。
  • assertAlmostEqual() および assertNotAlmostEqual() は、 first と second がほぼ等しいかを判定します。このメソッドは、オプションで指定された places (デフォルトは 7) の数に差を丸めてそれをゼロと比べるか、差が与えられた delta の値より小さいことを要求します。
  • loadTestsFromName() は、 TestLoader の suiteClass 属性を適切に受け入れます。(Fixed by Mark Roddy; bpo-6866.)
  • 新しいフックにより、 assertEqual() メソッドを拡張して新しいデータ型を扱わせられます。 addTypeEqualityFunc() メソッドは型オブジェクトと関数を取ります。この関数は、比較される両方のオブジェクトが特定の型であるときに使われます。この関数は、2 つのオブジェクトを比較し、マッチしなければ例外を送出するべきです。この関数が、新しいシーケンス比較メソッドがするように、2 つのオブジェクトがなぜマッチしないのかについて追加の情報を提供するのがいいアイデアです。

unittest.main() はオプションの exit 引数を取るようになりました。偽の場合、 main() は sys.exit() を呼び出さず、これにより対話型インタプリタから main() が使えるようになります。(Contributed by J. Pablo Fernández; bpo-3379.)

TestResult に、テストランの直前と直後に呼び出される startTestRun() および stopTestRun() が追加されました。 (Contributed by Robert Collins; bpo-5728.)

これら一連の変更により、 unittest.py は無様に大きくなったので、モジュールはパッケージとなり、コードは複数のファイルに分割されました (by Benjamin Peterson)。これは、モジュールをインポートして使う方法には影響しません。

参考

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)

    XML を解析するときのエラーは、 ParseError 例外を送出するようになりました。この例外のインスタンスは、問題の位置を与える (line, column) タプルを含む position 属性を持ちます。

  • ツリーを文字列に変換する ElementTree のコードが大幅に改善され、多くの場合でおおよそ 2 倍速くなりました。 ElementTree.write() および Element.write() メソッドは、 method パラメタを追加し、これは "xml" (デフォルト), "html", または "text" にできます。HTML モードは、空の要素を <empty/> ではなく <empty></empty> として出力し、text モードは要素を無視し、テキストのチャンクのみ出力します。要素の tag 属性を None に設定してその子はそのままにすると、ツリーが書き出されるとき、その要素は省かれるので、それ以上再編成することなく要素を一つ取り除けます。

    名前空間の操作も改善されました。すべての 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)

  • 新しい Element メソッド: iter() は、要素の子をジェネレータとして与えます。また、 for child in elem: と書いて要素の子に渡ってループできます。既存のメソッド getiterator() と、子のリストを構成して返す getchildren() は、非推奨になりました。

  • 新しい Element メソッド: itertext() は、その要素の子孫であるテキストのチャンクを全て与えます。例えば:

    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 は ElementTree を開発し、1.3 バージョンを作成しました。 1.3 を解説した彼の記事を http://effbot.org/zone/elementtree-13-intro.htm で読めます。 Florent Xicluna は、python-dev および bpo-6472 での議論の後、 Python に含まれるバージョンをアップデートしました。

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

Python のビルド過程と C API の変更は以下の通りです:

  • GNU デバッガ、GDB 7、の最新のリリースは Python を使って書けます 実行可能なプログラム P のデバッグを始めるとき、GDB は P-gdb.py という名前のファイルをロックし、それを自動的に読み込みます。Dave Malcolm は Python 自体をデバッグするときに便利ないくつかのコマンドを加える python-gdb.py に貢献しました。例えば、 py-up および py-down は、通常いくつかの C スタックフレームに対応する、 Python のスタックフレームを上がったり下がったりします。 py-print は、Python 変数の値を表示し、 py-bt は、 Python スタックトレースを表示します。(Added as a result of bpo-8032.)

  • Python に備え付けの .gdbinit ファイルを使うと、デバッグされているスレッドが GIL をほじしていないとき、2.7 バージョンの "pyo" マクロが正常に動くようになりました。このマクロは、表示の前にこれを取得するようになりました。 (Contributed by Victor Stinner; bpo-3632.)

  • Py_AddPendingCall() はスレッドセーフになり、ワーカスレッドがメイン Python スレッドに通知を投入することができるようになりました。これは特に、非同時性の IO 処理に便利です。(Contributed by Kristján Valur Jónsson; bpo-4293.)

  • 新しい関数: PyCode_NewEmpty() は、空のコードオブジェクトを生成します。要求されるのは、ファイル名、関数名、そして最初の行番号だけです。これは、より便利なトレースバックスタックを構成しようとする拡張モジュールに便利です。以前は、このような拡張はより多くの引数を必要とする PyCode_New() を呼び出す必要がありました。(Added by Jeffrey Yasskin.)

  • 新しい関数: PyErr_NewExceptionWithDoc() は、既存の PyErr_NewException() と同じように新しい例外クラスを生成しますが、新しい例外クラスの docstring を含む、追加の char * 引数を取ります。(Added by 'lekma' on the Python bug tracker; bpo-7033.)

  • 新しい関数: PyFrame_GetLineNumber() はフレームオブジェクトを取り、そのフレームが現在実行している行番号を返します。以前は、コードは現在実行しているバイトコード命令のインデクスを得て、それからそのアドレスに対応する行番号を探索する必要がありました。(Added by Jeffrey Yasskin.)

  • 新しい関数: PyLong_AsLongAndOverflow() および PyLong_AsLongLongAndOverflow() は、C の long や long long のような Python の長整数に近いです。この数が出力型に適合するには大きすぎるなら、 overflow フラグが設定され、呼び出し元に返されます。(Contributed by Case Van Horsen; bpo-7528 and bpo-7767.)

  • 新しい関数: 文字列から浮動小数点数への変換から由来する、新しい PyOS_string_to_double() 関数が追加されました。古い PyOS_ascii_strtod() および PyOS_ascii_atof() は、非推奨となりました。

  • 新しい関数: PySys_SetArgvEx() は、 sys.argv の値を設定し、 updatepath に依ってオプションで sys.path を更新して sys.argv[0] で指名されたスクリプトを含むディレクトリを含めることができます。

    この関数は、Python を埋め込んだアプリケーションのセキュリティホールを塞ぐために追加されました。古い関数 PySys_SetArgv() は、必ず sys.path を更新し、これはカレントディレクトリを追加することがあります。これにより、Python を埋め込んだアプリケーションを別の誰かが制御するディレクトリで実行すると、攻撃者がディレクトリにトロイの木馬モジュール(例えば、 os.py という名前のファイル) を仕込み、インポートさせ実行させる事ができました。

    Python を埋め込んだ C/C++ アプリケーションを保守しているなら、 PySys_SetArgv() を呼び出していないか調べ、 updatepath を偽に設定した PySys_SetArgvEx() を使うべきかよく考えてください。

    bpo-5753 で CVE-2008-5983 として報告され、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.)

  • 取り除かれた関数: PyEval_CallObject は、マクロとしてのみ利用できるようになりました。関数版は、ABI リンク互換性を保つために残されましたが、それは 1997 年のことです。今となっては削除するべきです。(Removed by Antoine Pitrou; bpo-8276.)

  • 新しいフォーマットコード: PyFormat_FromString(), PyFormat_FromStringV(), および PyErr_Format() 関数は、C の long long 型を表示する %lld および %llu フォーマットを受け付けるようになりました。(Contributed by Mark Dickinson; 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.)

  • Py_Finalize() 関数は、内部の threading._shutdown() 関数を呼び出します。これにより、インタプリタがシャトダウンするときに送出が防がれる例外があります。(Patch by Adam Olsen; bpo-1722344.)

  • PyMemberDef 構造を使って型の属性を定義する際、Python はもはや T_STRING_INPLACE 属性を削除または設定させようとはしません。

  • ctypes によって定義されたグローバルシンボルには、 Py または _ctypes が接頭されるようになりました。(Implemented by Thomas Heller; bpo-3102.)

  • 新しい設定オプション: --with-system-expat スイッチにより、 pyexpat モジュールをビルドして、システム Expat ライブラリを使えます。 (Contributed by Arfrever Frehtes Taifersar Arahesis; bpo-7609.)

  • 新しい設定オプション: --with-valgrind オプションは、 Valgrind メモリエラー検出器が正しく分析するのが難しい pymalloc アロケータを無効にするようになりました。ですから Valgrind は、メモリリークやオーバーランをより検出できます。 (Contributed by James Henstridge; bpo-2422.)

  • 新しい設定オプション: --with-dbmliborder= に空の文字列を与えて様々な DBM モジュールを全て無効にできます。 (Added by Arfrever Frehtes Taifersar Arahesis; bpo-6491.)

  • configure スクリプトは、ある種の 32-bit Intel チップ上の浮動小数点丸めバグを調べ、 X87_DOUBLE_ROUNDING プリプロセッサ定義を定義します。現在この定義を使うコードはありませんが、使うことを望む人がいたら使えます。(Added by Mark Dickinson; bpo-2937.)

    configure はまた、C++ リンクをサポートする LDCXXSHARED Makefile を設定するようになりました。 (Contributed by Arfrever Frehtes Taifersar Arahesis; bpo-1222585.)

  • ビルドプロセスは、pkg-config サポートに必要なファイルを生成するようになりました。(Contributed by Clinton Roy; bpo-3585.)

  • ビルドプロセスは、Subversion 1.7 をサポートするようになりました。 (Contributed by Arfrever Frehtes Taifersar Arahesis; bpo-6094.)

カプセル

Python 3.1 は、拡張モジュールに C API を提供する新しい C データ型 PyCapsule を追加しました。カプセルは、本質的には C の void * ポインタのホルダであり、モジュール属性として利用できるようになります。例えば、 socket モジュールの API は socket.CAPI として公開されていて、 unicodedata は ucnhash_CAPI を公開しています。その他の拡張はモジュールを import し、辞書にアクセスしてカプセルオブジェクトを取得し、そしてモジュールの様々な API 関数へのポインタの配列を指す void * ポインタを取得できます。

これに使われる既存のデータ型 PyCObject がありますが、これは型安全性を提供しません。pure Python で書かれた邪悪なコードは、 PyCObject をモジュール A から取り、どうにかしてそれをモジュール B の PyCObject で代えることで、セグメンテーション違反を起こし得ます。カプセルは自身の名前を知っていて、ポインタを得るには名前を提供しなければなりません:

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 は、様々な拡張モジュール API を提供するためにカプセルを内部的に使うようになりましたが、カプセルを処理するために PyCObject_AsVoidPtr() が CObject インタフェースとのコンパイル時互換性は保ったまま変更されました。 PyCObject_AsVoidPtr() を使うと PendingDeprecationWarning が合図されますが、デフォルトでは言及されません。

Implemented in Python 3.1 and backported to 2.7 by Larry Hastings; discussed in bpo-5630.

ポート特有の変更: Windows

  • msvcrt モジュールは、 crtassem.h からのいくつかの定数を追加しました。 CRT_ASSEMBLY_VERSION, VC_ASSEMBLY_PUBLICKEYTOKEN, および LIBRARIES_ASSEMBLY_NAME_PREFIX. (Contributed by David Cournapeau; bpo-4365.)
  • レジストリへのアクセスのための _winreg モジュールは、以前サポートされていた関数群の引数を増やした拡張版である CreateKeyEx() および DeleteKeyEx() を実装しました。 DisableReflectionKey(), EnableReflectionKey(), および QueryReflectionKey() もテストされ、ドキュメント化されました。(Implemented by Brian Curtin: bpo-7347.)
  • 新しい _beginthreadex() API がスレッドの開始に使われ、ネイティブのスレッドローカルストレージ間数が使われるようになりました。(Contributed by Kristján Valur Jónsson; bpo-3582.)
  • os.kill() 関数が Windows で働くようになりました。このシグナル値は定数 CTRL_C_EVENT, CTRL_BREAK_EVENT, その他の整数にできます。最初の 2 定数は Control-C および Control-Break 打鍵イベントをサブプロセスに送ります。その他の値は、 TerminateProcess() API を使います。(Contributed by Miki Tebeka; bpo-1220212.)
  • os.listdir() 関数は、空のパスに対してちゃんと失敗するようになりました。 (Fixed by Hirokazu Yamamoto; bpo-5913.)
  • mimelib モジュールは、初期化の際に Windows レジストリから MIME データベースを正しく読みこむようになりました。 (Patch by Gabriel Genellina; bpo-4969.)

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

  • 追加されたパッケージを、システムインストレーションとユーザがインストールした同じバージョンのコピーで共有するために、 sys.path に /Library/Python/2.7/site-packages が追加されました。 (Changed by Ronald Oussoren; 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)

ポート特有の変更: FreeBSD

  • FreeBSD 7.1 の、他のルーティングテーブルを選択するための getsockopt()/setsockopt() で使われている SO_SETFIB 定数が、 socket モジュールで使えるようになりました。(Added by Kyle VanderBeek; 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.)
  • 既存の対応する .py が存在する .pyc または .pyo ファイルからモジュールを import するとき、結果のコードオブジェクトの co_filename 属性は、元のファイル名が古くなったとき、上書きされます。これは、ファイルがリネーム、移動、異なるパスを通したアクセスをされたときに起こりえます。(Patch by Ziga Seilnacht and Jean-Paul Calderone; bpo-1180193.)
  • regrtest.py スクリプトは、テストを乱順に実行する -r オプションの、ランダムシードに使われる整数を取る --randseed= スイッチを取るようになりました。 -r オプションは、使われたシードも報告します。 (Added by Collin Winter.)
  • もう一つの regrtest.py スイッチは -j で、いくつのテストを並行して実行するかを指定する整数です。これにより、マルチコア機での合計実行時間を短縮できます。このオプションは、実行時間を長くすることで知られている -R スイッチなど、いくつかの他のオプションと互換です。 (Added by Antoine Pitrou, bpo-6152.) これはまた、選ばれたテストを失敗するまでループして実行する -F スイッチとも同時に使えます。(Added by Antoine Pitrou; bpo-7312.)
  • スクリプトとして実行されるとき、 py_compile.py モジュールは標準入力を読み込んでコンパイルするファイル名のリストとする '-' を引数として受け付けるようになりました。(Contributed by Piotr Ożarowski; bpo-8233.)

Python 2.7 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

  • range() 関数は、引数をより一貫して処理するようになりました。浮動小数点数でもなく整数でもない引数が与えられたら、その __int__() を呼び出すようになりました。(Fixed by Alexander Belopolsky; bpo-1533.)
  • 文字列 format() メソッドは浮動小数点数および複素数に使われるデフォルトの精度を、 str() で使われる精度に合わせ、小数第 6 位から 12 位に変更しました。 (Changed by Eric Smith; bpo-5920.)
  • with 文の最適化のため、特殊メソッド __enter__() および __exit__() はオブジェクトの型に属さなければならず、オブジェクトのインスタンスには直接取り付けられません。これは (object から導出された) 新スタイルクラスと C 拡張型に影響します。 (bpo-6101.)
  • Python 2.6 におけるバグのため、 __exit__() の exc_value パラメタははよく、例外のインスタンスではなく文字列表現になっていました。これは 2.7 では修正され、 exc_value は期待通りインスタンスになります。 (Fixed by Florent Xicluna; bpo-7853.)
  • __slots__ を利用して属性を制限した場合に、設定されていない属性を del したときに AttributeError にならなかったのを修正しました。 (Fixed by Benjamin Peterson; bpo-7604.)

標準ライブラリでは:

  • 年がサポートされている範囲外にはみ出るような datetime インスタンスの演算が、 OverflowError を送出しないことがありました。このようなエラーはより注意深く調べられ、例外を送出するようになりました。(Reported by Mark Leander, patch by Anand B. Pillai and Alexander Belopolsky; bpo-7150.)

  • Decimal インスタンスを文字列の format() メソッドに使うとき、デフォルトの揃えは以前は左揃えでした。これは右揃えに変更され、プログラムの出力が変わるかもしれません。(Changed by Mark Dickinson; bpo-6857.)

    signaling NaN (あるいは sNAN) との比較は、暗黙に比較演算に応じて真偽値を返すのではなく、 InvalidOperation 例外を発生させるようになりました。 Quiet NaN (あるいは NAN) はハッシュ可能になりました。 (Fixed by Mark Dickinson; bpo-7279.)

  • ElementTree ライブラリ xml.etree は、 (<?xml-stylesheet href="#style1"?> のような) 命令や (<!-- comment --> のような) コメントを処理する XML を出力するときにアンパサンドおよび角括弧をエスケープしなくなりました。 (Patch by Neil Muller; bpo-2746.)

  • StringIO オブジェクトの readline() メソッドは負の長さが要求されたとき、ほかのファイル風オブジェクトと同じように、何もしなくなりました。(bpo-7348)

  • syslog モジュールは、識別子として、以前デフォルトであった 'python' の値ではなく、 sys.argv[0] の値を使うようになりました。 (Changed by Sean Reifschneider; bpo-8451.)

  • tarfile モジュールのデフォルトエラー処理が変更され、致命的なエラーを抑制しないようになりました。デフォルトのエラーレベルは以前は 0 で、エラーはメッセージとしてデバッグログに書き込まれるだけでしたが、デバッグログはデフォルトでは活性化されていないため、エラーは顧みられませんでした。デフォルトのエラーレベルは 1 になり、エラーがあれば例外が送出されます。 (Changed by Lars Gustäbel; bpo-7357.)

  • urlparse モジュールの urlsplit() は、未知の URL スキームを RFC 3986 に応じた方法で処理します。 URL が "<something>://..." の形式なら、 :// の前のテキストを、それがモジュールの知らない作り物のスキームであってさえ、スキームとして扱います。この変更は、古い働きを使って動作していたコードを破壊することがあります。例えば、Python 2.6.4 や 2.5 は以下を返します:

    >>> 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)
  • 非推奨となった古い PyOS_ascii_strtod() および PyOS_ascii_atof() 関数の代わりに、新しい PyOS_string_to_double() 関数を使ってください。

Python を埋め込んだアプリケーションでは:

  • PySys_SetArgvEx() 関数が追加され、既存の PySys_SetArgv() 関数が使われた時のセキュリティホールを塞ぐことができるようになりました。 PySys_SetArgv() を呼び出していないか調べ、 updatepath を偽に設定した PySys_SetArgvEx() を使うべきかよく考えてください。

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

Python 2.7 メンテナンスリリースでは、正真正銘それが求められる状況では、新しい機能が追加される場合があります。そのような追加のどんなものでも Python Enhancement Proposal プロセスを通過しなければなりません。Python 3 だけに新しい機能を追加することによっても Python Package Index に公開することによってもいずれでも十分ではないと言えるだけのやむにやまれない理由付けが必要です。

個別の提案は以下にリストしますが、全ての Python 2.7 メンテナンスリリースに追加される新しい -3 警告は除いています。

Two new environment variables for debug mode

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

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

バージョン 2.7.15 で追加.

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

PEP 434 は、Pythonと一緒に出荷されるIDLE開発環境に変更を加えるための一般的な免除事項を説明します。これは、IDLE の開発者 が Python 2 と 3 のすべてのサポートされているバージョン間でより一貫したユーザーエクスペリエンスを提供するためのものです。

全ての IDLE の変更についての詳細は、個別のリリースについてのNEWS ファイルを参照してください。

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

PEP 466 は、 Python 2.7 メンテナンスリリースに含めることを認められた数多くのネットワークセキュリティ強化についての提案を記述しています。それら変更の最初のものは Python 2.7.7 に初めて登場しました。

Python 2.7.7 に PEP 466 関連で追加された機能:

  • hmac.compare_digest() が Python 3 からバックポートされました。これにより Python 2 アプリケーションで timing attack resistant comparison operation が利用可能になります (Contributed by Alex Gaynor; bpo-21306.)
  • python.org で公開される公式 Windows インストーラのビルドに使う OpenSSL が 1.0.1g にアップグレードされました . (Contributed by Zachary Ware; bpo-21462.)

Python 2.7.8 に PEP 466 関連で追加された機能:

  • hashlib.pbkdf2_hmac() が Python 3 からバックポートされました。これにより Python 2 アプリケーションでも、安全なパスワード格納に広範に使うのに相応しいハッシュアルゴリズムが利用できます (Contributed by Alex Gaynor; bpo-21304.)
  • python.org で公開される公式 Windows インストーラのビルドに使う OpenSSL が 1.0.1h にアップグレードされました (contributed by Zachary Ware in bpo-21671 for CVE-2014-0224)

Python 2.7.9 に PEP 466 関連で追加された機能:

  • Python 3.4 の ssl モジュールのほとんどがバックポートされました。つまり ssl は今や、Server Name Indication, TLS1.x 設定, platform certificate store へのアクセス, SSLContext クラス, その他機能が使えます (Contributed by Alex Gaynor and David Reid; bpo-21308.)

    個別の詳細については、モジュールのドキュメンテーション内の "バージョン 2.7.9 で追加" の注釈を参照してください。

  • os.urandom() は、呼び出しのたびに /dev/urandom を開きなおす代わりに /dev/urandom のファイル記述子をキャッシュするように変更されました。(Contributed by Alex Gaynor; bpo-21305.)

  • hashlib.algorithms_guaranteed と hashlib.algorithms_available が Python 3 からバックポートされました。これにより Python 2 アプリケーションが可能な限り最強のハッシュアルゴリズムを選択するのが容易になります (Contributed by Alex Gaynor in bpo-21307)

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

PEP 477 が Python 2.7 メンテナンスリリースに PEP 453 ensurepip モジュール, それによって可能になるドキュメンテーションの改善を含めることを認め、Python 2.7.9 リリースではじめてお披露目されました。

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

新しい ensurepip モジュール( PEP 453 で定義されています)は標準のクロスプラットフォームのメカニズムで、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 の通りプラットフォームのパッケージャは、プラットフォームでのそれらインストールの単純明快な手段を自身が提供する(普通システムのパッケージマネージャ)からと言う理由で、デフォルトでのこれらコマンドのインストールを選択しないかもしれません。

ドキュメントの変更

この変更の一部は、 Python モジュールのインストール と Python モジュールの配布 セクションがより手短な始め方として完全にデザインし直されたことと、FAQ ドキュメントです。ほとんどのパッケージングについてのドキュメンテーションは Python Packaging User Guide が保守している Python Packaging Authority に移動されて、独立したプロジェクトのドキュメンテーションになっています。

ですが、この移行は現在のところまだ少し不完全ですので、これらのガイドのレガシーなバージョンは Python モジュールのインストール (旧版) と Python モジュールの配布 (レガシーバージョン) に残してあります。

参考

PEP 453 -- Python インストールの際の明示的なpipのブートストラッピング
PEP は Donald Stufft と Nick Coghlan によって書かれ、Donald Stufft, Nick Coghlan, Martin von Löwis, Ned Deily により実装されました。

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

PEP 476 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 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 for details.

(Contributed by Victor Stinner in bpo-23404.)

バージョン 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.

(Contributed by Victor Stinner in bpo-23404.)

バージョン 2.7.14 で変更.

謝辞

著者は、以下の方々がこの記事の多くの草稿に提案、修正、そして助力を差し伸べてくださったことに感謝の意を表したいと思います: Nick Coghlan, Philip Jenvey, Ryan Lovett, R. David Murray, Hugh Secker-Walker.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • What's New in Python »


What's New in Python 2.6

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

What's New in Python 2.6

著者: A.M. Kuchling (amk at amk.ca)

この文書は Python 2.6 の新機能について解説します。 Python 2.6 は 2008 年 10 月 1 日にリリースされました。リリーススケジュールは PEP 361 に記述されています。

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 などとすることが出来ます。

新しいコマンドラインオプション -3 で、Python 3.0 で削除される機能についての警告を受け取ることが出来ます。このスイッチで、3.0 にコードを移植するためにはどの程度の仕事が必要になるのか知ることが出来るでしょう。この値は Python コードからもアクセス出来て、ブーリアン値 sys.py3kwarning と、C 拡張 API では Py_Py3kWarningFlag です。

参考

Python 3.0 についての提案を含む PEP は 3xxx シリーズにあります。 PEP 3000 は Python 3.0 の開発プロセスについて記述しています。Python 3.0 の全般的な目標について記述している PEP 3100 から始めて、個別の機能についての提案のこれより番号が高い PEP を探索してみてください。

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

2.6 の開発の間で、Python 開発プロセスは 2 つの重要な変更を経験しました: SourceForge の課題トラッカーから、カスタイマイズした Roundup インストレーションに乗り換えました。また、ドキュメントは LaTeX から reStructuredText に変換しました。

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

もう随分長いこと Python 開発者たちは、SourceForge のバグトラッカーにイライラを高め続けてきました。SourceForge がホストするソリューションには全くカスタマイズの余地がなく、たとえば課題のライフサイクルをカスタマイズ出来ませんでした。

そのようなわけで、Python Software Foundation のインフラ委員会はボランティアたちに課題トラッカーについて、異なるプロダクトのセットアップをし、SourceForge からバグ報告とパッチのインポートをする依頼の呼び掛けをしました。4 つのトラッカーが試されました: Jira, Launchpad, Roundup, Trac です。委員会は結果として Jira と Roundup の 2 つを候補に据えました。Jira はフリーソフトウェアプロジェクトの無償でのホストが可能な商用製品です; Roundup はそれを運営するボランティアとそれをホストするサーバが必要なオープンソースプロダクトです。

ボランティアへの呼び掛けののち、新しい Roundup インストレーションが https://bugs.python.org にセットアップされました。Roundup の一つのインストレーションは複数のトラッカーをホスト出来るため、このサーバは今では Jython と Python ウェブサイトのための課題トラッカーもホストしています。間違いなく将来はほかのものもホストするでしょう。可能な場所では、"What's New in Python" のこのエディションでは、それぞれの変更についてのバグ/パッチの Roundup アイテムにリンクします。

Python バグトラッカーのホスティングは、南アフリカの Stellenbosch による Upfront Systems が快く提供してくれています。Martin von Löwis が SourceForge からバグ報告とパッチをインポートするのに多大な労力を払いました; 彼によるこのインポート操作のためのスクリプトは http://svn.python.org/view/tracker/importer/ にあります。これは SourceForge から Roundup へ移行したいと考えているほかのプロジェクトにも役に立つでしょう。

参考

https://bugs.python.org
Python のバグトラッカー。
http://bugs.jython.org:
Jython のバグトラッカー。
http://roundup.sourceforge.net/
Roundup のダウンロードとドキュメント。
http://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 にすればいいでしょ、と持ちかけるのですが、良い変換を達成することにとらわれて、誰一人として仕事を完遂させようと時間を捧げることはしませんでした。

2.6 の開発サイクルの期間に、Georg Brandl はドキュメンテーションの処理のための新たなツールチェインの構築に多大な労力を払いました。 その成果であるパッケージは Sphinx と呼ばれ、 http://sphinx-doc.org/ で入手出来ます。

Sphinx は HTML 出力に集中し、人を惹きつけるスタイルでモダンな HTML を生成します。印刷出力は LaTeX への変換を経由することで健在です。入力のフォーマットは reStructuredText です。これはカスタムな拡張とディレクティブをサポートしているマークアップ文法で、Python コミュニティでは広く使われています。

Sphinx は執筆に使えるスタンドアロンのパッケージです。そして 2 ダースに届かんばかりのプロジェクトが(Sphinx ウェブサイトのリスト)、ドキュメンテーションツールとして Sphinx を採用しました。

参考

Documenting Python
Python ドキュメントの書き方について書いています。
Sphinx
Sphinx ツールチェインのドキュメントとコードです。
Docutils
縁の下の力持ちになっている reStructuredText のパーサとツールセットです。

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

The previous version, Python 2.5, added the 'with' statement as an optional feature, to be enabled by a from __future__ import with_statement directive. In 2.6 the statement no longer needs to be specially enabled; this means that with is now always a keyword. The rest of this section is a copy of the corresponding section from the "What's New in Python 2.5" document; if you're familiar with the 'with' statement from Python 2.5, you can skip this section.

'with' ステートメントは、以前なら後片付けが実行されるのを確実にするために try...finally ブロックを使ったであろうようなコードを、より単純明快にします。このセクションでは、このステートメントの普通の使い方を説明します。続くセクションでは実装の詳細を調べ、このステートメントとともに使うためにオブジェクトをどうやって書けば良いかをお見せします。

'with' ステートメントは基本構造が以下となる制御フロー構造です:

with expression [as variable]:
    with-block

expression は評価されて結果がコンテキスト管理プロトコルをサポートするオブジェクトにならなければなりません (具体的にはメソッド __enter__() と __exit__() を持つオブジェクト)。 ( 訳注: Python ドキュメント全体で context manager protocol と context management protocol とで不統一。同じものです。 )

with-block が呼び出される前に、 __enter__() が呼ばれるので、セットアップコードをそこで実行出来ます。それは variable 名(与えられた場合)に束縛されることになる値も返します(注意深く読んで下さい、つまり variable には expression の結果が代入される のではない のです)。

with-block ブロックの実行が終了後、ブロックが例外を送出する場合であろうとオブジェクトの __exit__() が呼び出されますので、ここで後片付けコードを実行出来ます。

いくつかの Python 標準オブジェクトが既にコンテキスト管理プロトコルをサポートしていて、 'with' とともに使えます。ファイルオブジェクトがその一例です:

with open('/etc/passwd', 'r') as f:
    for line in f:
        print line
        ... more processing code ...

このステートメントが実行し終わったあかつきには、 f のファイルオブジェクトは、たとえ for ループが道半ばにして例外と成り果てても、自動的にクローズされます。

注釈

このケースでは、 f は open() が作ったオブジェクトと同じです。これはファイルオブジェクトの file.__enter__() が 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()

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

Under the hood, the 'with' statement is fairly complicated. Most people will only use 'with' in company with existing objects and don't need to know these details, so you can skip the rest of this section if you like. Authors of new objects will need to understand the details of the underlying implementation and should keep reading.

コンテキスト管理プロトコルの高度な説明はこんなです:

  • expression は評価されて、 "コンテキストマネージャ(context manager)" にならなければなりません。コンテキストマネージャは __enter__() メソッドと __exit__() メソッドを持っていなければなりません。
  • コンテキストマネージャの __enter__() メソッドが呼び出されます。これの戻り値は VAR に代入されます。 as VAR 節がない場合は、この値は単に捨てられます。
  • BLOCK 内のコードが実行されます。
  • BLOCK が例外を起こした場合、コンテキストマネージャの __exit__() メソッドが 3 つの引数とともに呼び出されます。これは例外の詳細です (type, value, traceback, これは sys.exc_info() が返す値と同じで、例外が起こらなければ None です)。そのメソッドの戻り値は例外を再送出するかどうかを制御します: 全ての偽の値ではその例外が再送出され、 True では揉み消します。例外を揉み消すなど滅多なことでは欲しいと思わないでしょう。もしそうしてしまったら、 'with' ステートメントを含んだコードの作者は何か間違ったことが起こったことに決して気付かないですから。
  • BLOCK が例外を起こさなかった場合も __exit__() メソッドが呼び出されます。ただし type, value, traceback は全て 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"

__enter__() メソッドはとっても簡単で、トランザクションを開始する必要があるだけです。このアプリケーションでは、カーソルオブジェクトを結果とすることが有用なので、メソッドはそれを返しましょう。ユーザはこれにより as cursor をその 'with' ステートメントにつけて、そのカーソルを変数名に束縛できます:

class DatabaseConnection:
    ...
    def __enter__(self):
        # Code to start a new transaction
        cursor = self.cursor()
        return cursor

__exit__() メソッドはそれがほとんどの仕事をしなければならない場所なので、もっと複雑です。メソッドは例外が起こったのかどうかをチェックし、例外が起こっていなければトランザクションをコミットし、例外があればロールバックしなければいけません。

下記のコード内では実行がメソッドの末尾まで落ちていって、なのでデフォルトの 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:
    ...

The contextlib module also has a nested(mgr1, mgr2, ...) function that combines a number of context managers so you don't need to write nested 'with' statements. In this example, the single 'with' statement both starts a database transaction and acquires a thread lock:

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 - "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 ディレクトリ

Python を実行すると、モジュール検索パス sys.path にはパスが "site-packages" で終わるディレクトリが普通含まれます。このディレクトリは、ローカルにインストールされる機器を使う全てのユーザが使えるパッケージあるいは固有のサイトインストレーションを持つ場所として意図されています。

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 - ユーザごとの 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 - multiprocessing パッケージの追加
PEP 著 Jesse Noller と Richard Oudkerk; 実装 Richard Oudkerk と Jesse Noller.

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

Python 3.0 では % 演算子を補う、より強力な文字列フォーマッティングメソッドの format() が作られました。これをサポートする str.format() メソッドが Python 2.6 にバックポートされています。

2.6 では 8 ビット文字列と Unicode 文字列の両方が .format() メソッドを持ち、文字列をテンプレートとみなして、フォーマットに使われるべき引数を受け取ります。フォーマッティングのテンプレートには波括弧 ({, }) が特殊文字として使われます:

>>> # 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: 進化版文字列フォーマッティング
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 - 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 - 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

C API のレベルでは、Python 3.0 は既存の 8 ビット文字列型の名前を変えます。Python 2.x での PyStringObject は PyBytesObject になります。Python 2.6 では PyBytesObject(), PyBytes_Check(), PyBytes_FromStringAndSize() をはじめとする全ての文字列関数とマクロを #define を使ってサポートしています(訳注: pure Python レベルと同じく単なる PyString_* の別名として)。

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 - 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 はディスクへの一切の書き込みをせずに単純にメモリ内に全てをバッファします。

    (Python 2.6 では io.StringIO は pure Python で書かれているので、かなり遅いです。ですから今のところは既存の StringIO モジュール か cStringIO モジュールに留まっておくべきです。Python 3.0 の io モジュールは、ある時点で速度のために C に書き直されます。そしておそらくその実装は 2.x リリースにバックポートされます ( 訳注: 2.7 で実現 ) 。)

Python 2.6 では根底にある実装が io モジュールのクラスの上に組み立てられるようには再構築されていません (訳注: Python HowTo の移植ガイドにも触れられている通り、2.7 も同じです)。このモジュールは 3.0 への前方互換のコードを書くのを容易にするために、また、開発者たちがバッファリング I/O とテキスト I/O を自身で書く労力を省くために提供されています。

参考

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 はメモリが書き込み可能でなければならないことを指示します。
  • PyBUF_LOCK は読み出し専用もしくはメモリの排他ロックを要求します。
  • PyBUF_C_CONTIGUOUS と PyBUF_F_CONTIGUOUS は C-contiguous (最後の次元が最初に動きます) または Fortran-contiguous (最初の次元が最初に動きます) の行列レイアウトを要求します。 (訳注: 日本でも馴染みのある用語ではいわゆる column-major order (列優先)、 row-major order (行優先) です。)

PyArg_ParseTuple() のための 2 つの新しい書式化コード s* と z* は、パラメータとしてロックされたバッファオブジェクトを返します。

参考

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 - 抽象基底クラスの導入
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 - 整数リテラルのサポートと文法
PEP 著 Patrick Maupin、2.6 へのバックポートは Eric Smith による。

PEP 3129: クラスデコレータ

デコレータが拡張されて関数だけでなクラスにも使えるようになりました。今やこのように書くのは合法です:

@foo
@bar
class A:
  pass

これは次と等価です:

class A:
  pass

A = foo(bar(A))

参考

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 - 数値の型階層
PEP 著: Jeffrey Yasskin.

Guile マニュアルの Scheme's numerical tower 。

R5RS Scheme 仕様の Scheme's number datatypes 。

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

  • hasattr() 関数は __getattr__() メソッドが例外を起こすと何か失敗したのだと仮定して、全て捕捉して無視して False を返していました。ですがそのロジックは KeyboardInterrupt と SystemExit まで捕まえるべきではなかったのです。Python 2.6 では hasattr() はもはやそれら例外に出会ってもそれを捨てません。 (Fixed by Benjamin Peterson; 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.)

    同時に、 *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.)

  • 新しいビルトイン next(iterator, [default]) は指定したイテレータより次のアイテムを返します。 iterator が使い果たされている場合、 default 引数が与えられていれがこれを、そうでなければ StopIteration 例外を起こします。 (Backported in 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.)

    ほか math モジュールに isinf() と isnan() が追加されています; 浮動小数点数が、前者は無限大ならば、後者は非数ならばそれぞれ真を返します。 (bpo-1640)

    浮動小数点数を 16 進表記文字列に変換する変換関数が追加されています (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.)

  • __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.)

  • GeneratorExit 例外が Exception ではなく BaseException のサブクラスになっています。 except Exception: をする例外ハンドラが意図せず GeneratorExit 捕捉してしまうことがなくなります。 (Contributed by Chad Austin; bpo-1537.)

  • ジェネレータオブジェクトが、そのジェネレータを返すオリジナルのコードオブジェクトを参照する gi_code 属性を持つようになりました。 (Contributed by Collin Winter; bpo-1473257.)

  • ビルトイン関数 compile() が位置引数だけでなくキーワード引数も受け付けるようになりました。 (Contributed by Thomas Wouters; bpo-1444529.)

  • complex() コンストラクタが括弧で囲まれた複素数表現文字列を受け付けるようになっています。 complex(repr(cplx)) で元に戻せるということです。例えば complex('(3+4j)') は今では値 (3+4j) を返します。 (bpo-1491866)

  • 文字列の translate() メソッドが変形テーブルパラメータとして None を受け付けるようになりました。そのまま同じものを返す変形として扱われます。これにより文字を削除する操作を実行するのが簡単になります。 (Contributed by Bengt Richter and implemented by Raymond Hettinger; bpo-1193128.)

  • ビルトインの dir() 関数が、受け取ったオブジェクトの __dir__() メソッドをチェックするようになりました。このメソッドはそのオブジェクトで妥当な属性名を含む文字列のリストを返さなければなりません。これにより dir() が生成する値を制御出来ます。 __getattr__() や __getattribute__() メソッドを使うオブジェクトはこれを使うことで、約束するつもりの擬似属性を公表出来ます。 (bpo-1591665)

  • インスタンスメソッドオブジェクトが、そのメソッドを包含するオブジェクトと関数のための新たな属性を持つようになっています; im_self への新しい別名が __self__ です。また im_func も __func__ として利用可能です。古い名前は Python 2.6 で引き続きサポートされますが、3.0 ではいなくなります。

  • An obscure change: when you use the locals() function inside a class statement, the resulting dictionary no longer returns free variables. (Free variables, in this case, are variables referenced in the class statement that aren't attributes of the class.)

最適化

  • warnings モジュールが C で書き直されました。これにより警告をパーサから発行出来、また、インタプリタの起動が高速化しています。 (Contributed by Neal Norwitz and Brett Cannon; bpo-1631171.)

  • 型オブジェクトがメソッドのキャッシュを持つようになっています。これは個別のクラスについての正しいメソッド実装を見つけるのに必要な仕事を減らします。いったんキャッシュされれば、インタプリタは呼び出さなければならない正しいメソッドを知るために基底クラス群を横断しなくてもよくなります。基底クラスやクラス自身が修正されれば、Python の動的な振る舞いの面においても正しくあり続けなければならないので、キャッシュはクリアされます。 (Original optimization implemented by Armin Rigo, updated for Python 2.6 by Kevin Jacobs; bpo-1700288.)

    デフォルトではこの変更は、Python コアに含まれる型のみに適用されます。拡張モジュールは必ずしもこのキャッシュに互換ではなく、拡張モジュールはメソッドキャッシュを有効にするために、モジュールの tp_flags フィールドに明示的に Py_TPFLAGS_HAVE_VERSION_TAG を追加しなければなりません。(このメソッドキャッシュに対して互換であるためには、拡張モジュールのコードは、それが実装するどんな型についても tp_dict メンバに直接アクセスしたり修正したりしてはなりません。ほとんどのモジュールはこれをしていませんが、Python インタプリタがそれを検知することは出来ません。 bpo-1878 にいくらかの議論がありますので参照してください。)

  • キーワード引数を使う関数呼び出しが、素早くポインタで比較することで顕著に高速化しています。これは常に文字列丸ごとを比較する時間を省きます。 (Contributed by Raymond Hettinger, after an initial implementation by Antoine Pitrou; 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 を使うことでメモリ使用が減りました。

  • with ステートメントが __exit__() メソッドをスタック上に保存するようになり、ちょっとだけ高速化しました。 (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 のログを参照してください。

  • asyncore と asynchat モジュールが再び活発に保守され、多数のパッチとバグ修正が適用されました。 (Maintained by Josiah Carlson; see bpo-1736190 for one patch.)

  • bsddb モジュールは新しいメンテナ Jesús Cea Avión を得て、パッケージは今ではスタンドアロンのパッケージとして入手可能です。パッケージのウェブページは www.jcea.es/programacion/pybsddb.htm です。このモジュールは Python 3.0 では標準ライブラリからは削除される予定です。というのも、これの更新ペースは Python のそれよりも遥かに頻繁だからです。

    bsddb.dbshelve モジュールは pickle 化で、プロトコル 1 に制限するのではなく利用出来る一番高いプロトコルバージョンを使うようになりました。(Contributed by W. Barnes.)

  • cgi モジュールが HTTP POST リクエストのクエリ文字列を読み取るようになりました。これにより URL に "/cgi-bin/add.py?category=1" のようにクエリ文字列を含む form アクションに使えるようになります。 (Contributed by Alexandre Fiori and Nubis; bpo-1817.)

    parse_qs(), parse_qsl() 関数を cgi モジュールから urlparse モジュールに移動しました。もとのバージョンは cgi モジュールにまだいて、2.6 では呼び出すと PendingDeprecationWarning メッセージが報告されます。 (bpo-600362).

  • cmath モジュールに大掛かりな改訂が行われました。Mark Dickinson と Christian Heimes による貢献です。5 つの新しい関数が追加されました:

    • polar() は複素数を極形式 (polar form) に変換し、複素数の絶対値 (modulus) と偏角 (argument) を返します。
    • rect() はその逆で、絶対値と偏角から対応する複素数に戻します。
    • phase() は複素数の偏角 (angle とも呼ばれています) を返します。
    • isnan() はその引数の実数部か虚数部のどちらかが NaN であれば真を返します。
    • isinf() はその引数の実数部か虚数部のどちらかが無限大であれば真を返します。

    その改訂では、 cmath モジュールの数値的安定性も改善されました。全ての関数で、結果の実数部、虚数部は最小精度単位で少しの範囲内で、可能な限り正確です。詳細は 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' での一貫性のある方法で処理するようになりました。

  • collections モジュールに新しいデータ型が追加されています: namedtuple(typename, fieldnames) は、添え字だけでなく名前でもアクセス出来るフィールドを持った標準タプルのサブクラスを作るファクトリ関数です。例えば:

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

    標準ライブラリのいくつかの箇所で namedtuple インスタンスを返すように修正されています。例えば Decimal.as_tuple() メソッドは sign, digits, exponent フィールドを持った名前付きタプルを返すようになりました。

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

  • Cookie モジュールの Morsel オブジェクトが httponly 属性をサポートするようになりました。いくつかのブラウザでは、この属性を付けたクッキーは JavaScript コードからアクセスや操作が出来ません。 (Contributed by Arvin Schnell; 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.)

  • decimal モジュールが the General Decimal Specification のバージョン 1.55 に更新されました。新しい機能には exp() や 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.)

  • ビルトイン関数の reduce() が functools モジュールでも利用可能です。Python 3.0 ではビルトイン関数は削除されて functools のものだけが使えます; 現在のところ 2.x シリーズでビルトイン版を削除する計画はありません。 (Patched by Christian Heimes; bpo-1739906.) (---訳注: 2.7 でも削除されていません。使用を検出するには -3 オプションなどで警告をチェックしてください。 ---)

  • 可能な場合には、 getpass モジュールはプロンプトメッセージ出力とパスワードの読み取りに /dev/tty を使うようになりました。利用出来ない場合は標準エラー出力と標準入力が使われます。端末に入力パスワードがエコーされるかもしれない場合、プロンプト表示の前に警告が出力されます。 (Contributed by Gregory P. Smith.)

  • glob.glob() 関数が、Unicode パスが使われるかディレクトリ内に Unicode ファイル名がマッチすると Unicode ファイル名を返すようになりました。 (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.)

  • 省略可能パラメータ timeout が httplib.HTTPConnection と HTTPSConnection クラスのコンストラクタに追加されました。タイムアウトを秒で指定します。 (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.)
    • fsum() はイテラブルからの数列を、部分和の計算を通じて精度の損失を避けながら積み上げた合計の計算をします。 (Contributed by Jean Brouwers, Raymond Hettinger, and Mark Dickinson; 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 and 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.)

  • os.environ オブジェクトの clear() メソッドが、オブジェクトのキーから取り除くだけでなく os.unsetenv() を使って環境変数を未設定にするようになりました。 (Contributed by Martin Horcicka; bpo-1181.)

  • os.walk() 関数に followlinks パラメータが追加されています。これを真にすると、シンボリックリンクが指す相手のディレクトリを渡り歩くようになります。後方互換のためにこのパラメータのデフォルトは偽です。なお、親ディレクトリを指すシンボリックリンクなど参照が循環していると、無限再帰に陥りますので注意してください。 (bpo-1273829)

  • os.path モジュールの splitext() 関数が、先行するピリオドで分割しないように変更されています。これにより Unix のドットファイルの処理結果がよくなります。例えば os.path.splitext('.ipython') は ('', '.ipython') ではなく ('.ipython', '') を返すようになっています。 (bpo-1115886)

    新規関数 os.path.relpath(path, start='.') は、与えられれば start からの、与えられなければカレントディレクトリからの、目的地 path への相対パスを返します。 (Contributed by Richard Barran; bpo-1339796.)

    Windows において、 os.path.expandvars() が "%var%" 形式の記述に環境変数を展開し、 "~user" にユーザのホームディレクトリのパスを展開するようになりました。 (Contributed by Josiah Carlson; bpo-957650.) (---訳注: "~user" は実在した仕様かわかりません。2.7 に該当する実装もコメントも docstring もリファレンスもありませんし、当然この振る舞いは現在実在していません。---)

  • pdb モジュールで提供される Python デバッガに新たなコマンドが追加されました: "run" はデバッグ対象の Python プログラムを再起動します。またオプションとして、対象プログラムに与えるコマンドライン引数を渡せます。 (Contributed by Rocky Bernstein; bpo-1393667.)

  • トレースバックのデバッグを開始するのに使われる pdb.post_mortem() が、トレースバックが与えられない場合に sys.exc_info() からの戻り値のトレースバックを使うようになりました。 (Contributed by Facundo Batista; 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.)

  • pyexpat モジュールの Parser オブジェクトで、 buffer_size 属性の設定により文字データの保持に使うバッファのサイズを変更出来るようになりました。 (Contributed by Achim Gaedke; 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.)

    新たな triangular(low, high, mode) は、三角分布 (triangular distribution) に従う乱数を生成します。 mode は分布内の最頻値で、返却値は high を含まない low と high の間です。 (Contributed by Wladmir van der Laan and Raymond Hettinger; bpo-1681432.)

  • re モジュールによって実行される長い正規表現検索が届けられるシグナルをチェックするようになり、これにより多大な時間を要する検索を中断出来るようになります。 (Contributed by Josh Hoyt and Ralf Schmitt; bpo-846388.) (---訳注: 原文を忠実に訳すとわかりにくいですが、単に C のレベルでシグナルハンドラを仕掛けたので Python が割り込める、というのがここで言っていることです。本質的には「長い」や「時間のかかる」はあまり関係ないです。---)

    正規表現モジュールは、小さな正規表現固有仮想マシン用のバイトコードをコンパイルすることで実装されています。信頼出来ないコードにより、悪意あるバイトコード文字列を直接作って破滅させることが出来ます。ですので、2.6 では正規表現バイトコードの検証をするようにしてあります。(Contributed by Guido van Rossum from work for Google App Engine; bpo-3487.)

  • rlcompleter モジュールの Completer.complete() メソッドが名前の評価時に引き起こされた例外を無視するようになりました。 (Fixed by Lorenz Quack; bpo-2250.)

  • sched モジュールの scheduler インスタンスが読み出し専用の queue 属性を持つようになりました。これはスケジューラのキュー内容を名前付きタプル (time, priority, action, argument) で返します。 (Contributed by Raymond Hettinger; bpo-1861.)

  • select モジュールに新たに Linux システムコール epoll() と BSD システムコール kqueue() へのラッパー関数が追加されました。既存の poll オブジェクトには新たに modify() メソッドが追加されています。 pollobj.modify(fd, eventmask) はファイルデスクリプタかファイルオブジェクトとイベントマスクを取り、そのファイルの記録イベントのマスクを修正します。(Contributed by Christian Heimes; 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.)

  • Tkinter や GTK+ などのような場所で、シグナルハンドリングと GUI 処理のイベントループを組み合わせることは、長い間悩みの種でした; ほとんどのソフトウェアはポーリングを行って、わずかばかりの時間で起き上がっては GUI イベントが起きていないかチェックするハメになっています。 signal モジュールが、これをより効率的に行えるようにしました。 signal.set_wakeup_fd(fd) でファイルデスクリプタをセットすると、イベント受信時にファイルデスクリプタにバイトが書き込まれます。 C レベルの関数 PySignal_SetWakeupFd() もあります。同じくファイルデスクリプタを渡します。

    イベントループはこれを、読み込み用と書き込み用の 2 つのデスクリプタを作るパイプをオープンして使うことになるでしょう。書き込み用デスクリプタは set_wakeup_fd() に渡し、読み込み用デスクリプタはイベントループから select() や poll() で監視するデスクリプタのリストに追加すれば良いでしょう。シグナル受信時にはバイトが書き込まれてメインのイベントループが起き上がるので、ポーリングは必要なくなります。

    (Contributed by Adam Olsen; bpo-1583.)

    siginterrupt() 関数が Python コードから利用可能になりました。対象シグナルがシステムコールを中断出来るかどうかを変更出来ます。 (Contributed by Ralf Schmitt.)

    setitimer(), getitimer() 関数も追加されています (利用可能であれば)。 setitimer() は、指定時間経過後に処理にシグナルを届けます。時間は「壁時計時間 (wall-clock time)」(訳注: リファレンスでは「実時間」と表現している)、「プロセスの実行時間 (consumed process time)」、またはプロセス + システム時間の組合せで指定します。(Contributed by Guilherme Polo; bpo-2240.)

  • smtplib モジュールが、 SMTP_SSL クラスの追加によって SMTP over SSL をサポートするようになっています。このクラスは既存の SMTP と同じインターフェイスです。(Contributed by Monty Taylor.) 両方のクラスのコンストラクタでは新たに省略可能な timeout パラメータを取ります。最初に接続を試みる際のタイムアウト値を秒で指定します。(Contributed by Facundo Batista.)

    LMTP プロトコル ( RFC 2033) 実装もモジュールに追加されています。LMTP はメールキューを管理しないエージェント間で e-mail を転送する際に、SMTP の代わりに使われます。(LMTP implemented by Leif Hedstrom; bpo-957003.)

    SMTP.starttls() は今や RFC 3207 遵守であり、TLS ネゴシエーション自身で得たのでないサーバから得られるいかなる知識も記憶しません。(Patch contributed by Bill Fenner; bpo-829951.)

  • socket モジュールが TIPC (http://tipc.sourceforge.net/) をサポートするようになりました。これは高性能な非 IP ベースのプロトコルで、クラスタ環境で使われるように設計されたものです。TIPC のアドレスは 4 または 5 要素のタプルです。 (Contributed by Alberto Bertogli; bpo-1646.)

    新規の create_connection() 関数はアドレスを取り、省略可能なタイムアウト値を使って接続を行い、接続されたソケットオブジェクトを返します。この関数は同時に、アドレスのタイプを調べて IPv4 と IPv6 の相応しい方を使って接続します。あなたのコードが socket(socket.AF_INET, ...) を使う代わりに create_connection() に乗り換えることは、それが IPv6 対応で必要なこと全て、となるでしょう。

  • SocketServer モジュール内の基底クラスが、 timeout 属性で指定の無応答時間経過後に handle_timeout() メソッドを呼び出すようになっています。 (Contributed by Michael Pomraning.) serve_forever() メソッドは、オプションの秒指定のポーリング間隔を取るようになりました。これは、サーバがシャットダウン要求のチェックをどの程度の頻度で行えばよいのかを制御します。 (Contributed by Pedro Werneck and Jeffrey Yasskin; bpo-742598, bpo-1193577.)

  • Gerhard Häring により保守されている sqlite3 モジュールが、Python 2.5 時のバージョン 2.3.2 からバージョン 2.4.1 に更新されました。

  • struct モジュールが C99 の _Bool 型をフォーマット文字 '?' でサポートするようになりました。 (Contributed by David Remahl.)

  • subprocess モジュールの Popen オブジェクトに terminate(), kill(), send_signal() メソッドが追加されました。Windows では send_signal() は SIGTERM シグナルのみがサポートされ、またこれら全てのメソッドは Win32 API 関数の TerminateProcess() の別名になっています。 (Contributed by Christian Heimes.)

  • sys モジュールに新たに追加された変数 float_info は、 float.h に由来するプラットフォームの浮動小数点数サポートについての情報を含んだオブジェクトです。このオブジェクトの属性としては、 mant_dig (仮数部の桁数)、 epsilon (1.0 と、それより大きい表現可能な最小値との差)などがあります。 (Contributed by Christian Heimes; 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)

    現在動作中のプロファイラとトレーサーを、 sys.getprofile() と sys.gettrace() で知ることが出来るようになりました。 (Contributed by Georg Brandl; 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 エンコーディングです。)

    TarFile.add() メソッドが新たに exclude 引数を受け付けます。これはアーカイブから特定のファイル名を除外するために呼び出される呼び出し可能オブジェクトです。ファイル名を受け取って、除外すべきファイルの場合に真、そうでなければ偽を返してください。この呼び出し可能オブジェクトは add() に最初に追加される名前と再帰的に追加されるディレクトリの名前の両方に適用されます。

    (All changes contributed by Lars Gustäbel).

  • 省略可能パラメータ timeout が telnetlib.Telnet クラスのコンストラクタに追加されました。タイムアウトを秒で指定します。 (Added by Facundo Batista.)

  • tempfile.NamedTemporaryFile クラスは普通はこれが作った一時ファイルを、ファイルクローズ時に削除します。この振る舞いを、コンストラクタのパラメータに delete=False を渡すことで変更出来るようになりました。 (Contributed by Damien Miller; bpo-1537850.)

    新しいクラス SpooledTemporaryFile は一時ファイルのように振舞いますが、そのデータは最大サイズを超えるまではメモリ内に格納されます。その制限を超えると、その内容がディスク上の一時ファイルに書き込まれます。 (Contributed by Dustin J. Mitchell.)

    NamedTemporaryFile と SpooledTemporaryFile のともにコンテキストマネージャとして動作しますので、 with tempfile.NamedTemporaryFile() as tmp: ... のように書くことが出来ます。 (Contributed by Alexander Belopolsky; bpo-2021.)

  • test.test_support に、テストを書くのに便利な多くのコンテキストマネージャが追加されています。 EnvironmentVarGuard() は環境変数を一時的に変更して自動的に元に戻すコンテキストマネージャです。

    もう一つのコンテキストマネージャ TransientResource は、利用出来るかもしれないし出来ないかもしれないリソースの呼び出しを包むことが出来ます; 指定した例外リストを捕捉して無視します(---訳注: この紹介、良くないと思うのと、多分著者が誤解してます。確かに属性名/属性値を特定してこれに一致する場合にだけ例外を受け取るためのものなので、一致しないものは無視、という事実には反しませんが、「狙った例外は受け取る(ResourceDenied)」でもあるはずです。「期待した例外が発生する」ことをテストしたいでしょう、「期待しない例外はテストには関係ない」であるとともに。それとリファレンスと docstring によれば「指定した例外と属性に合致する場合に ResourceDenied」と言っているので、やはり事実とは反しています。---)。例えば、ネットワークのテストでは外部のウェブサイトとの接続時の特定の失敗を無視するでしょう:

    with test_support.TransientResource(IOError,
                                errno=errno.ETIMEDOUT):
    f = urllib.urlopen('https://sf.net')
    ...

    最後に、 check_warnings() は warning モジュールの警告フィルタをリセットして、全ての引き起こされる警告メッセージを記録するオブジェクトを返します (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.)

  • textwrap モジュールで、行頭と新たに作る行の末尾にもともと含まれている空白文字を保ったままにすることが出来るようになりました。 drop_whitespace=False を指定します:

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

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

  • timeit モジュールが、計測されるステートメントとセットアップコードとして、文字列だけでなく呼び出し可能オブジェクトを渡せるようになりました。 Timer インスタンスを作成する 2 つの便利関数が追加されています: repeat(stmt, setup, time, repeat, number) と timeit(stmt, setup, time, number) で、インスタンスを作成して対応するメソッドを呼びます。 (Contributed by Erik Demaine; bpo-1533909.)

  • Tkinter モジュールが、オプションとしてリストとタプルを受け付けるようになっています。Tcl/Tk へは空白区切りの文字列にして渡されます。 (Contributed by Guilherme Polo; bpo-2906.)

  • タートルグラフィックスのための turtle モジュールが Gregor Lingl により大幅に拡張されました。 モジュールの新しい機能は次の通りです:

    • 亀の移動と回転のアニメーションの改善。
    • 新しい delay() メソッド、 tracer() メソッド、 speed() メソッドを使って亀の動きをコントロールできるようになりました。
    • 亀に新しい姿を設定できたり、新しい座標系を定義できるようになりました。
    • 亀に、動作を巻き戻せる undo() メソッドが増えました。
    • マウスやキーボードからの入力イベントに反応するための簡易なサポートが入り、簡単なゲームを書けるようになりました。
    • turtle.cfg を使って、turtle の画面の起動時の見た目をカスタマイズできるようになりました。
    • モジュールの docstring が、他の言語に翻訳された docstring に置き換えられるようになりました。

    (bpo-1513695)

  • 省略可能パラメータ timeout が urllib.urlopen() 関数と urllib.ftpwrapper クラスのコンストラクタ、 urllib2.urlopen() 関数に追加されました。タイムアウトを秒で指定します。例えば:

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

  • warnings モジュールの formatwarning() と showwarning() に省略可能な line 引数が追加されました。ソースコードの行番号を与えることが出来ます。 (Added as part of bpo-1631171, which re-implemented part of the warnings module in C code.)

    新しい関数 catch_warnings() はコンテキストマネージャで、テスト目的で警告フィルタを一時的に変更して元に戻すのに使えます。 (bpo-3781).

  • XML-RPC の SimpleXMLRPCServer クラスと DocXMLRPCServer クラスでは、コンストラクタパラメータ bind_and_activate に False を渡すと、そのソケットに即座にバインドして有効化 (訳注: ソケットのリッスン) するのを避けられるようになりました。 これは server_bind() メソッドと server_activate() メソッドを呼び出してソケットへのバインドと有効化を行う前に、インスタンスの allow_reuse_address 属性を変更するのに使えます。 (Contributed by Peter Parente; 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.)

  • xmlrpclib モジュールが自動的に datetime.date と datetime.time を xmlrpclib.DateTime 型に変換することはなくなりました; 変換のセマンティクスが必ずしも全てのアプリケーションで正しいわけではありませんでした。 (bpo-1330538) xmlrpclib を使うコードは自分で date インスタンスと time インスタンスを変換すべきです。 そうしておくと、 1900 年以前の日付 (contributed by Ralf Schmitt; bpo-2014) と、XML-RPC レスポンス内で <i8> を使った 64 ビット整数表現 (contributed by Riku Lindblad; 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.)

    open(), read(), extract() メソッドはファイル名か ZipInfo オブジェクトのどちらかを受け取れるようになっています。これは誤って重複したファイル名を含んでいるアーカイブで有用でしょう。 (Contributed by Graham Horler; bpo-1775025.)

    最後に、 zipfile がアーカイブするファイルのファイル名として Unicode の使用をサポートするようになりました。 (Contributed by Alexey Borzenkov; 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.)

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

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 ライブラリの上に構築されています。この新しいモジュールはプロトコルのネゴシエイトのさらなる制御、X.509 証明書の使用、そして SSL サーバ (クライアントの対語としての) を Python で書くためのより良いサポートを提供しています。既存の socket モジュールにある SSL サポートは削除されずにそのまま使えますが、Python 3.0 では削除されます。

この新たなモジュールを使うには、まず最初にいつものやり方で TCP コネクションを作らなければなりません。そしてその上でそれを ssl.wrap_socket() 関数に渡します (---訳注: 2.7.9 ではさらに進化した SSLContext.wrap_socket が使えます ---)。証明書が必要かどうかを指定することが出来、証明書の情報を getpeercert() メソッドで取得することも出来ます。

参考

ssl モジュールについてのドキュメント。

非推奨と削除

  • 文字列を例外として送出することは出来なくなりました。これをすると TypeError を起こします。

  • PEP 352 で指示される Exception インターフェイスの変更が続けられています。 2.6 では、 args 属性を採用するので message 属性が非推奨となります。

  • (3.0 警告モード) Python 3.0 はたくさんの時代遅れのモジュールを削除し、ほかのものも名前変更するような標準ライブラリの再編成が特色となります。Python 2.6 を 3.0 警告モードで動かすと、それらがインポートされる際に警告が励起されます。

    非推奨モジュールのリストです: audiodev, bgenlocations, buildtools, bundlebuilder, Canvas, compiler, dircache, dl, fpformat, gensuitemodule, ihooks, imageop, imgfile, linuxaudiodev, mhlib, mimetools, multifile, new, pure, statvfs, sunaudiodev, test.testall, toaiff.

  • gopherlib モジュールは削除されました。

  • MimeWriter モジュールと mimify モジュール は非推奨となっています。代わりに email パッケージを使ってください。

  • md5 モジュールは非推奨となりました。代わりに hashlib モジュールを使ってください。

  • posixfile モジュールは非推奨となりました。 fcntl.lockf() がより良いロッキングを提供しています。

  • popen2 モジュールは非推奨となっています。 subprocess モジュールを使ってください。

  • rgbimg モジュールは削除されました。

  • sets モジュールは非推奨となりました。代わりにビルトインの set, frozenset 型を使ってください。

  • sha モジュールは非推奨となりました。代わりに hashlib モジュールを使ってください。

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

Python のビルド過程と C API の変更は以下の通りです:

  • Python はもはや、 C89 コンパイラでコンパイルされなければなりません (19 年も経ってる!)。ですので Python ソースツリーからは、 memmove() と strerror() の手前実装が削除されています。C89 標準ライブラリにあるものですから。

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

  • BerkeleyDB モジュールが C API オブジェクトを公開しています。 bsddb.db.api として利用可能です。このモジュールは bsddb モジュールを自身の独自の目的で使いたいほかの C 拡張で使えます。 (Contributed by Duncan Grisby.)

  • PEP 3118 改訂版バッファプロトコル で前述の新しいバッファインターフェイスのために、 PyObject_GetBuffer() と PyBuffer_Release() とほか少しの関数が追加されました。

  • Python の C stdio ライブラリの使用は今では、スレッドセーフ、もしくは、最低でも基底のライブラリと同じ程度にはスレッドセーフです。ファイルをあるスレッドが別スレッドで読み書き最中にクローズするとマズイことが起こるのは、もう長いこと居座り続けた潜在的なバグでした。2.6 ではファイルオブジェクトが参照カウントを持っていて、 PyFile_IncUseCount(), PyFile_DecUseCount() 関数で操作します。ファイルオブジェクトは参照カウントがゼロにならない限りクローズ出来ません。GIL が獲得されている間に FILE * ポインタを使った I/O 操作を実行する前に PyFile_IncUseCount() が呼び出されなければなりません。また、GIL の再獲得後に即座に PyFile_DecUseCount() が呼び出されなければなりません。(---訳注: 伝わりづらいので別の言い方で言い直すと「Inc してから GIL 解放して FILE* を弄び、済んだら GIL 再獲得して Dec する」。リファレンスのコード例ですぐにわかります。---) (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.)

  • PyComplex_AsCComplex() を使う C 関数とメソッドが __complex__() メソッドを持つ引数を受け付けるようになっています。特に、 cmath モジュールにある関数は、このメソッドを持つオブジェクトを受け付けます。これは Python 3.0 での変更のバックポートです。 (Contributed by Mark Dickinson; bpo-1675423.)

  • Python C API に 2 つの大文字小文字を区別しない文字列比較関数 PyOS_stricmp(char*, char*) と PyOS_strnicmp(char*, char*, Py_ssize_t) が追加されました。 (Contributed by Christian Heimes; bpo-1635.)

  • 多くの C 拡張が、 init* 関数内でモジュール辞書に整数と文字列定数を追加するために独自の小さなマクロを定義しています。 Python 2.6 ではついにモジュールに値を追加する標準マクロを定義しました。 PyModule_AddStringMacro と PyModule_AddIntMacro() です。 (Contributed by Christian Heimes.)

  • いくつかのマクロが 3.0 と 2.6 の両方でリネームされました。それが関数ではなくマクロであることを明確にするためです。 Py_Size() は Py_SIZE() となり、 Py_Type() は Py_TYPE() に、そして Py_Refcnt() が Py_REFCNT() になっています。元の大小文字混在版は後方互換のために Python 2.6 では利用可能なままです。 (bpo-1629)

  • Distutils は C 拡張を、デバッグバージョンの Python 実行時に別のディレクトリにビルドするようになりました。 (Contributed by Collin Winter; 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.)

  • msvcrt モジュールはいまでは通常文字系とワイド文字系の両方のコンソール I/O API をサポートします。 getwch() 関数と getwche() 関数は打鍵を読み取り、Unicode 値を返します。 putwch() 関数は Unicode 文字を受け取り、コンソールに書き出します。 (Contributed by Christian Heimes.)

  • os.path.expandvars() は "%var%" 形式を環境変数で置換し、 "~user" をユーザのホームディレクトリパスに置換します(---訳注: 上のほうの訳注参照。---)。 (Contributed by Josiah Carlson; bpo-957650.)

  • socket モジュールのソケットオブジェクトが ioctl() メソッドを持つようになりました。 WSAIoctl() インターフェイスへの限定的なインターフェイスを提供します。

  • _winreg モジュールに新しい関数 ExpandEnvironmentStrings() が追加されています。これは入力文字列が %NAME% のように参照されている場合に環境変数を展開します。このモジュールで提供されるハンドルオブジェクトはコンテキスト管理プロトコルをサポートするようになったので、 with ステートメントで使えます。 (Contributed by Christian Heimes.)

    _winreg は x64 システムのためのより良いサポートが追加されています。 64 ビットシステムで動作する 32 ビットプロセスでレジストリリフレクションを有無効化をする DisableReflectionKey(), EnableReflectionKey(), QueryReflectionKey() 関数を公開しています。 (bpo-1753245)

  • msilib モジュールの Record オブジェクトに GetInteger() と GetString() メソッドが追加されました。フィールド値をそれぞれ数値として、または文字列として返します。 (Contributed by Floris Bruynooghe; bpo-2125.)

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

  • Python をフレームワークビルドでコンパイルする際に、 configure スクリプトに --with-framework-name オプションでフレームワーク名を指定出来るようになりました。
  • macfs モジュールは削除されました。これは同様に macostools.touched() 関数の削除を必要としました。それが macfs モジュールに依存していたので。 (bpo-1490190)
  • ほか多くの Mac OS モジュールが非推奨となり、 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, terminalcommand 。

ポート特有の変更: IRIX

たくさんの古い IRIX 固有のモジュールが非推奨となり、Python 3.0 では削除されます: al と AL, cd, cddb, cdplayer, CL と cl, DEVICE, ERRNO, FILE, FL と fl, flp, fm, GET, GLWS, GL と gl, IN, IOCTL, jpeg, panelparser, readcd, SV と sv, torgb, videoreader, 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 の議論を参照して下さい。

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

  • xmlrpclib モジュールが自動的に datetime.date と datetime.time を xmlrpclib.DateTime 型に変換することは、もう二度としません; 変換のセマンティクスは必ずしも全てのアプリケーションで正しいわけではなかったのです。 xmlrpclib を使うコードは自分で date と time インスタンスを変換すべきです。(bpo-1330538)

  • (3.0 警告モード) Exception クラスはスライスやインデクスアクセスで警告を出します; Exception のタプルのような振る舞いはのちに取り除かれます。

  • (3.0 警告モード) 2 つの辞書や 2 つの比較メソッドを実装しないオブジェクトの不等号比較は警告されます。 dict1 == dict2 はまだ動作しますが、 dict1 < dict2 はのちに取り除かれます。

    Python のスコープルールの実装の詳細であるセル間の比較も、警告を引き起こします。なぜならこれは、3.0 ではそのような比較は完全に禁止されているからです。

謝辞

著者は提案の申し出や修正、様々なこの記事の草稿の助けをしてくれた以下の人々に感謝します: 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 »


What's New in Python 2.5

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

What's New in Python 2.5

著者: A.M. Kuchling

この文書は Python 2.5 の新機能について解説します。 Python 2.5 の最終リリースは 2006 年 8 月にスケジュールされました。 PEP 356 が予定されたリリーススケジュールを記述しています。

Python 2.5 の変更は言語とライブラリの改善の面白い組み合わせになりました。ライブラリの強化のほうが Python ユーザコミュニティにとっては重要でしょう。多数の大変利用価値の高いパッケージが追加されました。新しいモジュールとしては、XML 処理のための ElementTree (xml.etree)、SQLite データベースのためのモジュール(sqlite)、そして C 関数呼び出しのためのモジュール ctypes があります。

言語の変更の意義は、中程度のものです。いくつかの心地よい機能が入りましたが、そのほとんどの機能は毎日使うというものでもありません。条件式(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 にいくつかの例があるので見てください。条件式の周りをいつでも括弧で囲むなら、このケースにぶち当たることもありません。

参考

PEP 308 - 条件式 (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 - 関数の部分適用
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 - Metadata for Python Software Packages v1.1
PEP 提案と著 A.M. Kuchling、 Richard Jones、 Fred Drake; 実装 Richard Jones と Fred Drake.

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

PEP 328 のうち簡単な方は Python 2.4 で実装されました: from module import names 文において、 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 - マルチラインインポートと、絶対/相対インポート
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 - モジュールをスクリプトとして実行する
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 - 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 がその規則を正確に説明していますが、それによると 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 でコルーチンを効果的に使うためのパターンを理解する必要があります。

close() メソッドの追加には、自明とは言えない副作用が一つあります。 close() はジェネレータがガーベージコレクトされる際に呼ばれるので、ジェネレータコードはジェネレータが破棄される前に、一つ動くラストチャンスを持つのです。このラストチャンスは、ジェネレータ内の try...finally ステートメントがもはや必ず動けることを意味しています; finally 節は必ず実行の機会を得ます。 try...finally と yield を組み合わせられないという構文的な制限は、それゆえに取り除かれました。これは小さな言語の取るに足らないことのように見えますが、ジェネレータの使用と try...finally は PEP 343 で記述される with ステートメントの実装のために実際に必要です。この新しいステートメントについては続くセクションで見ていきましょう。

もう一つさらに深遠なこの変更の効果: 以前はジェネレータの gi_frame 属性は常にフレームオブジェクトでした。今では gi_frame は、ジェネレータが使い果たされた場合に None になります。

参考

PEP 0342 - 拡張されたジェネレータを用いたコルーチン

PEP は Guido van Rossum と Phillip J. Eby によって書かれ、Phillip J. Eby によって実装されました。コルーチンとしてのジェネレータの用法のいくつかの手が込んだ例が含まれています。

この機能の初期バージョンは Raymond Hettinger による PEP 288 と Samuele Pedroni による PEP 325 で提案されました。

https://en.wikipedia.org/wiki/Coroutine
コルーチンに関する WikiPedia エントリ。
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

expression は評価されて結果がコンテキスト管理プロトコルをサポートするオブジェクトにならなければなりません (具体的にはメソッド __enter__() と __exit__() を持つオブジェクト)。 ( 訳注: Python ドキュメント全体で context manager protocol と context management protocol とで不統一。同じものです。 )

with-block が呼び出される前に、 __enter__() が呼ばれるので、セットアップコードをそこで実行出来ます。それは variable 名(与えられた場合)に束縛されることになる値も返します(注意深く読んで下さい、つまり variable には expression の結果が代入される のではない のです)。

with-block ブロックの実行が終了後、ブロックが例外を送出する場合であろうとオブジェクトの __exit__() が呼び出されますので、ここで後片付けコードを実行出来ます。

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 ループが道半ばにして例外と成り果てても、自動的にクローズされます。

注釈

このケースでは、 f は open() が作ったオブジェクトと同じです。これはファイルオブジェクトの file.__enter__() が 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()

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

Under the hood, the 'with' statement is fairly complicated. Most people will only use 'with' in company with existing objects and don't need to know these details, so you can skip the rest of this section if you like. Authors of new objects will need to understand the details of the underlying implementation and should keep reading.

コンテキスト管理プロトコルの高度な説明はこんなです:

  • expression は評価されて、 "コンテキストマネージャ(context manager)" にならなければなりません。コンテキストマネージャは __enter__() メソッドと __exit__() メソッドを持っていなければなりません。
  • コンテキストマネージャの __enter__() メソッドが呼び出されます。これの戻り値は VAR に代入されます。 as VAR 節がない場合は、この値は単に捨てられます。
  • BLOCK 内のコードが実行されます。
  • BLOCK が例外を起こした場合、コンテキストマネージャの __exit__ メソッドが 3 つの引数とともに呼び出されます。これは例外の詳細です (type, value, traceback, これは sys.exc_info() が返す値と同じで、例外が起こらなければ None です)。そのメソッドの戻り値は例外を再送出するかどうかを制御します: 全ての偽の値ではその例外が再送出され、 True では揉み消します。例外を揉み消すなど滅多なことでは欲しいと思わないでしょう。もしそうしてしまったら、 'with' ステートメントを含んだコードの作者は何か間違ったことが起こったことに決して気付かないですから。
  • BLOCK が例外を起こさなかった場合も __exit__() メソッドが呼び出されます。ただし type, value, traceback は全て 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"

__enter__() メソッドはとっても簡単で、トランザクションを開始する必要があるだけです。このアプリケーションでは、カーソルオブジェクトを結果とすることが有用なので、メソッドはそれを返しましょう。ユーザはこれにより as cursor をその 'with' ステートメントにつけて、そのカーソルを変数名に束縛できます:

class DatabaseConnection:
    ...
    def __enter__ (self):
        # Code to start a new transaction
        cursor = self.cursor()
        return cursor

__exit__() メソッドはそれがほとんどの仕事をしなければならない場所なので、もっと複雑です。メソッドは例外が起こったのかどうかをチェックし、例外が起こっていなければトランザクションをコミットし、例外があればロールバックしなければいけません。

下記のコード内では実行がメソッドの末尾まで落ちていって、なのでデフォルトの 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:
    ...

The contextlib module also has a nested(mgr1, mgr2, ...) function that combines a number of context managers so you don't need to write nested 'with' statements. In this example, the single 'with' statement both starts a database transaction and acquires a thread lock:

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 - "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 - 例外のためのスーパークラス
PEP 著: Brett Cannon と Guido van Rossum; 実装: Brett Cannon.

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

Python の C API についての広範囲に渡る修正は、 int の代わりとなる新しい Py_ssize_t 型を使うことです。これは 64 ビットプラットフォームにおいてインタプリタがより大きなデータを扱えるようにします。この変更は 32 ビットプラットフォームでの Python には影響しません。

Python インタプリタのあらゆる場所で、大きさや数え上げのために C の int 型が使われていました; 例えばリストやタプルの要素数は int で格納されていました。ほとんどの 64 ビットプラットフォームでは今でも int を 32 ビット型として定義していますので、リストは 2**31 - 1 = 2147483647 までしか保持出来なかった、ということです。(実際には 64 ビットコンパイラが使える小数の異なったプログラミングモデルもあります -- http://www.unix.org/version2/whatsnew/lp64_wp.html の議論を参照して下さい -- ですがほとんどの場合で利用可能なモデルでは int は 32 ビットのままです。)

2147483647 に要素数が制限されることは 32 ビットプラットフォームではあまり重大でもありません。その長さ制限を喰らう前にメモリを使い果たすでしょうから。それぞれのリストアイテムは、ポインタのための領域 (4 バイト) をアイテムを表現する PyObject に余分に必要とします。2147483647*4 は既に 32 ビットのアドレス空間が含められるバイト数を超えています。(---訳注: 意味不明。何か誤解があるような…? 4 バイトは 2147483647 (符号付きとして 2^31 - 1) でしょう。4 を掛ける説明なんかここでまったくされていない。なぜ掛ける? それと要素のインデクシングとアイテムの必要領域は議論には無関係なのでは?---)

しかしながら 64 ビットプラットフォームではさらに多くのメモリをアドレスすることが出来ます。リストのためのポインタではたった 16 GiB の領域を必要とするだけですから、Python プログラマがそのように巨大なリストを構築しようとすることは理不尽でもありません。それゆえ Python インタプリタは int に代わる何かほかの型を使う必要に迫られました。それは 64 ビットプラットフォームで 64 ビットを使うことです。その変更は 64 ビット機での非互換性をもたらすので、64 ビットユーザが比較的少数派である間は、今のところ漸近的推移で合意されました。 (5 年もしくは 10 年の間には 全て が 64 ビット機であるかもしれませんので、この漸近的推移はより苦痛になるかもしれません。) --- (---訳注: 16 GiB はどこから出てくる? 2147483647*4 と 2147483647*8 の間らしいが…。このセクション全体として、誤解か説明不足かどちらかです。 ssize_t として 64 ビットプラットフォームで 64 ビットアドレス空間を目いっぱい使える、このセクションはそれだけを言えばいいはずなのですが…。それと「漸近的推移」(transition)についてですが、これはこの変更の意図としては続く文の「まだ int のものがいる」ことを指しているのですが、文章の構造から考えると、この著者は「32 ビット機でさえ 64 ビットにするのが理想だ」を含意していたのではないかという気がします。---)

この変更は C 拡張モジュールの著者に大変大きく影響します。Python 文字列とリストやタプルのようなコンテナ型は、そのサイズを表すのに Py_ssize_t を使うようになっています。 PyList_Size() のような関数は Py_ssize_t を返します。拡張モジュール内のコードでは、ですので、ある程度の変数の Py_ssize_t への変更が必要でしょう。

PyArg_ParseTuple() 関数と Py_BuildValue() 関数は新しい変換コード n を Py_ssize_t のために持ちました。 PyArg_ParseTuple() の s# と t# はデフォルトではまだ int を出力しますが、 PY_SSIZE_T_CLEAN を定義することが出来ます。 Python.h インクルード前に定義してください。 Py_ssize_t を返すようになります。

PEP 353 には、拡張の著者が読んで学ぶべき 64 ビットプラットフォームサポートについてのセクションがあります。

参考

PEP 353 - 添え字型に 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 を送出します。

これに呼応する nb_index スロットが C レベルの PyNumberMethods 構造体に追加され、C 拡張はこれでこのプロトコルを実装出来ます。 PyNumber_Index(obj) は拡張コード内で __index__() を呼び出してその結果を得るのに使えます。

参考

PEP 357 - スライシングのために任意のオブジェクトを使えるようにする
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 を参照してください; 例えば、ソースコードの先頭付近にこのような行を追加することで出来ます:

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

最適化

Several of the optimizations were developed at the NeedForSpeed sprint, an event held in Reykjavik, Iceland, from May 21--28 2006. The sprint focused on speed enhancements to the CPython implementation and was funded by EWT LLC with local support from CCP Games. Those optimizations added at this sprint are specially marked in the following list.

  • When they were introduced in Python 2.4, the built-in set and frozenset types were built on top of Python's dictionary type. In 2.5 the internal data structure has been customized for implementing sets, and as a result sets will use a third less memory and are somewhat faster. (Implemented by Raymond Hettinger.)
  • The speed of some Unicode operations, such as finding substrings, string splitting, and character map encoding and decoding, has been improved. (Substring search and splitting improvements were added by Fredrik Lundh and Andrew Dalke at the NeedForSpeed sprint. Character maps were improved by Walter Dörwald and Martin von Löwis.)
  • 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.)
  • The re module got a 1 or 2% speedup by switching to Python's allocator functions instead of the system's malloc() and free(). (Contributed by Jack Diederich at the NeedForSpeed sprint.)
  • The code generator's peephole optimizer now performs simple constant folding in expressions. If you write something like a = 2+3, the code generator will do the arithmetic and produce code corresponding to a = 5. (Proposed and implemented by 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 ログに目を通してみてください。

  • audioop モジュールに a-LAW エンコーディングのサポートが追加され、また、u-LAW エンコーディングのコードも改善されています。 (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.)

  • カンマ区切りフォーマットで書かれたファイルの解析を行う csv モジュールに、数多くの拡張とバグフィックスがありました。 csv.field_size_limit(new_limit)() 関数を呼び出すことにより、フィールドの最大バイト数を制限出来るようになっています; new_limit 引数を省略すると現在設定されている制限値を返します。 reader クラスに line_num 属性が追加されています。これはソースから読み込んだ物理行数を表します; レコードは物理行複数行に渡る場合がありますので、 line_num は読み込んだレコード数とは同じではありません。

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

  • fileinput モジュールがさらに柔軟性を持つようになりました。Unicode ファイル名がサポートがサポートされるようになりました。 input() 関数に mode パラメータが追加されました。これは "r" がデフォルトで、バイナリとして読み込みことも出来ますし、 universal newlines モードも使えます。もう一つの新しいパラメータ openhook で、ファイルを開くのに open() の代わりのものを使えます。ファイル集合のイテレートでは、 FileInput オブジェクトの fileno() が現在開いているファイルのファイル記述子を返します。 (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.)

  • 新規モジュール: msilib モジュールで、 Microsoft インストーラの .msi ファイルと CAB ファイルの作成をすることが出来ます。 .msi データベースの読み込みサポートもいくらか入っています。 (Contributed by Martin von Löwis.)

  • nis モジュールで、システムデフォルトのドメイン以外のドメインへのアクセスが可能になりました。 nis.match() と nis.maps() に domain 引数を渡します。 (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() が秒の端数が正確な値を返すという意味ではありません; 全てのシステムがそのような精度をサポートしてはいません。)

    定数 os.SEEK_SET, os.SEEK_CUR, os.SEEK_END が追加されました; これらは os.lseek() 関数へ渡すパラメータです。ロックに用いる 2 つの定数 os.O_SHLOCK と 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.)

  • ライブラリ: pickle, cPickle モジュールが __reduce__() が None を返すことを許さなくなっています; 必ず引数のタプルを返さなければなりません。また同様に、非推奨となっていた bin キーワードパラメータも、もはや拒絶します。 None を返すことは Python 2.4 では非推奨となっていて、これにてその機能の削除は完成したことになります。

  • パッケージ検索のための色々なユーティリティを含む pkgutil モジュールが、PEP 302 のインポートフックをサポートするよう拡張されて、ZIP 形式アーカイブに格納されたパッケージに対しても動作するようになりました。 (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.)

  • SimpleXMLRPCServer クラスと DocXMLRPCServer クラスに XML-RPC 操作を限られた URL パスに制限する rpc_paths 属性が追加されています; デフォルトでは '/' と '/RPC2' のみが許されています。 rpc_paths に None か空のタプルを渡すことで、このパスのチェックは無効になります。

  • 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() アクセッサメソッドも追加されています。それぞれソケットについてのアドレスファミリ、タイプ、プロトコルを取得します。

  • 新規モジュール: spwd モジュールは、シャドーパスワードをサポートするシステムにおいて、シャドーパスワードデータベースへのアクセスを提供します。

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

  • unicodedata モジュールが、 Unicode 文字データベースのバージョン 4.1.0 を使うように更新されました。いくつかの仕様によってバージョン 3.2.0 が必要とされるので、 unicodedata.ucd_3_2_0 としてまだ利用可能です。

  • 新モジュール: uuid モジュールは RFC 4122 による UUID (universally unique identifiers) を生成します。その RFC ではいくつかの異なる UUID のバージョンを定義しており、文字列から生成するもの、システム特性から生成するもの、純粋に乱数から生成するものがあります。このモジュールでは UUID クラスと uuid1(), uuid3(), uuid4(), uuid5() 関数を持っていて、それら異なったバージョンの UUID を生成します。(UUID バージョン 2 は RFC 4122 にありませんのでこのモジュールにもないです)

    >>> 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 パッケージ

Thomas Heller による ctypes パッケージが標準ライブラリに追加されました。 ctypes はシェアドライブラリや DLL の任意の関数呼び出しを担ってくれます。熟練ユーザであれば dl モジュールは知っているでしょう。これはシェアドライブラリのロードとその中の関数呼び出しをするための関数を提供していました。 ctypes パッケージはこれより遥かに手が込んでいます。

シェアドライブラリや DLL をロードするには、 CDLL クラスのインスタンスを、その名前かパスを渡して構築します。構築したら、 CDLL オブジェクトの属性にアクセスすることで任意の関数呼び出しが出来ます:

import ctypes

libc = ctypes.CDLL('libc.so.6')
result = libc.printf("Line of output\n")

様々な C の型についての型コンストラクタが提供されています: c_int(), c_float(), c_double(), c_char_p() (char * に等価), など。Python 型とは違い、C 版は全て mutable です; value 属性を介して値を代入出来ます。 Python 整数と文字列は自動的に対応する C 型に変換されますが、それ以外の型では適切な型コンストラクタを使わなければなりません。(なければなりません と言いました。間違えれば、インタプリタがセグメンテーション違反で落ちるなどしょっちゅうです。)

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 では同時に Python の C API も提供していて、 ctypes.pythonapi オブジェクトとして利用出来ます。このオブジェクトは関数呼び出し前に GIL を解放 しません 。インタプリタ内のコードを呼び出すのにロックは保持されていなければならないからです。 PyObject * ポインタを構築する py_object() 型コンストラクタもあります。単純な利用法はこうです:

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 ラッパーを書き始めるでしょう,

参考

http://starship.python.net/crew/theller/ctypes/
ctypes のウェブページで、チュートリアル、リファレンス、FAQ があります。

ctypes モジュールについてのドキュメント。

ElementTree パッケージ

XML 処理のための、Fredrik Lundh の ElementTree ライブラリのサブセットが、標準ライブラリに xml.etree として追加されました。利用可能なモジュールは ElementTree 1.2.6 よりの ElementTree, ElementPath, ElementInclude です。 C 実装 cElementTree モジュールも含まれています。

このセクションの残りの部分は ElementTree 利用の簡単な概略について提供します。完全なドキュメントは 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 インターフェイスのほんの一部しか記載していません。さらに詳しい情報については、パッケージの公式ドキュメントを参照して下さい。

参考

http://effbot.org/zone/element-index.htm
ElementTree の公式ドキュメント

hashlib パッケージ

Gregory P. Smith による新モジュール hashlib が、 md5 と sha モジュールを置き換えるものとして追加されました。 hashlib は新たなセキュアハッシュ (SHA-224, SHA-256, SHA-384, SHA-512) サポートを追加しています。利用可能な場合、このモジュールは OpenSSL を使ってアルゴリズムのプラットフォームに最適化された高速実装を使います。

古い md5 と sha モジュールは、後方互換のための hashlib へのラッパーとして残されています。新しいモジュールのインターフェイスは古いものと似てはいますが同じではありません。一番顕著な違いはそのコンストラクタ関数で、新しくハッシュオブジェクトを作るための名前が違います:

# 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 パッケージ

pysqlite モジュール (http://www.pysqlite.org) は SQLite 埋め込みデータベースへのラッパーであり、これが標準ライブラリに sqlite3 名のパッケージとして追加されました。

SQLite は、軽量なディスク上のデータベースを提供する C ライブラリです。別のサーバプロセスを用意する必要なく、 SQL クエリー言語の非標準的な一種を使用してデータベースにアクセスできます。一部のアプリケーションは内部データ保存に SQLite を使えます。また、SQLite を使ってアプリケーションのプロトタイプを作り、その後そのコードを PostgreSQL や Oracle のような大規模データベースに移植するということも可能です。

pysqlite は Gerhard Häring によって書かれ、 PEP 249 に記述された 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)
>>>

For more information about the SQL dialect supported by SQLite, see https://www.sqlite.org.

参考

http://www.pysqlite.org
pysqlite のウェブページ。
https://www.sqlite.org
SQLite のウェブページ。ここの文書ではサポートされる SQL 方言の文法と使えるデータ型を説明しています。

sqlite3 モジュールについてのドキュメント。

PEP 249 - Database API Specification 2.0
Marc-Andre Lemburg により書かれた PEP。

wsgiref パッケージ

Web Server Gateway Interface (WSGI) v1.0 は、 Web サーバと Python で記述された Web アプリケーションとの標準インターフェースであり、 PEP 333 で定義されています。 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()

参考

http://www.wsgi.org
WSGI 関連のリソースについて集約しているウェブサイト。
PEP 333 - 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 にて開発されました。

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

  • PEP 353 に由来する C API の大きな変更がありました。これはインタプリタを int ではなく Py_ssize_t 型定義を使うように修正するものです。詳細は前のほうのセクション PEP 353: 添え字型に ssize_t を使う を参照して下さい。

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

  • PyErr_Warn() 関数が、 PyErr_WarnEx(category, message, stacklevel) を採用のために非推奨となっています。後者はこの関数と呼び出し元との間を隔てるスタックフレーム数を指定できます。 stacklevel を 1 とすると関数呼び出しは PyErr_WarnEx() からとなり、2 であればその一つ上から、などです。 (Added by Neal Norwitz.)

  • CPython は今でも C で書かれていますが、コードは C++ コンパイラでもエラーなしでコンパイル出来るようになりました。 (Implemented by Anthony Baxter, Martin von Löwis, Skip Montanaro.)

  • PyRange_New() 関数が削除されました。これは一度もドキュメントされたことはありませんし、コアコード内で一度も使われたこともなく、また、手薄なエラーチェックを持った危険なものでした。あまりないとは思いますがもしあなたの拡張が使っていたのであれば、以下のようなもので置き換え出来ます:

    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.)
  • Windows: .dll はもはや拡張モジュールのファイル拡張子としてはサポートされません。これからは .pyd だけが拡張モジュールとして検索されるファイル拡張子です。

Python 2.5 への移植

このセクションでは前述の変更により必要となるかもしれないコードの変更を列挙します:

  • ASCII がモジュールのデフォルトエンコーディングになっています(訳注: Python 3 からはデフォルトは utf-8 (PEP 3120))。8 ビット文字を含んでいるのにエンコーディング宣言がないモジュールが構文エラーになるようになりました。Python 2.4 では構文エラーとはならず警告でした。
  • 以前はジェネレータの gi_frame 属性は常にフレームオブジェクトでしたが、 PEP 342: ジェネレータの新機能 で説明した PEP 342 での変更により、 gi_frame は None になりえます。
  • Unicode 文字列とデフォルトの ASCII エンコーディングで Unicode に変換出来ない 8 ビット文字列との比較を試みると、新しい警告 UnicodeWarning が引き起こされるようになっています。以前はそのような比較では UnicodeDecodeError 例外を起こしていました。
  • ライブラリ: csv モジュールは引用符内のマルチラインをより厳密に扱うようになっています。フィールド内に改行を埋め込んでいるファイルがある場合は、その入力は改行文字を残すやり方で行分解されるはずです。
  • ライブラリ: locale モジュールの format() 関数は、以前は %文字指示子が一つを超えてさえいなければ任意の文字列を受け付けていたかもしれませんが、Python 2.5 からは正確に一つの、ほかに周りをテキストで囲まれていない %文字指示子でなければなりません。
  • ライブラリ: pickle, cPickle モジュールが __reduce__() が None を返すことを許さなくなっています; 必ず引数のタプルを返さなければなりません。また同様に、非推奨となっていた bin キーワードパラメータも、もはや拒絶します。
  • ライブラリ: SimpleXMLRPCServer クラスと DocXMLRPCServer クラスに XML-RPC 操作を限られた URL パスに制限する rpc_paths 属性が追加されています; デフォルトでは '/' と '/RPC2' のみが許されています。 rpc_paths に None か空のタプルを渡すことで、このパスのチェックは無効になります。
  • C API: 64 ビット機でより大きなデータを処理出来るよう、多くの関数が int の代わりに Py_ssize_t を使うようになっています。拡張コードでは警告を避けて 64 ビット機サポートをするのに同じ変更が必要でしょう。この変更についての議論について書いた PEP 353: 添え字型に ssize_t を使う を参照して下さい。
  • C API: obmalloc の変更により、 PyMem_*() 系関数と PyObject_*() 系関数を混ぜて使わないように注意しなければなりません。ある系列の *_Malloc() でメモリを獲得するならば、解放は対応するほうの *_Free() 関数を使わなければいけません。

謝辞

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 »


What's New in Python 2.3

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

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 は変更できない集合のためのクラスなので、辞書のキーとして利用出来ます。集合型は辞書の上に構築されているので、集合内の要素はハッシュ可能でなければなりません。

単純な使用例です:

>>> 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])
>>>

It's also possible to take the symmetric difference of two sets. This is the set of all elements in the union that aren't in the intersection. Another way of putting it is that the symmetric difference contains all elements that are in exactly one set. Again, there's an alternative notation (^), and an in-place version with the ungainly name 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 - 集合オブジェクト型をビルトインに追加する
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

A new keyword, yield, was introduced for generators. Any function containing a yield statement is a generator function; this is detected by Python's bytecode compiler which compiles the function specially as a result.

When you call a generator function, it doesn't return a single value; instead it returns a generator object that supports the iterator protocol. On executing the yield statement, the generator outputs the value of i, similar to a return statement. The big difference between yield and a return statement is that on reaching a yield the generator's state of execution is suspended and local variables are preserved. On the next call to the generator's .next() method, the function will resume executing immediately after the yield statement. (For complicated reasons, the yield statement isn't allowed inside the try block of a try...finally statement; read PEP 255 for a full explanation of the interaction between yield and exceptions.)

上記 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) といった書き方もできます。

Inside a generator function, the return statement can only be used without a value, and signals the end of the procession of values; afterwards the generator cannot return any further values. return with a value, such as return 5, is a syntax error inside a generator function. The end of the generator's results can also be indicated by raising StopIteration manually, or by just letting the flow of execution fall off the bottom of the function.

自分でクラスを書いて、ジェネレータで言うところのローカル変数をインスタンス変数として全部保管しておけば、同じ効果を得ることは可能です。たとえば整数のリストを返すのは、 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://www.cs.arizona.edu/icon/) から着想しています。Icon ではジェネレータが言語の中枢になっています。Icon では、あらゆる式と関数がジェネレータのように振舞います。 https://www.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 - 単純なジェネレータ
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 - Python ソースコードのエンコーディングを定義する
Marc-André Lemburg、 Martin von Löwis 著; Suzuki Hisao、 Martin von Löwis 実装.

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

The new zipimport module adds support for importing modules from a ZIP-format archive. You don't need to import the module explicitly; it will be automatically imported if a ZIP archive's filename is added to sys.path. For example:

amk@nyman:~/src/python$ unzip -l /tmp/example.zip
Archive:  /tmp/example.zip
  Length     Date   Time    Name
 --------    ----   ----    ----
     8467  11-26-02 22:30   jwzthreading.py
 --------                   -------
     8467                   1 file
amk@nyman:~/src/python$ ./python
Python 2.3 (#1, Aug 1 2003, 19:54:32)
>>> import sys
>>> sys.path.insert(0, '/tmp/example.zip')  # Add .zip file to front of path
>>> import jwzthreading
>>> jwzthreading.__file__
'/tmp/example.zip/jwzthreading.py'
>>>

sys.path には今や ZIP 書庫のファイル名も入れることが出来ます。ZIP アーカイブ内にはどんなファイルを置いてもかまいませんが、import できるのは *.py, *.pyc, *.pyo だけです。書庫に *.py だけが含まれる場合には、Python は書庫を修正して対応する *.pyc を作るなどということはしないので、 *.pyc ファイルを含まない ZIP 書庫からのインポートはやや遅いかもしれません。

書庫内のパスをサブディレクトリ以下のみインポートするように指定出来ます; 例えば、パス /tmp/example.zip/lib/ はその書庫内の lib/ サブディレクトリだけからインポートします。

参考

PEP 273 - Zip アーカイブからモジュールをインポートする
このモジュールの実装も行った、James C. Ahlstrom による PEP です。 Python 2.3 は PEP 273 の仕様に従っていますが、 Just van Rossum の書いた、 PEP 302 に記述されている import フックによる実装を使っています。その新しい import フックについては PEP 302: 新たなインポートフック をみてください。

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

Windows NT, 2000, XP では、ファイルシステムはファイル名として Unicode 文字列を使います。伝統的に Python はファイル名をバイト文字列として表現してきましたが、それはアクセス出来ないファイル名を表してしまう場合があって、不十分でした。

Python はいまや (ファイルシステムの制約の範囲内での) 任意の Unicode 文字列をファイル名が期待される全ての関数で許容します。 os.listdir() に Unicode 文字列が渡されれば、Python は今では Unicode 文字列のリストを返します。新しい関数 os.getcwdu() は Unicode 文字列でカレントディレクトリを返します(訳注: ちなみに Python 3 での Unicode 周りの大改造に伴いこの関数はなくなり、代わりに「あえてバイト列のほうを返す」 os.getcwdb が追加されています(os.getcwdu がもはや Unicode を返すので)。)。

ファイル名のバイト文字列はいまでも動きます。Windows 版 Python は透過的にそれらを Unicode に mbcs エンコーディングを使って変換します。

ほかのシステムでもファイル名の Unicode は許容されますが、システムに渡す前にバイト文字列に変換され、 UnicodeError 例外を引き起こすかもしれません。アプリケーションは任意の Unicode 文字列がファイル名に許されるかどうかを、ブーリアン値 os.path.supports_unicode_filenames をチェックすることでテスト出来ます。

MacOS では、 os.listdir() は Unicode ファイル名を返すようになっているでしょう。

参考

PEP 277 - Windows NT での Unicode ファイル名サポート
Neil Hodgson 著; 実装 Neil Hodgson, Martin von Löwis, Mark Hammond。

PEP 278: Universal Newline サポート

The three major operating systems used today are Microsoft Windows, Apple's Macintosh OS, and the various Unix derivatives. A minor irritation of cross-platform work is that these three platforms all use different characters to mark the ends of lines in text files. Unix uses the linefeed (ASCII character 10), MacOS uses the carriage return (ASCII character 13), and Windows uses a two-character sequence of a carriage return plus a newline.

Python のファイルオブジェクトが、動作しているプラットフォームに従わない行終端変換をサポートするようになりました。ファイルのオープンにモード 'U' や 'rU' を使うと、 universal newlines モードを使った読み込みとしてファイルを開きます。これで read(), readline() などのファイルメソッドが、 3 つどの行終端でも '\n' に翻訳して返すようになります。

universal newline サポートはモジュールのインポートと execfile() 関数でのファイル実行にも使われます。これで 3 つ全てのオペレーティングシステム間で行終端変換の必要なく Python モジュールを共有出来ます。

This feature can be disabled when compiling Python by specifying the --without-universal-newlines switch when running Python's configure script.

参考

PEP 278 : 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 - 組み込み関数 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

デフォルトの設定では、情報メッセージとデバッグメッセージは揉み消され、また、出力は標準エラー出力に送られます。情報メッセージとデバッグメッセージ表示の有効化は、ルートロガーの setLevel() メソッドを呼び出して行えます。

上の例での warning() 呼び出しの文字列フォーマットの操作に注目してください。全てのログメッセージ関数は、引数 (msg, arg1, arg2, ...) を取り、 msg % (arg1, arg2, ...) の結果の文字列をログ出力します。

最も最新のトレースバックを記録する exception() 関数もあります。他の全ての関数も、 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')
 ...

ログレコードは普通階層を上に向かって伝播するので、 server.auth へのログは server と root にも見られますが、 Logger はこれを propagate 属性に False を設定することで避けれます。

logging パッケージにはさらに、カスタマイズ可能なクラス群があります。 Logger インスタンスにログメッセージを伝える際、それは LogRecord インスタンスを作って、任意の数の異なる Handler インスタンスへ送ります。ロガーとハンドラにはフィルタのリストを取り付けることも出来、それぞれのフィルタは無視する LogRecord を決めたり、渡す前にレコードを修正したり出来ます。それらが最後に出力される際、 LogRecord インスタンスは Formatter クラスによりテキストに変換されます。これら全てのクラスはあなた自身の特別に書いたクラスに置き換え可能です。

これら全ての機能で logging パッケージは最も複雑なアプリケーションでさえ、十分な柔軟性を提供しているはずです。ここではそれら機能の不完全な概要しか示しませんでしたので、全ての詳細はパッケージのドキュメントを参照してください。 PEP 282 を読むことも助けになるでしょう。(---訳注: 今ではクックブックもあるのでそちらもどうぞ。---)

参考

PEP 282 - ログシステム
PEP 著: Vinay Sajip と Trent Mick; 実装: Vinay Sajip.

PEP 285: Boolean 型

真偽値型 (Boolean) が Python 2.3 に追加されました。関連して 2 つの定数 True と False が __builtin__ モジュールに追加されています。(定数 True と False は Python 2.2.1 にはビルトインに追加されてはいたのですが、 2.2.1 版のものは単純に整数の 1 と 0 をセットしただけのもので、独立した真偽値型ではありませんでした。)

この新しい型の型オブジェクトの名前は 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's Booleans were not added for the sake of strict type-checking. A very strict language such as Pascal would also prevent you performing arithmetic with Booleans, and would require that the expression in an if statement always evaluate to a Boolean result. Python is not this strict and never will be, as PEP 285 explicitly says. This means you can still use any expression in an if statement, even ones that evaluate to a list or tuple or some random object. The Boolean type is a subclass of the int class so that arithmetic using a Boolean still works.

>>> True + 1
2
>>> False + 1
1
>>> False * 75
0
>>> True * 75
75

True と False はぶっちゃけて言えば…: これらは整数値 1 と 0 の別名だけれども唯一異なるのは str() と repr() が '1' と '0' ではなく 'True' と 'False' を返すことだけである。

参考

PEP 285 - 真偽値型の追加
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 - コーデックエラーを処理するコールバック
Walter Dörwald 著、実装

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

長い間要望されてきた Python カタログのサポートが 2.3 で初登場です。

カタログの心臓部は Distutils の新コマンド register です。 python setup.py register を実行すると、名前、バージョン、メンテナ、説明、ライセンスのようなパッケージ記述のメタデータを収集して、中央カタログサーバに送信します。結果のカタログは https://pypi.org で利用可能です。

カタログ作成をもう少し便利にするために、Distutils の setup() 関数に新たにオプショナルな classifiers キーワード引数が追加されています。 Trove スタイルの文字列のリストは、ソフトウェアの分類を助けるために与えることが出来ます。

以下は 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 - Package Index and Metadata for Distutils
Richard Jones 著、実装

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

カスタムなインポートフックを書くことは、Python 1.3 で ihooks モジュールが導入されたその日からずっと可能でした。それでも本当のところそれで幸せになった人は誰一人いません。それで新しいインポートフックを書くのが難しくてとっ散らかっていたからです。 imputil と iu モジュール のような代わりとなる色々な提案がありましたが、そのいずれも多くの賛同を得ることが出来たものはありませんし、そのいずれもが簡単に C コードから使うことが出来ませんでした。

PEP 302 はその先駆者、特に 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 参照):

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 - 新たなインポートフック
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

reader() 関数はたくさんのオプションを取ります。フィールドセパレータはカンマだけに制限されておらず任意の文字に変更出来、引用も変更できます。

カンマ区切りファイルの異なった方言を定義して登録出来ます。今のところ 2 つの方言があって、両者とも Microsoft Excel で使われるものです。独立している csv.writer はタプルやリストの連続から、デリミタを含む文字列は引用符で囲みつつカンマ区切りファイルを生成します。

参考

PEP 305 - CSV File API
PEP 著と実装: Kevin Altis, Dave Cole, Andrew McNamara, Skip Montanaro, Cliff Wells.

PEP 307: Pickle の機能拡張

pickle, cPickle モジュールで、2.3 の開発サイクル中にいくつか留意すべきことがありました。2.2 では新スタイルクラスを特に困難なく pickle 化出来たものの、あまりコンパクトには pickle 化は出来ませんでした。 PEP 307 が些細な例を引用しています。新スタイルクラスは旧スタイルクラスに較べて 3 倍の長さになっていました。

解決方法として、新しい pickle プロトコルが発明されました。 pickle.dumps() 関数はずっと長い間、テキストとするのかバイナリとするのかについてはサポートしていました。2.3 ではこのフラグは Boolean から整数に再定義されました: 0 は旧式のテキストモード pickle フォーマット、1 が同じく旧式のバイナリフォーマット、そして 2 が今回の 2.3 から特有のフォーマットです。新しく追加された定数 pickle.HIGHEST_PROTOCOL を指定すると、最も望ましいものが選択されます。

unpickle は安全な操作についての考慮はしなくなりました。2.2 の pickle は unpickle される安全でないクラス (特に __safe_for_unpickling__ 属性) を避けようとするフックを提供していましたが、このコードは一度も監査されることがなく、2.3 で全て白紙にしました。Python のどのバージョンでも、信頼出来ないデータを unpickle すべきではありません。

新スタイルクラスでの pickle のオーバーヘッドを減らすために、pickle をカスタマイズする、3 つの特殊メソッドを使った新インターフェイスが追加されました: __getstate__(), __setstate__(), __getnewargs__() 。これらメソッドの完全なセマンティクスについては PEP 307 を調べてください。

pickle をもっとさらに圧縮する方法として、pickle されるクラスの身元特定のために長い文字列を使う代わりに整数コードを使えるようになっています。Python Software Foundation は標準コードのリストを保守しています; プライベート使用のためのコード範囲もあります。現在のところ指定されているコードはありません。

参考

PEP 307 - 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]

ビルトインのシーケンスの __getitem__() メソッドに slice オブジェクトを渡すことも出来るようになりました:

>>> range(10).__getitem__(slice(0, 5, 2))
[0, 2, 4]

あるいは直接 slice オブジェクトを添え字に使えます:

>>> range(10)[slice(0, 5, 2)]
[0, 2, 4]

拡張スライスをサポートするシーケンスの実装を単純化するために、 slice オブジェクトに indices(length)() メソッドが追加されています。これはシーケンスの長さを受け取って、タプル (start, stop, step) を返すことで直接 range() に渡せるようにしています。 indices() は範囲外のインデクスを、標準のスライスと一貫した方法で処理します (そしてこの当たり障りのない言い回しは、ややこしい詳細の荒波を隠しているのですよ…!) このメソッドはこうやって使うのを意図したものです:

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'

  • A new warning, PendingDeprecationWarning was added to indicate features which are in the process of being deprecated. The warning will not be printed by default. To check for use of features that will be deprecated in the future, supply -Walways::PendingDeprecationWarning:: on the command line or use warnings.filterwarnings().

  • 文字列ベースの例外、例えば raise "Error occurred" のようなもの、これは廃止のための過程を開始しています。文字列を例外として投げると PendingDeprecationWarning が発行されます。

  • None を変数名に使うと SyntaxWarning 警告を出すようになっています。将来バージョンの Python では None はキーワードになります。

  • ファイルオブジェクト自身が自身のイテレータのように振舞うようになったために、Python 2.1 で導入されたファイルオブジェクトの xreadlines() メソッドはもう必要ありません。 xreadlines() メソッドは元々はファイル内の全行をループするのに高速な手段として導入されましたが、今では単純に for line in file_obj と書くことが出来ます。ファイルオブジェクトにはさらに読み出し専用の encoding 属性を持つようになっていて、これはファイルで使われているエンコーディングを与えます。ファイルへの Unicode 文字列書き込みでは、与えられたエンコーディングを使って自動的にバイト列に変換されます。(---訳注: encoding は読み出し専用なので「与える」といっても直接セットすることは出来ません。ビルトインの open() と file にはエンコーディングを指定するインターフェイスがありません。一般にはこれは何かほかの関数などで間接的にセットすることになりますが、2.6 以降であれば open() 、そうでないなら codec モジュールなどを介して制御することになると思います。Python 3 以降を含む 2.6 以降は open() が良いです。---)

  • 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". To understand the motivation for this change, read Michele Simionato's article "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 はマルチスレッドプログラムを、バイトコード N 個実行のたびに実行スレッドを切り替えて実行します。このデフォルトの N が 10 から 100 に増やされました。これはシングルスレッドアプリケーションにおいてこの切り替えのオーバヘッドを減らして高速化するためです。マルチスレッドアプリケーションでは応答時間が遅くなる被害を被るかもしれませんが、このリミット値を元の小さな値に戻すのは簡単で、 sys.setcheckinterval(N) を使います。設定されているリミット値は新規関数 sys.getcheckinterval() で取得できます。

  • マイナーですが広範囲に渡る変更として、拡張型の名前の変更があります。Python と一緒に含まれるモジュールで定義される拡張型の名前が、モジュール名と '.' が型名に前置されるようになりました。例えば Python 2.2 ではソケットオブジェクトを作って __class__ を出力すると、このような出力だったでしょう:

    >>> s = socket.socket()
>>> s.__class__
<type 'socket'>

    2.3 ではこうなります:

    >>> s.__class__
<type '_socket.socket'>

  • One of the noted incompatibilities between old- and new-style classes has been removed: you can now assign to the __name__ and __bases__ attributes of new-style classes. There are some restrictions on what can be assigned to __bases__ along the lines of those relating to assigning to an instance's __class__ attribute.

文字列に関する変更

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

  • startswith(), endswith() メソッドが start と end パラメータとして負数を受け付けるようになりました。

  • もう一つ追加の文字列メソッドは zfill() で、これは string モジュール内で元々関数だったものです。 zfill() は指定の幅まで数値文字列の左側にゼロ埋めをします。なお、 % 演算子の方が今でも zfill() より柔軟で強力です。:

    >>> '45'.zfill(4)
'0045'
>>> '12345'.zfill(4)
'12345'
>>> 'goofy'.zfill(6)
'0goofy'

    (Contributed by Walter Dörwald.)

  • 新規の型オブジェクト basestring が追加されました。 8 ビット文字列と Unicode 文字列はともにこの型から派生しているので、 isinstance(obj, basestring) はどちらの文字列型でも True を返します。これは完全に抽象型なので basestring のインスタンスを構築することは出来ません。 (---訳注: Python 3 では文字列 = Unicode、バイト列の扱いが大きく変わり、まずバイト列と Unicode は決して同じものとはみなされません (今ここで 8 ビット文字列と呼んでいるものは Python 3 では文字列ではありません、バイト列です) し、 basestring 型も撤廃されています。Python 2.7 で Python 3 をサポートする必要があるような場合は、なるべく basestring に依存しないようにした方が良いです。---)

  • 内部化した文字列はもう不死身ではないので、内部辞書からの参照が、参照している唯一のものとなれば、普通にガーベージコレクト対象となります。 (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*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 バージョン 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 モジュールとして追加されています。詳細はこのドキュメントの下の方に記述してありますのでそちらを参照して下さい。

  • Distutils の Extension クラスに新たにコンストラクタ引数 depends が追加されました。これは拡張が依存する追加的なソースファイルを列挙します。Distutils はその依存ファイルのいずれかが更新されると再コンパイルを行います。例えば sampmodule.c がヘッダファイル sample.h をインクルードしているとして、 Extension オブジェクトをこのように構築します:

    ext = Extension("samp",
                sources=["sampmodule.c"],
                depends=["sample.h"])

    sample.h を修正するとモジュールは再コンパイルされます。 (Contributed by Jeremy Hylton.)

  • Distutils のほかのマイナーな変更: 環境変数 CC, CFLAGS, CPP, LDFLAGS, CPPFLAGS をチェックして Python のコンフィグレーションでの設定をオーバライドするようになっています (contributed by Robert Weber)。

  • 以前までは doctest モジュールは公開メソッドの docstring とテストケースの関数を検索するだけでしたが、今ではプライベートなものも調べます。 DocTestSuite() 関数は doctest テスト群から unittest.TestSuite オブジェクトを作ります。

  • 新しい関数 gc.get_referents(object) は object により参照されている全てのオブジェクトのリストを返します。

  • getopt モジュールに新規関数 gnu_getopt() が追加されました。これは既存の getopt() 関数と同じ引数を取りますが、GNU スタイルの走査モードを使います。既存の getopt() 関数は非オプション引数が現れるとすぐにオプション処理をやめますが、GNU スタイルモードは処理を続行するので、オプションと引数をミックス出来ます。例えば:

    >>> 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(lg n). (See https://xlinux.nist.gov/dads//HTML/priorityque.html for more information about the priority queue data structure.)

    heapq モジュールには、 heappush() 関数と heappop() 関数が含まれており、これらはほかの mutable な Python シーケンス型の上にヒーププライオリティを保ちつつアイテムの追加と削除を行います。Python リストを使う例としてはこのような具合です:

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

  • IDLE 統合開発環境は IDLEfork プロジェクト (http://idlefork.sourceforge.net) からのコードを用いるように更新されました。最も特筆すべき特徴は開発コードがサブプロセスで実行されるようになったことで、これにより手動で reload() 操作を行う必要はなくなっています。IDLE の中核コードは標準ライブラリの idlelib パッケージとして組み込まれました。

  • imaplib モジュールが IMAP over SSL をサポートするようになりました. (Contributed by Piers Lauder and Tino Lange.)

  • itertools モジュールは ML 言語や Haskell 言語で提供されている様々な関数に触発された、イテレータとともに用いる有用な数多くの関数を含んでいます。例えば、 itertools.ifilter(predicate, iterator) はイテレータ内で関数 predicate() が True を返す要素全てを返し、 itertools.repeat(obj, N) は obj の N 回繰り返しを返します。ほかにもモジュールには数多くの関数を含んでいます。詳細はパッケージのドキュメントを参照してください。(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.)

  • いくつもの新規 POSIX 関数 (getpgid(), killpg(), lchown(), loadavg(), major(), makedev(), minor(), mknod()) が os モジュールの下位の posix モジュールに追加されました。(Contributed by Gustavo Niemeyer, Geert Jansen, and Denis S. Otkidach.)

  • os モジュール内の *stat() 系関数が、タイムスタンプの秒の端数を報告するようになりました。そのようなタイムスタンプは time.time() が返すのと同じで浮動小数点数で表現されます。

    テストを通じて、タイムスタンプが浮動小数点となっていくつかのアプリケーションが破壊されることがわかっています。互換性のために、 stat_result タイムスタンプのタプルインターフェイスは整数で表現されます。名前付きフィールド (これは Python 2.2 で最初に導入されました) を用いる場合にもタイムスタンプは今でも整数ですが、 os.stat_float_times() を呼び出すことで浮動小数点数で返却するように出来ます:

    >>> os.stat("/tmp").st_mtime
1034791200
>>> os.stat_float_times(True)
>>> os.stat("/tmp").st_mtime
1034791200.6335014

    Python 2.4 では、浮動小数点数を返すのがデフォルトとなります。

    アプリケーション開発者は、この機能を有効にするのは、全ての自身のライブラリが浮動小数点数のタイムスタンプで正しく動作するか、タプル API を使用する場合のみにしてください。使うのであればこの機能は、都度都度有効にしようとせずにアプリケーションレベルで有効にすべきです。

  • optparse モジュールに新たなコマンドライン引数パーサが追加されました。これはオプション値を特定の Python 型に変換することが出来、また、自動的に使用例メッセージを生成します。詳細はこのドキュメントの続くセクションを参照して下さい。

  • 古く、また一度としてドキュメントされたこともない linuxaudiodev モジュールは非推奨となり、新しいバージョンが ossaudiodev として追加されました。このモジュールがリネームされたのは OSS サウンドドライバは Linux に限って利用出来るものではなく、インターフェイスも整理され、色々な手で更新されたからです。(Contributed by Greg Ward and Nicholas FitzRoy-Dale.)

  • 実行中のプラットフォームについての色々な特性を決定する数多くの関数を含む、新規 platform モジュールが追加されました。アーキテクチャ、CPU タイプ、Windows の OS バージョンや Linux ディストリビューションのバージョンなどを取得できます。(Contributed by Marc-André Lemburg.)

  • pyexpat モジュールのパーサオブジェクトが、オプショナルで文字データをバッファ出来るようになりました。結果として文字データハンドラの呼び出しが少なくなり、速くなります。バッファリングの有効化にはパーサオブジェクトの buffer_text 属性を True にセットします。

  • random モジュールに sample(population, k) 関数が追加されました。 population は母集団の要素を含んだ、シーケンスか xrange オブジェクトで、 sample() は母集団から k 要素を値の置換なしに選択します。 k は len(population) までの任意の値を渡せます。例えば:

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

  • readline モジュールは多くの新規関数を追加しました: get_history_item(), get_current_history_length(), redisplay() 。

  • rexec モジュールと Bastion モジュールはもう利用出来ないようにしてあります。インポートを試みれば RuntimeError を投げます。新スタイルクラスは rexec により提供される制限実行環境を突破する新たな術を持っており、誰もそれを修正することに興味もなく、その時間も持っていません。 rexec を使うアプリケーションを持っているならば、何かほかの手段で書き換えてください。

    (Python 2.2 または 2.1 に留まるにしてもそれは何一つあなたのアプリケーションを安全にはしません。それらバージョンの rexec モジュールには既知のバグがあるからです。繰り返します。 rexec を使っているなら、即座に使用をやめてください。)

  • rotor モジュールが非推奨となりました。暗号化に使うアルゴリズムが安全ではないと思われているからです。暗号が必要なのであれば、独立して入手出来るいくつもの AES Python モジュールのなかの一つを使ってください。(---訳注: rotor モジュールは 2.4 で削除されました。---)

  • 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) サポートが始まりました。

  • C マクロの PYTHON_API_VERSION の値が Python レベルで sys.api_version として公開されるようになりました。新関数 sys.exc_clear() を呼び出すことで、現在の例外をクリア出来るようになりました。

  • 新モジュール tarfile で tar 形式のアーカイブファイルの読み書きが出来ます。 (Contributed by Lars Gustäbel.)

  • 新規モジュール textwrap には、テキストのパラグラフを含んだ文字列を折り返すための関数群を含まれています。 wrap(text, width) 関数は文字列を入力に取り、指定した幅より長いものを含まない行に分割して文字列のリストで返します。 fill(text, width) 関数は指定した幅を超えない分割行に再整形して単一文字列で返します。(ご想像どおり fill() は wrap() の上に構築されています。例えば:

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

    モジュールには実際のテキスト折り返しの戦略を実装する TextWrapper クラスが含まれています。 TextWrapper クラスと wrap() 関数、 fill() 関数のどちらも、整形を細かく制御するための数多くの追加的なキーワード引数をサポートしています。詳細はモジュールのドキュメントを調べてください。(Contributed by Greg Ward.)

  • thread モジュールと threading モジュールの仲間として、プラットフォームがスレッドをサポートしない場合の何もしない実装の thread モジュールインターフェイスとして dummy_thread と dummy_threading が追加されました。これはスレッド化を意図する (スレッドが実際動くかには依存 しない) モジュールがコードの先頭に以下のように書くことで単純化することを狙ったものです:

    try:
    import threading as _threading
except ImportError:
    import dummy_threading as _threading

    この例ではモジュール名として _threading を使っていて、これは実際の threading モジュールが必ずしも必要ではないことをはっきりさせています。 _threading モジュール内の関数とクラスはスレッドがサポートされているいないに関わらず呼び出すことが出来、これは if 文を避け、コードを少しばかり明快にします。このモジュールはスレッドなしのマルチスレッドコードを走らせるのに特別なことをしません。つまり他のスレッドが戻るのを待ったり何か他のことをするのを待つコードは、単に永遠にハングします。

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

  • xml.dom.minidom の DOM 実装で、指定したエンコーディングによる XML 出力が可能になりました。DOM ノードの toxml() メソッド、 toprettyxml() メソッドにオプショナルなエンコーディング引数を与えることで行えます。

  • 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 モジュールとして追加されました。これら型は異なるカレンダであるとか多くの洒落た機能をサポートはせずに、時刻表現の基礎だけに集中するものです。

The three primary types are: date, representing a day, month, and year; time, consisting of hour, minute, and second; and datetime, which contains all the attributes of both date and time. There's also a timedelta class representing differences between two points in time, and time zone logic is implemented by classes inheriting from the abstract tzinfo class.

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

Instances can be compared, hashed, and converted to strings (the result is the same as that of isoformat()). date and datetime instances can be subtracted from each other, and added to timedelta instances. The largest missing feature is that there's no standard library support for parsing strings and getting back a date or datetime.

さらに詳しい情報については、モジュールのリファレンスドキュメントを参照してください。 (Contributed by Tim Peters.)

optparse モジュール

The getopt module provides simple parsing of command-line arguments. The new optparse module (originally named Optik) provides more elaborate command-line parsing that follows the Unix conventions, automatically creates the output for --help, and can perform different actions for different options.

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

これは、全てのオプションの値を含んだオブジェクトと残った引数を含む文字列リストを返します。

Invoking the script with the various arguments now works as you'd expect it to. Note that the length argument is automatically converted to an integer.

$ ./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}>
[]
$

The help message is automatically generated for you:

$ ./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() 関数を大きなメモリプールを得るのに使い、それより小さなメモリ要求はこれらプールで実現しています。

In 2.1 and 2.2, pymalloc was an experimental feature and wasn't enabled by default; you had to explicitly enable it when compiling Python by providing the --with-pymalloc option to the configure script. In 2.3, pymalloc has had further enhancements and is now enabled by default; you'll have to supply --without-pymalloc to disable it.

この変更は 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() を使います。

Thanks to lots of work by Tim Peters, pymalloc in 2.3 also provides debugging features to catch memory overwrites and doubled frees in both extension modules and in the interpreter itself. To enable this support, compile a debugging version of the Python interpreter by running configure with --with-pydebug.

拡張の著者のために、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 の変更は以下の通りです:

  • The cycle detection implementation used by the garbage collection has proven to be stable, so it's now been made mandatory. You can no longer compile Python without it, and the --with-cycle-gc switch to configure has been removed.
  • Python can now optionally be built as a shared library (libpython2.3.so) by supplying --enable-shared when running Python's configure script. (Contributed by Ondrej Palkovsky.)
  • マクロ DL_EXPORT と DL_IMPORT が非推奨となっています。Python コアが一般的にマクロ PyAPI_FUNC と PyAPI_DATA を使うのに対し、Python 拡張モジュールの初期化関数が新規マクロ PyMODINIT_FUNC を使って宣言されなければならなくなりました。
  • The interpreter can be compiled without any docstrings for the built-in functions and modules by supplying --without-doc-strings to the configure script. This makes the Python executable about 10% smaller, but will also mean that you can't get help for Python's built-ins. (Contributed by Gustavo Niemeyer.)
  • 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 秒になりました)。
  • C 拡張型のクラスメソッドと静的メソッドを定義出来るようになりました。メソッドの PyMethodDef 構造体に METH_CLASS フラグか METH_STATIC フラグをセットすることで行えます。
  • Python は Expat XML パーサのソースコードのコピーを丸抱えするようになり、これにより Expat のシステムのバージョンやローカルにインストールされたものへの依存がなくなっています。
  • If you dynamically allocate type objects in your extension, you should be aware of a change in the rules relating to the __module__ and __name__ attributes. In summary, you will want to ensure the type's dictionary contains a '__module__' key; making the module name the part of the type name leading up to the final period will no longer have the desired effect. For more detail, read the API reference documentation or the source.

ポート特有の変更

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 プログラムのその実行の一部としてセットすることが出来ます。

  • The regrtest.py script now provides a way to allow "all resources except foo." A resource name passed to the -u option can now be prefixed with a hyphen ('-') to mean "remove this resource." For example, the option '-uall,-bsddb' could be used to enable the use of all resources except 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 »


変更履歴

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • What's New in Python »

変更履歴

Python 3.7.2 final

リリース日: 2018-12-23

ライブラリ

  • bpo-31715: Associate .mjs file extension with application/javascript MIME Type.

ビルド

  • 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: Avoid leaking the linker flags from Link Time Optimizations (LTO) into distutils when compiling C extensions.

C API

  • bpo-35259: Conditionally declare Py_FinalizeEx() (new in 3.6) based on Py_LIMITED_API. Patch by Arthur Neufeld.

Python 3.7.2 release candidate 1

リリース日: 2018-12-11

セキュリティ

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

Core and Builtins

  • bpo-35444: Fixed error handling in pickling methods when fail to look up builtin "getattr".
  • bpo-35436: Fix various issues with memory allocation error handling. Patch by Zackery Spytz.
  • 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: Fixed the code page decoder for input longer than 2 GiB containing undecodable bytes.
  • bpo-35336: Fix PYTHONCOERCECLOCALE=1 environment variable: only coerce the C locale if the LC_CTYPE locale is "C".
  • bpo-33954: For str.format(), float.__format__() and complex.__format__() methods for non-ASCII decimal point when using the "n" formatter.
  • bpo-35269: Fix a possible segfault involving a newly-created coroutine. Patch by Zackery Spytz.
  • 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: 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: 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-29341: Clarify in the docstrings of os methods that path-like objects are also accepted as input parameters.
  • bpo-35050: socket: Fix off-by-one bug in length check for AF_ALG name and type.
  • bpo-34974: bytes and bytearray constructors no longer convert unexpected exceptions (e.g. MemoryError and KeyboardInterrupt) to TypeError.
  • bpo-34973: Fixed crash in bytes() when the list argument is mutated while it is iterated.
  • bpo-34824: Fix a possible null pointer dereference in Modules/_ssl.c. Patch by Zackery Spytz.
  • bpo-1621: Do not assume signed integer overflow behavior (C undefined behavior) when performing set hash table resizing.

ライブラリ

  • 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-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-34172: Revert the fix for this issue previously released in 3.7.1 pending further investigation: Fix a reference issue inside multiprocessing.Pool that caused the pool to remain alive if it was deleted without being closed or terminated explicitly.
  • 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-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: Enable TCP_NODELAY on Windows for proactor asyncio event loop.
  • bpo-35341: Add generic version of collections.OrderedDict to the typing module. Patch by Ismo Toijala.
  • bpo-35371: Fixed possible crash in os.utime() on Windows when pass incorrect arguments.
  • bpo-27903: Fix ResourceWarning in platform.dist() on SuSE and Caldera OpenLinux. Patch by Ville Skyttä.
  • bpo-35308: Fix regression in webbrowser where default browsers may be preferred over browsers in the BROWSER environment variable.
  • 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: Update ensurepip to install pip 18.1 and setuptools 40.6.2.
  • 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: 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: Modify the following fnctl function to retry if interrupted by a signal (EINTR): flock, lockf, fnctl
  • bpo-35062: Fix incorrect parsing of _io.IncrementalNewlineDecoder's translate argument.
  • bpo-35079: Improve difflib.SequenceManager.get_matching_blocks doc by adding 'non-overlapping' and changing '!=' to '<'.
  • bpo-35017: socketserver.BaseServer.serve_forever() now exits immediately if it's shutdown() method is called while it is polling for new events.
  • bpo-31047: Fix ntpath.abspath regression where it didn't remove a trailing separator on Windows. Patch by Tim Graham.
  • bpo-34794: Fixed a leak in Tkinter when pass the Python wrapper around Tcl_Obj back to Tcl/Tk.
  • 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: Verify the value for the parameter '-s' of the cProfile CLI. Patch by Robert Kuska
  • bpo-33947: dataclasses now handle recursive reprs without raising RecursionError.
  • bpo-16965: The 2to3 execfile fixer now opens the file with mode 'rb'. Patch by Zackery Spytz.
  • 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-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-34936: Fix TclError in tkinter.Spinbox.selection_element(). Patch by Juliette Monsel.
  • 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-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-34738: ZIP files created by distutils will now include entries for directories.
  • bpo-31177: Fix bug that prevented using reset_mock on mock instances with deleted attributes
  • bpo-34536: Enum._missing_: raise ValueError if None returned and TypeError if non-member is returned.
  • 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-34574: OrderedDict iterators are not exhausted during pickling anymore. Patch by Sergey Fedoseev.
  • 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-29877: compileall: import ProcessPoolExecutor only when needed, preventing hangs on low resource platforms
  • bpo-22005: Implemented unpickling instances of datetime, date and time pickled by Python 2. encoding='latin1' should be used for successful decoding.

ドキュメント

  • bpo-35089: Remove mention of typing.io and typing.re. Their types should be imported from typing directly.
  • bpo-35038: Fix the documentation about an unexisting f_restricted attribute in the frame object. Patch by Stéphane Wirtel
  • bpo-35044: Fix the documentation with the role exc for the appropriated exception. Patch by Stéphane Wirtel
  • bpo-35035: Rename documentation for email.utils to email.utils.rst.
  • bpo-34967: Use app.add_object_type() instead of the deprecated Sphinx function app.description_unit()
  • bpo-11233: Create availability directive for documentation. Original patch by Georg Brandl.
  • bpo-33594: Document getargspec, from_function and from_builtin as deprecated in their respective docstring, and include version since deprecation in DeprecationWarning message.
  • bpo-32613: Update the faq/windows.html to use the py command from PEP 397 instead of python.

テスト

  • bpo-33725: test_multiprocessing_fork may crash on recent versions of macOS. Until the issue is resolved, skip the test on macOS.
  • bpo-35352: Modify test_asyncio to use the certificate set from the test directory.
  • 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: 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: 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-35296: The Windows installer (MSI) now also install internal header files (Include/internal/ subdirectory).
  • 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: Fix a compiler error when statically linking pyexpat in Modules/Setup.
  • 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: Have --with-lto works correctly with clang.
  • bpo-33015: Fix an undefined behaviour in the pthread implementation of PyThread_start_new_thread(): add a function wrapper to always return NULL.

Windows

  • bpo-35401: Updates Windows build to OpenSSL 1.1.0j
  • bpo-34977: venv on Windows will now use a python.exe redirector rather than copying the actual binaries from the base environment.
  • bpo-34977: Adds support for building a Windows App Store package
  • bpo-35067: Remove _distutils_findvs module and use vswhere.exe instead.
  • bpo-34532: Fixes exit code of list version arguments for py.exe.
  • bpo-32890: Fix usage of GetLastError() instead of errno in os.execve() and os.truncate().

macOS

  • bpo-35402: Update macOS installer to use Tcl/Tk 8.6.9.1.
  • bpo-35401: Update macOS installer to use OpenSSL 1.1.0j.
  • bpo-35025: Properly guard the use of the CLOCK_GETTIME et al. macros in timemodule on macOS.
  • bpo-24658: On macOS, fix reading from and writing into a file with a size larger than 2 GiB.

IDLE

  • bpo-35213: Where appropriate, use 'macOS' in idlelib.
  • bpo-34864: On macOS, warn if the system preference "Prefer tabs when opening documents" is set to "Always".
  • 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: Remove unused imports from lib/idlelib
  • bpo-33000: Document that IDLE's shell has no line limit. A program that runs indefinitely can overfill memory.
  • bpo-23220: Explain how IDLE's Shell displays output.
  • 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: Add IDLE doc subsection explaining editor windows. Topics include opening, title and status bar, .py* extension, and running.
  • bpo-35093: Document the IDLE document viewer in the IDLE doc. Add a paragraph in "Help and preferences", "Help sources" subsection.
  • bpo-35088: Update idlelib.help.copy_string docstring. We now use git and backporting instead of hg and forward merging.
  • bpo-35087: Update idlelib help files for the current doc build. The main change is the elimination of chapter-section numbers.

Tools/Demos

  • bpo-34989: python-gdb.py now handles errors on computing the line number of a Python frame.

C API

  • bpo-35322: Fix memory leak in PyUnicode_EncodeLocale() and PyUnicode_EncodeFSDefault() on error handling.
  • bpo-35296: make install now also installs the internal API: Include/internal/*.h header files.
  • bpo-34725: Adds _Py_SetProgramFullPath so embedders may override sys.executable

Python 3.7.1 final

Release date: 2018-10-20

ライブラリ

  • bpo-34970: Protect tasks weak set manipulation in asyncio.all_tasks()

Python 3.7.1 release candidate 2

Release date: 2018-10-13

Core and Builtins

  • bpo-34879: Fix a possible null pointer dereference in bytesobject.c. Patch by Zackery Spytz.
  • 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-34320: Fix dict(od) didn't copy iteration order of OrderedDict.

ライブラリ

  • bpo-34769: Fix for async generators not finalizing when event loop is in debug mode and garbage collector runs in another thread.
  • bpo-34922: Fixed integer overflow in the digest() and hexdigest() methods for the SHAKE algorithm in the hashlib module.
  • bpo-34909: Enum: fix grandchildren subclassing when parent mixed with concrete data types.
  • bpo-34900: Fixed unittest.TestCase.debug() when used to call test methods with subtests. Patch by Bruno Oliveira.
  • bpo-34871: Fix inspect module polluted sys.modules when parsing __text_signature__ of callable.
  • bpo-34872: Fix self-cancellation in C implementation of asyncio.Task
  • 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-34521: Use socket.CMSG_SPACE() to calculate ancillary data size instead of socket.CMSG_LEN() in multiprocessing.reduction.recvfds() as RFC 3542 requires the use of the former for portable applications.
  • bpo-34334: In QueueHandler, clear exc_text from LogRecord to prevent traceback from being written twice.
  • bpo-6721: Acquire the logging module's commonly used internal locks while fork()ing to avoid deadlocks in the child process.
  • bpo-34172: Fix a reference issue inside multiprocessing.Pool that caused the pool to remain alive if it was deleted without being closed or terminated explicitly.

ドキュメント

  • bpo-32174: chm document displays non-ASCII charaters properly on some MBCS Windows systems.

テスト

  • bpo-32962: Fixed test_gdb when Python is compiled with flags -mcet -fcf-protection -O0.

macOS

  • bpo-34370: Revert to using the released Tk 8.6.8 with macOS installers instead of the Tk 8.6.x development snapshot used with 3.7.1rc1 and 3.6.7rc1. The snapshot introduced at least one significant regression (bpo-34927).

C API

  • bpo-34910: Ensure that PyObject_Print() always returns -1 on error. Patch by Zackery Spytz.

Python 3.7.1 release candidate 1

Release date: 2018-09-26

セキュリティ

  • 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: CVE-2018-14647: The C accelerated _elementtree module now initializes hash randomization salt from _Py_HashSecret instead of libexpat's default CSPRNG.
  • bpo-34405: Updated to OpenSSL 1.1.0i for Windows builds.
  • 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: Fixed thread-safety of error handling in _ssl.

Core and Builtins

  • bpo-34783: Fix a crash with musl libc (on Alpine Linux) when the script filename specified on the command line doesn't exist.
  • bpo-34762: Fix contextvars C API to use PyObject* pointer types.
  • bpo-34735: Fix a memory leak in Modules/timemodule.c. Patch by Zackery Spytz.
  • bpo-34588: Fix an off-by-one in the recursive call pruning feature of traceback formatting.
  • 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: Fix the error handler of standard streams like sys.stdout: PYTHONIOENCODING=":" is now ignored instead of setting the error handler to "strict".
  • 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: The UTF-8 Mode is now also enabled by the "POSIX" locale, not only by the "C" locale.
  • bpo-34400: Fix undefined behavior in parsetok.c. Patch by Zackery Spytz.
  • bpo-34377: Update valgrind suppression list to use _PyObject_Free/_PyObject_Realloc instead of PyObject_Free/PyObject_Realloc.
  • bpo-34170: -X dev: it is now possible to override the memory allocator using PYTHONMALLOC even if the developer mode is enabled.
  • bpo-34126: Fix crashes when profiling certain invalid calls of unbound methods. Patch by Jeroen Demeyer.
  • bpo-24618: Fixed reading invalid memory when create the code object with too small varnames tuple or too large argument counts.
  • 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: Fix buffer overflow while converting unicode to numeric values.
  • bpo-34080: Fixed a memory leak in the compiler when it raised some uncommon errors during tokenizing.
  • bpo-34066: Disabled interruption by Ctrl-C between calling open() and entering a with block in with open().
  • bpo-34042: Fix dict.copy() to maintain correct total refcount (as reported by sys.gettotalrefcount()).
  • bpo-33985: Implement contextvars.ContextVar.name attribute.
  • bpo-33956: Update vendored Expat library copy to version 2.2.5.
  • bpo-24596: Decref the module object in PyRun_SimpleFileExFlags() before calling PyErr_Print(). Patch by Zackery Spytz.
  • bpo-33451: Close directly executed pyc files before calling PyEval_EvalCode().
  • 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-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-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: Fix assertion failures in the tell() method of io.TextIOWrapper. Patch by Zackery Spytz.
  • bpo-31577: Fix a crash in os.utime() in case of a bad ns argument. Patch by Oren Milman.

ライブラリ

  • bpo-29577: Support multiple mixin classes when creating Enums.
  • bpo-34670: Add SSLContext.post_handshake_auth and SSLSocket.verify_client_post_handshake for TLS 1.3's post handshake authentication feature.
  • 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: Ensure os.lchmod() is never defined on Linux.
  • bpo-34363: dataclasses.asdict() and .astuple() now handle namedtuples correctly.
  • bpo-34625: Update vendorized expat library version to 2.2.6.
  • bpo-34621: Fix un/pickling compatbility of uuid.UUID objects with older versions of Python (<3.7).
  • 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-34610: Fixed iterator of multiprocessing.managers.DictProxy.
  • bpo-34421: Fix distutils logging for non-ASCII strings. This caused installation issues on Windows.
  • bpo-34604: Fix possible mojibake in the error message of pwd.getpwnam and grp.getgrnam. Patch by William Grzybowski.
  • bpo-34530: distutils.spawn.find_executable() now falls back on os.defpath if the PATH environment variable is not set.
  • bpo-34282: Fix enum members getting shadowed by parent attributes.
  • 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: Correct typo in Lib/ctypes/_aix.py
  • bpo-34515: Fix parsing non-ASCII identifiers in lib2to3.pgen2.tokenize (PEP 3131).
  • 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: 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: 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: Fix inspect.getsourcelines for module level frames/tracebacks. Patch by Vladimir Matveev.
  • bpo-34171: Running the trace module no longer creates the trace.cover file.
  • 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-34341: Appending to the ZIP archive with the ZIP64 extension no longer grows the size of extra fields of existing entries.
  • bpo-34333: Fix %-formatting in pathlib.PurePath.with_suffix() when formatting an error message.
  • 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-34246: smtplib.SMTP.send_message() no longer modifies the content of the mail_options argument. Patch by Pablo S. Blum de Aguiar.
  • bpo-31047: Fix ntpath.abspath for invalid paths on windows. Patch by Franz Woellert.
  • bpo-34263: asyncio's event loop will not pass timeouts longer than one day to epoll/select etc.
  • bpo-34035: Fix several AttributeError in zipfile seek() methods. Patch by Mickaël Schoentgen.
  • bpo-32215: Fix performance regression in sqlite3 when a DML statement appeared in a different line than the rest of the SQL query.
  • bpo-34251: Restore msilib.Win64 to preserve backwards compatibility since it's already used by distutils' bdist_msi command.
  • bpo-19891: Ignore errors caused by missing / non-writable homedir while writing history during exit of an interactive session. Patch by Anthony Sottile.
  • bpo-34213: Allow frozen dataclasses to have a field named "object". Previously this conflicted with an internal use of "object".
  • bpo-21446: The reload fixer now uses importlib.reload() instead of deprecated imp.reload().
  • bpo-940286: pydoc's Helper.showtopic() method now prints the cross references of a topic correctly.
  • bpo-34164: base64.b32decode() could raise UnboundLocalError or OverflowError for incorrect padding. Now it always raises base64.Error in these cases.
  • bpo-33729: Fixed issues with arguments parsing in hashlib.
  • bpo-34108: Remove extraneous CR in 2to3 refactor.
  • bpo-27494: Reverted bpo-27494. 2to3 rejects now a trailing comma in generator expressions.
  • bpo-33967: functools.singledispatch now raises TypeError instead of IndexError when no positional arguments are passed.
  • 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 hash-based pycs.
  • bpo-34054: The multiprocessing module now uses the monotonic clock time.monotonic() instead of the system clock time.time() to implement timeout.
  • 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: 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: webbrowser: Correct the arguments passed to Opera Browser when opening a new URL using the webbrowser module. Patch by Bumsik Kim.
  • bpo-33978: Closed existing logging handlers before reconfiguration via fileConfig and dictConfig. Patch by Karthikeyan Singaravelan.
  • bpo-14117: Make minor tweaks to turtledemo. The 'wikipedia' example is now 'rosette', decribing what it draws. The 'penrose' print output is reduced. The'1024' output of 'tree' is eliminated.
  • bpo-33974: Fixed passing lists and tuples of strings containing special characters ", \, {, } and \n as options to ttk widgets.
  • bpo-27500: Fix getaddrinfo to resolve IPv6 addresses correctly.
  • bpo-24567: Improve random.choices() to handle subnormal input weights that could occasionally trigger an IndexError.
  • 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-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-33916: bz2 and lzma: When Decompressor.__init__() is called twice, free the old lock to not leak memory.
  • bpo-32568: Make select.epoll() and its documentation consistent regarding sizehint and flags.
  • bpo-33833: Fixed bug in asyncio where ProactorSocketTransport logs AssertionError if force closed during write.
  • bpo-33663: Convert content length to string before putting to header.
  • bpo-26544: Fixed implementation of platform.libc_ver(). It almost always returned version '2.9' for glibc.
  • bpo-33805: Improve error message of dataclasses.replace() when an InitVar is not specified
  • bpo-27397: Make email module properly handle invalid-length base64 strings.
  • bpo-33476: Fix _header_value_parser.py when address group is missing final ';'. Contributed by Enrique Perez-Terron
  • 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-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-32933: unittest.mock.mock_open() now supports iteration over the file contents. Patch by Tony Flury.
  • 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-31608: Raise a TypeError instead of crashing if a collections.deque subclass returns a non-deque from __new__. Patch by Oren Milman.
  • bpo-29456: Fix bugs in hangul normalization: u1176, u11a7 and u11c3

ドキュメント

  • bpo-34790: Document how passing coroutines to asyncio.wait() can be confusing.
  • bpo-28617: Fixed info in the stdtypes docs concerning the types that support membership tests.
  • bpo-34065: Fix wrongly written basicConfig documentation markup syntax
  • bpo-33460: replaced ellipsis with correct error codes in tutorial chapter 3.
  • bpo-33847: Add '@' operator entry to index.
  • bpo-25041: Document AF_PACKET in the socket module.

テスト

  • bpo-34537: Fix test_gdb.test_strings() when LC_ALL=C and GDB was compiled with Python 3.6 or earlier.
  • 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: Fix test_shutil if unzip doesn't support -t.
  • 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-34594: Fix usage of hardcoded errno values in the tests.
  • bpo-34542: Use 3072 RSA keys and SHA-256 signature for test certs and keys.
  • bpo-11193: Remove special condition for AIX in test_subprocess.test_undecodable_env
  • 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: Fix ftplib test for TLS 1.3 by reading from data socket.
  • bpo-34399: Update all RSA keys and DH params to use at least 2048 bits.
  • bpo-33746: Fix test_unittest when run in verbose mode.
  • 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: 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-32663: Making sure the SMTPUTF8SimTests class of tests gets run in test_smtplib.py.

ビルド

  • bpo-34710: Fixed SSL module build with OpenSSL & pedantic CFLAGS.
  • bpo-34582: Add JUnit XML output for regression tests and update Azure DevOps builds.
  • 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-34121: Fix detection of C11 atomic support on clang.
  • bpo-30345: Add -g to LDFLAGS when compiling with LTO to get debug symbols.
  • bpo-33648: The --with-c-locale-warning configuration flag has been removed. It has had no effect for about a year.

Windows

  • bpo-34770: Fix a possible null pointer dereference in pyshellext.cpp.
  • bpo-34603: Fix returning structs from functions produced by MSVC
  • bpo-34581: Guard MSVC-specific code in socketmodule.c with #ifdef _MSC_VER.
  • bpo-34062: Fixed the '--list' and '--list-paths' arguments for the py.exe launcher
  • bpo-34225: Ensure INCLUDE and LIB directories do not end with a backslash.
  • 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: 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: Output error when ReadConsole is canceled by CancelSynchronousIo instead of crashing.
  • bpo-29097: Fix bug where datetime.fromtimestamp() erronously throws an OSError on Windows for values between 0 and 86400. Patch by Ammar Askar.

macOS

  • bpo-34370: Have macOS 10.9+ installer builds for 3.7.1rc and 3.6.7rc use a development snapshot of Tk 8.6 (post-8.6.8) to mitigate certain scroller issues seen with IDLE and tkinter apps.
  • bpo-34405: Update to OpenSSL 1.1.0i for macOS installer builds.
  • 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-31903: In _scproxy, drop the GIL when calling into SystemConfiguration to avoid deadlocks.

IDLE

  • bpo-34548: Use configured color theme for read-only text views.
  • 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: Fixed mousewheel scrolling direction on macOS.
  • bpo-34275: Make IDLE calltips always visible on Mac. Some MacOS-tk combinations need .update_idletasks(). Patch by Kevin Walzer.
  • bpo-34120: Fix unresponsiveness after closing certain windows and dialogs.
  • 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: Add test for idlelib.stackview.StackBrowser.
  • bpo-33924: Change mainmenu.menudefs key 'windows' to 'window'. Every other menudef key is lowercase version of main menu entry.
  • bpo-33906: Rename idlelib.windows as window Match Window on the main menu and remove last plural module name.
  • 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: IDLE: In rstrip, rename class RstripExtension as Rstrip
  • 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: Add "help" in the welcome message of IDLE
  • bpo-33839: IDLE: refactor ToolTip and CallTip and add documentation and tests
  • bpo-33855: Minimally test all IDLE modules. Add missing files, import module, instantiate classes, and check coverage. Check existing files.

Tools/Demos

  • bpo-32962: python-gdb now catchs UnicodeDecodeError exceptions when calling string().
  • bpo-32962: python-gdb now catchs ValueError on read_var(): when Python has no debug symbols for example.

C API

  • bpo-34247: Fix Py_Initialize() regression introduced in 3.7.0: read environment variables like PYTHONOPTIMIZE.
  • bpo-23927: Fixed SystemError in PyArg_ParseTupleAndKeywords() when the w* format unit is used for optional parameter.
  • bpo-34008: Py_Main() can again be called after Py_Initialize(), as in Python 3.6.

Python 3.7.0 final

Release date: 2018-06-27

ライブラリ

  • bpo-33851: Fix ast.get_docstring() for a node that lacks a docstring.

C API

  • 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: 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: Fix a crash in Python initialization when parsing the command line options. Thanks Christoph Gohlke for the bug report and the fix!
  • 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: Fix signed/unsigned comparison warning in pyhash.c.

ライブラリ

  • bpo-30167: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by Steve Weber.
  • 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: Avoid race condition with debug logging
  • bpo-33694: asyncio: Fix a race condition causing data loss on pause_reading()/resume_reading() when using the ProactorEventLoop.
  • bpo-32493: Correct test for uuid_enc_be availability in configure.ac. Patch by Michael Felt.
  • bpo-33792: Add asyncio.WindowsSelectorEventLoopPolicy and asyncio.WindowsProactorEventLoopPolicy.
  • bpo-33778: Update unicodedata's database to Unicode version 11.0.0.
  • bpo-33770: improve base64 exception message for encoded inputs of invalid length
  • 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: The concatenation (+) and repetition (*) sequence operations now raise TypeError instead of SystemError when performed on mmap.mmap objects. Patch by Zackery Spytz.
  • bpo-33734: asyncio/ssl: Fix AttributeError, increase default handshake timeout
  • bpo-11874: Use a better regex when breaking usage into wrappable parts. Avoids bogus assertion errors from custom metavar strings.
  • bpo-33582: Emit a deprecation warning for inspect.formatargspec

ドキュメント

  • bpo-33409: Clarified the relationship between PEP 538's PYTHONCOERCECLOCALE and PEP 540's PYTHONUTF8 mode.
  • bpo-33736: Improve the documentation of asyncio.open_connection(), asyncio.start_server() and their UNIX socket counterparts.
  • bpo-31432: Clarify meaning of CERT_NONE, CERT_OPTIONAL, and CERT_REQUIRED flags for ssl.SSLContext.verify_mode.

ビルド

  • 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: Reduces maximum marshal recursion depth on release builds.

IDLE

  • 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: Clicking on a context line moves that line to the top of the editor window.
  • bpo-33763: IDLE: Use read-only text widget for code context instead of label widget.
  • 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: 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: 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: 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: Fix module_globals parameter of warnings.warn_explicit(): don't crash if module_globals is not a dict.
  • 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: Fixed miscellaneous bugs in converting annotations to strings and optimized parentheses in the string representation.
  • bpo-33391: Fix a leak in set_symmetric_difference().
  • bpo-28055: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.
  • bpo-32911: Due to unexpected compatibility issues discovered during downstream beta testing, reverted 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: 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-32751: When cancelling the task due to a timeout, asyncio.wait_for() will now wait until the cancellation is complete.
  • bpo-32684: Fix gather to propagate cancellation of itself even with return_exceptions.
  • bpo-33654: Support protocol type switching in SSLTransport.set_protocol().
  • bpo-33674: Pause the transport as early as possible to further reduce the risk of data_received() being called before connection_made().
  • 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: Fixed bug where calling write_eof() on a _SelectorSocketTransport after it's already closed raises AttributeError.
  • bpo-32610: Make asyncio.all_tasks() return only pending tasks.
  • bpo-32410: Avoid blocking on file IO in sendfile fallback code
  • bpo-33469: Fix RuntimeError after closing loop that used run_in_executor
  • bpo-33672: Fix Task.__repr__ crash with Cython's bogus coroutines
  • 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: Pickles of type variables and subscripted generics are now future-proof and compatible with older Python versions.
  • bpo-32493: Fixed uuid.uuid1() on FreeBSD.
  • bpo-33618: Finalize and document preliminary and experimental TLS 1.3 support with OpenSSL 1.1.1
  • bpo-33623: Fix possible SIGSGV when asyncio.Future is created in __del__
  • 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: 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: 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: Add a new block_on_close class attribute to ForkingMixIn and ThreadingMixIn classes of socketserver.
  • bpo-33548: tempfile._candidate_tempdir_list should consider common TEMP locations
  • bpo-33109: argparse subparsers are once again not required by default, reverting the change in behavior introduced by bpo-26510 in 3.7.0a2.
  • bpo-33536: dataclasses.make_dataclass now checks for invalid field names and duplicate fields. Also, added a check for invalid field specifications.
  • bpo-33542: Prevent uuid.get_node from using a DUID instead of a MAC on Windows. Patch by Zvi Effron
  • 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: Optimize asyncio.ensure_future() by reordering if checks: 1.17x faster.
  • 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: 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: 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: 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: Updated alias mapping with glibc 2.27 supported locales.
  • bpo-33422: Fix trailing quotation marks getting deleted when looking up byte/string literals on pydoc. Patch by Andrés Delfino.
  • 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: Update error message when constructing invalid inspect.Parameters Patch by Dong-hee Na.
  • bpo-33263: Fix FD leak in _SelectorSocketTransport Patch by Vlad Starostin.
  • 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: The ssl module now contains OP_NO_RENEGOTIATION constant, available with OpenSSL 1.1.0h or 1.1.1.
  • bpo-16865: Support arrays >=2GiB in ctypes. Patch by Segev Finer.

ドキュメント

  • bpo-23859: Document that asyncio.wait() does not cancel its futures on timeout.
  • bpo-32436: Document PEP 567 changes to asyncio.
  • bpo-33604: Update HMAC md5 default to a DeprecationWarning, bump removal to 3.8.
  • bpo-33503: Fix broken pypi link
  • bpo-33421: Add missing documentation for typing.AsyncContextManager.

テスト

  • bpo-33655: Ignore test_posix_fallocate failures on BSD platforms that might be due to running on ZFS.
  • bpo-32604: Remove the _xxsubinterpreters module (meant for testing) and associated helpers. This module was originally added recently in 3.7b1.

ビルド

  • bpo-33614: Ensures module definition files for the stable ABI on Windows are correctly regenerated.
  • bpo-33522: Enable CI builds on Visual Studio Team Services at https://python.visualstudio.com/cpython
  • 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: The .editrc file in user's home directory is now processed correctly during the readline initialization through editline emulation on macOS.

IDLE

  • bpo-33628: IDLE: Cleanup codecontext.py and its test.
  • bpo-33564: IDLE's code context now recognizes async as a block opener.
  • bpo-32831: Add docstrings and tests for codecontext.

Python 3.7.0 beta 4

Release date: 2018-05-02

Core and Builtins

  • bpo-33363: Raise a SyntaxError for async with and async for statements outside of async functions.
  • bpo-33128: Fix a bug that causes PathFinder to appear twice on sys.meta_path. Patch by Pablo Galindo Salgado.
  • 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: Fix potential memory leak in normalizestring().
  • 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: Improved error messages in 'async with' when __aenter__() or __aexit__() return non-awaitable object.
  • bpo-33199: Fix ma_version_tag in dict implementation is uninitialized when copying from key-sharing dict.

ライブラリ

  • bpo-33281: Fix ctypes.util.find_library regression on macOS.

  • bpo-33383: Fixed crash in the get() method of the dbm.ndbm database object when it is called with a single argument.

  • bpo-33329: Fix multiprocessing regression on newer glibcs

  • bpo-991266: Fix quoting of the Comment attribute of http.cookies.SimpleCookie.

  • bpo-33131: Upgrade bundled version of pip to 10.0.1.

  • 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: lib2to3 now recognizes rf'...' strings.

  • bpo-11594: Ensure line-endings are respected when using lib2to3.

  • bpo-33254: Have importlib.resources.contents() and importlib.abc.ResourceReader.contents() return an iterable instead of an iterator.

  • bpo-33256: Fix display of <module> call in the html produced by cgitb.html(). Patch by Stéphane Blondon.

  • 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)

    This fix also changed pydoc to add os.getcwd() to sys.path when necessary, rather than adding ".".

  • bpo-33169: Delete entries of None in sys.path_importer_cache when importlib.machinery.invalidate_caches() is called.

  • bpo-33217: Deprecate looking up non-Enum objects in Enum classes and Enum members (will raise TypeError in 3.8+).

  • bpo-33203: random.Random.choice() now raises IndexError for empty sequences consistently even when called from subclasses without a getrandbits() implementation.

  • bpo-33224: Update difflib.mdiff() for PEP 479. Convert an uncaught StopIteration in a generator into a return-statement.

  • bpo-33209: End framing at the end of C implementation of pickle.Pickler.dump().

  • bpo-20104: Improved error handling and fixed a reference leak in os.posix_spawn().

  • 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: Raise RuntimeError when executor.submit is called during interpreter shutdown.

  • 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-33378: Add Korean language switcher for https://docs.python.org/3/
  • bpo-33276: Clarify that the __path__ attribute on modules cannot be just any value.
  • bpo-33201: Modernize documentation for writing C extension types.
  • 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: Add a note about curses.addch and curses.addstr exception behavior when writing outside a window, or pad.
  • bpo-32337: Update documentation related with dict order.

テスト

  • bpo-33358: Fix test_embed.test_pre_initialization_sys_options() when the interpreter is built with --enable-shared.

ビルド

  • bpo-33394: Enable the verbose build for extension modules, when GNU make is passed macros on the command line.
  • bpo-33393: Update config.guess and config.sub files.
  • bpo-33377: Add new triplets for mips r6 and riscv variants (used in extension suffixes).
  • 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: The embedding tests can once again be built with clang 6.0

Windows

  • bpo-33184: Update Windows installer to use OpenSSL 1.1.0h.

macOS

  • bpo-33184: Update macOS installer build to use OpenSSL 1.1.0h.

IDLE

  • 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: 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: pygettext.py now recognizes only literal strings as docstrings and translatable strings, and rejects bytes literals and f-string expressions.
  • bpo-31920: Fixed handling directories as arguments in the pygettext script. Based on patch by Oleg Krasnikov.
  • bpo-29673: Fix pystackv and pystack gdbinit macros.
  • 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

セキュリティ

  • bpo-33136: Harden ssl module against LibreSSL 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: Minimal fix to prevent buffer overrun in os.symlink on Windows
  • 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 and CVE-2018-1061. Patch by Jamie Davis.

Core and Builtins

  • 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: 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: Fixed jumping when the function contains an async for loop.
  • bpo-33026: Fixed jumping out of "with" block by setting f_lineno.
  • 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: Prevent jumps from 'return' and 'exception' trace events.
  • bpo-32836: Don't use temporary variables in cases of list/dict/set comprehensions

ライブラリ

  • bpo-33141: Have Field objects pass through __set_name__ to their default values, if they have their own __set_name__.
  • 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: 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: 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: The ssl module now compiles with LibreSSL 2.7.1.
  • bpo-32505: Raise TypeError if a member variable of a dataclass is of type Field, but doesn't have a type annotation.
  • bpo-33078: Fix the failure on OSX caused by the tests relying on sem_getvalue
  • bpo-33116: Add 'Field' to dataclasses.__all__.
  • bpo-32896: Fix an error where subclassing a dataclass with a field that uses a default_factory would generate an incorrect class.
  • 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: 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: Add missing NoReturn to __all__ in typing.py
  • bpo-33078: Fix the size handling in multiprocessing.Queue when a pickling error occurs.
  • bpo-33064: lib2to3 now properly supports trailing commas after *args and **kwargs in function signatures.
  • bpo-33056: FIX properly close leaking fds in concurrent.futures.ProcessPoolExecutor.
  • 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: Avoid failing in multiprocessing.Process if the standard streams are closed or None at exit.
  • bpo-33037: Skip sending/receiving data after SSL transport closing.
  • 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: Fix C implementation of ABC.__subclasscheck__(cls, subclass) crashed when subclass is not a type object.
  • bpo-33009: Fix inspect.signature() for single-parameter partialmethods.
  • bpo-32969: Expose several missing constants in zlib and fix corresponding documentation.
  • 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: Fix wrong redirection of a low descriptor (0 or 1) to stderr in subprocess if another low descriptor is closed.
  • bpo-32857: In tkinter, after_cancel(None) now raises a ValueError instead of canceling the first scheduled function. Patch by Cheryl Sabella.
  • 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: 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-33126: Document PyBuffer_ToContiguous().
  • bpo-27212: Modify documentation for the islice() recipe to consume initial values up to the start index.
  • bpo-28247: Update zipapp documentation to describe how to make standalone applications.
  • bpo-18802: Documentation changes for ipaddress. Patch by Jon Foster and Berker Peksag.
  • bpo-27428: Update documentation to clarify that WindowsRegistryFinder implements MetaPathFinder. (Patch by Himanshu Lakhara)

テスト

  • bpo-32872: Avoid regrtest compatibility issue with namespace packages.
  • bpo-32517: Fix failing test_asyncio on macOS 10.12.2+ due to transport of KqueueSelector loop was not being closed.
  • bpo-19417: Add test_bdb.py.

ビルド

  • bpo-33163: Upgrade pip to 9.0.3 and setuptools to v39.0.1.

Windows

  • bpo-33016: Fix potential use of uninitialized memory in nt._getfinalpathname
  • bpo-32903: Fix a memory leak in os.chdir() on Windows if the current directory is set to a UNC path.

macOS

  • 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: 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: Simplify and rename StringTranslatePseudoMapping in pyparse.

Tools/Demos

  • bpo-32885: Add an -n flag for Tools/scripts/pathfix.py to disable automatic backup creation (files with ~ suffix).

C API

  • bpo-33042: Embedding applications may once again call PySys_ResetWarnOptions, PySys_AddWarnOption, and PySys_AddXOption prior to calling Py_Initialize.
  • 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

セキュリティ

  • bpo-28414: The ssl module now allows users to perform their own IDN en/decoding when using SNI.

Core and Builtins

  • bpo-32889: Update Valgrind suppression list to account for the rename of Py_ADDRESS_IN_RANG to address_in_range.
  • bpo-31356: Remove the new API added in bpo-31356 (gc.ensure_disabled() context manager).
  • bpo-32305: For namespace packages, ensure that both __file__ and __spec__.origin are set to None.
  • bpo-32303: Make sure __spec__.loader matches __loader__ for namespace packages.
  • bpo-32711: Fix the warning messages for Python/ast_unparse.c. Patch by Stéphane Wirtel
  • bpo-32583: Fix possible crashing in builtin Unicode decoders caused by write out-of-bound errors when using customized decode error handlers.

ライブラリ

  • 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: Fixed tarfile.itn handling of out-of-bounds float values. Patch by Joffrey Fuhrer.

  • 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: 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: Add OP_ENABLE_MIDDLEBOX_COMPAT and test workaround for TLSv1.3 for future compatibility with OpenSSL 1.1.1.

  • bpo-30622: The ssl module now detects missing NPN support in LibreSSL.

  • bpo-32922: dbm.open() now encodes filename with the filesystem encoding rather than default encoding.

  • bpo-32859: In os.dup2, don't check every call whether the dup3 syscall exists or not.

  • bpo-32556: nt._getfinalpathname, nt._getvolumepathname and nt._getdiskusage now correctly convert from bytes.

  • bpo-25988: Emit a DeprecationWarning when using or importing an ABC directly from collections rather than from collections.abc.

  • 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: Make sure sys.argv remains as a list when running trace.

  • 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: Fixed asyncio.Condition issue which silently ignored cancellation after notifying and cancelling a conditional lock. Patch by Bar Harel.

  • 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: socket: Remove TCP_FASTOPEN,TCP_KEEPCNT,TCP_KEEPIDLE,TCP_KEEPINTVL flags on older version Windows during run-time.

  • bpo-31787: Fixed refleaks of __init__() methods in various modules. (Contributed by Oren Milman)

  • bpo-30157: Fixed guessing quote and delimiter in csv.Sniffer.sniff() when only the last field is quoted. Patch by Jake Davis.

  • bpo-32792: collections.ChainMap() preserves the order of the underlying mappings.

  • 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: Implement native fast sendfile for Windows proactor event loop.

  • 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: 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: Implement asyncio.TimerHandle.when() method.

  • bpo-32691: Use mod_spec.parent when running modules with pdb

  • 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: Do not include name field in SMTP envelope from address. Patch by Stéphane Wirtel

  • bpo-31453: Add TLSVersion constants and SSLContext.maximum_version / minimum_version attributes. The new API wraps OpenSSL 1.1 https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_min_proto_version.html feature.

  • 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: Fix the error handling in Aifc_read.initfp() when the SSND chunk is not found. Patch by Zackery Spytz.

  • bpo-32585: Add Ttk spinbox widget to tkinter.ttk. Patch by Alan D Moore.

  • 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: The TarFile class now recurses directories in a reproducible way.

  • bpo-30693: The ZipFile class now recurses directories in a reproducible way.

ドキュメント

  • 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: Clarify docs for -O and -OO. Patch by Terry Reedy.
  • bpo-32436: Add documentation for the contextvars module (PEP 567).
  • bpo-32800: Update link to w3c doc for xml default namespaces.
  • bpo-11015: Update test.support documentation.
  • bpo-8722: Document __getattr__() behavior when property get() method raises AttributeError.
  • 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: Improve docstrings for pathlib.PurePath subclasses.

テスト

  • bpo-31809: Add tests to verify connection with secp ECDH curves.

ビルド

  • bpo-32898: Fix the python debug build when using COUNT_ALLOCS.

Windows

  • bpo-32901: Update Tcl and Tk versions to 8.6.8
  • bpo-31966: Fixed WindowsConsoleIO.write() for writing empty data.
  • bpo-32409: Ensures activate.bat can handle Unicode contents.
  • bpo-32457: Improves handling of denormalized executable path when launching Python.
  • bpo-32370: Use the correct encoding for ipconfig output in the uuid module. Patch by Segev Finer.
  • 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: Update macOS 10.9+ installer to Tcl/Tk 8.6.8.

IDLE

  • bpo-32916: Change str to code in pyparse.
  • bpo-32905: Remove unused code in pyparse module.
  • bpo-32874: Add tests for pyparse.
  • 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: 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: Update configdialog General tab docstring to add new widgets to the widget list.

Tools/Demos

  • 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: Fix coroutine's ResourceWarning when there's an active error set when it's being finalized.

  • bpo-32650: Pdb and other debuggers dependent on bdb.py will correctly step over (next command) native coroutines. Patch by Pablo Galindo.

  • bpo-28685: Optimize list.sort() and sorted() by using type specialized comparisons when possible.

  • 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: 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: The locals() dictionary now displays in the lexical order that variables were defined. Previously, the order was reversed.

  • bpo-32677: Add .isascii() method to str, bytes and bytearray. It can be used to test that string contains only ASCII characters.

  • bpo-32670: Enforce PEP 479 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: 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: Expose preadv and pwritev system calls in the os module. Patch by Pablo Galindo

  • 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: Improved frozenset() hash to create more distinct hash values when faced with datasets containing many similar values.

  • bpo-32550: Remove the STORE_ANNOTATION bytecode.

  • bpo-20104: Expose posix_spawn as a low level API in the os module. (removed before 3.7.0rc1)

  • bpo-24340: Fixed estimation of the code stack size.

  • bpo-32436: Implement PEP 567 Context Variables.

  • 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: 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: 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: Make dict.copy() up to 5.5 times faster.

  • bpo-31113: Get rid of recursion in the compiler for normal control flow.

ライブラリ

  • bpo-25988: Deprecate exposing the contents of collections.abc in the regular collections module.

  • 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: 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: Added support for setting the compression level for zipfile.ZipFile.

  • bpo-32251: Implement asyncio.BufferedProtocol (provisional API).

  • bpo-32513: In dataclasses, allow easier overriding of dunder methods without specifying decorator parameters.

  • bpo-32660: termios makes available FIONREAD, FIONCLEX, FIOCLEX, FIOASYNC and FIONBIO also under Solaris/derivatives.

  • bpo-27931: Fix email address header parsing error when the username is an empty quoted string. Patch by Xiang Zhang.

  • bpo-32659: Under Solaris and derivatives, os.stat_result provides a st_fstype attribute.

  • 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: Implement asyncio.StreamWriter.wait_closed() and asyncio.StreamWriter.is_closing() methods

  • bpo-32643: Make Task._step, Task._wakeup and Future._schedule_callbacks methods private.

  • bpo-32630: Refactor decimal module to use contextvars to store decimal context.

  • bpo-32622: Add asyncio.AbstractEventLoop.sendfile() method.

  • 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: uuid.uuid1 no longer raises an exception if a 64-bit hardware address is encountered.

  • bpo-32596: concurrent.futures imports ThreadPoolExecutor and ProcessPoolExecutor lazily (using PEP 562). It makes import asyncio about 15% faster because asyncio uses only ThreadPoolExecutor by default.

  • bpo-31801: Add _ignore_ to Enum so temporary variables can be used during class construction without being turned into members.

  • bpo-32576: Use queue.SimpleQueue() in places where it can be invoked from a weakref callback.

  • 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: The nis module is now compatible with new libnsl and headers location.

  • bpo-32467: collections.abc.ValuesView now inherits from collections.abc.Collection.

  • bpo-32473: Improve ABCMeta._dump_registry() output readability

  • bpo-32102: New argument capture_output for subprocess.run

  • bpo-32521: glibc has removed Sun RPC. Use replacement libtirpc headers and library in nis module.

  • bpo-32493: UUID module fixes build for FreeBSD/OpenBSD

  • bpo-32503: Pickling with protocol 4 no longer creates too small frames.

  • bpo-29237: Create enum for pstats sorting options

  • bpo-32454: Add close(fd) function to the socket module.

  • 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: The hmac module now has hmac.digest(), which provides an optimized HMAC digest.

  • bpo-28134: Sockets now auto-detect family, type and protocol from file descriptor by default.

  • bpo-32404: Fix bug where datetime.datetime.fromtimestamp() did not call __new__ in datetime.datetime subclasses.

  • bpo-32403: Improved speed of datetime.date and datetime.datetime alternate constructors.

  • bpo-32228: Ensure that truncate() preserves the file position (as reported by tell()) after writes longer than the buffer size.

  • bpo-32410: Implement loop.sock_sendfile for asyncio event loop.

  • 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: Add socket.getblocking() method.

  • 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: collections.namedtuple() now supports default values.

  • bpo-29302: Add contextlib.AsyncExitStack. Patch by Alexander Mohr and Ilya Kulakov.

  • 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: 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: Use super().method instead of socket.method in SSLSocket. They were there most likely for legacy reasons.

  • 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: Add a queue.SimpleQueue class, an unbounded FIFO queue with a reentrant C implementation of put().

ドキュメント

  • bpo-32724: Add references to some commands in the documentation of Pdb. Patch by Stéphane Wirtel
  • bpo-32649: Complete the C API documentation, profiling and tracing part with the newly added per-opcode events.
  • 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.

テスト

  • bpo-32721: Fix test_hashlib to not fail if the _md5 module is not built.

  • bpo-28414: Add test cases for IDNA 2003 and 2008 host names. IDNA 2003 internationalized host names are working since bpo-31399 has landed. IDNA 2008 are still broken.

  • 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: Add test certs and test for ECDSA cert and EC/RSA dual mode.

  • bpo-32549: On Travis CI, Python now Compiles and uses a local copy of OpenSSL 1.1.0g for testing.

ビルド

  • bpo-32635: Fix segfault of the crypt module when libxcrypt is provided instead of libcrypt at the system.
  • 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: Drop support of FreeBSD 9 and older.
  • bpo-29708: If the SOURCE_DATE_EPOCH environment variable is set, py_compile will always create hash-based .pyc files.

Windows

  • bpo-32588: Create standalone _distutils_findvs module and add missing _queue module to installer.
  • bpo-29911: Ensure separate Modify and Uninstall buttons are displayed.
  • bpo-32507: Use app-local UCRT install rather than the proper update for old versions of Windows.

macOS

  • 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: No longer add /Library/Python/3.x/site-packages to sys.path for macOS framework builds to avoid future conflicts.

C API

  • bpo-32681: Fix uninitialized variable 'res' in the C implementation of os.dup2. Patch by Stéphane Wirtel
  • 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: 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: __class_getitem__ is now an automatic class method.
  • bpo-32399: Add AIX uuid library support for RFC4122 using uuid_create() in libc.a
  • 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). Original patch by Michael Felt.
  • bpo-32379: Make MRO computation faster when a class inherits from a single base.
  • bpo-32259: The error message of a TypeError raised when unpack non-iterable is now more specific.
  • bpo-27169: The __debug__ constant is now optimized out at compile time. This fixes also bpo-22091.
  • 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: 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: Fix an unnecessary ifdef in the include of VersionHelpers.h in socketmodule on Windows.
  • bpo-30579: Implement TracebackType.__new__ to allow Python-level creation of traceback objects, and make TracebackType.tb_next mutable.
  • 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: Improve the error message logic for object.__new__ and object.__init__. Patch by Sanyam Khurana.
  • 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: -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: Add a new UTF-8 mode: implementation of the PEP 540.
  • bpo-32226: PEP 560: Add support for __mro_entries__ and __class_getitem__. Implemented by Ivan Levkivskyi.
  • bpo-32225: PEP 562: Add support for module __getattr__ and __dir__. Implemented by Ivan Levkivskyi.
  • bpo-31901: The atexit module now has its callback stored per interpreter.
  • bpo-31650: Implement PEP 552 (Deterministic pycs). Python now supports invalidating bytecode cache files bashed on a source content hash rather than source last-modified time.
  • bpo-29469: Move constant folding from bytecode layer to AST layer. Original patch by Eugene Toder.

ライブラリ

  • bpo-32506: Now that dict is defined as keeping insertion order, drop OrderedDict and just use plain dict.

  • bpo-32279: Add params to dataclasses.make_dataclasses(): init, repr, eq, order, hash, and frozen. Pass them through to dataclass().

  • bpo-32278: Make type information optional on dataclasses.make_dataclass(). If omitted, the string 'typing.Any' is used.

  • bpo-32499: Add dataclasses.is_dataclass(obj), which returns True if obj is a dataclass or an instance of one.

  • bpo-32468: Improve frame repr() to mention filename, code name and current line number.

  • bpo-23749: asyncio: Implement loop.start_tls()

  • bpo-32441: Return the new file descriptor (i.e., the second argument) from os.dup2. Previously, None was always returned.

  • 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: 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: asyncio: Add Task.get_loop() and Future.get_loop()

  • bpo-26133: Don't unsubscribe signals in asyncio UNIX event loop on interpreter shutdown.

  • 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: 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: asyncio.transport.resume_reading() and pause_reading() are now idempotent. New transport.is_reading() method is added.

  • bpo-32355: Optimize asyncio.gather(); now up to 15% faster.

  • bpo-32351: Use fastpath in asyncio.sleep if delay<0 (2x boost)

  • bpo-32348: Optimize asyncio.Future schedule/add/remove callback. The optimization shows 3-6% performance improvements of async/await code.

  • 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: 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: Implement asyncio.create_task(coro) shortcut

  • 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: urllib.parse.urlsplit() does not convert zone-id (scope) to lower case for scoped IPv6 addresses in hostnames now.

  • bpo-32302: Fix bdist_wininst of distutils for CRT v142: it binary compatible with CRT v140.

  • bpo-29711: Fix stop_serving in asyncio proactor loop kill all listening servers

  • bpo-32308: re.sub() now replaces empty matches adjacent to a previous non-empty match.

  • bpo-29970: Abort asyncio SSLProtocol connection if handshake not complete within 10s

  • bpo-32314: Implement asyncio.run().

  • bpo-17852: Revert incorrect fix based on misunderstanding of _Py_PyAtExit() semantics.

  • bpo-32296: Implement asyncio._get_running_loop() and get_event_loop() in C. This makes them 4x faster.

  • 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: 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: Raise NotImplementedError instead of SystemError on platforms where chmod(..., follow_symlinks=False) is not supported. Patch by Anthony Sottile.

  • 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: 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: Move asyncio.test_utils to test.test_asyncio.

  • bpo-32272: Remove asyncio.async() function.

  • bpo-32269: Add asyncio.get_running_loop() function.

  • 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: Deprecate yield from lock, await lock, with (yield from lock) and with await lock for asyncio synchronization primitives.

  • bpo-22589: Changed MIME type of .bmp from 'image/x-ms-bmp' to 'image/bmp'

  • bpo-32193: Convert asyncio to use async/await syntax. Old styled yield from is still supported too.

  • bpo-32206: Add support to run modules with pdb

  • bpo-32227: functools.singledispatch now supports registering implementations using type annotations.

  • 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: The getnode() ip getter now uses 'ip link' instead of 'ip link list'.

  • bpo-32143: os.statvfs() includes the f_fsid field from statvfs(2)

  • bpo-26439: Fix ctypes.util.find_library() for AIX by implementing ctypes._aix.find_library() Patch by: Michael Felt

  • 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: Ensure TCP_NODELAY is set on Linux. Tests by Victor Stinner.

  • bpo-31778: ast.literal_eval() is now more strict. Addition and subtraction of arbitrary numbers no longer allowed.

  • bpo-31802: Importing native path module (posixpath, ntpath) now works even if the os module still is not imported.

  • bpo-30241: Add contextlib.AbstractAsyncContextManager. Patch by Jelle Zijlstra.

  • 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: TextIOWrapper.reconfigure() supports changing encoding, errors, and newline.

ドキュメント

  • bpo-32418: Add get_loop() method to Server and AbstractServer classes.

テスト

  • bpo-32252: Fix faulthandler_suppress_crash_report() used to prevent core dump files when testing crashes. getrlimit() returns zero on success.
  • 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: Implement support for subprocess.Popen(close_fds=True) on Windows. Patch by Segev Finer.

Tools/Demos

  • 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: Py_Initialize() doesn't reset the memory allocators to default if the PYTHONMALLOC environment variable is not set.
  • 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: Moved the pygetopt.h header into internal/, since it has no public APIs.
  • 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: 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: 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: The repr of deeply nested dict now raises a RecursionError instead of crashing due to a stack overflow.
  • 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: Add a new "developer mode": new "-X dev" command line option to enable debug checks at runtime.
  • 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: 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: 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: 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: Fix the interactive interpreter looping endlessly when no memory.
  • 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: BytesWarning no longer emitted when the fromlist argument of __import__() or the __all__ attribute of the module contain bytes instances.
  • bpo-31845: Environment variables are once more read correctly at interpreter startup.
  • 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: Fixed OverflowError in the 'unicode-escape' codec and in codecs.escape_decode() when decode an escaped non-ascii byte.
  • 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: 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: 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: Prevent crashes when calling methods of an uninitialized zipimport.zipimporter object. Patch by Oren Milman.
  • bpo-30399: Standard repr() of BaseException with a single argument no longer contains redundant trailing comma.
  • bpo-31626: Fixed a bug in debug memory allocator. There was a write to freed memory after shrinking a memory block.
  • bpo-30817: PyErr_PrintEx() clears now the ignored exception that may be raised by _PySys_SetObjectId(), for example when no memory.

ライブラリ

  • 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: PEP 557, Data Classes. Provides a decorator which adds boilerplate methods to classes which use type annotations so specify fields.

  • bpo-27240: The header folding algorithm for the new email policies has been rewritten, which also fixes bpo-30788, bpo-31831, and bpo-32182. In particular, RFC2231 folding is now done correctly.

  • 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-321010: Add sys.flags.dev_mode flag

  • 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: 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: 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: 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: Make msilib.SummaryInformation.GetProperty() return None when the value of property is VT_EMPTY. Initial patch by Mark Mc Mahon.

  • 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: 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: Fix wrong usage of collections.namedtuple() in the RobotFileParser.parse() method.

    Initial patch by Robin Wellner.

  • 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: 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: Added the -k command-line option to python -m unittest to run only tests that match the given pattern(s).

  • 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: 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: 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: 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: warnings: When Python is build is debug mode (Py_DEBUG), DeprecationWarning, PendingDeprecationWarning and ImportWarning warnings are now displayed by default.

  • 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: Added support of splitting on a pattern that could match an empty string.

  • 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: Drop legacy SSL transport from asyncio, ssl.MemoryBIO is always used anyway.

  • bpo-32066: asyncio: Support pathlib.Path in create_unix_connection; sock arg should be optional

  • bpo-32046: Updates 2to3 to convert from operator.isCallable(obj) to callable(obj). Patch by Dong-hee Na.

  • bpo-32018: inspect.signature should follow PEP 8, if the parameter has an annotation and a default value. Patch by Dong-hee Na.

  • bpo-32025: Add time.thread_time() and time.thread_time_ns()

  • 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: Make asyncio.IncompleteReadError and LimitOverrunError pickleable.

  • 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: Restored support of loading marshal files with the TYPE_INT64 code. These files can be produced in Python 2.7.

  • 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: Fix race condition when flushing a file is slow, which can cause a segfault if closing the file from another thread.

  • 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: cProfile command line now accepts -m module_name as an alternative to script path. Patch by Sanyam Khurana.

  • bpo-31970: Reduce performance overhead of asyncio debug mode.

  • bpo-31843: database argument of sqlite3.connect() now accepts a path-like object, instead of just a string.

  • bpo-31945: Add Configurable blocksize to HTTPConnection and HTTPSConnection for improved upload throughput. Patch by Nir Soffer.

  • bpo-31943: Add a cancelled() method to asyncio.Handle. Patch by Marat Sharafutdinov.

  • 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: Fix potential missed signal in signal.signal().

  • bpo-31933: Fix Blake2 params leaf_size and node_offset on big endian platforms. Patch by Jack O'Connor.

  • bpo-21423: Add an initializer argument to {Process,Thread}PoolExecutor

  • 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: 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: Add 3 new clock identifiers: time.CLOCK_BOOTTIME, time.CLOCK_PROF and time.CLOCK_UPTIME.

  • bpo-31897: plistlib now catches more errors when read binary plists and raises InvalidFileException instead of unexpected exceptions.

  • bpo-25720: Fix the method for checking pad state of curses WINDOW. Patch by Masayuki Yamamoto.

  • bpo-31893: Fixed the layout of the kqueue_event structure on OpenBSD and NetBSD. Fixed the comparison of the kqueue_event objects.

  • bpo-31891: Fixed building the curses module on NetBSD.

  • bpo-31884: added required constants to subprocess module for setting priority on windows

  • bpo-28281: Remove year (1-9999) limits on the Calendar.weekday() function.

    Patch by Mark Gollahon.

  • bpo-31702: crypt.mksalt() now allows to specify the number of rounds for SHA-256 and SHA-512 hashing.

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

  • bpo-31854: Add mmap.ACCESS_DEFAULT constant.

  • bpo-31834: Use optimized code for BLAKE2 only with SSSE3+. The pure SSE2 implementation is slower than the pure C reference implementation.

  • 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: The shutil.rmtree() function has been sped up to 20--40%. This was done using the os.scandir() function.

  • 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: Don't release the GIL if we can acquire a multiprocessing semaphore immediately.

  • bpo-28326: Fix multiprocessing.Process when stdout and/or stderr is closed or None.

  • 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: 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: 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: Add AbstractEventLoop.sock_recv_into().

  • bpo-31457: If nested log adapters are used, the inner process() methods are no longer omitted.

  • bpo-31457: The manager property on LoggerAdapter objects is now properly settable.

  • 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: time.clock() and time.get_clock_info('clock') now emit a DeprecationWarning warning.

  • 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: 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: Add new function to seal a mock and prevent the automatically creation of child mocks. Patch by Mario Corchero.

  • bpo-31784: Implement the  PEP 564, 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: 2to3 now generates a code that uses abstract collection classes from collections.abc rather than collections.

  • bpo-31770: Prevent a crash when calling the __init__() method of a sqlite3.Cursor object more than once. Patch by Oren Milman.

  • bpo-31764: Prevent a crash in sqlite3.Cursor.close() in case the Cursor object is uninitialized. Patch by Oren Milman.

  • bpo-31752: Fix possible crash in timedelta constructor called with custom integers.

  • bpo-31620: an empty asyncio.Queue now doesn't leak memory when queue.get pollers timeout

  • bpo-31690: Allow the flags re.ASCII, re.LOCALE, and re.UNICODE to be used as group flags for regular expressions.

  • 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: Added support for the Blowfish hashing in the crypt module.

  • 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: Added a workaround for getkey() in curses for ncurses 5.7 and earlier.

  • bpo-31307: Allow use of bytes objects for arguments to configparser.ConfigParser.read(). Patch by Vincent Michel.

  • 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: multiprocessing's semaphore tracker should be launched again if crashed.

  • bpo-31308: Make multiprocessing's forkserver process immune to Ctrl-C and other user interruptions. If it crashes, restart it when necessary.

  • bpo-31245: Added support for AF_UNIX socket in asyncio create_datagram_endpoint.

  • bpo-30553: Add HTTP/2 status code 421 (Misdirected Request) to http.HTTPStatus. Patch by Vitor Pereira.

ドキュメント

  • bpo-32105: Added asyncio.BaseEventLoop.connect_accepted_socket versionadded marker.

テスト

  • bpo-31380: Skip test_httpservers test_undecodable_file on macOS: fails on APFS.
  • 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: Skip on Android test_faulthandler tests that raise SIGSEGV and remove the test.support.requires_android_level decorator.
  • 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: 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: Skip test_get_event_loop_new_process in test.test_asyncio.test_events when sem_open() is not functional.
  • 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-28538: Revert the previous changes, the if_nameindex structure is defined by Unified Headers.
  • bpo-28762: Revert the last commit, the F_LOCK macro is defined by Android Unified Headers.
  • bpo-29040: Support building Android with Unified Headers. The first NDK release to support Unified Headers is android-ndk-r14.
  • bpo-32059: detect_modules() in setup.py now also searches the sysroot paths when cross-compiling.
  • bpo-31957: Fixes Windows SDK version detection when building for Windows.
  • bpo-31609: Fixes quotes in PCbuild/clean.bat
  • bpo-31934: Abort the build when building out of a not clean source tree.
  • 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: Update Windows builds to use SQLite 3.21.0.
  • bpo-28791: Update OS X installer to use SQLite 3.21.0.
  • bpo-28643: Record profile-opt build progress with stamp files.
  • bpo-31866: Finish removing support for AtheOS.

Windows

  • bpo-1102: Return None when View.Fetch() returns ERROR_NO_MORE_ITEMS instead of raising MSIError.

    Initial patch by Anthony Tuininga.

  • bpo-31944: Fixes Modify button in Apps and Features dialog.

  • bpo-20486: Implement the Database.Close() method to help closing MSI database objects.

  • bpo-31857: Make the behavior of USE_STACKCHECK deterministic in a multi-threaded environment.

macOS

  • bpo-31392: Update macOS installer to use OpenSSL 1.0.2m

IDLE

  • 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: Delete unused file idlelib/tabbedpages.py. Use of TabbedPageSet in configdialog was replaced by ttk.Notebook.

  • bpo-32100: IDLE: Fix old and new bugs in pathbrowser; improve tests. Patch mostly by Cheryl Sabella.

  • 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: The font sample in the IDLE configuration dialog is now editable. Changes persist while IDLE remains open

  • 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: 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: 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: 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: 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: 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: The Py_UseClassExceptionsFlag flag has been removed. It was deprecated and wasn't used anymore since Python 2.0.
  • 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: Add Py_RETURN_RICHCOMPARE macro to reduce boilerplate code in rich comparison functions.
  • 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.

Python 3.7.0 alpha 2

Release date: 2017-10-16

Core and Builtins

  • 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: Restored blocking "from package import module" by setting sys.modules["package.module"] to None.
  • bpo-31708: Allow use of asynchronous generator expressions in synchronous functions.
  • bpo-31709: Drop support of asynchronous __aiter__.
  • bpo-30404: The -u option now makes the stdout and stderr streams unbuffered rather than line-buffered.
  • bpo-31619: Fixed a ValueError when convert a string with large number of underscores to integer with binary base.
  • bpo-31602: Fix an assertion failure in zipimporter.get_source() in case of a bad zlib.decompress(). Patch by Oren Milman.
  • bpo-31592: Fixed an assertion failure in Python parser in case of a bad unicodedata.normalize(). Patch by Oren Milman.
  • 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: Importlib was instrumented with two dtrace probes to profile import timing.
  • bpo-31566: Fix an assertion failure in _warnings.warn() in case of a bad __name__ global. Patch by Oren Milman.
  • bpo-31506: Improved the error message logic for object.__new__ and object.__init__.
  • bpo-31505: Fix an assertion failure in json, in case _json.make_encoder() received a bad encoder() argument. Patch by Oren Milman.
  • 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: Fix an assertion failure in _random.Random.seed() in case the argument has a bad __abs__() method. Patch by Oren Milman.
  • 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: 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: Optimized calling wrapper and classmethod descriptors.
  • bpo-31353: PEP 553 - 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: Maintain a list of open buffered files, flush them before exiting the interpreter. Based on a patch from Armin Rigo.
  • bpo-31315: Fix an assertion failure in imp.create_dynamic(), when spec.name is not a string. Patch by Oren Milman.
  • bpo-31311: Fix a crash in the __setstate__() method of ctypes._CData, in case of a bad __dict__. Patch by Oren Milman.
  • 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: 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: Make async and await proper keywords, as specified in PEP 492.

ライブラリ

  • bpo-30058: Fixed buffer overflow in select.kqueue.control().

  • 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: On Windows, faulthandler.enable() now ignores MSC and COM exceptions.

  • bpo-31728: Prevent crashes in _elementtree due to unsafe cleanup of Element.text and Element.tail. Patch by Oren Milman.

  • bpo-31671: Now re.compile() converts passed RegexFlag to normal int object before compiling. bm_regex_compile benchmark shows 14% performance improvements.

  • 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: Fixed memory leaks in Tkinter's methods splitlist() and split() when pass a string larger than 2 GiB.

  • bpo-31673: Fixed typo in the name of Tkinter's method adderrorinfo().

  • 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: Fix the string representation of a netrc object.

  • bpo-31638: Add optional argument compressed to zipapp.create_archive, and add option --compress to the command line interface of zipapp.

  • bpo-25351: Avoid venv activate failures with undefined variables

  • bpo-20519: Avoid ctypes use (if possible) and improve import time for uuid.

  • bpo-28293: The regular expression cache is no longer completely dumped when it is full.

  • bpo-31596: Added pthread_getcpuclockid() to the time module

  • bpo-27494: Make 2to3 accept a trailing comma in generator expressions. For example, set(x for x in [],) is now allowed.

  • bpo-30347: Stop crashes when concurrently iterate over itertools.groupby() iterators.

  • bpo-30346: An iterator produced by itertools.groupby() iterator now becomes exhausted after advancing the groupby iterator.

  • bpo-31556: Cancel asyncio.wait_for future faster if timeout <= 0

  • 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: threading.current_thread() should not return a dummy thread at shutdown.

  • 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: 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: 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 insteads of hardcoded name of the base class.

  • bpo-31351: python -m ensurepip now exits with non-zero exit code if pip bootstrapping has failed.

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

ドキュメント

  • bpo-31537: Fix incorrect usage of get_history_length in readline documentation example code. Patch by Brad Smith.
  • bpo-30085: The operator functions without double underscores are preferred for clarity. The one with underscores are only kept for back-compatibility.

ビルド

  • bpo-31696: Improve compiler version information in sys.version when Python is built with Clang.
  • bpo-31625: Stop using ranlib on static libraries. Instead, we assume ar supports the 's' flag.
  • bpo-31624: Remove support for BSD/OS.
  • bpo-22140: Prevent double substitution of prefix in python-config.sh.
  • bpo-31569: Correct PCBuild/ case to PCbuild/ in build scripts and documentation.
  • bpo-31536: Avoid wholesale rebuild after make regen-all if nothing changed.

IDLE

  • 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: IDLE - Make _htest, _utest parameters keyword only.

  • bpo-31559: Remove test order dependence in idle_test.test_browser.

  • 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: Default fonts now are scaled on HiDPI displays.

  • 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: 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: Fix memory corruption due to allocator mix in getpath.c between Py_GetPath() and Py_SetPath()
  • bpo-25658: Implement PEP 539 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

セキュリティ

  • bpo-29781: SSLObject.version() now correctly returns None when handshake over BIO has not been performed yet.
  • bpo-29505: Add fuzz tests for float(str), int(str), unicode(str); for oss-fuzz.
  • bpo-30947: Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to get security fixes.
  • bpo-30730: Prevent environment variables injection in subprocess on Windows. Prevent passing other environment variables and command arguments.
  • bpo-30694: Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple security vulnerabilities including: CVE-2017-9233 (External entity infinite loop DoS), CVE-2016-9063 (Integer overflow, re-fix), CVE-2016-0718 (Fix regression bugs from 2.2.0's fix to CVE-2016-0718) and CVE-2012-0876 (Counter hash flooding with SipHash). Note: the 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: 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: Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 and CVE-2016-4472. See https://sourceforge.net/p/expat/bugs/537/ for more information.

Core and Builtins

  • 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: 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: Fix an assertion failure in PyErr_WriteUnraisable() in case of an exception with a bad __module__ attribute. Patch by Oren Milman.

  • bpo-31416: Fix assertion failures in case of a bad warnings.filters or warnings.defaultaction. Patch by Oren Milman.

  • 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: 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: Raise a TypeError instead of SystemError in case warnings.onceregistry is not a dictionary. Patch by Oren Milman.

  • 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: Fix several possible instances of undefined behavior due to floating-point demotions.

  • 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: Consolidate CPython's global runtime state under a single struct. This improves discoverability of the runtime state.

  • bpo-31347: Fix possible undefined behavior in _PyObject_FastCall_Prepend.

  • 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: 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: 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: Fix a crash in some methods of io.TextIOWrapper, when the decoder's state is invalid. Patch by Oren Milman.

  • bpo-30721: print now shows correct usage hint for using Python 2 redirection syntax. Patch by Sanyam Khurana.

  • bpo-31070: Fix a race condition in importlib _get_module_lock().

  • bpo-30747: Add a non-dummy implementation of _Py_atomic_store and _Py_atomic_load on MSVC.

  • bpo-31095: Fix potential crash during GC caused by tp_dealloc which doesn't call PyObject_GC_UnTrack().

  • bpo-31071: Avoid masking original TypeError in call with * unpacking when other arguments are passed.

  • bpo-30978: str.format_map() now passes key lookup exceptions through. Previously any exception was replaced with a KeyError exception.

  • bpo-30808: Use _Py_atomic API for concurrency-sensitive signal state.

  • 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: 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: Avoid blocking in pthread_mutex_lock() when PyThread_acquire_lock() is asked not to block.

  • bpo-31161: Make sure the 'Missing parentheses' syntax error message is only applied to SyntaxError, not to subclasses. Patch by Martijn Pieters.

  • bpo-30814: Fixed a race condition when import a submodule from a package.

  • bpo-30736: The internal unicodedata database has been upgraded to Unicode 10.0.

  • bpo-30604: Move co_extra_freefuncs from per-thread to per-interpreter to avoid crashes.

  • bpo-30597: print now shows expected input in custom error message when used as a Python 2 statement. Patch by Sanyam Khurana.

  • bpo-30682: Removed a too-strict assertion that failed for certain f-strings, such as eval("f'\n'") and eval("f'\r'").

  • 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: Implement PEP 538 (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: Allows setting cell values for __closure__. Patch by Lisa Roach.

  • bpo-30537: itertools.islice now accepts integer-like objects (having an __index__ method) as start, stop, and slice arguments

  • 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: Fixed parsing backslashes in f-strings.

  • 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: Fixed type.__setattr__() and type.__delattr__() for non-interned attribute names. Based on patch by Eryk Sun.

  • 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: object.__format__(x, '') is now equivalent to str(x) rather than format(str(self), '').

  • bpo-30024: Circular imports involving absolute imports with binding a submodule to a name are now supported.

  • 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 Dong-hee Na.

  • bpo-29839: len() now raises ValueError rather than OverflowError if __len__() returned a large negative integer.

  • bpo-11913: README.rst is now included in the list of distutils standard READMEs and therefore included in source distributions.

  • 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: Fix memory usage regression of set and frozenset object.

  • bpo-29935: Fixed error messages in the index() method of tuple, list and deque when pass indices of wrong type.

  • 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: Fixed the slowing down to 25 times in the searching of some unlucky Unicode characters.

  • bpo-29102: Add a unique ID to PyInterpreterState. This makes it easier to identify each subinterpreter.

  • 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: Show correct error messages when any of the pthread_* calls in thread_pthread.h fails.

  • bpo-29849: Fix a memory leak when an ImportError is raised during from import.

  • bpo-28856: Fix an oversight that %b format for bytes should support objects follow the buffer protocol.

  • bpo-29723: The sys.path[0] initialization change for 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: Escaped percent "%%" in the format string for classic string formatting no longer allows any characters between two percents.

  • bpo-29714: Fix a regression that bytes format may fail when containing zero bytes inside.

  • 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: Set correct __cause__ for errors about invalid awaitables returned from __aiter__ and __anext__.

  • bpo-28876: bool(range) works even if len(range) raises OverflowError.

  • bpo-29683: Fixes to memory allocation in _PyCode_SetExtra. Patch by Brian Coleman.

  • 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: Support __rmod__ for subclasses of str being called before str.__mod__. Patch by Martijn Pieters.

  • bpo-29607: Fix stack_effect computation for CALL_FUNCTION_EX. Patch by Matthieu Dartiailh.

  • 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: Fixed possibly dereferencing undefined pointers when creating weakref objects.

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

  • bpo-29438: Fixed use-after-free problem in key sharing dict.

  • bpo-29546: Set the 'path' and 'name' attribute on ImportError for from ... import ....

  • bpo-29546: Improve from-import error message with location

  • 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: Prevent RunMainFromImporter overwriting sys.path[0].

  • bpo-29337: Fixed possible BytesWarning when compare the code objects. Warnings could be emitted at compile time.

  • bpo-29327: Fixed a crash when pass the iterable keyword argument to sorted().

  • bpo-29034: Fix memory leak and use-after-free in os module (path_converter).

  • bpo-29159: Fix regression in bytes(x) when x.__index__() raises Exception.

  • bpo-29049: Call _PyObject_GC_TRACK() lazily when calling Python function. Calling function is up to 5% faster.

  • bpo-28927: bytes.fromhex() and bytearray.fromhex() now ignore all ASCII whitespace, not only spaces. Patch by Robert Xiao.

  • bpo-28932: Do not include <sys/random.h> if it does not exist.

  • bpo-25677: Correct the positioning of the syntax error caret for indented blocks. Based on patch by Michael Layzell.

  • bpo-29000: Fixed bytes formatting of octals with zero padding in alternate form.

  • bpo-18896: Python function can now have more than 255 parameters. collections.namedtuple() now supports tuples with more than 255 elements.

  • bpo-28596: The preferred encoding is UTF-8 on Android. Patch written by Chi Hsuan Yen.

  • bpo-22257: Clean up interpreter startup (see PEP 432).

  • 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: functools.lru_cache() was susceptible to an obscure reentrancy bug triggerable by a monkey-patched len() function.

  • 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: f-string expressions are no longer accepted as docstrings and by ast.literal_eval() even if they do not include expressions.

  • bpo-28512: Fixed setting the offset attribute of SyntaxError by PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().

  • bpo-28918: Fix the cross compilation of xxlimited when Python has been built with Py_DEBUG defined.

  • 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: 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: 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: More than 255 arguments can now be passed to a function.

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

  • 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: Optimize _PyDict_NewPresized() to create correct size dict. Improve speed of dict literal with constant keys up to 30%.

  • bpo-28532: Show sys.version when -V option is supplied twice.

  • 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: Fix the set_inheritable() file descriptor method on platforms that do not have the ioctl FIOCLEX and FIONCLEX commands.

  • bpo-26920: Fix not getting the locale's charset upon initializing the interpreter, on platforms that do not have langinfo.

  • bpo-28648: Fixed crash in Py_DecodeLocale() in debug build on Mac OS X when decode astral characters. Patch by Xiang Zhang.

  • bpo-28665: Improve speed of the STORE_DEREF opcode by 40%.

  • bpo-19398: Extra slash no longer added to sys.path components in case of empty compile-time PYTHONPATH components.

  • bpo-28621: Sped up converting int to float by reusing faster bits counting implementation. Patch by Adrian Wielgosik.

  • bpo-28580: Optimize iterating split table values. Patch by Xiang Zhang.

  • bpo-28583: PyDict_SetDefault didn't combine split table when needed. Patch by Xiang Zhang.

  • 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: dict.update() no longer allocate unnecessary large memory.

  • bpo-28426: Fixed potential crash in PyUnicode_AsDecodedObject() in debug build.

  • bpo-28517: Fixed of-by-one error in the peephole optimizer that caused keeping unreachable code.

  • bpo-28214: Improved exception reporting for problematic __set_name__ attributes.

  • bpo-23782: Fixed possible memory leak in _PyTraceback_Add() and exception loss in PyTraceBack_Here().

  • bpo-28183: Optimize and cleanup dict iteration.

  • bpo-26081: Added C implementation of asyncio.Future. Original patch by Yury Selivanov.

  • bpo-28379: Added sanity checks and tests for PyUnicode_CopyCharacters(). Patch by Xiang Zhang.

  • bpo-28376: The type of long range iterator is now registered as Iterator. Patch by Oren Milman.

  • 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: Resolving special methods of uninitialized type now causes implicit initialization of the type instead of a fail.

  • bpo-18287: PyType_Ready() now checks that tp_name is not NULL. Original patch by Niklas Koep.

  • bpo-24098: Fixed possible crash when AST is changed in process of compiling it.

  • bpo-28201: Dict reduces possibility of 2nd conflict in hash table when hashes have same lower bits.

  • bpo-28350: String constants with null character no longer interned.

  • bpo-26617: Fix crash when GC runs during weakref callbacks.

  • bpo-27942: String constants now interned recursively in tuples and frozensets.

  • bpo-28289: ImportError.__init__ now resets not specified attributes.

  • bpo-21578: Fixed misleading error message when ImportError called with invalid keyword args.

  • bpo-28203: Fix incorrect type in complex(1.0, {2:3}) error message. Patch by Soumya Sharma.

  • 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: Now __set_name__ is looked up on the class instead of the instance.

  • bpo-27955: Fallback on reading /dev/urandom device when the getrandom() syscall fails with EPERM, for example when blocked by SECCOMP.

  • bpo-28192: Don't import readline in isolated mode.

  • bpo-27441: Remove some redundant assignments to ob_size in longobject.c. Thanks Oren Milman.

  • 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: Fix a regression in zipimport's compile_source(). zipimport should use the same optimization level as the interpreter.

  • bpo-28126: Replace Py_MEMCPY with memcpy(). Visual Studio can properly optimize memcpy().

  • 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: Raise DeprecationWarning when async and await keywords are used as variable/attribute/class/function name.

  • bpo-26182: Fix a refleak in code that raises DeprecationWarning.

  • bpo-28721: Fix asynchronous generators aclose() and athrow() to handle StopAsyncIteration propagation properly.

  • bpo-26110: Speed-up method calls: add LOAD_METHOD and CALL_METHOD opcodes.

ライブラリ

  • bpo-31499: xml.etree: Fix a crash when a parser is part of a reference cycle.

  • bpo-31482: random.seed() now works with bytes in version=1

  • 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: Speed improvements to the typing module. Original PRs by Ivan Levkivskyi and Mitar.

  • bpo-31544: The C accelerator module of ElementTree ignored exceptions raised when looking up TreeBuilder target methods in XMLParser().

  • bpo-31234: socket.create_connection() now fixes manually a reference cycle: clear the variable storing the last exception on success.

  • bpo-31457: LoggerAdapter objects can now be nested.

  • bpo-31431: SSLContext.check_hostname now automatically sets SSLContext.verify_mode to ssl.CERT_REQUIRED instead of failing with a ValueError.

  • bpo-31233: socketserver.ThreadingMixIn now keeps a list of non-daemonic threads to wait until all these threads complete in server_close().

  • 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: Improves SSL error handling to avoid losing error numbers.

  • bpo-27629: Make return types of SSLContext.wrap_bio() and SSLContext.wrap_socket() customizable.

  • bpo-28958: ssl.SSLContext() now uses OpenSSL error information when a context cannot be instantiated.

  • 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: 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: 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: Fix string concatenation bug in rare error path in the subprocess module

  • bpo-31350: Micro-optimize asyncio._get_running_loop() to become up to 10% faster.

  • 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: Add TLS 1.3 cipher suites and OP_NO_TLSv1_3.

  • 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: 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: The map() and as_completed() iterators in concurrent.futures now avoid keeping a reference to yielded objects.

  • bpo-31281: Fix fileinput.FileInput(files, inplace=True) when files contain pathlib.Path objects.

  • bpo-10746: Fix ctypes producing wrong PEP 3118 type codes for integer types.

  • bpo-27584: AF_VSOCK has been added to the socket interface which allows communication between virtual machines and their host.

  • 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: Update some methods in the _pyio module to also accept integer types. Patch by Oren Milman.

  • bpo-31249: concurrent.futures: WorkItem.run() used by ThreadPoolExecutor now breaks a reference cycle between an exception object and the WorkItem object.

  • bpo-31247: xmlrpc.server now explicitly breaks reference cycles when using sys.exc_info() in code handling exceptions.

  • 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: 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: Many asserts in multiprocessing are now more informative, and some error types have been changed to more specific ones.

  • bpo-31109: Convert zipimport to use Argument Clinic.

  • 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: Non-daemonic threads created by a multiprocessing.Process are now joined on child exit.

  • bpo-31183: dis now works with asynchronous generator and coroutine objects. Patch by George Collins based on diagnosis by Luciano Ramalho.

  • 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: Fixed miscellaneous errors in asyncio speedup module.

  • bpo-31151: socketserver.ForkingMixIn.server_close() now waits until all child processes completed to prevent leaking zombie processes.

  • bpo-31072: Add an include_file parameter to zipapp.create_archive()

  • 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: 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: Fix copyreg._slotnames() mangled attribute calculation for classes whose name begins with an underscore. Patch by Shane Harvey.

  • bpo-31080: Allow logging.config.fileConfig to accept kwargs and/or args.

  • 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: Fixed a crash when using asyncio and threads.

  • bpo-30987: Added support for CAN ISO-TP protocol in the socket module.

  • bpo-30522: Added a setStream method to logging.StreamHandler to allow the stream to be set after creation.

  • bpo-30502: Fix handling of long oids in ssl. Based on patch by Christian Heimes.

  • bpo-5288: Support tzinfo objects with sub-minute offsets.

  • 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: 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: Fix unittest.mock's autospec to not fail on method-bound builtin functions. Patch by Aaron Gallagher.

  • bpo-30961: Fix decrementing a borrowed reference in tracemalloc.

  • bpo-19896: Fix multiprocessing.sharedctypes to recognize typecodes 'q' and 'Q'.

  • 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: Change ttk.OptionMenu radiobuttons to be unique across instances of OptionMenu.

  • 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: Fix segfault in readline when using readline's history-size option. Patch by Nir Soffer.

  • bpo-30794: Added multiprocessing.Process.kill method to terminate using the SIGKILL signal on Unix.

  • bpo-30319: socket.close() now ignores ECONNRESET error.

  • bpo-30828: Fix out of bounds write in asyncio.CFuture.remove_done_callback().

  • bpo-30302: Use keywords in the repr of datetime.timedelta.

  • 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: Fix bug when modifying os.environ while iterating over it

  • 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: 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: Fix email header value parser dropping folding white space in certain cases.

  • bpo-30596: Add a close() method to multiprocessing.Process.

  • 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: Update zlib to 1.2.11.

  • bpo-30119: ftplib.FTP.putline() now throws ValueError on commands that contains CR or LF. Patch by Dong-hee Na.

  • bpo-30879: os.listdir() and os.scandir() now emit bytes names when called with bytes-like argument.

  • bpo-30746: Prohibited the '=' character in environment variable names in os.putenv() and os.spawn*().

  • bpo-30664: The description of a unittest subtest now preserves the order of keyword arguments of TestCase.subTest().

  • bpo-21071: struct.Struct.format type is now str instead of bytes.

  • 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: Fixed the lgettext() family of functions in the gettext module. They now always return bytes.

  • bpo-30616: Functional API of enum allows to create empty enums. Patched by Dong-hee Na

  • bpo-30038: Fix race condition between signal delivery and wakeup file descriptor. Patch by Nathaniel Smith.

  • bpo-23894: lib2to3 now recognizes rb'...' and f'...' strings.

  • bpo-24744: pkgutil.walk_packages function now raises ValueError if path is a string. Patch by Sanyam Khurana.

  • bpo-24484: Avoid race condition in multiprocessing cleanup.

  • 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: The traceback no longer displayed for SystemExit raised in a callback registered by atexit.

  • bpo-30508: Don't log exceptions if Task/Future "cancel()" method was called.

  • 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: The dis.dis() function now is able to disassemble nested code objects.

  • 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: 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: Updates to typing module: Add generic AsyncContextManager, add support for ContextManager on all versions. Original PRs by Jelle Zijlstra and Ivan Levkivskyi

  • bpo-30605: re.compile() no longer raises a BytesWarning when compiling a bytes instance with misplaced inline modifier. Patch by Roy Williams.

  • bpo-29870: Fix ssl sockets leaks when connection is aborted in asyncio/ssl implementation. Patch by Michaël Sghaïer.

  • bpo-29743: Closing transport during handshake process leaks open socket. Patch by Nikolay Kim

  • bpo-27585: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu Sornay.

  • bpo-30014: modify() method of poll(), epoll() and devpoll() based classes of selectors module is around 10% faster. Patch by Giampaolo Rodola'.

  • 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: Addded empty __slots__ to abc.ABC. This allows subclassers to deny __dict__ and __weakref__ creation. Patch by Aaron Hall.

  • bpo-30520: Loggers are now pickleable.

  • bpo-30557: faulthandler now correctly filters and displays exception codes on Windows

  • bpo-30526: Add TextIOWrapper.reconfigure() and a TextIOWrapper.write_through attribute.

  • bpo-30245: Fix possible overflow when organize struct.pack_into error message. Patch by Yuan Liu.

  • bpo-30378: Fix the problem that logging.handlers.SysLogHandler cannot handle IPv6 addresses.

  • bpo-16500: Allow registering at-fork handlers.

  • bpo-30470: Deprecate invalid ctypes call protection on Windows. Patch by Mariatta Wijaya.

  • bpo-30414: multiprocessing.Queue._feed background running thread do not break from main loop on exception.

  • bpo-30003: Fix handling escape characters in HZ codec. Based on patch by Ma Lin.

  • bpo-30149: inspect.signature() now supports callables with variable-argument parameters wrapped with partialmethod. Patch by Dong-hee Na.

  • 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: Fix AttributeError when using SimpleQueue.empty() under spawn and forkserver start methods.

  • 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: 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: 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: The macpath is now deprecated and will be removed in Python 3.8.

  • bpo-30299: Compiling regular expression in debug mode on CPython now displays the compiled bytecode in human readable form.

  • bpo-30048: Fixed Task.cancel() can be ignored when the task is running coroutine and the coroutine returned without any more await.

  • bpo-30266: contextlib.AbstractContextManager now supports anti-registration by setting __enter__ = None or __exit__ = None, following the pattern introduced in bpo-25958. Patch by Jelle Zijlstra.

  • bpo-30340: Enhanced regular expressions optimization. This increased the performance of matching some patterns up to 25 times.

  • 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: Optimized case-insensitive matching and searching of regular expressions.

  • bpo-29990: Fix range checking in GB18030 decoder. Original patch by Ma Lin.

  • 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: 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: 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: Avoid KeyboardInterrupt tracebacks in forkserver helper process when Ctrl-C is received.

  • bpo-30103: binascii.b2a_uu() and uu.encode() now support using '`' as zero instead of space.

  • 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: Fix getsockname() for unbound AF_UNIX sockets on Linux.

  • 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: 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: Add support for curses.A_ITALIC.

  • bpo-29822: inspect.isabstract() now works during __init_subclass__. Patch by Nate Soares.

  • bpo-29960: Preserve generator state when _random.Random.setstate() raises an exception. Patch by Bryan Olson.

  • bpo-30070: Fixed leaks and crashes in errors handling in the parser module.

  • bpo-22352: Column widths in the output of dis.dis() are now adjusted for large line numbers and instruction offsets.

  • 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: Fix PathLike support for shutil.unpack_archive. Patch by Jelle Zijlstra.

  • 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: _io._IOBase.readlines will check if it's closed first when hint is present.

  • bpo-29694: Fixed race condition in pathlib mkdir with flags parents=True. Patch by Armin Rigo.

  • bpo-29692: Fixed arbitrary unchaining of RuntimeError exceptions in contextlib.contextmanager. Patch by Siddharth Velankar.

  • 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. Patch by Aviv Palivoda.

  • 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: Pickling and copying ImportError now preserves name and path attributes.

  • bpo-29995: re.escape() now escapes only regex special characters.

  • bpo-29962: Add math.remainder operation, implementing remainder as specified in IEEE 754.

  • bpo-29649: Improve struct.pack_into() exception messages for problems with the buffer size and offset. Patch by Andrew Nester.

  • bpo-29654: Support If-Modified-Since HTTP header (browser cache). Patch by Pierre Quentel.

  • bpo-29931: Fixed comparison check for ipaddress.ip_interface objects. Patch by Sanjay Sundaresan.

  • bpo-29953: Fixed memory leaks in the replace() method of datetime and time objects when pass out of bound fold argument.

  • bpo-29942: Fix a crash in itertools.chain.from_iterable when encountering long runs of empty iterables.

  • bpo-10030: Sped up reading encrypted ZIP files by 2 times.

  • bpo-29204: Element.getiterator() and the html parameter of XMLParser() were deprecated only in the documentation (since Python 3.2 and 3.4 correspondintly). Now using them emits a deprecation warning.

  • bpo-27863: Fixed multiple crashes in ElementTree caused by race conditions and wrong types.

  • 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: 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: unittest.TestCase.assertRaises() now manually breaks a reference cycle to not keep objects alive longer than expected.

  • bpo-29901: The zipapp module now supports general path-like objects, not just pathlib.Path.

  • 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: Release references to tasks, their arguments and their results as soon as they are finished in multiprocessing.Pool.

  • bpo-19930: The mode argument of os.makedirs() no longer affects the file permission bits of newly-created intermediate-level directories.

  • bpo-29884: faulthandler: Restore the old sigaltstack during teardown. Patch by Christophe Zeitouny.

  • bpo-25455: Fixed crashes in repr of recursive buffered file-like objects.

  • bpo-29800: Fix crashes in partial.__repr__ if the keys of partial.keywords are not strings. Patch by Michael Seifert.

  • 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: Using non-integer value for selecting a plural form in gettext is now deprecated.

  • bpo-26121: Use C library implementation for math functions erf() and erfc().

  • bpo-29619: os.stat() and os.DirEntry.inode() now convert inode (st_ino) using unsigned integers.

  • bpo-28298: Fix a bug that prevented array 'Q', 'L' and 'I' from accepting big intables (objects that have __int__) as elements.

  • bpo-29645: Speed up importing the webbrowser module. webbrowser.register() is now thread-safe.

  • bpo-28231: The zipfile module now accepts path-like objects for external paths.

  • bpo-26915: index() and count() methods of collections.abc.Sequence now check identity before checking equality when do comparisons.

  • bpo-28682: Added support for bytes paths in os.fwalk().

  • bpo-29728: Add new socket.TCP_NOTSENT_LOWAT (Linux 3.12) constant. Patch by Nathaniel J. Smith.

  • bpo-29623: Allow use of path-like object as a single argument in ConfigParser.read(). Patch by David Ellis.

  • bpo-9303: Migrate sqlite3 module to _v2 API. Patch by Aviv Palivoda.

  • bpo-28963: Fix out of bound iteration in asyncio.Future.remove_done_callback implemented in C.

  • bpo-29704: asyncio.subprocess.SubprocessStreamProtocol no longer closes before all pipes are closed.

  • bpo-29271: Fix Task.current_task and Task.all_tasks implemented in C to accept None argument as their pure Python implementation.

  • bpo-29703: Fix asyncio to support instantiation of new event loops in child processes.

  • 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: Method register_function() of xmlrpc.server.SimpleXMLRPCDispatcher and its subclasses can now be used as a decorator.

  • bpo-29376: Fix assertion error in threading._DummyThread.is_alive().

  • bpo-28624: Add a test that checks that cwd parameter of Popen() accepts PathLike objects. Patch by Sayan Chowdhury.

  • bpo-28518: Start a transaction implicitly before a DML statement. Patch by Aviv Palivoda.

  • bpo-29742: get_extra_info() raises exception if get called on closed ssl transport. Patch by Nikolay Kim.

  • 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: Altering a kwarg dictionary passed to functools.partial() no longer affects a partial object after creation.

  • 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: 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: Improve some deprecations in importlib. Some deprecated methods now emit DeprecationWarnings and have better descriptive messages.

  • bpo-29534: Fixed different behaviour of Decimal.from_float() for _decimal and _pydecimal. Thanks Andrew Nester.

  • bpo-10379: locale.format_string now supports the 'monetary' keyword argument, and locale.format is deprecated.

  • bpo-29851: importlib.reload() now raises ModuleNotFoundError if the module lacks a spec.

  • 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: Fix datetime.fromtimestamp() regression introduced in Python 3.6.0: check minimum and maximum years.

  • bpo-29416: Prevent infinite loop in pathlib.Path.mkdir

  • bpo-29444: Fixed out-of-bounds buffer access in the group() method of the match object. Based on patch by WGH.

  • bpo-29377: Add WrapperDescriptorType, MethodWrapperType, and MethodDescriptorType built-in types to types module. Original patch by Manuel Krebber.

  • 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: 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: The help of a builtin or extension class now includes the constructor signature if __text_signature__ is provided for the class.

  • 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: Fix a regression in argparse that help messages would wrap at non-breaking spaces.

  • bpo-28735: Fixed the comparison of mock.MagickMock with mock.ANY.

  • bpo-29197: Removed deprecated function ntpath.splitunc().

  • bpo-29210: Removed support of deprecated argument "exclude" in tarfile.TarFile.add().

  • bpo-29219: Fixed infinite recursion in the repr of uninitialized ctypes.CDLL instances.

  • bpo-29192: Removed deprecated features in the http.cookies module.

  • bpo-29193: A format string argument for string.Formatter.format() is now positional-only.

  • bpo-29195: Removed support of deprecated undocumented keyword arguments in methods of regular expression objects.

  • 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 differen threads with the same uncached arguments.

  • bpo-20804: The unittest.mock.sentinel attributes now preserve their identity when they are copied or pickled.

  • 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: Fix unittest.mock._Call helper: don't ignore the name parameter anymore. Patch written by Jiajun Huang.

  • bpo-15812: inspect.getframeinfo() now correctly shows the first line of a context. Patch by Sam Breese.

  • bpo-28985: Update authorizer constants in sqlite3 module. Patch by Dingyuan Wang.

  • bpo-29079: Prevent infinite loop in pathlib.resolve() on Windows

  • bpo-13051: Fixed recursion errors in large or resized curses.textpad.Textbox. Based on patch by Tycho Andersen.

  • bpo-9770: curses.ascii predicates now work correctly with negative integers.

  • bpo-28427: old keys should not remove new values from WeakValueDictionary when collecting from another thread.

  • bpo-28923: Remove editor artifacts from Tix.py.

  • bpo-28871: Fixed a crash when deallocate deep ElementTree.

  • bpo-19542: Fix bugs in WeakValueDictionary.setdefault() and WeakValueDictionary.pop() when a GC collection happens in another thread.

  • bpo-20191: Fixed a crash in resource.prlimit() when passing a sequence that doesn't own its elements as limits.

  • bpo-16255: subprocess.Popen uses /system/bin/sh on Android as the shell, instead of /bin/sh.

  • bpo-28779: multiprocessing.set_forkserver_preload() would crash the forkserver process if a preloaded module instantiated some multiprocessing objects such as locks.

  • 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: 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: Unknown escapes consisting of '\' and an ASCII letter in re.sub() replacement templates regular expressions now are errors.

  • bpo-28835: Fix a regression introduced in warnings.catch_warnings(): call warnings.showwarning() if it was overridden inside the context manager.

  • 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: Add sys.getandroidapilevel(): return the build time API version of Android as an integer. Function only available on Android.

  • 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: Restored the __reduce__() methods of datetime objects.

  • 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: don't duplicate warning filters when the warnings module is reloaded (thing usually only done in unit tests).

  • bpo-20572: Remove the subprocess.Popen.wait endtime parameter. It was deprecated in 3.4 and undocumented prior to that.

  • bpo-25659: In ctypes, prevent a crash calling the from_buffer() and from_buffer_copy() methods on abstract classes like Array.

  • 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: Makes Path.resolve() succeed on paths that do not exist. Patch by Vajrasky Kok

  • 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: Fixed possible crash in _io.TextIOWrapper deallocator when the garbage collector is invoked in other thread. Based on patch by Sebastian Cufre.

  • bpo-27517: LZMA compressor and decompressor no longer raise exceptions if given empty data twice. Patch by Benjamin Fogle.

  • bpo-28549: Fixed segfault in curses's addch() with ncurses6.

  • 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: The webbrowser module now supports Firefox 36+ and derived browsers. Based on patch by Oleg Broytman.

  • 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: 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: 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: 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: The textwrap.TextWrapper class now honors non-breaking spaces. Based on patch by Kaarle Ritvanen.

  • bpo-28353: os.fwalk() no longer fails on broken links.

  • bpo-28430: Fix iterator of C implemented asyncio.Future doesn't accept non-None value is passed to it.send(val).

  • bpo-27025: Generated names for Tkinter widgets now start by the "!" prefix for readability.

  • bpo-25464: Fixed HList.header_exists() in tkinter.tix module by addin a workaround to Tix library bug.

  • bpo-28488: shutil.make_archive() no longer adds entry "./" to ZIP archive.

  • 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: timeit now uses the sequence 1, 2, 5, 10, 20, 50,... instead of 1, 10, 100,... for autoranging.

  • bpo-28115: Command-line interface of the zipfile module now uses argparse. Added support of long options.

  • bpo-18219: Optimize csv.DictWriter for large number of columns. Patch by Mariatta Wijaya.

  • bpo-28448: Fix C implemented asyncio.Future didn't work on Windows.

  • 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: Fix error building socket module when multithreading is disabled.

  • bpo-28240: timeit: remove -c/--clock and -t/--time command line options which were deprecated since Python 3.3.

  • bpo-28240: timeit now repeats the benchmarks 5 times instead of only 3 to make benchmarks more reliable.

  • 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 for rationale.

  • bpo-24452: Make webbrowser support Chrome on Mac OS X. Patch by Ned Batchelder.

  • bpo-20766: Fix references leaked by pdb in the handling of SIGINT handlers.

  • bpo-27998: Fixed bytes path support in os.scandir() on Windows. Patch by Eryk Sun.

  • bpo-28317: The disassembler now decodes FORMAT_VALUE argument.

  • bpo-28380: unittest.mock Mock autospec functions now properly support assert_called, assert_not_called, and assert_called_once.

  • bpo-28229: lzma module now supports pathlib.

  • bpo-28321: Fixed writing non-BMP characters with binary format in plistlib.

  • bpo-28225: bz2 module now supports pathlib. Initial patch by Ethan Furman.

  • bpo-28227: gzip now supports pathlib. Patch by Ethan Furman.

  • bpo-28332: Deprecated silent truncations in socket.htons and socket.ntohs. Original patch by Oren Milman.

  • bpo-27358: Optimized merging var-keyword arguments and improved error message when passing a non-mapping as a var-keyword argument.

  • bpo-28257: Improved error message when passing a non-iterable as a var-positional argument. Added opcode BUILD_TUPLE_UNPACK_WITH_CALL.

  • bpo-28322: Fixed possible crashes when unpickle itertools objects from incorrect pickle data. Based on patch by John Leitch.

  • bpo-28228: imghdr now supports pathlib.

  • bpo-28226: compileall now supports pathlib.

  • bpo-28314: Fix function declaration (C flags) for the getiterator() method of xml.etree.ElementTree.Element.

  • 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: 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: Fixed possible use after free in the decompress() methods of the LZMADecompressor and BZ2Decompressor classes. Original patch by John Leitch.

  • 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: 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: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py. Patch by Madison May.

  • bpo-27611: Fixed support of default root window in the tkinter.tix module. Added the master parameter in the DisplayStyle constructor.

  • 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: Allow falsy values to be used for msg parameter of subTest().

  • 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: Fix memory leak on Windows in the os module (fix path_converter() function).

  • bpo-25400: RobotFileParser now correctly returns default values for crawl_delay and request_rate. Initial patch by Peter Wirtz.

  • bpo-27932: Prevent memory leak in win32_ver().

  • Fix UnboundLocalError in socket._sendfile_use_sendfile.

  • bpo-28075: Check for ERROR_ACCESS_DENIED in Windows implementation of os.stat(). Patch by Eryk Sun.

  • 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: Prevent codecs.escape_encode() from raising SystemError when an empty bytestring is passed.

  • bpo-28181: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

  • bpo-25895: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by Gergely Imreh and Markus Holtermann.

  • bpo-28114: Fix a crash in parse_envlist() when env contains byte strings. Patch by Eryk Sun.

  • bpo-27599: Fixed buffer overrun in binascii.b2a_qp() and binascii.a2b_qp().

  • bpo-27906: Fix socket accept exhaustion during high TCP traffic. Patch by Kevin Conway.

  • bpo-28174: Handle when SO_REUSEPORT isn't properly supported. Patch by Seth Michael Larson.

  • bpo-26654: Inspect functools.partial in asyncio.Handle.__repr__. Patch by iceboy.

  • bpo-26909: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

  • bpo-28176: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

  • bpo-27759: Fix selectors incorrectly retain invalid file descriptors. Patch by Mark Williams.

  • bpo-28325: Remove vestigial MacOS 9 macurl2path module and its tests.

  • bpo-28368: Refuse monitoring processes if the child watcher has no loop attached. Patch by Vincent Michel.

  • bpo-28369: Raise RuntimeError when transport's FD is used with add_reader, add_writer, etc.

  • bpo-28370: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг Марк.

  • bpo-28371: Deprecate passing asyncio.Handles to run_in_executor.

  • bpo-28372: Fix asyncio to support formatting of non-python coroutines.

  • bpo-28399: Remove UNIX socket from FS before binding. Patch by Коренберг Марк.

  • bpo-27972: Prohibit Tasks to await on themselves.

  • bpo-24142: Reading a corrupt config file left configparser in an invalid state. Original patch by Florian Höch.

  • bpo-29581: ABCMeta.__new__ now accepts **kwargs, allowing abstract base classes to use keyword parameters in __init_subclass__. Patch by Nate Soares.

  • 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: path.resolve(strict=False) no longer cuts the path after the first element not present in the filesystem. Patch by Antoine Pietri.

ドキュメント

  • bpo-31294: Fix incomplete code snippet in the ZeroMQSocketListener and ZeroMQSocketHandler examples and adapt them to Python 3.

  • bpo-21649: Add RFC 7525 and Mozilla server side TLS links to SSL documentation.

  • bpo-31128: Allow the pydoc server to bind to arbitrary hostnames.

  • bpo-30803: Clarify doc on truth value testing. Original patch by Peter Thomassen.

  • bpo-30176: Add missing attribute related constants in curses documentation.

  • 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: Add missing info of code object in inspect documentation.

  • 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, bpo-12518)

  • bpo-28929: Link the documentation to its source file on GitHub.

  • bpo-25008: Document smtpd.py as effectively deprecated and add a pointer to aiosmtpd, a third-party asyncio-based replacement.

  • bpo-26355: Add canonical header link on each page to corresponding major version of the documentation. Patch by Matthias Bussonnier.

  • bpo-29349: Fix Python 2 syntax in code for building the documentation.

  • 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 and zero-argument super().

  • bpo-28513: Documented command-line interface of zipfile.

テスト

  • 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: Silence traceback in test_ssl
  • bpo-31346: Prefer PROTOCOL_TLS_CLIENT and PROTOCOL_TLS_SERVER protocols for SSLContext.
  • bpo-25674: Remove sha256.tbs-internet.com ssl test
  • 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: 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: Add the set_nomemory(start, stop) and remove_mem_hooks() functions to the _testcapi module.
  • 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: 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: Use proper command line parsing in _testembed
  • bpo-28950: Disallow -j0 to be combined with -T/-l in regrtest command line arguments.
  • bpo-28683: Fix the tests that bind() a unix socket and raise PermissionError on Android for a non-root user.
  • bpo-26936: Fix the test_socket failures on Android - getservbyname(), getservbyport() and getaddrinfo() are broken on some Android API levels.
  • bpo-28666: Now test.support.rmtree is able to remove unwritable or unreadable directories.
  • bpo-23839: Various caches now are cleared before running every test file.
  • bpo-26944: Fix test_posix for Android where 'id -G' is entirely wrong or missing the effective gid.
  • bpo-28409: regrtest: fix the parser of command line arguments.
  • bpo-28217: Adds _testconsole module to test console input.
  • bpo-26939: Add the support.setswitchinterval() function to fix test_functools hanging on the Android armv7 qemu emulator.

ビルド

  • bpo-31354: Allow --with-lto to be used on all builds, not just make profile-opt.

  • 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: Per PEP 11, support for the IRIX operating system was removed.

  • bpo-30854: Fix compile error when compiling --without-threads. Patch by Masayuki Yamamoto.

  • bpo-30687: Locate msbuild.exe on Windows when building rather than vcvarsall.bat

  • 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: Add --with-assertions configure flag to explicitly enable C assert() checks. Defaults to off. --with-pydebug implies --with-assertions.

  • bpo-28787: Fix out-of-tree builds of Python when configured with --with--dtrace.

  • bpo-29243: Prevent unnecessary rebuilding of Python during make test, make install and some other make targets when configured with --enable-optimizations.

  • 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: Fix --enable-optimization didn't work.

  • 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: Update Windows build and OS X installers to use OpenSSL 1.0.2k.

  • 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: Remove old Be OS helper scripts.

  • bpo-26851: Set Android compilation and link flags.

  • bpo-28768: Fix implicit declaration of function _setmode. Patch by Masayuki Yamamoto

  • bpo-29080: Removes hard dependency on hg.exe from PCBuild/build.bat

  • bpo-23903: Added missed names to PC/python3.def.

  • bpo-28762: lockf() is available on Android API level 24, but the F_LOCK macro is not defined in android-ndk-r13.

  • 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: 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: Do not define sys.implementation._multiarch on Android.

  • bpo-10656: Fix out-of-tree building on AIX. Patch by Tristan Carel and Michael Haubenwallner.

  • bpo-26359: Rename --with-optimiations to --enable-optimizations.

  • bpo-28444: Fix missing extensions modules when cross compiling.

  • bpo-28208: Update Windows build and OS X installers to use SQLite 3.14.2.

  • bpo-28248: Update Windows build and OS X installers to use OpenSSL 1.0.2j.

  • 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: Fix building extensions modules on Cygwin. Patch by Roumen Petrov, based on original patch by Jason Tishler.

  • 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: Fixed build with Estonian locale (python-config and distclean targets in Makefile). Patch by Arfrever Frehtes Taifersar Arahesis.

  • bpo-26661: setup.py now detects system libffi with multiarch wrapper.

  • 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: Remove redundant include search directory option for building outside the source tree.

  • bpo-28676: Prevent missing 'getentropy' declaration warning on macOS. Patch by Gareth Rees.

Windows

  • bpo-31392: Update Windows build to use OpenSSL 1.1.0f
  • bpo-30389: Adds detection of Visual Studio 2017 to distutils on Windows.
  • 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: Change to building with MSVC v141 (included with Visual Studio 2017)
  • 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: Pre-build OpenSSL, Tcl and Tk and include the binaries in the build.
  • bpo-30731: Add a missing xmlns to python.manifest so that it matches the schema.
  • bpo-30291: Allow requiring 64-bit interpreters from py.exe using -64 suffix. Contributed by Steve (Gadget) Barnes.
  • bpo-30362: Adds list options (-0, -0p) to py.exe launcher. Contributed by Steve Barnes.
  • bpo-23451: Fix socket deprecation warnings in socketmodule.c. Patch by Segev Finer.
  • 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: Removes readme.txt from the installer.
  • bpo-25778: winreg does not truncate string correctly (Patch by Eryk Sun)
  • bpo-28896: Deprecate WindowsRegistryFinder and disable it by default
  • bpo-28522: Fixes mishandled buffer reallocation in getpathp.c
  • bpo-28402: Adds signed catalog files for stdlib on Windows.
  • bpo-28333: Enables Unicode for ps1/ps2 and input() prompts. (Patch by Eryk Sun)
  • bpo-28251: Improvements to help manuals on Windows.
  • bpo-28110: launcher.msi has different product codes between 32-bit and 64-bit
  • bpo-28161: Opening CON for write access fails
  • bpo-28162: WindowsConsoleIO readall() fails if first line starts with Ctrl+Z
  • bpo-28163: WindowsConsoleIO fileno() passes wrong flags to _open_osfhandle
  • bpo-28164: _PyIO_get_console_type fails for various paths
  • bpo-28137: Renames Windows path file to ._pth
  • bpo-28138: Windows ._pth file should allow import site

IDLE

  • bpo-31493: IDLE code context -- fix code update and font update timers.

    Canceling timers prevents a warning message when test_idle completes.

  • 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: IDLE - Improve rstrip entry in doc. Strip trailing whitespace strips more than blank spaces. Multiline string literals are not skipped.

  • bpo-31480: IDLE - make tests pass with zzdummy extension disabled by default.

  • 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: 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: Rearrange IDLE configdialog GenPage into Window, Editor, and Help sections.

  • 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: IDLE - Do not modify tkinter.message in test_configdialog.

  • 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: IDLE: Factor HighPage(Frame) class from ConfigDialog. Patch by Cheryl Sabella.

  • bpo-31001: Add tests for configdialog highlight tab. Patch by Cheryl Sabella.

  • bpo-31205: IDLE: Factor KeysPage(Frame) class from ConfigDialog. The slightly modified tests continue to pass. Patch by Cheryl Sabella.

  • bpo-31130: IDLE -- stop leaks in test_configdialog. Initial patch by Victor Stinner.

  • bpo-31002: Add tests for configdialog keys tab. Patch by Cheryl Sabella.

  • 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: IDLE - Add an outline of a TabPage class in configdialog. Update existing classes to match outline. Initial patch by Cheryl Sabella.

  • bpo-31050: Factor GenPage(Frame) class from ConfigDialog. The slightly modified tests continue to pass. Patch by Cheryl Sabella.

  • 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: IDLE - Use ttk widgets in ConfigDialog. Patches by Terry Jan Reedy and Cheryl Sabella.

  • 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: 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: IDLE: Add more tests for General tab.

  • 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: IDLE -- Add more configdialog font page tests.

  • bpo-28523: IDLE: replace 'colour' with 'color' in configdialog.

  • bpo-30917: Add tests for idlelib.config.IdleConf. Increase coverage from 46% to 96%. Patch by Louie Lu.

  • 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: 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: IDLE: Add tests for ConfigParser subclasses in config. Patch by Louie Lu.

  • bpo-30881: IDLE: Add docstrings to browser.py. Patch by Cheryl Sabella.

  • 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: IDLE: In Settings dialog, select font with Up, Down keys as well as mouse. Initial patch by Louie Lu.

  • bpo-8231: IDLE: call config.IdleConf.GetUserCfgDir only once.

  • 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: IDLE: configdialog - Add docstrings and fix comments. Patch by Cheryl Sabella.

  • bpo-30495: IDLE: Improve textview with docstrings, PEP8 names, and more tests. Patch by Cheryl Sabella.

  • 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: IDLE: add docstrings to grep module. Patch by Cheryl Sabella

  • bpo-21519: IDLE's basic custom key entry dialog now detects duplicates properly. Original patch by Saimadhav Heblikar.

  • 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: 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: 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: 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: Add doc subsubsection about IDLE failure to start. Popup no-connection message directs users to this section.

  • bpo-30642: Fix reference leaks in IDLE tests. Patches by Louie Lu and Terry Jan Reedy.

  • bpo-30495: Add docstrings for textview.py and use PEP8 names. Patches by Cheryl Sabella and Terry Jan Reedy.

  • 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: Add _utest option to textview; add new tests. Increase coverage to 100%. Patches by Louie Lu and Terry Jan Reedy.

  • bpo-29071: IDLE colors f-string prefixes (but not invalid ur prefixes).

  • bpo-28572: Add 10% to coverage of IDLE's test_configdialog. Update and augment description of the configuration system.

Tools/Demos

  • bpo-30983: gdb integration commands (py-bt, etc.) work on optimized shared builds now, too. PEP 523 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: Added the slice index converter in Argument Clinic.
  • 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: python-gdb.py now supports also method-wrapper (wrapperobject) objects.
  • bpo-28023: Fix python-gdb.py didn't support new dict implementation.
  • bpo-15369: The pybench and pystone microbenchmark have been removed from Tools. Please use the new Python benchmark suite https://github.com/python/performance which is more reliable and includes a portable version of pybench working on Python 2 and Python 3.
  • bpo-28102: The zipfile module CLI now prints usage to stderr. Patch by Stephen J. Turnbull.

C API

  • 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: 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: PyUnicode_AsWideCharString() now raises a ValueError if the second argument is NULL and the wchar_t* string contains null characters.

  • bpo-16500: Deprecate PyOS_AfterFork() and add PyOS_BeforeFork(), PyOS_AfterFork_Parent() and PyOS_AfterFork_Child().

  • 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: 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: 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: The result of PyUnicode_AsUTF8AndSize() and PyUnicode_AsUTF8() is now of type const char * rather of char *.

  • 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: The index parameters start and end of PyUnicode_FindChar() are now adjusted to behave like str[start:end].

  • bpo-28808: PyUnicode_CompareWithASCIIString() now never raises exceptions.

  • 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: Private variable _Py_PackageContext is now of type const char * rather of char *.

  • bpo-19569: Compiler warnings are now emitted if use most of deprecated functions.

  • 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: Fix asynchronous generators to handle GeneratorExit in athrow() correctly
  • 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: 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: Fix signed/unsigned comparison warning in pyhash.c.
  • bpo-33391: Fix a leak in set_symmetric_difference().
  • bpo-28055: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.
  • bpo-33231: Fix potential memory leak in normalizestring().
  • bpo-29922: Improved error messages in 'async with' when __aenter__() or __aexit__() return non-awaitable object.
  • bpo-33199: Fix ma_version_tag in dict implementation is uninitialized when copying from key-sharing dict.
  • bpo-33041: Fixed jumping when the function contains an async for loop.
  • bpo-32282: Fix an unnecessary ifdef in the include of VersionHelpers.h in socketmodule on Windows.
  • 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-30167: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by Steve Weber.
  • 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: Avoid race condition with debug logging
  • 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: Fix gather to propagate cancellation of itself even with return_exceptions.
  • 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: Fixed bug where calling write_eof() on a _SelectorSocketTransport after it's already closed raises AttributeError.
  • bpo-33672: Fix Task.__repr__ crash with Cython's bogus coroutines
  • bpo-33469: Fix RuntimeError after closing loop that used run_in_executor
  • bpo-11874: Use a better regex when breaking usage into wrappable parts. Avoids bogus assertion errors from custom metavar strings.
  • 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: tempfile._candidate_tempdir_list should consider common TEMP locations
  • bpo-33542: Prevent uuid.get_node from using a DUID instead of a MAC on Windows. Patch by Zvi Effron
  • bpo-26819: Fix race condition with ReadTransport.resume_reading in Windows proactor event loop.
  • 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: Updated alias mapping with glibc 2.27 supported locales.
  • bpo-33422: Fix trailing quotation marks getting deleted when looking up byte/string literals on pydoc. Patch by Andrés Delfino.
  • bpo-33197: Update error message when constructing invalid inspect.Parameters Patch by Dong-hee Na.
  • bpo-33383: Fixed crash in the get() method of the dbm.ndbm database object when it is called with a single argument.
  • bpo-33329: Fix multiprocessing regression on newer glibcs
  • bpo-991266: Fix quoting of the Comment attribute of http.cookies.SimpleCookie.
  • bpo-33131: Upgrade bundled version of pip to 10.0.1.
  • 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: Fix FD leak in _SelectorSocketTransport Patch by Vlad Starostin.
  • bpo-33256: Fix display of <module> call in the html produced by cgitb.html(). Patch by Stéphane Blondon.
  • bpo-33203: random.Random.choice() now raises IndexError for empty sequences consistently even when called from subclasses without a getrandbits() implementation.
  • bpo-33224: Update difflib.mdiff() for PEP 479. Convert an uncaught StopIteration in a generator into a return-statement.
  • bpo-33209: End framing at the end of C implementation of pickle.Pickler.dump().
  • 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: 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: The ssl module now compiles with LibreSSL 2.7.1.
  • 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: 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: Fix wrong redirection of a low descriptor (0 or 1) to stderr in subprocess if another low descriptor is closed.
  • 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: If nested log adapters are used, the inner process() methods are no longer omitted.
  • bpo-16865: Support arrays >=2GiB in ctypes. Patch by Segev Finer.
  • 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-33503: Fix broken pypi link
  • bpo-33421: Add missing documentation for typing.AsyncContextManager.
  • bpo-33378: Add Korean language switcher for https://docs.python.org/3/
  • bpo-33276: Clarify that the __path__ attribute on modules cannot be just any value.
  • bpo-33201: Modernize documentation for writing C extension types.
  • 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: Document PyBuffer_ToContiguous().
  • bpo-27212: Modify documentation for the islice() recipe to consume initial values up to the start index.
  • bpo-28247: Update zipapp documentation to describe how to make standalone applications.
  • bpo-18802: Documentation changes for ipaddress. Patch by Jon Foster and Berker Peksag.
  • bpo-27428: Update documentation to clarify that WindowsRegistryFinder implements MetaPathFinder. (Patch by Himanshu Lakhara)
  • bpo-8243: Add a note about curses.addch and curses.addstr exception behavior when writing outside a window, or pad.
  • bpo-31432: Clarify meaning of CERT_NONE, CERT_OPTIONAL, and CERT_REQUIRED flags for ssl.SSLContext.verify_mode.

テスト

  • bpo-33655: Ignore test_posix_fallocate failures on BSD platforms that might be due to running on ZFS.
  • bpo-19417: Add test_bdb.py.

ビルド

  • 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: Ensures module definition files for the stable ABI on Windows are correctly regenerated.
  • bpo-33522: Enable CI builds on Visual Studio Team Services at https://python.visualstudio.com/cpython
  • 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: Enable the verbose build for extension modules, when GNU make is passed macros on the command line.

Windows

  • bpo-33184: Update Windows installer to OpenSSL 1.0.2o.

macOS

  • bpo-33184: Update macOS installer build to use OpenSSL 1.0.2o.

IDLE

  • 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: Clicking on a context line moves that line to the top of the editor window.
  • bpo-33763: IDLE: Use read-only text widget for code context instead of label widget.
  • 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: 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: Display up to maxlines non-blank lines for Code Context. If there is no current context, show a single blank line.
  • bpo-33628: IDLE: Cleanup codecontext.py and its test.
  • bpo-33564: IDLE's code context now recognizes async as a block opener.
  • bpo-29706: IDLE now colors async and await as keywords in 3.6. They become full keywords in 3.7.
  • 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: 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: Add docstrings and tests for codecontext.

Tools/Demos

  • bpo-33189: pygettext.py now recognizes only literal strings as docstrings and translatable strings, and rejects bytes literals and f-string expressions.
  • bpo-31920: Fixed handling directories as arguments in the pygettext script. Based on patch by Oleg Krasnikov.
  • bpo-29673: Fix pystackv and pystack gdbinit macros.
  • bpo-32885: Add an -n flag for Tools/scripts/pathfix.py to disable automatic backup creation (files with ~ suffix).
  • 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: 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

テスト

  • bpo-32872: Avoid regrtest compatibility issue with namespace packages.

ビルド

  • 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

セキュリティ

  • bpo-33001: Minimal fix to prevent buffer overrun in os.symlink on Windows
  • 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 and CVE-2018-1061. Patch by Jamie Davis.

Core and Builtins

  • bpo-33026: Fixed jumping out of "with" block by setting f_lineno.
  • bpo-17288: Prevent jumps from 'return' and 'exception' trace events.
  • bpo-32889: Update Valgrind suppression list to account for the rename of Py_ADDRESS_IN_RANG to address_in_range.
  • bpo-32650: Pdb and other debuggers dependent on bdb.py will correctly step over (next command) native coroutines. Patch by Pablo Galindo.
  • 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: Fix possible crashing in builtin Unicode decoders caused by write out-of-bound errors when using customized decode error handlers.
  • bpo-26163: Improved frozenset() hash to create more distinct hash values when faced with datasets containing many similar values.
  • bpo-27169: The __debug__ constant is now optimized out at compile time. This fixes also bpo-22091.
  • bpo-32329: sys.flags.hash_randomization is now properly set to 0 when hash randomization is turned off by PYTHONHASHSEED=0.
  • 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: 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: 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: The repr of deeply nested dict now raises a RecursionError instead of crashing due to a stack overflow.

ライブラリ

  • bpo-33064: lib2to3 now properly supports trailing commas after *args and **kwargs in function signatures.

  • bpo-31804: Avoid failing in multiprocessing.Process if the standard streams are closed or None at exit.

  • bpo-33037: Skip sending/receiving data after SSL transport closing.

  • bpo-30353: Fix ctypes pass-by-value for structs on 64-bit Cygwin/MinGW.

  • bpo-33009: Fix inspect.signature() for single-parameter partialmethods.

  • bpo-32969: Expose several missing constants in zlib and fix corresponding documentation.

  • bpo-32713: Fixed tarfile.itn handling of out-of-bounds float values. Patch by Joffrey Fuhrer.

  • bpo-30622: The ssl module now detects missing NPN support in LibreSSL.

  • bpo-32922: dbm.open() now encodes filename with the filesystem encoding rather than default encoding.

  • bpo-32859: In os.dup2, don't check every call whether the dup3 syscall exists or not.

  • 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: In tkinter, after_cancel(None) now raises a ValueError instead of canceling the first scheduled function. Patch by Cheryl Sabella.

  • bpo-32852: Make sure sys.argv remains as a list when running trace.

  • bpo-32841: Fixed asyncio.Condition issue which silently ignored cancellation after notifying and cancelling a conditional lock. Patch by Bar Harel.

  • bpo-31787: Fixed refleaks of __init__() methods in various modules. (Contributed by Oren Milman)

  • bpo-30157: Fixed guessing quote and delimiter in csv.Sniffer.sniff() when only the last field is quoted. Patch by Jake Davis.

  • bpo-32394: socket: Remove TCP_FASTOPEN, TCP_KEEPCNT flags on older version Windows during run-time.

  • 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: 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: 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: Do not include name field in SMTP envelope from address. Patch by Stéphane Wirtel

  • bpo-27931: Fix email address header parsing error when the username is an empty quoted string. Patch by Xiang Zhang.

  • 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: uuid.uuid1 no longer raises an exception if a 64-bit hardware address is encountered.

  • bpo-31848: Fix the error handling in Aifc_read.initfp() when the SSND chunk is not found. Patch by Zackery Spytz.

  • 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: The nis module is now compatible with new libnsl and headers location.

  • bpo-32473: Improve ABCMeta._dump_registry() output readability

  • bpo-32521: glibc has removed Sun RPC. Use replacement libtirpc headers and library in nis module.

  • bpo-32228: Ensure that truncate() preserves the file position (as reported by tell()) after writes longer than the buffer size.

  • bpo-26133: Don't unsubscribe signals in asyncio UNIX event loop on interpreter shutdown.

  • 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: urllib.parse.urlsplit() does not convert zone-id (scope) to lower case for scoped IPv6 addresses in hostnames now.

  • bpo-32302: Fix bdist_wininst of distutils for CRT v142: it binary compatible with CRT v140.

  • 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: Raise NotImplementedError instead of SystemError on platforms where chmod(..., follow_symlinks=False) is not supported. Patch by Anthony Sottile.

  • bpo-32199: The getnode() ip getter now uses 'ip link' instead of 'ip link list'.

  • bpo-27456: Ensure TCP_NODELAY is set on Linux. Tests by Victor Stinner.

  • 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: Importing native path module (posixpath, ntpath) now works even if the os module still is not imported.

ドキュメント

  • bpo-17232: Clarify docs for -O and -OO. Patch by Terry Reedy.
  • bpo-32800: Update link to w3c doc for xml default namespaces.
  • bpo-8722: Document __getattr__() behavior when property get() method raises AttributeError.
  • 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: Improve docstrings for pathlib.PurePath subclasses.
  • 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.

テスト

  • bpo-32517: Fix failing test_asyncio on macOS 10.12.2+ due to transport of KqueueSelector loop was not being closed.
  • bpo-32721: Fix test_hashlib to not fail if the _md5 module is not built.
  • bpo-32252: Fix faulthandler_suppress_crash_report() used to prevent core dump files when testing crashes. getrlimit() returns zero on success.
  • 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.

ビルド

  • bpo-32635: Fix segfault of the crypt module when libxcrypt is provided instead of libcrypt at the system.

Windows

  • bpo-33016: Fix potential use of uninitialized memory in nt._getfinalpathname
  • bpo-32903: Fix a memory leak in os.chdir() on Windows if the current directory is set to a UNC path.
  • bpo-31966: Fixed WindowsConsoleIO.write() for writing empty data.
  • bpo-32409: Ensures activate.bat can handle Unicode contents.
  • bpo-32457: Improves handling of denormalized executable path when launching Python.
  • bpo-32370: Use the correct encoding for ipconfig output in the uuid module. Patch by Segev Finer.
  • 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: Create standalone _distutils_findvs module.

macOS

  • 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: 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: Simplify and rename StringTranslatePseudoMapping in pyparse.
  • bpo-32916: Change str to code in pyparse.
  • bpo-32905: Remove unused code in pyparse module.
  • bpo-32874: Add tests for pyparse.
  • 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: 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: Update configdialog General tab docstring to add new widgets to the widget list.

Tools/Demos

  • 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: Fix pygettext not extracting docstrings for functions with type annotated arguments. Patch by Toby Harradine.

C API

  • 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: 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: 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: Fix the interactive interpreter looping endlessly when no memory.
  • 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: Fix a segmentation fault caused by a combination of the async soft keyword and continuation lines.
  • bpo-21720: BytesWarning no longer emitted when the fromlist argument of __import__() or the __all__ attribute of the module contain bytes instances.
  • bpo-31825: Fixed OverflowError in the 'unicode-escape' codec and in codecs.escape_decode() when decode an escaped non-ascii byte.
  • 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: 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: Restored blocking "from package import module" by setting sys.modules["package.module"] to None.
  • bpo-31626: Fixed a bug in debug memory allocator. There was a write to freed memory after shrinking a memory block.
  • bpo-31619: Fixed a ValueError when convert a string with large number of underscores to integer with binary base.
  • bpo-31592: Fixed an assertion failure in Python parser in case of a bad unicodedata.normalize(). Patch by Oren Milman.
  • 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: Fix an assertion failure in _warnings.warn() in case of a bad __name__ global. Patch by Oren Milman.
  • bpo-31505: Fix an assertion failure in json, in case _json.make_encoder() received a bad encoder() argument. Patch by Oren Milman.
  • 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: 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: Fix an assertion failure in _random.Random.seed() in case the argument has a bad __abs__() method. Patch by Oren Milman.
  • bpo-31315: Fix an assertion failure in imp.create_dynamic(), when spec.name is not a string. Patch by Oren Milman.
  • bpo-31311: Fix a crash in the __setstate__() method of ctypes._CData, in case of a bad __dict__. Patch by Oren Milman.
  • 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: 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: PyErr_PrintEx() clears now the ignored exception that may be raised by _PySys_SetObjectId(), for example when no memory.

ライブラリ

  • 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: The header folding algorithm for the new email policies has been rewritten, which also fixes bpo-30788, bpo-31831, and bpo-32182. In particular, RFC2231 folding is now done correctly.

  • 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: Make msilib.SummaryInformation.GetProperty() return None when the value of property is VT_EMPTY. Initial patch by Mark Mc Mahon.

  • bpo-31325: Fix wrong usage of collections.namedtuple() in the RobotFileParser.parse() method.

    Initial patch by Robin Wellner.

  • 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: 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: 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: Make asyncio.IncompleteReadError and LimitOverrunError pickleable.

  • 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: Restored support of loading marshal files with the TYPE_INT64 code. These files can be produced in Python 2.7.

  • bpo-31970: Reduce performance overhead of asyncio debug mode.

  • 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: Fix potential missed signal in signal.signal().

  • bpo-31933: Fix Blake2 params leaf_size and node_offset on big endian platforms. Patch by Jack O'Connor.

  • 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: 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: plistlib now catches more errors when read binary plists and raises InvalidFileException instead of unexpected exceptions.

  • bpo-25720: Fix the method for checking pad state of curses WINDOW. Patch by Masayuki Yamamoto.

  • bpo-31893: Fixed the layout of the kqueue_event structure on OpenBSD and NetBSD. Fixed the comparison of the kqueue_event objects.

  • bpo-31891: Fixed building the curses module on NetBSD.

  • 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: Fix multiprocessing.Process when stdout and/or stderr is closed or None.

  • bpo-31457: If nested log adapters are used, the inner process() methods are no longer omitted.

  • bpo-31457: The manager property on LoggerAdapter objects is now properly settable.

  • 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: 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: Fixed buffer overflow in select.kqueue.control().

  • bpo-31770: Prevent a crash when calling the __init__() method of a sqlite3.Cursor object more than once. Patch by Oren Milman.

  • 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: Prevent a crash in sqlite3.Cursor.close() in case the Cursor object is uninitialized. Patch by Oren Milman.

  • bpo-31752: Fix possible crash in timedelta constructor called with custom integers.

  • bpo-31701: On Windows, faulthandler.enable() now ignores MSC and COM exceptions.

  • bpo-31728: Prevent crashes in _elementtree due to unsafe cleanup of Element.text and Element.tail. Patch by Oren Milman.

  • bpo-31620: an empty asyncio.Queue now doesn't leak memory when queue.get pollers timeout

  • 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: Fixed memory leaks in Tkinter's methods splitlist() and split() when pass a string larger than 2 GiB.

  • bpo-31673: Fixed typo in the name of Tkinter's method adderrorinfo().

  • bpo-30806: Fix the string representation of a netrc object.

  • bpo-15037: Added a workaround for getkey() in curses for ncurses 5.7 and earlier.

  • bpo-25351: Avoid venv activate failures with undefined variables

  • 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: Stop crashes when concurrently iterate over itertools.groupby() iterators.

  • bpo-31516: threading.current_thread() should not return a dummy thread at shutdown.

  • bpo-31351: python -m ensurepip now exits with non-zero exit code if pip bootstrapping has failed.

  • bpo-31482: random.seed() now works with bytes in version=1

  • 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: multiprocessing's semaphore tracker should be launched again if crashed.

  • bpo-31308: Make multiprocessing's forkserver process immune to Ctrl-C and other user interruptions. If it crashes, restart it when necessary.

ドキュメント

  • bpo-32105: Added asyncio.BaseEventLoop.connect_accepted_socket versionadded marker.
  • bpo-31537: Fix incorrect usage of get_history_length in readline documentation example code. Patch by Brad Smith.
  • bpo-30085: The operator functions without double underscores are preferred for clarity. The one with underscores are only kept for back-compatibility.

テスト

  • bpo-31380: Skip test_httpservers test_undecodable_file on macOS: fails on APFS.
  • 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: 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: Add the set_nomemory(start, stop) and remove_mem_hooks() functions to the _testcapi module.

ビルド

  • bpo-32059: detect_modules() in setup.py now also searches the sysroot paths when cross-compiling.
  • bpo-31957: Fixes Windows SDK version detection when building for Windows.
  • bpo-31609: Fixes quotes in PCbuild/clean.bat
  • bpo-31934: Abort the build when building out of a not clean source tree.
  • 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: Update Windows builds to use SQLite 3.21.0.
  • bpo-28791: Update OS X installer to use SQLite 3.21.0.
  • bpo-22140: Prevent double substitution of prefix in python-config.sh.
  • bpo-31536: Avoid wholesale rebuild after make regen-all if nothing changed.

Windows

  • bpo-1102: Return None when View.Fetch() returns ERROR_NO_MORE_ITEMS instead of raising MSIError.

    Initial patch by Anthony Tuininga.

  • bpo-31944: Fixes Modify button in Apps and Features dialog.

macOS

  • bpo-31392: Update macOS installer to use OpenSSL 1.0.2m

IDLE

  • 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: Delete unused file idlelib/tabbedpages.py. Use of TabbedPageSet in configdialog was replaced by ttk.Notebook.

  • bpo-32100: IDLE: Fix old and new bugs in pathbrowser; improve tests. Patch mostly by Cheryl Sabella.

  • 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: The font sample in the IDLE configuration dialog is now editable. Changes persist while IDLE remains open

  • 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: 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: 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: 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: IDLE - Make _htest, _utest parameters keyword only.

  • bpo-31559: Remove test order dependence in idle_test.test_browser.

  • 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: Default fonts now are scaled on HiDPI displays.

  • 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: 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: 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: Fix memory corruption due to allocator mix in getpath.c between Py_GetPath() and Py_SetPath()
  • 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.

Python 3.6.3 final

Release date: 2017-10-03

ライブラリ

  • bpo-31641: Re-allow arbitrary iterables in concurrent.futures.as_completed(). Fixes regression in 3.6.3rc1.

ビルド

  • bpo-31662: Fix typos in Windows uploadrelease.bat script. Fix Windows Doc build issues in Doc/make.bat.
  • bpo-31423: Fix building the PDF documentation with newer versions of Sphinx.

Python 3.6.3 release candidate 1

Release date: 2017-09-18

セキュリティ

  • bpo-29781: SSLObject.version() now correctly returns None when handshake over BIO has not been performed yet.
  • bpo-30947: Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to get security fixes.

Core and Builtins

  • 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: Fix an assertion failure in PyErr_WriteUnraisable() in case of an exception with a bad __module__ attribute. Patch by Oren Milman.

  • bpo-31416: Fix assertion failures in case of a bad warnings.filters or warnings.defaultaction. Patch by Oren Milman.

  • bpo-31411: Raise a TypeError instead of SystemError in case warnings.onceregistry is not a dictionary. Patch by Oren Milman.

  • bpo-31373: Fix several possible instances of undefined behavior due to floating-point demotions.

  • 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: Include sys/sysmacros.h for major(), minor(), and makedev(). GNU C libray plans to remove the functions from sys/types.h.

  • 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: 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: Fix a crash in some methods of io.TextIOWrapper, when the decoder's state is invalid. Patch by Oren Milman.

  • bpo-30721: print now shows correct usage hint for using Python 2 redirection syntax. Patch by Sanyam Khurana.

  • bpo-31070: Fix a race condition in importlib _get_module_lock().

  • bpo-31095: Fix potential crash during GC caused by tp_dealloc which doesn't call PyObject_GC_UnTrack().

  • bpo-31071: Avoid masking original TypeError in call with * unpacking when other arguments are passed.

  • bpo-30978: str.format_map() now passes key lookup exceptions through. Previously any exception was replaced with a KeyError exception.

  • bpo-30808: Use _Py_atomic API for concurrency-sensitive signal state.

  • 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: 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: Avoid blocking in pthread_mutex_lock() when PyThread_acquire_lock() is asked not to block.

  • bpo-31161: Make sure the 'Missing parentheses' syntax error message is only applied to SyntaxError, not to subclasses. Patch by Martijn Pieters.

  • bpo-30814: Fixed a race condition when import a submodule from a package.

  • bpo-30597: print now shows expected input in custom error message when used as a Python 2 statement. Patch by Sanyam Khurana.

ライブラリ

  • bpo-31499: xml.etree: Fix a crash when a parser is part of a reference cycle.

  • 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: Speed improvements to the typing module. Original PRs by Ivan Levkivskyi and Mitar.

  • bpo-31544: The C accelerator module of ElementTree ignored exceptions raised when looking up TreeBuilder target methods in XMLParser().

  • bpo-31234: socket.create_connection() now fixes manually a reference cycle: clear the variable storing the last exception on success.

  • bpo-31457: LoggerAdapter objects can now be nested.

  • bpo-31400: Improves SSL error handling to avoid losing error numbers.

  • bpo-28958: ssl.SSLContext() now uses OpenSSL error information when a context cannot be instantiated.

  • 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: Fix string concatenation bug in rare error path in the subprocess module

  • bpo-31350: Micro-optimize asyncio._get_running_loop() to become up to 10% faster.

  • 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: Add TLS 1.3 cipher suites and OP_NO_TLSv1_3.

  • 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: 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: The map() and as_completed() iterators in concurrent.futures now avoid keeping a reference to yielded objects.

  • bpo-10746: Fix ctypes producing wrong PEP 3118 type codes for integer types.

  • 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: concurrent.futures: WorkItem.run() used by ThreadPoolExecutor now breaks a reference cycle between an exception object and the WorkItem object.

  • bpo-31247: xmlrpc.server now explicitly breaks reference cycles when using sys.exc_info() in code handling exceptions.

  • 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: Fixed miscellaneous errors in asyncio speedup module.

  • 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: Fix copyreg._slotnames() mangled attribute calculation for classes whose name begins with an underscore. Patch by Shane Harvey.

  • bpo-31061: Fixed a crash when using asyncio and threads.

  • bpo-30502: Fix handling of long oids in ssl. Based on patch by Christian Heimes.

  • bpo-30119: ftplib.FTP.putline() now throws ValueError on commands that contains CR or LF. Patch by Dong-hee Na.

  • 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: Fix unittest.mock's autospec to not fail on method-bound builtin functions. Patch by Aaron Gallagher.

  • bpo-30961: Fix decrementing a borrowed reference in tracemalloc.

  • bpo-25684: Change ttk.OptionMenu radiobuttons to be unique across instances of OptionMenu.

  • 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: Fix segfault in readline when using readline's history-size option. Patch by Nir Soffer.

  • bpo-30319: socket.close() now ignores ECONNRESET error.

  • bpo-30828: Fix out of bounds write in asyncio.CFuture.remove_done_callback().

  • 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: Fix bug when modifying os.environ while iterating over it

  • bpo-30532: Fix email header value parser dropping folding white space in certain cases.

  • bpo-30879: os.listdir() and os.scandir() now emit bytes names when called with bytes-like argument.

  • bpo-30746: Prohibited the '=' character in environment variable names in os.putenv() and os.spawn*().

  • bpo-29755: Fixed the lgettext() family of functions in the gettext module. They now always return bytes.

ドキュメント

  • bpo-31294: Fix incomplete code snippet in the ZeroMQSocketListener and ZeroMQSocketHandler examples and adapt them to Python 3.
  • bpo-21649: Add RFC 7525 and Mozilla server side TLS links to SSL documentation.
  • bpo-30803: Clarify doc on truth value testing. Original patch by Peter Thomassen.

テスト

  • bpo-31320: Silence traceback in test_ssl
  • bpo-25674: Remove sha256.tbs-internet.com ssl test
  • 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: 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-30854: Fix compile error when compiling --without-threads. Patch by Masayuki Yamamoto.

Windows

  • bpo-30389: Adds detection of Visual Studio 2017 to distutils on Windows.
  • bpo-31340: Change to building with MSVC v141 (included with Visual Studio 2017)
  • 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: Add a missing xmlns to python.manifest so that it matches the schema.

IDLE

  • bpo-31493: IDLE code context -- fix code update and font update timers.

    Canceling timers prevents a warning message when test_idle completes.

  • 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: IDLE - Improve rstrip entry in doc. Strip trailing whitespace strips more than blank spaces. Multiline string literals are not skipped.

  • bpo-31480: IDLE - make tests pass with zzdummy extension disabled by default.

  • 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: 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: Rearrange IDLE configdialog GenPage into Window, Editor, and Help sections.

  • 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: IDLE - Do not modify tkinter.message in test_configdialog.

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

    Inital patch by Charles Wohlganger.

  • bpo-31206: IDLE: Factor HighPage(Frame) class from ConfigDialog. Patch by Cheryl Sabella.

  • bpo-31001: Add tests for configdialog highlight tab. Patch by Cheryl Sabella.

  • bpo-31205: IDLE: Factor KeysPage(Frame) class from ConfigDialog. The slightly modified tests continue to pass. Patch by Cheryl Sabella.

  • bpo-31130: IDLE -- stop leaks in test_configdialog. Initial patch by Victor Stinner.

  • bpo-31002: Add tests for configdialog keys tab. Patch by Cheryl Sabella.

  • 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: IDLE - Add an outline of a TabPage class in configdialog. Update existing classes to match outline. Initial patch by Cheryl Sabella.

  • bpo-31050: Factor GenPage(Frame) class from ConfigDialog. The slightly modified tests continue to pass. Patch by Cheryl Sabella.

  • 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: IDLE - Use ttk widgets in ConfigDialog. Patches by Terry Jan Reedy and Cheryl Sabella.

  • 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: 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: IDLE: Add more tests for General tab.

  • 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: IDLE -- Add more configdialog font page tests.

  • bpo-28523: IDLE: replace 'colour' with 'color' in configdialog.

  • bpo-30917: Add tests for idlelib.config.IdleConf. Increase coverage from 46% to 96%. Patch by Louie Lu.

  • 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: 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: IDLE: Add tests for ConfigParser subclasses in config. Patch by Louie Lu.

  • bpo-30881: IDLE: Add docstrings to browser.py. Patch by Cheryl Sabella.

  • 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: IDLE: In Settings dialog, select font with Up, Down keys as well as mouse. Initial patch by Louie Lu.

  • bpo-8231: IDLE: call config.IdleConf.GetUserCfgDir only once.

  • 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: IDLE: configdialog - Add docstrings and fix comments. Patch by Cheryl Sabella.

  • bpo-30495: IDLE: Improve textview with docstrings, PEP8 names, and more tests. Patch by Cheryl Sabella.

  • 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: IDLE: add docstrings to grep module. Patch by Cheryl Sabella

  • bpo-21519: IDLE's basic custom key entry dialog now detects duplicates properly. Original patch by Saimadhav Heblikar.

  • 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: 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: 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: gdb integration commands (py-bt, etc.) work on optimized shared builds now, too. PEP 523 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

セキュリティ

  • bpo-30730: Prevent environment variables injection in subprocess on Windows. Prevent passing other environment variables and command arguments.
  • bpo-30694: Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple security vulnerabilities including: CVE-2017-9233 (External entity infinite loop DoS), CVE-2016-9063 (Integer overflow, re-fix), CVE-2016-0718 (Fix regression bugs from 2.2.0's fix to CVE-2016-0718) and CVE-2012-0876 (Counter hash flooding with SipHash). Note: the 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: 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

Core and Builtins

  • bpo-30682: Removed a too-strict assertion that failed for certain f-strings, such as eval("f'\n'") and eval("f'\r'").
  • bpo-30604: Move co_extra_freefuncs to not be per-thread to avoid crashes
  • bpo-29104: Fixed parsing backslashes in f-strings.
  • 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: Fixed type.__setattr__() and type.__delattr__() for non-interned attribute names. Based on patch by Eryk Sun.
  • 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: sys.getsizeof() on a code object now returns the sizes which includes the code struct and sizes of objects which it references. Patch by Dong-hee Na.
  • bpo-29949: Fix memory usage regression of set and frozenset object.
  • bpo-29935: Fixed error messages in the index() method of tuple, list and deque when pass indices of wrong type.
  • bpo-29859: Show correct error messages when any of the pthread_* calls in thread_pthread.h fails.
  • bpo-28876: bool(range) works even if len(range) raises OverflowError.
  • bpo-29600: Fix wrapping coroutine return values in StopIteration.
  • bpo-28856: Fix an oversight that %b format for bytes should support objects follow the buffer protocol.
  • bpo-29714: Fix a regression that bytes format may fail when containing zero bytes inside.
  • bpo-29478: If max_line_length=None is specified while using the Compat32 policy, it is no longer ignored. Patch by Mircea Cosbuc.

ライブラリ

  • bpo-30616: Functional API of enum allows to create empty enums. Patched by Dong-hee Na
  • bpo-30038: Fix race condition between signal delivery and wakeup file descriptor. Patch by Nathaniel Smith.
  • bpo-23894: lib2to3 now recognizes rb'...' and f'...' strings.
  • bpo-23890: unittest.TestCase.assertRaises() now manually breaks a reference cycle to not keep objects alive longer than expected.
  • bpo-30149: inspect.signature() now supports callables with variable-argument parameters wrapped with partialmethod. Patch by Dong-hee Na.
  • 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: Fixed comparison check for ipaddress.ip_interface objects. Patch by Sanjay Sundaresan.
  • bpo-30605: re.compile() no longer raises a BytesWarning when compiling a bytes instance with misplaced inline modifier. Patch by Roy Williams.

セキュリティ

  • bpo-29591: Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 and CVE-2016-4472. See https://sourceforge.net/p/expat/bugs/537/ for more information.

ライブラリ

  • bpo-24484: Avoid race condition in multiprocessing cleanup (#2159)
  • bpo-28994: The traceback no longer displayed for SystemExit raised in a callback registered by atexit.
  • bpo-30508: Don't log exceptions if Task/Future "cancel()" method was called.
  • 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: Fix ssl sockets leaks when connection is aborted in asyncio/ssl implementation. Patch by Michaël Sghaïer.
  • bpo-29743: Closing transport during handshake process leaks open socket. Patch by Nikolay Kim
  • bpo-27585: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu Sornay.
  • 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: inspect.isabstract() now works during __init_subclass__. Patch by Nate Soares.
  • bpo-29581: ABCMeta.__new__ now accepts **kwargs, allowing abstract base classes to use keyword parameters in __init_subclass__. Patch by Nate Soares.
  • bpo-30557: faulthandler now correctly filters and displays exception codes on Windows
  • bpo-30378: Fix the problem that logging.handlers.SysLogHandler cannot handle IPv6 addresses.
  • bpo-29960: Preserve generator state when _random.Random.setstate() raises an exception. Patch by Bryan Olson.
  • bpo-30414: multiprocessing.Queue._feed background running thread do not break from main loop on exception.
  • bpo-30003: Fix handling escape characters in HZ codec. Based on patch by Ma Lin.
  • bpo-30301: Fix AttributeError when using SimpleQueue.empty() under spawn and forkserver start methods.
  • 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: 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: Fixed Task.cancel() can be ignored when the task is running coroutine and the coroutine returned without any more await.
  • bpo-30266: contextlib.AbstractContextManager now supports anti-registration by setting __enter__ = None or __exit__ = None, following the pattern introduced in bpo-25958. Patch by Jelle Zijlstra.
  • 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: Fix range checking in GB18030 decoder. Original patch by Ma Lin.
  • bpo-26293: Change resulted because of zipfile breakage. (See also: bpo-29094)
  • 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: Avoid KeyboardInterrupt tracebacks in forkserver helper process when Ctrl-C is received.
  • 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: Fix getsockname() for unbound AF_UNIX sockets on Linux.
  • bpo-30070: Fixed leaks and crashes in errors handling in the parser module.
  • 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: 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: _io._IOBase.readlines will check if it's closed first when hint is present.
  • bpo-29694: Fixed race condition in pathlib mkdir with flags parents=True. Patch by Armin Rigo.
  • bpo-29692: Fixed arbitrary unchaining of RuntimeError exceptions in contextlib.contextmanager. Patch by Siddharth Velankar.
  • bpo-29998: Pickling and copying ImportError now preserves name and path attributes.
  • bpo-29953: Fixed memory leaks in the replace() method of datetime and time objects when pass out of bound fold argument.
  • bpo-29942: Fix a crash in itertools.chain.from_iterable when encountering long runs of empty iterables.
  • bpo-27863: Fixed multiple crashes in ElementTree caused by race conditions and wrong types.
  • 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: Avoid incorrect errors raised by Path.mkdir(exist_ok=True) when the OS gives priority to errors such as EACCES over EEXIST.
  • bpo-29861: Release references to tasks, their arguments and their results as soon as they are finished in multiprocessing.Pool.
  • bpo-29884: faulthandler: Restore the old sigaltstack during teardown. Patch by Christophe Zeitouny.
  • bpo-25455: Fixed crashes in repr of recursive buffered file-like objects.
  • bpo-29800: Fix crashes in partial.__repr__ if the keys of partial.keywords are not strings. Patch by Michael Seifert.
  • bpo-29742: get_extra_info() raises exception if get called on closed ssl transport. Patch by Nikolay Kim.
  • 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: 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: The zipfile module now accepts path-like objects for external paths.
  • bpo-26915: index() and count() methods of collections.abc.Sequence now check identity before checking equality when do comparisons.
  • 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: 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: 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: Add doc subsubsection about IDLE failure to start. Popup no-connection message directs users to this section.
  • bpo-30642: Fix reference leaks in IDLE tests. Patches by Louie Lu and Terry Jan Reedy.
  • bpo-30495: Add docstrings for textview.py and use PEP8 names. Patches by Cheryl Sabella and Terry Jan Reedy.
  • 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: Add _utest option to textview; add new tests. Increase coverage to 100%. Patches by Louie Lu and Terry Jan Reedy.

C API

  • bpo-27867: Function PySlice_GetIndicesEx() no longer replaced with a macro if Py_LIMITED_API is not set.

ビルド

  • bpo-29941: Add --with-assertions configure flag to explicitly enable C assert() checks. Defaults to off. --with-pydebug implies --with-assertions.
  • bpo-28787: Fix out-of-tree builds of Python when configured with --with--dtrace.
  • bpo-29243: Prevent unnecessary rebuilding of Python during make test, make install and some other make targets when configured with --enable-optimizations.
  • 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: Fix --enable-optimization didn't work.

ドキュメント

  • bpo-30176: Add missing attribute related constants in curses documentation.

  • 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: Add missing info of code object in inspect documentation.

Tools/Demos

  • bpo-29367: python-gdb.py now supports also method-wrapper (wrapperobject) objects.

テスト

  • 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: 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: Locate msbuild.exe on Windows when building rather than vcvarsall.bat
  • 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: The sys.path[0] initialization change for 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-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: Set correct __cause__ for errors about invalid awaitables returned from __aiter__ and __anext__.
  • bpo-29683: Fixes to memory allocation in _PyCode_SetExtra. Patch by Brian Coleman.
  • 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: Support __rmod__ for subclasses of str being called before str.__mod__. Patch by Martijn Pieters.
  • bpo-29607: Fix stack_effect computation for CALL_FUNCTION_EX. Patch by Matthieu Dartiailh.
  • 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: Fixed possibly dereferencing undefined pointers when creating weakref objects.
  • bpo-29438: Fixed use-after-free problem in key sharing dict.
  • bpo-29319: Prevent RunMainFromImporter overwriting sys.path[0].
  • bpo-29337: Fixed possible BytesWarning when compare the code objects. Warnings could be emitted at compile time.
  • bpo-29327: Fixed a crash when pass the iterable keyword argument to sorted().
  • bpo-29034: Fix memory leak and use-after-free in os module (path_converter).
  • bpo-29159: Fix regression in bytes(x) when x.__index__() raises Exception.
  • bpo-28932: Do not include <sys/random.h> if it does not exist.
  • bpo-25677: Correct the positioning of the syntax error caret for indented blocks. Based on patch by Michael Layzell.
  • bpo-29000: Fixed bytes formatting of octals with zero padding in alternate form.
  • 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: functools.lru_cache() was susceptible to an obscure reentrancy bug triggerable by a monkey-patched len() function.
  • 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: Fixed setting the offset attribute of SyntaxError by PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().
  • bpo-28918: Fix the cross compilation of xxlimited when Python has been built with Py_DEBUG defined.
  • bpo-28731: Optimize _PyDict_NewPresized() to create correct size dict. Improve speed of dict literal with constant keys up to 30%.

ライブラリ

  • bpo-29169: Update zlib to 1.2.11.
  • bpo-29623: Allow use of path-like object as a single argument in ConfigParser.read(). Patch by David Ellis.
  • bpo-28963: Fix out of bound iteration in asyncio.Future.remove_done_callback implemented in C.
  • bpo-29704: asyncio.subprocess.SubprocessStreamProtocol no longer closes before all pipes are closed.
  • bpo-29271: Fix Task.current_task and Task.all_tasks implemented in C to accept None argument as their pure Python implementation.
  • bpo-29703: Fix asyncio to support instantiation of new event loops in child processes.
  • bpo-29376: Fix assertion error in threading._DummyThread.is_alive().
  • bpo-28624: Add a test that checks that cwd parameter of Popen() accepts PathLike objects. Patch by Sayan Chowdhury.
  • bpo-28518: Start a transaction implicitly before a DML statement. Patch by Aviv Palivoda.
  • bpo-29532: Altering a kwarg dictionary passed to functools.partial() no longer affects a partial object after creation.
  • 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: 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: Fix datetime.fromtimestamp() regression introduced in Python 3.6.0: check minimum and maximum years.
  • bpo-29519: Fix weakref spewing exceptions during interpreter shutdown when used with a rare combination of multiprocessing and custom codecs.
  • bpo-29416: Prevent infinite loop in pathlib.Path.mkdir
  • bpo-29444: Fixed out-of-bounds buffer access in the group() method of the match object. Based on patch by WGH.
  • 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: Fix a regression in argparse that help messages would wrap at non-breaking spaces.
  • bpo-28735: Fixed the comparison of mock.MagickMock with mock.ANY.
  • bpo-29316: Restore the provisional status of typing module, add corresponding note to documentation. Patch by Ivan L.
  • bpo-29219: Fixed infinite recursion in the repr of uninitialized ctypes.CDLL instances.
  • bpo-29011: Fix an important omission by adding Deque to the typing module.
  • 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 differen threads with the same uncached arguments.
  • 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: Fix unittest.mock._Call helper: don't ignore the name parameter anymore. Patch written by Jiajun Huang.
  • bpo-29203: functools.lru_cache() now respects PEP 468 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: inspect.getframeinfo() now correctly shows the first line of a context. Patch by Sam Breese.
  • 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: Allow random.Random.seed() to use high quality OS randomness rather than the pid and time.
  • bpo-29061: Fixed bug in secrets.randbelow() which would hang when given a negative input. Patch by Brendan Donegan.
  • bpo-29079: Prevent infinite loop in pathlib.resolve() on Windows
  • bpo-13051: Fixed recursion errors in large or resized curses.textpad.Textbox. Based on patch by Tycho Andersen.
  • bpo-29119: Fix weakrefs in the pure python version of collections.OrderedDict move_to_end() method. Contributed by Andra Bogildea.
  • bpo-9770: curses.ascii predicates now work correctly with negative integers.
  • bpo-28427: old keys should not remove new values from WeakValueDictionary when collecting from another thread.
  • bpo-28923: Remove editor artifacts from Tix.py.
  • bpo-29055: Neaten-up empty population error on random.choice() by suppressing the upstream exception.
  • bpo-28871: Fixed a crash when deallocate deep ElementTree.
  • bpo-19542: Fix bugs in WeakValueDictionary.setdefault() and WeakValueDictionary.pop() when a GC collection happens in another thread.
  • bpo-20191: Fixed a crash in resource.prlimit() when passing a sequence that doesn't own its elements as limits.
  • bpo-28779: multiprocessing.set_forkserver_preload() would crash the forkserver process if a preloaded module instantiated some multiprocessing objects such as locks.
  • bpo-28847: dbm.dumb now supports reading read-only files and no longer writes the index file when it is not changed.
  • 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: IDLE colors f-string prefixes (but not invalid ur prefixes).
  • bpo-28572: Add 10% to coverage of IDLE's test_configdialog. Update and augment description of the configuration system.

Windows

  • bpo-29579: Removes readme.txt from the installer
  • bpo-29326: Ignores blank lines in ._pth files (Patch by Alexey Izbyshev)
  • bpo-28164: Correctly handle special console filenames (patch by Eryk Sun)
  • bpo-29409: Implement PEP 529 for io.FileIO (Patch by Eryk Sun)
  • bpo-29392: Prevent crash when passing invalid arguments into msvcrt module.
  • bpo-25778: winreg does not truncate string correctly (Patch by Eryk Sun)
  • bpo-28896: Deprecate WindowsRegistryFinder and disable it by default.

C API

  • 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: 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: 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-28929: Link the documentation to its source file on GitHub.
  • bpo-25008: Document smtpd.py as effectively deprecated and add a pointer to aiosmtpd, a third-party asyncio-based replacement.
  • bpo-26355: Add canonical header link on each page to corresponding major version of the documentation. Patch by Matthias Bussonnier.
  • bpo-29349: Fix Python 2 syntax in code for building the documentation.

テスト

  • 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: 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: Disallow -j0 to be combined with -T/-l in regrtest command line arguments.
  • bpo-28683: Fix the tests that bind() a unix socket and raise PermissionError on Android for a non-root user.
  • bpo-26939: Add the support.setswitchinterval() function to fix test_functools hanging on the Android armv7 qemu emulator.

ビルド

  • 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: Update Windows build and OS X installers to use OpenSSL 1.0.2k.
  • bpo-26851: Set Android compilation and link flags.
  • bpo-28768: Fix implicit declaration of function _setmode. Patch by Masayuki Yamamoto
  • bpo-29080: Removes hard dependency on hg.exe from PCBuild/build.bat
  • bpo-23903: Added missed names to PC/python3.def.
  • bpo-28762: lockf() is available on Android API level 24, but the F_LOCK macro is not defined in android-ndk-r13.
  • 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: 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: 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: Fix a memory leak in split-table dictionaries: setattr() must not convert combined table into split table. Patch written by INADA Naoki.
  • bpo-28990: Fix asyncio SSL hanging if connection is closed before handshake is completed. (Patch by HoHo-Ho)

Tools/Demos

  • bpo-28770: Fix python-gdb.py for fastcalls.

Windows

  • bpo-28896: Deprecate WindowsRegistryFinder.

ビルド

  • 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: 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: 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: Fix a bug in the implementation yield from when checking if the next instruction is YIELD_FROM. Regression introduced by WORDCODE (bpo-26647).

ライブラリ

  • 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: Fix a regression introduced in warnings.catch_warnings(): call warnings.showwarning() if it was overriden inside the context manager.
  • 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: 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: Reading a corrupt config file left configparser in an invalid state. Original patch by Florian Höch.
  • bpo-28843: Fix asyncio C Task to handle exceptions __traceback__.

C API

  • bpo-28808: PyUnicode_CompareWithASCIIString() now never raises exceptions.

ドキュメント

  • 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 and zero-argument super().

Tools/Demos

  • 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: Show sys.version when -V option is supplied twice.
  • 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: Fix the set_inheritable() file descriptor method on platforms that do not have the ioctl FIOCLEX and FIONCLEX commands.
  • bpo-26920: Fix not getting the locale's charset upon initializing the interpreter, on platforms that do not have langinfo.
  • bpo-28648: Fixed crash in Py_DecodeLocale() in debug build on Mac OS X when decode astral characters. Patch by Xiang Zhang.
  • bpo-19398: Extra slash no longer added to sys.path components in case of empty compile-time PYTHONPATH components.
  • bpo-28665: Improve speed of the STORE_DEREF opcode by 40%.
  • bpo-28583: PyDict_SetDefault didn't combine split table when needed. Patch by Xiang Zhang.
  • 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: Fix a refleak in code that raises DeprecationWarning.
  • bpo-28721: Fix asynchronous generators aclose() and athrow() to handle StopAsyncIteration propagation properly.

ライブラリ

  • bpo-28752: Restored the __reduce__() methods of datetime objects.
  • 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: don't duplicate warning filters when the warnings module is reloaded (thing usually only done in unit tests).
  • bpo-20572: The subprocess.Popen.wait method's undocumented endtime parameter now raises a DeprecationWarning.
  • bpo-25659: In ctypes, prevent a crash calling the from_buffer() and from_buffer_copy() methods on abstract classes like Array.
  • bpo-19717: Makes Path.resolve() succeed on paths that do not exist. Patch by Vajrasky Kok
  • 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: Fixed possible crash in _io.TextIOWrapper deallocator when the garbage collector is invoked in other thread. Based on patch by Sebastian Cufre.
  • bpo-28600: Optimize loop.call_soon.
  • bpo-28613: Fix get_event_loop() return the current loop if called from coroutines/callbacks.
  • bpo-28634: Fix asyncio.isfuture() to support unittest.Mock.
  • bpo-26081: Fix refleak in _asyncio.Future.__iter__().throw.
  • bpo-28639: Fix inspect.isawaitable to always return bool Patch by Justin Mayfield.
  • bpo-28652: Make loop methods reject socket kinds they do not support.
  • bpo-28653: Fix a refleak in functools.lru_cache.
  • bpo-28703: Fix asyncio.iscoroutinefunction to handle Mock objects.
  • bpo-28704: Fix create_unix_server to support Path-like objects (PEP 519).
  • bpo-28720: Add collections.abc.AsyncGenerator.

ドキュメント

  • bpo-28513: Documented command-line interface of zipfile.

テスト

  • bpo-28666: Now test.support.rmtree is able to remove unwritable or unreadable directories.
  • bpo-23839: Various caches now are cleared before running every test file.

ビルド

  • bpo-10656: Fix out-of-tree building on AIX. Patch by Tristan Carel and Michael Haubenwallner.
  • bpo-26359: Rename --with-optimiations to --enable-optimizations.
  • 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: 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: dict.update() no longer allocate unnecessary large memory.
  • bpo-28426: Fixed potential crash in PyUnicode_AsDecodedObject() in debug build.
  • bpo-28517: Fixed of-by-one error in the peephole optimizer that caused keeping unreachable code.
  • bpo-28214: Improved exception reporting for problematic __set_name__ attributes.
  • bpo-23782: Fixed possible memory leak in _PyTraceback_Add() and exception loss in PyTraceBack_Here().
  • bpo-28471: Fix "Python memory allocator called without holding the GIL" crash in socket.setblocking.

ライブラリ

  • bpo-27517: LZMA compressor and decompressor no longer raise exceptions if given empty data twice. Patch by Benjamin Fogle.
  • bpo-28549: Fixed segfault in curses's addch() with ncurses6.
  • 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: The webbrowser module now supports Firefox 36+ and derived browsers. Based on patch by Oleg Broytman.
  • 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: The various ways of specifying weights for random.choices() now produce the same result sequences.
  • 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: The textwrap.TextWrapper class now honors non-breaking spaces. Based on patch by Kaarle Ritvanen.
  • bpo-28353: os.fwalk() no longer fails on broken links.
  • bpo-28430: Fix iterator of C implemented asyncio.Future doesn't accept non-None value is passed to it.send(val).
  • bpo-27025: Generated names for Tkinter widgets now start by the "!" prefix for readability.
  • bpo-25464: Fixed HList.header_exists() in tkinter.tix module by addin a workaround to Tix library bug.
  • bpo-28488: shutil.make_archive() no longer adds entry "./" to ZIP archive.
  • 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: Optimize csv.DictWriter for large number of columns. Patch by Mariatta Wijaya.
  • bpo-28448: Fix C implemented asyncio.Future didn't work on Windows.
  • bpo-28480: Fix error building socket module when multithreading is disabled.
  • bpo-24452: Make webbrowser support Chrome on Mac OS X.
  • bpo-20766: Fix references leaked by pdb in the handling of SIGINT handlers.
  • bpo-28492: Fix how StopIteration exception is raised in _asyncio.Future.
  • bpo-28500: Fix asyncio to handle async gens GC from another thread.
  • bpo-26923: Fix asyncio.Gather to refuse being cancelled once all children are done. Patch by Johannes Ebke.
  • bpo-26796: Don't configure the number of workers for default threadpool executor. Initial patch by Hans Lawrenz.
  • bpo-28544: Implement asyncio.Task in C.

Windows

  • bpo-28522: Fixes mishandled buffer reallocation in getpathp.c

ビルド

  • bpo-28444: Fix missing extensions modules when cross compiling.
  • bpo-28208: Update Windows build and OS X installers to use SQLite 3.14.2.
  • bpo-28248: Update Windows build and OS X installers to use OpenSSL 1.0.2j.

テスト

  • bpo-26944: Fix test_posix for Android where 'id -G' is entirely wrong or missing the effective gid.
  • 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: Optimize and cleanup dict iteration.
  • bpo-26081: Added C implementation of asyncio.Future. Original patch by Yury Selivanov.
  • bpo-28379: Added sanity checks and tests for PyUnicode_CopyCharacters(). Patch by Xiang Zhang.
  • bpo-28376: The type of long range iterator is now registered as Iterator. Patch by Oren Milman.
  • bpo-28376: Creating instances of range_iterator by calling range_iterator type now is deprecated. Patch by Oren Milman.
  • bpo-28376: The constructor of range_iterator now checks that step is not 0. Patch by Oren Milman.
  • bpo-26906: Resolving special methods of uninitialized type now causes implicit initialization of the type instead of a fail.
  • bpo-18287: PyType_Ready() now checks that tp_name is not NULL. Original patch by Niklas Koep.
  • bpo-24098: Fixed possible crash when AST is changed in process of compiling it.
  • bpo-28201: Dict reduces possibility of 2nd conflict in hash table when hashes have same lower bits.
  • bpo-28350: String constants with null character no longer interned.
  • bpo-26617: Fix crash when GC runs during weakref callbacks.
  • bpo-27942: String constants now interned recursively in tuples and frozensets.
  • bpo-21578: Fixed misleading error message when ImportError called with invalid keyword args.
  • bpo-28203: Fix incorrect type in complex(1.0, {2:3}) error message. Patch by Soumya Sharma.
  • 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: Now __set_name__ is looked up on the class instead of the instance.
  • bpo-27955: Fallback on reading /dev/urandom device when the getrandom() syscall fails with EPERM, for example when blocked by SECCOMP.
  • bpo-28192: Don't import readline in isolated mode.
  • Upgrade internal unicode databases to Unicode version 9.0.0.
  • bpo-28131: Fix a regression in zipimport's compile_source(). zipimport should use the same optimization level as the interpreter.
  • bpo-28126: Replace Py_MEMCPY with memcpy(). Visual Studio can properly optimize memcpy().
  • 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: Raise DeprecationWarning when async and await keywords are used as variable/attribute/class/function name.

ライブラリ

  • bpo-27998: Fixed bytes path support in os.scandir() on Windows. Patch by Eryk Sun.

  • bpo-28317: The disassembler now decodes FORMAT_VALUE argument.

  • 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: unittest.mock Mock autospec functions now properly support assert_called, assert_not_called, and assert_called_once.

  • bpo-27181: remove statistics.geometric_mean and defer until 3.7.

  • bpo-28229: lzma module now supports pathlib.

  • bpo-28321: Fixed writing non-BMP characters with binary format in plistlib.

  • bpo-28225: bz2 module now supports pathlib. Initial patch by Ethan Furman.

  • bpo-28227: gzip now supports pathlib. Patch by Ethan Furman.

  • bpo-27358: Optimized merging var-keyword arguments and improved error message when passing a non-mapping as a var-keyword argument.

  • bpo-28257: Improved error message when passing a non-iterable as a var-positional argument. Added opcode BUILD_TUPLE_UNPACK_WITH_CALL.

  • bpo-28322: Fixed possible crashes when unpickle itertools objects from incorrect pickle data. Based on patch by John Leitch.

  • bpo-28228: imghdr now supports pathlib.

  • bpo-28226: compileall now supports pathlib.

  • bpo-28314: Fix function declaration (C flags) for the getiterator() method of xml.etree.ElementTree.Element.

  • 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: 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: Fixed possible use after free in the decompress() methods of the LZMADecompressor and BZ2Decompressor classes. Original patch by John Leitch.

  • 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: 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: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py. Patch by Madison May.

  • bpo-27611: Fixed support of default root window in the tkinter.tix module. Added the master parameter in the DisplayStyle constructor.

  • 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: Allow falsy values to be used for msg parameter of subTest().

  • 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: Fix memory leak on Windows in the os module (fix path_converter() function).

  • bpo-25400: RobotFileParser now correctly returns default values for crawl_delay and request_rate. Initial patch by Peter Wirtz.

  • bpo-27932: Prevent memory leak in win32_ver().

  • Fix UnboundLocalError in socket._sendfile_use_sendfile.

  • bpo-28075: Check for ERROR_ACCESS_DENIED in Windows implementation of os.stat(). Patch by Eryk Sun.

  • 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: Prevent codecs.escape_encode() from raising SystemError when an empty bytestring is passed.

  • bpo-28181: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

  • bpo-25895: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by Gergely Imreh and Markus Holtermann.

  • bpo-28114: Fix a crash in parse_envlist() when env contains byte strings. Patch by Eryk Sun.

  • bpo-27599: Fixed buffer overrun in binascii.b2a_qp() and binascii.a2b_qp().

  • bpo-27906: Fix socket accept exhaustion during high TCP traffic. Patch by Kevin Conway.

  • bpo-28174: Handle when SO_REUSEPORT isn't properly supported. Patch by Seth Michael Larson.

  • bpo-26654: Inspect functools.partial in asyncio.Handle.__repr__. Patch by iceboy.

  • bpo-26909: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

  • bpo-28176: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

  • bpo-27759: Fix selectors incorrectly retain invalid file descriptors. Patch by Mark Williams.

  • bpo-28368: Refuse monitoring processes if the child watcher has no loop attached. Patch by Vincent Michel.

  • bpo-28369: Raise RuntimeError when transport's FD is used with add_reader, add_writer, etc.

  • bpo-28370: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг Марк.

  • bpo-28371: Deprecate passing asyncio.Handles to run_in_executor.

  • bpo-28372: Fix asyncio to support formatting of non-python coroutines.

  • bpo-28399: Remove UNIX socket from FS before binding. Patch by Коренберг Марк.

  • bpo-27972: Prohibit Tasks to await on themselves.

Windows

  • bpo-28402: Adds signed catalog files for stdlib on Windows.
  • bpo-28333: Enables Unicode for ps1/ps2 and input() prompts. (Patch by Eryk Sun)
  • bpo-28251: Improvements to help manuals on Windows.
  • bpo-28110: launcher.msi has different product codes between 32-bit and 64-bit
  • bpo-28161: Opening CON for write access fails
  • bpo-28162: WindowsConsoleIO readall() fails if first line starts with Ctrl+Z
  • bpo-28163: WindowsConsoleIO fileno() passes wrong flags to _open_osfhandle
  • bpo-28164: _PyIO_get_console_type fails for various paths
  • bpo-28137: Renames Windows path file to ._pth
  • bpo-28138: Windows ._pth file should allow import site

C API

  • bpo-28426: Deprecated undocumented functions PyUnicode_AsEncodedObject(),
PyUnicode_AsDecodedObject(), PyUnicode_AsDecodedUnicode() and
PyUnicode_AsEncodedUnicode().

ビルド

  • bpo-28258: Fixed build with Estonian locale (python-config and distclean targets in Makefile). Patch by Arfrever Frehtes Taifersar Arahesis.
  • bpo-26661: setup.py now detects system libffi with multiarch wrapper.
  • bpo-15819: Remove redundant include search directory option for building outside the source tree.

テスト

  • 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: 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: Fix corrupted result from PyLong_FromLong(0) when Python is compiled with NSMALLPOSINTS = 0.
  • bpo-27080: Implement formatting support for PEP 515. Initial patch by Chris Angelico.
  • bpo-27199: In tarfile, expose copyfileobj bufsize to improve throughput. Patch by Jason Fried.
  • 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: Remove platform-specific directories from sys.path.
  • bpo-28071: Add early-out for differencing from an empty set.
  • bpo-25758: Prevents zipimport from unnecessarily encoding a filename (patch by Eryk Sun)
  • 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: 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: Implement tokenizing support for PEP 515. Patch by Georg Brandl.
  • bpo-27999: Make "global after use" a SyntaxError, and ditto for nonlocal. Patch by Ivan Levkivskyi.
  • bpo-28003: Implement PEP 525 -- Asynchronous Generators.
  • bpo-27985: Implement PEP 526 -- Syntax for Variable Annotations. Patch by Ivan Levkivskyi.
  • 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: A backslash-character pair that is not a valid escape sequence now generates a DeprecationWarning. Patch by Emanuel Barry.
  • 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: Remove unnecessary error checks in exec_builtin_or_dynamic().
  • bpo-27078: Added BUILD_STRING opcode. Optimized f-strings evaluation.
  • bpo-17884: Python now requires systems with inttypes.h and stdint.h
  • 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: Removed support for Windows CE. It was never finished, and Windows CE is no longer a relevant platform for Python.
  • Implement PEP 523.
  • bpo-27870: A left shift of zero by a large integer no longer attempts to allocate large amounts of memory.
  • 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: 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: Support passing the bytes/bytearray.translate() "delete" argument by keyword.
  • bpo-27812: Properly clear out a generator's frame's backreference to the generator to prevent crashes in frame.clear().
  • bpo-27811: Fix a crash when a coroutine that has not been awaited is finalized with warnings-as-errors enabled.
  • 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: 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: int() now always returns an instance of exact int.
  • 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: Make class definition namespace ordered by default.
  • 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: 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: 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: 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: Make only type() itself accept the one-argument form. Patch by Eryk Sun and Emanuel Barry.
  • 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: Implement PEP 530 -- asynchronous comprehensions.
  • bpo-27942: Fix memory leak in codeobject.c

ライブラリ

  • bpo-28732: Fix crash in os.spawnv() with no elements in args
  • bpo-28485: Always raise ValueError for negative compileall.compile_dir(workers=...) parameter, even when multithreading is unavailable.
  • bpo-28037: Use sqlite3_get_autocommit() instead of setting Connection->inTransaction manually.
  • 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: Regular expression match object groups are now accessible using __getitem__. "mo[x]" is equivalent to "mo.group(x)".
  • bpo-10740: sqlite3 no longer implicitly commit an open transaction before DDL statements.
  • bpo-17941: Add a module parameter to collections.namedtuple().
  • 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: xmlrpc now supports unmarshalling additional data types used by Apache XML-RPC implementation for numerics and None.
  • bpo-28070: Fixed parsing inline verbose flag in regular expressions.
  • bpo-19500: Add client-side SSL session resumption to the ssl module.
  • 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: 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: Changed some RuntimeError's in the zipfile module to more appropriate types. Improved some error messages and debugging output.
  • 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: 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: Fix the ability to pass the --link-objects option to the distutils build_ext command.
  • bpo-28019: itertools.count() no longer rounds non-integer step in range between 1.0 and 2.0 to 1.
  • 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: Update the lib2to3 grammar to handle the unpacking generalizations added in 3.5.
  • 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: Convert re flag constants to IntFlag.
  • bpo-28025: Convert all ssl module constants to IntEnum and IntFlags. SSLContext properties now return flags and enums.
  • bpo-23591: Add Flag, IntFlag, and auto() to enum module.
  • bpo-433028: Added support of modifier spans in regular expressions.
  • bpo-24594: Validates persist parameter when opening MSI database
  • bpo-17582: xml.etree.ElementTree nows preserves whitespaces in attributes (Patch by Duane Griffin. Reviewed and approved by Stefan Behnel.)
  • bpo-28047: Fixed calculation of line length used for the base64 CTE in the new email policies.
  • bpo-27576: Fix call order in OrderedDict.__init__().
  • email.generator.DecodedGenerator now supports the policy keyword.
  • bpo-28027: Remove undocumented modules from Lib/plat-*: IN, CDROM, DLFCN, TYPES, CDIO, and STROPTS.
  • bpo-27445: Don't pass str(_charset) to MIMEText.set_payload(). Patch by Claude Paroz.
  • 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: 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: Allow ImportErrors in encoding implementation to propagate.
  • bpo-26667: Support path-like objects in importlib.util.
  • bpo-27570: Avoid zero-length memcpy() etc calls with null source pointers in the "ctypes" and "array" modules.
  • 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: The email.mime classes now all accept an optional policy keyword.
  • bpo-27988: Fix email iter_attachments incorrect mutation of payload list.
  • bpo-16113: Add SHA-3 and SHAKE support to hashlib module.
  • Eliminate a tautological-pointer-compare warning in _scproxy.c.
  • 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.
  • bpo-27778: Expose the Linux getrandom() syscall as a new os.getrandom() function. This change is part of the PEP 524.
  • bpo-27691: Fix ssl module's parsing of GEN_RID subject alternative name fields in X.509 certs.
  • bpo-18844: Add random.choices().
  • 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: Add BLAKE2 (blake2b and blake2s) to hashlib.
  • bpo-26032: Optimized globbing in pathlib by using os.scandir(); it is now about 1.5--4 times faster.
  • bpo-25596: Optimized glob() and iglob() functions in the glob module; they are now about 3--6 times faster.
  • bpo-27928: Add scrypt (password-based key derivation function) to hashlib module (requires OpenSSL 1.1.0).
  • bpo-27850: Remove 3DES from ssl module's default cipher list to counter measure sweet32 attack (CVE-2016-2183).
  • bpo-27766: Add ChaCha20 Poly1305 to ssl module's default cipher list. (Required OpenSSL 1.1.0 or LibreSSL).
  • bpo-25387: Check return value of winsound.MessageBeep.
  • bpo-27866: Add SSLContext.get_ciphers() method to get a list of all enabled ciphers.
  • bpo-27744: Add AF_ALG (Linux Kernel crypto) to socket module.
  • bpo-26470: Port ssl and hashlib module to OpenSSL 1.1.0.
  • bpo-11620: Fix support for SND_MEMORY in winsound.PlaySound. Based on a patch by Tim Lesher.
  • bpo-11734: Add support for IEEE 754 half-precision floats to the struct module. Based on a patch by Eli Stevens.
  • bpo-27919: Deprecated extra_path distribution option in distutils packaging.
  • 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: 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: Fix error when distutils encounters symlink.
  • bpo-27881: Fixed possible bugs when setting sqlite3.Connection.isolation_level. Based on patch by Xiang Zhang.
  • bpo-27861: Fixed a crash in sqlite3.Connection.cursor() when a factory creates not a cursor. Patch by Xiang Zhang.
  • bpo-19884: Avoid spurious output on OS X with Gnu Readline.
  • 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: Fix a regression in Connection.commit(). Statements should not be reset after a commit.
  • 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) - 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: Make _normalize parameter to Fraction constuctor keyword-only, so that Fraction(2, 3, 4) now raises TypeError.
  • bpo-27539: Fix unnormalised Fraction.__pow__ result in the case of negative exponent and negative base.
  • bpo-21718: cursor.description is now available for queries using CTEs.
  • bpo-27819: In distutils sdists, simply produce the "gztar" (gzipped tar format) distributions on all platforms unless "formats" is supplied.
  • bpo-2466: posixpath.ismount now correctly recognizes mount points which the user does not have permission to access.
  • bpo-9998: On Linux, ctypes.util.find_library now looks in LD_LIBRARY_PATH for shared libraries.
  • bpo-27573: exit message for code.interact is now configurable.
  • bpo-27930: Improved behaviour of logging.handlers.QueueListener. Thanks to Paulo Andrade and Petr Viktorin for the analysis and patch.
  • bpo-6766: Distributed reference counting added to multiprocessing to support nesting of shared values / proxy objects.
  • bpo-21201: Improves readability of multiprocessing error message. Thanks to Wojciech Walczak for patch.
  • asyncio: Add set_protocol / get_protocol to Transports.
  • bpo-27456: asyncio: Set TCP_NODELAY by default.

IDLE

  • bpo-15308: Add 'interrupt execution' (^C) to Shell menu. Patch by Roger Serwy, updated by Bayard Randel.
  • bpo-27922: Stop IDLE tests from 'flashing' gui widgets on the screen.
  • bpo-27891: Consistently group and sort imports within idlelib modules.
  • bpo-17642: add larger font sizes for classroom projection.
  • Add version to title of IDLE help window.
  • bpo-25564: In section on IDLE -- console differences, mention that using exec means that __builtins__ is defined for each statement.
  • 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: Excluded underscored names and other private API from limited API.
  • bpo-26027: Add support for path-like objects in PyUnicode_FSConverter() & PyUnicode_FSDecoder().

テスト

  • bpo-27427: Additional tests for the math module. Patch by Francisco Couzo.
  • bpo-27953: Skip math and cmath tests that fail on OS X 10.4 due to a poor libm implementation of tan.
  • bpo-26040: Improve test_math and test_cmath coverage and rigour. Patch by Jeff Allen.
  • bpo-27787: Call gc.collect() before checking each test for "dangling threads", since the dangling threads are weak references.

ビルド

  • bpo-27566: Fix clean target in freeze makefile (patch by Lisa Roach)
  • bpo-27705: Update message in validate_ucrtbase.py
  • bpo-27976: Deprecate building _ctypes with the bundled copy of libffi on non-OSX UNIX platforms.
  • 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: Support for DTrace and SystemTap probes.
  • bpo-26307: The profile-opt build now applies PGO to the built-in modules.
  • bpo-26359: Add the --with-optimizations flag to turn on LTO and PGO build support when available.
  • bpo-27917: Set platform triplets for Android builds.
  • 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: Fix LTO builds on OS X.
  • 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: 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: Update xz dependency to 5.2.2 and build it from source.
  • bpo-25144: Ensures TargetDir is set before continuing with custom install.
  • bpo-1602: Windows console doesn't input or print Unicode (PEP 528)
  • bpo-27781: Change file system encoding on Windows to UTF-8 (PEP 529)
  • bpo-27731: Opt-out of MAX_PATH on Windows 10
  • bpo-6135: Adds encoding and errors parameters to subprocess.
  • bpo-27959: Adds oem encoding, alias ansi to mbcs, move aliasmbcs to codec lookup.
  • bpo-27982: The functions of the winsound module now accept keyword arguments.
  • bpo-20366: Build full text search support into SQLite on Windows.
  • bpo-27756: Adds new icons for Python files and processes on Windows. Designs by Cherry Wang.
  • 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: 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: 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: Decreased an overhead of parsing keyword arguments in functions implemented with using Argument Clinic.
  • bpo-22557: Now importing already imported modules is up to 2.5 times faster.
  • bpo-17596: Include <wincrypt.h> to help with Min GW building.
  • bpo-17599: On Windows, rename the privately defined REPARSE_DATA_BUFFER structure to avoid conflicting with the definition from Min GW.
  • bpo-27507: Add integer overflow check in bytearray.extend(). Patch by Xiang Zhang.
  • bpo-27581: Don't rely on wrapping for overflow check in PySequence_Tuple(). Patch by Xiang Zhang.
  • bpo-1621: Avoid signed integer overflow in list and tuple operations. Patch by Xiang Zhang.
  • 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: Respect the PYTHONCASEOK environment variable under Windows.
  • bpo-27514: Make having too many statically nested blocks a SyntaxError instead of SystemError.
  • bpo-27366: Implemented PEP 487 (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.

ライブラリ

  • bpo-26027: Add PEP 519/__fspath__() support to the os and os.path modules. Includes code from Jelle Zijlstra. (See also: bpo-27524)
  • bpo-27598: Add Collections to collections.abc. Patch by Ivan Levkivskyi, docs by Neil Girdhar.
  • 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: Support keyword arguments to zlib.decompress(). Patch by Xiang Zhang.
  • bpo-27736: Prevent segfault after interpreter re-initialization due to ref count problem introduced in code for bpo-27038 in 3.6.0a3. Patch by Xiang Zhang.
  • bpo-25628: The verbose and rename parameters for collections.namedtuple are now keyword-only.
  • bpo-12345: Add mathematical constant tau to math and cmath. See also PEP 628.
  • 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: Add to concurrent.futures.thread.ThreadPoolExecutor() the ability to specify a thread name prefix.
  • bpo-27181: Add geometric_mean and harmonic_mean to statistics module.
  • bpo-27573: code.interact now prints an message when exiting.
  • bpo-6422: Add autorange method to timeit.Timer objects.
  • bpo-27773: Correct some memory management errors server_hostname in _ssl.wrap_socket().
  • 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: Undocumented support of general bytes-like objects as path in compile() and similar functions is now deprecated.
  • bpo-26800: Undocumented support of general bytes-like objects as paths in os functions is now deprecated.
  • bpo-26981: Add _order_ compatibility shim to enum.Enum for Python 2/3 code bases.
  • 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: Fix possible usage of uninitialized memory in operator.methodcaller.
  • bpo-27774: Fix possible Py_DECREF on unowned object in _sre.
  • bpo-27760: Fix possible integer overflow in binascii.b2a_qp.
  • bpo-27758: Fix possible integer overflow in the _csv module for large record lengths.
  • bpo-27568: Prevent HTTPoxy attack (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: Remove dead code from the "array" module's slice handling. Patch by Chuck.
  • bpo-27656: Do not assume sched.h defines any SCHED_* constants.
  • 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: Implemented PEP 495 (Local Time Disambiguation).
  • Expose the EPOLLEXCLUSIVE constant (when it is defined) in the select module.
  • bpo-27567: Expose the EPOLLRDHUP and POLLRDHUP constants in the select module.
  • bpo-1621: Avoid signed int negation overflow in the "audioop" module.
  • bpo-27533: Release GIL in nt._isdir
  • bpo-17711: Fixed unpickling by the persistent ID with protocol 0. Original patch by Alexandre Vassalotti.
  • bpo-27522: Avoid an unintentional reference cycle in email.feedparser.
  • bpo-27512: Fix a segfault when os.fspath() called an __fspath__() method that raised an exception. Patch by Xiang Zhang.

IDLE

  • 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: 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: Escape key now closes Query box as cancelled.
  • bpo-27609: IDLE: tab after initial whitespace should tab, not autocomplete. This fixes problem with writing docstrings at least twice indented.
  • 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: 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: 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: add line counter and crc to IDLE configHandler test dump.

テスト

  • bpo-25805: Skip a test in test_pkgutil as needed that doesn't work when __name__ == __main__. Patch by SilentGhost.
  • bpo-27472: Add test.support.unix_shell as the path to the default shell.
  • bpo-27369: In test_pyexpat, avoid testing an error message detail that changed in Expat 2.2.0.
  • 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: Update bundled Tcl/Tk to 8.6.6.
  • bpo-27610: Adds PEP 514 metadata to Windows installer
  • bpo-27469: Adds a shell extension to the launcher so that drag and drop works correctly.
  • bpo-27309: Enables proper Windows styles in python[w].exe manifest.

ビルド

  • bpo-27713: Suppress spurious build warnings when updating importlib's bootstrap files. Patch by Xiang Zhang
  • 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: CPP invocation in configure must use CPPFLAGS. Patch by Chi Hsuan Yen.
  • 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: Set PYTHON_FOR_GEN in configure as the Python program to be used for file generation during the build.
  • 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

Core and Builtins

  • bpo-27473: Fixed possible integer overflow in bytes and bytearray concatenations. Patch by Xiang Zhang.
  • 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: __length_hint__() of bytearray iterators no longer return a negative integer for a resized bytearray.
  • bpo-27007: The fromhex() class methods of bytes and bytearray subclasses now return an instance of corresponding subclass.

ライブラリ

  • bpo-26844: Fix error message for imp.find_module() to refer to 'path' instead of 'name'. Patch by Lev Maximov.
  • bpo-23804: Fix SSL zero-length recv() calls to not block and not raise an error about unclean EOF.
  • bpo-27466: Change time format returned by http.cookie.time2netscape, confirming the netscape cookie format and making it consistent with documentation.
  • 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: Change the socketserver.StreamRequestHandler.wfile attribute to implement BufferedIOBase. In particular, the write() method no longer does partial writes.
  • 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: Only the level argument to zlib.compress() is keyword argument now. The first argument is positional-only.
  • bpo-27038: Expose the DirEntry type as os.DirEntry. Code patch by Jelle Zijlstra.
  • bpo-27186: Update os.fspath()/PyOS_FSPath() to check the return value of __fspath__() to be either str or bytes.
  • 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: 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: Fixed curses.ascii functions isblank(), iscntrl() and ispunct().
  • bpo-27294: Numerical state in the repr for Tkinter event objects is now represented as a combination of known flags.
  • 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: 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: socket.ioctl now supports SIO_LOOPBACK_FAST_PATH. Patch by Daniel Stokes.
  • bpo-27048: Prevents distutils failing on Windows when environment variables contain non-ASCII characters
  • bpo-27330: Fixed possible leaks in the ctypes module.
  • bpo-27238: Got rid of bare excepts in the turtle module. Original patch by Jelle Zijlstra.
  • 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 bug described in issue25782.

セキュリティ

  • 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-16864: sqlite3.Cursor.lastrowid now supports REPLACE statement. Initial patch by Alex LordThorsen.
  • bpo-26386: Fixed ttk.TreeView selection operations with item id's containing spaces.
  • bpo-8637: Honor a pager set by the env var MANPAGER (in preference to one set by the env var PAGER).

セキュリティ

  • bpo-22636: Avoid shell injection problems with ctypes.util.find_library().

ライブラリ

  • 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: Add loop.connect_accepted_socket(). Patch by Jim Fulton.

IDLE

  • bpo-27477: IDLE search dialogs now use ttk widgets.
  • 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: make command line "idle-test> python test_help.py" work. __file__ is relative when python is started in the file's directory.
  • bpo-27452: add line counter and crc to IDLE configHandler test dump.
  • 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: Test_idle no longer changes the locale.
  • bpo-27365: Allow non-ascii chars in IDLE NEWS.txt, for contributor names.
  • 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: 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: Fix IDLE.app failure to launch on OS X due to vestigial import.

C API

  • bpo-26754: PyUnicode_FSDecoder() accepted a filename argument encoded as an iterable of integers. Now only strings and byte-like objects are accepted.

ビルド

  • bpo-28066: Fix the logic that searches build directories for generated include files when building outside the source tree.
  • bpo-27442: Expose the Android API level that python was built against, in sysconfig.get_config_vars() as 'ANDROID_API_LEVEL'.
  • 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: Update Windows builds to use OpenSSL 1.0.2h.
  • 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: Fixed the type of the first argument of module-level functions generated by Argument Clinic. Patch by Petr Viktorin.
  • bpo-27418: Fixed Tools/importbench/importbench.py.

ドキュメント

  • bpo-19489: Moved the search box from the sidebar to the header and footer of each page. Patch by Ammar Askar.
  • bpo-27285: Update documentation to reflect the deprecation of pyvenv and normalize on the term "virtual environment". Patch by Steve Piercy.

テスト

  • 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

Core and Builtins

  • bpo-27095: Simplified MAKE_FUNCTION and removed MAKE_CLOSURE opcodes. Patch by Demur Rumed.
  • bpo-27190: Raise NotSupportedError if sqlite3 is older than 3.3.1. Patch by Dave Sawyer.
  • 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: Added BUILD_CONST_KEY_MAP opcode.
  • bpo-27186: Add support for os.PathLike objects to open() (part of PEP 519).
  • bpo-27066: Fixed SystemError if a custom opener (for open()) returns a negative number without setting an exception.
  • 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: Python interpreter is now about 7% faster due to optimized instruction decoding. Based on patch by Demur Rumed.
  • bpo-26647: Python interpreter now uses 16-bit wordcode instead of bytecode. Patch by Demur Rumed.
  • bpo-23275: Allow assigning to an empty target list in round brackets: () = iterable.
  • 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.

ライブラリ

  • 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: Generated names for Tkinter widgets are now more meaningful and recognizable.
  • bpo-25455: Fixed crashes in repr of recursive ElementTree.Element and functools.partial objects.
  • bpo-27294: Improved repr for Tkinter event objects.
  • bpo-20508: Improve exception message of IPv{4,6}Network.__getitem__. Patch by Gareth Rees.

セキュリティ

  • bpo-26556: Update expat to 2.1.1, fixes CVE-2015-1283.
  • Fix TLS stripping vulnerability in smtplib, CVE-2016-0772. Reported by Team Oststrom.

ライブラリ

  • bpo-21386: Implement missing IPv4Address.is_global property. It was documented since 07a5610bae9d. Initial patch by Roger Luethi.
  • bpo-27029: Removed deprecated support of universal newlines mode from ZipFile.open().
  • 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: Add os.PathLike support to DirEntry (part of PEP 519). Initial patch by Jelle Zijlstra.
  • bpo-20900: distutils register command now decodes HTTP responses correctly. Initial patch by ingrid.
  • bpo-27186: Add os.PathLike support to pathlib, removing its provisional status (part of PEP 519). Initial patch by Dusty Phillips.
  • bpo-27186: Add support for os.PathLike objects to os.fsencode() and os.fsdecode() (part of PEP 519).
  • bpo-27186: Introduce os.PathLike and os.fspath() (part of PEP 519).
  • 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 (Awaitable, AsyncIterable, AsyncIterator) have been added (in fact they made it into 3.5.1 but were never mentioned).
  • 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: Fix the "platform" module to tolerate when sys.version contains truncated build information.

セキュリティ

  • 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-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: In the zlib module, allow decompressing raw Deflate streams with a predefined zdict. Based on patch by Xiang Zhang.
  • 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: Use _sysconfigdata.py to initialize distutils.sysconfig.
  • 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: Add __all__ to string. Patch by Emanuel Barry.
  • 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: Clarify the subprocess.CalledProcessError error message text when the child process died due to a signal.
  • bpo-25931: Don't define socketserver.Forking* names on platforms such as Windows that do not support os.fork().
  • bpo-21776: distutils.upload now correctly handles HTTPError. Initial patch by Claudiu Popa.
  • bpo-26526: Replace custom parse tree validation in the parser module with a simple DFA validator.
  • bpo-27114: Fix SSLContext._load_windows_store_certs fails with PermissionError
  • bpo-18383: Avoid creating duplicate filters when using filterwarnings and simplefilter. Based on patch by Alex Shkop.
  • bpo-23026: winreg.QueryValueEx() now return an integer for REG_QWORD type.
  • bpo-26741: subprocess.Popen destructor now emits a ResourceWarning warning if the child process is still running.
  • bpo-27056: Optimize pickle.load() and pickle.loads(), up to 10% faster to deserialize a lot of small objects.
  • bpo-21271: New keyword only parameters in reset_mock call.

IDLE

  • 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: Switch all scrollbars in IDLE to ttk versions. Where needed, minimal tests are added to cover changes.
  • 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: idlelib.macosx.isXyzTk functions initialize as needed.
  • bpo-27262: move Aqua unbinding code, which enable context menus, to macosx.
  • 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: 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: Revise idle_test/README.txt with advice about avoiding tk warning messages from tests. Apply advice to several IDLE tests.
  • bpo-24225: Update idlelib/README.txt with new file names and event handlers.
  • bpo-27156: Remove obsolete code not used by IDLE.
  • bpo-27117: Make colorizer htest and turtledemo work with dark themes. Move code for configuring text widget colors to a new function.
  • 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: When tk reports font size as 0, change to size 10. Such fonts on Linux prevented the configuration dialog from opening.
  • bpo-21939: Add test for IDLE's percolator. Original patch by Saimadhav Heblikar.
  • bpo-21676: Add test for IDLE's replace dialog. Original patch by Saimadhav Heblikar.
  • bpo-18410: Add test for IDLE's search dialog. Original patch by Westley Martínez.
  • bpo-21703: Add test for undo delegator. Patch mostly by Saimadhav Heblikar .
  • bpo-27044: Add ConfigDialog.remove_var_callbacks to stop memory leaks.
  • bpo-23977: Add more asserts to test_delegator.

ドキュメント

  • 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: Document the new PEP 448 unpacking syntax of 3.5.
  • bpo-22558: Add remaining doc links to source code for Python-coded modules. Patch by Yoni Lavi.

テスト

  • 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: Tools/buildbot/test.bat script now uses -j1 by default to run each test file in fresh child process.

Windows

  • 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-27229: Fix the cross-compiling pgen rule for in-tree builds. Patch by Xavier de Gaye.
  • bpo-26930: Update OS X 10.5+ 32-bit-only installer to build and link with OpenSSL 1.0.2h.

Windows

  • bpo-17500: Remove unused and outdated icons. (See also: https://github.com/python/pythondotorg/issues/945)

C API

  • bpo-27186: Add the PyOS_FSPath() function (part of PEP 519).
  • bpo-26282: PyArg_ParseTupleAndKeywords() now supports positional-only parameters.

Tools/Demos

  • 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

Core and Builtins

  • bpo-20041: Fixed TypeError when frame.f_trace is set to None. Patch by Xavier de Gaye.
  • bpo-26168: Fixed possible refleaks in failing Py_BuildValue() with the "N" format unit.
  • bpo-26991: Fix possible refleak when creating a function with annotations.
  • bpo-27039: Fixed bytearray.remove() for values greater than 127. Based on patch by Joe Jevnik.
  • bpo-23640: int.from_bytes() no longer bypasses constructors for subclasses.
  • bpo-27005: Optimized the float.fromhex() class method for exact float. It is now 2 times faster.
  • 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: gc.get_objects() no longer contains a broken tuple with NULL pointer.
  • 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: 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: 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: Make the builtin slice type support cycle collection.
  • bpo-26718: super.__init__ no longer leaks memory if called multiple times. NOTE: A direct call of super.__init__ is not endorsed!
  • bpo-27138: Fix the doc comment for FileFinder.find_spec().
  • bpo-27147: Mention PEP 420 in the importlib docs.
  • bpo-25339: PYTHONIOENCODING now has priority over locale in setting the error handler for stdin and stdout.
  • 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: Optimize bytes.replace(b'', b'.') and bytearray.replace(b'', b'.'). Patch written by Josh Snider.
  • 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: Add tests for reloading namespace packages.
  • bpo-21099: Switch applicable importlib tests to use PEP 451 API.
  • 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: 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: The debug hooks on Python memory allocator PyObject_Malloc() now detect when functions are called without holding the GIL.
  • bpo-26516: Add PYTHONMALLOC environment variable to set the Python memory allocators and/or install debug hooks.
  • bpo-26516: The PyMem_SetupDebugHooks() function can now also be used on Python compiled in release mode.
  • 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: In debug mode, debug hooks are now also installed on Python memory allocators when Python is configured without pymalloc.
  • 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: 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: Correct behavior to reject comma as a legal character for cookie names.
  • bpo-26136: Upgrade the warning when a generator raises StopIteration from PendingDeprecationWarning to DeprecationWarning. Patch by Anish Shah.
  • 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: 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: 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: Sped-up allocation of dict key objects by using Python's small object allocator. (Contributed by Julian Taylor.)
  • bpo-18018: Import raises ImportError instead of SystemError if a relative import is attempted without a known parent package.
  • 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: The format of the co_lnotab attribute of code objects changes to support negative line number delta.
  • 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: If __package__ != __spec__.parent or if neither __package__ or __spec__ are defined then ImportWarning is raised.
  • bpo-22995: [UPDATE] Comment out the one of the pickleability tests in _PyObject_GetState() due to regressions observed in Cython-based projects.
  • bpo-25961: Disallowed null characters in the type name.
  • bpo-25973: Fix segfault when an invalid nonlocal statement binds a name starting with two underscores.
  • 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: Massive replacing unsafe attribute setting code with special macro Py_SETREF.
  • bpo-25766: Special method __bytes__() now works in str subclasses.
  • 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: Fixed problem with in-place string concatenation and utf-8 cache.
  • bpo-5319: New Py_FinalizeEx() API allowing Python to set an exit status of 120 on failure to flush buffered streams.
  • bpo-25485: telnetlib.Telnet is now a context manager.
  • bpo-24097: Fixed crash in object.__reduce__() if slot name is freed inside __getattr__.
  • 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: Fix a possible segfault during argument parsing in functions that accept filesystem paths.
  • 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: Fixed tokenizer crash when processing undecodable source code with a null byte.
  • bpo-25462: The hash of the key now is calculated only once in most operations in C implementation of OrderedDict.
  • bpo-22995: Default implementation of __reduce__ and __reduce_ex__ now rejects builtin types with not defined __new__.
  • 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: Fix parser and AST: fill lineno and col_offset of "arg" node when compiling AST from Python objects.
  • bpo-24726: Fixed a crash and leaking NULL in repr() of OrderedDict that was mutated by direct calls of dict methods.
  • bpo-25449: Iterating OrderedDict with keys with unstable hash now raises KeyError in C implementations as well as in Python implementation.
  • bpo-25395: Fixed crash when highly nested OrderedDict structures were garbage collected.
  • bpo-25401: Optimize bytes.fromhex() and bytearray.fromhex(): they are now between 2x and 3.5x faster.
  • bpo-25399: Optimize bytearray % args using the new private _PyBytesWriter API. Formatting is now between 2.5 and 5 times faster.
  • 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: Fix input() to prompt to the redirected stdout when sys.stdout.fileno() fails.
  • bpo-25349: Optimize bytes % args using the new private _PyBytesWriter API. Formatting is now up to 2 times faster.
  • bpo-24806: Prevent builtin types that are not allowed to be subclassed from being subclassed through multiple inheritance.
  • bpo-25301: The UTF-8 decoder is now up to 15 times as fast for error handlers: ignore, replace and surrogateescape.
  • bpo-24848: Fixed a number of bugs in UTF-7 decoding of misformed data.
  • 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: Import trace messages emitted in verbose (-v) mode are no longer formatted twice.
  • 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: 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: 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: Implement PEP 498 "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: Fix semantic bugs when using binary operators with dictionary views and tuples.
  • bpo-26171: Fix possible integer overflow and heap corruption in zipimporter.get_data().
  • bpo-25660: Fix TAB key behaviour in REPL with readline.
  • bpo-26288: Optimize PyLong_AsDouble.
  • 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)
  • bpo-25887: Raise a RuntimeError when a coroutine object is awaited more than once.

ライブラリ

  • 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: Fix infinite recursion using typing.py. Thanks to Kalle Tuure!

  • bpo-27031: Removed dummy methods in Tkinter widget classes: tk_menuBar() and tk_bindForTraversal().

  • bpo-14132: Fix urllib.request redirect handling when the target only has a query string. Original fix by Ján Janech.

  • 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: The default value of the decode_data parameter for smtpd.SMTPChannel and smtpd.SMTPServer constructors is changed to False.

  • bpo-27034: Removed deprecated class asynchat.fifo.

  • 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: 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: Honor debuglevel flag in urllib.request.HTTPHandler. Patch contributed by Chi Hsuan Yen.

  • 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: mock_open 'files' no longer error on readline at end of file. Patch from Yolanda Robla.

  • bpo-25745: Fixed leaking a userptr in curses panel destructor.

  • bpo-26977: Removed unnecessary, and ignored, call to sum of squares helper in statistics.pvariance.

  • bpo-26002: Use bisect in statistics.median instead of a linear search. Patch by Upendra Kuma.

  • bpo-25974: Make use of new Decimal.as_integer_ratio() method in statistics module. Patch by Stefan Krah.

  • bpo-26996: Add secrets module as described in PEP 506.

  • bpo-26881: The modulefinder module now supports extended opcode arguments.

  • bpo-23815: Fixed crashes related to directly created instances of types in _tkinter and curses.panel modules.

  • bpo-17765: weakref.ref() no longer silently ignores keyword arguments. Patch by Georg Brandl.

  • bpo-26873: xmlrpc now raises ResponseError on unsupported type tags instead of silently return incorrect result.

  • 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: Fixed the comparison of plistlib.Data with other types.

  • 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: 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: Print server URL on http.server startup. Initial patch by Felix Kaiser.

  • bpo-25788: fileinput.hook_encoded() now supports an "errors" argument for passing to open. Original patch by Joseph Hackman.

  • bpo-26634: recursive_repr() now sets __qualname__ of wrapper. Patch by Xiang Zhang.

  • 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: assertSequenceEqual() now correctly outputs non-stringified differing items (like bytes in the -b mode). This affects assertListEqual() and assertTupleEqual().

  • 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: itemgetter, attrgetter and methodcaller objects no longer silently ignore keyword arguments.

  • bpo-26733: Disassembling a class now disassembles class and static methods. Patch by Xiang Zhang.

  • bpo-26801: Fix error handling in shutil.get_terminal_size(), catch AttributeError instead of NameError. Patch written by Emanuel Barry.

  • bpo-24838: tarfile's ustar and gnu formats now correctly calculate name and link field limits for multibyte character encodings like utf-8.

セキュリティ

  • 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-26717: Stop encoding Latin-1-ized WSGI paths with UTF-8. Patch by Anthony Sottile.
  • bpo-26782: Add STARTUPINFO to subprocess.__all__ on Windows.
  • bpo-26404: Add context manager to socketserver. Patch by Aviv Palivoda.
  • 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: Eliminate http.server._quote_html() and use html.escape(quote=False). Patch by Xiang Zhang.
  • bpo-26685: Raise OSError if closing a socket fails.
  • bpo-16329: Add .webm to mimetypes.types_map. Patch by Giampaolo Rodola'.
  • bpo-13952: Add .csv to mimetypes.types_map. Patch by Geoff Wilson.
  • bpo-26587: the site module now allows .pth files to specify files to be added to sys.path (e.g. zip files).
  • bpo-25609: Introduce contextlib.AbstractContextManager and typing.ContextManager.
  • bpo-26709: Fixed Y2038 problem in loading binary PLists.
  • bpo-23735: Handle terminal resizing with Readline 6.3+ by installing our own SIGWINCH handler. Patch by Eric Price.
  • bpo-25951: Change SSLSocket.sendall() to return None, as explicitly documented for plain socket objects. Patch by Aviv Palivoda.
  • 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: Added missing XMLPullParser to ElementTree.__all__.
  • bpo-22854: Change BufferedReader.writable() and BufferedWriter.readable() to always return False.
  • 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: doctest.DocFileTest and doctest.testfile() now support packages (module splitted into multiple directories) for the package parameter.
  • 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: Raise ValueError rather than SystemError when a negative length is passed to SSLSocket.recv() or read().
  • bpo-23804: Fix SSL recv(0) and read(0) methods to return zero bytes instead of up to 1024.
  • bpo-26616: Fixed a bug in datetime.astimezone() method.
  • 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: 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: 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: 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: The _tracemalloc now supports tracing memory allocations of multiple address spaces (domains).
  • bpo-24266: Ctrl+C during Readline history search now cancels the search mode when compiled with Readline 7.
  • bpo-26590: Implement a safe finalizer for the _socket.socket type. It now releases the GIL to close the socket.
  • bpo-18787: spwd.getspnam() now raises a PermissionError if the user doesn't have privileges.
  • bpo-26560: Avoid potential ValueError in BaseHandler.start_response. Initial patch by Peter Inglesby.
  • 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-26313: ssl.py _load_windows_store_certs fails if windows cert store is empty. Patch by Baji.

ライブラリ

  • bpo-26569: Fix pyclbr.readmodule() and pyclbr.readmodule_ex() to support importing packages.
  • 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: Handle sockets in directories unittest discovery is scanning. Patch from Victor van den Elzen.
  • bpo-16181: cookiejar.http2time() now returns None if year is higher than datetime.MAXYEAR.
  • bpo-26513: Fixes platform module detection of Windows Server
  • bpo-23718: Fixed parsing time in week 0 before Jan 1. Original patch by Tamás Bence Gedai.
  • bpo-26323: Add Mock.assert_called() and Mock.assert_called_once() methods to unittest.mock. Patch written by Amit Saha.
  • bpo-20589: Invoking Path.owner() and Path.group() on Windows now raise NotImplementedError instead of ImportError.
  • bpo-26177: Fixed the keys() method for Canvas and Scrollbar widgets.
  • bpo-15068: Got rid of excessive buffering in fileinput. The bufsize parameter is now deprecated and ignored.
  • bpo-19475: Added an optional argument timespec to the datetime isoformat() method to choose the precision of the time component.
  • bpo-2202: Fix UnboundLocalError in AbstractDigestAuthHandler.get_algorithm_impls. Initial patch by Mathieu Dupuy.
  • bpo-26167: Minimized overhead in copy.copy() and copy.deepcopy(). Optimized copying and deepcopying bytearrays, NotImplemented, slices, short lists, tuples, dicts, sets.
  • bpo-25718: Fixed pickling and copying the accumulate() iterator with total is None.
  • bpo-26475: Fixed debugging output for regular expressions with the (?x) flag.
  • bpo-26482: Allowed pickling recursive dequeues.
  • bpo-26335: Make mmap.write() return the number of bytes written like other write methods. Patch by Jakub Stasiak.
  • 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: Remove the file if the internal open() call in NamedTemporaryFile() fails. Patch by Silent Ghost.
  • 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: Leading <~ is optional now in base64.a85decode() with adobe=True. Patch by Swati Jaiswal.
  • bpo-26186: Remove an invalid type check in importlib.util.LazyLoader.
  • bpo-26367: importlib.__import__() raises ImportError like builtins.__import__() when level is specified but without an accompanying package specified.
  • 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: 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-25939: On Windows open the cert store readonly in ssl.enum_certificates.

ライブラリ

  • bpo-25995: os.walk() no longer uses FDs proportional to the tree depth.
  • bpo-25994: Added the close() method and the support of the context manager protocol for the os.scandir() iterator.
  • bpo-23992: multiprocessing: make MapResult not fail-fast upon exception.
  • bpo-26243: Support keyword arguments to zlib.compress(). Patch by Aviv Palivoda.
  • 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: __dict__ for an OrderedDict instance is now created only when needed.
  • bpo-25911: Restored support of bytes paths in os.walk() on Windows.
  • bpo-26045: Add UTF-8 suggestion to error message when posting a non-Latin-1 string with http.client.
  • bpo-26039: Added zipfile.ZipInfo.from_file() and zipinfo.ZipInfo.is_dir(). Patch by Thomas Kluyver.
  • bpo-12923: Reset FancyURLopener's redirect counter even if there is an exception. Based on patches by Brian Brazil and Daniel Rocco.
  • 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: copy.deepcopy() now correctly copies range() objects with non-atomic attributes.
  • bpo-23076: Path.glob() now raises a ValueError if it's called with an invalid pattern. Patch by Thomas Nyberg.
  • bpo-19883: Fixed possible integer overflows in zipimport.
  • 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: 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: xmlrpc now works with strings not encodable with used non-UTF-8 encoding.
  • bpo-25935: Garbage collector now breaks reference loops with OrderedDict.
  • bpo-16620: Fixed AttributeError in msilib.Directory.glob().
  • bpo-26013: Added compatibility with broken protocol 2 pickles created in old Python 3 versions (3.4.3 and lower).
  • bpo-26129: Deprecated accepting non-integers in grp.getgrgid().
  • bpo-25850: Use cross-compilation by default for 64-bit Windows.
  • bpo-25822: Add docstrings to the fields of urllib.parse results. Patch contributed by Swati Jaiswal.
  • bpo-22642: Convert trace module option parsing mechanism to argparse. Patch contributed by SilentGhost.
  • bpo-24705: Fix sysconfig._parse_makefile not expanding ${} vars appearing before $() vars.
  • bpo-26069: Remove the deprecated apis in the trace module.
  • bpo-22138: Fix mock.patch behavior when patching descriptors. Restore original values after patching. Patch contributed by Sean McCully.
  • bpo-25672: In the ssl module, enable the SSL_MODE_RELEASE_BUFFERS mode option if it is safe to do so.
  • bpo-26012: Don't traverse into symlinks for ** pattern in pathlib.Path.[r]glob().
  • bpo-24120: Ignore PermissionError when traversing a tree with pathlib.Path.[r]glob(). Patch by Ulrich Petri.
  • 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: fileinput now uses sys.stdin as-is if it does not have a buffer attribute (restores backward compatibility).
  • bpo-25971: Optimized creating Fractions from floats by 2 times and from Decimals by 3 times.
  • bpo-25802: Document as deprecated the remaining implementations of importlib.abc.Loader.load_module().
  • bpo-25928: Add Decimal.as_integer_ratio().
  • 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: Have the functions in compileall return booleans instead of ints and add proper documentation and tests for the return values.
  • bpo-24103: Fixed possible use after free in ElementTree.XMLPullParser.
  • bpo-25860: os.fwalk() no longer skips remaining directories when error occurs. Original patch by Samson Lee.
  • bpo-25914: Fixed and simplified OrderedDict.__sizeof__.
  • bpo-25869: Optimized deepcopying ElementTree; it is now 20 times faster.
  • 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: Fixed various refcount issues in ElementTree iteration.
  • bpo-22227: The TarFile iterator is reimplemented using generator. This implementation is simpler that using class.
  • bpo-25638: Optimized ElementTree.iterparse(); it is now 2x faster. Optimized ElementTree parsing; it is now 10% faster.
  • bpo-25761: Improved detecting errors in broken pickle data.
  • 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: 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: In the subprocess module, preserve any exception caused by fork() failure when preexec_fn is used.
  • bpo-25771: Tweak the exception message for importlib.util.resolve_name() when 'package' isn't specified but necessary.
  • bpo-6478: _strptime's regexp cache now is reset after changing timezone with time.tzset().
  • 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: 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: 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: Fixed copying object with state with boolean value is false.
  • bpo-10131: Fixed deep copying of minidom documents. Based on patch by Marian Ganisin.
  • bpo-7990: dir() on ElementTree.Element now lists properties: "tag", "text", "tail" and "attrib". Original patch by Santoso Wijaya.
  • bpo-25725: Fixed a reference leak in pickle.loads() when unpickling invalid data including tuple instructions.
  • bpo-25663: In the Readline completer, avoid listing duplicate global names, and search the global namespace before searching builtins.
  • bpo-25688: Fixed file leak in ElementTree.iterparse() raising an error.
  • bpo-23914: Fixed SystemError raised by unpickler on broken pickle data.
  • bpo-25691: Fixed crash on deleting ElementTree.Element attributes.
  • bpo-25624: ZipFile now always writes a ZIP_STORED header for directory entries. Patch by Dingyuan Wang.
  • 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: Avoid incorrect errors raised by os.makedirs(exist_ok=True) when the OS gives priority to errors such as EACCES over EEXIST.
  • bpo-25593: Change semantics of EventLoop.stop() in asyncio.
  • 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: 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: 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: 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: Added "escape" to the __all__ list in the glob module.
  • bpo-25584: Fixed recursive glob() with patterns starting with **.
  • bpo-25446: Fix regression in smtplib's AUTH LOGIN support.
  • bpo-18010: Fix the pydoc web server's module search function to handle exceptions from importing packages.
  • bpo-25554: Got rid of circular references in regular expression parsing.
  • bpo-18973: Command-line interface of the calendar module now uses argparse instead of optparse.
  • 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: Fixed inspect.getdoc() for inherited docstrings of properties. Original patch by John Mark Vandenberg.
  • bpo-25515: Always use os.urandom as a source of randomness in uuid.uuid4.
  • 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: The lru_cache() wrapper objects now can be copied and pickled (by returning the original object unchanged).
  • bpo-25390: typing: Don't crash on Union[str, Pattern].
  • bpo-25441: asyncio: Raise error from drain() when socket is closed.
  • bpo-25410: Cleaned up and fixed minor bugs in C implementation of OrderedDict.
  • 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: Remove mentions of the formatter module being removed in Python 3.6.
  • 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: pickletools.dis() now outputs implicit memo index for the MEMOIZE opcode.
  • bpo-25357: Add an optional newline parameter to binascii.b2a_base64(). base64.b64encode() uses it to avoid a memory copy.
  • bpo-24164: Objects that need calling __new__ with keyword arguments, can now be pickled using pickle protocols older than protocol version 4.
  • bpo-25364: zipfile now works in threads disabled builds.
  • bpo-25328: smtpd's SMTPChannel now correctly raises a ValueError if both decode_data and enable_SMTPUTF8 are set to true.
  • bpo-16099: RobotFileParser now supports Crawl-delay and Request-rate extensions. Patch by Nikolay Bogoychev.
  • bpo-25316: distutils raises OSError instead of DistutilsPlatformError when MSVC is not installed.
  • bpo-25380: Fixed protocol for the STACK_GLOBAL opcode in pickletools.opcodes.
  • 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: 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: Fix CGIRequestHandler to split the query from the URL at the first question mark (?) rather than the last. Patch from Xiang Zhang.
  • 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: 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: Default implementation of tzinfo.fromutc() was returning wrong results in some cases.
  • bpo-25203: Failed readline.set_completer_delims() no longer left the module in inconsistent state.
  • bpo-25011: rlcompleter now omits private and special attribute names unless the prefix starts with underscores.
  • bpo-25209: rlcompleter now can add a space or a colon after completed keyword.
  • bpo-22241: timezone.utc name is now plain 'UTC', not 'UTC-00:00'.
  • 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: Timeit now warns when there is substantial (4x) variance between best and worst times. Patch from Serhiy Storchaka.
  • bpo-24633: site-packages/README -> README.txt.
  • 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: 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: urllib.parse raises ValueError on all invalid ports. Patch by Martin Panter.
  • bpo-24360: Improve __repr__ of argparse.Namespace() for invalid identifiers. Patch by Matthias Bussonnier.
  • bpo-23426: run_setup was broken in distutils. Patch from Alexander Belopolsky.
  • bpo-13938: 2to3 converts StringTypes to a tuple. Patch from Mark Hammond.
  • 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: improved tests for zipimporter2. Patch from Mark Lawrence.
  • bpo-18622: unittest.mock.mock_open().reset_mock would recurse infinitely. Patch from Nicola Palumbo and Laurent De Buyst.
  • 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: unittest.mock side_effects can now be exceptions again. This was a regression vs Python 3.4. Patch from Ignacio Rossi
  • bpo-13248: Remove deprecated inspect.getmoduleinfo function.
  • bpo-25578: Fix (another) memory leak in SSLSocket.getpeercer().
  • bpo-25530: Disable the vulnerable SSLv3 protocol by default when creating ssl.SSLContext.
  • bpo-25569: Fix memory leak in SSLSocket.getpeercert().
  • bpo-25471: Sockets returned from accept() shouldn't appear to be nonblocking.
  • 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: Add asyncio.StreamReader.readuntil() method. Patch by Марк Коренберг.
  • 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: Avoid unnecessary serialization of getaddrinfo(3) calls on current versions of OpenBSD and NetBSD. Patch by A. Jesse Jiryu Davis.
  • bpo-26848: Fix asyncio/subprocess.communicate() to handle empty input. Patch by Jack O'Connor.
  • bpo-27040: Add loop.get_exception_handler method
  • bpo-27041: asyncio: Add loop.create_future method

IDLE

  • 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: fix incorrect change in IOBinding that prevented printing. Augment IOBinding htest to include all major IOBinding functions.
  • 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: 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: 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: Improve the appearance of the IDLE editor window status bar. Patch by Mark Roseman.
  • 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: 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: Re-activate the config dialog help button with some content about the other buttons and the new IDLE Dark theme.
  • 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: 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: Users can now set breakpoint colors in Settings -> Custom Highlighting. Original patch by Mark Roseman.
  • 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: Idle: make calltip and completion boxes appear on Macs affected by a tk regression. Initial patch by Mark Roseman.
  • bpo-24988: Idle ScrolledList context menus (used in debugger) now work on Mac Aqua. Patch by Mark Roseman.
  • bpo-24801: Make right-click for context menu work on Mac Aqua. Patch by Mark Roseman.
  • bpo-25173: Associate tkinter messageboxes with a specific widget. For Mac OSX, make them a 'sheet'. Patch by Mark Roseman.
  • 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: Condense and rewrite Idle doc section on text colors.
  • bpo-21995: Explain some differences between IDLE and console Python.
  • bpo-22820: Explain need for print when running file from Idle editor.
  • bpo-25224: Doc: augment Idle feature list and no-subprocess section.
  • bpo-25219: Update doc for Idle command line options. Some were missing and notes were not correct.
  • bpo-24861: Most of idlelib is private and subject to change. Use idleib.idle.* to start Idle. See idlelib.__init__.__doc__.
  • bpo-25199: Idle: add synchronization comments for future maintainers.
  • 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: Deprecate unused idlelib.idlever with possible removal in 3.6.
  • bpo-24790: Remove extraneous code (which also create 2 & 3 conflicts).

ドキュメント

  • bpo-26736: Used HTTPS for external links in the documentation if possible.
  • 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: Adds note to ctypes documentation regarding cdll.msvcrt.
  • bpo-24952: Clarify the default size argument of stack_size() in the "threading" and "_thread" modules. Patch from Mattip.
  • 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

テスト

  • bpo-21916: Added tests for the turtle module. Patch by ingrid, Gregory Loyse and Jelle Zijlstra.
  • bpo-26295: When using "python3 -m test --testdir=TESTDIR", regrtest doesn't add "test." prefix to test module names.
  • bpo-26523: The multiprocessing thread pool (multiprocessing.dummy.Pool) was untested.
  • bpo-26015: Added new tests for pickling iterators of mutable sequences.
  • bpo-26325: Added test.support.check_no_resource_warning() to check that no ResourceWarning is emitted.
  • 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: Tests for OrderedDict are extracted from test_collections into separate file test_ordered_dict.
  • bpo-25449: Added tests for OrderedDict subclasses.
  • 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: Add python -m test --list-tests command to list tests.
  • bpo-18174: python -m test --huntrleaks ... now also checks for leak of file descriptors. Patch written by Richard Oudkerk.
  • 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: Skip test_timestamp_overflow in test_import if bytecode files cannot be written.

ビルド

  • bpo-21277: Don't try to link _ctypes with a ffi_convenience library.
  • bpo-26884: Fix linking extension modules for cross builds. Patch by Xavier de Gaye.
  • 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: 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: Link audioop, _datetime, _ctypes_test modules to libm, except on Mac OS X. Patch written by Chi Hsuan Yen.
  • 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: Adds validation of ucrtbase[d].dll version with warning for old versions.
  • bpo-17603: Avoid error about nonexistant fileblocks.o file by using a lower-level check for st_blocks in struct stat.
  • bpo-26079: Fixing the build output folder for tix-8.4.3.6. Patch by Bjoern Thiel.
  • bpo-26465: Update Windows builds to use OpenSSL 1.0.2g.
  • 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: Add support for building with ICC to configure, including a new --with-icc flag.
  • bpo-25696: Fix installation of Python on UNIX with make -j9.
  • bpo-24986: It is now possible to build Python on Windows without errors when external libraries are not available.
  • 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: Update OS X 10.5+ 32-bit-only installer to build and link with OpenSSL 1.0.2g.
  • bpo-26268: Update Windows builds to use OpenSSL 1.0.2f.
  • bpo-25136: Support Apple Xcode 7's new textual SDK stub libraries.
  • 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: Updates make_zip.py to correctly generate library ZIP file.
  • 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: bdist_wininst created binaries fail to start and find 32bit Python
  • bpo-26073: Update the list of magic numbers in launcher
  • bpo-26065: Excludes venv from library when generating embeddable distro.
  • bpo-25022: Removed very outdated PC/example_nt/ directory.

Tools/Demos

  • 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: Fix the Freeze tool to properly use flags passed through configure. Patch by Daniel Shaulov.
  • bpo-26489: Add dictionary unpacking support to Tools/parser/unparse.py. Patch by Guo Ci Teo.
  • bpo-26316: Fix variable name typo in Argument Clinic.
  • bpo-25440: Fix output of python-config --extension-suffix.
  • bpo-25154: The pyvenv script has been deprecated in favour of python3 -m venv.

C API

  • bpo-26312: SystemError is now raised in all programming bugs with using PyArg_ParseTupleAndKeywords(). RuntimeError did raised before in some programming bugs.
  • 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

セキュリティ

  • bpo-32551: The sys.path[0] initialization change for 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 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: Fixed possible integer overflow in PyBytes_DecodeEscape, CVE-2017-1000158. Original patch by Jay Bosamiya; rebased to Python 3 by Miro Hrončok.

  • bpo-30947: Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to get security fixes.

Core and Builtins

  • bpo-31095: Fix potential crash during GC caused by tp_dealloc which doesn't call PyObject_GC_UnTrack().

ライブラリ

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

ライブラリ

  • bpo-30119: ftplib.FTP.putline() now throws ValueError on commands that contains CR or LF. Patch by Dong-hee Na.

Python 3.5.4 release candidate 1

Release date: 2017-07-23

セキュリティ

  • bpo-30730: Prevent environment variables injection in subprocess on Windows. Prevent passing other environment variables and command arguments.
  • bpo-30694: Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple security vulnerabilities including: CVE-2017-9233 (External entity infinite loop DoS), CVE-2016-9063 (Integer overflow, re-fix), CVE-2016-0718 (Fix regression bugs from 2.2.0's fix to CVE-2016-0718) and CVE-2012-0876 (Counter hash flooding with SipHash). Note: the 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: 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: Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 and CVE-2016-4472. See https://sourceforge.net/p/expat/bugs/537/ for more information.

Core and Builtins

  • 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: Avoid blocking in pthread_mutex_lock() when PyThread_acquire_lock() is asked not to block.
  • 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: Fixed type.__setattr__() and type.__delattr__() for non-interned attribute names. Based on patch by Eryk Sun.
  • bpo-29935: Fixed error messages in the index() method of tuple, list and deque when pass indices of wrong type.
  • bpo-28876: bool(range) works even if len(range) raises OverflowError.
  • bpo-29600: Fix wrapping coroutine return values in StopIteration.
  • 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: Support __rmod__ for subclasses of str being called before str.__mod__. Patch by Martijn Pieters.
  • 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: Fixed possibly dereferencing undefined pointers when creating weakref objects.
  • bpo-29438: Fixed use-after-free problem in key sharing dict.
  • bpo-29319: Prevent RunMainFromImporter overwriting sys.path[0].
  • bpo-29337: Fixed possible BytesWarning when compare the code objects. Warnings could be emitted at compile time.
  • bpo-29478: If max_line_length=None is specified while using the Compat32 policy, it is no longer ignored. Patch by Mircea Cosbuc.

ライブラリ

  • bpo-29403: Fix unittest.mock's autospec to not fail on method-bound builtin functions. Patch by Aaron Gallagher.

  • bpo-30961: Fix decrementing a borrowed reference in tracemalloc.

  • 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: Fix segfault in readline when using readline's history-size option. Patch by Nir Soffer.

  • 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: Fix bug when modifying os.environ while iterating over it

  • bpo-30532: Fix email header value parser dropping folding white space in certain cases.

  • bpo-29169: Update zlib to 1.2.11.

  • bpo-30879: os.listdir() and os.scandir() now emit bytes names when called with bytes-like argument.

  • bpo-30746: Prohibited the '=' character in environment variable names in os.putenv() and os.spawn*().

  • bpo-29755: Fixed the lgettext() family of functions in the gettext module. They now always return bytes.

  • 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: unittest.TestCase.assertRaises() now manually breaks a reference cycle to not keep objects alive longer than expected.

  • bpo-30149: inspect.signature() now supports callables with variable-argument parameters wrapped with partialmethod. Patch by Dong-hee Na.

  • bpo-29931: Fixed comparison check for ipaddress.ip_interface objects. Patch by Sanjay Sundaresan.

  • bpo-24484: Avoid race condition in multiprocessing cleanup.

  • bpo-28994: The traceback no longer displayed for SystemExit raised in a callback registered by atexit.

  • bpo-30508: Don't log exceptions if Task/Future "cancel()" method was called.

  • 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: Fix ssl sockets leaks when connection is aborted in asyncio/ssl implementation. Patch by Michaël Sghaïer.

  • bpo-29743: Closing transport during handshake process leaks open socket. Patch by Nikolay Kim

  • bpo-27585: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu Sornay.

  • 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: Fix the problem that logging.handlers.SysLogHandler cannot handle IPv6 addresses.

  • bpo-29960: Preserve generator state when _random.Random.setstate() raises an exception. Patch by Bryan Olson.

  • bpo-30414: multiprocessing.Queue._feed background running thread do not break from main loop on exception.

  • bpo-30003: Fix handling escape characters in HZ codec. Based on patch by Ma Lin.

  • bpo-30301: Fix AttributeError when using SimpleQueue.empty() under spawn and forkserver start methods.

  • 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: 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: Fixed Task.cancel() can be ignored when the task is running coroutine and the coroutine returned without any more await.

  • bpo-29990: Fix range checking in GB18030 decoder. Original patch by Ma Lin.

  • bpo-26293: Change resulted because of zipfile breakage. (See also: bpo-29094)

  • 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: Avoid KeyboardInterrupt tracebacks in forkserver helper process when Ctrl-C is received.

  • 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: Fix getsockname() for unbound AF_UNIX sockets on Linux.

  • bpo-30070: Fixed leaks and crashes in errors handling in the parser module.

  • 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: _io._IOBase.readlines will check if it's closed first when hint is present.

  • bpo-29694: Fixed race condition in pathlib mkdir with flags parents=True. Patch by Armin Rigo.

  • bpo-29692: Fixed arbitrary unchaining of RuntimeError exceptions in contextlib.contextmanager. Patch by Siddharth Velankar.

  • bpo-29998: Pickling and copying ImportError now preserves name and path attributes.

  • bpo-29942: Fix a crash in itertools.chain.from_iterable when encountering long runs of empty iterables.

  • bpo-27863: Fixed multiple crashes in ElementTree caused by race conditions and wrong types.

  • 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: Avoid incorrect errors raised by Path.mkdir(exist_ok=True) when the OS gives priority to errors such as EACCES over EEXIST.

  • bpo-29861: Release references to tasks, their arguments and their results as soon as they are finished in multiprocessing.Pool.

  • bpo-29884: faulthandler: Restore the old sigaltstack during teardown. Patch by Christophe Zeitouny.

  • bpo-25455: Fixed crashes in repr of recursive buffered file-like objects.

  • bpo-29800: Fix crashes in partial.__repr__ if the keys of partial.keywords are not strings. Patch by Michael Seifert.

  • bpo-29742: get_extra_info() raises exception if get called on closed ssl transport. Patch by Nikolay Kim.

  • 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: 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: SimpleXMLRPCDispatcher no longer chains KeyError (or any other exception) to exception(s) raised in the dispatched methods. Patch by Petr Motejlek.

  • bpo-29704: asyncio.subprocess.SubprocessStreamProtocol no longer closes before all pipes are closed.

  • bpo-29703: Fix asyncio to support instantiation of new event loops in child processes.

  • bpo-29376: Fix assertion error in threading._DummyThread.is_alive().

  • 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: Fix unittest.mock._Call helper: don't ignore the name parameter anymore. Patch written by Jiajun Huang.

  • bpo-29532: Altering a kwarg dictionary passed to functools.partial() no longer affects a partial object after creation.

  • 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: Fix datetime.fromtimestamp() regression introduced in Python 3.6.0: check minimum and maximum years.

  • bpo-29519: Fix weakref spewing exceptions during interpreter shutdown when used with a rare combination of multiprocessing and custom codecs.

  • bpo-29416: Prevent infinite loop in pathlib.Path.mkdir

  • bpo-29444: Fixed out-of-bounds buffer access in the group() method of the match object. Based on patch by WGH.

  • 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: Fix a regression in argparse that help messages would wrap at non-breaking spaces.

  • bpo-28735: Fixed the comparison of mock.MagickMock with mock.ANY.

  • bpo-29011: Fix an important omission by adding Deque to the typing module.

  • bpo-29219: Fixed infinite recursion in the repr of uninitialized ctypes.CDLL instances.

  • 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 differen threads with the same uncached arguments.

  • 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-30176: Add missing attribute related constants in curses documentation.
  • bpo-26985: Add missing info of code object in inspect documentation.
  • bpo-28929: Link the documentation to its source file on GitHub.
  • bpo-25008: Document smtpd.py as effectively deprecated and add a pointer to aiosmtpd, a third-party asyncio-based replacement.
  • bpo-26355: Add canonical header link on each page to corresponding major version of the documentation. Patch by Matthias Bussonnier.
  • bpo-29349: Fix Python 2 syntax in code for building the documentation.

テスト

  • bpo-30822: Fix regrtest command line parser to allow passing -u extralargefile to run test_zipfile64.

  • 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), --matchfile (load a list of test filters from a text file, 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).

  • 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: 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: 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: 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-29243: Prevent unnecessary rebuilding of Python during make test, make install and some other make targets when configured with --enable-optimizations.
  • 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: Fix --enable-optimization didn't work.

Windows

  • bpo-30687: Locate msbuild.exe on Windows when building rather than vcvarsall.bat
  • bpo-29392: Prevent crash when passing invalid arguments into msvcrt module.

C API

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

Core and Builtins

  • bpo-29073: bytearray formatting no longer truncates on first null byte.
  • bpo-28932: Do not include <sys/random.h> if it does not exist.
  • bpo-28147: Fix a memory leak in split-table dictionaries: setattr() must not convert combined table into split table.
  • bpo-25677: Correct the positioning of the syntax error caret for indented blocks. Based on patch by Michael Layzell.
  • bpo-29000: Fixed bytes formatting of octals with zero padding in alternate form.
  • bpo-28512: Fixed setting the offset attribute of SyntaxError by PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().
  • bpo-28991: functools.lru_cache() was susceptible to an obscure reentrancy bug caused by a monkey-patched len() function.
  • bpo-28648: Fixed crash in Py_DecodeLocale() in debug build on Mac OS X when decode astral characters. Patch by Xiang Zhang.
  • bpo-19398: Extra slash no longer added to sys.path components in case of empty compile-time PYTHONPATH components.
  • bpo-28426: Fixed potential crash in PyUnicode_AsDecodedObject() in debug build.
  • bpo-23782: Fixed possible memory leak in _PyTraceback_Add() and exception loss in PyTraceBack_Here().
  • bpo-28379: Added sanity checks and tests for PyUnicode_CopyCharacters(). Patch by Xiang Zhang.
  • bpo-28376: The type of long range iterator is now registered as Iterator. Patch by Oren Milman.
  • bpo-28376: The constructor of range_iterator now checks that step is not 0. Patch by Oren Milman.
  • bpo-26906: Resolving special methods of uninitialized type now causes implicit initialization of the type instead of a fail.
  • bpo-18287: PyType_Ready() now checks that tp_name is not NULL. Original patch by Niklas Koep.
  • bpo-24098: Fixed possible crash when AST is changed in process of compiling it.
  • bpo-28350: String constants with null character no longer interned.
  • bpo-26617: Fix crash when GC runs during weakref callbacks.
  • bpo-27942: String constants now interned recursively in tuples and frozensets.
  • bpo-21578: Fixed misleading error message when ImportError called with invalid keyword args.
  • bpo-28203: Fix incorrect type in error message from complex(1.0, {2:3}). Patch by Soumya Sharma.
  • bpo-27955: Fallback on reading /dev/urandom device when the getrandom() syscall fails with EPERM, for example when blocked by SECCOMP.
  • bpo-28131: Fix a regression in zipimport's compile_source(). zipimport should use the same optimization level as the interpreter.
  • bpo-25221: Fix corrupted result from PyLong_FromLong(0) when Python is compiled with NSMALLPOSINTS = 0.
  • bpo-25758: Prevents zipimport from unnecessarily encoding a filename (patch by Eryk Sun)
  • bpo-28189: dictitems_contains no longer swallows compare errors. (Patch by Xiang Zhang)
  • bpo-27812: Properly clear out a generator's frame's backreference to the generator to prevent crashes in frame.clear().
  • bpo-27811: Fix a crash when a coroutine that has not been awaited is finalized with warnings-as-errors enabled.
  • 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: set literal evaluation order did not match documented behaviour.
  • 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: 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: 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: 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: 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: Respect the PYTHONCASEOK environment variable under Windows.
  • bpo-27514: Make having too many statically nested blocks a SyntaxError instead of SystemError.
  • bpo-27473: Fixed possible integer overflow in bytes and bytearray concatenations. Patch by Xiang Zhang.
  • bpo-27507: Add integer overflow check in bytearray.extend(). Patch by Xiang Zhang.
  • bpo-27581: Don't rely on wrapping for overflow check in PySequence_Tuple(). Patch by Xiang Zhang.
  • bpo-27443: __length_hint__() of bytearray iterators no longer return a negative integer for a resized bytearray.
  • bpo-27942: Fix memory leak in codeobject.c

ライブラリ

  • bpo-15812: inspect.getframeinfo() now correctly shows the first line of a context. Patch by Sam Breese.

  • 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: Fixed recursion errors in large or resized curses.textpad.Textbox. Based on patch by Tycho Andersen.

  • bpo-29119: Fix weakrefs in the pure python version of collections.OrderedDict move_to_end() method. Contributed by Andra Bogildea.

  • bpo-9770: curses.ascii predicates now work correctly with negative integers.

  • bpo-28427: old keys should not remove new values from WeakValueDictionary when collecting from another thread.

  • bpo-28923: Remove editor artifacts from Tix.py.

  • bpo-28871: Fixed a crash when deallocate deep ElementTree.

  • bpo-19542: Fix bugs in WeakValueDictionary.setdefault() and WeakValueDictionary.pop() when a GC collection happens in another thread.

  • bpo-20191: Fixed a crash in resource.prlimit() when pass a sequence that doesn't own its elements as limits.

  • bpo-28779: multiprocessing.set_forkserver_preload() would crash the forkserver process if a preloaded module instantiated some multiprocessing objects such as locks.

  • bpo-28847: dbm.dumb now supports reading read-only files and no longer writes the index file when it is not changed.

  • bpo-25659: In ctypes, prevent a crash calling the from_buffer() and from_buffer_copy() methods on abstract classes like Array.

  • bpo-28732: Fix crash in os.spawnv() with no elements in args

  • bpo-28485: Always raise ValueError for negative compileall.compile_dir(workers=...) parameter, even when multithreading is unavailable.

  • 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: LZMA compressor and decompressor no longer raise exceptions if given empty data twice. Patch by Benjamin Fogle.

  • bpo-28549: Fixed segfault in curses's addch() with ncurses6.

  • 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: The webbrowser module now supports Firefox 36+ and derived browsers. Based on patch by Oleg Broytman.

  • 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: 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: The textwrap.TextWrapper class now honors non-breaking spaces. Based on patch by Kaarle Ritvanen.

  • bpo-28353: os.fwalk() no longer fails on broken links.

  • bpo-25464: Fixed HList.header_exists() in tkinter.tix module by addin a workaround to Tix library bug.

  • bpo-28488: shutil.make_archive() no longer add entry "./" to ZIP archive.

  • bpo-24452: Make webbrowser support Chrome on Mac OS X.

  • bpo-20766: Fix references leaked by pdb in the handling of SIGINT handlers.

  • 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: Fixed writing non-BMP characters with binary format in plistlib.

  • 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: Fix the ability to pass the --link-objects option to the distutils build_ext command.

  • 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: Fixed possible use after free in the decompress() methods of the LZMADecompressor and BZ2Decompressor classes. Original patch by John Leitch.

  • 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: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py. Patch by Madison May.

  • bpo-27611: Fixed support of default root window in the tkinter.tix module.

  • 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: Allow falsy values to be used for msg parameter of subTest().

  • bpo-27932: Prevent memory leak in win32_ver().

  • Fix UnboundLocalError in socket._sendfile_use_sendfile.

  • bpo-28075: Check for ERROR_ACCESS_DENIED in Windows implementation of os.stat(). Patch by Eryk Sun.

  • bpo-25270: Prevent codecs.escape_encode() from raising SystemError when an empty bytestring is passed.

  • bpo-28181: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

  • bpo-25895: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by Gergely Imreh and Markus Holtermann.

  • bpo-27599: Fixed buffer overrun in binascii.b2a_qp() and binascii.a2b_qp().

  • 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: itertools.count() no longer rounds non-integer step in range between 1.0 and 2.0 to 1.

  • bpo-25969: Update the lib2to3 grammar to handle the unpacking generalizations added in 3.5.

  • 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: Validates persist parameter when opening MSI database

  • bpo-17582: xml.etree.ElementTree nows preserves whitespaces in attributes (Patch by Duane Griffin. Reviewed and approved by Stefan Behnel.)

  • bpo-28047: Fixed calculation of line length used for the base64 CTE in the new email policies.

  • bpo-27445: Don't pass str(_charset) to MIMEText.set_payload(). Patch by Claude Paroz.

  • 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: Avoid zero-length memcpy() etc calls with null source pointers in the "ctypes" and "array" modules.

  • 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: Fix email iter_attachments incorrect mutation of payload list.

  • bpo-27691: Fix ssl module's parsing of GEN_RID subject alternative name fields in X.509 certs.

  • bpo-27850: Remove 3DES from ssl module's default cipher list to counter measure sweet32 attack (CVE-2016-2183).

  • bpo-27766: Add ChaCha20 Poly1305 to ssl module's default cipher list. (Required OpenSSL 1.1.0 or LibreSSL).

  • 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: Fix error when distutils encounters symlink.

  • bpo-27881: Fixed possible bugs when setting sqlite3.Connection.isolation_level. Based on patch by Xiang Zhang.

  • bpo-27861: Fixed a crash in sqlite3.Connection.cursor() when a factory creates not a cursor. Patch by Xiang Zhang.

  • bpo-19884: Avoid spurious output on OS X with Gnu Readline.

  • 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: 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). 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: Fix unnormalised Fraction.__pow__ result in the case of negative exponent and negative base.

  • bpo-21718: cursor.description is now available for queries using CTEs.

  • bpo-2466: posixpath.ismount now correctly recognizes mount points which the user does not have permission to access.

  • bpo-27773: Correct some memory management errors server_hostname in _ssl.wrap_socket().

  • 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: Fix possible usage of uninitialized memory in operator.methodcaller.

  • bpo-27774: Fix possible Py_DECREF on unowned object in _sre.

  • bpo-27760: Fix possible integer overflow in binascii.b2a_qp.

  • bpo-27758: Fix possible integer overflow in the _csv module for large record lengths.

  • bpo-27568: Prevent HTTPoxy attack (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: Do not assume sched.h defines any SCHED_* constants.

  • 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: Release GIL in nt._isdir

  • bpo-17711: Fixed unpickling by the persistent ID with protocol 0. Original patch by Alexandre Vassalotti.

  • bpo-27522: Avoid an unintentional reference cycle in email.feedparser.

  • bpo-26844: Fix error message for imp.find_module() to refer to 'path' instead of 'name'. Patch by Lev Maximov.

  • bpo-23804: Fix SSL zero-length recv() calls to not block and not raise an error about unclean EOF.

  • bpo-27466: Change time format returned by http.cookie.time2netscape, confirming the netscape cookie format and making it consistent with documentation.

  • bpo-26664: Fix activate.fish by removing mis-use of $.

  • 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: Fixed curses.ascii functions isblank(), iscntrl() and ispunct().

  • 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: Prevents distutils failing on Windows when environment variables contain non-ASCII characters

  • bpo-27330: Fixed possible leaks in the ctypes module.

  • bpo-27238: Got rid of bare excepts in the turtle module. Original patch by Jelle Zijlstra.

  • 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 bug described in issue25782.

セキュリティ

  • 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-26386: Fixed ttk.TreeView selection operations with item id's containing spaces.

セキュリティ

  • bpo-22636: Avoid shell injection problems with ctypes.util.find_library().

ライブラリ

  • 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: Add loop.connect_accepted_socket(). Patch by Jim Fulton.
  • bpo-27930: Improved behaviour of logging.handlers.QueueListener. Thanks to Paulo Andrade and Petr Viktorin for the analysis and patch.
  • bpo-21201: Improves readability of multiprocessing error message. Thanks to Wojciech Walczak for patch.
  • bpo-27456: asyncio: Set TCP_NODELAY by default.
  • bpo-27906: Fix socket accept exhaustion during high TCP traffic. Patch by Kevin Conway.
  • bpo-28174: Handle when SO_REUSEPORT isn't properly supported. Patch by Seth Michael Larson.
  • bpo-26654: Inspect functools.partial in asyncio.Handle.__repr__. Patch by iceboy.
  • bpo-26909: Fix slow pipes IO in asyncio. Patch by INADA Naoki.
  • bpo-28176: Fix callbacks race in asyncio.SelectorLoop.sock_connect.
  • bpo-27759: Fix selectors incorrectly retain invalid file descriptors. Patch by Mark Williams.
  • bpo-28368: Refuse monitoring processes if the child watcher has no loop attached. Patch by Vincent Michel.
  • bpo-28369: Raise RuntimeError when transport's FD is used with add_reader, add_writer, etc.
  • bpo-28370: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг Марк.
  • bpo-28371: Deprecate passing asyncio.Handles to run_in_executor.
  • bpo-28372: Fix asyncio to support formatting of non-python coroutines.
  • bpo-28399: Remove UNIX socket from FS before binding. Patch by Коренберг Марк.
  • bpo-27972: Prohibit Tasks to await on themselves.
  • bpo-26923: Fix asyncio.Gather to refuse being cancelled once all children are done. Patch by Johannes Ebke.
  • bpo-26796: Don't configure the number of workers for default threadpool executor. Initial patch by Hans Lawrenz.
  • bpo-28600: Optimize loop.call_soon().
  • bpo-28613: Fix get_event_loop() return the current loop if called from coroutines/callbacks.
  • bpo-28639: Fix inspect.isawaitable to always return bool Patch by Justin Mayfield.
  • bpo-28652: Make loop methods reject socket kinds they do not support.
  • bpo-28653: Fix a refleak in functools.lru_cache.
  • bpo-28703: Fix asyncio.iscoroutinefunction to handle Mock objects.
  • bpo-24142: Reading a corrupt config file left the parser in an invalid state. Original patch by Florian Höch.
  • bpo-28990: Fix SSL hanging if connection is closed before handshake completed. (Patch by HoHo-Ho)

IDLE

  • bpo-15308: Add 'interrupt execution' (^C) to Shell menu. Patch by Roger Serwy, updated by Bayard Randel.
  • bpo-27922: Stop IDLE tests from 'flashing' gui widgets on the screen.
  • Add version to title of IDLE help window.
  • bpo-25564: In section on IDLE -- console differences, mention that using exec means that __builtins__ is defined for each statement.
  • 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: 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: add line counter and crc to IDLE configHandler test dump.
  • bpo-27365: Allow non-ascii chars in IDLE NEWS.txt, for contributor names.
  • 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: PyUnicode_CompareWithASCIIString() now never raises exceptions.
  • bpo-26754: PyUnicode_FSDecoder() accepted a filename argument encoded as an iterable of integers. Now only strings and bytes-like objects are accepted.

ドキュメント

  • bpo-28513: Documented command-line interface of zipfile.

テスト

  • bpo-28950: Disallow -j0 to be combined with -T/-l/-M in regrtest command line arguments.
  • bpo-28666: Now test.support.rmtree is able to remove unwritable or unreadable directories.
  • bpo-23839: Various caches now are cleared before running every test file.
  • bpo-28409: regrtest: fix the parser of command line arguments.
  • bpo-27787: Call gc.collect() before checking each test for "dangling threads", since the dangling threads are weak references.
  • bpo-27369: In test_pyexpat, avoid testing an error message detail that changed in Expat 2.2.0.

Tools/Demos

  • 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: Fixed the type of the first argument of module-level functions generated by Argument Clinic. Patch by Petr Viktorin.
  • bpo-27418: Fixed Tools/importbench/importbench.py.

Windows

  • bpo-28251: Improvements to help manuals on Windows.
  • bpo-28110: launcher.msi has different product codes between 32-bit and 64-bit
  • bpo-25144: Ensures TargetDir is set before continuing with custom install.
  • bpo-27469: Adds a shell extension to the launcher so that drag and drop works correctly.
  • bpo-27309: Enabled proper Windows styles in python[w].exe manifest.

ビルド

  • bpo-29080: Removes hard dependency on hg.exe from PCBuild/build.bat
  • bpo-23903: Added missed names to PC/python3.def.
  • bpo-10656: Fix out-of-tree building on AIX. Patch by Tristan Carel and Michael Haubenwallner.
  • bpo-26359: Rename --with-optimiations to --enable-optimizations.
  • bpo-28444: Fix missing extensions modules when cross compiling.
  • bpo-28248: Update Windows build and OS X installers to use OpenSSL 1.0.2j.
  • bpo-28258: Fixed build with Estonian locale (python-config and distclean targets in Makefile). Patch by Arfrever Frehtes Taifersar Arahesis.
  • bpo-26661: setup.py now detects system libffi with multiarch wrapper.
  • bpo-28066: Fix the logic that searches build directories for generated include files when building outside the source tree.
  • bpo-15819: Remove redundant include search directory option for building outside the source tree.
  • bpo-27566: Fix clean target in freeze makefile (patch by Lisa Roach)
  • bpo-27705: Update message in validate_ucrtbase.py
  • 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: The profile-opt build now applies PGO to the built-in modules.
  • bpo-26359: Add the --with-optimizations configure flag.
  • bpo-27713: Suppress spurious build warnings when updating importlib's bootstrap files. Patch by Xiang Zhang
  • 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: CPP invocation in configure must use CPPFLAGS. Patch by Chi Hsuan Yen.
  • 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: Set PYTHON_FOR_GEN in configure as the Python program to be used for file generation during the build.
  • 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: 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: Update Windows builds to use OpenSSL 1.0.2h.

テスト

  • bpo-26867: Ubuntu's openssl OP_NO_SSLv3 is forced on by default; fix test.

IDLE

  • bpo-27365: Allow non-ascii in idlelib/NEWS.txt - minimal part for 3.5.2.

Python 3.5.2 リリース候補 1

Release date: 2016-06-12

Core and Builtins

  • bpo-27066: Fixed SystemError if a custom opener (for open()) returns a negative number without setting an exception.
  • bpo-20041: Fixed TypeError when frame.f_trace is set to None. Patch by Xavier de Gaye.
  • bpo-26168: Fixed possible refleaks in failing Py_BuildValue() with the "N" format unit.
  • bpo-26991: Fix possible refleak when creating a function with annotations.
  • bpo-27039: Fixed bytearray.remove() for values greater than 127. Patch by Joe Jevnik.
  • bpo-23640: int.from_bytes() no longer bypasses constructors for subclasses.
  • bpo-26811: gc.get_objects() no longer contains a broken tuple with NULL pointer.
  • 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: Make the builtin slice type support cycle collection.
  • bpo-26718: super.__init__ no longer leaks memory if called multiple times. NOTE: A direct call of super.__init__ is not endorsed!
  • bpo-25339: PYTHONIOENCODING now has priority over locale in setting the error handler for stdin and stdout.
  • 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: 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: 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: 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: Correct behavior to reject comma as a legal character for cookie names.
  • 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: Fix the doc comment for FileFinder.find_spec().
  • 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: 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: 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: [UPDATE] Comment out the one of the pickleability tests in _PyObject_GetState() due to regressions observed in Cython-based projects.
  • bpo-25961: Disallowed null characters in the type name.
  • bpo-25973: Fix segfault when an invalid nonlocal statement binds a name starting with two underscores.
  • 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: Massive replacing unsafe attribute setting code with special macro Py_SETREF.
  • bpo-25766: Special method __bytes__() now works in str subclasses.
  • 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: Fixed problem with in-place string concatenation and utf-8 cache.
  • bpo-27147: Mention PEP 420 in the importlib docs.
  • bpo-24097: Fixed crash in object.__reduce__() if slot name is freed inside __getattr__.
  • 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: Fix semantic bugs when using binary operators with dictionary views and tuples.
  • bpo-26171: Fix possible integer overflow and heap corruption in zipimporter.get_data().
  • bpo-25660: Fix TAB key behaviour in REPL with readline.
  • bpo-25887: Raise a RuntimeError when a coroutine object is awaited more than once.
  • 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.

セキュリティ

  • bpo-26556: Update expat to 2.1.1, fixes CVE-2015-1283.
  • Fix TLS stripping vulnerability in smtplib, CVE-2016-0772. Reported by Team Oststrom

ライブラリ

  • bpo-21386: Implement missing IPv4Address.is_global property. It was documented since 07a5610bae9d. Initial patch by Roger Luethi.
  • 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 (Awaitable, AsyncIterable, AsyncIterator) have been added (in fact they made it into 3.5.1 but were never mentioned).
  • 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: Fix the "platform" module to tolerate when sys.version contains truncated build information.

セキュリティ

  • 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-27164: In the zlib module, allow decompressing raw Deflate streams with a predefined zdict. Based on patch by Xiang Zhang.

  • 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: Add __all__ to string. Patch by Emanuel Barry.

  • bpo-26373: subprocess.Popen.communicate now correctly ignores BrokenPipeError when the child process dies before .communicate() is called in more/all circumstances.

  • bpo-21776: distutils.upload now correctly handles HTTPError. Initial patch by Claudiu Popa.

  • bpo-27114: Fix SSLContext._load_windows_store_certs fails with PermissionError

  • bpo-18383: Avoid creating duplicate filters when using filterwarnings and simplefilter. Based on patch by Alex Shkop.

  • 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: Fix infinite recursion using typing.py. Thanks to Kalle Tuure!

  • bpo-14132: Fix urllib.request redirect handling when the target only has a query string. Original fix by Ján Janech.

  • 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: Honor debuglevel flag in urllib.request.HTTPHandler. Patch contributed by Chi Hsuan Yen.

  • 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: mock_open 'files' no longer error on readline at end of file. Patch from Yolanda Robla.

  • bpo-25745: Fixed leaking a userptr in curses panel destructor.

  • bpo-26977: Removed unnecessary, and ignored, call to sum of squares helper in statistics.pvariance.

  • bpo-26881: The modulefinder module now supports extended opcode arguments.

  • bpo-23815: Fixed crashes related to directly created instances of types in _tkinter and curses.panel modules.

  • bpo-17765: weakref.ref() no longer silently ignores keyword arguments. Patch by Georg Brandl.

  • bpo-26873: xmlrpc now raises ResponseError on unsupported type tags instead of silently return incorrect result.

  • bpo-26711: Fixed the comparison of plistlib.Data with other types.

  • 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: 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: recursive_repr() now sets __qualname__ of wrapper. Patch by Xiang Zhang.

  • 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: assertSequenceEqual() now correctly outputs non-stringified differing items (like bytes in the -b mode). This affects assertListEqual() and assertTupleEqual().

  • 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: itemgetter, attrgetter and methodcaller objects no longer silently ignore keyword arguments.

  • bpo-26733: Disassembling a class now disassembles class and static methods. Patch by Xiang Zhang.

  • bpo-26801: Fix error handling in shutil.get_terminal_size(), catch AttributeError instead of NameError. Patch written by Emanuel Barry.

  • bpo-24838: tarfile's ustar and gnu formats now correctly calculate name and link field limits for multibyte character encodings like utf-8.

セキュリティ

  • 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-26717: Stop encoding Latin-1-ized WSGI paths with UTF-8. Patch by Anthony Sottile.
  • 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: Add .webm to mimetypes.types_map. Patch by Giampaolo Rodola'.
  • bpo-13952: Add .csv to mimetypes.types_map. Patch by Geoff Wilson.
  • bpo-26709: Fixed Y2038 problem in loading binary PLists.
  • bpo-23735: Handle terminal resizing with Readline 6.3+ by installing our own SIGWINCH handler. Patch by Eric Price.
  • 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: Change BufferedReader.writable() and BufferedWriter.readable() to always return False.
  • 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: Raise ValueError rather than SystemError when a negative length is passed to SSLSocket.recv() or read().
  • bpo-23804: Fix SSL recv(0) and read(0) methods to return zero bytes instead of up to 1024.
  • bpo-26616: Fixed a bug in datetime.astimezone() method.
  • 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: Ctrl+C during Readline history search now cancels the search mode when compiled with Readline 7.
  • bpo-26560: Avoid potential ValueError in BaseHandler.start_response. Initial patch by Peter Inglesby.

セキュリティ

  • bpo-26313: ssl.py _load_windows_store_certs fails if windows cert store is empty. Patch by Baji.

ライブラリ

  • bpo-26569: Fix pyclbr.readmodule() and pyclbr.readmodule_ex() to support importing packages.
  • 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: Handle sockets in directories unittest discovery is scanning. Patch from Victor van den Elzen.
  • bpo-16181: cookiejar.http2time() now returns None if year is higher than datetime.MAXYEAR.
  • bpo-26513: Fixes platform module detection of Windows Server
  • bpo-23718: Fixed parsing time in week 0 before Jan 1. Original patch by Tamás Bence Gedai.
  • bpo-20589: Invoking Path.owner() and Path.group() on Windows now raise NotImplementedError instead of ImportError.
  • bpo-26177: Fixed the keys() method for Canvas and Scrollbar widgets.
  • bpo-15068: Got rid of excessive buffering in the fileinput module. The bufsize parameter is no longer used.
  • bpo-2202: Fix UnboundLocalError in AbstractDigestAuthHandler.get_algorithm_impls. Initial patch by Mathieu Dupuy.
  • bpo-25718: Fixed pickling and copying the accumulate() iterator with total is None.
  • bpo-26475: Fixed debugging output for regular expressions with the (?x) flag.
  • 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: Remove the file if the internal open() call in NamedTemporaryFile() fails. Patch by Silent Ghost.
  • 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: Leading <~ is optional now in base64.a85decode() with adobe=True. Patch by Swati Jaiswal.
  • bpo-26186: Remove an invalid type check in importlib.util.LazyLoader.
  • bpo-26367: importlib.__import__() raises SystemError like builtins.__import__() when level is specified but without an accompanying package specified.
  • bpo-26309: In the "socketserver" module, shut down the request (closing the connected socket) when verify_request() returns false. Patch by Aviv Palivoda.

セキュリティ

  • bpo-25939: On Windows open the cert store readonly in ssl.enum_certificates.

ライブラリ

  • bpo-25995: os.walk() no longer uses FDs proportional to the tree depth.
  • 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: Restored support of bytes paths in os.walk() on Windows.
  • bpo-26045: Add UTF-8 suggestion to error message when posting a non-Latin-1 string with http.client.
  • bpo-12923: Reset FancyURLopener's redirect counter even if there is an exception. Based on patches by Brian Brazil and Daniel Rocco.
  • 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: copy.deepcopy() now correctly copies range() objects with non-atomic attributes.
  • bpo-23076: Path.glob() now raises a ValueError if it's called with an invalid pattern. Patch by Thomas Nyberg.
  • bpo-19883: Fixed possible integer overflows in zipimport.
  • 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: xmlrpc now works with strings not encodable with used non-UTF-8 encoding.
  • bpo-25935: Garbage collector now breaks reference loops with OrderedDict.
  • bpo-16620: Fixed AttributeError in msilib.Directory.glob().
  • bpo-26013: Added compatibility with broken protocol 2 pickles created in old Python 3 versions (3.4.3 and lower).
  • bpo-25850: Use cross-compilation by default for 64-bit Windows.
  • bpo-17633: Improve zipimport's support for namespace packages.
  • bpo-24705: Fix sysconfig._parse_makefile not expanding ${} vars appearing before $() vars.
  • bpo-22138: Fix mock.patch behavior when patching descriptors. Restore original values after patching. Patch contributed by Sean McCully.
  • bpo-25672: In the ssl module, enable the SSL_MODE_RELEASE_BUFFERS mode option if it is safe to do so.
  • bpo-26012: Don't traverse into symlinks for ** pattern in pathlib.Path.[r]glob().
  • bpo-24120: Ignore PermissionError when traversing a tree with pathlib.Path.[r]glob(). Patch by Ulrich Petri.
  • bpo-25447: fileinput now uses sys.stdin as-is if it does not have a buffer attribute (restores backward compatibility).
  • 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: Fixed possible use after free in ElementTree.XMLPullParser.
  • bpo-25860: os.fwalk() no longer skips remaining directories when error occurs. Original patch by Samson Lee.
  • bpo-25914: Fixed and simplified OrderedDict.__sizeof__.
  • bpo-25902: Fixed various refcount issues in ElementTree iteration.
  • 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: 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: In the subprocess module, preserve any exception caused by fork() failure when preexec_fn is used.
  • bpo-6478: _strptime's regexp cache now is reset after changing timezone with time.tzset().
  • 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: 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: 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: Fixed copying object with state with boolean value is false.
  • bpo-10131: Fixed deep copying of minidom documents. Based on patch by Marian Ganisin.
  • bpo-25725: Fixed a reference leak in pickle.loads() when unpickling invalid data including tuple instructions.
  • bpo-25663: In the Readline completer, avoid listing duplicate global names, and search the global namespace before searching builtins.
  • bpo-25688: Fixed file leak in ElementTree.iterparse() raising an error.
  • bpo-23914: Fixed SystemError raised by unpickler on broken pickle data.
  • bpo-25691: Fixed crash on deleting ElementTree.Element attributes.
  • 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: Add asyncio.StreamReader.readuntil() method. Patch by Марк Коренберг.
  • 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: Avoid unnecessary serialization of getaddrinfo(3) calls on current versions of OpenBSD and NetBSD. Patch by A. Jesse Jiryu Davis.
  • bpo-26848: Fix asyncio/subprocess.communicate() to handle empty input. Patch by Jack O'Connor.
  • bpo-27040: Add loop.get_exception_handler method
  • bpo-27041: asyncio: Add loop.create_future method
  • bpo-27223: asyncio: Fix _read_ready and _write_ready to respect _conn_lost. Patch by Łukasz Langa.
  • bpo-22970: asyncio: Fix inconsistency cancelling Condition.wait. Patch by David Coles.

IDLE

  • 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: Make clear in idlelib.idle_test.__init__ that the directory is a private implementation of test.test_idle and tool for maintainers.
  • 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: Revise idle_test/README.txt with advice about avoiding tk warning messages from tests. Apply advice to several IDLE tests.
  • bpo-27117: Make colorizer htest and turtledemo work with dark themes. Move code for configuring text widget colors to a new function.
  • 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: Add test for IDLE's percolator. Original patch by Saimadhav Heblikar.
  • bpo-21676: Add test for IDLE's replace dialog. Original patch by Saimadhav Heblikar.
  • bpo-18410: Add test for IDLE's search dialog. Original patch by Westley Martínez.
  • bpo-21703: Add test for IDLE's undo delegator. Original patch by Saimadhav Heblikar .
  • bpo-27044: Add ConfigDialog.remove_var_callbacks to stop memory leaks.
  • bpo-23977: Add more asserts to test_delegator.
  • 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: fix incorrect change in IOBinding that prevented printing. Augment IOBinding htest to include all major IOBinding functions.
  • 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-19489: Moved the search box from the sidebar to the header and footer of each page. Patch by Ammar Askar.
  • bpo-24136: Document the new PEP 448 unpacking syntax of 3.5.
  • bpo-26736: Used HTTPS for external links in the documentation if possible.
  • 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: Adds note to ctypes documentation regarding cdll.msvcrt.
  • bpo-25500: Fix documentation to not claim that __import__ is searched for in the global scope.
  • 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

テスト

  • bpo-21916: Added tests for the turtle module. Patch by ingrid, Gregory Loyse and Jelle Zijlstra.
  • bpo-26523: The multiprocessing thread pool (multiprocessing.dummy.Pool) was untested.
  • bpo-26015: Added new tests for pickling iterators of mutable sequences.
  • bpo-26325: Added test.support.check_no_resource_warning() to check that no ResourceWarning is emitted.
  • 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: Tests for OrderedDict are extracted from test_collections into separate file test_ordered_dict.
  • bpo-26583: Skip test_timestamp_overflow in test_import if bytecode files cannot be written.

ビルド

  • bpo-26884: Fix linking extension modules for cross builds. Patch by Xavier de Gaye.
  • 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: Fix the cross-compiling pgen rule for in-tree builds. Patch by Xavier de Gaye.
  • bpo-21668: Link audioop, _datetime, _ctypes_test modules to libm, except on Mac OS X. Patch written by Xavier de Gaye.
  • 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: Adds validation of ucrtbase[d].dll version with warning for old versions.
  • bpo-17603: Avoid error about nonexistant fileblocks.o file by using a lower-level check for st_blocks in struct stat.
  • bpo-26079: Fixing the build output folder for tix-8.4.3.6. Patch by Bjoern Thiel.
  • bpo-26465: Update Windows builds to use OpenSSL 1.0.2g.
  • 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: 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: Add support for building with ICC to configure, including a new --with-icc flag.
  • bpo-25696: Fix installation of Python on UNIX with make -j9.
  • bpo-26930: Update OS X 10.5+ 32-bit-only installer to build and link with OpenSSL 1.0.2h.
  • bpo-26268: Update Windows builds to use OpenSSL 1.0.2f.
  • bpo-25136: Support Apple Xcode 7's new textual SDK stub libraries.
  • 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: Updates make_zip.py to correctly generate library ZIP file.
  • 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: bdist_wininst created binaries fail to start and find 32bit Python
  • bpo-26073: Update the list of magic numbers in launcher
  • bpo-26065: Excludes venv from library when generating embeddable distro.

Tools/Demos

  • 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: Fix the Freeze tool to properly use flags passed through configure. Patch by Daniel Shaulov.
  • bpo-26489: Add dictionary unpacking support to Tools/parser/unparse.py. Patch by Guo Ci Teo.
  • bpo-26316: Fix variable name typo in Argument Clinic.

Windows

  • bpo-17500: Remove unused and outdated icons. (See also: https://github.com/python/pythondotorg/issues/945)

Python 3.5.1 最終版

Release date: 2015-12-06

Core and Builtins

  • bpo-25709: Fixed problem with in-place string concatenation and utf-8 cache.

Windows

  • 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: Fix a possible segfault during argument parsing in functions that accept filesystem paths.
  • 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: Fixed tokenizer crash when processing undecodable source code with a null byte.
  • bpo-25462: The hash of the key now is calculated only once in most operations in C implementation of OrderedDict.
  • bpo-22995: Default implementation of __reduce__ and __reduce_ex__ now rejects builtin types with not defined __new__.
  • bpo-25555: Fix parser and AST: fill lineno and col_offset of "arg" node when compiling AST from Python objects.
  • 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: Fixed a crash and leaking NULL in repr() of OrderedDict that was mutated by direct calls of dict methods.
  • bpo-25449: Iterating OrderedDict with keys with unstable hash now raises KeyError in C implementations as well as in Python implementation.
  • bpo-25395: Fixed crash when highly nested OrderedDict structures were garbage collected.
  • 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: Fix input() to prompt to the redirected stdout when sys.stdout.fileno() fails.
  • bpo-24806: Prevent builtin types that are not allowed to be subclassed from being subclassed through multiple inheritance.
  • bpo-24848: Fixed a number of bugs in UTF-7 decoding of misformed data.
  • bpo-25280: Import trace messages emitted in verbose (-v) mode are no longer formatted twice.
  • 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: The stdprinter (used as sys.stderr before the io module is imported at startup) now uses the backslashreplace error handler.
  • bpo-25131: Make the line number and column offset of set/dict literals and comprehensions correspond to the opening brace.
  • 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.

ライブラリ

  • 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: Avoid incorrect errors raised by os.makedirs(exist_ok=True) when the OS gives priority to errors such as EACCES over EEXIST.
  • bpo-25593: Change semantics of EventLoop.stop() in asyncio.
  • 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: In the Readline completer, only call getattr() once per attribute.
  • 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: Added "escape" to the __all__ list in the glob module.
  • bpo-25584: Fixed recursive glob() with patterns starting with **.
  • bpo-25446: Fix regression in smtplib's AUTH LOGIN support.
  • bpo-18010: Fix the pydoc web server's module search function to handle exceptions from importing packages.
  • bpo-25554: Got rid of circular references in regular expression parsing.
  • 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: Fixed inspect.getdoc() for inherited docstrings of properties. Original patch by John Mark Vandenberg.
  • bpo-25515: Always use os.urandom as a source of randomness in uuid.uuid4.
  • 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: The lru_cache() wrapper objects now can be copied and pickled (by returning the original object unchanged).
  • bpo-25390: typing: Don't crash on Union[str, Pattern].
  • bpo-25441: asyncio: Raise error from drain() when socket is closed.
  • bpo-25410: Cleaned up and fixed minor bugs in C implementation of OrderedDict.
  • bpo-25411: Improved Unicode support in SMTPHandler through better use of the email package. Thanks to user simon04 for the patch.
  • bpo-25407: Remove mentions of the formatter module being removed in Python 3.6.
  • 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: zipfile now works in threads disabled builds.
  • bpo-25328: smtpd's SMTPChannel now correctly raises a ValueError if both decode_data and enable_SMTPUTF8 are set to true.
  • bpo-25316: distutils raises OSError instead of DistutilsPlatformError when MSVC is not installed.
  • bpo-25380: Fixed protocol for the STACK_GLOBAL opcode in pickletools.opcodes.
  • 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: 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: Fix CGIRequestHandler to split the query from the URL at the first question mark (?) rather than the last. Patch from Xiang Zhang.
  • 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: C implementation of functools.lru_cache() now calculates key's hash only once.
  • bpo-22958: Constructor and update method of weakref.WeakValueDictionary now accept the self and the dict keyword arguments.
  • bpo-22609: Constructor of collections.UserDict now accepts the self keyword argument.
  • bpo-25111: Fixed comparison of traceback.FrameSummary.
  • 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: Fix string.Formatter problem with auto-numbering and nested format_specs. Patch by Anthon van der Neut.
  • bpo-25233: Rewrite the guts of asyncio.Queue and asyncio.Semaphore to be more understandable and correct.
  • bpo-25203: Failed readline.set_completer_delims() no longer left the module in inconsistent state.
  • bpo-23600: Default implementation of tzinfo.fromutc() was returning wrong results in some cases.
  • bpo-23329: Allow the ssl module to be built with older versions of LibreSSL.
  • Prevent overflow in _Unpickler_Read.
  • 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: Make deque_clear() safer by emptying the deque before clearing. This helps avoid possible reentrancy issues.
  • bpo-19143: platform module now reads Windows version from kernel32.dll to avoid compatibility shims.
  • bpo-25092: Fix datetime.strftime() failure when errno was already set to EINVAL.
  • 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: 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: Omitted internal frames in traceback functions print_stack(), format_stack(), and extract_stack() called without arguments.
  • bpo-25118: Fix a regression of Python 3.5.0 in os.waitpid() on Windows.
  • 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: Correctly compute stack usage of the BUILD_MAP opcode.
  • 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: Make sure that HTMLParser.feed() returns all the data, even when convert_charrefs is True.
  • bpo-24982: shutil.make_archive() with the "zip" format now adds entries for directories (including empty directories) in ZIP file.
  • bpo-25019: Fixed a crash caused by setting non-string key of expat parser. Based on patch by John Leitch.
  • bpo-16180: Exit pdb if file has syntax error, instead of trapping user in an infinite loop. Patch by Xavier de Gaye.
  • 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: Fix error handling and a race condition (related to garbage collection) in collections.OrderedDict constructor.
  • bpo-24881: Fixed setting binary mode in Python implementation of FileIO on Windows and Cygwin. Patch from Akira Li.
  • bpo-25578: Fix (another) memory leak in SSLSocket.getpeercer().
  • bpo-25530: Disable the vulnerable SSLv3 protocol by default when creating ssl.SSLContext.
  • bpo-25569: Fix memory leak in SSLSocket.getpeercert().
  • bpo-25471: Sockets returned from accept() shouldn't appear to be nonblocking.
  • bpo-25319: When threading.Event is reinitialized, the underlying condition should use a regular lock rather than a recursive lock.
  • bpo-21112: Fix regression in unittest.expectedFailure on subclasses. Patch from Berker Peksag.
  • 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: Fix overrun error in deque.index(). Found by John Leitch and Bryce Darling.
  • bpo-24774: Fix docstring in http.server.test. Patch from Chiu-Hsiang Hsu.
  • bpo-21159: Improve message in configparser.InterpolationMissingOptionError. Patch from Łukasz Langa.
  • bpo-20362: Honour TestCase.longMessage correctly in assertRegex. Patch from Ilia Kurenkov.
  • bpo-23572: Fixed functools.singledispatch on classes with falsy metaclasses. Patch by Ethan Furman.
  • asyncio: ensure_future() now accepts awaitable objects.

IDLE

  • 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: 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: Improve the appearance of the IDLE editor window status bar. Patch by Mark Roseman.
  • 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: 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: Re-activate the config dialog help button with some content about the other buttons and the new IDLE Dark theme.
  • 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: 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: Users can now set breakpoint colors in Settings -> Custom Highlighting. Original patch by Mark Roseman.
  • 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: Idle: make calltip and completion boxes appear on Macs affected by a tk regression. Initial patch by Mark Roseman.
  • bpo-24988: Idle ScrolledList context menus (used in debugger) now work on Mac Aqua. Patch by Mark Roseman.
  • bpo-24801: Make right-click for context menu work on Mac Aqua. Patch by Mark Roseman.
  • bpo-25173: Associate tkinter messageboxes with a specific widget. For Mac OSX, make them a 'sheet'. Patch by Mark Roseman.
  • 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: Condense and rewrite Idle doc section on text colors.
  • bpo-21995: Explain some differences between IDLE and console Python.
  • bpo-22820: Explain need for print when running file from Idle editor.
  • bpo-25224: Doc: augment Idle feature list and no-subprocess section.
  • bpo-25219: Update doc for Idle command line options. Some were missing and notes were not correct.
  • bpo-24861: Most of idlelib is private and subject to change. Use idleib.idle.* to start Idle. See idlelib.__init__.__doc__.
  • bpo-25199: Idle: add synchronization comments for future maintainers.
  • 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: Deprecate unused idlelib.idlever with possible removal in 3.6.
  • bpo-24790: Remove extraneous code (which also create 2 & 3 conflicts).

ドキュメント

  • bpo-22558: Add remaining doc links to source code for Python-coded modules. Patch by Yoni Lavi.
  • 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: Clarify the default size argument of stack_size() in the "threading" and "_thread" modules. Patch from Mattip.
  • bpo-23725: Overhaul tempfile docs. Note deprecated status of mktemp. Patch from Zbigniew Jędrzejewski-Szmek.
  • bpo-24808: Update the types of some PyTypeObject fields. Patch by Joseph Weston.
  • bpo-22812: Fix unittest discovery examples. Patch from Pam McA'Nulty.

テスト

  • bpo-25449: Added tests for OrderedDict subclasses.
  • 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: 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.

ビルド

  • 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: Windows MSIs now have unique display names.
  • bpo-24986: It is now possible to build Python on Windows without errors when external libraries are not available.

Windows

  • bpo-25450: Updates shortcuts to start Python in installation directory.
  • bpo-25164: Changes default all-users install directory to match per-user directory.
  • bpo-25143: Improves installer error messages for unsupported platforms.
  • bpo-25163: Display correct directory in installer when using non-default settings.
  • bpo-25361: Disables use of SSE2 instructions in Windows 32-bit build
  • bpo-25089: Adds logging to installer for case where launcher is not selected on upgrade.
  • bpo-25165: Windows uninstallation should not remove launcher if other versions remain
  • bpo-25112: py.exe launcher is missing icons
  • bpo-25102: Windows installer does not precompile for -O or -OO.
  • bpo-25081: Makes Back button in installer go back to upgrade page when upgrading.
  • bpo-25091: Increases font size of the installer.
  • bpo-25126: Clarifies that the non-web installer will download some components.
  • bpo-25213: Restores requestedExecutionLevel to manifest to disable UAC virtualization.
  • bpo-25022: Removed very outdated PC/example_nt/ directory.

Tools/Demos

  • bpo-25440: Fix output of python-config --extension-suffix.

Python 3.5.0 final

Release date: 2015-09-13

ビルド

  • bpo-25071: Windows installer should not require TargetDir parameter when installing quietly.

Python 3.5.0 release candidate 4

Release date: 2015-09-09

ライブラリ

  • bpo-25029: Fixes MemoryError in test_strptime.

ビルド

  • 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: Prevent import subsystem stack frames from being counted by the warnings.warn(stacklevel=) parameter.
  • bpo-24912: Prevent __class__ assignment to immutable built-in objects.
  • bpo-24975: Fix AST compilation for PEP 448 syntax.

ライブラリ

  • bpo-24917: time_strftime() buffer over-read.
  • 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: Fixed a bug in typing.py where isinstance([], typing.Iterable) would return True once, then False on subsequent calls.
  • bpo-24989: Fixed buffer overread in BytesIO.readline() if a position is set beyond size. Based on patch by John Leitch.
  • 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: Interpreter now starts properly when dynamic loading is disabled. Patch by Petr Viktorin.
  • bpo-21167: NAN operations are now handled correctly when python is compiled with ICC even if -fp-model strict is not specified.
  • bpo-24492: A "package" lacking a __name__ attribute when trying to perform a from .. import ... statement will trigger an ImportError instead of an AttributeError.

ライブラリ

  • bpo-24847: Removes vcruntime140.dll dependency from Tcl/Tk.
  • bpo-24839: platform._syscmd_ver raises DeprecationWarning
  • 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: Resize odict in all cases that the underlying dict resizes.

ライブラリ

  • bpo-24824: Signatures of codecs.encode() and codecs.decode() now are compatible with pydoc.
  • bpo-24634: Importing uuid should not try to load libc on Windows
  • bpo-24798: _msvccompiler.py doesn't properly support manifests
  • bpo-4395: Better testing and documentation of binary operators. Patch by Martin Panter.
  • bpo-23973: Update typing.py from GitHub repo.
  • bpo-23004: mock_open() now reads binary data correctly when the type of read_data is bytes. Initial patch by Aaron Hill.
  • bpo-23888: Handle fractional time in cookie expiry. Patch by ssh.
  • 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: Fix timezones in email.utils.formatdate. Patch from Dmitry Shachnev.
  • bpo-23779: imaplib raises TypeError if authenticator tries to abort. Patch from Craig Holmquist.
  • bpo-23319: Fix ctypes.BigEndianStructure, swap correctly bytes. Patch written by Matthieu Gautier.
  • bpo-23254: Document how to close the TCPServer listening socket. Patch from Martin Panter.
  • bpo-19450: Update Windows and OS X installer builds to use SQLite 3.8.11.
  • bpo-17527: Add PATCH to wsgiref.validator. Patch from Luca Sbardella.
  • bpo-24791: Fix grammar regression for call syntax: 'g(*a or b)'.

IDLE

  • bpo-23672: Allow Idle to edit and run files with astral chars in name. Patch by Mohd Sanad Zaki Rizvi.
  • 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: 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: Idle menus. Remove tearoff lines. Patch by Roger Serwy.

ドキュメント

  • 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: Improve reload() docs. Patch by Dorian Pula.
  • bpo-23589: Remove duplicate sentence from the FAQ. Patch by Yongzhi Pan.
  • bpo-24729: Correct IO tutorial to match implementation regarding encoding parameter to open function.

テスト

  • 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: Restored optimization of bytes.rfind() and bytearray.rfind() for single-byte argument on Linux.
  • bpo-24569: Make PEP 448 dictionary evaluation more consistent.
  • bpo-24583: Fix crash when set is mutated while being updated.
  • bpo-24407: Fix crash when dict is mutated while being updated.
  • 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: Plug refleak on SyntaxError in function parameters annotations.
  • bpo-15944: memoryview: Allow arbitrary formats when casting to bytes. Patch by Martin Panter.

ライブラリ

  • bpo-23441: rcompleter now prints a tab character instead of displaying possible completions for an empty word. Initial patch by Martin Sekera.
  • bpo-24683: Fixed crashes in _json functions called with arguments of inappropriate type.
  • bpo-21697: shutil.copytree() now correctly handles symbolic links that point to directories. Patch by Eduardo Seabra and Thomas Kluyver.
  • bpo-14373: Fixed segmentation fault when gc.collect() is called during constructing lru_cache (C implementation).
  • 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: Random.setstate() now validates the value of state last element.
  • bpo-22485: Fixed an issue that caused inspect.getsource to return incorrect results on nested functions.
  • bpo-22153: Improve unittest docs. Patch from Martin Panter and evilzero.
  • bpo-24580: Symbolic group references to open group in re patterns now are explicitly forbidden as well as numeric group references.
  • bpo-24206: Fixed __eq__ and __ne__ methods of inspect classes.
  • bpo-24631: Fixed regression in the timeit module with multiline setup.
  • bpo-18622: unittest.mock.mock_open().reset_mock would recurse infinitely. Patch from Nicola Palumbo and Laurent De Buyst.
  • 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: chunk.Chunk.read() now always returns bytes, not str.
  • bpo-18684: Fixed reading out of the buffer in the re module.
  • bpo-24259: tarfile now raises a ReadError if an archive is truncated inside a data segment.
  • bpo-15014: SMTP.auth() and SMTP.login() now support RFC 4954's optional initial-response argument to the SMTP AUTH command.
  • bpo-24669: Fix inspect.getsource() for 'async def' functions. Patch by Kai Groner.
  • bpo-24688: ast.get_docstring() for 'async def' functions.

ビルド

  • 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: 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: Add Py_tp_finalize slot for the stable ABI.
  • bpo-24400: Introduce a distinct type for PEP 492 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: Add gi_yieldfrom to generators and cr_await to coroutines. Contributed by Benno Leslie and Yury Selivanov.
  • bpo-19235: Add new RecursionError exception. Patch by Georg Brandl.

ライブラリ

  • bpo-21750: mock_open.read_data can now be read from each instance, as it could in Python 3.3.
  • bpo-24552: Fix use after free in an error case of the _pickle module.
  • bpo-24514: tarfile now tolerates number fields consisting of only whitespace.
  • 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: Restore semantic round-trip correctness in tokenize/untokenize for tab-indented blocks.
  • bpo-24456: Fixed possible buffer over-read in adpcm2lin() and lin2adpcm() functions of the audioop module.
  • bpo-24336: The contextmanager decorator now works with functions with keyword arguments called "func" and "self". Patch by Martin Panter.
  • bpo-24522: Fix possible integer overflow in json accelerator module.
  • bpo-24489: ensure a previously set C errno doesn't disturb cmath.polar().
  • bpo-24408: Fixed AttributeError in measure() and metrics() methods of tkinter.Font.
  • bpo-14373: C implementation of functools.lru_cache() now can be used with methods.
  • bpo-24347: Set KeyError if PyDict_GetItemWithError returns NULL.
  • bpo-24348: Drop superfluous incref/decref.
  • bpo-24359: Check for changed OrderedDict size during iteration.
  • bpo-24368: Support keyword arguments in OrderedDict methods.
  • bpo-24362: Simplify the C OrderedDict fast nodes resize logic.
  • bpo-24377: Fix a ref leak in OrderedDict.__repr__.
  • bpo-24369: Defend against key-changes during iteration.

テスト

  • 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 for details)

ドキュメント

  • bpo-24458: Update documentation to cover multi-phase initialization for extension modules (PEP 489). Patch by Petr Viktorin.
  • bpo-24351: Clarify what is meant by "identifier" in the context of string.Template instances.

ビルド

  • 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: 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: Update uses of PyObject_IsTrue(), PyObject_Not(), PyObject_IsInstance(), PyObject_RichCompareBool() and _PyDict_Contains() to check for and handle errors correctly.
  • bpo-24328: Fix importing one character extension modules.
  • bpo-11205: In dictionary displays, evaluate the key before the value.
  • bpo-24285: Fixed regression that prevented importing extension modules from inside packages. Patch by Petr Viktorin.

ライブラリ

  • bpo-23247: Fix a crash in the StreamWriter.reset() of CJK codecs.
  • bpo-24270: Add math.isclose() and cmath.isclose() functions as per PEP 485. Contributed by Chris Barker and Tal Einat.
  • bpo-5633: Fixed timeit when the statement is a string and the setup is not.
  • bpo-24326: Fixed audioop.ratecv() with non-default weightB argument. Original patch by David Moore.
  • bpo-16991: Add a C implementation of OrderedDict.
  • 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: Fixed optimization of property descriptor getter.
  • bpo-24268: PEP 489: Multi-phase extension module initialization. Patch by Petr Viktorin.
  • bpo-23955: Add pyvenv.cfg option to suppress registry/environment lookup for generating sys.path on Windows.
  • bpo-24257: Fixed system error in the comparison of faked types.SimpleNamespace.
  • bpo-22939: Fixed integer overflow in iterator object. Patch by Clement Rouault.
  • 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: Fixed exception type checking in standard error handlers.
  • bpo-15027: The UTF-32 encoder is now 3x to 7x faster.
  • bpo-23290: Optimize set_merge() for cases where the target is empty. (Contributed by Serhiy Storchaka.)
  • bpo-2292: PEP 448: Additional Unpacking Generalizations.
  • bpo-24096: Make warnings.warn_explicit more robust against mutation of the warnings.filters list.
  • bpo-23996: Avoid a crash when a delegated generator raises an unnormalized StopIteration exception. Patch by Stefan Behnel.
  • bpo-23910: Optimize property() getter calls. Patch by Joe Jevnik.
  • bpo-23911: Move path-based importlib bootstrap code to a separate frozen module.
  • bpo-24192: Fix namespace package imports.
  • bpo-24022: Fix tokenizer crash when processing undecodable source code.
  • bpo-9951: Added a hex() method to bytes, bytearray, and memoryview.
  • bpo-22906: PEP 479: Change StopIteration handling inside generators.
  • bpo-24017: PEP 492: Coroutines with async and await syntax.

ライブラリ

  • bpo-14373: Added C implementation of functools.lru_cache(). Based on patches by Matt Joiner and Alexey Kachayev.
  • 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: collections.UserString now supports __getnewargs__(), __rmod__(), casefold(), format_map(), isprintable(), and maketrans(). Patch by Joe Jevnik.
  • bpo-24244: Prevents termination when an invalid format string is encountered on Windows in strftime.
  • bpo-23973: PEP 484: Add the typing module.
  • bpo-23086: The collections.abc.Sequence() abstract base class added start and stop parameters to the index() mixin. Patch by Devin Jeanpierre.
  • 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: Fixed segmentation fault in sqlite3.Row constructor with faked cursor type.
  • 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: Add missing method stubs to _io.RawIOBase. Patch by Laura Rupprecht.
  • 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: 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: Improved error message in os.path.join() with single argument.
  • bpo-6598: Increased time precision and random number range in email.utils.make_msgid() to strengthen the uniqueness of the message ID.
  • bpo-24091: Fixed various crashes in corner cases in C implementation of ElementTree.
  • 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: quote_via argument added to urllib.parse.urlencode.
  • bpo-20098: New mangle_from policy option for email, default True for compat32, but False for all other policies.
  • bpo-24211: The email library now supports RFC 6532: it can generate headers using utf-8 instead of encoded words.
  • bpo-16314: Added support for the LZMA compression in distutils.
  • bpo-21804: poplib now supports RFC 6856 (UTF8).
  • bpo-18682: Optimized pprint functions for builtin scalar types.
  • bpo-22027: smtplib now supports RFC 6531 (SMTPUTF8).
  • bpo-23488: Random generator objects now consume 2x less memory on 64-bit.
  • bpo-1322: platform.dist() and platform.linux_distribution() functions are now deprecated. Initial patch by Vajrasky Kok.
  • bpo-22486: Added the math.gcd() function. The fractions.gcd() function now is deprecated. Based on patch by Mark Dickinson.
  • bpo-24064: Property() docstrings are now writeable. (Patch by Berker Peksag.)
  • bpo-22681: Added support for the koi8_t encoding.
  • bpo-22682: Added support for the kz1048 encoding.
  • bpo-23796: peek and read1 methods of BufferedReader now raise ValueError if they called on a closed object. Patch by John Hergenroeder.
  • bpo-21795: smtpd now supports the 8BITMIME extension whenever the new decode_data constructor argument is set to False.
  • bpo-24155: optimize heapq.heapify() for better cache performance when heapifying large lists.
  • 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: When calling a _sqlite.Connection, it now complains if passed any keyword arguments. Previously it silently ignored them.
  • bpo-20274: Remove ignored and erroneous "kwargs" parameters from three METH_VARARGS methods on _sqlite.Connection.
  • 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: Add a collections.abc.Generator abstract base class. Contributed by Stefan Behnel.
  • bpo-23880: Tkinter's getint() and getdouble() now support Tcl_Obj. Tkinter's getdouble() now supports any numbers (in particular int).
  • bpo-22619: Added negative limit support in the traceback module. Based on patch by Dmitry Kazakov.
  • bpo-24094: Fix possible crash in json.encode with poorly behaved dict subclasses.
  • bpo-9246: On POSIX, os.getcwd() now supports paths longer than 1025 bytes. Patch written by William Orr.
  • bpo-17445: add difflib.diff_bytes() to support comparison of byte strings (fixes a regression from Python 2).
  • bpo-23917: Fall back to sequential compilation when ProcessPoolExecutor doesn't exist. Patch by Claudiu Popa.
  • 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: os functions now reject paths with embedded null character on Windows instead of silently truncating them.
  • bpo-23728: binascii.crc_hqx() could return an integer outside of the range 0-0xffff for empty data.
  • 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: asyncio.Lock, Condition, Semaphore, and BoundedSemaphore support new 'async with' syntax. Contributed by Yury Selivanov.
  • bpo-24179: Support 'async for' for asyncio.StreamReader. Contributed by Yury Selivanov.
  • bpo-24184: Add AsyncIterator and AsyncIterable ABCs to collections.abc. Contributed by Yury Selivanov.
  • bpo-22547: Implement informative __repr__ for inspect.BoundArguments. Contributed by Yury Selivanov.
  • bpo-24190: Implement inspect.BoundArgument.apply_defaults() method. Contributed by Yury Selivanov.
  • bpo-20691: Add 'follow_wrapped' argument to inspect.Signature.from_callable() and inspect.signature(). Contributed by Yury Selivanov.
  • bpo-24248: Deprecate inspect.Signature.from_function() and inspect.Signature.from_builtin().
  • bpo-23898: Fix inspect.classify_class_attrs() to support attributes with overloaded __eq__ and __bool__. Patch by Mike Bayer.
  • bpo-24298: Fix inspect.signature() to correctly unwrap wrappers around bound methods.

IDLE

  • bpo-23184: remove unused names and imports in idlelib. Initial patch by Al Sweigart.

テスト

  • bpo-21520: test_zipfile no longer fails if the word 'bad' appears anywhere in the name of the current directory.
  • bpo-9517: Move script_helper into the support package. Patch by Christie Wilson.

ドキュメント

  • bpo-22155: Add File Handlers subsection with createfilehandler to tkinter doc. Remove obsolete example from FAQ. Patch by Martin Panter.
  • bpo-24029: Document the name binding behavior for submodule imports.
  • bpo-24077: Fix typo in man page for -I command option: -s, not -S

Tools/Demos

  • bpo-24000: Improved Argument Clinic's mapping of converters to legacy "format units". Updated the documentation to match.
  • bpo-24001: Argument Clinic converters now use accept={type} instead of types={'type'} to specify the types the converter accepts.
  • bpo-23330: h2py now supports arbitrary filenames in #include.
  • 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: 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-style information.
  • bpo-22631: Added Linux-specific socket constant CAN_RAW_FD_FRAMES. Patch courtesy of Joe Jevnik.
  • bpo-23731: Implement PEP 488: removal of .pyo files.
  • 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: 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: Fixed formatting Windows error messages on Wine. Patch by Martin Panter.
  • bpo-23466: %c, %o, %x, and %X in bytes formatting now raise TypeError on non-integer input.
  • bpo-24044: Fix possible null pointer dereference in list.sort in out of memory conditions.
  • bpo-21354: PyCFunction_New function is exposed by python DLL again.

ライブラリ

  • bpo-23840: tokenize.open() now closes the temporary binary file on error to fix a resource warning.
  • bpo-16914: new debuglevel 2 in smtplib adds timestamps to debug output.
  • 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 and supersedes that change.
  • bpo-23703: Fix a regression in urljoin() introduced in 901e4e52b20a. Patch by Demian Brecht.
  • bpo-4254: Adds _curses.update_lines_cols(). Patch by Arnon Yaari
  • bpo-19933: Provide default argument for ndigits in round. Patch by Vajrasky Kok.
  • bpo-23193: Add a numeric_owner parameter to tarfile.TarFile.extract and tarfile.TarFile.extractall. Patch by Michael Vogt and Eric Smith.
  • bpo-23342: Add a subprocess.run() function than returns a CalledProcess instance for a more consistent API than the existing call* functions.
  • 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: Fix possible integer overflows in the pickle module.
  • bpo-22931: Allow '[' and ']' in cookie values.
  • The keywords attribute of functools.partial is now always a dictionary.
  • bpo-23811: Add missing newline to the PyCompileError error message. Patch by Alex Shkop.
  • 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: Improve BOM handling when seeking to multiple positions of a writable text file.
  • bpo-23464: Removed deprecated asyncio JoinableQueue.
  • 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: Added Python implementation of io.FileIO.
  • 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: Raise same exception on both Python 2 and 3 if sem_open is not available. Patch by Davin Potts.
  • 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: Added DefragResult, ParseResult, SplitResult, DefragResultBytes, ParseResultBytes, and SplitResultBytes to urllib.parse.__all__. Patch by Martin Panter.
  • bpo-23881: urllib.request.ftpwrapper constructor now closes the socket if the FTP connection failed to fix a ResourceWarning.
  • 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: 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: _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: xml.sax.parseString() now supports string argument.
  • bpo-23338: Fixed formatting ctypes error messages on Cygwin. Patch by Makoto Kato.
  • bpo-15582: inspect.getdoc() now follows inheritance chains.
  • bpo-2175: SAX parsers now support a character stream of InputSource object.
  • bpo-16840: Tkinter now supports 64-bit integers added in Tcl 8.4 and arbitrary precision integers added in Tcl 8.5.
  • 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: 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: Tkinter now supports new boolean type in Tcl 8.5.
  • bpo-23836: Fix the faulthandler module to handle reentrant calls to its signal handlers.
  • bpo-23838: linecache now clears the cache and returns an empty result on MemoryError.
  • bpo-10395: Added os.path.commonpath(). Implemented in posixpath and ntpath. Based on patch by Rafik Draoui.
  • bpo-23611: Serializing more "lookupable" objects (such as unbound methods or nested classes) now are supported with pickle protocols < 4.
  • bpo-13583: sqlite3.Row now supports slice indexing.
  • 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: 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.
  • 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: collections.deque() objects now support __add__, __mul__, and __imul__().
  • bpo-23171: csv.Writer.writerow() now supports arbitrary iterables.
  • bpo-23745: The new email header parser now handles duplicate MIME parameter names without error, similar to how get_param behaves.
  • bpo-22117: Fix os.utime(), it now rounds the timestamp towards minus infinity (-inf) instead of rounding towards zero.
  • bpo-23310: Fix MagicMock's initializer to work with __methods__, just like configure_mock(). Patch by Kasia Jachim.

ビルド

  • bpo-23817: FreeBSD now uses "1.0" in the SOVERSION as other operating systems, instead of just "1".
  • bpo-23501: Argument Clinic now generates code into separate files by default.

テスト

  • bpo-23799: Added test.support.start_threads() for running and cleaning up multiple threads.
  • bpo-22390: test.regrtest now emits a warning if temporary files or directories are left after running a test.

Tools/Demos

  • bpo-18128: pygettext now uses standard +NNNN format in the POT-Creation-Date header.
  • 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: Argument Clinic now wraps long impl prototypes at column 78.
  • bpo-20586: Argument Clinic now ensures that functions without docstrings have signatures.
  • bpo-23492: Argument Clinic now generates argument parsing code with PyArg_Parse instead of PyArg_ParseTuple if possible.
  • 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: PyImport_ReInitLock() now checks for lock allocation error

Python 3.5.0 alpha 3

Release date: 2015-03-28

Core and Builtins

  • 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: Python doesn't support anymore platforms without stat() or fstat(), these functions are always required.
  • bpo-23681: The -b option now affects comparisons of bytes with int.
  • bpo-23632: Memoryviews now allow tuple indexing (including for multi-dimensional memoryviews).
  • bpo-23192: Fixed generator lambdas. Patch by Bruno Cauet.
  • bpo-23629: Fix the default __sizeof__ implementation for variable-sized objects.

ライブラリ

  • bpo-14260: The groupindex attribute of regular expression pattern object now is non-modifiable mapping.
  • 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: pprint() of OrderedDict now outputs the same representation as repr().
  • bpo-23765: Removed IsBadStringPtr calls in ctypes
  • bpo-22364: Improved some re error messages using regex for hints.
  • bpo-23742: ntpath.expandvars() no longer loses unbalanced single quotes.
  • bpo-21717: The zipfile.ZipFile.open function now supports 'x' (exclusive creation) mode.
  • bpo-21802: The reader in BufferedRWPair now is closed even when closing writer failed in BufferedRWPair.close().
  • 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: 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: The pprint module now supports mapping proxies.
  • bpo-17530: pprint now wraps long bytes objects and bytearrays.
  • bpo-22687: Fixed some corner cases in breaking words in tetxtwrap. Got rid of quadratic complexity in breaking long words.
  • 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: 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: Avoid explicit checks for str in zipapp, adding support for pathlib.Path objects as arguments.
  • 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: Added support for writing ZIP files to unseekable streams.
  • bpo-23647: Increase imaplib's MAXLINE to accommodate modern mailbox sizes.
  • 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: 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: 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: 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: 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: 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: _strptime now uniformly handles all days in week 0, including Dec 30 of previous year. Based on patch by Jim Carroll.
  • bpo-23700: Iterator of NamedTemporaryFile now keeps a reference to NamedTemporaryFile instance. Patch by Bohuslav Kabrda.
  • bpo-22903: The fake test case created by unittest.loader when it fails importing a test module is now picklable.
  • 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: 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: Allow selection of output units in timeit. Patch by Julian Gindi.
  • bpo-23631: Fix traceback.format_list when a traceback has been mutated.
  • bpo-23568: Add rdivmod support to MagicMock() objects. Patch by Håkan Lövdahl.
  • bpo-2052: Add charset parameter to HtmlDiff.make_file().
  • bpo-23668: Support os.truncate and os.ftruncate on Windows.
  • bpo-23138: Fixed parsing cookies with absent keys or values in cookiejar. Patch by Demian Brecht.
  • 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: Add matmul support to MagicMock. Patch by Håkan Lövdahl.
  • bpo-23566: enable(), register(), dump_traceback() and dump_traceback_later() functions of faulthandler now accept file descriptors. Patch by Wei Wu.
  • bpo-22928: Disabled HTTP header injections in http.client. Original patch by Demian Brecht.
  • bpo-23615: Modules bz2, tarfile and tokenize now can be reloaded with imp.reload(). Patch by Thomas Kluyver.
  • 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.

ビルド

  • bpo-23585: make patchcheck will ensure the interpreter is built.

テスト

  • bpo-23583: Added tests for standard IO streams in IDLE.
  • bpo-22289: Prevent test_urllib2net failures due to ftp connection timeout.

Tools/Demos

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

ライブラリ

  • bpo-22524: New os.scandir() function, part of the PEP 471: "os.scandir() function -- a better and faster directory iterator". Patch written by Ben Hoyt.

  • bpo-23103: Reduced the memory consumption of IPv4Address and IPv6Address.

  • bpo-21793: BaseHTTPRequestHandler again logs response code as numeric, not as stringified enum. Patch by Demian Brecht.

  • bpo-23476: In the ssl module, enable OpenSSL's X509_V_FLAG_TRUSTED_FIRST flag on certificate stores when it is available.

  • 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: Added an __all__ to the types module.

  • bpo-23563: Optimized utility functions in urllib.parse.

  • bpo-7830: Flatten nested functools.partial.

  • bpo-20204: Added the __module__ attribute to _tkinter classes.

  • 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: Corrected pure python implementation of timedelta division.

    Eliminated OverflowError from timedelta * float for some floats; Corrected rounding in timedelta true division.

  • 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: Make it possible to show local variables in tracebacks for both the traceback module and unittest.

  • bpo-15955: Add an option to limit the output size in bz2.decompress(). Patch by Nikolaus Rath.

  • bpo-6639: Module-level turtle functions no longer raise TclError after closing the window.

  • bpo-814253: Group references and conditional group references now work in lookbehind assertions in regular expressions. (See also: bpo-9179)

  • 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: io.FileIO() called flush() after closing the file. flush() was not called in close() if closefd=False.

  • bpo-23374: Fixed pydoc failure with non-ASCII files when stdout encoding differs from file system encoding (e.g. on Mac OS).

  • bpo-23481: Remove RC4 from the SSL module's default cipher list.

  • bpo-21548: Fix pydoc.synopsis() and pydoc.apropos() on modules with empty docstrings.

  • bpo-22885: Fixed arbitrary code execution vulnerability in the dbm.dumb module. Original patch by Claudiu Popa.

  • bpo-23239: ssl.match_hostname() now supports matching of IP addresses.

  • bpo-23146: Fix mishandling of absolute Windows paths with forward slashes in pathlib.

  • bpo-23096: Pickle representation of floats with protocol 0 now is the same for both Python and C implementations.

  • bpo-19105: pprint now more efficiently uses free space at the right.

  • bpo-14910: Add allow_abbrev parameter to argparse.ArgumentParser. Patch by Jonathan Paugh, Steven Bethard, paul j3 and Daniel Eriksson.

  • bpo-21717: tarfile.open() now supports 'x' (exclusive creation) mode.

  • bpo-23344: marshal.dumps() is now 20-25% faster on average.

  • bpo-20416: marshal.dumps() with protocols 3 and 4 is now 40-50% faster on average.

  • bpo-23421: Fixed compression in tarfile CLI. Patch by wdv4758h.

  • bpo-23367: Fix possible overflows in the unicodedata module.

  • 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: turtledemo now has a visual sorting algorithm demo. Original patch from Jason Yeo.

  • bpo-23801: Fix issue where cgi.FieldStorage did not always ignore the entire preamble to a multipart body.

ビルド

  • bpo-23445: pydebug builds now use "gcc -Og" where possible, to make the resulting executable faster.
  • bpo-23686: Update OS X 10.5 installer build to use OpenSSL 1.0.2a.

C API

  • bpo-20204: Deprecation warning is now raised for builtin types without the __module__ attribute.

Windows

  • bpo-23465: Implement PEP 486 - Make the Python Launcher aware of virtual environments. Patch by Paul Moore.
  • 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: PEP 475 - EINTR handling.
  • bpo-22735: Fix many edge cases (including crashes) involving custom mro() implementations.
  • bpo-22896: Avoid using PyObject_AsCharBuffer(), PyObject_AsReadBuffer() and PyObject_AsWriteBuffer().
  • bpo-21295: Revert some changes (bpo-16795) to AST line numbers and column offsets that constituted a regression.
  • bpo-22986: Allow changing an object's __class__ between a dynamic type and static type in some cases.
  • 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: The default __ne__() now returns NotImplemented if __eq__() returned NotImplemented. Original patch by Martin Panter.
  • bpo-23321: Fixed a crash in str.decode() when error handler returned replacement string longer than malformed input data.
  • bpo-22286: The "backslashreplace" error handlers now works with decoding and translating.
  • bpo-23253: Delay-load ShellExecute[AW] in os.startfile for reduced startup overhead on Windows.
  • 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: %-interpolation (aka printf) formatting added for bytes and bytearray.
  • bpo-23048: Fix jumping out of an infinite while loop in the pdb.
  • 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: If the current working directory ends up being set to a non-existent directory then import will no longer raise FileNotFoundError.
  • bpo-22869: Move the interpreter startup & shutdown code to a new dedicated pylifecycle.c module
  • bpo-22847: Improve method cache efficiency.
  • bpo-22335: Fix crash when trying to enlarge a bytearray to 0x7fffffff bytes on a 32-bit platform.
  • bpo-22653: Fix an assertion failure in debug mode when doing a reentrant dict insertion in debug mode.
  • bpo-22643: Fix integer overflow in Unicode case operations (upper, lower, title, swapcase, casefold).
  • bpo-17636: Circular imports involving relative imports are now supported.
  • bpo-22604: Fix assertion error in debug mode when dividing a complex number by (nan+0j).
  • bpo-21052: Do not raise ImportWarning when sys.path_hooks or sys.meta_path are set to None.
  • 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: Fixed integer overflow issues in "backslashreplace", "xmlcharrefreplace", and "surrogatepass" error handlers.
  • bpo-22540: speed up PyObject_IsInstance and PyObject_IsSubclass in the common case that the second argument has metaclass type.
  • bpo-18711: Add a new PyErr_FormatV function, similar to PyErr_Format but accepting a va_list argument.
  • bpo-22520: Fix overflow checking when generating the repr of a unicode object.
  • bpo-22519: Fix overflow checking in PyBytes_Repr.
  • bpo-22518: Fix integer overflow issues in latin-1 encoding.
  • bpo-16324: _charset parameter of MIMEText now also accepts email.charset.Charset instances. Initial patch by Claude Paroz.
  • bpo-1764286: Fix inspect.getsource() to support decorated functions. Patch by Claudiu Popa.
  • bpo-18554: os.__all__ includes posix functions.
  • bpo-21391: Use os.path.abspath in the shutil module.
  • 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: Now ValueError is raised instead of TypeError when str or bytes argument contains not permitted null character or byte.
  • 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: Displaying the __qualname__ of the underlying function in the repr of a bound method.
  • bpo-22206: Using pthread, PyThread_create_key() now sets errno to ENOMEM and returns -1 (error) on integer overflow.
  • bpo-20184: Argument Clinic based signature introspection added for 30 of the builtin functions.
  • bpo-22116: C functions and methods (of the 'builtin_function_or_method' type) can now be weakref'ed. Patch by Wei Wu.
  • 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: Apply Argument Clinic to bytes and bytearray. Patch by Tal Einat.
  • bpo-22082: Clear interned strings in slotdefs.
  • Upgrade Unicode database to Unicode 7.0.0.
  • bpo-21897: Fix a crash with the f_locals attribute with closure variables when frame.clear() has been called.
  • 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: 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: 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: 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: Fix a crash in the builtin function super() when called without argument and without current frame (ex: embedded Python).
  • bpo-21425: Fix flushing of standard streams in the interactive interpreter.
  • 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: PyBytes_Concat() now tries to concatenate in-place when the first argument has a reference count of 1. Patch by Nikolaus Rath.
  • bpo-20355: -W command line options now have higher priority than the PYTHONWARNINGS environment variable. Patch by Arfrever.
  • bpo-21274: Define PATH_MAX for GNU/Hurd in Python/pythonrun.c.
  • bpo-20904: Support setting FPU precision on m68k.
  • bpo-21209: Fix sending tuples to custom generator objects with the yield from syntax.
  • bpo-21193: pow(a, b, c) now raises ValueError rather than TypeError when b is negative. Patch by Josh Rosenberg.
  • bpo-21176: PEP 465: Add the '@' operator for matrix multiplication.
  • bpo-21134: Fix segfault when str is called on an uninitialized UnicodeEncodeError, UnicodeDecodeError, or UnicodeTranslateError object.
  • bpo-19537: Fix PyUnicode_DATA() alignment under m68k. Patch by Andreas Schwab.
  • bpo-20929: Add a type cast to avoid shifting a negative number.
  • bpo-20731: Properly position in source code files even if they are opened in text mode. Patch by Serhiy Storchaka.
  • bpo-20637: Key-sharing now also works for instance dictionaries of subclasses. Patch by Peter Ingebretson.
  • bpo-8297: Attributes missing from modules now include the module name in the error text. Original patch by ysj.ray.
  • bpo-19995: %c, %o, %x, and %X now raise TypeError on non-integer input.
  • 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: Allow \x00 to be used as a fill character when using str, int, float, and complex __format__ methods.
  • bpo-20480: Add ipaddress.reverse_pointer. Patch by Leon Weber.
  • 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: 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: Perform overflow checks before allocating memory in the _Py_char2wchar function.

ライブラリ

  • bpo-23399: pyvenv creates relative symlinks where possible.
  • bpo-20289: cgi.FieldStorage() now supports the context management protocol.
  • bpo-13128: Print response headers for CONNECT requests when debuglevel > 0. Patch by Demian Brecht.
  • bpo-15381: Optimized io.BytesIO to make less allocations and copyings.
  • 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: Closing io.BytesIO with exported buffer is rejected now to prevent corrupting exported buffer.
  • bpo-23326: Removed __ne__ implementations. Since fixing default __ne__ implementation in bpo-21408 they are redundant.
  • bpo-23363: Fix possible overflow in itertools.permutations.
  • bpo-23364: Fix possible overflow in itertools.product.
  • bpo-23366: Fixed possible integer overflow in itertools.combinations.
  • bpo-23369: Fixed possible integer overflow in _json.encode_basestring_ascii.
  • 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: Restored support of writing ZIP files to tellable but non-seekable streams.
  • bpo-14099: Writing to ZipFile and reading multiple ZipExtFiles is threadsafe now.
  • bpo-19361: JSON decoder now raises JSONDecodeError instead of ValueError.
  • bpo-18518: timeit now rejects statements which can't be compiled outside a function or a loop (e.g. "return" or "break").
  • bpo-23094: Fixed readline with frames in Python implementation of pickle.
  • bpo-23268: Fixed bugs in the comparison of ipaddress classes.
  • bpo-21408: Removed incorrect implementations of __ne__() which didn't returned NotImplemented if __eq__() returned NotImplemented. The default __ne__() now works correctly.
  • bpo-19996: email.feedparser.FeedParser now handles (malformed) headers with no key rather than assuming the body has started.
  • bpo-20188: Support Application-Layer Protocol Negotiation (ALPN) in the ssl module.
  • bpo-23133: Pickling of ipaddress objects now produces more compact and portable representation.
  • bpo-23248: Update ssl error codes from latest OpenSSL git master.
  • bpo-23266: Much faster implementation of ipaddress.collapse_addresses() when there are many non-consecutive addresses.
  • bpo-23098: 64-bit dev_t is now supported in the os module.
  • 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: Add an option to limit output size when decompressing LZMA data. Patch by Nikolaus Rath and Martin Panter.
  • bpo-23250: In the http.cookies module, capitalize "HttpOnly" and "Secure" as they are written in the standard.
  • bpo-23063: In the distutils' check command, fix parsing of reST with code or code-block directives.
  • 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)
  • bpo-17911: Provide a way to seed the linecache for a PEP-302 module without actually loading the code.
  • 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: Provide a home() classmethod on Path objects. Contributed by Victor Salgado and Mayank Tripathi.
  • bpo-23206: Make json.dumps(..., ensure_ascii=False) as fast as the default case of ensure_ascii=True. Patch by Naoki Inada.
  • bpo-23185: Add math.inf and math.nan constants.
  • bpo-23186: Add ssl.SSLObject.shared_ciphers() and ssl.SSLSocket.shared_ciphers() to fetch the client's list ciphers sent at handshake.
  • bpo-23143: Remove compatibility with OpenSSLs older than 0.9.8.
  • bpo-23132: Improve performance and introspection support of comparison methods created by functool.total_ordering.
  • bpo-19776: Add an expanduser() method on Path objects.
  • bpo-23112: Fix SimpleHTTPServer to correctly carry the query string and fragment when it redirects to add a trailing slash.
  • bpo-21793: Added http.HTTPStatus enums (i.e. HTTPStatus.OK, HTTPStatus.NOT_FOUND). Patch by Demian Brecht.
  • bpo-23093: In the io, module allow more operations to work on detached streams.
  • bpo-23111: In the ftplib, make ssl.PROTOCOL_SSLv23 the default protocol version.
  • 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: pprint now produces evaluable output for wrapped strings.
  • bpo-23071: Added missing names to codecs.__all__. Patch by Martin Panter.
  • bpo-22783: Pickling now uses the NEWOBJ opcode instead of the NEWOBJ_EX opcode if possible.
  • bpo-15513: Added a __sizeof__ implementation for pickle classes.
  • 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: Fixed HTTPConnection.set_tunnel with default port. The port value in the host header was set to "None". Patch by Demian Brecht.
  • bpo-23016: A warning no longer produces an AttributeError when the program is run with pythonw.exe.
  • 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: Fix inspect.getsource() to load updated source of reloaded module. Initial patch by Berker Peksag.
  • bpo-21740: Support wrapped callables in doctest. Patch by Claudiu Popa.
  • bpo-23009: Make sure selectors.EpollSelecrtor.select() works when no FD is registered.
  • bpo-22959: In the constructor of http.client.HTTPSConnection, prefer the context's check_hostname attribute over the check_hostname parameter.
  • bpo-22696: Add function sys.is_finalizing() to know about interpreter shutdown.
  • bpo-16043: Add a default limit for the amount of data xmlrpclib.gzip_decode will return. This resolves CVE-2013-1753.
  • 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: 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: Update turtledemo doc and add module to the index.
  • bpo-21032: Fixed socket leak if HTTPConnection.getresponse() fails. Original patch by Martin Panter.
  • bpo-22407: Deprecated the use of re.LOCALE flag with str patterns or re.ASCII. It was newer worked.
  • bpo-22902: The "ip" command is now used on Linux to determine MAC address in uuid.getnode(). Pach by Bruno Cauet.
  • bpo-22960: Add a context argument to xmlrpclib.ServerProxy constructor.
  • bpo-22389: Add contextlib.redirect_stderr().
  • 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: SAX parser now supports files opened with file descriptor or bytes path.
  • bpo-22609: Constructors and update methods of mapping classes in the collections module now accept the self keyword argument.
  • bpo-22940: Add readline.append_history_file.
  • bpo-19676: Added the "namereplace" error handler.
  • bpo-22788: Add context parameter to logging.handlers.HTTPHandler.
  • bpo-22921: Allow SSLContext to take the hostname parameter even if OpenSSL doesn't support SNI.
  • bpo-22894: TestCase.subTest() would cause the test suite to be stopped when in failfast mode, even in the absence of failures.
  • bpo-22796: HTTP cookie parsing is now stricter, in order to protect against potential injection attacks.
  • bpo-22370: Windows detection in pathlib is now more robust.
  • bpo-22841: Reject coroutines in asyncio add_signal_handler(). Patch by Ludovic.Gasc.
  • bpo-19494: Added urllib.request.HTTPBasicPriorAuthHandler. Patch by Matej Cepl.
  • bpo-22578: Added attributes to the re.error class.
  • bpo-22849: Fix possible double free in the io.TextIOWrapper constructor.
  • bpo-12728: Different Unicode characters having the same uppercase but different lowercase are now matched in case-insensitive regular expressions.
  • bpo-22821: Fixed fcntl() with integer argument on 64-bit big-endian platforms.
  • bpo-21650: Add an --sort-keys option to json.tool CLI.
  • bpo-22824: Updated reprlib output format for sets to use set literals. Patch contributed by Berker Peksag.
  • bpo-22824: Updated reprlib output format for arrays to display empty arrays without an unnecessary empty list. Suggested by Serhiy Storchaka.
  • bpo-22406: Fixed the uu_codec codec incorrectly ported to 3.x. Based on patch by Martin Panter.
  • bpo-17293: uuid.getnode() now determines MAC address on AIX using netstat. Based on patch by Aivars Kalvāns.
  • bpo-22769: Fixed ttk.Treeview.tag_has() when called without arguments.
  • bpo-22417: Verify certificates by default in httplib (PEP 476).
  • bpo-22775: Fixed unpickling of http.cookies.SimpleCookie with protocol 2 and above. Patch by Tim Graham.
  • bpo-22776: Brought excluded code into the scope of a try block in SysLogHandler.emit().
  • bpo-22665: Add missing get_terminal_size and SameFileError to shutil.__all__.
  • bpo-6623: Remove deprecated Netrc class in the ftplib module. Patch by Matt Chaput.
  • bpo-17381: Fixed handling of case-insensitive ranges in regular expressions.
  • bpo-22410: Module level functions in the re module now cache compiled locale-dependent regular expressions taking into account the locale.
  • bpo-22759: Query methods on pathlib.Path() (exists(), is_dir(), etc.) now return False when the underlying stat call raises NotADirectoryError.
  • 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: Implemented reprs of classes in the zipfile module.
  • bpo-22457: Honour load_tests in the start_dir of discovery.
  • bpo-18216: gettext now raises an error when a .mo file has an unsupported major version number. Patch by Aaron Hill.
  • 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: Make the pickling of global objects which don't have a __module__ attribute less slow.
  • bpo-18853: Fixed ResourceWarning in shlex.__nain__.
  • bpo-9351: Defaults set with set_defaults on an argparse subparser are no longer ignored when also set on the parent parser.
  • 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: 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: 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: SSLv3 is now disabled throughout the standard library. It can still be enabled by instantiating a SSLContext manually.
  • bpo-22641: In asyncio, the default SSL context for client connections is now created using ssl.create_default_context(), for stronger security.
  • bpo-17401: Include closefd in io.FileIO repr.
  • 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: Convert the array and cmath modules to Argument Clinic.
  • bpo-18643: Add socket.socketpair() on Windows.
  • bpo-22435: Fix a file descriptor leak when socketserver bind fails.
  • bpo-13096: Fixed segfault in CTypes POINTER handling of large values.
  • bpo-11694: Raise ConversionError in xdrlib as documented. Patch by Filip Gruszczyński and Claudiu Popa.
  • bpo-19380: Optimized parsing of regular expressions.
  • bpo-1519638: Now unmatched groups are replaced with empty strings in re.sub() and re.subn().
  • bpo-18615: sndhdr.what/whathdr now return a namedtuple.
  • bpo-22462: Fix pyexpat's creation of a dummy frame to make it appear in exception tracebacks.
  • bpo-21965: Add support for in-memory SSL to the ssl module. Patch by Geert Jansen.
  • bpo-21173: Fix len() on a WeakKeyDictionary when .clear() was called with an iterator alive.
  • bpo-11866: Eliminated race condition in the computation of names for new threads.
  • bpo-21905: Avoid RuntimeError in pickle.whichmodule() when sys.modules is mutated while iterating. Patch by Olivier Grisel.
  • 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: 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: The zipfile module CLI now adds entries for directories (including empty directories) in ZIP file.
  • bpo-22449: In the ssl.SSLContext.load_default_certs, consult the environmental variables SSL_CERT_DIR and SSL_CERT_FILE on Windows.
  • 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: Added non derived UTF-8 aliases to locale aliases table.
  • bpo-20079: Added locales supported in glibc 2.18 to locale alias table.
  • bpo-20218: Added convenience methods read_text/write_text and read_bytes/ write_bytes to pathlib.Path objects.
  • 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: When an io.BufferedRWPair object is deallocated, clear its weakrefs.
  • bpo-22437: Number of capturing groups in regular expression is no longer limited by 100.
  • bpo-17442: InteractiveInterpreter now displays the full chained traceback in its showtraceback method, to match the built in interactive interpreter.
  • bpo-23392: Added tests for marshal C API that works with FILE*.
  • bpo-10510: distutils register and upload methods now use HTML standards compliant CRLF line endings.
  • bpo-9850: Fixed macpath.join() for empty first component. Patch by Oleg Oshmyan.
  • bpo-5309: distutils' build and build_ext commands now accept a -j option to enable parallel building of extension modules.
  • bpo-22448: Improve canceled timer handles cleanup to prevent unbound memory usage. Patch by Joshua Moore-Oliva.
  • bpo-22427: TemporaryDirectory no longer attempts to clean up twice when used in the with statement in generator.
  • bpo-22362: Forbidden ambiguous octal escapes out of range 0-0o377 in regular expressions.
  • bpo-20912: Now directories added to ZIP file have correct Unix and MS-DOS directory attributes.
  • bpo-21866: ZipFile.close() no longer writes ZIP64 central directory records if allowZip64 is false.
  • bpo-22278: Fix urljoin problem with relative urls, a regression observed after changes to issue22118 were submitted.
  • bpo-22415: Fixed debugging output of the GROUPREF_EXISTS opcode in the re module. Removed trailing spaces in debugging output.
  • bpo-22423: Unhandled exception in thread no longer causes unhandled AttributeError when sys.stderr is None.
  • bpo-21332: Ensure that bufsize=1 in subprocess.Popen() selects line buffering, rather than block buffering. Patch by Akira Li.
  • bpo-21091: Fix API bug: email.message.EmailMessage.is_attachment is now a method.
  • 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: Add NNTPError to nntplib.__all__.
  • 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: The warnings registries are now reset when the filters are modified.
  • 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: 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: An exception in Tkinter callback no longer crashes the program when it is run with pythonw.exe.
  • bpo-22168: Prevent turtle AttributeError with non-default Canvas on OS X.
  • 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: The glob module now supports recursive search in subdirectories using the ** pattern.
  • bpo-21951: Fixed a crash in Tkinter on AIX when called Tcl command with empty string or tuple argument.
  • bpo-21951: Tkinter now most likely raises MemoryError instead of crash if the memory allocation fails.
  • bpo-22338: Fix a crash in the json module on memory allocation failure.
  • bpo-12410: imaplib.IMAP4 now supports the context management protocol. Original patch by Tarek Ziadé.
  • bpo-21270: We now override tuple methods in mock.call objects so that they can be used as normal call attributes.
  • 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: First letter no longer is stripped from the "status" key in the result of Treeview.heading().
  • bpo-19524: Fixed resource leak in the HTTP connection when an invalid response is received. Patch by Martin Panter.
  • bpo-20421: Add a .version() method to SSL sockets exposing the actual protocol version in use.
  • bpo-19546: configparser exceptions no longer expose implementation details. Chained KeyErrors are removed, which leads to cleaner tracebacks. Patch by Claudiu Popa.
  • 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: 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: 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: Turtledemo buttons no longer disappear when the window is shrunk. Original patches by Jan Kanis and Lita Cho.
  • 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: Add a default number of workers to ThreadPoolExecutor equal to 5 times the number of CPUs. Patch by Claudiu Popa.
  • 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: 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: 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: 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: 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: signal.set_wakeup_fd(fd) now raises an exception if the file descriptor is in blocking mode.
  • bpo-16808: inspect.stack() now returns a named tuple instead of a tuple. Patch by Daniel Shahaf.
  • bpo-22236: Fixed Tkinter images copying operations in NoDefaultRoot mode.
  • 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: 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: Added the "members" parameter to TarFile.list().
  • bpo-19628: Allow compileall recursion depth to be specified with a -r option.
  • bpo-15696: Add a __sizeof__ implementation for mmap objects on Windows.
  • bpo-22068: Avoided reference loops with Variables and Fonts in Tkinter.
  • bpo-22165: SimpleHTTPRequestHandler now supports undecodable file names.
  • bpo-15381: Optimized line reading in io.BytesIO.
  • bpo-8797: Raise HTTPError on failed Basic Authentication immediately. Initial patch by Sam Bull.
  • bpo-20729: Restored the use of lazy iterkeys()/itervalues()/iteritems() in the mailbox module.
  • bpo-21448: Changed FeedParser feed() to avoid O(N**2) behavior when parsing long line. Original patch by Raymond Hettinger.
  • 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: glob() patterns ending with a slash no longer match non-dirs on AIX. Based on patch by Delhallt.
  • bpo-21725: Added support for RFC 6531 (SMTPUTF8) in smtpd.
  • 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: Added support for the "xztar" format in the shutil module.
  • bpo-21121: Don't force 3rd party C extensions to be built with -Werror=declaration-after-statement.
  • 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: Convert posixmodule to use Argument Clinic.
  • 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: Bypass IDNA for pure-ASCII host names in the socket module (in particular for numeric IPs).
  • 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: the strict mode and argument of HTMLParser, HTMLParser.error, and the HTMLParserError exception have been removed.
  • bpo-22085: Dropped support of Tk 8.3 in Tkinter.
  • bpo-21580: Now Tkinter correctly handles bytes arguments passed to Tk. In particular this allows initializing images from binary data.
  • 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: On Windows, signal.set_wakeup_fd() now also supports sockets. A side effect is that Python depends to the WinSock library.
  • 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: Make turtledemo start as active on OS X even when run with subprocess. Patch by Lita Cho.
  • bpo-21704: Fix build error for _multiprocessing when semaphores are not available. Patch by Arfrever Frehtes Taifersar Arahesis.
  • 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: Reprs of most Python implemented classes now contain actual class name instead of hardcoded one.
  • bpo-21947: The dis module can now disassemble generator-iterator objects based on their gi_code attribute. Patch by Clement Rouault.
  • bpo-16133: The asynchat.async_chat.handle_read() method now ignores BlockingIOError exceptions.
  • bpo-22044: Fixed premature DECREF in call_tzinfo_method. Patch by Tom Flanagan.
  • 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: Removed a number of out-of-dated and non-working for a long time Tkinter methods.
  • 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: Clean up and speed up the ntpath module.
  • bpo-21888: plistlib's load() and loads() now work if the fmt parameter is specified.
  • bpo-22032: __qualname__ instead of __name__ is now always used to format fully qualified class names of Python implemented classes.
  • bpo-22031: Reprs now always use hexadecimal format with the "0x" prefix when contain an id in form " at 0x...".
  • bpo-22018: signal.set_wakeup_fd() now raises an OSError instead of a ValueError on fstat() failure.
  • bpo-21044: tarfile.open() now handles fileobj with an integer 'name' attribute. Based on patch by Antoine Pietri.
  • bpo-21966: Respect -q command-line option when code module is ran.
  • bpo-19076: Don't pass the redundant 'file' argument to self.error().
  • bpo-16382: Improve exception message of warnings.warn() for bad category. Initial patch by Phil Elson.
  • 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: Fixed source file viewing in pydoc's server mode on Windows.
  • bpo-11259: asynchat.async_chat().set_terminator() now raises a ValueError if the number of received bytes is negative.
  • bpo-12523: asynchat.async_chat.push() now raises a TypeError if it doesn't get a bytes string
  • bpo-21707: Add missing kwonlyargcount argument to ModuleFinder.replace_paths_in_code().
  • bpo-20639: calling Path.with_suffix('') allows removing the suffix again. Patch by July Tikhonov.
  • bpo-21714: Disallow the construction of invalid paths using Path.with_name(). Original patch by Antony Lee.
  • bpo-15014: Added 'auth' method to smtplib to make implementing auth mechanisms simpler, and used it internally in the login method.
  • 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: 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: headers parameter of wsgiref.headers.Headers is now optional. Initial patch by Pablo Torres Navarrete and SilentGhost.
  • bpo-21781: ssl.RAND_add() now supports strings longer than 2 GB.
  • bpo-21679: Prevent extraneous fstat() calls during open(). Patch by Bohuslav Kabrda.
  • bpo-21863: cProfile now displays the module name of C extension functions, in addition to their own name.
  • 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: Better handling of Python exceptions in the sqlite3 module.
  • bpo-21476: Make sure the email.parser.BytesParser TextIOWrapper is discarded after parsing, so the input file isn't unexpectedly closed.
  • bpo-20295: imghdr now recognizes OpenEXR format images.
  • bpo-21729: Used the "with" statement in the dbm.dumb module to ensure files closing. Patch by Claudiu Popa.
  • bpo-21491: socketserver: Fix a race condition in child processes reaping.
  • bpo-21719: Added the st_file_attributes field to os.stat_result on Windows.
  • bpo-21832: Require named tuple inputs to be exact strings.
  • bpo-21722: The distutils "upload" command now exits with a non-zero return code when uploading fails. Patch by Martin Dengler.
  • bpo-21723: asyncio.Queue: support any type of number (ex: float) for the maximum size. Patch written by Vajrasky Kok.
  • bpo-21711: support for "site-python" directories has now been removed from the site module (it was deprecated in 3.4).
  • 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: dbm.dump.open() now always creates a new database when the flag has the value 'n'. Patch by Claudiu Popa.
  • 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: Prevent a security hole in CGIHTTPServer by URL unquoting paths before checking for a CGI script at that path.
  • bpo-21310: Fixed possible resource leak in failed open().
  • 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: Fixed chaining nonnormalized exceptions in io close() methods.
  • bpo-11709: Fix the pydoc.help function to not fail when sys.stdin is not a valid file.
  • bpo-21515: tempfile.TemporaryFile now uses os.O_TMPFILE flag is available.
  • bpo-13223: Fix pydoc.writedoc so that the HTML documentation for methods that use 'self' in the example code is generated correctly.
  • bpo-21463: In urllib.request, fix pruning of the FTP cache.
  • 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: Introduce importlib.util.module_from_spec() as the preferred way to create a new module.
  • bpo-21552: Fixed possible integer overflow of too long string lengths in the tkinter module on 64-bit platforms.
  • 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: Added "key" and "reverse" parameters to heapq.merge(). (First draft of patch contributed by Simon Sapin.)
  • bpo-21402: tkinter.ttk now works when default root window is not set.
  • bpo-3015: _tkinter.create() now creates tkapp object with wantobject=1 by default.
  • bpo-10203: sqlite3.Row now truly supports sequence protocol. In particular it supports reverse() and negative indices. Original patch by Claudiu Popa.
  • 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: Added support for the WebP image type in the imghdr module. Patch by Fabrice Aneche and Claudiu Popa.
  • bpo-21513: Speedup some properties of IP addresses (IPv4Address, IPv6Address) such as .is_private or .is_multicast.
  • bpo-21137: Improve the repr for threading.Lock() and its variants by showing the "locked" or "unlocked" status. Patch by Berker Peksag.
  • 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: Add a default backlog to socket.listen().
  • bpo-21525: Most Tkinter methods which accepted tuples now accept lists too.
  • 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: Tkinter tests now don't reuse default root window. New root window is created for every test class.
  • bpo-10744: Fix PEP 3118 format strings on ctypes objects with a nontrivial shape.
  • bpo-20826: Optimize ipaddress.collapse_addresses().
  • bpo-21487: Optimize ipaddress.summarize_address_range() and ipaddress.{IPv4Network,IPv6Network}.subnets().
  • bpo-21486: Optimize parsing of netmasks in ipaddress.IPv4Network and ipaddress.IPv6Network.
  • bpo-13916: Disallowed the surrogatepass error handler for non UTF-* encodings.
  • bpo-20998: Fixed re.fullmatch() of repeated single character pattern with ignore case. Original patch by Matthew Barnett.
  • bpo-21075: fileinput.FileInput now reads bytes from standard stream if binary mode is specified. Patch by Sam Kimbrel.
  • bpo-19775: Add a samefile() method to pathlib Path objects. Initial patch by Vajrasky Kok.
  • bpo-21226: Set up modules properly in PyImport_ExecCodeModuleObject (and friends).
  • bpo-21398: Fix a unicode error in the pydoc pager when the documentation contains characters not encodable to the stdout encoding.
  • 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: importlib.abc.InspectLoader.source_to_code() is now a staticmethod.
  • bpo-21424: Simplified and optimized heaqp.nlargest() and nmsmallest() to make fewer tuple comparisons.
  • bpo-21396: Fix TextIOWrapper(..., write_through=True) to not force a flush() on the underlying binary stream. Patch by akira.
  • bpo-18314: Unlink now removes junctions on Windows. Patch by Kim Gräsman
  • 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: _decimal: The module now supports function signatures.
  • 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: 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: Have the OrderedDict mark deleted links as unusable. This gives an early failure if the link is deleted during iteration.
  • bpo-21421: Add __slots__ to the MappingViews ABC. Patch by Josh Rosenberg.
  • bpo-21101: Eliminate double hashing in the C speed-up code for collections.Counter().
  • bpo-21321: itertools.islice() now releases the reference to the source iterator when the slice is exhausted. Patch by Anton Afanasyev.
  • 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: 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: removed previously deprecated asyncore.dispatcher __getattr__ cheap inheritance hack.
  • bpo-9815: assertRaises now tries to clear references to local variables in the exception's traceback.
  • 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: Calling sys.flags.__new__ would crash the interpreter, now it raises a TypeError.
  • bpo-19385: Make operations on a closed dbm.dumb database always raise the same exception.
  • bpo-21207: Detect when the os.urandom cached fd has been closed or replaced, and open it anew.
  • 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: Path objects can now be instantiated from str subclass instances (such as numpy.str_).
  • 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: mindom now raises a custom ValueError indicating it doesn't support spaces in URIs instead of letting a 'split' ValueError bubble up.
  • bpo-21068: The ssl.PROTOCOL* constants are now enum members.
  • bpo-21276: posixmodule: Don't define USE_XATTRS on KFreeBSD and the Hurd.
  • bpo-21262: New method assert_not_called for Mock. It raises AssertionError if the mock has been called.
  • bpo-21238: New keyword argument unsafe to Mock. It raises AttributeError incase of an attribute startswith assert or assret.
  • bpo-20896: ssl.get_server_certificate() now uses PROTOCOL_SSLv23, not PROTOCOL_SSLv3, for maximum compatibility.
  • bpo-21239: patch.stopall() didn't work deterministically when the same name was patched more than once.
  • bpo-21203: Updated fileConfig and dictConfig to remove inconsistencies. Thanks to Jure Koren for the patch.
  • bpo-21222: Passing name keyword argument to mock.create_autospec now works.
  • bpo-21197: Add lib64 -> lib symlink in venvs on 64-bit non-OS X POSIX.
  • 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: setting an iterable side_effect on a mock function created by create_autospec now works. Patch by Kushal Das.
  • bpo-7776: Fix Host: header and reconnection when using http.client.HTTPConnection.set_tunnel(). Patch by Nikolaus Rath.
  • bpo-20968: unittest.mock.MagicMock now supports division. Patch by Johannes Baiter.
  • 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)
  • 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: Fixed undocumented filter API of the rot13 codec. Patch by Berker Peksag.
  • bpo-20539: Improved math.factorial error message for large positive inputs and changed exception type (OverflowError -> ValueError) for large negative inputs.
  • bpo-21172: isinstance check relaxed from dict to collections.Mapping.
  • bpo-21155: asyncio.EventLoop.create_unix_server() now raises a ValueError if path and sock are specified at the same time.
  • bpo-21136: Avoid unnecessary normalization of Fractions resulting from power and other operations. Patch by Raymond Hettinger.
  • bpo-17621: Introduce importlib.util.LazyLoader.
  • bpo-21076: signal module constants were turned into enums. Patch by Giampaolo Rodola'.
  • bpo-20636: Improved the repr of Tkinter widgets.
  • bpo-19505: The items, keys, and values views of OrderedDict now support reverse iteration using reversed().
  • bpo-21149: Improved thread-safety in logging cleanup during interpreter shutdown. Thanks to Devin Jeanpierre for the patch.
  • bpo-21058: Fix a leak of file descriptor in tempfile.NamedTemporaryFile(), close the file descriptor if io.open() fails
  • bpo-21200: Return None from pkgutil.get_loader() when __spec__ is missing.
  • bpo-21013: Enhance ssl.create_default_context() when used for server side sockets to provide better security by default.
  • bpo-20145: assertRaisesRegex and assertWarnsRegex now raise a TypeError if the second argument is not a string or compiled regex.
  • bpo-20633: Replace relative import by absolute import.
  • bpo-20980: Stop wrapping exception when using ThreadPool.
  • bpo-21082: In os.makedirs, do not set the process-wide umask. Note this changes behavior of makedirs when exist_ok=True.
  • bpo-20990: Fix issues found by pyflakes for multiprocessing.
  • 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: Improve the command-line interface of json.tool.
  • bpo-20995: Enhance default ciphers used by the ssl module to enable better security and prioritize perfect forward secrecy.
  • bpo-20884: Don't assume that __file__ is defined on importlib.__init__.
  • bpo-21499: Ignore __builtins__ in several test_importlib.test_api tests.
  • bpo-20627: xmlrpc.client.ServerProxy is now a context manager.
  • bpo-19165: The formatter module now raises DeprecationWarning instead of PendingDeprecationWarning.
  • bpo-13936: Remove the ability of datetime.time instances to be considered false in boolean contexts.
  • bpo-18931: selectors module now supports /dev/poll on Solaris. Patch by Giampaolo Rodola'.
  • 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: Implement incremental decoder for cp65001 code (Windows code page 65001, Microsoft UTF-8).
  • 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: Include the broadcast address in the usuable hosts for IPv6 in ipaddress.
  • 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: distutils should not produce unhelpful "error: None" messages anymore. distutils.util.grok_environment_error is kept but doc-deprecated.
  • bpo-20875: Prevent possible gzip "'read' is not defined" NameError. Patch by Claudiu Popa.
  • 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: RE pattern methods now accept the string keyword parameters as documented. The pattern and source keyword parameters are left as deprecated aliases.
  • bpo-20778: Fix modulefinder to work with bytecode-only modules.
  • bpo-20791: copy.copy() now doesn't make a copy when the input is a bytes object. Initial patch by Peter Otten.
  • bpo-19748: On AIX, time.mktime() now raises an OverflowError for year outsize range [1902; 2037].
  • bpo-19573: inspect.signature: Use enum for parameter kind constants.
  • bpo-20726: inspect.signature: Make Signature and Parameter picklable.
  • bpo-17373: Add inspect.Signature.from_callable method.
  • bpo-20378: Improve repr of inspect.Signature and inspect.Parameter.
  • bpo-20816: Fix inspect.getcallargs() to raise correct TypeError for missing keyword-only arguments. Patch by Jeremiah Lowin.
  • bpo-20817: Fix inspect.getcallargs() to fail correctly if more than 3 arguments are missing. Patch by Jeremiah Lowin.
  • 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: 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: inspect.Signature and inspect.Parameter are now hashable. Thanks to Antony Lee for bug reports and suggestions.
  • bpo-15916: doctest.DocTestSuite returns an empty unittest.TestSuite instead of raising ValueError if it finds no tests
  • 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).
  • bpo-21311: Avoid exception in _osx_support with non-standard compiler configurations. Patch by John Szakmeister.
  • bpo-11571: Ensure that the turtle window becomes the topmost window when launched on OS X.
  • bpo-21801: Validate that __signature__ is None or an instance of Signature.
  • bpo-21923: Prevent AttributeError in distutils.sysconfig.customize_compiler due to possible uninitialized _config_vars.
  • bpo-21323: Fix http.server to again handle scripts in CGI subdirectories, broken by the fix for security bpo-19435. Patch by Zach Byrne.
  • bpo-22733: Fix ffi_prep_args not zero-extending argument values correctly on 64-bit Windows.
  • 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: 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: Update Idle doc chapter to match current Idle and add new information.
  • 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: 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: 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: Code objects are not normally pickled by the pickle module. To match this, they are no longer pickled when running under Idle.
  • bpo-17390: Adjust Editor window title; remove 'Python', move version to end.
  • bpo-14105: Idle debugger breakpoints no longer disappear when inserting or deleting lines.
  • 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: Add support for non-ascii identifiers to HyperParser.
  • bpo-21940: Add unittest for WidgetRedirector. Initial patch by Saimadhav Heblikar.
  • bpo-18592: Add unittest for SearchDialogBase. Patch by Phil Webster.
  • bpo-21694: Add unittest for ParenMatch. Patch by Saimadhav Heblikar.
  • bpo-21686: add unittest for HyperParser. Original patch by Saimadhav Heblikar.
  • 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: Closing a Find-in-files output window while the search is still in progress no longer closes Idle.
  • bpo-18910: Add unittest for textView. Patch by Phil Webster.
  • bpo-18292: Add unittest for AutoExpand. Patch by Saihadhav Heblikar.
  • bpo-18409: Add unittest for AutoComplete. Patch by Phil Webster.
  • bpo-21477: htest.py - Improve framework, complete set of tests. Patches by Saimadhav Heblikar
  • 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: Change default paragraph width to 72, the PEP 8 recommendation.
  • bpo-21284: Paragraph reformat test passes after user changes reformat width.
  • bpo-17654: Ensure IDLE menus are customized properly on OS X for non-framework builds and for all variants of Tk.
  • bpo-23180: Rename IDLE "Windows" menu item to "Window". Patch by Al Sweigart.

ビルド

  • bpo-15506: Use standard PKG_PROG_PKG_CONFIG autoconf macro in the configure script.
  • bpo-22935: Allow the ssl module to be compiled if openssl doesn't support SSL 3.
  • bpo-22592: Drop support of the Borland C compiler to build Python. The distutils module still supports it to build extensions.
  • bpo-22591: Drop support of MS-DOS, especially of the DJGPP compiler (MS-DOS port of GCC).
  • bpo-16537: Check whether self.extensions is empty in setup.py. Patch by Jonathan Hosmer.
  • bpo-22359: Remove incorrect uses of recursive make. Patch by Jonas Wagner.
  • bpo-21958: Define HAVE_ROUND when building with Visual Studio 2013 and above. Patch by Zachary Turner.
  • 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: "make suspicious", "make linkcheck" and "make doctest" in Doc/ now display special message when and only when there are failures.
  • 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: Add a build option to enable AddressSanitizer support.
  • 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: Refactor and fix curses configure check to always search in a ncursesw directory.
  • bpo-15234: For BerkelyDB 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: Tools/scripts/generate_opcode_h.py automatically regenerates Include/opcode.h from Lib/opcode.py if the latter gets any change.
  • 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: Eliminate use of deprecated bundlebuilder in OS X builds.
  • bpo-15968: Incorporated Tcl, Tk, and Tix builds into the Windows build solution.
  • bpo-17095: Fix Modules/Setup shared support.
  • bpo-21811: Anticipated fixes to support OS X versions > 10.9.
  • bpo-21166: Prevent possible segfaults and other random failures of python --generate-posix-vars in pybuilddir.txt build target.
  • bpo-18096: Fix library order returned by python-config.
  • bpo-17219: Add library build dir for Python extension cross-builds.
  • bpo-22919: Windows build updated to support VC 14.0 (Visual Studio 2015), which will be used for the official release.
  • bpo-21236: Build _msi.pyd with cabinet.lib instead of fci.lib
  • bpo-17128: Use private version of OpenSSL for OS X 10.5+ installer.

C API

  • 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: 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: PyType_Ready() now checks that statically allocated type has no dynamically allocated bases.
  • bpo-22453: Removed non-documented macro PyObject_REPR().
  • bpo-18395: Rename _Py_char2wchar() to Py_DecodeLocale(), rename _Py_wchar2char() to Py_EncodeLocale(), and document these functions.
  • 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: 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().

ドキュメント

  • 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: 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: The documentation of the json module now refers to new JSON RFC 7159 instead of obsoleted RFC 4627.
  • 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: undocument deprecated asynchat.fifo class.
  • bpo-17386: Expanded functionality of the Doc/make.bat script to make it much more comparable to Doc/Makefile.
  • bpo-21312: Update the thread_foobar.h template file to include newer threading APIs. Patch by Jack McCracken.
  • bpo-21043: Remove the recommendation for specific CA organizations and to mention the ability to load the OS certificates.
  • bpo-20765: Add missing documentation for PurePath.with_name() and PurePath.with_suffix().
  • 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: Document cases where __main__.__spec__ is None.

テスト

  • bpo-18982: Add tests for CLI of the calendar module.
  • 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: All test_re tests now work with unittest test discovery.
  • bpo-22173: Update lib2to3 tests to use unittest test discovery.
  • bpo-16000: Convert test_curses to use unittest.
  • bpo-21456: Skip two tests in test_urllib2net.py if _ssl module not present. Patch by Remi Pointel.
  • bpo-20746: Fix test_pdb to run in refleak mode (-R). Patch by Xavier de Gaye.
  • bpo-22060: test_ctypes has been somewhat cleaned up and simplified; it now uses unittest test discovery to find its tests.
  • 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: Assorted cleanups in test_imaplib. Patch by Milan Oberkirch.
  • 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: Fix test_ssl to accept LibreSSL version strings. Thanks to William Orr.
  • bpo-21918: Converted test_tools from a module to a package containing separate test files for each tested script.
  • bpo-9554: Use modern unittest features in test_argparse. Initial patch by Denver Coneybeare and Radu Voicilas.
  • 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: Refactored the ctypes test package to skip tests explicitly rather than silently.
  • bpo-18492: All resources are now allowed when tests are not run by regrtest.py.
  • 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: Added tests for Tkinter images.
  • bpo-21493: Added test for ntpath.expanduser(). Original patch by Claudiu Popa.
  • bpo-19925: Added tests for the spwd module. Original patch by Vajrasky Kok.
  • bpo-21522: Added Tkinter tests for Listbox.itemconfigure(), PanedWindow.paneconfigure(), and Menu.entryconfigure().
  • bpo-17756: Fix test_code test when run from the installed location.
  • bpo-17752: Fix distutils tests when run from the installed location.
  • 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: Fix a socket test on KFreeBSD.
  • bpo-21223: Pass test_site/test_startup_imports when some of the extensions are built as builtins.
  • bpo-20635: Added tests for Tk geometry managers.
  • Add test case for freeze.
  • bpo-20743: Fix a reference leak in test_tcl.
  • bpo-21097: Move test_namespace_pkgs into test_importlib.
  • bpo-21503: Use test_both() consistently in test_importlib.
  • 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: asyncio tests no longer rely on tests.txt file. (Patch by Vajrasky Kok)
  • 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: Prevent some Tk segfaults on OS X when running gui tests.
  • bpo-23211: Workaround test_logging failure on some OS X 10.6 systems.
  • bpo-23345: Prevent test_ssl failures with large OpenSSL patch level values (like 0.9.8zc).

Tools/Demos

  • bpo-22314: pydoc now works when the LINES environment variable is set.
  • 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: The makelocalealias.py script no longer ignores UTF-8 mapping.
  • 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: Command-line interface of the zipfile module now correctly extracts ZIP files with directory entries. Patch by Ryan Wilson.
  • 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: Tools/scripts/diff.py now uses argparse instead of optparse.
  • bpo-21906: Make Tools/scripts/md5sum.py work in Python 3. Patch by Zachary Ware.
  • bpo-21629: Fix Argument Clinic's "--converters" feature.
  • Add support for yield from to 2to3.
  • Add support for the PEP 465 matrix multiplication operator to 2to3.
  • bpo-16047: Fix module exception list and __file__ handling in freeze. Patch by Meador Inge.
  • bpo-11824: Consider ABI tags in freeze. Patch by Meador Inge.
  • bpo-20535: PYTHONWARNING no longer affects the run_tests.py script. Patch by Arfrever Frehtes Taifersar Arahesis.

Windows

  • 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: The Windows build scripts now expect external library sources to be in PCbuild\..\externals rather than PCbuild\..\...
  • bpo-17717: The Windows build scripts now use a copy of NASM pulled from svn.python.org to build OpenSSL.
  • bpo-21907: Improved the batch scripts provided for building Python.
  • bpo-22644: The bundled version of OpenSSL has been updated to 1.0.1j.
  • bpo-10747: Use versioned labels in the Windows start menu. Patch by Olive Kilburn.
  • 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.)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • What's New in Python »


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

Python チュートリアル

Python は強力で、学びやすいプログラミング言語です。効率的な高レベルデータ構造と、シンプルで効果的なオブジェクト指向プログラミング機構を備えています。 Python は、洗練された文法・動的なデータ型付け・インタープリタであることなどから、スクリプティングや高速アプリケーション開発(Rapid Application Development: RAD)に理想的なプログラミング言語となっています。

Python Web サイト(https://www.python.org) は、 Python インタープリタと標準ライブラリのソースコードと、主要プラットフォームごとにコンパイル済みのバイナリファイルを無料で配布しています。また、Python Web サイトには、無料のサードパーティモジュールやプログラム、ツール、ドキュメントなども紹介しています。

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. 文字列型 (string)
      • 3.1.3. リスト型 (list)
    • 3.2. プログラミングへの第一歩
  • 4. その他の制御フローツール
    • 4.1. if Statements
    • 4.2. for Statements
    • 4.3. range() 関数
    • 4.4. break and continue Statements, and else Clauses on Loops
    • 4.5. pass Statements
    • 4.6. 関数を定義する
    • 4.7. 関数定義についてもう少し
      • 4.7.1. デフォルトの引数値
      • 4.7.2. キーワード引数
      • 4.7.3. 任意引数リスト
      • 4.7.4. 引数リストのアンパック
      • 4.7.5. ラムダ式
      • 4.7.6. ドキュメンテーション文字列
      • 4.7.7. 関数のアノテーション
    • 4.8. 間奏曲: コーディングスタイル
  • 5. データ構造
    • 5.1. リスト型についてもう少し
      • 5.1.1. リストをスタックとして使う
      • 5.1.2. リストをキューとして使う
      • 5.1.3. リストの内包表記
      • 5.1.4. ネストしたリストの内包表記
    • 5.2. The del statement
    • 5.3. タプルとシーケンス
    • 5.4. 集合型
    • 5.5. 辞書型 (dictionary)
    • 5.6. ループのテクニック
    • 5.7. 条件についてもう少し
    • 5.8. シーケンスとその他の型の比較
  • 6. モジュール (module)
    • 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. 定義済みクリーンアップ処理
  • 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. カスタマイズ用モジュール

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python チュートリアル »

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

インタプリタは、簡単な電卓のように動作します: 式を入力すると、その結果が表示されます。式の文法は素直なものです: 演算子 +, -, *, / は (Pascal や C といった) 他のほとんどの言語と同じように動作します; 丸括弧 (()) をグループ化に使うこともできます。例えば:

>>> 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  # result * 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. 文字列型 (string)

Python は、数だけではなく、文字列も操作できます。文字列を記述する方法は複数あり、単引用符 ('...') で囲むか、もしくは二重引用符 ("...") で囲みます。結果はどちらも同じ文字列になります。[2] 引用符は、\ でエスケープできます。:

>>> 'spam eggs'  # single quotes
'spam eggs'
>>> '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.'

対話的インタプリタが文字列を出力するとき、出力文字列は引用符に囲まれ、特殊文字はバックスラッシュでエスケープされます。出力文字が入力とは違って見える (囲っている引用符が変わる) こともありますが、その 2 つの文字列は同じ文字列です。文字列が単引用符を含み二重引用符を含まない場合、二重引用符で囲われ、それ以外の場合は単引用符で囲われます。

>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'
>>> print('"Isn\'t," they said.')
"Isn't," they said.
>>> s = 'First line.\nSecond line.'  # \n means newline
>>> s  # without print(), \n is included in the output
'First line.\nSecond line.'
>>> print(s)  # with print(), \n produces a 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

文字列リテラルは複数行にまたがって書けます。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'

開始値は常に含まれ、終了値は常に含まれないことに注意してください。なので s[:i] + s[i:] は常に s と等しくなります:

>>> word[:2] + word[2:]
'Python'
>>> word[:4] + word[4:]
'Python'

スライスのインデックスには、便利なデフォルト値があります; 最初のインデックスを省略すると、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'

スライスの使い方をおぼえる良い方法は、インデックスが文字と文字の あいだ (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 の文字列は変更できません -- つまり不変 (immutable) です。従って、文字列のインデックスで指定したある場所に代入を行うとエラーが発生します:

>>> 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
文字列は代表的な シーケンス型 で、シーケンス型でサポートされている共通の操作をサポートしています。
文字列メソッド
文字列は、基本的な変換や検索を行うための数多くのメソッドをサポートしています。
フォーマット済み文字列リテラル
式の埋め込みをサポートした文字列リテラル
書式指定文字列の文法
str.format() を使った文字列のフォーマットについての情報があります。
printf 形式の文字列書式化
文字列が % 演算子の左オペランドである場合に呼び出される古いフォーマット操作について、詳しく記述されています。

3.1.3. リスト型 (list)

Pythonは多くの 複合 (compound) データ型を備えており、複数の値をまとめるのに使われます。最も汎用性が高いのは リスト (list) で、コンマ区切りの値 (要素) の並びを角括弧で囲んだものとして書き表されます。リストは異なる型の要素を含むこともありますが、通常は同じ型の要素のみを持ちます。

>>> squares = [1, 4, 9, 16, 25]
>>> squares
[1, 4, 9, 16, 25]

文字列 (や他の全ての組み込みのシーケンス (sequence) 型) のように、リストはインデックスやスライスができます:

>>> squares[0]  # indexing returns the item
1
>>> squares[-1]
25
>>> squares[-3:]  # slicing returns a new list
[9, 16, 25]

全てのスライス操作は、指定された要素を含む新しいリストを返します。例えば、次のスライスは、リストの新しい (浅い) コピーを返します。:

>>> squares[:]
[1, 4, 9, 16, 25]

リストは、リストの連結などもサポートしています:

>>> squares + [36, 49, 64, 81, 100]
[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

不変 (immutable) な文字列とは違って、リストは可変 (mutable) 型ですので、要素を入れ替えられます。:

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

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]

スライスには、代入もできます。スライスの代入で、リストのサイズを変更したり、全てを削除したりもできます:

>>> 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 数列 の先頭の部分列は次のように書けます:

>>> # 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 のような特殊文字は、単引用符 ('...') と二重引用符 ("...") で同じ意味を持ちます。両者の唯一の違いは、単引用符で囲われた箇所では " をエスケープする必要がない (ただし \' はエスケープする必要がある) ことで、逆もまた同様です。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python チュートリアル »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python チュートリアル »

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

先ほど紹介した while 文の他にも、 Python は他の言語でおなじみの制御フロー文を備えていますが、これらには多少ひねりを加えてあります。

4.1. if Statements

おそらく最もおなじみの文型は 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

There can be zero or more elif parts, and the else part is optional. The keyword 'elif' is short for 'else if', and is useful to avoid excessive indentation. An if ... elif ... elif ... sequence is a substitute for the switch or case statements found in other languages.

4.2. for Statements

The for statement in Python differs a bit from what you may be used to in C or Pascal. Rather than always iterating over an arithmetic progression of numbers (like in Pascal), or giving the user the ability to define both the iteration step and halting condition (as C), Python's for statement iterates over the items of any sequence (a list or a string), in the order that they appear in the sequence. For example (no pun intended):

>>> # Measure some strings:
... words = ['cat', 'window', 'defenestrate']
>>> for w in words:
...     print(w, len(w))
...
cat 3
window 6
defenestrate 12

ループ内部でイテレートしているシーケンスを修正する必要があれば (例えば選択されたアイテムを複製するために)、最初にコピーを作ることをお勧めします。シーケンスに対するイテレーションは暗黙にコピーを作りません。スライス記法はこれを特に便利にします:

>>> for w in words[:]:  # Loop over a slice copy of the entire list.
...     if len(w) > 6:
...         words.insert(0, w)
...
>>> words
['defenestrate', 'cat', 'window', 'defenestrate']

for w in words: を使った場合は、この例は defenestrate を何度も繰り返し挿入することで、無限リストを作成しようとします。

4.3. range() 関数

数列にわたって反復を行う必要がある場合、組み込み関数 range() が便利です。この関数は算術型の数列を生成します:

>>> for i in range(5):
...     print(i)
...
0
1
2
3
4

指定した終端値は生成されるシーケンスには入りません。range(10) は 10 個の値を生成し、長さ 10 のシーケンスにおける各項目のインデクスとなります。range を別の数から開始したり、他の増加量 (負でも; 増加量は時に 'ステップ(step)' と呼ばれることもあります) を指定することもできます:

range(5, 10)
   5, 6, 7, 8, 9

range(0, 10, 3)
   0, 3, 6, 9

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 を直接出力すると変なことになります:

>>> print(range(10))
range(0, 10)

range() が返すオブジェクトは、いろいろな点でリストであるかのように振る舞いますが、本当はリストではありません。これは、イテレートした時に望んだ数列の連続した要素を返すオブジェクトです。しかし実際にリストを作るわけではないので、スペースの節約になります。

このようなオブジェクトは イテラブル (iterable) と呼ばれます。これらは関数やコンストラクタのターゲットとして、あるだけの項目を逐次与えるのに適しています。 for 文がそのような イテレータ であることはすでに見てきました。関数 list() もまた一つの例です。これはイテラブルからリストを生成します:

>>> list(range(5))
[0, 1, 2, 3, 4]

後ほど、イテラブルを返したりイテラブルを引数として取る関数をもっと見ていきます。

4.4. break and continue Statements, and else Clauses on Loops

break 文は、C 言語と同じく、最も内側の for または while ループを中断します。

Loop statements may have an else clause; it is executed when the loop terminates through exhaustion of the list (with for) or when the condition becomes false (with while), but not when the loop is terminated by a break statement. This is exemplified by the following loop, which searches for prime numbers:

>>> 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 ループに属しています。)

When used with a loop, the else clause has more in common with the else clause of a try statement than it does that of if statements: a try statement's else clause runs when no exception occurs, and a loop's else clause runs when no break occurs. For more on the try statement and exceptions, see 例外を処理する.

continue 文も C 言語から借りてきたもので、ループの次のイテレーションを実行します:

>>> for num in range(2, 10):
...     if num % 2 == 0:
...         print("Found an even number", num)
...         continue
...     print("Found a number", num)
Found an even number 2
Found a number 3
Found an even number 4
Found a number 5
Found an even number 6
Found a number 7
Found an even number 8
Found a number 9

4.5. pass Statements

pass 文は何もしません。 pass は、文を書くことが構文上要求されているが、プログラム上何の動作もする必要がない時に使われます:

>>> while True:
...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
...

これは最小のクラスを作るときによく使われる方法です:

>>> class MyEmptyClass:
...     pass
...

Another place pass can be used is as a place-holder for a function or conditional body when you are working on new code, allowing you to keep thinking at a more abstract level. The pass is silently ignored:

>>> def initlog(*args):
...     pass   # Remember to implement this!
...

4.6. 関数を定義する

フィボナッチ数列 (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 文で名前を挙げておかない限り)できません。

関数を呼び出す際の実際の引数 (実引数) は、関数が呼び出されるときに関数のローカルなシンボルテーブル内に取り込まれます。そうすることで、引数は 値渡し (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 の新しい機能を示しています:

  • The return statement returns with a value from a function. return without an expression argument returns None. Falling off the end of a function also returns None.
  • 文 result.append(a) では、リストオブジェクト result の メソッド (method) を呼び出しています。メソッドとは、オブジェクトに '属している' 関数のことで、 obj を何らかのオブジェクト (式であっても構いません)、 methodname をそのオブジェクトで定義されているメソッド名とすると、 obj.methodname と書き表されます。異なる型は異なるメソッドを定義しています。異なる型のメソッドで同じ名前のメソッドを持つことができ、あいまいさを生じることはありません。 (クラス (class) を使うことで、自前のオブジェクト型とメソッドを定義することもできます。 クラス 参照) 例で示されているメソッド append() は、リストオブジェクトで定義されています; このメソッドはリストの末尾に新たな要素を追加します。この例での append() は result = result + [a] と等価ですが、より効率的です。

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

可変個の引数を伴う関数を定義することもできます。引数の定義方法には 3 つの形式があり、それらを組み合わせることができます。

4.7.1. デフォルトの引数値

もっとも便利なのは、一つ以上の引数に対してデフォルトの値を指定する形式です。この形式を使うと、定義されている引数より少ない個数の引数で呼び出せる関数を作成します:

def ask_ok(prompt, retries=4, reminder='Please try again!'):
    while True:
        ok = input(prompt)
        if ok in ('y', 'ye', 'yes'):
            return True
        if ok 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.7.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 keyword 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.7.3. 任意引数リスト

最後に、最も使うことの少ない選択肢として、関数が任意の個数の引数で呼び出せるよう指定する方法があります。これらの引数はタプル (タプルとシーケンス を参照) に格納されます。可変個の引数の前に、ゼロ個かそれ以上の引数があっても構いません。

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.7.4. 引数リストのアンパック

引数がすでにリストやタプルになっていて、個別な位置引数を要求する関数呼び出しに渡すためにアンパックする必要がある場合には、逆の状況が起こります。例えば、組み込み関数 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.7.5. ラムダ式

キーワード 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.7.6. ドキュメンテーション文字列

ドキュメンテーション文字列については、その内容と書式に関する慣習をいくつか挙げます。

最初の行は、常に対象物の目的を短く簡潔にまとめたものでなくてはなりません。簡潔に書くために、対象物の名前や型を明示する必要はありません。名前や型は他の方法でも得られるからです (名前がたまたま関数の演算内容を記述する動詞である場合は例外です)。最初の行は大文字で始まり、ピリオドで終わっていなければなりません。

ドキュメンテーション文字列中にさらに記述すべき行がある場合、二行目は空行にし、まとめの行と残りの記述部分を視覚的に分離します。つづく行は一つまたはそれ以上の段落で、対象物の呼び出し規約や副作用について記述します。

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.7.7. 関数のアノテーション

関数アノテーション はユーザ定義関数で使用される型についての完全にオプションなメタデータ情報です (詳細は PEP 3107 と PEP 484 を参照してください)。

Annotations are stored in the __annotations__ attribute of the function as a dictionary and have no effect on any other part of the function. Parameter annotations are defined by a colon after the parameter name, followed by an expression evaluating to the value of the annotation. Return annotations are defined by a literal ->, followed by an expression, between the parameter list and the colon denoting the end of the def statement. The following example has a positional argument, a keyword argument, and the return value annotated:

>>> 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.8. 間奏曲: コーディングスタイル

これからより長くより複雑な Python のコードを書いていくので、そろそろ コーディングスタイル について語っても良い頃です。ほとんどの言語は様々なスタイルで書け (もっと簡潔に言えば フォーマットでき)、スタイルによって読み易さが異なります。他人にとって読み易いコードにしようとするのはどんなときでも良い考えであり、良いコーディングスタイルを採用することが非常に強力な助けになります。

Python には、ほとんどのプロジェクトが守っているスタイルガイドとして PEP 8 があります。それは非常に読み易く目に優しいコーディングスタイルを推奨しています。全ての Python 開発者はある時点でそれを読むべきです。ここに最も重要な点を抜き出しておきます:

  • インデントには空白 4 つを使い、タブは使わないこと。

    空白 4 つは (深くネストできる) 小さいインデントと (読み易い) 大きいインデントのちょうど中間に当たります。タブは混乱させるので、使わずにおくのが良いです。

  • ソースコードの幅が 79 文字を越えないように行を折り返すこと。

    こうすることで小さいディスプレイを使っているユーザも読み易くなり、大きなディスプレイではソースコードファイルを並べることもできるようになります。

  • 関数やクラスや関数内の大きめのコードブロックの区切りに空行を使うこと。

  • 可能なら、コメントは行に独立で書くこと。

  • docstring を使うこと。

  • 演算子の前後とコンマの後には空白を入れ、括弧類のすぐ内側には空白を入れないこと: a = f(1, 2) + g(3, 4)。

  • クラスや関数に一貫性のある名前を付けること。慣習では CamelCase をクラス名に使い、 lower_case_with_underscores を関数名やメソッド名に使います。常に self をメソッドの第 1 引数の名前 (クラスやメソッドについては クラス初見 を見よ) として使うこと。

  • あなたのコードを世界中で使ってもらうつもりなら、風変りなエンコーディングは使わないこと。どんな場合でも、Python のデフォルト UTF-8 またはプレーン ASCII が最も上手くいきます。

  • 同様に、ほんの少しでも他の言語を話す人がコードを読んだりメンテナンスする可能性があるのであれば、非 ASCII 文字も識別子に使うべきではありません。

脚注

[1] 実際には、オブジェクトへの参照渡し (call by object reference) と書けばよいのかもしれません。というのは、変更可能なオブジェクトが渡されると、関数の呼び出し側は、呼び出された側の関数がオブジェクトに行ったどんな変更 (例えばリストに挿入された要素) にも出くわすことになるからです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python チュートリアル »


5. データ構造

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python チュートリアル »

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() はリストの末尾の要素を削除して返します。この場合も要素は削除されます。 (メソッドの用法 (signature) で i の両側にある角括弧は、この引数がオプションであることを表しているだけなので、角括弧を入力する必要はありません。この表記法は Python Library Reference の中で頻繁に見ることになるでしょう。)

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 a 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 の変更可能なデータ構造全てについての設計上の原則となっています。

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)]

これはより簡潔で読みやすいです。

A list comprehension consists of brackets containing an expression followed by a for clause, then zero or more for or if clauses. The result will be a new list resulting from evaluating the expression in the context of the for and if clauses which follow it. For example, this listcomp combines the elements of two lists if they are not equal:

>>> [(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, in <module>
    [x, x**2 for x in range(6)]
               ^
SyntaxError: invalid syntax
>>> # 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. The del statement

There is a way to remove an item from a list given its index instead of its value: the del statement. This differs from the pop() method which returns a value. The del statement can also be used to remove slices from a list or clear the entire list (which we did earlier by assignment of an empty list to the slice). For example:

>>> 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])

ご覧のとおり、タプルの表示には常に丸括弧がついていて、タプルのネストが正しく解釈されるようになっています。タプルを書くときは必ずしも丸括弧で囲まなくてもいいですが、(タプルが大きな式の一部だった場合は) 丸括弧が必要な場合もあります。タプルの要素を代入することはできません。しかし、タプルにリストのような変更可能型を含めることはできます。

タプルはリストと似ていますが、たいてい異なる場面と異なる目的で利用されます。タプルは不変型 (immutable) で、複数の型の要素からなることもあり、要素はアンパック(この節の後半に出てきます)操作やインデックス (あるいは namedtuples の場合は属性)でアクセスすることが多いです。一方、リストは変更可能 (mutable) で、要素はたいてい同じ型のオブジェクトであり、たいていイテレートによってアクセスします。

問題は 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 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 は、二つのオブジェクトが実際に同じオブジェクトであるかどうかを調べます。この比較は、リストのような変更可能なオブジェクトにだけ意味があります。全ての比較演算子は同じ優先順位を持っており、ともに数値演算子よりも低い優先順位となります。(訳注: is は、 is None のように、シングルトンの変更不能オブジェクトとの比較に用いる場合もあります。(「変更可能なオブジェクトにだけ意味があります」の部分を削除することを Doc-SIG に提案中。))

比較は連結させることができます。例えば、 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 言語のプログラマは不満に思うかもしれませんが、この仕様は、 C 言語プログラムで遭遇する、式の中で == のつもりで = とタイプしてしまうといったありふれた問題を回避します。

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

シーケンスオブジェクトは同じシーケンス型の他のオブジェクトと比較できます。比較には 辞書的な (lexicographical) 順序が用いられます。まず、最初の二つの要素を比較し、その値が等しくなければその時点で比較結果が決まります。等しければ次の二つの要素を比較し、以降シーケンスの要素が尽きるまで続けます。比較しようとする二つの要素がいずれも同じシーケンス型であれば、そのシーケンス間での辞書比較を再帰的に行います。二つのシーケンスの全ての要素の比較結果が等しくなれば、シーケンスは等しいとみなされます。片方のシーケンスがもう一方の先頭部分にあたる部分シーケンスならば、短い方のシーケンスが小さいシーケンスとみなされます。文字列に対する辞書的な順序づけには、個々の文字を並べるのに Unicode コードポイントの数を用います。以下に、同じ型のオブジェクトを持つシーケンス間での比較を行った例を示します:

(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(); のようなメソッドチェインを許している場合もあります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python チュートリアル »


7. 入力と出力

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python チュートリアル »

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

これらのフォーマット仕様の参考資料として、 書式指定ミニ言語仕様 のガイドを参照してください。

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. 古い文字列書式設定方法

% 演算子を使って文字列書式設定をする方法もあります。これは、演算子の左側の sprintf() スタイルのフォーマット文字列に、演算子の右側の値を適用し、その結果の文字列を返します。例えば:

>>> 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) のように二つの引数を伴って呼び出されます。

>>> f = open('workfile', 'w')

最初の引数はファイル名の入った文字列です。二つめの引数も文字列で、ファイルをどのように使うかを示す数個の文字が入っています。 mode は、ファイルが読み出し専用なら 'r' 、書き込み専用 (同名の既存のファイルがあれば消去されます) なら 'w' とします。 'a' はファイルを追記用に開きます。ファイルに書き込まれた内容は自動的にファイルの終端に追加されます。 'r+' はファイルを読み書き両用に開きます。 mode 引数は省略可能で、省略された場合には 'r' であると仮定します。

通常、ファイルはテキストモード (text mode) で開かれ、特定のエンコーディングでエンコードされたファイルに対して文字列を読み書きします。エンコーディングが指定されなければ、デフォルトはプラットフォーム依存です (open() を参照してください) 。モードに 'b' をつけるとファイルをバイナリモード (binary mode) で開き、 byte オブジェクトを読み書きします。テキストファイル以外のすべてのファイルはバイナリモードを利用するべきです。

テキストモードの読み取りでは、プラットフォーム固有の行末記号 (Unix では \n 、Windows では \r\n) をただの \n に変換するのがデフォルトの動作です。テキストモードの書き込みでは、 \n が出てくる箇所をプラットフォーム固有の行末記号に戻すのがデフォルトの動作です。この裏で行われるファイルデータの変換はテキストファイルには上手く働きますが、 JPEG ファイルや EXE ファイルのようなバイナリデータを破壊する恐れがあります。そのようなファイルを読み書きする場合には注意して、バイナリモードを使うようにしてください。

It is good practice to use the with keyword when dealing with file objects. The advantage is that the file is properly closed after its suite finishes, even if an exception is raised at some point. Using with is also much shorter than writing equivalent try-finally blocks:

>>> with open('workfile') as f:
...     read_data = f.read()
>>> f.closed
True

with キーワードを使わない場合は、f.close() を呼び出してファイルを閉じ、そのファイルが使っていたシステムリソースをすぐに解放する必要があります。 明示的にファイルを閉じなかった場合は、いつかは Python のガベージコレクタがそのファイルオブジェクトを破棄し開かれいていたファイルを閉じますが、しばらくはファイルが開かれたままでいる可能性があります。 他に考えられるリスクは、別の Python の実装ではこの片付け処理が別のタイミングで実行されることです。

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 バイトを読み出して返します。ファイルの終端にすでに達していた場合、 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, from_what) を使います。ファイル位置は基準点 (reference point) にオフセット値 offset を足して計算されます。参照点は from_what 引数で選びます。from_what の値が 0 ならばファイルの 先頭から測り、1 ならば現在のファイル位置を使い、2 ならばファイルの終端を参照点として使います。from_what は省略することができ、デフォルトの値は 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) を使うことができます。この標準モジュール json は、Python のデータ 階層を取り、文字列表現に変換します。この処理は シリアライズ (serializing) と呼ばれます。文字列表現からデータを再構築することは、デシリアライズ (deserializing) と呼ばれます。シリアライズされてからデシリアライズされるまでの間に、オブジェクトの文字列表現はファイルやデータの形で保存したり、ネットワークを通じて離れたマシンに送ったりすることができます。

注釈

JSON 形式は現代的なアプリケーションでデータをやりとりする際によく使われます。多くのプログラマーが既に JSON に詳しいため、JSON はデータの相互交換をする場合の良い選択肢です。

オブジェクト x があり、その JSON 形式の文字列表現を見るには、単純な1行のコードを書くだけです:

>>> import json
>>> json.dumps([1, 'simple', 'list'])
'[1, "simple", "list"]'

dumps() に似た関数に、dump() があり、こちらは単純にオブジェクトを text file にシリアライズします。f が書き込み用に開かれた text file だとすると、次のように書くことができます:

json.dump(x, f)

逆にデシリアライズするには、f が読み込み用に開かれた text file だとすると、次のようになります:

x = json.load(f)

このような単純なシリアライズをする手法は、リストや辞書を扱うことはできますが、任意のクラス・インスタンスを JSON にシリアライズするにはもう少し努力しなくてはなりません。json モジュールのリファレンスにこれについての解説があります。

参考

pickle - pickle モジュール

JSON とは対照的に、 pickle は任意の複雑な Python オブジェクトをシリアライズ可能なプロトコルです。しかし、Python に特有のプロトコルで、他の言語で記述されたアプリケーションと通信するのには使えません。さらに、デフォルトでは安全でなく、信頼できない送信元から送られてきた、スキルのある攻撃者によって生成された pickle データをデシリアライズすると、攻撃者により任意のコードが実行されてしまいます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python チュートリアル »


8. エラーと例外

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python チュートリアル »

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't convert 'int' object to str implicitly

エラーメッセージの最終行は何が起こったかを示しています。例外は様々な型 (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 節で指定された例外と一致しない例外が発生すると、その例外は try 文の外側に渡されます。例外に対するハンドラ (handler、処理部) がどこにもなければ、 処理されない例外 (unhandled exception) となり、上記に示したようなメッセージを出して実行を停止します。

A try statement may have more than one except clause, to specify handlers for different exceptions. At most one handler will be executed. Handlers only handle exceptions that occur in the corresponding try clause, not in other handlers of the same try statement. An except clause may name multiple exceptions as a parenthesized tuple, for example:

... except (RuntimeError, TypeError, NameError):
...     pass

except 節のクラスは、例外と同じクラスか基底クラスのときに互換 (compatible)となります。 (逆方向では成り立ちません --- 派生クラスの例外がリストされている 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 節が駆動されるのです。

最後の except 節では例外名を省いて、ワイルドカード (wildcard、総称記号) にすることができます。ワイルドカードの except 節は非常に注意して使ってください。というのは、ワイルドカードは通常のプログラムエラーをたやすく隠してしまうからです！ワイルドカードの except 節はエラーメッセージを出力した後に例外を再送出する (関数やメソッドの呼び出し側が同様にして例外を処理できるようにする) 用途にも使えます:

import sys

try:
    f = open('myfile.txt')
    s = f.readline()
    i = int(s.strip())
except OSError as err:
    print("OS error: {0}".format(err))
except ValueError:
    print("Could not convert data to an integer.")
except:
    print("Unexpected error:", sys.exc_info()[0])
    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()

The use of the else clause is better than adding additional code to the try clause because it avoids accidentally catching an exception that wasn't raised by the code being protected by the try ... except statement.

例外が発生するとき、例外は関連付けられた値を持つことができます。この値は例外の 引数 (argument) とも呼ばれます。引数の有無および引数の型は、例外の型に依存します。

except 節では、例外名の後に変数を指定することができます。この変数は例外インスタンスに結び付けられており、 instance.args に例外インスタンス生成時の引数が入っています。例外インスタンスには __str__() が定義されており、 .args を参照しなくても引数を直接印字できるように利便性が図られています。必要なら、例外を送出する前にインスタンス化して、任意の属性を追加できます。

>>> try:
...     raise Exception('spam', 'eggs')
... except Exception as inst:
...     print(type(inst))    # the exception instance
...     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

例外が引数を持っていれば、それらは処理されない例外のメッセージの最後の部分 (「詳細説明」) に出力されます。

例外ハンドラは、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 の唯一の引数は送出される例外を指し示します。 これは例外インスタンスか例外クラス (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. ユーザー定義例外

プログラム上で新しい例外クラスを作成することで、独自の例外を指定することができます (Python のクラスについては クラス 参照)。例外は、典型的に Exception クラスから、直接または間接的に派生したものです。

例外クラスでは、普通のクラスができることなら何でも定義することができますが、通常は単純なものにしておきます。大抵は、いくつかの属性だけを提供し、例外が発生したときにハンドラがエラーに関する情報を取り出せるようにする程度にとどめます。複数の別個の例外を送出するようなモジュールを作成する際には、そのモジュールで定義されている例外の基底クラスを作成するのが一般的なプラクティスです:

class Error(Exception):
    """Base class for exceptions in this module."""
    pass

class InputError(Error):
    """Exception raised for errors in the input.

    Attributes:
        expression -- input expression in which the error occurred
        message -- explanation of the error
    """

    def __init__(self, expression, message):
        self.expression = expression
        self.message = message

class TransitionError(Error):
    """Raised when an operation attempts a state transition that's not
    allowed.

    Attributes:
        previous -- state at beginning of transition
        next -- attempted new state
        message -- explanation of why the specific transition is not allowed
    """

    def __init__(self, previous, next, message):
        self.previous = previous
        self.next = next
        self.message = message

ほとんどの例外は、標準の例外の名前付けと同様に、"Error" で終わる名前で定義されています。

多くの標準モジュールでは、モジュールで定義されている関数内で発生する可能性のあるエラーを報告させるために、独自の例外を定義しています。クラスについての詳細な情報は クラス 章で提供されています。

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

try 文にはもう一つオプションの節があります。この節はクリーンアップ動作を定義するためのもので、どんな状況でも必ず実行されます。例を示します:

>>> try:
...     raise KeyboardInterrupt
... finally:
...     print('Goodbye, world!')
...
Goodbye, world!
KeyboardInterrupt
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>

A finally clause is always executed before leaving the try statement, whether an exception has occurred or not. When an exception has occurred in the try clause and has not been handled by an except clause (or it has occurred in an except or else clause), it is re-raised after the finally clause has been executed. The finally clause is also executed "on the way out" when any other clause of the try statement is left via a break, continue or return statement. A more complicated example:

>>> def divide(x, y):
...     try:
...         result = x / y
...     except ZeroDivisionError:
...         print("division by zero!")
...     else:
...         print("result is", result)
...     finally:
...         print("executing finally clause")
...
>>> divide(2, 1)
result is 2.0
executing finally clause
>>> divide(2, 0)
division by zero!
executing finally clause
>>> divide("2", "1")
executing finally clause
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 3, in divide
TypeError: unsupported operand type(s) for /: 'str' and 'str'

As you can see, the finally clause is executed in any event. The TypeError raised by dividing two strings is not handled by the except clause and therefore re-raised after the finally clause has been executed.

実世界のアプリケーションでは、 finally 節は(ファイルやネットワーク接続などの)外部リソースを、利用が成功したかどうかにかかわらず解放するために便利です。

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

オブジェクトのなかには、その利用の成否にかかわらず、不要になった際に実行される標準的なクリーンアップ処理が定義されているものがあります。以下の、ファイルをオープンして内容を画面に表示する例をみてください。

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 されます。ファイルなどの、定義済みクリーンアップ処理を持つオブジェクトについては、それぞれのドキュメントで示されます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python チュートリアル »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python チュートリアル »

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

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

os モジュールは、オペレーティングシステムと対話するための多くの関数を提供しています:

>>> import os
>>> os.getcwd()      # Return the current working directory
'C:\\Python37'
>>> 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. コマンドライン引数

一般的なユーティリティスクリプトでは、よくコマンドライン引数を扱う必要があります。コマンドライン引数は sys モジュールの argv 属性にリストとして保存されています。例えば、以下の出力は、 python demo.py one two three とコマンドライン上で起動した時に得られるものです:

>>> import sys
>>> print(sys.argv)
['demo.py', 'one', 'two', 'three']

getopt モジュールは、 sys.argv を Unix の getopt() 関数の慣習に従って処理します。より強力で柔軟性のあるコマンドライン処理機能は、 argparse モジュールで提供されています。

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://tycho.usno.navy.mil/cgi-bin/timer.pl') as response:
...     for line in response:
...         line = line.decode('utf-8')  # Decoding the binary data to text.
...         if 'EST' in line or 'EDT' in line:  # look for Eastern Time
...             print(line)

<BR>Nov. 25, 09:43:32 PM EST

>>> 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 に基づくメッセージ文書を含む電子メールメッセージを管理するためのライブラリです。実際にメッセージを送信したり受信したりする smtplib や poplib と違って、email パッケージには (添付文書を含む) 複雑なメッセージ構造の構築やデコードを行ったり、インターネット標準のエンコードやヘッダプロトコルの実装を行ったりするための完全なツールセットを備えています。
  • json パッケージはこの一般的なデータ交換形式のパースをロバストにサポートしています。csv モジュールはデータベースや表計算で一般的にサポートされている CSV ファイルを直接読み書きするのをサポートしています。xml.etree.ElementTree、xml.dom ならびに xml.sax パッケージは XML の処理をサポートしています。総合すると、これらのモジュールによって Python アプリケーションと他のツールの間でとても簡単にデータを受け渡すことが出来ます。
  • sqlite3 モジュールは SQLite データベースライブラリのラッパです。若干非標準の SQL シンタックスを用いて更新や接続出来る永続的なデータベースを提供します。
  • 国際化に関する機能は、 gettext, locale, codecs パッケージといったモジュール群でサポートされています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python チュートリアル »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python チュートリアル »

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("%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 は自動的にメモリを管理します (ほとんどのオブジェクトは参照カウント方式で管理し、ガベージコレクション(garbage collection)で循環参照を除去します)。オブジェクトに対する最後の参照がなくなってしばらくするとメモリは解放されます。

このようなアプローチはほとんどのアプリケーションでうまく動作しますが、中にはオブジェクトをどこか別の場所で利用している間だけ追跡しておきたい場合もあります。残念ながら、オブジェクトを追跡するだけでオブジェクトに対する恒久的な参照を作ることになってしまいます。 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:/python37/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
>>> sum([0.1]*10) == 1.0
False

decimal モジュールを使うと、必要なだけの精度で算術演算を行えます:

>>> getcontext().prec = 36
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857')

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python チュートリアル »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python チュートリアル »

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 をスクリプトとして実行します:

python3 -m venv tutorial-env

これは tutorial-env ディレクトリがなければ作成して、その中に Python インタプリタ、標準ライブラリ、その他関連するファイルを含むサブディレクトリを作ります。

仮想環境を作ったら、それを有効化する必要があります。

Windows の場合:

tutorial-env\Scripts\activate.bat

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']
>>>

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

You can install, upgrade, and remove packages using a program called pip. By default pip will install packages from the Python Package Index, <https://pypi.org>. You can browse the Python Package Index by going to it in your web browser, or you can use pip's limited search feature:

(tutorial-env) $ pip search astronomy
skyfield               - Elegant astronomy for Python
gary                   - Galactic astronomy and gravitational dynamics.
novas                  - The United States Naval Observatory NOVAS astronomy library
astroobs               - Provides astronomy ephemeris to plan telescope observations
PyAstronomy            - A collection of astronomy related tools for Python.
...

pip は "search", "install", "uninstall", "freeze" など、いくつかのサブコマンドを持っています。 (pip の完全なドキュメントは Python モジュールのインストール ガイドを参照してください。)

パッケージ名を指定してそのパッケージの最新版をインストールすることができます:

(tutorial-env) $ 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) $ 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 は要求されたバージョンがインストール済みだと表示して何もしません。別のバージョン番号を指定すればそのバージョンをインストールしますし、pip install --upgrade を実行すればそのパッケージを最新版に更新します:

(tutorial-env) $ 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

pip uninstall コマンドに削除するパッケージ名を1つ以上指定します。

pip show は指定されたパッケージの情報を表示します:

(tutorial-env) $ 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:

pip list は仮想環境にインストールされた全てのパッケージを表示します:

(tutorial-env) $ pip list
novas (3.1.1.3)
numpy (1.9.2)
pip (7.0.3)
requests (2.7.0)
setuptools (16.0)

pip freeze はインストールされたパッケージ一覧を、pip install が解釈するフォーマットで生成します。一般的な慣習として、このリストを requirements.txt というファイルに保存します:

(tutorial-env) $ 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) $ 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 モジュールの配布 ガイドを参照してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python チュートリアル »


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

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.1.3. OpenSolaris
    • 2.2. Python のビルド
    • 2.3. Python に関係するパスとファイル
    • 2.4. その他
    • 2.5. エディタと IDE
  • 3. Windows で Python を使う
    • 3.1. 完全版インストーラ
      • 3.1.1. インストール手順
      • 3.1.2. MAX_PATH の制限を除去する
      • 3.1.3. インストーラの GUI なしでインストールする
      • 3.1.4. ダウンロード不要なインストール
      • 3.1.5. インストール後の変更
    • 3.2. Microsoft ストアパッケージ
      • 3.2.1. 既知の問題
    • 3.3. nuget.org パッケージ
    • 3.4. 埋め込み可能なパッケージ
      • 3.4.1. Python アプリケーション
      • 3.4.2. Python の埋め込み
    • 3.5. 別のバンドル
    • 3.6. Python を構成する
      • 3.6.1. 補足: 環境変数の設定
      • 3.6.2. Python 実行ファイルを見つける
    • 3.7. Windows の Python ランチャ
      • 3.7.1. 最初に
        • 3.7.1.1. コマンドラインから起動する
        • 3.7.1.2. 仮想環境 (Virtual environments)
        • 3.7.1.3. スクリプトから起動する
        • 3.7.1.4. ファイルの関連付けから起動する
      • 3.7.2. シェバン (shebang) 行
      • 3.7.3. シェバン行の引数
      • 3.7.4. カスタマイズ
        • 3.7.4.1. INI ファイルによるカスタマイズ
        • 3.7.4.2. デフォルトのPythonバージョンのカスタマイズ
      • 3.7.5. 診断
    • 3.8. モジュールの検索
    • 3.9. 追加のモジュール
      • 3.9.1. PyWin32
      • 3.9.2. cx_Freeze
      • 3.9.3. WConio
    • 3.10. Windows 上で Python をコンパイルする
    • 3.11. ほかのプラットフォーム
  • 4. Macintosh で Python を使う
    • 4.1. MacPython の入手とインストール
      • 4.1.1. Python スクリプトの実行方法
      • 4.1.2. GUI でスクリプトを実行
      • 4.1.3. Configuration
    • 4.2. IDE
    • 4.3. 追加の Python パッケージのインストール
    • 4.4. Mac での GUI プログラミング
    • 4.5. Mac 上の Python アプリケーションの配布
    • 4.6. 他のリソース

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python のセットアップと利用 »

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

CPython インタプリタはコマンドラインと環境を読み取って様々な設定を行ないます。

CPython implementation detail: 他の実装のコマンドラインスキームは CPython とは異なります。さらなる情報は 別のPythonの実装 を参照してください。

1.1. コマンドライン

Python を起動するとき、以下のうち任意のオプションを指定できます:

python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args]

もちろん、もっとも一般的な利用方法は、単純にスクリプトを起動することです:

python myscript.py

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

インタプリタのインターフェイスは UNIX シェルのものに似ていますが、より多くの起動方法を提供しています:

  • tty デバイスに接続された標準入力とともに起動された場合、 EOF (end-of-file 文字。 UNIX では Ctrl-D で、Windows では Ctrl-Z, Enter で入力可能) を受け取るまで、コマンドを受け取り、それを実行します。
  • ファイル名引数か、標準入力としてファイルを渡された場合、そのファイルからスクリプトを読み込んで実行します。
  • ディレクトリ名を引数に受け取った場合、そのディレクトリから適切な名前のスクリプトファイルを読み込んで実行します。
  • -c コマンド オプションを利用して起動された場合、 コマンド として渡された Python の文を実行します。 コマンド の部分には改行で区切られた複数行を指定することもできます。行の先頭の空白文字は Python 文の重要要素です！
  • -m モジュール名 として Python モジュールパスにあるモジュールを指定された場合、そのモジュールをスクリプトとして実行します。

非インタラクティブモードでは、入力の全体が実行前にパースされます。

インタプリタによって消費されるオプションリストが終了したあと、継続する全ての引数は sys.argv に渡ります。 -- ただし、添字 0 の先頭要素(sys.argv[0]) はプログラムのソース自体を示す文字列です。

-c <command>

command 内の Python コードを実行します。 command は改行によって区切られた1行以上の文です。通常のモジュールのコードと同じく、行頭の空白文字は意味を持ちます。

このオプションが指定された場合、 sys.argv の最初の要素は "-c" になり、カレントディレクトリが sys.path の先頭に追加されます (そのディレクトリにあるモジュールをトップレベルモジュールとして import 出来るようになります)。

-m <module-name>

sys.path から指定されたモジュール名のモジュールを探し、その内容を __main__ モジュールとして実行します。

引数は module 名なので、拡張子 (.py) を含めてはいけません。モジュール名は有効な Python の絶対モジュール名 (absolute module name) であるべきですが、実装がそれを強制しているとは限りません (例えば、ハイフンを名前に含める事を許可するかもしれません)。

パッケージ名 (名前空間パッケージも含む) でも構いません。通常のモジュールの代わりにパッケージ名が与えられた場合、インタプリタは <pkg>.__main__ を main モジュールとして実行します。この挙動はスクリプト引数として渡されたディレクトリや zip ファイルをインタプリタが処理するのと意図的に同じにしています。

注釈

このオプションは組み込みモジュールや C で書かれた拡張モジュールには利用できません。 Python モジュールファイルを持っていないからです。しかし、コンパイル済みのモジュールは、たとえ元のソースファイルがなくても利用可能です。

このオプションが指定された場合、 sys.argv の最初の要素はモジュールファイルのフルパスになります (モジュールファイルを検索している間、最初の要素は "-m" に設定されます)。 -c オプションと同様に、カレントディレクトリが sys.path の先頭に追加されます。

多くの標準ライブラリモジュールにはスクリプトとして実行された時のためのコードがあります。例えば、 timeit モジュールは次のように実行可能です:

python -mtimeit -s 'setup here' 'benchmarked code here'
python -mtimeit -h # for details

参考

runpy.run_module()
Python コードで直接使える等価な機能

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

バージョン 3.1 で変更: __main__ サブモジュールを実行するパッケージ名が提供されました。

バージョン 3.4 で変更: 名前空間パッケージもサポートされました

-

標準入力 (sys.stdin) からコマンドを読み込みます。標準入力がターミナルだった場合、暗黙的に -i オプションが指定されます。

このオプションが指定された場合、 sys.argv の最初の要素は "-" で、カレントディレクトリが sys.path の先頭に追加されます。

<script>

script 内の Python コードを実行します。 script は、Python ファイル、 __main__.py ファイルがあるディレクトリ、 __main__.py ファイルがある zip ファイルのいずれかの、ファイルシステム上の (絶対または相対) パスでなければなりません。

このオプションが指定された場合、 sys.argv の最初の要素はコマンドラインで指定されたスクリプト名になります。

スクリプト名が Python ファイルを直接指定していた場合、そのファイルを含むディレクトリが sys.path の先頭に追加され、そのファイルは __main__ モジュールとして実行されます。

スクリプト名がディレクトリか zip ファイルを指定していた場合、スクリプト名が sys.path に追加され、その中の __main__.py ファイルが __main__ モジュールとして実行されます。

参考

runpy.run_path()
Python コードで直接使える等価な機能

インターフェイスオプションが与えられなかった場合、-i が暗黙的に指定され、sys.argv[0] が空の文字列 ("") になり、 現在のディレクトリが sys.path の先頭に追加されます。また、利用可能であればタブ補完と履歴編集が自動的に有効かされます (readline の設定 を参照してください)。

参考

インタプリタを起動する

バージョン 3.4 で変更: タブ補完と履歴の編集が自動的に有効化されます。

1.1.2. 一般オプション

-?
-h
--help

全コマンドラインオプションの短い説明を出力します。

-V
--version

Python のバージョン番号を表示して終了します。出力の例:

Python 3.7.0b2+

2つ指定すると、次のようにより多くのビルドの情報を表示します:

Python 3.7.0b2+ (3.7:0c076caaa8, Sep 22 2018, 12:04:24)
[GCC 6.2.0 20161005]

バージョン 3.6 で追加: -VV オプション。

1.1.3. その他のオプション

-b

bytes または bytearray を str と比較した場合、または、 bytes を int と比較した場合に警告を発生させます。このオプションを2度指定した場合 (-bb) は、エラーを発生させます。

バージョン 3.5 で変更: bytes と 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

パーサーのデバッグ出力を有効にします。(専門家専用です。コンパイルオプションに依存します)。 PYTHONDEBUG も参照してください。

-E

全ての PYTHON* 環境変数を無視します。例えば、 PYTHONPATH や PYTHONHOME などです。

-i

最初の引数にスクリプトが指定された場合や -c オプションが利用された場合、 sys.stdin がターミナルに出力されない場合も含めて、スクリプトかコマンドを実行した後にインタラクティブモードに入ります。 PYTHONSTARTUP ファイルは読み込みません。

このオプションはグローバル変数や、スクリプトが例外を発生させるときにそのスタックトレースを調べるのに便利です。 PYTHONINSPECT も参照してください。

-I

Python を隔離モードで実行します。-E と -s も暗黙的に指定されます。隔離モードでは sys.path はスクリプトのディレクトリやユーザのサイトパッケージのディレクトリを含みません。全 PYTHON* 環境変数も無視されます。ユーザが悪意のあるコードを注入するのを防ぐために更なる制限が課されるかもしれません。

バージョン 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). See also PYTHONOPTIMIZE.

バージョン 3.5 で変更: PEP 488 に従って .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).

バージョン 3.5 で変更: PEP 488 に従って .pyc ファイル名を変更します。

-q

インタラクティブモードでも copyright とバージョンのメッセージを表示しません。

バージョン 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.

以前のバージョンの Python では、このオプションはハッシュのランダム化を有効にします。これにより、 str, bytes, datetime 型の __hash__() 値が予測不可能な乱数で "ソルト" されます。ハッシュ値は各 Python プロセスでは固定ですが、 Python を繰り返し再実行した場合は別の予測不能な値になります。

ハッシュのランダム化は、dict の生成コストが最悪の O(n^2) になるように注意深く選ばれた入力値を与えることによる DoS 攻撃への防御策として提供されています。詳細は http://www.ocert.org/advisories/ocert-2011-003.html を参照してください。

PYTHONHASHSEED によってハッシュシードの固定値を秘密にすることが出来ます。

バージョン 3.7 で変更: このオプションが無視されなくなりました.

バージョン 3.2.3 で追加.

-s

user site-packages directory を sys.path に追加しません。

参考

PEP 370 -- ユーザごとの 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)は、モジュールを検索するときにチェックされた各ファイルに対してメッセージを出力します。また、終了時のモジュールクリーンアップに関する情報も提供します。 PYTHONVERBOSE も参照してください。

-W arg

警告制御。 Python の警告機構はデフォルトでは警告メッセージを sys.stderr に表示します。典型的な警告メッセージは次の書式で表示されます。

file:line: category: message

デフォルトでは、各警告は発生したソース行ごとに一度だけ表示されます。このオプションは、警告をどれくらいの頻度で表示するかを制御します。

複数の -W オプションを指定することができます。警告が1つ以上のオプションとマッチしたときは、最後にマッチしたオプションのアクションが有効になります。不正な -W オプションは無視されます (最初の警告が発生したときに、不正なオプションに対する警告メッセージが表示されます)。

警告は、 PYTHONWARNINGS 環境変数を使い、そして Python プログラムの中から warnings モジュールを利用して制御できます。

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 (e.g. -Wi, -Wd, -Wa, -We) and the interpreter will resolve them to the appropriate action name.

See 警告フィルタ and Describing Warning Filters for more details.

-x

Unix 以外の形式の #!cmd を使うために、ソースの最初の行をスキップします。これは、DOS専用のハックのみを目的としています。

-X

様々な実装固有のオプションのために予約されています。現在のところ CPython は以下の値を定義しています:

  • -X faulthandler は faulthandler を有効化します;
  • -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.
  • -X tracemalloc は tracemalloc モジュールを用いて Python のメモリ割り当てのトレースを開始します。デフォルトでは最新のフレームのみがトレースのトレースバックに格納されます。最大 NFRAME フレームのトレースバックで トレースを開始するには -X tracemalloc=NFRAME を使用してください。詳細は tracemalloc.start() を参照してください。
  • -X showalloccount to output the total count of allocated objects for each type when the program finishes. This only works when Python was built with COUNT_ALLOCS defined.
  • -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.
  • -X dev: enable CPython's "development mode", introducing additional runtime checks which 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. Effect of the developer mode:
    • Add default warning filter, as -W default.
    • Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks() C function.
    • Enable the faulthandler module to dump the Python traceback on a crash.
    • Enable asyncio debug mode.
    • Set the dev_mode attribute of sys.flags to True
  • -X utf8 enables UTF-8 mode for operating system interfaces, overriding the default locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when it would otherwise activate automatically). See PYTHONUTF8 for more details.

任意の値を渡し、 sys._xoptions 辞書から取り出すことも出来ます。

バージョン 3.2 で変更: -X オプションが追加されました。

バージョン 3.3 で追加: -X faulthandler オプション。

バージョン 3.4 で追加: -X showrefcount および -X tracemalloc オプション。

バージョン 3.6 で追加: -X showalloccount オプション。

バージョン 3.7 で追加: -X importtime, -X dev, -X utf8 オプション。

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

-J

Jython のために予約されています。

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 変数として操作することができます。

PYTHONSTARTUP

この変数が読み込み可能なファイル名の場合、対話モードで最初のプロンプトが表示される前にそのファイルの Python コマンドが実行されます。 ファイル内で定義されているオブジェクトやインポートされたオブジェクトを対話セッションで修飾せずに使用するために、ファイルは対話的なコマンドと同じ名前空間で実行されます。 このファイル内のプロンプト sys.ps1 や sys.ps2、ならびにフック sys.__interactivehook__ を変更することも出来ます。

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.

バージョン 3.7 で追加.

PYTHONDEBUG

この変数に空でない文字列を設定するのは -d オプションを指定するのと等価です。整数を指定した場合、 -d を複数回指定したのと同じになります。

PYTHONINSPECT

この変数に空でない文字列を設定するのは -i オプションを指定するのと等価です。

この変数は Python コードから os.environ を使って変更して、プログラム終了時のインスペクトモードを強制することができます。

PYTHONUNBUFFERED

この変数に空でない文字列を設定するのは -u オプションを指定するのと等価です。

PYTHONVERBOSE

この変数に空でない文字列を設定するのは -v オプションを指定するのと等価です。整数を設定した場合、 -v を複数回指定したのと同じになります。

PYTHONCASEOK

この環境変数が設定されている場合、 Python は import 文で大文字/小文字を区別しません。 これは Windows と OS X でのみ動作します。

PYTHONDONTWRITEBYTECODE

この変数に空でない文字列を設定した場合、 Python はソースモジュールのインポート時に .pyc ファイルを作成しようとはしなくなります。 -B オプションを指定するのと等価です。

PYTHONHASHSEED

この変数が設定されていない場合や random に設定された場合、乱数値が str、bytes ならびに datetime オブジェクトのハッシュのシードに使われます。

PYTHONHASHSEED が整数値に設定された場合、その値はハッシュランダム化が扱う型の hash() 生成の固定シードに使われます。

その目的は再現性のあるハッシュを可能にすることです。例えばインタープリタ自身の自己テストや Python プロセスのクラスタでハッシュ値を共有するのに用います。

整数は [0,4294967295] の十進数でなければなりません。0 を指定するとハッシュランダム化は無効化されます。

バージョン 3.2.3 で追加.

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 -- ユーザごとの site-packages ディレクトリ

PYTHONUSERBASE

user base directory を設定します。これは python setup.py install --user 時に user site-packages directory と Distutils installation paths のパスを計算するのに使われます。

参考

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

PYTHONEXECUTABLE

この環境変数が設定された場合、 sys.argv[0] に、C ランタイムから取得した値の代わりにこの環境変数の値が設定されます。Mac OS X でのみ動作します。

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

See 警告フィルタ and Describing Warning Filters for more details.

PYTHONFAULTHANDLER

この環境変数が空でない文字列に設定された場合、起動時に faulthandler.enable() が呼び出されます。Python のトレースバックをダンプするために SIGSEGV、SIGFPE、SIGABRT、SIGBUS および SIGILL シグナルのハンドラを導入します。-X faulthandler オプションと等価です。

バージョン 3.3 で追加.

PYTHONTRACEMALLOC

この環境変数が空でない文字列に設定された場合、tracemalloc モジュールを利用して Python のメモリ割り当てのトレースを開始します。変数の値はトレース時のトレースバックで保持されるフレームの最大数です。例えば PYTHONTRACEMALLOC=1 の場合、最新のフレームのみを保持します。詳細は tracemalloc.start() を参照してください、

バージョン 3.4 で追加.

PYTHONPROFILEIMPORTTIME

If this environment variable is set to a non-empty string, Python will show how long each import takes. This is exactly equivalent to setting -X importtime on the command line.

バージョン 3.7 で追加.

PYTHONASYNCIODEBUG

この環境変数が空でない文字列に設定された場合、asyncio モジュールの デバッグモード が有効化されます。

バージョン 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

See the default memory allocators and the PyMem_SetupDebugHooks() function (install debug hooks on Python memory allocators).

バージョン 3.7 で変更: Added the "default" allocator.

バージョン 3.6 で追加.

PYTHONMALLOCSTATS

If set to a non-empty string, Python will print statistics of the pymalloc memory allocator every time a new pymalloc object arena is created, and on shutdown.

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 errors 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 。

バージョン 3.6 で追加: より詳しくは PEP 529 を参照をしてください。

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 。

バージョン 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.

Availability: *nix.

バージョン 3.7 で追加: See PEP 538 for more details.

PYTHONDEVMODE

If this environment variable is set to a non-empty string, enable the CPython "development mode". See the -X dev option.

バージョン 3.7 で追加.

PYTHONUTF8

If set to 1, enables the interpreter's UTF-8 mode, where UTF-8 is used as the text encoding for system interfaces, regardless of the current locale setting.

This means that:

  • sys.getfilesystemencoding() returns 'UTF-8' (the locale encoding is ignored).
  • locale.getpreferredencoding() returns 'UTF-8' (the locale encoding is ignored, and the function's do_setlocale parameter 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)

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.

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

If set to 0, the interpreter runs in its default locale-aware mode.

Setting any other non-empty string causes an error during interpreter initialisation.

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

Also available as the -X utf8 option.

Availability: *nix.

バージョン 3.7 で追加: See PEP 540 for more details.

1.2.1. デバッグモード変数

以下の環境変数は、--with-pydebug ビルドオプションを指定して構成されたデバッグビルド版の Python でのみ効果があります。

PYTHONTHREADDEBUG

設定された場合、 Python はスレッドデバッグ情報を表示します。

PYTHONDUMPREFS

設定された場合、 Python はインタプリタのシャットダウン後に残っているオブジェクトと参照カウントをダンプします。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python のセットアップと利用 »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python のセットアップと利用 »

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-old.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-creating-rpms.html
Fedora ユーザー向け
http://www.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.1.3. OpenSolaris

OpenCSW から Python を入手することができます。 Python の様々なバージョンが利用可能でインストールすることができます。e.g. pkgutil -i python27.

2.2. Python のビルド

CPython を自分でコンパイルしたい場合は、まず ソース を入手します。 最新リリース版のソースをダウンロード、あるいはソースリポジトリから新しく クローン を作成してください。(パッチの作成に貢献したい場合はクローンが必要になるでしょう。)

ビルドは通常次の手順で行います

./configure
make
make install

Configure のオプションや特定の Unix プラットフォームにおける注意点は Python ソースツリーのルートにある README.rst に細かく記載されています。

警告

make install は python3 バイナリを上書きまたはリンクを破壊してしまうかもしれません。そのため、make install の代わりに exec_prefix/bin/pythonversion のみインストールする make altinstall が推奨されています。

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

これらはローカルインストールの慣例に応じて変化します; prefix (${prefix}) と exec_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. エディタと IDE

Python プログラミング言語をサポートする IDE はたくさんあります。 多くのエディタや IDE にはシンタックスハイライト機能、デバッグツール、 PEP 8 チェック機能があります。

包括的な一覧を見るには、 Python Editors や Integrated Development Environments を訪れてください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python のセットアップと利用 »


4. Macintosh で Python を使う

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python のセットアップと利用 »

4. Macintosh で Python を使う

著者: Bob Savage <bobsavage@mac.com>

Mac OS X が動作している Macintosh 上の Python は原則的には他の Unix プラットフォーム上の Python と非常によく似ていますが、 IDE やパッケージ・マネージャなどの指摘すべき追加要素があります。

4.1. MacPython の入手とインストール

Mac OS X 10.8 には Apple によって Python 2.7 がプリインストールされています。Python の Web サイト (https://www.python.org) から最新バージョンの Python 3 を取得しインストールすることもできます。新しい Intel の CPU でも古い PPC の CPU でもネイティブに動作する "ユニバーサル・バイナリ" ビルドの最新のものがあります。

インストールを行うといくつかのものが手に入ります:

  • A MacPython 3.6 folder in your Applications folder. In here you find IDLE, the development environment that is a standard part of official Python distributions; PythonLauncher, which handles double-clicking Python scripts from the Finder; and the "Build Applet" tool, which allows you to package Python scripts as standalone applications on your system.
  • Python 実行ファイルやライブラリを含む /Library/Frameworks/Python.framework フレームワーク。インストーラはシェルのパスにこの場所を追加します。 MacPython をアンインストールするには、これら 3 つを削除すればよいだけです。 Python 実行ファイルへのシンボリックリンクは /usr/local/bin/ に置かれています。

Apple が提供している Python のビルドは /System/Library/Frameworks/Python.framework と /usr/bin/python にそれぞれインストールされています。これらは Apple が管理しているものであり Apple やサードパーティのソフトウェアが使用するので、編集したり削除したりしてはいけません。 python.org から新しいバージョンの Python をインストールする場合には、それぞれ正常に動作する 2 つの異なる Python 環境がコンピュータにインストールされるため、意図する方の Python のパスを設定し、使用することが重要です。

IDLE にはヘルプメニューがあり Python のドキュメントにアクセスすることができます。もし Python が全くの初めての場合にはドキュメントのチュートリアルを最初から読み進めることをおすすめします。

もし他の Unix プラットフォームで Python を使い慣れている場合には Unix シェルからの Python スクリプトの実行についての節を読むことをおすすめします。

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

Mac OS X で Python を始める最良の方法は統合開発環境である IDLE を使うことです、 IDE 節を参照し IDE を実行しているときにヘルプメニューを使ってください。

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. Mac OS X comes with a number of standard Unix command line editors, vim and emacs among them. If you want a more Mac-like editor, BBEdit or TextWrangler from Bare Bones Software (see http://www.barebones.com/products/bbedit/index.html) are good choices, as is TextMate (see https://macromates.com/). Other editors include Gvim (http://macvim-dev.github.io/macvim/) and Aquamacs (http://aquamacs.org/).

ターミナルからスクリプトを実行するには /usr/local/bin がシェルのパスに含まれていることを確認してください。

Finder からスクリプトを実行するのには 2 つの方法があります:

  • PythonLauncher へドラッグする
  • Finder の情報ウィンドウから PythonLauncher をそのスクリプト (もしくは .py スクリプト全て) を開くデフォルトのアプリケーションとして選び、スクリプトファイルをダブルクリックしてください。 PythonLauncher の環境設定にはどのようにスクリプトを実行するかを管理する様々な設定があります。 option キーを押しながらドラッグすることで実行するごとにこれらの設定を変えられますし、環境設定メニューから全ての実行に対して設定変更することもできます。

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

古いバージョンの Python には、気を付けておかないといけない Mac OS X の癖があります: Aqua ウィンドウマネージャとやりとりをする (別の言い方をすると GUI を持つ) プログラムは特別な方法で実行する必要があります。 そのようなスクリプトを実行するには python ではなく pythonw を使ってください。

Python 3.6 では、 python と pythonw のどちらでも使えます。

4.1.3. Configuration

OS X 上の Python では PYTHONPATH のような全ての標準の Unix 環境変数が使えますが、Finder からプログラムを起動する場合このような環境変数を設定する方法は非標準であり Finder は起動時に .profile や .cshrc を読み込みません。 ~/.MacOSX/environment.plist ファイルを作る必要があります。詳細については Apple の Technical Document QA1067 を参照してください。

MacPython の Python パッケージのインストールについてのさらなる情報は、 追加の Python パッケージのインストール 節を参照してください。

4.2. IDE

MacPython ships with the standard IDLE development environment. A good introduction to using IDLE can be found at http://www.hashcollision.org/hkn/python/idle_intro/index.html.

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

追加の Python パッケージをインストールする方法がいくつかあります:

  • パッケージは Python の標準の distutils モードを使ってインストールすることができます (python setup.py install)。
  • 多くのパッケージは setuptools 拡張や pip ラッパーを使ってもインストールできます。 https://pip.pypa.io/ を参照してください。

4.4. Mac での GUI プログラミング

Python で Mac 上の GUI アプリケーションをビルドする方法がいくつかあります。

PyObjC は Mac の最新の開発基盤である Apple の Objective-C/Cocoa フレームワークへの Python バインディングです。PyObjC の情報は https://pythonhosted.org/pyobjc/ にあります。

Python 標準の GUI ツールキットは、クロスプラットフォームの Tk ツールキット (https://www.tcl.tk) 上に構築された tkinter です。 Tk の Aqua ネイティブバージョンは Apple が OS X にバンドルしており、最新バージョンは https://www.activestate.com からダウンロードおよびインストールできます; またソースからビルドすることもできます。

wxPython is another popular cross-platform GUI toolkit that runs natively on Mac OS X. Packages and documentation are available from https://www.wxpython.org.

PyQt は別の人気のあるクロスプラットフォームの GUI ツールキットで Mac OS X 上でネイティブに動作します。詳しい情報は https://riverbankcomputing.com/software/pyqt/intro にあります。

4.5. Mac 上の Python アプリケーションの配布

The "Build Applet" tool that is placed in the MacPython 3.6 folder is fine for packaging small Python scripts on your own machine to run as a standard Mac application. This tool, however, is not robust enough to distribute Python applications to other users.

Mac 上の単独の Python アプリケーションをデプロイする標準のツールは py2app です。 py2app のインストールと使用法に関する情報は http://undefined.org/python/#py2app にあります。

4.6. 他のリソース

MacPython メーリングリストは Mac での Python ユーザや開発者にとって素晴しいサポートリソースです:

https://www.python.org/community/sigs/current/pythonmac-sig/

他の役に立つリソースは MacPython wiki です:

https://wiki.python.org/moin/MacPython

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python のセットアップと利用 »


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

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. __main__ に対する特別な考慮
    • 5.8. 取り掛かり中の問題
    • 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. 条件式 (Conditional Expressions)
    • 6.13. ラムダ (lambda)
    • 6.14. 式のリスト
    • 6.15. 評価順序
    • 6.16. 演算子の優先順位
  • 7. 単純文 (simple statement)
    • 7.1. 式文 (expression statement)
    • 7.2. 代入文 (assignment statement)
    • 7.3. The assert statement
    • 7.4. The pass statement
    • 7.5. The del statement
    • 7.6. The return statement
    • 7.7. The yield statement
    • 7.8. The raise statement
    • 7.9. The break statement
    • 7.10. The continue statement
    • 7.11. The import statement
    • 7.12. The global statement
    • 7.13. The nonlocal statement
  • 8. 複合文 (compound statement)
    • 8.1. The if statement
    • 8.2. The while statement
    • 8.3. The for statement
    • 8.4. The try statement
    • 8.5. The with statement
    • 8.6. 関数定義
    • 8.7. クラス定義
    • 8.8. コルーチン
  • 9. トップレベル要素
    • 9.1. 完全な Python プログラム
    • 9.2. ファイル入力
    • 9.3. 対話的入力
    • 9.4. 式入力
  • 10. 完全な文法仕様

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


6. 式 (expression)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • 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 ::=  expression comp_for
comp_for      ::=  ["async"] "for" target_list "in" or_test [comp_iter]
comp_iter     ::=  comp_for | comp_if
comp_if       ::=  "if" expression_nocond [comp_iter]

The comprehension consists of a single expression followed by at least one for clause and zero or more for or if clauses. In this case, the elements of the new container are those that would be produced by considering each of the for or if clauses a block, nesting from left to right, and evaluating the expression to produce an element each time the innermost block is reached.

However, aside from the iterable expression in the leftmost for clause, the comprehension is executed in a separate implicitly nested scope. This ensures that names assigned to in the target list don't "leak" into the enclosing scope.

The iterable expression in the leftmost for clause is evaluated directly in the enclosing scope and then passed as an argument to the implictly nested scope. Subsequent for clauses and any filter condition in the leftmost for clause cannot be evaluated in the enclosing scope as they may depend on the values obtained from the leftmost iterable. For example: [x*y for x in range(10) for y in range(x, x+10)].

内包表記が常に適切な型のコンテナになるのを保証するために、 yield 式や yield from 式は暗黙的な入れ子のスコープでは禁止されています (Python 3.7 では、そのような式はコンパイル時に DeprecationWarning を発生させ、 Python 3.8 以降では SyntaxError を発生させます)。

Since Python 3.6, in an async def function, an async for clause may be used to iterate over a asynchronous iterator. A comprehension in an async def function may consist of either a for or async for clause following the leading expression, may contain additional for or async for clauses, and may also use await expressions. If a comprehension contains either async for clauses or await expressions it is called an asynchronous comprehension. An asynchronous comprehension may suspend the execution of the coroutine function in which it appears. See also PEP 530.

バージョン 3.6 で追加: 非同期内包表記が導入されました。

バージョン 3.7 で非推奨: yield および yield from は暗黙的な入れ子のスコープでは非推奨となりました。

6.2.5. リスト表示

リスト表示は、角括弧で囲われた式の系列です。系列は空の系列であってもかまいません:

list_display ::=  "[" [starred_list | comprehension] "]"

リスト表示は、新しいリストオブジェクトを与えます。リストの内容は、式のリストまたはリスト内包表記 (list comprehension) で指定されます。 カンマで区切られた式のリストが与えられたときは、それらの各要素は左から右へと順に評価され、その順にリスト内に配置されます。 内包表記が与えられたときは、内包表記の結果の要素でリストが構成されます。

6.2.6. 集合表示

集合表示は波括弧で表され、キーと値を分けるコロンがないことで辞書表現と区別されます:

set_display ::=  "{" (starred_list | comprehension) "}"

集合表示は、新しいミュータブルな集合オブジェクトを与えます。集合の内容は、式の並びまたは内包表記によって指定されます。 カンマ区切りの式のリストが与えられたときは、その要素は左から右へ順に評価され、集合オブジェクトに加えられます。 内包表記が与えられたときは、内包表記の結果の要素で集合が構成されます。

空集合は {} で構成できません。このリテラルは空の辞書を構成します。

6.2.7. 辞書表示

辞書表示は、波括弧で囲われた、キーと値のペアからなる系列です。系列は空の系列であってもかまいません:

dict_display       ::=  "{" [key_datum_list | dict_comprehension] "}"
key_datum_list     ::=  key_datum ("," key_datum)* [","]
key_datum          ::=  expression ":" expression | "**" or_expr
dict_comprehension ::=  expression ":" expression comp_for

辞書表示は、新たな辞書オブジェクトを表します。

キーとデータからなる対の並びがカンマ区切りで与えられたときは、その要素は左から右へ評価され、辞書のエントリーを定義します。すなわち、それぞれのキーオブジェクトが、辞書内で対応するデータを保存するキーとして使われます。 これにより、キーとデータのリストの中で同じキーを複数回指定することができ、そのキーに対する最終的な辞書の値は、最後に与えられたものになります。

ダブルアスタリスク ** は 辞書のアンパック を表します。このとき被演算子は mapping でなければなりません。それぞれのmappingの要素は、新たな辞書に追加されます。キー/データの対もしくは辞書のアンパックによって先に追加された値は、後から追加された値によって上書きされます。

バージョン 3.5 で追加: 辞書表示のアンパックは最初に PEP 448 で提案されました。

辞書内包表記は、リストや集合の内包表記とは対照的に、通常の "for" や "if" 節の前に、コロンで分けられた 2 つの式が必要です。内包表記が起動すると、結果のキーと値の要素が、作られた順に新しい辞書に挿入されます。

キーの値として使える型に関する制限は 標準型の階層 節ですでに列挙しています。(一言でいうと、キーは変更可能なオブジェクトを全て排除した hashable でなければなりません。) 重複するキー間で衝突が起きても、衝突が検出されることはありません; あるキーに対して、最後に渡されたデータ (プログラムテキスト上では、辞書表記の最も右側値となるもの) が使われます。

6.2.8. ジェネレータ式

ジェネレータ式 (generator expression) とは、丸括弧を使ったコンパクトなジェネレータ表記法です:

generator_expression ::=  "(" expression comp_for ")"

ジェネレータ式は新たなジェネレータオブジェクトを与えます。この構文は内包表記とほぼ同じですが、角括弧や波括弧ではなく、丸括弧で囲まれます。

Variables used in the generator expression are evaluated lazily when the __next__() method is called for the generator object (in the same fashion as normal generators). However, the iterable expression in the leftmost for clause is immediately evaluated, so that an error produced by it will be emitted at the point where the generator expression is defined, rather than at the point where the first value is retrieved. Subsequent for clauses and any filter condition in the leftmost for clause cannot be evaluated in the enclosing scope as they may depend on the values obtained from the leftmost iterable. For example: (x*y for x in range(10) for y in range(x, x+10)).

関数の唯一の引数として渡す場合には、丸括弧を省略できます。詳しくは 呼び出し (call) 節を参照してください。

ジェネレータ式自身の期待される動作を妨げないために、 yield 式や yield from 式は暗黙的に定義されたジェネレータでは禁止されています (Python 3.7 では、そのような式はコンパイル時に DeprecationWarning を発生させ、 Python 3.8 以降では SyntaxError を発生させます)。

If a generator expression contains either async for clauses or await expressions it is called an asynchronous generator expression. An asynchronous generator expression returns a new asynchronous generator object, which is an asynchronous iterator (see 非同期イテレータ (Asynchronous Iterator)).

バージョン 3.6 で追加: 非同期ジェネレータ式が導入されました。

バージョン 3.7 で変更: Python 3.7 より前では、非同期ジェネレータ式は async def コルーチンでしか使えませんでした。 3.7 からは、任意の関数で非同期ジェネレータ式が使えるようになりました。

バージョン 3.7 で非推奨: yield および yield from は暗黙的な入れ子のスコープでは非推奨となりました。

6.2.9. Yield 式

yield_atom       ::=  "(" yield_expression ")"
yield_expression ::=  "yield" [expression_list | "from" expression]

yield 式は ジェネレータ 関数や term:非同期ジェネレータ <asynchronous generator> を定義するときに使われます。従って、関数定義の本体でのみ使えます。 関数の本体で yield 式 を使用するとその関数はジェネレータになり、 async def 関数の本体で使用するとそのコルーチン関数は非同期ジェネレータになります。 例えば次のようになります:

def gen():  # defines a generator function
    yield 123

async def agen(): # defines an asynchronous generator function
    yield 123

含まれているスコープの副作用のため、 yield 式は暗黙的に定義されたスコープの一部として内包表記やジェネレータ式を実装するのに使うことは許可されていません (Python 3.7 では、そのような式はコンパイル時に DeprecationWarning を発生させ、 Python 3.8 以降では SyntaxError を発生させます)。

バージョン 3.7 で非推奨: yield 式は、暗黙的な入れ子のスコープで内包表記やジェネレータ式を実装するための使用が非推奨になりました。

ジェネレータ関数についてはすぐ下で説明されています。非同期ジェネレータ関数は、 非同期ジェネレータ関数 (asynchronous generator function) 節に分けて説明されています。

ジェネレータ関数が呼び出された時、ジェネレータとしてのイテレータを返します。ジェネレータはその後ジェネレータ関数の実行を制御します。ジェネレータのメソッドが呼び出されると実行が開始されます。開始されると、最初の yield 式まで処理して一時停止し、呼び出し元へ expression_list の値を返します。ここで言う一時停止とは、ローカル変数の束縛、命令ポインタや内部の評価スタック、そして例外処理のを含むすべてのローカル状態が保持されることを意味します。再度、ジェネレータのメソッドが呼び出されて実行を再開した時、ジェネレータは 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 - 単純なジェネレータ
Python へのジェネレータと yield 文の導入提案。
PEP 0342 - 拡張されたジェネレータを用いたコルーチン
シンプルなコルーチンとして利用できるように、ジェネレータの構文と API を拡張する提案。
PEP 380 - サブジェネレータへの委譲構文
サブジェネレータの委譲を簡単にするための、 yield_from 構文の導入提案。
PEP 525 - 非同期ジェネレータ
コルーチン関数へのジェネレータの実装能力の追加による PEP 492 の拡張提案。

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(type[, value[, traceback]])

ジェネレータが中断した位置で type 型の例外を発生させて、そのジェネレータ関数が生成する次の値を返します。ジェネレータが値を生成することなく終了すると StopIteration が発生します。ジェネレータ関数が渡された例外を捕捉しない、もしくは違う例外を発生させるなら、その例外は呼び出し元へ伝搬されます。

generator.close()

ジェネレータ関数が一時停止した時点で GeneratorExit を発生させます。 そして、ジェネレータ関数が無事に終了するか、既にクローズされているか、(例外が捕捉されなかったために) GeneratorExit が送出された場合、 close は呼び出し元へ戻ります。 ジェネレータが値を生成する場合 RuntimeError が発生します。 close() はジェネレータが例外や正常な終了により既に終了している場合は何もしません。

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 式があると、その関数は 非同期ジェネレータ 関数として定義されます。

When an asynchronous generator function is called, it returns an asynchronous iterator known as an asynchronous generator object. That object then controls the execution of the generator function. An asynchronous generator object is typically used in an async for statement in a coroutine function analogously to how a generator object would be used in a for statement.

Calling one of the asynchronous generator's methods returns an awaitable object, and the execution starts when this object is awaited on. At that time, the execution proceeds to the first yield expression, where it is suspended again, returning the value of expression_list to the awaiting coroutine. As with a generator, suspension means that all local state is retained, including the current bindings of local variables, the instruction pointer, the internal evaluation stack, and the state of any exception handling. When the execution is resumed by awaiting on the next object returned by the asynchronous generator's methods, the function can proceed exactly as if the yield expression were just another external call. The value of the yield expression after resuming depends on the method which resumed the execution. If __anext__() is used then the result is None. Otherwise, if asend() is used, then the result will be the value passed in to that method.

In an asynchronous generator function, yield expressions are allowed anywhere in a try construct. However, if an asynchronous generator is not resumed before it is finalized (by reaching a zero reference count or by being garbage collected), then a yield expression within a try construct could result in a failure to execute pending finally clauses. In this case, it is the responsibility of the event loop or scheduler running the asynchronous generator to call the asynchronous generator-iterator's aclose() method and run the resulting coroutine object, thus allowing any pending finally clauses to execute.

To take care of finalization, 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.

The expression yield from <expr> is a syntax error when used in an asynchronous generator function.

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

This subsection describes the methods of an asynchronous generator iterator, which are used to control the execution of a generator function.

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 a __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 an StopAsyncIteration exception, signalling that the asynchronous iteration has completed.

This method is normally called implicitly by a async for loop.

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(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, an 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.

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

プライマリの評価は、属性参照をサポートする型のオブジェクトでなければならず、これにはほとんどのオブジェクトが当てはまります。そしてこのオブジェクトは、名前が指定した識別子名であるような属性を生成しなければなりません。この生成は __getattr__() メソッドをオーバーライドすることでカスタマイズできます。その属性が得られなければ、例外 AttributeError が送出されます。そうでなければ、生成されるオブジェクトの型と値は、属性を生成したオブジェクトにより決まります。同じ属性参照を複数回評価すると、互いに異なる属性オブジェクトが得られることがあります。

6.3.2. 添字表記 (subscription)

添字表記は、シーケンス (文字列、タプルまたはリスト) やマップ (辞書) オブジェクトから、要素を一つ選択します:

subscription ::=  primary "[" expression_list "]"

プライマリの評価は、添字表記をサポートするオブジェクト (例えばリストや辞書) でなければなりません。ユーザ定義のオブジェクトは、 __getitem__() メソッドを定義することで添字表記をサポートできます。

組み込みオブジェクトでは、添字表記をサポートするオブジェクトには 2 種類あります:

プライマリがマップであれば、式リストの値評価結果はマップ内のいずれかのキー値に相当するオブジェクトにならなければなりません。添字表記は、そのキーに対応するマップ内の値 (value) を選択します。 (式リストの要素が単独である場合を除き、式リストはタプルでなければなりません。)

プライマリがシーケンスであれば、式リストの評価結果は整数またはスライス (以下の節で論じます) でなければなりません。

形式的な構文はシーケンスの負のインデックスにいかなる特例も与えません。しかし、すべての組み込みのシーケンスが与える __getitem__() メソッドは、負のインデックスを、インデックスにシーケンスの長さを加えて解釈します (つまり、 x[-1] は x の最後の要素を選択します)。結果の値はシーケンスの要素数より小さな非負の整数でなければなりません。添字表記は、(0 から数えた) インデックスを持つ要素を選択します。負のインデックスのサポートは、オブジェクトの __getitem__() メソッドに現れるので、このメソッドをオーバーライドするサブクラスは、明示的にこのサポートを追加する必要があります。

文字列型の要素は文字 (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

上記の形式的な構文法にはあいまいなところがあります: 式リストに見えるものは、スライスリストにも見えるため、添字表記はスライス表記としても解釈されうるということです。(スライスリストが適切なスライスを含まない場合)、これ以上の構文の複雑化はせず、スライス表記としての解釈よりも添字表記としての解釈が優先されるように定義することで、あいまいさを取り除いています。

スライス表記に対する意味付けは、以下のようになります。プライマリの値評価結果は、以下に述べるようにしてスライスリストから生成されたキーによって (通常の添字表記と同じ __getitem__() メソッドを使って) インデクス指定できなければなりません。スライスリストに一つ以上のカンマが含まれている場合、キーは各スライス要素を値変換したものからなるタプルになります; それ以外の場合、単一のスライス要素自体を値変換したものがキーになります。一個の式であるスライス要素は、その式に変換されます。適切なスライスは、スライスオブジェクト (標準型の階層 参照) に変換され、その start, stop および step 属性は、それぞれ指定した下境界、上境界、およびとび幅 (stride) になります。式がない場所は None で置き換えられます。

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 ::=  ["*"] expression ("," ["*"] expression)*
starred_and_keywords ::=  ("*" expression | keyword_item)
                          ("," "*" expression | "," keyword_item)*
keywords_arguments   ::=  (keyword_item | "**" expression)
                          ("," keyword_item | "," "**" expression)*
keyword_item         ::=  identifier "=" expression

最後の位置引数やキーワード引数の後にカンマをつけてもかまいません。構文の意味付けに影響を及ぼすことはありません。

プライマリの評価は呼び出し可能オブジェクトでなければなりません。 (ユーザ定義関数、組み込み関数、組み込みオブジェクトのメソッド、クラスオブジェクト、クラスインスタンスのメソッド、および __call__() メソッドを持つ全てのオブジェクトが呼び出し可能です)。引数式は全て、呼び出しを試みる前に評価されます。仮引数 (formal parameter) リストの構文については 関数定義 を参照してください。

キーワード引数が存在する場合、以下のようにして最初に位置引数 (positional argument) に変換されます。まず、値の入っていないスロットが仮引数に対して生成されます。N 個の位置引数がある場合、位置引数は先頭の N スロットに配置されます。次に、各キーワード引数について、識別子を使って対応するスロットを決定します (識別子が最初の仮引数名と同じなら、最初のスロットを使う、といった具合です)。スロットがすでにすべて埋まっていたなら TypeError 例外が送出されます。それ以外の場合、引数値をスロットに埋めていきます。 (式が None であっても、その式でスロットを埋めます)。全ての引数が処理されたら、まだ埋められていないスロットをそれぞれに対応する関数定義時のデフォルト値で埋めます。(デフォルト値は、関数が定義されたときに一度だけ計算されます; 従って、リストや辞書のような変更可能なオブジェクトがデフォルト値として使われると、対応するスロットに引数を指定しない限り、このオブジェクトが全ての呼び出しから共有されます; このような状況は通常避けるべきです。) デフォルト値が指定されていない、値の埋められていないスロットが残っている場合 TypeError 例外が送出されます。そうでない場合、値の埋められたスロットからなるリストが呼び出しの引数として使われます。

CPython implementation detail: 実装では、名前を持たない位置引数を受け取る組み込み関数を提供されるかもしれません。そういった引数がドキュメント化のために '名付けられて' いたとしても、実際には名付けられていないのでキーワードでは提供されません。 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 例外が送出されます。

*identifier や **identifier 構文を使った仮引数は、位置引数スロットやキーワード引数名にすることができません。

バージョン 3.5 で変更: 関数呼び出しは任意の数の * アンパックと ** アンパックを受け取り、位置引数はイテラブルアンパック (*) の後ろに置け、キーワード引数は辞書アンパック (**) の後ろに置けるようになりました。 最初に PEP 448 で提案されました。

呼び出しを行うと、例外を送出しない限り、常に何らかの値を返します。 None を返す場合もあります。戻り値がどのように算出されるかは、呼び出し可能オブジェクトの形態によって異なります。

各形態では---

ユーザ定義関数:

関数のコードブロックに引数リストが渡され、実行されます。コードブロックは、まず仮引数を実引数に結合 (bind) します; この動作については 関数定義 で記述しています。コードブロックで return 文が実行される際に、関数呼び出しの戻り値 (return value) が決定されます。

組み込み関数またはメソッド:

結果はインタプリタに依存します; 組み込み関数やメソッドの詳細は 組み込み関数 を参照してください。

クラスオブジェクト:

そのクラスの新しいインスタンスが返されます。

クラスインスタンスメソッド:

対応するユーザ定義の関数が呼び出されます。このとき、呼び出し時の引数リストより一つ長い引数リストで呼び出されます: インスタンスが引数リストの先頭に追加されます。

クラスインスタンス:

クラスで __call__() メソッドが定義されていなければなりません; __call__() メソッドが呼び出された場合と同じ効果をもたらします。

6.4. Await 式

awaitable オブジェクトでの coroutine 実行を一時停止します。 coroutine function 内でのみ使用できます。

await_expr ::=  "await" primary

バージョン 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 を送出していました)

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

全ての単項算術演算とビット単位演算は、同じ優先順位を持っています:

u_expr ::=  power | "-" u_expr | "+" u_expr | "~" u_expr

単項演算子 - (マイナス) は、引数となる数値の符号を反転 (negation) します。

単項演算子 + (プラス) は、数値引数を変更しません。

単項演算子 ~ (反転) は、整数引数をビット単位反転 (bitwise invert) したものを与えます。x のビット単位反転は、-(x+1) として定義されています。この演算子は整数にのみ適用されます。

上記の三つはいずれも、引数が正しい型でない場合には 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) 演算子は、引数同士の積を与えます。引数は、両方とも数値であるか、片方が整数で他方がシーケンスかのどちらかでなければなりません。前者の場合、数値は共通の型に変換された後乗算されます。後者の場合、シーケンスの繰り返し操作が行われます。繰り返し数を負にすると、空のシーケンスを与えます。

@ (at) 演算子は行列の乗算に対し使用されます。 Python の組み込み型はこの演算子を実装していません。

バージョン 3.5 で追加.

/ (除算: division) および // (切り捨て除算: floor division) は、引数同士の商を与えます。数値引数はまず共通の型に変換されます。整数の除算結果は浮動小数点になりますが、整数の切り捨て除算結果は整数になります; この場合、結果は数学的な除算に 'floor' 関数 を適用したものになります。ゼロによる除算を行うと ZeroDivisionError 例外を送出します。

% (剰余: 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 形式の文字列書式化 節を参照してください。

切り捨て除算演算子、剰余演算子、および divmod() 関数は、複素数に対しては定義されていません。目的に合うならば、代わりに abs() を使って浮動小数点に変換してください。

+ (加算) 演算は、引数同士の和を与えます。引数は双方とも数値型か、双方とも同じ型のシーケンスでなければなりません。前者の場合、数値は共通の型に変換され、加算されます。後者の場合、シーケンスは結合 (concatenate) されます。

- (減算) 演算は、引数間で減算を行った値を返します。数値引数はまず共通の型に変換されます。

6.8. シフト演算 (shifting operation)

シフト演算は、算術演算よりも低い優先順位を持っています:

shift_expr ::=  a_expr | shift_expr ("<<" | ">>") a_expr

これらは整数を引数にとります。引数は共通の型に変換されます。シフト演算は第一引数を、第二引数で与えられたビット数だけ、左または右にビットシフトします。

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

& 演算子は、引数同士のビット単位の AND を与えます。引数は整数でなければなりません。

^ 演算子は、引数同士のビット単位の XOR (排他的 OR) を与えます。引数は整数でなければなりません。

| 演算子は、引数同士のビット単位の (包含的) OR を与えます。引数は整数でなければなりません。

6.10. 比較

C 言語と違って、Python における比較演算子は同じ優先順位をもっており、全ての算術演算子、シフト演算子、ビット単位演算子よりも低くなっています。また a < b < c が数学で伝統的に用いられているのと同じ解釈になる点も C 言語と違います:

comparison    ::=  or_expr (comp_operator or_expr)*
comp_operator ::=  "<" | ">" | "==" | ">=" | "<=" | "!="
                   | "is" ["not"] | ["not"] "in"

比較演算の結果はブール値: True または False になります。

比較はいくらでも連鎖することができます。例えば 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 ではやや抽象的な概念です: 例えば、オブジェクトの値にアクセスする正統な方法はありません。 また、その全てのデータ属性から構成されるなどの特定の方法で、オブジェクトの値を構築する必要性もありません。 比較演算子は、オブジェクトの値とは何かについての特定の概念を実装しています。 この比較の実装によって、間接的にオブジェクトの値を定義している考えることもできます。

全ての型は (直接的あるいは間接的に) object のサブクラスとなっているので、デフォルトの比較の振る舞いを object から継承しています。 基本的なカスタマイズ で解説されているように、型を使って rich comparison methods である __lt__() などのメソッドを実装することで、 比較の振る舞いをカスタマイズできます。

等価比較 (== および !=) のデフォルトの振る舞いは、オブジェクトの同一性に基づいています。 従って、同一のインスタンスの等価比較の結果は等しいとなり、同一でないインスタンスの等価比較の結果は等しくないとなります。 デフォルトの振る舞いをこのようにしたのは、全てのオブジェクトを反射的 (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 に従ったものです。

  • バイナリシーケンス (bytes または bytearray のインスタンス) は、これらの型の範囲で異なる型とも比較できます。 比較は要素の数としての値を使った辞書式順序で行われます。

  • 文字列 (str のインスタンス) の比較は、文字の Unicode のコードポイントの数としての値 (組み込み関数 ord() の返り値) を使った辞書式順序で行われます。 [3]

    文字列とバイナリシーケンスは直接には比較できません。

  • シーケンス (tuple, list, or range のインスタンス) の比較は、同じ型どうしでしか行えず、 range は順序比較をサポートしていません。 異なる型どうしの等価比較の結果は等価でないとなり、異なる型どうしの順序比較は TypeError を送出します。

    シーケンスの比較は、要素の反射性があるものとして、対応する要素どうしの比較を使って辞書式順序で行われます。

    要素の反射性が強制されていると、コレクションの比較ではコレクションの要素 x に対して x == x が常に真だと仮定します。 この仮定に基づいて、最初に要素の同一性が比較され、同一でない要素どうしに対してのみ要素の比較が行われます。 この手法は、比較される要素が反射的な場合、厳密な要素比較と同じ結果をもたらします。 反射的でない要素では厳密な要素比較と異なる結果になり、驚くかもしれません: 例えば、反射的でない非数値がリストで使われたとき、比較の振る舞いは次のような結果になります:

    >>> nan = float('NaN')
>>> nan is nan
True
>>> nan == nan
False                 <-- the defined non-reflexive behavior of NaN
>>> [nan] == [nan]
True                  <-- list enforces reflexivity and tests identity first

    組み込みのコレクションどうしの辞書式比較は次のように動作します:

    • 比較の結果が等価となる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. 所属検査演算

The operators in and not in test for membership. x in s evaluates to True if x is a member of s, and False otherwise. x not in s returns the negation of x in s. All built-in sequences and set types support this as well as dictionary, for which in tests whether the dictionary has a given key. For container types such as list, tuple, set, frozenset, dict, or collections.deque, the expression x in y is equivalent to any(x is e or x == e for e in y).

文字列やバイト列型については、 x in y は x が y の部分文字列であるとき、かつそのときに限り True になります。これは y.find(x) != -1 と等価です。空文字列は、他の任意の文字列の部分文字列とみなされます。従って "" in "abc" は True を返すことになります。

__contains__() メソッドを実装したユーザ定義クラスでは、 y.__contains__(x) の返り値が真となる場合に x in y の返り値は True となり、そうでない場合は False となります。

__contains__() を定義していないが __iter__() は定義しているユーザ定義クラスでは、 x in y は x == z となるようなある値 z が y 内にわたる反復で生成された場合、 True となります。もし、反復の間に例外が発生すれば、 in が例外を発生させたようにみえます。

最終的には、旧スタイルの反復プロトコルの実行を試みます: もしクラスが __getitem__() を定義しているならば、 x in y は x == y[i] となるような非負整数のインデックス i が存在するとき、かつそのときにかぎり True となります。インデックス i が負である場合に IndexError 例外が送出されることはありません。 (他の何らかの例外が送出された場合、例外は in から送出されたかのようになります)。

演算子 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

ブール演算のコンテキストや、式が制御フローの文で使われる際には、次の値は偽だと解釈されます: False 、 None 、すべての型における数値の 0、空の文字列、空のコンテナ (文字列、タプル、リスト、辞書、集合、凍結集合など)。 それ以外の値は真だと解釈されます。 ユーザ定義のオブジェクトは、 __bool__() メソッドを与えることで、真偽値をカスタマイズできます。

演算子 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. 条件式 (Conditional Expressions)

conditional_expression ::=  or_test ["if" or_test "else" expression]
expression             ::=  conditional_expression | lambda_expr
expression_nocond      ::=  or_test | lambda_expr_nocond

条件式 (しばしば "三項演算子" と呼ばれます) は最も優先度が低いPython の演算です。

x if C else y という式は最初に条件 x ではなく C を評価します; C が true の場合 x が評価され値が返されます; それ以外の場合には y が評価され返されます。

条件演算に関してより詳しくは PEP 308 を参照してください。

6.13. ラムダ (lambda)

lambda_expr        ::=  "lambda" [parameter_list] ":" expression
lambda_expr_nocond ::=  "lambda" [parameter_list] ":" expression_nocond

ラムダ式 (ラムダ形式とも呼ばれます) は無名関数を作成するのに使います。 式 lambda parameters: expression は関数オブジェクトになります。 この無名オブジェクトは以下に定義されている関数オブジェクト同様に動作します:

def <lambda>(parameters):
    return expression

引数の一覧の構文は 関数定義 を参照してください。ラムダ式で作成された関数は文やアノテーションを含むことができない点に注意してください。

6.14. 式のリスト

expression_list    ::=  expression ("," expression)* [","]
starred_list       ::=  starred_item ("," starred_item)* [","]
starred_expression ::=  expression | (starred_item ",")* [starred_item]
starred_item       ::=  expression | "*" or_expr

リスト表示や辞書表示の一部になっているものを除き、少なくとも一つのカンマを含む式のリストはタプルになります。 タプルの長さは、リストにある式の数に等しくなります。 式は左から右へ評価されます。

アスタリスク * は イテラブルのアンパック を意味します。 この被演算子は イテラブル でなければなりません。 このイテラブルはアンパックされた位置で要素のシーケンスに展開され、新しいタプル、リスト、集合に入れ込まれます。

バージョン 3.5 で追加: 式リストでのイテラブルのアンパックは最初に PEP 448 で提案されました。

単一要素のタプル (別名 単集合 (singleton) ) を作りたければ、末尾にカンマが必要です。単一の式だけで、末尾にカンマをつけない場合には、タプルではなくその式の値になります (空のタプルを作りたいなら、中身が空の丸括弧ペア: () を使います。)

6.15. 評価順序

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.16. 演算子の優先順位

以下の表は Python における演算子の優先順位を要約したものです。優先順位の最も低い (結合が最も弱い) ものから最も高い (結合が最も強い) ものに並べてあります。同じボックス内の演算子の優先順位は同じです。構文が明示的に示されていないものは二項演算子です。同じボックス内の演算子は、左から右へとグループ化されます (例外として、べき乗は右から左にグループ化されます)。

比較 節で述べられているように、比較、所属、同一性のテストは全てが同じ優先順位を持っていて、左から右に連鎖するという特徴を持っていることに注意してください。

演算子 | 説明
lambda | ラムダ式
if -- else | 条件式
or | ブール演算 OR
and | ブール演算 AND
not x | ブール演算 NOT
in, not in, is, is not, <, <=, >, >=, !=, == | 所属や同一性のテストを含む比較
| | ビット単位 OR
^ | ビット単位 XOR
& | ビット単位 AND
<<, >> | シフト演算
+, - | 加算および減算
*, @, /, //, % | 乗算、行列乗算、除算、切り捨て除算、剰余 [5]
+x, -x, ~x | 正数、負数、ビット単位 NOT
** | べき乗 [6]
await x | Await 式
x[index], x[index:index], x(arguments...), x.attribute | 添字指定、スライス操作、呼び出し、属性参照
(expressions...), [expressions...], {key: value...}, {expressions...} | 式結合またはタプル表示、リスト表示、辞書表示、集合表示

脚注

[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] % 演算子は文字列フォーマットにも使われ、同じ優先順位が当てはまります。
[6] べき乗演算子 ** はその右側にある単項演算子かビット単位演算子よりも優先して結合します。つまり 2**-1 は 0.5 になります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python 言語リファレンス »


7. 単純文 (simple statement)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 言語リファレンス »

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

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 が送出されます (添字指定されたシーケンスに代入を行っても、リスト要素の新たな追加はできません)。

    一次語が (辞書のような) マップオブジェクトの場合、まず添字はマップのキー型と互換性のある型でなくてはなりません。次に、添字を被代入オブジェクトに関連付けるようなキー/データの対を生成するようマップオブジェクトに問い合わせます。この操作では、既存のキー/値の対を同じキーと別の値で置き換えてもよく、(同じ値を持つキーが存在しない場合) 新たなキー/値の対を挿入してもかまいません。

    ユーザ定義のオブジェクトには、適切な引数で __setitem__() メソッドが呼び出されます。

  • ターゲットがスライスなら: 参照されている一次語式が評価されます。一次語式は、(リストのような) ミュータブルなシーケンスオブジェクトを与えなければなりません。被代入オブジェクトは同じ型のシーケンスオブジェクトでなければなりません。次に、スライスの下限と上限を示す式があれば評価されます; デフォルト値はそれぞれ 0 とシーケンスの長さです。上限と下限の評価は整数でなければなりません。いずれかの境界が負数なら、シーケンスの長さが加算されます。最終的に、境界は 0 からシーケンスの長さまでに収まるように刈りこまれます。最後に、スライスを被代入オブジェクトで置き換えてよいかシーケンスオブジェクトに問い合わせます。ターゲットシーケンスで許されている限り、スライスの長さは被代入シーケンスの長さと異なっていてよく、この場合にはターゲットシーケンスの長さが変更されます。

CPython implementation detail: 現在の実装では、ターゲットの構文は式の構文と同じであるとみなされており、無効な構文はコード生成フェーズ中に詳細なエラーメッセージを伴って拒否されます。

代入の定義によれば、左辺と右辺のオーバーラップは '同時 (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 - 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)

Annotation assignment is the combination, in a single statement, of a variable or attribute annotation and an optional assignment statement:

annotated_assignment_stmt ::=  augtarget ":" expression ["=" expression]

代入文 (assignment statement) との違いは、代入先が 1 つに限定され右辺の値も 1 つに限定されることです。

代入先として単純名を使うと、クラススコープもしくはモジュールスコープの場合、注釈は評価され、クラスもしくはモジュールの特殊属性 __annotations__ に格納されます。 この属性は、変数名 (プライベート変数の場合はマングリングされた名前) から評価後の注釈への対応付けを持つ辞書です。 この属性は書き込み可能であり、注釈が静的に存在している場合、クラスもしくはモジュールの本体の実行の先頭で自動的に作成されます。

代入先として式を使うと、クラススコープもしくはモジュールスコープの場合、注釈は評価されますが、格納されません。

関数スコープで名前に注釈が付いていた場合は、その名前はその関数スコープでローカルなものになります。 注釈は絶対に評価されず、関数スコープにも格納されません。

右辺がある場合、注釈代入はアノテーション (有効であれば) を評価する前に、実際に代入を行います。 対象となる式の右辺が無い場合は、インタプリタは最後の __setitem__() や __setattr__() 呼び出し以外の対象の式を評価します。

参考

PEP 526 - Syntax for Variable Annotations
(クラス変数やインスタンス変数を含んだ) 変数の型注釈を付ける、コメントで表現するのではない文法の追加提案。
PEP 484 - Type hints
typing モジュールを追加し、静的解析ツールや IDE で使える型アノテーションの標準的な文法を提供する提案。

7.3. The assert statement

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. The pass statement

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. The del statement

del_stmt ::=  "del" target_list

オブジェクトの削除 (deletion) は、代入の定義と非常に似た方法で再帰的に定義されています。ここでは完全な詳細は記述せず、いくつかのヒントを述べるにとどめます。

ターゲットリストに対する削除は、各々のターゲットを左から右へと順に再帰的に削除します。

名前の削除は、ローカルまたはグローバル名前空間からその名前の束縛を取り除きます。どちらの名前空間かは、名前が同じコードブロック内の global 文で宣言されているかどうかによります。名前が未束縛 (unbound) なら、 NameError 例外が送出されます。

属性参照、添字表記、およびスライスの削除操作は、対象となる一次語オブジェクトに渡されます; スライスの削除は一般的には適切な型の空のスライスを代入するのと等価です (が、この仕様自体もスライスされるオブジェクトで決定されています)。

バージョン 3.2 で変更: 以前は、ある名前がネストしたブロックの自由変数として表れる場合は、ローカル名前空間からその名前を削除することは不正な処理でした。

7.6. The return statement

return_stmt ::=  "return" [expression_list]

return は、関数定義内で構文法的にネストして現れますが、ネストしたクラス定義内には現れません。

式リストがある場合、リストが値評価されます。それ以外の場合は None で置き換えられます。

return を使うと、式リスト (または None) を戻り値として、現在の関数呼び出しから抜け出します。

When return passes control out of a try statement with a finally clause, that finally clause is executed before really leaving the function.

ジェネレータ関数では、 return 文はジェネレータの終わりを示し、 StopIteration 例外を送出させます。返された値は (あれば)、 StopIteration を構成する引数に使われ、 StopIteration.value 属性になります。

In an asynchronous generator function, an empty return statement indicates that the asynchronous generator is done and will cause StopAsyncIteration to be raised. A non-empty return statement is a syntax error in an asynchronous generator function.

7.7. The yield statement

yield_stmt ::=  yield_expression

yield 文は意味的に yield expression 式と同じです。yield 文を用いると yield 式文で必要な括弧を省略することが出来ます。例えば、yield 文

yield <expr>
yield from <expr>

は以下の yield 式文と等価です

(yield <expr>)
(yield from <expr>)

yield 式及び文は generator を定義するときに、その本体内でのみ使うことが出来ます。関数定義内で yield を使用することで、その定義は通常の関数でなくジェネレータ関数になります。

yield の意味の完全な説明は、 Yield 式 節を参照してください。

7.8. The raise statement

raise_stmt ::=  "raise" [expression ["from" expression]]

式を伴わなければ、 raise は現在のスコープで最終的に有効になっている例外を再送出します。そのような例外が現在のスコープでアクティブでない場合、 RuntimeError 例外が送出されて、これがエラーであることを示します。

そうでなければ、 raise は最初の式を、例外オブジェクトとして評価します。これは、 BaseException のサブクラスまたはインスタンスでなければなりません。クラスなら、例外インスタンスが必要なとき、クラスを無引数でインスタンス化することで得られます。

例外の 型 は例外インスタンスのクラスで、 値 はインスタンスそのものです。

トレースバックオブジェクトは通常、例外が送出される時に自動で作られ、その例外に書き込み可能の __traceback__ 属性として付与されます。 with_traceback() 例外メソッド (トレースバックを引数に設定した同じ例外を返します) を使い、例外を作って独自のトレースバックを設定するのを一度に出来ます。このように:

raise Exception("foo occurred").with_traceback(tracebackobj)

from 節は例外の連鎖に使われます: 第二の expression は、与えられるなら、別の例外クラスまたはインスタンスでなければならず、これが送出された例外に (書き込み可能の) __cause__ 属性として付与されます。送出された例外がハンドルされなければ、両方の例外が印字されます:

>>> 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>
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>
RuntimeError: Something bad happened

例外ハンドラまたは finally 節の中で例外が送出された時も、同じような機構が暗黙に働きます。このとき、先に起こった例外が、新しい例外の __context__ 属性に付与されます:

>>> try:
...     print(1 / 0)
... except:
...     raise RuntimeError("Something bad happened")
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
ZeroDivisionError: division by zero

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened

from 節に None を指定することで、例外の連鎖を明示的に非表示にできます:

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

例外に関する追加情報は 例外 節にあります。また、例外処理に関する情報は The try statement 節にあります。

バージョン 3.3 で変更: None が raise X from Y の Y として使えるようになりました。

バージョン 3.3 で追加: __suppress_context__ 属性の設定で、例外のコンテキストが自動的に非表示になります。

7.9. The break statement

break_stmt ::=  "break"

break 文は、構文としては for ループや while ループの内側でのみ出現することができますが、ループ内の関数定義やクラス定義の内側には出現できません。

It terminates the nearest enclosing loop, skipping the optional else clause if the loop has one.

for ループを break によって終了すると、ループ制御ターゲットはその時の値を保持します。

When break passes control out of a try statement with a finally clause, that finally clause is executed before really leaving the loop.

7.10. The continue statement

continue_stmt ::=  "continue"

continue 文は for ループや while ループ内のネストで構文法的にのみ現れますが、ループ内の関数定義やクラス定義、 finally 句の中には現れません。 continue 文は、文を囲う最も内側のループの次の周期に処理を継続します。

When continue passes control out of a try statement with a finally clause, that finally clause is executed before really starting the next loop cycle.

7.11. The import statement

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" module "import" "*"
module          ::=  (identifier ".")* identifier
relative_module ::=  "."* module | "."+

(from 節が無い) 基本の import 文は 2 つのステップで実行されます:

  1. モジュールを見付け出し、必要であればロードし初期化する
  2. import 文が表れるスコープのローカル名前空間で名前を定義する。

文が (カンマで区切られた) 複数の節を含んでいるときは、ちょうどその節が個別の import 文に分割されたかのように、2つのステップが節ごとに個別に実行されます。

モジュールを見付け、ロードする 1 つ目のステップの詳細については、 インポートシステム の節により詳しく書かれています。そこでは、インポートシステムの動作をカスタマイズするのに使える全てのフックの仕組みだけでなく、様々な種類のインポートできるパッケージとモジュールについても解説されています。このステップが失敗するということは、おそらくモジュールが見付からないか、 あるいは モジュールにあるコードの実行を含め、モジュールの初期化の途中でエラーが起きるかのどちらかが起きていることに注意してください。

要求したモジュールが無事に取得できた場合、次の 3 つのうちの 1 つの方法でローカル名前空間で使えるようになります:

  • If the module name is followed by as, then the name following as is bound directly to the imported module.
  • 他の名前が指定されておらず、インポートされているモジュールが最上位のモジュールだった場合、そのモジュール名がインポートされたモジュールへの参照として、ローカル名前空間で束縛されます
  • インポートされているモジュールが最上位のモジュール でない 場合、モジュールを含む最上位のパッケージ名が、そのパッケージへの参照として、ローカル名前空間で束縛されます。インポートされたモジュールには、直接ではなく完全修飾名を使ってアクセスしなければなりません

from 形式ではもう少し複雑な手順を踏みます:

  1. from 節で指定されたモジュールを見付け出し、必要であればロードし初期化する;
  2. import 節で指定されたそれぞれの識別子に対し以下の処理を行う:
    1. インポートされたモジュールがその識別子名の属性を持っているかを確認する
    2. 持っていなかった場合は、その識別子名でサブモジュールのインポートを試み、再度その属性がインポートされたモジュールにあるか確認する
    3. 属性が見付からない場合は、 ImportError を送出する。
    4. otherwise, a reference to that value is stored in the local namespace, using the name in the as clause if it is present, otherwise using the attribute name

例:

import foo                 # foo imported and bound locally
import foo.bar.baz         # foo.bar.baz imported, foo bound locally
import foo.bar.baz as fbb  # foo.bar.baz imported and bound as fbb
from foo.bar import baz    # foo.bar.baz imported and 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 をインポートします。相対インポートの仕様は PEP 328 に含まれています。

どのモジュールがロードされるべきかを動的に決めたいアプリケーションのために、組み込み関数 importlib.import_module() が提供されています。

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 文を使う必要がある Python 3.7 の唯一の機能は annotations です。

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 文であり、その他の特殊な意味付けや構文的な制限はありません。

future 文の入ったモジュール M 内で使われている組み込み関数 exec() や compile() によってコンパイルされるコードは、デフォルトの設定では、 future 文に関係する新たな構文や意味付けを使うようになっています。この仕様は compile() のオプション引数で制御できます --- 詳細はこの関数に関するドキュメントを参照してください。

対話的インタプリタのプロンプトでタイプ入力した future 文は、その後のインタプリタセッション中で有効になります。インタプリタを -i オプションで起動して実行すべきスクリプト名を渡し、スクリプト中に future 文を入れておくと、新たな機能はスクリプトが実行された後に開始する対話セッションで有効になります。

参考

PEP 236 - Back to the __future__
__future__ 機構の原案

7.12. The global statement

global_stmt ::=  "global" identifier ("," identifier)*

The global statement is a declaration which holds for the entire current code block. It means that the listed identifiers are to be interpreted as globals. It would be impossible to assign to a global variable without global, although free variables may refer to globals without being declared global.

Names listed in a global statement must not be used in the same code block textually preceding that global statement.

global 文で列挙する名前は、 for ループのループ制御ターゲットや、 class 定義、関数定義、 import 文、変数アノテーションで仮引数として使ってはなりません。

CPython implementation detail: 現在の実装では、これらの制限のうち幾つかについては強制していませんが、プログラムでこの緩和された仕様を乱用すべきではありません。将来の実装では、この制限を強制したり、暗黙のうちにプログラムの意味付けを変更したりする可能性があります。

Programmer's note: global is a directive to the parser. It applies only to code parsed at the same time as the global statement. In particular, a global statement contained in a string or code object supplied to the built-in exec() function does not affect the code block containing the function call, and code contained in such a string is unaffected by global statements in the code containing the function call. The same applies to the eval() and compile() functions.

7.13. The nonlocal statement

nonlocal_stmt ::=  "nonlocal" identifier ("," identifier)*

nonlocal 文は、列挙された識別子がグローバルを除く一つ外側のスコープで先に束縛された変数を参照するようにします。これは、束縛のデフォルトの動作がまずローカル名前空間を探索するので重要です。この文は、中にあるコードが、グローバル (モジュール) スコープ以外のローカルスコープの外側の変数を再束縛できるようにします。

nonlocal 文で列挙された名前は、 global 文で列挙された名前と違い、外側のスコープですでに存在する束縛を参照しなければなりません (新しい束縛が作られるべきスコープの選択が曖昧さを排除できません)。

nonlocal 文で列挙された名前は、ローカルスコープですでに存在する束縛と衝突してはなりません。

参考

PEP 3104 - Access to Names in Outer Scopes
nonlocal 文の詳細。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python 言語リファレンス »


8. 複合文 (compound statement)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 言語リファレンス »

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
                   | 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. The if statement

if 文は、条件分岐を実行するために使われます:

if_stmt ::=  "if" expression ":" suite
             ("elif" expression ":" suite)*
             ["else" ":" suite]

if 文は、式を一つ一つ評価してゆき、真になるまで続けて、真になった節のスイートだけを選択します (真: true と偽: false の定義については、 ブール演算 (boolean operation) 節を参照してください); 次に、選択したスイートを実行します (そして、 if 文の他の部分は、実行や評価をされません)。全ての式が偽になった場合、 else 節があれば、そのスイートが実行されます。

8.2. The while statement

while 文は、式の値が真である間、実行を繰り返すために使われます:

while_stmt ::=  "while" expression ":" suite
                ["else" ":" suite]

This repeatedly tests the expression and, if it is true, executes the first suite; if the expression is false (which may be the first time it is tested) the suite of the else clause, if present, is executed and the loop terminates.

A break statement executed in the first suite terminates the loop without executing the else clause's suite. A continue statement executed in the first suite skips the rest of the suite and goes back to testing the expression.

8.3. The for statement

for 文は、シーケンス (文字列、タプルまたはリスト) や、その他の反復可能なオブジェクト (iterable object) 内の要素に渡って反復処理を行うために使われます:

for_stmt ::=  "for" target_list "in" expression_list ":" suite
              ["else" ":" suite]

The expression list is evaluated once; it should yield an iterable object. An iterator is created for the result of the expression_list. The suite is then executed once for each item provided by the iterator, in the order returned by the iterator. Each item in turn is assigned to the target list using the standard rules for assignments (see 代入文 (assignment statement)), and then the suite is executed. When the items are exhausted (which is immediately when the sequence is empty or an iterator raises a StopIteration exception), the suite in the else clause, if present, is executed, and the loop terminates.

A break statement executed in the first suite terminates the loop without executing the else clause's suite. A continue statement executed in the first suite skips the rest of the suite and continues with the next item, or with the else clause if there is no next item.

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() は、 Pascal の for i := a to b do の効果をエミュレートするのに適した、整数のイテレータを返します; すなわち、 list(range(3)) はリスト [0, 1, 2] を返します。

注釈

ループ中でのシーケンスの変更には微妙な問題があります (これはミュータブルなシーケンスのみ、例えばリストで起こり得ます)。 どの要素が次に使われるかを追跡するために、内部的なカウンタが使われており、このカウンタは反復のたびに加算されます。 このカウンタがシーケンスの長さに達すると、ループは終了します。 このことから、スイートの中でシーケンスから現在の (または以前の) 要素を除去すると、(次の要素の位置が、既に処理済みの現在の要素のインデックスになるために) 次の要素が飛ばされることになります。 同様に、スイートの中でシーケンス中の現在の要素以前に要素を挿入すると、現在の要素がループの次の週で再度扱われることになります。 こうした仕様は、厄介なバグにつながります。 これは、シーケンス全体のスライスを使って一時的なコピーを作ることで避けられます。 例えば次のようにします:

for x in a[:]:
    if x < 0: a.remove(x)

8.4. The try statement

try 文は、ひとまとめの文に対して、例外処理および/またはクリーンアップコードを指定します:

try_stmt  ::=  try1_stmt | try2_stmt
try1_stmt ::=  "try" ":" suite
               ("except" [expression ["as" identifier]] ":" suite)+
               ["else" ":" suite]
               ["finally" ":" suite]
try2_stmt ::=  "try" ":" suite
               "finally" ":" suite

The except clause(s) specify one or more exception handlers. When no exception occurs in the try clause, no exception handler is executed. When an exception occurs in the try suite, a search for an exception handler is started. This search inspects the except clauses in turn until one is found that matches the exception. An expression-less except clause, if present, must be last; it matches any exception. For an except clause with an expression, that expression is evaluated, and the clause matches the exception if the resulting object is "compatible" with the exception. An object is compatible with an exception if it is the class or a base class of the exception object or a tuple containing an item compatible with the exception.

例外がどの except 節にも合致しなかった場合、現在のコードを囲うさらに外側、そして呼び出しスタックへと検索を続けます。 [1]

except 節のヘッダにある式を値評価するときに例外が発生すると、元々のハンドラ検索はキャンセルされ、新たな例外に対する例外ハンドラの検索を現在の except 節の外側のコードや呼び出しスタックに対して行います (try 文全体が例外を発行したかのように扱われます)。

When a matching except clause is found, the exception is assigned to the target specified after the as keyword in that except clause, if present, and the except clause's suite is executed. All except clauses must have an executable block. When the end of this block is reached, execution continues normally after the entire try statement. (This means that if two nested handlers exist for the same exception, and the exception occurs in the try clause of the inner handler, the outer handler will not handle the exception.)

例外が as target を使って代入されたとき、それは except 節の終わりに消去されます。これはちょうど、以下のコード:

except E as N:
    foo

が、以下のコードに翻訳されたかのようなものです:

except E as N:
    try:
        foo
    finally:
        del N

よって、例外を except 節以降で参照できるようにするためには、別の名前に代入されなければなりません。例外が削除されるのは、トレースバックが付与されると、そのスタックフレームと循環参照を形作り、次のガベージ収集までそのフレーム内のすべての局所変数を生存させてしまうからです。

except 節のスイートが実行される前に、例外に関する詳細が sys モジュールに保存され、 sys.exc_info() からアクセスできます。 sys.exc_info() は、例外クラス、例外インスタンス、そして例外が発生したプログラム上の位置を識別するトレースバックオブジェクト (標準型の階層 を参照してください) の 3 要素からなるタプルを返します。 sys.exc_info() の値は、例外を処理した関数から戻るときに、以前 (関数呼び出し前) の値に戻されます。

The optional else clause is executed if the control flow leaves the try suite, no exception was raised, and no return, continue, or break statement was executed. Exceptions in the else clause are not handled by the preceding except clauses.

If finally is present, it specifies a 'cleanup' handler. The try clause is executed, including any except and else clauses. If an exception occurs in any of the clauses and is not handled, the exception is temporarily saved. The finally clause is executed. If there is a saved exception it is re-raised at the end of the finally clause. If the finally clause raises another exception, the saved exception is set as the context of the new exception. If the finally clause executes a return or break statement, the saved exception is discarded:

>>> def f():
...     try:
...         1/0
...     finally:
...         return 42
...
>>> f()
42

finally 節を実行している間は、プログラムからは例外情報は利用できません。

When a return, break or continue statement is executed in the try suite of a try...finally statement, the finally clause is also executed 'on the way out.' A continue statement is illegal in the finally clause. (The reason is a problem with the current implementation --- this restriction may be lifted in the future).

The return value of a function is determined by the last return statement executed. Since the finally clause always executes, a return statement executed in the finally clause will always be the last one executed:

>>> def foo():
...     try:
...         return 'try'
...     finally:
...         return 'finally'
...
>>> foo()
'finally'

例外に関するその他の情報は 例外 節にあります。また、 raise 文の使用による例外の生成に関する情報は、 The raise statement 節にあります。

8.5. The with statement

with 文は、ブロックの実行を、コンテキストマネージャによって定義されたメソッドでラップするために使われます (with文とコンテキストマネージャ セクションを参照してください)。これにより、よくある try...except...finally 利用パターンをカプセル化して便利に再利用することができます。

with_stmt ::=  "with" with_item ("," with_item)* ":" suite
with_item ::=  expression ["as" target]

一つの "要素" を持つ with 文の実行は以下のように進行します:

  1. コンテキスト式 (with_item で与えられた式) を評価することで、コンテキストマネージャを取得します。

  2. コンテキストマネージャの __exit__() メソッドが、後で使うためにロードされます。

  3. コンテキストマネージャの __enter__() メソッドが呼ばれます。

  4. with 文にターゲットが含まれていたら、それに __enter__() からの戻り値が代入されます。

    注釈

    with 文は、 __enter__() メソッドがエラーなく終了した場合には __exit__() が常に呼ばれることを保証します。ですので、もしターゲットリストへの代入中にエラーが発生した場合には、これはそのスイートの中で発生したエラーと同じように扱われます。以下のステップ 6 を参照してください。

  5. スイートが実行されます。

  6. コンテキストマネージャの __exit__() メソッドが呼ばれます。スイートが例外によって終了されたのなら、その例外の型、値、トレースバックが __exit__() に引数として渡されます。そうでなければ、 3 つの None 引数が与えられます。

    スイートが例外により終了され、 __exit__() メソッドからの戻り値が偽（false）ならば、例外が再送出されます。この戻り値が真（true）ならば例外は抑制され、実行は with 文の次の文から続きます。

    もしそのスイートが例外でない何らかの理由で終了した場合、その __exit__() からの戻り値は無視されて、実行は発生した終了の種類に応じた通常の位置から継続します。

複数の要素があるとき、コンテキストマネージャは複数の with 文がネストされたかのように進行します:

with A() as a, B() as b:
    suite

は、以下と同等です

with A() as a:
    with B() as b:
        suite

バージョン 3.1 で変更: 複数のコンテキスト式をサポートしました。

参考

PEP 343 - "with" ステートメント
Python の with 文の仕様、背景、および例が記載されています。

8.6. 関数定義

関数定義は、ユーザ定義関数オブジェクトを定義します (標準型の階層 節参照):

funcdef                 ::=  [decorators] "def" funcname "(" [parameter_list] ")"
                             ["->" expression] ":" suite
decorators              ::=  decorator+
decorator               ::=  "@" dotted_name ["(" [argument_list [","]] ")"] NEWLINE
dotted_name             ::=  identifier ("." identifier)*
parameter_list          ::=  defparameter ("," defparameter)* ["," [parameter_list_starargs]]
                             | parameter_list_starargs
parameter_list_starargs ::=  "*" [parameter] ("," defparameter)* ["," ["**" parameter [","]]]
                             | "**" parameter [","]
parameter               ::=  identifier [":" expression]
defparameter            ::=  parameter ["=" expression]
funcname                ::=  identifier

関数定義は実行可能な文です。関数定義を実行すると、現在のローカルな名前空間内で関数名を関数オブジェクト (関数の実行可能コードをくるむラッパ) に束縛します。この関数オブジェクトには、関数が呼び出された際に使われるグローバルな名前空間として、現在のグローバルな名前空間への参照が入っています。

関数定義は関数本体を実行しません; 関数本体は関数が呼び出された時にのみ実行されます。 [2]

関数定義は一つ以上のデコレータ (decorator) 式でラップできます。デコレータ式は関数を定義するとき、関数定義の入っているスコープで評価されます。その結果は、関数オブジェクトを唯一の引数にとる呼び出し可能オブジェクトでなければなりません。関数オブジェクトの代わりに、返された値が関数名に束縛されます。複数のデコレータはネストして適用されます。例えば、以下のようなコード:

@f1(arg)
@f2
def func(): pass

は、だいたい次と等価です

def func(): pass
func = f1(arg)(f2(func))

ただし、前者のコードでは元々の関数を func という名前へ一時的に束縛することはない、というところを除きます。

1 つ以上の 仮引数 が parameter = expression の形を取っているとき、関数は "デフォルト引数値" を持つと言います。デフォルト値を持つ仮引数では、呼び出し時にそれに対応する実引数 (argument) は省略でき、その場合は仮引数のデフォルト値が使われます。ある引数がデフォルト値を持っている場合、それ以降 "*" が出てくるまでの引数は全てデフォルト値を持っていなければなりません -- これは文法定義では表現されていない構文的制限です。

デフォルト引数値は関数定義が実行されるときに左から右へ評価されます。 これは、デフォルト引数の式は関数が定義されるときにただ一度だけ評価され、同じ "計算済みの" 値が呼び出しのたびに使用されることを意味します。この仕様を理解しておくことは特に、デフォルト引数値がリストや辞書のようなミュータブルなオブジェクトであるときに重要です: 関数がこのオブジェクトを変更 (例えばリストに要素を追加) すると、このデフォルト値が変更の影響を受けてしまします。一般には、これは意図しない動作です。このような動作を避けるには、デフォルト値として 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" の後のパラメタはキーワード専用パラメータで、キーワード引数を使ってのみ渡されます。

Parameters may have annotations of the form ": expression" following the parameter name. Any parameter may have an annotation even those of the form *identifier or **identifier. Functions may have "return" annotation of the form "-> expression" after the parameter list. These annotations can be any valid Python expression. The presence of annotations does not change the semantics of a function. The annotation values are available as values of a dictionary keyed by the parameters' names in the __annotations__ attribute of the function object. If the annotations import from __future__ is used, annotations are preserved as strings at runtime which enables postponed evaluation. Otherwise, they are evaluated when the function definition is executed. In this case annotations may be evaluated in a different order than they appear in the source code.

It is also possible to create anonymous functions (functions not bound to a name), for immediate use in expressions. This uses lambda expressions, described in section ラムダ (lambda). Note that the lambda expression is merely a shorthand for a simplified function definition; a function defined in a "def" statement can be passed around or assigned to another name just like a function defined by a lambda expression. The "def" form is actually more powerful since it allows the execution of multiple statements and annotations.

プログラマへのメモ: 関数は第一級オブジェクトです。関数定義内で実行された "def" 文は、返り値や引数として渡せるローカル関数を定義します。ネストした関数内で使われる自由変数は、 def を含んでいる関数のローカル変数にアクセスできます。詳細は 名前づけと束縛 (naming and binding) 節を参照してください。

参考

PEP 3107 - Function Annotations
関数アノテーションの元の仕様書。
PEP 484 - 型ヒント
アノテーションの標準的な意味付けである型ヒントの定義。
PEP 526 - Syntax for Variable Annotations
クラス変数とインスタンス変数を含む変数に型ヒントが宣言できる機能
PEP 563 - アノテーションの遅延評価
実行時にアノテーションを貪欲評価するのではなく文字列形式で保持することによる、アノテーションにおける前方参照のサポート

8.7. クラス定義

クラス定義は、クラスオブジェクトを定義します (標準型の階層 節参照):

classdef    ::=  [decorators] "class" classname [inheritance] ":" suite
inheritance ::=  "(" [argument_list] ")"
classname   ::=  identifier

クラス定義は実行可能な文です。継承リストは通常、基底クラスリストを与えます (より高度な使い方は、 メタクラス を参照してください)。ですから、リストのそれぞれの要素の評価はサブクラス化しても良いクラスであるべきです。継承リストのないクラスは、デフォルトで、基底クラス object を継承するので:

class Foo:
    pass

は、以下と同等です

class Foo(object):
    pass

次にクラスのスイートが、新たな実行フレーム (名前づけと束縛 (naming and binding) を参照してください) 内で、新たに作られたローカル名前空間と元々のグローバル名前空間を使って実行されます (通常、このスイートには主に関数定義が含まれます)。クラスのスイートが実行し終えると、実行フレームは破棄されますが、ローカルな名前空間は保存されます。[3] 次に、継承リストを基底クラスに、保存されたローカル名前空間を属性値辞書に、それぞれ使ってクラスオブジェクトが生成されます。最後に、もとのローカル名前空間において、クラス名がこのクラスオブジェクトに束縛されます。

クラス本体で属性が定義された順序は新しいクラスの __dict__ に保持されます。 この性質が期待できるのは、クラスが作られた直後かつ定義構文を使って定義されたクラスであるときのみです。

クラス作成は、 メタクラス を利用して大幅にカスタマイズできます。

関数をデコレートするのと同じように、クラスもデコレートすることが出来ます、

@f1(arg)
@f2
class Foo: pass

は、だいたい次と等価です

class Foo: pass
Foo = f1(arg)(f2(Foo))

デコレータ式の評価規則は関数デコレータと同じです。結果はクラス名に束縛されます。

プログラマのための注釈: クラス定義内で定義された変数はクラス属性であり、全てのインスタンス間で共有されます。インスタンス属性は、メソッドの中で self.name = value とすることで設定できます。クラス属性もインスタンス属性も "self.name" 表記でアクセスでき、この表記でアクセスしたとき、インスタンス属性は同名のクラス属性を隠蔽します。クラス属性は、インスタンス属性のデフォルト値として使えますが、そこにミュータブルな値を使うと予期せぬ結果につながります。 記述子 を使うと、詳細な実装が異なるインスタンス変数を作成できます。

参考

PEP 3115 - Metaclasses in Python 3000
メタクラスの宣言を現在の文法と、メタクラス付きのクラスがどのように構築されるかの意味論を変更した提案
PEP 3129 - クラスデコレータ
クラスデコレータを追加した提案。 関数デコレータとメソッドデコレータは PEP 318 で導入されました。

8.8. コルーチン

バージョン 3.5 で追加.

8.8.1. コルーチン関数定義

async_funcdef ::=  [decorators] "async" "def" funcname "(" [parameter_list] ")"
                   ["->" expression] ":" suite

Python で実行しているコルーチンは多くの時点で一時停止と再開ができます (coroutine を参照してください)。 コルーチン関数の本体では、 await 識別子と async 識別子は予約語になります; 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()

8.8.2. The async for statement

async_for_stmt ::=  "async" for_stmt

asynchronous iterable の iter の実装からは非同期のコードが呼べ、 asynchronous iterator の next メソッドからも非同期のコードが呼べます。

async for 文によって非同期なイテレータを簡単にイテレーションすることができます。

以下のコード:

async for TARGET in ITER:
    BLOCK
else:
    BLOCK2

は意味論的に以下と等価です:

iter = (ITER)
iter = type(iter).__aiter__(iter)
running = True
while running:
    try:
        TARGET = await type(iter).__anext__(iter)
    except StopAsyncIteration:
        running = False
    else:
        BLOCK
else:
    BLOCK2

詳細は __aiter__() や __anext__() を参照してください。

コルーチン関数の本体の外で async for 文を使用すると SyntaxError になります。

8.8.3. The async with statement

async_with_stmt ::=  "async" with_stmt

asynchronous context manager は、 enter メソッドと exit メソッド内部で実行を一時停止できる context manager です。

以下のコード:

async with EXPR as VAR:
    BLOCK

は意味論的に以下と等価です:

mgr = (EXPR)
aexit = type(mgr).__aexit__
aenter = type(mgr).__aenter__(mgr)

VAR = await aenter
try:
    BLOCK
except:
    if not await aexit(mgr, *sys.exc_info()):
        raise
else:
    await aexit(mgr, None, None, None)

詳細は __aenter__() や __aexit__() を参照してください。

コルーチン関数の本体の外で async with 文を使用すると SyntaxError になります。

参考

PEP 492 - async 構文および await 構文付きのコルーチン
コルーチンを Python のまともな独り立ちした概念にし、サポートする構文を追加した提案。

脚注

[1] 例外は、別の例外を送出するような finally 節が無い場合にのみ呼び出しスタックへ伝わります。新しい例外によって、古い例外は失われます。
[2] 関数の本体の最初の文として現われる文字列リテラルは、その関数の __doc__ 属性に変換され、その関数のドキュメンテーション文字列(docstring) になります。
[3] クラスの本体の最初の文として現われる文字列リテラルは、その名前空間の __doc__ 要素となり、そのクラスのドキュメンテーション文字列(docstring)になります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python 言語リファレンス »


9. トップレベル要素

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 言語リファレンス »

9. トップレベル要素

Python インタプリタは、標準入力や、プログラムの引数として与えられたスクリプト、対話的にタイプ入力された命令、モジュールのソースファイルなど、様々な入力源から入力を得ることができます。この章では、それぞれの場合に用いられる構文法について説明しています。

9.1. 完全な Python プログラム

言語仕様の中では、その言語を処理するインタプリタがどのように起動されるかまで規定する必要はないのですが、完全な Python プログラムの概念を知っておくと役に立ちます。完全な Python プログラムは、最小限に初期化された環境: 全ての組み込み変数と標準モジュールが利用可能で、かつ sys (様々なシステムサービス)、 builtins (組み込み関数、例外、および None)、 __main__ の 3 つを除く全てのモジュールが初期化されていない状態で動作します。 __main__ は、完全なプログラムを実行する際に、ローカルおよびグローバルな名前空間を提供するために用いられます。

完全な Python プログラムの構文は、下の節で述べるファイル入力のためのものです。

インタプリタは、対話的モード (interactive mode) で起動されることもあります; この場合、インタプリタは完全なプログラムを読んで実行するのではなく、一度に単一の実行文 (複合文のときもあります) を読み込んで実行します。初期状態の環境は、完全なプログラムを実行するときの環境と同じです; 各実行文は、 __main__ の名前空間内で実行されます。

A complete program can be passed to the interpreter in three forms: with the -c string command line option, as a file passed as the first command line argument, or as standard input. If the file or standard input is a tty device, the interpreter enters interactive mode; otherwise, it executes the file as a complete program.

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*

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python 言語リファレンス »


10. 完全な文法仕様

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 言語リファレンス »

10. 完全な文法仕様

これは、パーサージェネレータが読み込んで、Python のソースファイルを解析するために使われる、完全な Python の文法です:

# Grammar for Python

# NOTE WELL: You should also follow all the steps listed at
# https://devguide.python.org/grammar/

# Start symbols for the grammar:
#       single_input is a single interactive statement;
#       file_input is a module or sequence of commands read from an input file;
#       eval_input is the input for the eval() functions.
# NB: compound_stmt in single_input is followed by extra NEWLINE!
single_input: NEWLINE | simple_stmt | compound_stmt NEWLINE
file_input: (NEWLINE | stmt)* ENDMARKER
eval_input: testlist NEWLINE* ENDMARKER

decorator: '@' dotted_name [ '(' [arglist] ')' ] NEWLINE
decorators: decorator+
decorated: decorators (classdef | funcdef | async_funcdef)

async_funcdef: 'async' funcdef
funcdef: 'def' NAME parameters ['->' test] ':' suite

parameters: '(' [typedargslist] ')'
typedargslist: (tfpdef ['=' test] (',' tfpdef ['=' test])* [',' [
        '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]]
      | '**' tfpdef [',']]]
  | '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]]
  | '**' tfpdef [','])
tfpdef: NAME [':' test]
varargslist: (vfpdef ['=' test] (',' vfpdef ['=' test])* [',' [
        '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]]
      | '**' vfpdef [',']]]
  | '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]]
  | '**' vfpdef [',']
)
vfpdef: NAME

stmt: simple_stmt | compound_stmt
simple_stmt: small_stmt (';' small_stmt)* [';'] NEWLINE
small_stmt: (expr_stmt | del_stmt | pass_stmt | flow_stmt |
             import_stmt | global_stmt | nonlocal_stmt | assert_stmt)
expr_stmt: testlist_star_expr (annassign | augassign (yield_expr|testlist) |
                     ('=' (yield_expr|testlist_star_expr))*)
annassign: ':' test ['=' test]
testlist_star_expr: (test|star_expr) (',' (test|star_expr))* [',']
augassign: ('+=' | '-=' | '*=' | '@=' | '/=' | '%=' | '&=' | '|=' | '^=' |
            '<<=' | '>>=' | '**=' | '//=')
# For normal and annotated assignments, additional restrictions enforced by the interpreter
del_stmt: 'del' exprlist
pass_stmt: 'pass'
flow_stmt: break_stmt | continue_stmt | return_stmt | raise_stmt | yield_stmt
break_stmt: 'break'
continue_stmt: 'continue'
return_stmt: 'return' [testlist]
yield_stmt: yield_expr
raise_stmt: 'raise' [test ['from' test]]
import_stmt: import_name | import_from
import_name: 'import' dotted_as_names
# note below: the ('.' | '...') is necessary because '...' is tokenized as ELLIPSIS
import_from: ('from' (('.' | '...')* dotted_name | ('.' | '...')+)
              'import' ('*' | '(' import_as_names ')' | import_as_names))
import_as_name: NAME ['as' NAME]
dotted_as_name: dotted_name ['as' NAME]
import_as_names: import_as_name (',' import_as_name)* [',']
dotted_as_names: dotted_as_name (',' dotted_as_name)*
dotted_name: NAME ('.' NAME)*
global_stmt: 'global' NAME (',' NAME)*
nonlocal_stmt: 'nonlocal' NAME (',' NAME)*
assert_stmt: 'assert' test [',' test]

compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | with_stmt | funcdef | classdef | decorated | async_stmt
async_stmt: 'async' (funcdef | with_stmt | for_stmt)
if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite]
while_stmt: 'while' test ':' suite ['else' ':' suite]
for_stmt: 'for' exprlist 'in' testlist ':' suite ['else' ':' suite]
try_stmt: ('try' ':' suite
           ((except_clause ':' suite)+
            ['else' ':' suite]
            ['finally' ':' suite] |
           'finally' ':' suite))
with_stmt: 'with' with_item (',' with_item)*  ':' suite
with_item: test ['as' expr]
# NB compile.c makes sure that the default except clause is last
except_clause: 'except' [test ['as' NAME]]
suite: simple_stmt | NEWLINE INDENT stmt+ DEDENT

test: or_test ['if' or_test 'else' test] | lambdef
test_nocond: or_test | lambdef_nocond
lambdef: 'lambda' [varargslist] ':' test
lambdef_nocond: 'lambda' [varargslist] ':' test_nocond
or_test: and_test ('or' and_test)*
and_test: not_test ('and' not_test)*
not_test: 'not' not_test | comparison
comparison: expr (comp_op expr)*
# <> isn't actually a valid comparison operator in Python. It's here for the
# sake of a __future__ import described in PEP 401 (which really works :-)
comp_op: '<'|'>'|'=='|'>='|'<='|'<>'|'!='|'in'|'not' 'in'|'is'|'is' 'not'
star_expr: '*' expr
expr: xor_expr ('|' xor_expr)*
xor_expr: and_expr ('^' and_expr)*
and_expr: shift_expr ('&' shift_expr)*
shift_expr: arith_expr (('<<'|'>>') arith_expr)*
arith_expr: term (('+'|'-') term)*
term: factor (('*'|'@'|'/'|'%'|'//') factor)*
factor: ('+'|'-'|'~') factor | power
power: atom_expr ['**' factor]
atom_expr: ['await'] atom trailer*
atom: ('(' [yield_expr|testlist_comp] ')' |
       '[' [testlist_comp] ']' |
       '{' [dictorsetmaker] '}' |
       NAME | NUMBER | STRING+ | '...' | 'None' | 'True' | 'False')
testlist_comp: (test|star_expr) ( comp_for | (',' (test|star_expr))* [','] )
trailer: '(' [arglist] ')' | '[' subscriptlist ']' | '.' NAME
subscriptlist: subscript (',' subscript)* [',']
subscript: test | [test] ':' [test] [sliceop]
sliceop: ':' [test]
exprlist: (expr|star_expr) (',' (expr|star_expr))* [',']
testlist: test (',' test)* [',']
dictorsetmaker: ( ((test ':' test | '**' expr)
                   (comp_for | (',' (test ':' test | '**' expr))* [','])) |
                  ((test | star_expr)
                   (comp_for | (',' (test | star_expr))* [','])) )

classdef: 'class' NAME ['(' [arglist] ')'] ':' suite

arglist: argument (',' argument)*  [',']

# The reason that keywords are test nodes instead of NAME is that using NAME
# results in an ambiguity. ast.c makes sure it's a NAME.
# "test '=' test" is really "keyword '=' test", but we have no such token.
# These need to be in a single rule to avoid grammar that is ambiguous
# to our LL(1) parser. Even though 'test' includes '*expr' in star_expr,
# we explicitly match '*' here, too, to give it proper precedence.
# Illegal combinations and orderings are blocked in ast.c:
# multiple (test comp_for) arguments are blocked; keyword unpackings
# that precede iterable unpackings are blocked; etc.
argument: ( test [comp_for] |
            test '=' test |
            '**' test |
            '*' test )

comp_iter: comp_for | comp_if
sync_comp_for: 'for' exprlist 'in' or_test [comp_iter]
comp_for: ['async'] sync_comp_for
comp_if: 'if' test_nocond [comp_iter]

# not used in grammar, but may appear in "node" passed from Parser to Compiler
encoding_decl: NAME

yield_expr: 'yield' [yield_arg]
yield_arg: 'from' test | testlist

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python 言語リファレンス »


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

Python 標準ライブラリ

Python 言語リファレンス ではプログラミング言語 Python の厳密な構文とセマンティクスについて説明されていますが、このライブラリリファレンスマニュアルでは Python とともに配付されている標準ライブラリについて説明します。また Python 配布物に収められていることの多いオプションのコンポーネントについても説明します。

Python の標準ライブラリはとても拡張性があり、下の長い目次のリストで判るように幅広いものを用意しています。このライブラリには、例えばファイル I/O のように、Python プログラマが直接アクセスできないシステム機能へのアクセス機能を提供する (Cで書かれた) 組み込みモジュールや、日々のプログラミングで生じる多くの問題に標準的な解決策を提供するPython で書かれたモジュールが入っています。これら数多くのモジュールには、プラットフォーム固有の事情をプラットフォーム独立な API へと昇華させることにより、Pythonプログラムに移植性を持たせ、それを高めるという明確な意図があります。

Windows 向けの Python インストーラはたいてい標準ライブラリのすべてを含み、しばしばそれ以外の追加のコンポーネントも含んでいます。Unix 系のオペレーティングシステムの場合は Python は一揃いのパッケージとして提供されるのが普通で、オプションのコンポーネントを手に入れるにはオペレーティングシステムのパッケージツールを使うことになるでしょう。

標準ライブラリに加えて、数千のコンポーネントが (独立したプログラムやモジュールからパッケージ、アプリケーション開発フレームワークまで) 成長し続けるコレクションとしてPython Package Index から入手可能です。

  • はじめに
    • Notes on availability
  • 組み込み関数
  • 組み込み定数
    • site モジュールで追加される定数
  • 組み込み型
    • 真理値判定
    • Boolean Operations --- and, or, not
    • 比較
    • 数値型 int, float, complex
    • イテレータ型
    • シーケンス型 --- list, tuple, range
    • テキストシーケンス型 --- str
    • バイナリシーケンス型 --- bytes, bytearray, memoryview
    • set（集合）型 --- set, frozenset
    • マッピング型 --- dict
    • コンテキストマネージャ型
    • その他の組み込み型
    • 特殊属性
  • 組み込み例外
    • 基底クラス
    • 具象例外
    • 警告
    • 例外のクラス階層
  • テキスト処理サービス
    • string --- 一般的な文字列操作
    • re --- 正規表現操作
    • difflib --- 差分の計算を助ける
    • textwrap --- テキストの折り返しと詰め込み
    • unicodedata --- Unicode データベース
    • stringprep --- インターネットのための文字列調製
    • readline --- GNU readline のインタフェース
    • rlcompleter --- GNU readline向け補完関数
  • バイナリデータ処理
    • struct --- バイト列をパックされたバイナリデータとして解釈する
    • codecs --- codec レジストリと基底クラス
  • データ型
    • datetime --- 基本的な日付型および時間型
    • calendar --- 一般的なカレンダーに関する関数群
    • collections --- コンテナデータ型
    • collections.abc --- コレクションの抽象基底クラス
    • heapq --- ヒープキューアルゴリズム
    • bisect --- 配列二分法アルゴリズム
    • array --- 効率のよい数値アレイ
    • weakref --- 弱参照
    • types --- 動的な型生成と組み込み型に対する名前
    • copy --- 浅いコピーおよび深いコピー操作
    • pprint --- データ出力の整然化
    • reprlib --- もう一つの repr() の実装
    • enum --- 列挙型のサポート
  • 数値と数学モジュール
    • numbers --- 数の抽象基底クラス
    • math --- 数学関数
    • cmath --- 複素数のための数学関数
    • decimal --- 十進固定及び浮動小数点数の算術演算
    • fractions --- 有理数
    • random --- 擬似乱数を生成する
    • statistics --- 数理統計関数
  • 関数型プログラミング用モジュール
    • itertools --- 効率的なループ実行のためのイテレータ生成関数
    • functools --- 高階関数と呼び出し可能オブジェクトの操作
    • operator --- 関数形式の標準演算子
  • ファイルとディレクトリへのアクセス
    • pathlib --- オブジェクト指向のファイルシステムパス
    • os.path --- 共通のパス名操作
    • fileinput --- 複数の入力ストリームをまたいだ行の繰り返し処理をサポートする
    • stat --- stat() の結果を解釈する
    • filecmp --- ファイルおよびディレクトリの比較
    • tempfile --- 一時ファイルやディレクトリの作成
    • glob --- Unix 形式のパス名のパターン展開
    • fnmatch --- Unix ファイル名のパターンマッチ
    • linecache --- テキストラインにランダムアクセスする
    • shutil --- 高水準のファイル操作
    • macpath --- Mac OS 9 のパス操作関数
  • データの永続化
    • pickle --- Python オブジェクトの直列化
    • copyreg --- pickle サポート関数を登録する
    • shelve --- Python オブジェクトの永続化
    • marshal --- 内部使用向けの Python オブジェクト整列化
    • dbm --- Unix "データベース" へのインタフェース
    • sqlite3 --- SQLite データベースに対する DB-API 2.0 インタフェース
  • データ圧縮とアーカイブ
    • zlib --- gzip 互換の圧縮
    • gzip --- gzip ファイルのサポート
    • bz2 --- bzip2 圧縮のサポート
    • lzma --- LZMA アルゴリズムを使用した圧縮
    • zipfile --- ZIP アーカイブの処理
    • tarfile --- tar アーカイブファイルの読み書き
  • ファイルフォーマット
    • csv --- CSV ファイルの読み書き
    • configparser --- 設定ファイルのパーサー
    • netrc --- netrc ファイルの処理
    • xdrlib --- XDR データのエンコードおよびデコード
    • plistlib --- Mac OS X .plist ファイルの生成と解析
  • 暗号関連のサービス
    • hashlib --- セキュアハッシュおよびメッセージダイジェスト
    • hmac --- メッセージ認証のための鍵付きハッシュ化
    • secrets --- 機密を扱うために安全な乱数を生成する
  • 汎用オペレーティングシステムサービス
    • os --- 雑多なオペレーティングシステムインタフェース
    • io --- ストリームを扱うコアツール
    • time --- 時刻データへのアクセスと変換
    • argparse --- コマンドラインオプション、引数、サブコマンドのパーサー
    • getopt --- C 言語スタイルのコマンドラインオプションパーサ
    • logging --- Python 用ロギング機能
    • logging.config --- ロギングの環境設定
    • logging.handlers --- ロギングハンドラ
    • getpass --- 可搬性のあるパスワード入力機構
    • curses --- 文字セル表示を扱うための端末操作
    • curses.textpad --- curses プログラムのためのテキスト入力ウィジェット
    • curses.ascii --- ASCII 文字に関するユーティリティ
    • curses.panel --- curses のためのパネルスタック拡張
    • platform --- 実行中プラットフォームの固有情報を参照する
    • errno --- 標準の errno システムシンボル
    • ctypes --- Pythonのための外部関数ライブラリ
  • 並行実行
    • threading --- スレッドベースの並列処理
    • multiprocessing --- プロセスベースの並列処理
    • concurrent パッケージ
    • concurrent.futures -- 並列タスク実行
    • subprocess --- サブプロセス管理
    • sched --- イベントスケジューラ
    • queue --- 同期キュークラス
    • _thread --- 低水準の スレッド API
    • _dummy_thread --- _thread の代替モジュール
    • dummy_threading --- threading の代替モジュール
  • contextvars --- コンテキスト変数
    • コンテキスト変数
    • Manual Context Management
    • asyncio support
  • Networking and Interprocess Communication
    • asyncio --- Asynchronous I/O
    • socket --- 低水準ネットワークインターフェイス
    • ssl --- ソケットオブジェクトに対する TLS/SSL ラッパー
    • select --- I/O 処理の完了を待機する
    • selectors --- 高水準の I/O 多重化
    • asyncore --- 非同期ソケットハンドラ
    • asynchat --- 非同期ソケットコマンド/レスポンスハンドラ
    • signal --- 非同期イベントにハンドラを設定する
    • mmap --- メモリマップファイル
  • インターネット上のデータの操作
    • email --- 電子メールと MIME 処理のためのパッケージ
    • json --- JSON エンコーダおよびデコーダ
    • mailcap --- mailcap ファイルの操作
    • mailbox --- 様々な形式のメールボックス操作
    • mimetypes --- ファイル名を MIME 型へマップする
    • base64 --- Base16, Base32, Base64, Base85 データの符号化
    • binhex --- binhex4 形式ファイルのエンコードおよびデコード
    • binascii --- バイナリデータと ASCII データとの間での変換
    • quopri --- MIME quoted-printable 形式データのエンコードおよびデコード
    • uu --- uuencode形式のエンコードとデコード
  • 構造化マークアップツール
    • html --- HyperText Markup Language のサポート
    • html.parser--- HTML および XHTML のシンプルなパーサー
    • html.entities --- HTML 一般実体の定義
    • XMLを扱うモジュール群
    • xml.etree.ElementTree --- ElementTree XML API
    • xml.dom --- 文書オブジェクトモデル (DOM) API
    • xml.dom.minidom --- 最小限の DOM の実装
    • xml.dom.pulldom --- 部分的な DOM ツリー構築のサポート
    • xml.sax --- SAX2 パーサのサポート
    • xml.sax.handler --- SAX ハンドラの基底クラス
    • xml.sax.saxutils --- SAX ユーティリティ
    • xml.sax.xmlreader --- XML パーサのインタフェース
    • xml.parsers.expat --- Expat を使った高速な XML 解析
  • インターネットプロトコルとサポート
    • webbrowser --- 便利なウェブブラウザコントローラー
    • cgi --- CGI (ゲートウェイインタフェース規格) のサポート
    • cgitb --- CGI スクリプトのトレースバック管理機構
    • wsgiref --- WSGI ユーティリティとリファレンス実装
    • urllib --- URL を扱うモジュール群
    • urllib.request --- URL を開くための拡張可能なライブラリ
    • urllib.response --- urllib で使用するレスポンスクラス
    • urllib.parse --- URL を解析して構成要素にする
    • urllib.error --- urllib.request が投げる例外
    • urllib.robotparser --- robots.txt のためのパーザ
    • http --- HTTP モジュール群
    • http.client --- HTTP プロトコルクライアント
    • ftplib --- FTPプロトコルクライアント
    • poplib --- POP3 プロトコルクライアント
    • imaplib --- IMAP4 プロトコルクライアント
    • nntplib --- NNTP プロトコルクライアント
    • smtplib --- SMTP プロトコルクライアント
    • smtpd --- SMTP サーバー
    • telnetlib --- Telnet クライアント
    • uuid --- UUID objects according to RFC 4122
    • socketserver --- ネットワークサーバのフレームワーク
    • http.server --- HTTP サーバ
    • http.cookies --- HTTPの状態管理
    • http.cookiejar --- HTTP クライアント用の Cookie 処理
    • xmlrpc --- XMLRPC サーバーとクライアントモジュール
    • xmlrpc.client --- XML-RPC クライアントアクセス
    • xmlrpc.server --- 基本的なXML-RPCサーバー
    • ipaddress --- IPv4/IPv6 操作ライブラリ
  • マルチメディアサービス
    • audioop --- 生の音声データを操作する
    • aifc --- AIFFおよびAIFCファイルの読み書き
    • sunau --- Sun AUファイルの読み書き
    • wave --- WAVファイルの読み書き
    • chunk --- IFFチャンクデータの読み込み
    • colorsys --- 色体系間の変換
    • imghdr --- 画像の形式を決定する
    • sndhdr --- サウンドファイルの識別
    • ossaudiodev --- OSS互換オーディオデバイスへのアクセス
  • 国際化
    • gettext --- 多言語対応に関する国際化サービス
    • locale --- 国際化サービス
  • プログラムのフレームワーク
    • turtle --- タートルグラフィックス
    • cmd --- 行指向のコマンドインタープリタのサポート
    • shlex --- 単純な字句解析
  • Tk を用いたグラフィカルユーザインターフェイス
    • tkinter --- Tcl/Tk の Python インタフェース
    • tkinter.ttk --- Tk のテーマ付きウィジェット
    • tkinter.tix --- Tkの拡張ウィジェット
    • tkinter.scrolledtext --- スクロールするテキストウィジェット
    • IDLE
    • 他のグラフィカルユーザインタフェースパッケージ
  • 開発ツール
    • typing --- 型ヒントのサポート
    • pydoc --- ドキュメント生成とオンラインヘルプシステム
    • doctest --- 対話的な実行例をテストする
    • unittest --- ユニットテストフレームワーク
    • unittest.mock --- モックオブジェクトライブラリ
    • unittest.mock --- 入門
    • 2to3 - Python 2 から 3 への自動コード変換
    • test --- Python 用回帰テストパッケージ
    • test.support --- テストのためのユーティリティ関数
    • test.support.script_helper --- Utilities for the Python execution tests
  • デバッグとプロファイル
    • bdb --- デバッガーフレームワーク
    • faulthandler --- Python tracebackのダンプ
    • pdb --- Python デバッガ
    • Python プロファイラ
    • timeit --- 小さなコード断片の実行時間計測
    • trace --- Python 文実行のトレースと追跡
    • tracemalloc --- メモリ割り当ての追跡
  • ソフトウェア・パッケージと配布
    • distutils --- Python モジュールの構築とインストール
    • ensurepip --- pip インストーラのブートストラップ
    • venv --- 仮想環境の作成
    • zipapp --- Manage executable Python zip archives
  • Python ランタイムサービス
    • sys --- システムパラメータと関数
    • sysconfig --- Python の構成情報にアクセスする
    • builtins --- 組み込みオブジェクト
    • __main__ --- トップレベルのスクリプト環境
    • warnings --- 警告の制御
    • dataclasses --- データクラス
    • contextlib --- Utilities for with-statement contexts
    • abc --- 抽象基底クラス
    • atexit --- 終了ハンドラ
    • traceback --- スタックトレースの表示または取得
    • __future__ --- future 文の定義
    • gc --- ガベージコレクタインターフェース
    • inspect --- 活動中のオブジェクトの情報を取得する
    • site --- サイト固有の設定フック
  • カスタム Python インタプリタ
    • code --- インタプリタ基底クラス
    • codeop --- Pythonコードをコンパイルする
  • モジュールのインポート
    • zipimport --- Zip アーカイブからモジュールを import する
    • pkgutil --- パッケージ拡張ユーティリティ
    • modulefinder --- スクリプト中で使われているモジュールを検索する
    • runpy --- Python モジュールの位置特定と実行
    • importlib --- The implementation of import
  • Python言語サービス
    • parser --- Python 解析木にアクセスする
    • ast --- 抽象構文木
    • symtable --- コンパイラの記号表へのアクセス
    • symbol --- Python 解析木と共に使われる定数
    • token --- Python 解析木と共に使われる定数
    • keyword --- Python キーワードチェック
    • tokenize --- Pythonソースのためのトークナイザ
    • tabnanny --- あいまいなインデントの検出
    • pyclbr --- Python クラスブラウザサポート
    • py_compile --- Python ソースファイルのコンパイル
    • compileall --- Python ライブラリをバイトコンパイル
    • dis --- Python バイトコードの逆アセンブラ
    • pickletools --- pickle 開発者のためのツール群
  • 各種サービス
    • formatter --- 汎用の出力書式化機構
  • MS Windows 固有のサービス
    • msilib --- Microsoft インストーラーファイルの読み書き
    • msvcrt --- MS VC++実行時システムの有用なルーチン群
    • winreg --- Windows レジストリへのアクセス
    • winsound --- Windows 用の音声再生インタフェース
  • Unix 固有のサービス
    • posix --- 最も一般的な POSIX システムコール群
    • pwd --- パスワードデータベースへのアクセスを提供する
    • spwd --- シャドウパスワードデータベース
    • grp --- グループデータベースへのアクセス
    • crypt --- Unix パスワードをチェックするための関数
    • termios --- POSIX スタイルの端末制御
    • tty --- 端末制御のための関数群
    • pty --- 擬似端末ユーティリティ
    • fcntl --- fcntl および ioctl システムコール
    • pipes --- シェルパイプラインへのインタフェース
    • resource --- リソース使用状態の情報
    • nis --- Sun の NIS (Yellow Pages) へのインタフェース
    • syslog --- Unix syslog ライブラリルーチン群
  • 取って代わられたモジュール群
    • optparse --- コマンドラインオプション解析器
    • imp --- import 内部へのアクセス
  • ドキュメント化されていないモジュール
    • プラットフォーム固有のモジュール

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


組み込み関数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

組み込み関数

Python インタプリタには数多くの関数と型が組み込まれており、いつでも利用できます。それらをここにアルファベット順に挙げます。

 |  | 組み込み関数 |  |
abs() | delattr() | hash() | memoryview() | set()
all() | dict() | help() | min() | setattr()
any() | dir() | hex() | next() | slice()
ascii() | divmod() | id() | object() | sorted()
bin() | enumerate() | input() | oct() | staticmethod()
bool() | eval() | int() | open() | str()
breakpoint() | exec() | isinstance() | ord() | sum()
bytearray() | filter() | issubclass() | pow() | super()
bytes() | float() | iter() | print() | tuple()
callable() | format() | len() | property() | type()
chr() | frozenset() | list() | range() | vars()
classmethod() | getattr() | locals() | repr() | zip()
compile() | globals() | map() | reversed() | __import__()
complex() | hasattr() | max() | round() |
abs(x)

数の絶対値を返します。引数は整数または浮動小数点数です。引数が複素数なら、その絶対値 (magnitude) が返されます。

all(iterable)

iterable の全ての要素が真ならば (もしくは iterable が空ならば) True を返します。以下のコードと等価です:

def all(iterable):
    for element in iterable:
        if not element:
            return False
    return True
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 の式としても使える形式になります。

>>> 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])

ブール値、即ち True または False のどちらかを返します。x は標準の 真理値判定手続き を用いて変換されます。x が偽または省略されている場合、この関数は False を返します。それ以外の場合、True を返します。bool クラスは int クラスの派生クラスです(数値型 int, float, complex を参照してください)。このクラスからさらに派生することはできません。ブール値のインスタンスは False と True のみです(ブール値 を参照してください)。

バージョン 3.7 で変更: x は位置のみ引数になりました。

breakpoint(*args, **kws)

This function drops you into the debugger at the call site. Specifically, it calls sys.breakpointhook(), passing args and kws straight through. By default, sys.breakpointhook() calls pdb.set_trace() expecting no arguments. In this case, it is purely a convenience function so you don't have to explicitly import pdb or type as much code to enter the debugger. However, sys.breakpointhook() can be set to some other function and breakpoint() will automatically call that, allowing you to drop into the debugger of choice.

バージョン 3.7 で追加.

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[, encoding[, errors]]])

範囲 0 <= x < 256 の整数のイミュータブルなシーケンスである "bytes" オブジェクトを返します。 bytes は bytearray のイミュータブル版です。オブジェクトを変化させないようなメソッドや、インデクシングやスライシングのふるまいは、これと同様のものです。

従って、コンストラクタ引数は bytearray() のものと同様に解釈されます。

バイト列オブジェクトはリテラルでも生成できます。 文字列およびバイト列リテラル を参照してください。

バイナリシーケンス型 --- bytes, bytearray, memoryview, バイトオブジェクト, bytes と bytearray の操作 も参照してください。

callable(object)

object 引数が呼び出し可能オブジェクトであれば True を、そうでなければ False を返します。この関数が真を返しても、呼び出しは失敗する可能性がありますが、偽であれば、 object の呼び出しは決して成功しません。なお、クラスは呼び出し可能 (クラスを呼び出すと新しいインスタンスを返します) です。また、インスタンスはクラスが __call__() メソッドを持つなら呼び出し可能です。

バージョン 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 形式は関数デコレータ (decorator) です。詳しくは 関数定義 の関数定義の説明を参照してください。

このメソッドはクラスで呼び出すこと (例えば C.f()) も、インスタンスとして呼び出すこと (例えば C().f()) もできます。インスタンスはそのクラスが何であるかを除いて無視されます。クラスメソッドが派生クラスに対して呼び出された場合、派生したクラスオブジェクトが暗黙の第一引数として渡されます。

クラスメソッドは C++ や Java の静的メソッドとは異なります。静的メソッドは、この節の staticmethod() を参照してください。

クラスメソッドについて詳しい情報は、 標準型の階層 の標準型階層のドキュメントを参照してください。

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 は、 source のコンパイルにどの future statements を作用させるかを制御します。 どちらも与えられていない (または両方ともゼロ) ならば、 compile() を呼び出している側のコードで有効な future 文とともにコードをコンパイルします。 flags 引数が与えられていて dont_inherit は与えられていない (またはゼロ) 場合は、それに加えて flags に指定された future 文が使われます。 dont_inherit がゼロでない整数の場合、 flags 引数がそのまま使われ、 compile を呼び出している側で有効な future 文は無視されます。

future 文はビットフィールドで指定されます。ビットフィールドはビット単位の OR を取ることで複数の文を指定することができます。特定の機能を指定するために必要なビットフィールドは、__future__ モジュールの _Feature インスタンスにおける compiler_flag 属性で得られます。

引数 optimize は、コンパイラの最適化レベルを指定します; デフォルトの値 -1 は、インタプリタの -O オプションで与えられるのと同じ最適化レベルを選びます。明示的なレベルは、 0 (最適化なし、 __debug__ は真)、 1 (assert は取り除かれ、 __debug__ は偽)、 2 (docstring も取り除かれる) です。

この関数は、コンパイルされたソースが不正である場合 SyntaxError を、ソースがヌルバイトを含む場合 ValueError を送出します。

Python コードをパースしてその AST 表現を得たいのであれば、 ast.parse() を参照してください。

注釈

複数行に渡るコードの文字列を 'single' や 'eval' モードでコンパイルするとき、入力は一つ以上の改行文字で終端されなければなりません。これは、 code モジュールで不完全な文と完全な文を検知しやすくするためです。

警告

AST オブジェクトにコンパイルしているときに、十分に大きい文字列や複雑な文字列によって Python の抽象構文木コンパイラのスタックが深さの限界を越えることで、 Python インタプリタをクラッシュさせられます。

バージョン 3.2 で変更: Windows や Mac の改行も受け付けます。また 'exec' モードでの入力が改行で終わっている必要もありません。optimize 引数が追加されました。

バージョン 3.5 で変更: 以前は source にヌルバイトがあったときに TypeError を送出していました。

class complex([real[, imag]])

値 real + imag*1j の複素数を返すか、文字列や数を複素数に変換します。第一引数が文字列なら、それが複素数と解釈され、この関数は第二引数無しで呼び出されなければなりません。第二引数は文字列であってはなりません。それぞれの引数は (複素数を含む) 任意の数値型です。 imag が省略された場合、標準の値はゼロで、このコンストラクタは int や float のような数値変換としてはたらきます。両方の引数が省略された場合、 0j を返します。

注釈

文字列から変換するとき、その文字列は中央の + や - 演算子の周りに空白を含んではなりません。例えば、complex('1+2j') はいいですが、complex('1 + 2j') は ValueError を送出します。

複素数型については 数値型 int, float, complex に説明があります。

バージョン 3.6 で変更: コードリテラル中で桁をグループ化するのにアンダースコアを利用できます。

delattr(object, name)

setattr() の親戚です。引数はオブジェクトと文字列です。文字列はオブジェクトの属性のうち一つの名前でなければなりません。この関数は、オブジェクトが許すなら、指名された属性を削除します。例えば、 delattr(x, 'foobar') は del x.foobar と等価です。

class dict(**kwarg)
class dict(mapping, **kwarg)
class dict(iterable, **kwarg)

新しい辞書を作成します。 dict オブジェクトは辞書クラスです。このクラスに関するドキュメンテーションは dict と マッピング型 --- dict を参照してください。

他のコンテナについては、 ビルトインの list, set, tuple クラスおよび collections モジュールを参照してください。

dir([object])

引数がない場合、現在のローカルスコープにある名前のリストを返します。引数がある場合、そのオブジェクトの有効な属性のリストを返そうと試みます。

オブジェクトが __dir__() という名のメソッドを持つなら、そのメソッドが呼び出され、属性のリストを返さなければなりません。これにより、カスタムの __getattr__() や __getattribute__() 関数を実装するオブジェクトは、dir() が属性を報告するやり方をカスタマイズできます。

オブジェクトが __dir__() を提供していない場合、定義されていればオブジェクトの __dict__ 属性から、そして型オブジェクトから、情報を収集しようと試みます。結果のリストは完全であるとは限らず、また、カスタムの __getattr__() を持つ場合、不正確になるかもしれません。

デフォルトの dir() メカニズムは、完全というより最重要な情報を作成しようとするため、異なる型のオブジェクトでは異なって振る舞います:

  • オブジェクトがモジュールオブジェクトの場合、リストにはモジュールの属性の名前が含まれます。
  • オブジェクトが型オブジェクトやクラスオブジェクトの場合、リストにはその属性の名前と、再帰的にたどったその基底クラスの属性が含まれます。
  • それ以外の場合には、リストにはオブジェクトの属性名、クラス属性名、再帰的にたどった基底クラスの属性名が含まれます。

返されるリストはアルファベット順に並べられています。例えば:

>>> import struct
>>> dir()   # show the names in the module namespace  # doctest: +SKIP
['__builtins__', '__name__', 'struct']
>>> dir(struct)   # show the names in the struct module # doctest: +SKIP
['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 つの (複素数でない) 数を引数として取り、整数の除法を行ったときの商と剰余からなる対を返します。混合した被演算子型では、二項算術演算子での規則が適用されます。整数では、結果は (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(sequence, start=0):
    n = start
    for elem in sequence:
        yield n, elem
        n += 1
eval(expression, globals=None, locals=None)

文字列とオプションの引数 globals、locals をとります。globals を与える場合は辞書でなくてはなりません。locals を与える場合は任意のマッピングオブジェクトにできます。

expression 引数は Python 式 (技術的な言い方では、条件のリスト) として構文解析され評価されます。 このとき辞書 globals および locals はそれぞれグローバルおよびローカルな名前空間として使われます。 globals 辞書が与えられ、 __builtins__ をキーとする値が含まれていない場合、 expression が構文解析される前に、組み込みモジュール builtins の辞書への参照がキー __builtins__ の値として挿入されます。 よって、 expression は通常、標準の builtins モジュールへの完全なアクセスを有し、制限された環境は伝播します。 locals 辞書が省略された場合、デフォルトは globals 辞書です。 辞書が両方とも省略された場合、表現式は eval() が呼び出されている環境の下で実行されます。 構文エラーは例外として報告されます。例:

>>> x = 1
>>> eval('x+1')
2

この関数は (compile() で生成されるような) 任意のコードオブジェクトを実行するのにも利用できます。この場合、文字列の代わりにコードオブジェクトを渡します。このコードオブジェクトが、引数 mode を 'exec' としてコンパイルされている場合、 eval() が返す値は None になります。

ヒント: exec() 関数により文の動的な実行がサポートされています。globals() および locals() 関数は、それぞれ現在のグローバルおよびローカルな辞書を返すので、それらを eval() や exec() に渡して使うことができます。

リテラルだけを含む式の文字列を安全に評価できる関数、 ast.literal_eval() も参照してください。

exec(object[, globals[, locals]])

この関数は Python コードの動的な実行をサポートします。 object は文字列かコードオブジェクトでなければなりません。文字列なら、その文字列は一連の Python 文として解析され、そして (構文エラーが生じない限り) 実行されます。 [1] コードオブジェクトなら、それは単純に実行されます。どの場合でも、実行されるコードはファイル入力として有効であることが期待されます (リファレンスマニュアルの節 "file-input" を参照)。なお、 return および yield 文は、 exec() 関数に渡されたコードの文脈中においてさえ、関数定義の外では使えません。返り値は None です。

いずれの場合でも、オプションの部分が省略されると、コードは現在のスコープ内で実行されます。globals だけが与えられたなら、辞書でなくてはならず、グローバル変数とローカル変数の両方に使われます。globals と locals が与えられたなら、それぞれグローバル変数とローカル変数として使われます。locals を指定する場合は何らかのマップ型オブジェクトでなければなりません。モジュールレベルでは、グローバルとローカルは同じ辞書です。exec が globals と locals として別のオブジェクトを取った場合、コードはクラス定義に埋め込まれたかのように実行されます。

globals 辞書がキー __builtins__ に対する値を含まなければ、そのキーに対して、組み込みモジュール builtins の辞書への参照が挿入されます。ですから、実行されるコードを exec() に渡す前に、 globals に自作の __builtins__ 辞書を挿入することで、コードがどの組み込みを利用できるか制御できます。

注釈

組み込み関数 globals() および locals() は、それぞれ現在のグローバルおよびローカルの辞書を返すので、それらを exec() の第二、第三引数にそのまま渡して使うと便利なことがあります。

注釈

標準では locals は後に述べる関数 locals() のように動作します: 標準の locals 辞書に対する変更を試みてはいけません。 exec() の呼び出しが返る時にコードが locals に与える影響を知りたいなら、明示的に locals 辞書を渡してください。

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) と同等です。

function が偽を返すような iterable の各要素を返す補完的関数は、 itertools.filterfalse() を参照してください。

class float([x])

数または文字列 x から生成された浮動小数点数を返します。

引数が文字列の場合、10進数を含んだ文字列にしてください。先頭に符号が付いていたり、空白中に埋め込まれていてもかまいません。符号として '+' か '-' を追加できます。'+' は、作られる値に何の影響も与えません。引数は NaN (not-a-number) や正負の無限大を表す文字列でもかまいません。正確には、入力は、前後の空白を取り除いた後に以下の文法に従う必要があります:

sign           ::=  "+" | "-"
infinity       ::=  "Infinity" | "inf"
nan            ::=  "nan"
numeric_value  ::=  floatnumber | infinity | nan
numeric_string ::=  [sign] numeric_value

ここで floatnumber は 浮動小数点数リテラル で記述されている Python の浮動小数点数リテラルです。大文字か小文字かは関係なく、例えば "inf"、 "Inf"、 "INFINITY" 、 "iNfINity" は全て正の無限大として使える綴りです。

一方で、引数が整数または浮動小数点数なら、(Python の浮動小数点数の精度で) 同じ値の浮動小数点数が返されます。引数が Python の浮動小数点数の範囲外なら、 OverflowError が送出されます。

一般の Python オブジェクト x に対して、float(x) は x.__float__() に委譲します。

引数が与えられなければ、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 は位置のみ引数になりました。

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])

新しい frozenset オブジェクトを返します。オプションで iterable から得られた要素を含みます。 frozenset はビルトインクラスです。このクラスに関するドキュメントは frozenset と set（集合）型 --- set, frozenset を参照してください。

他のコンテナについては、ビルトインクラス set, list, tuple, dict や collections モジュールを見てください。

getattr(object, name[, default])

object の指名された属性の値を返します。 name は文字列でなくてはなりません。文字列がオブジェクトの属性の一つの名前であった場合、戻り値はその属性の値になります。例えば、 getattr(x, 'foobar') は x.foobar と等価です。指名された属性が存在しない場合、 default が与えられていればそれが返され、そうでない場合には AttributeError が送出されます。

globals()

現在のグローバルシンボルテーブルを表す辞書を返します。これは常に現在のモジュール (関数やメソッドの中では、それを呼び出したモジュールではなく、それを定義しているモジュール) の辞書です。

hasattr(object, name)

引数はオブジェクトと文字列です。文字列がオブジェクトの属性名の一つであった場合 True を、そうでない場合 False を返します。 (この関数は、 getattr(object, name) を呼び出して AttributeError を送出するかどうかを見ることで実装されています。)

hash(object)

オブジェクトのハッシュ値を (存在すれば) 返します。ハッシュ値は整数です。これらは辞書を検索する際に辞書のキーを高速に比較するために使われます。等しい値となる数値は等しいハッシュ値を持ちます (1 と 1.0 のように型が異なっていてもです)。

注釈

独自の __hash__() メソッドを実装したオブジェクトを使う場合、hash() が実行するマシンのビット幅に合わせて戻り値を切り捨てることに注意してください。詳しくは __hash__() を参照してください。

help([object])

組み込みヘルプシステムを起動します。(この関数は対話的な使用のためのものです。) 引数が与えられていない場合、対話的ヘルプシステムはインタプリタコンソール上で起動します。引数が文字列の場合、文字列はモジュール、関数、クラス、メソッド、キーワード、またはドキュメントの項目名として検索され、ヘルプページがコンソール上に印字されます。引数がその他のオブジェクトの場合、そのオブジェクトに関するヘルプページが生成されます。

この関数は、 site モジュールから、組み込みの名前空間に移されました。

バージョン 3.4 で変更: pydoc と inspect への変更により、呼び出し可能オブジェクトの報告されたシグニチャがより包括的で一貫性のあるものになりました。

hex(x)

Convert an integer number to a lowercase hexadecimal string prefixed with "0x". If x is not a Python int object, it has to define an __index__() method that returns an integer. Some examples:

>>> 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 implementation detail: This is the address of the object in memory.

input([prompt])

引数 prompt が存在すれば、それが末尾の改行を除いて標準出力に書き出されます。次に、この関数は入力から 1 行を読み込み、文字列に変換して (末尾の改行を除いて) 返します。 EOF が読み込まれたとき、 EOFError が送出されます。例:

>>> s = input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"

readline モジュールが読み込まれていれば、 input() はそれを使って精緻な行編集やヒストリ機能を提供します。

class int([x])
class int(x, base=10)

数値または文字列 x から作成された整数オブジェクトを返します。引数が与えられない場合には 0 を返します。 x に __int__() が定義されている場合は、 int(x) は x.__int__() を返します。 x に __trunc__() が定義されている場合は、 `x.__trunc__() を返します。 浮動小数点数については、これは 0 に近い側へ切り捨てます。

x が数値でない、あるいは base が与えられた場合、 x は文字列、 bytes インスタンス、 bytearray インスタンスのいずれかで、基数 base の 整数リテラル で表されたものでなければなりません。 オプションで、リテラルの前に + あるいは - を (中間のスペースなしで) 付けることができます。 また、リテラルは余白で囲むことができます。 基数 n のリテラルは、 0 から n-1 の数字に値 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 のどれかになります。 したがって int('010', 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 は位置のみ引数になりました。

isinstance(object, classinfo)

object 引数が classinfo 引数のインスタンスであるか、 (直接、間接、または 仮想) サブクラスのインスタンスの場合に真を返します。 object が与えられた型のオブジェクトでない場合、この関数は常に偽を返します。 classinfo が型オブジェクトのタプル (あるいは再帰的に複数のタプル) の場合、 object がそれらのいずれかのインスタンスであれば真を返します。 classinfo が型や型からなるタプル、あるいは複数のタプルのいずれでもない場合、 TypeError 例外が送出されます。

issubclass(class, classinfo)

class が classinfo の (直接または間接的な、あるいは virtual) サブクラスである場合に真を返します。クラスはそれ自身のサブクラスとみなされます。 classinfo はクラスオブジェクトからなるタプルでもよく、この場合には classinfo のすべてのエントリが調べられます。その他の場合では、例外 TypeError が送出されます。

iter(object[, sentinel])

イテレータ (iterator) オブジェクトを返します。 第二引数があるかどうかで、第一引数の解釈は大きく異なります。 第二引数がない場合、 object は反復プロトコル (__iter__() メソッド) か、シーケンスプロトコル (引数が 0 から開始する __getitem__() メソッド) をサポートする集合オブジェクトでなければなりません。これらのプロトコルが両方ともサポートされていない場合、 TypeError が送出されます。 第二引数 sentinel が与えられているなら、 object は呼び出し可能オブジェクトでなければなりません。この場合に生成されるイテレータは、 __next__() を呼ぶ毎に object を引数無しで呼び出します。返された値が sentinel と等しければ、 StopIteration が送出され、そうでなければ、戻り値がそのまま返されます。

イテレータ型 も見てください。

One useful application of the second form of iter() is to read lines of a file until a certain line is reached. The following example reads a file until the readline() method returns an empty string:

with open('mydata.txt') as fp:
    for line in iter(fp.readline, ''):
        process_line(line)
len(s)

オブジェクトの長さ (要素の数) を返します。引数はシーケンス (文字列、バイト列、タプル、リスト、range 等) かコレクション (辞書、集合、凍結集合等) です。

class list([iterable])

list は、実際には関数ではなくミュータブルなシーケンス型で、 リスト型 (list) と シーケンス型 --- list, tuple, range にドキュメント化されています。

locals()

現在のローカルシンボルテーブルを表す辞書を更新して返します。関数ブロックで locals() を呼び出した場合自由変数が返されます、クラスブロックでは返されません。

注釈

この辞書の内容は変更してはいけません; 変更しても、インタプリタが使うローカル変数や自由変数の値には影響しません。

map(function, iterable, ...)

function を、結果を返しながら iterable の全ての要素に適用するイテレータを返します。追加の iterable 引数が渡されたなら、 function はその数だけの引数を取らなければならず、全てのイテラブルから並行して取られた要素に適用されます。複数のイテラブルが与えられたら、このイテレータはその中の最短のイテラブルが尽きた時点で止まります。関数の入力がすでに引数タプルに配置されている場合は、 itertools.starmap() を参照してください。

max(iterable, *[, key, default])
max(arg1, arg2, *args[, key])

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 キーワード専用引数。

memoryview(obj)

与えられたオブジェクトから作られた "メモリビュー" オブジェクトを返します。詳しくは メモリビュー を参照してください。

min(iterable, *[, key, default])
min(arg1, arg2, *args[, key])

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 キーワード専用引数。

next(iterator[, default])

iterator の __next__() メソッドを呼び出すことにより、次の要素を取得します。イテレータが尽きている場合、 default が与えられていればそれが返され、そうでなければ StopIteration が送出されます。

class object

特徴を持たない新しいオブジェクトを返します。 object は全てのクラスの基底クラスです。これは、 Python のクラスの全てのインスタンスに共通のメソッド群を持ちます。この関数はいかなる引数も受け付けません。

注釈

object は __dict__ を 持たない ので、 object クラスのインスタンスに任意の属性を代入することはできません。

oct(x)

整数を先頭に "0o" が付いた 8 進文字列に変換します。 結果は Python の式としても使える形式になります。

>>> 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 は:term:path-like object で、開くファイルの (絶対または現在のワーキングディレクトリに対する相対) パス名を与えるものか、または、ラップするファイルの整数のファイルディスクリプタです。(ファイルディスクリプタが与えられた場合は、それは closefd が False に設定されていない限り、返された I/O オブジェクトが閉じられるときに閉じられます。)

mode はオプションの文字列で、ファイルが開かれるモードを指定します。デフォルトは 'r' で、読み込み用にテキストモードで開くという意味です。その他のよく使われる値は、書き込み (ファイルがすでに存在する場合はそのファイルを切り詰めます) 用の 'w'、排他的な生成用の 'x'、追記用の 'a' です (いくつかの Unix システムでは、全て の書き込みが現在のファイルシーク位置に関係なくファイルの末尾に追加されます)。テキストモードでは、encoding が指定されていない場合に使われるエンコーディングはプラットフォームに依存します:locale.getpreferredencoding(False) を使って現在のロケールエンコーディングを取得します。(rawバイト列の読み書きには、バイナリモードを使い、encoding は未指定のままとします) 指定可能なモードは次の表の通りです。

文字 | 意味
'r' | 読み込み用に開く (デフォルト)
'w' | 書き込み用に開き、まずファイルを切り詰める
'x' | 排他的な生成に開き、ファイルが存在する場合は失敗する
'a' | 書き込み用に開き、ファイルが存在する場合は末尾に追記する
'b' | バイナリモード
't' | テキストモード (デフォルト)
'+' ディスクファイルを更新用に開く (読み込み／書き込み)
'U' | universal newlines mode (deprecated)

デフォルトのモードは 'r' (開いてテキストの読み込み、'rt' と同義) です。バイナリの読み書きアクセスについては、モード 'w+b' はファイルを開いて 0 バイトに切り詰めます。'r+b' はファイルを切り詰めずに開きます。

概要 で触れられているように、Python はバイナリとテキストの I/O を区別します。(mode 引数に 'b' を含めて) バイナリモードで開かれたファイルは、内容をいかなるデコーディングもせずに bytes オブジェクトとして返します。(デフォルトや、 mode 引数に 't' が含まれたときの) テキストモードでは、ファイルの内容は str として返され、バイト列はまず、プラットフォーム依存のエンコーディングか、encoding が指定された場合は指定されたエンコーディングを使ってデコードされます。

注釈

Python は、下層のオペレーティングシステムがテキストファイルをどう認識するかには依存しません; すべての処理は Python 自身で行われ、よってプラットフォーム非依存です。

buffering はオプションの整数で、バッファリングの方針を設定するのに使われます。バッファリングを無効にする (バイナリモードでのみ有効) には 0、行単位バッファリング (テキストモードでのみ有効) には 1、固定値のチャンクバッファの大きさをバイト単位で指定するには 1 以上の整数を渡してください。buffering 引数が与えられていないとき、デフォルトのバッファリング方針は以下のように動作します:

  • バイナリファイルは固定サイズのチャンクでバッファリングされます。バッファサイズは、下層のデバイスの「ブロックサイズ」を決定するヒューリスティックを用いて選択され、それが不可能な場合は代わりに io.DEFAULT_BUFFER_SIZE が使われます。多くのシステムでは、典型的なバッファサイズは 4096 か 8192 バイト長になるでしょう。
  • 「対話的な」テキストファイル (isatty() が True を返すファイル) は行バッファリングを使用します。 その他のテキストファイルは、上で説明したバイナリファイル用の方針を使用します。

encoding はファイルのエンコードやデコードに使われる text encoding の名前です。このオプションはテキストモードでのみ使用してください。デフォルトエンコーディングはプラットフォーム依存 (locale.getpreferredencoding() が返すもの) ですが、Pythonでサポートされているエンコーディングはどれでも使えます。詳しくは codecs モジュール内のサポートしているエンコーディングのリストを参照してください。

errors はオプションの文字列で、エンコードやデコードでのエラーをどのように扱うかを指定するものです。バイナリモードでは使用できません。様々な標準のエラーハンドラが使用可能です (エラーハンドラ に列記されています) が、 codecs.register_error() に登録されているエラー処理の名前も使用可能です。標準のエラーハンドラの名前には、以下のようなものがあります:

  • 'strict' はエンコーディングエラーがあると例外 ValueError を発生させます。デフォルト値である None も同じ効果です。
  • 'ignore' はエラーを無視します。エンコーディングエラーを無視することで、データが失われる可能性があることに注意してください。
  • 'replace' は、不正な形式のデータが存在した場所に('?' のような) 置換マーカーを挿入します。
  • 'surrogateescape' は正しくないバイト列を、Unicode の Private Use Area (私用領域) にある U+DC80 から U+DCFF のコードポイントで示します。データを書き込む際に surrogateescape エラーハンドラが使われると、これらの私用コードポイントは元と同じバイト列に変換されます。これはエンコーディングが不明なファイルを処理するのに便利です。
  • 'xmlcharrefreplace' はファイルへの書き込み時のみサポートされます。そのエンコーディングでサポートされない文字は、&#nnn; 形式の適切な XML 文字参照で置換されます。
  • 'backslashreplace' は不正なデータを Python のバックスラッシュ付きのエスケープシーケンスで置換します。
  • 'namereplace' (書き込み時のみサポートされています) はサポートされていない文字を \N{...} エスケープシーケンスで置換します。

newline は universal newlines モードの動作を制御します (テキストモードでのみ動作します)。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 などの、ファイル操作モジュールも参照してください。

バージョン 3.3 で変更:
  • opener 引数を追加しました。
  • 'x' モードを追加しました。
  • 以前は IOError が送出されていました、それは現在 OSError のエイリアスになりました。
  • 既存のファイルを 排他的生成モード('x')で開いた場合、 FileExistsError を送出するようになりました。
バージョン 3.4 で変更:
  • ファイルが継承不可になりました。

Deprecated since version 3.4, will be removed in version 4.0: 'U' モード。

バージョン 3.5 で変更:
  • システムコールが中断されシグナルハンドラが例外を送出しなかった場合、この関数は InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。
  • 'namereplace' エラーハンドラが追加されました。
バージョン 3.6 で変更:
  • os.PathLike を実装したオブジェクトを受け入れるようになりました。
  • Windowsでは、コンソールバッファのオープンは、io.FileIO`ではなく、:class:`io.RawIOBase のサブクラスを返すでしょう。
ord(c)

1 文字の Unicode 文字を表す文字列に対し、その文字の Unicode コードポイントを表す整数を返します。例えば、 ord('a') は整数 97 を返し、 ord('€') (ユーロ記号) は 8364 を返します。これは chr() の逆です。

pow(x, y[, z])

x の y 乗を返します; z があれば、x の y 乗に対する z の剰余を返します (pow(x, y) % z より効率よく計算されます)。二引数の形式 pow(x, y) は、冪乗演算子を使った x**y と等価です。

引数は数値型でなくてはなりません。型混合の場合、二項算術演算における型強制規則が適用されます。 int 被演算子に対しては、第二引数が負でない限り、結果は (型強制後の) 被演算子と同じ型になります; 負の場合、全ての引数は浮動小数点に変換され、浮動小数点の結果が返されます。例えば、 10**2 は 100 を返しますが、 10**-2 は 0.01 を返します。第二引数が負の場合、第三引数は省略しなければなりません。 z がある場合、 x および y は整数型でなければならず、 y は非負でなくてはなりません。

print(*objects, sep=' ', end='\n', file=sys.stdout, 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() をデコレータ (decorator) として使えば、読み出し専用 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." に設定します。

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 で変更: 属性オブジェクトのドックストリングが書き込み可能になりました。

range(stop)
range(start, stop[, step])

range は、実際には関数ではなくイミュータブルなシーケンス型で、 range と シーケンス型 --- list, tuple, range にドキュメント化されています。

repr(object)

オブジェクトの印字可能な表現を含む文字列を返します。この関数は多くの型について、 eval() に渡されたときと同じ値を持つようなオブジェクトを表す文字列を生成しようとします。そうでない場合は、山括弧に囲まれたオブジェクトの型の名前と追加の情報 (大抵の場合はオブジェクトの名前とアドレスを含みます) を返します。クラスは、 __repr__() メソッドを定義することで、この関数によりそのクラスのインスタンスが返すものを制御することができます。

reversed(seq)

要素を逆順に取り出すイテレータ (reverse iterator) を返します。 seq は __reversed__() メソッドを持つか、シーケンス型プロトコル (__len__() メソッド、および、 0 以上の整数を引数とする __getitem__() メソッド) をサポートするオブジェクトでなければなりません。

round(number[, ndigits])

number の小数部を ndigists 桁に丸めた値を返します。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([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 と等価です。

class slice(stop)
class slice(start, stop[, step])

range(start, stop, step) で指定されるインデクスの集合を表す、スライス (slice) オブジェクトを返します。引数 start および step はデフォルトでは None です。スライスオブジェクトは読み出し専用の属性 start、stop および step を持ち、これらは単に引数で使われた 値 (またはデフォルト値) を返します。これらの値には、その他のはっきりと した機能はありません。しかしながら、これらの値は Numerical Python および、その他のサードパーティによる拡張で利用されています。スライスオブジェクトは拡張されたインデクス指定構文が使われる際にも生成されます。例えば a[start:stop:step] や a[start:stop, i] です。この関数の代替となるイテレータを返す関数、itertools.islice() も参照してください。

sorted(iterable, *, key=None, reverse=False)

iterable の要素を並べ替えた新たなリストを返します。

2 つのオプション引数があり、これらはキーワード引数として指定されなければなりません。

key には 1 引数関数を指定します。これは iterable の各要素から比較キーを展開するのに使われます (例えば、 key=str.lower のように指定します)。 デフォルト値は None です (要素を直接比較します)。

reverse は真偽値です。 True がセットされた場合、リストの要素は個々の比較が反転したものとして並び替えられます。

旧式の cmp 関数を key 関数に変換するには functools.cmp_to_key() を使用してください。

組み込みの sort() 関数は安定なことが保証されています。同等な要素の相対順序を変更しないことが保証されていれば、ソートは安定です。これは複数のパスでソートを行なうのに役立ちます（例えば部署でソートしてから給与の等級でソートする場合）。

ソートの例と簡単なチュートリアルは ソート HOW TO を参照して下さい。

@staticmethod

メソッドを静的メソッドへ変換します。

静的メソッドは暗黙の第一引数を受け取りません。静的メソッドを宣言するには、このイディオムを使ってください:

class C:
    @staticmethod
    def f(arg1, arg2, ...): ...

@staticmethod は関数デコレータ (decorator) 形式です。詳しくは 関数定義 の関数定義の説明を参照してください。

このメソッドはクラスで呼び出すこと (例えば C.f() ) も、インスタンスとして呼び出すこと (例えば C().f()) もできます。インスタンスはそのクラスが何であるかを除いて無視されます。

Python における静的メソッドは Java や C++ における静的メソッドと類似しています。クラスコンストラクタの代替を生成するのに役立つ変種、 classmethod() も参照してください。

あらゆるデコレータと同じく、 staticmethod は普通の関数のように呼べ、その返り値で処理が行えます。 この機能は、クラス本体から関数を参照する必要があり、かつ、インスタンスメソッドに自動変換されるのを避けたいケースで必要になります。 そのようなケースでは、このイディオムが使えます:

class C:
    builtin_open = staticmethod(open)

静的メソッドについて詳しくは、 標準型の階層 の標準型階層についてのドキュメントを繙いてください。

class str(object='')
class str(object=b'', encoding='utf-8', errors='strict')

object の str 版を返します。詳細は str() を参照してください。

str は組み込みの文字列 クラス です。文字列に関する一般的な情報は、テキストシーケンス型 --- str を参照してください。

sum(iterable[, start])

start と iterable の要素を左から右へ合計し、総和を返します。 start はデフォルトで 0 です。 iterable の要素は通常は数値で、start の値は文字列であってはなりません。

使う場面によっては、 sum() よりもいい選択肢があります。文字列からなるシーケンスを結合する高速かつ望ましい方法は ''.join(sequence) を呼ぶことです。浮動小数点数値を拡張された精度で加算するには、 math.fsum() を参照してください。一連のイテラブルを連結するには、 itertools.chain() の使用を考えてください。

super([type[, object-or-type]])

メソッドの呼び出しを type の親または兄弟クラスに委譲するプロキシオブジェクトを返します。これはクラスの中でオーバーライドされた継承メソッドにアクセスするのに便利です。探索の順序は、 type 自身が飛ばされるのをのぞいて getattr() で使われるのと同じです。

type の __mro__ 属性は、 getattr() と super() の 両方で使われる、メソッド解決の探索順序を列記します。 この属性は動的で、継承の階層構造が更新されれば、随時変化します。

第 2 引数が省かれたなら、返されるスーパーオブジェクトは束縛されません。第 2 引数がオブジェクトであれば、 isinstance(obj, type) は真でなければなりません。第 2 引数が型であれば、 issubclass(type2, type) は真でなければなりません (これはクラスメソッドに役に立つでしょう)。

super の典型的な用途は 2 つあります。第一に、単継承のクラス階層構造で super は名前を明示することなく親クラスを参照するのに使え、それゆえコードをメンテナンスしやすくなります。この用途は他のプログラミング言語で見られる super の用途によく似ています。

2 つ目の用途は、動的な実行環境下で協調的な多重継承をサポートすることです。この用途は Python に特有で、静的にコンパイルされる言語や、単継承のみをサポートする言語では見られないものです。この機能により、複数の基底クラスが同じメソッドを実装する "diamond diagram" を実装できます。このメソッドをあらゆる場合に同じ形式で呼び出せるようにするのが、良い設計です (理由は、呼び出しの順序が実行時に決定されること、呼び出しの順序がクラス階層の変更に対応すること、呼び出しの順序に実行時まで未知の兄弟クラスが含まれる場合があることです)。

両方の用途において、典型的なスーパークラスの呼び出しは次のようになります:

class C(B):
    def method(self, arg):
        super().method(arg)    # This does the same thing as:
                               # super(C, self).method(arg)

なお、super() は super().__getitem__(name) のような明示的なドット表記属性探索の束縛処理の一部として実装されています。これは、 __getattribute__() メソッドを予測可能な順序でクラスを検索するように実装し、協調的な多重継承をサポートすることで実現されています。従って、 super() は文や super()[name] のような演算子を使った暗黙の探索向けには定義されていません。

また、 super() の使用は引数無しの形式を除きメソッド内部に限定されないことにも注目して下さい。2引数の形式は、必要な要素を正確に指定するので、適当な参照を作ることができます。クラス定義中における引数無しの形式は、定義されているクラスを取り出すのに必要な詳細を、通常の方法で現在のインスタンスにアクセスするようにコンパイラが埋めるのではたらきます。

super() を用いて協調的なクラスを設計する方法の実践的な提案は、 guide to using super() を参照してください。

tuple([iterable])

tuple は、実際は関数ではなくイミュータブルなシーケンス型で、タプル型 (tuple) と シーケンス型 --- list, tuple, range にドキュメント化されています。

class type(object)
class type(name, bases, dict)

引数が1つだけの場合、object の型を返します。返り値は型オブジェクトで、一般に object.__class__ によって返されるのと同じオブジェクトです。

オブジェクトの型の判定には、 isinstance() 組み込み関数を使うことが推奨されます。これはサブクラスを考慮するからです。

引数が 3 つの場合、新しい型オブジェクトを返します。本質的には class 文の動的な形式です。 name 文字列はクラス名で、 __name__ 属性になります。 bases タプルは基底クラスの羅列で、 __bases__ 属性になります。 dict 辞書はクラス本体の定義を含む名前空間で、標準の辞書にコピーされて __dict__ 属性になります。たとえば、以下の二つの文は同じ type オブジェクトを作ります:

>>> class X:
...     a = 1
...
>>> X = type('X', (object,), dict(a=1))

型オブジェクト も参照してください。

バージョン 3.6 で変更: type.__new__ をオーバーライドしていない:class:type のサブクラスは、オブジェクトの型を得るのに１引数形式を利用することができません。

vars([object])

モジュール、クラス、インスタンス、あるいはそれ以外の __dict__ 属性を持つオブジェクトの、 __dict__ 属性を返します。

モジュールやインスタンスのようなオブジェクトは、更新可能な __dict__ 属性を持っています。ただし、それ以外のオブジェクトでは __dict__ 属性への書き込みが制限されている場合があります。書き込みに制限がある例としては、辞書を直接更新されることを防ぐために types.MappingProxyType を使っているクラスがあります。

引数がなければ、vars() は locals() のように振る舞います。ただし、辞書 locals への更新は無視されるため、辞書 locals は読み出し時のみ有用であることに注意してください。

zip(*iterables)

それぞれのイテラブルから要素を集めたイテレータを作ります。

この関数はタプルのイテレータを返し、その i 番目のタプルは引数シーケンスまたはイテラブルそれぞれの i 番目の要素を含みます。このイテレータは、入力イテラブルの中で最短のものが尽きたときに止まります。単一のイテラブル引数が与えられたときは、1 要素のタプルからなるイテレータを返します。引数がなければ、空のイテレータを返します。次と等価です:

def zip(*iterables):
    # zip('ABCD', 'xy') --> Ax By
    sentinel = object()
    iterators = [iter(it) for it in iterables]
    while iterators:
        result = []
        for it in iterators:
            elem = next(it, sentinel)
            if elem is sentinel:
                return
            result.append(elem)
        yield tuple(result)

イテラブルの左から右への評価順序は保証されています。そのため zip(*[iter(s)]*n) を使ってデータ系列を長さ n のグループにクラスタリングするイディオムが使えます。これは、各出力タプルがイテレータを n 回呼び出した結果となるよう、 同じ イテレータを n 回繰り返します。これは入力を長さ n のチャンクに分割する効果があります。

zip() は、長い方のイテラブルの終端にある対にならない値を考慮したい場合は、等しくない長さの入力に対して使うべきではありません。そのような値が重要な場合、代わりに itertools.zip_longest() を使ってください。

zip() に続けて * 演算子を使うと、zip したリストを元に戻せます:

>>> x = [1, 2, 3]
>>> y = [4, 5, 6]
>>> zipped = zip(x, y)
>>> list(zipped)
[(1, 4), (2, 5), (3, 6)]
>>> x2, y2 = zip(*zip(x, y))
>>> x == list(x2) and y == list(y2)
True
__import__(name, globals=None, locals=None, fromlist=(), level=0)

注釈

これは importlib.import_module() とは違い、日常の Python プログラミングでは必要ない高等な関数です。

This function is invoked by the import statement. It can be replaced (by importing the builtins module and assigning to builtins.__import__) in order to change semantics of the import statement, but doing so is strongly discouraged as it is usually simpler to use import hooks (see PEP 302) to attain the same goals and does not cause issues with code which assumes the default import implementation is in use. Direct use of __import__() is also discouraged in favor of importlib.import_module().

この関数は、モジュール name をインポートし、 globals と locals が与えられれば、パッケージのコンテキストで名前をどう解釈するか決定するのに使います。 fromlist は name で与えられるモジュールからインポートされるべきオブジェクトまたはサブモジュールの名前を与ます。標準の実装では locals 引数はまったく使われず、 globals は import 文のパッケージコンテキストを決定するためにのみ使われます。

level は絶対と相対どちらのインポートを使うかを指定します。 0 (デフォルト) は絶対インポートのみ実行します。正の level の値は、 __import__() を呼び出したディレクトリから検索対象となる親ディレクトリの数を示します (詳細は PEP 328 を参照してください)。

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 に変更されます)。

脚注

[1] なお、パーサは Unix スタイルの行末の記法しか受け付けません。コードをファイルから読んでいるなら、必ず、改行変換モードで Windows や Mac スタイルの改行を変換してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python 標準ライブラリ »


組み込み定数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

組み込み定数

組み込み名前空間にはいくつかの定数があります。定数の一覧:

False

bool 型の偽値です。False への代入は不正で、SyntaxError を送出します。

True

bool 型の真値です。True への代入は不正で、SyntaxError を送出します。

None

型 NoneType の唯一の値です。 None は、関数にデフォルト引数が渡されなかったときなどに、値の非存在を表すのに頻繁に用いられます。 None への代入は不正で、SyntaxError を送出します。

NotImplemented

特殊な二項演算のメソッド (e.g. __eq__(), __lt__(), __add__(), __rsub__(), etc.) が、他の型に対して演算が実装されていないことを示すために返す特殊値です。インプレースの特殊な二項演算のメソッド (e.g. __imul__(), __iand__(), etc.) も同じ理由でこの値を返すことがあります。真偽値は真です。

注釈

二項演算の (あるいはインプレースの) メソッドが NotImplemented を返した場合、インタープリタはもう一方の型で定義された対の演算で代用を試みます (あるいは演算によっては他の代替手段も試みます)。試行された演算全てが NotImplemented を返した場合、インタープリタは適切な例外を送出します。 NotImplemented を正しく返さないと、誤解を招きかねないエラーメッセージになったり、 NotImplemented が Python コードに返されるようなことになります。

例として 算術演算の実装 を参照してください。

注釈

NotImplementedError と NotImplemented は、似たような名前と目的を持っていますが、相互に変換できません。 利用する際には、 NotImplementedError を参照してください。

Ellipsis

The same as the ellipsis literal "...". Special value used mostly in conjunction with extended slicing syntax for user-defined container data types.

__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

Objects that when printed or called, print the text of copyright or credits, respectively.

license

Object that when printed, prints the message "Type license() to see the full license text", and when called, displays the full license text in a pager-like fashion (one screen at a time).

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


組み込み型

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

組み込み型

以下のセクションでは、インタプリタに組み込まれている標準型について記述します。

主要な組み込み型は、数値、シーケンス、マッピング、クラス、インスタンス、および例外です。

コレクションクラスには、ミュータブルなものがあります。コレクションのメンバをインプレースに足し、引き、または並べ替えて、特定の要素を返さないメソッドは、コレクション自身ではなく None を返します。

演算には、複数の型でサポートされているものがあります; 特に、ほぼ全てのオブジェクトは、比較でき、真理値を判定でき、 (repr() 関数や、わずかに異なる str() 関数によって) 文字列に変換できます。オブジェクトが print() 関数で印字されるとき、文字列に変換する関数が暗黙に使われます。

真理値判定

どのようなオブジェクトでも真理値として判定でき、 if や while の条件あるいは以下のブール演算の被演算子として使えます。

オブジェクトは、デフォルトでは真と判定されます。ただしそのクラスが __bool__() メソッドを定義していて、それが False を返す場合、または __len__() メソッドを定義していて、それが 0 を返す場合は偽と判定されます。 [1] 主な組み込みオブジェクトで偽と判定されるものを次に示します:

  • 偽であると定義されている定数: None と False
  • 数値型におけるゼロ: 0, 0.0, 0j, Decimal(0), Fraction(0, 1)
  • 空のシーケンスまたはコレクション: '', (), [], {}, set(), range(0)

ブール値の結果を返す演算および組み込み関数は、特に注釈のない限り常に偽値として 0 または False を返し、真値として 1 または True を返します。 (重要な例外: ブール演算 or および and は常に被演算子のうちの一つを返します。)

Boolean Operations --- and, or, not

以下にブール演算を、優先順位が低い順に示します:

演算 | 結果 | 注釈
x or y | x が偽なら y, そうでなければ x | (1)
x and y | x が偽なら x, そうでなければ y | (2)
not x | x が偽なら True, そうでなければ False | (3)

注釈:

  1. この演算子は短絡評価されます。つまり第一引数が偽のときにのみ、第二引数が評価されます。
  2. この演算子は短絡評価されます。つまり第一引数が真のときにのみ、第二引数が評価されます。
  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 | 同一のオブジェクトでない

異なる型のオブジェクトは、異なる数値型を除き、決して等価になりません。さらに、型には、 (例えば関数オブジェクトのように) その型のどの 2 つのオブジェクトも等しくないという、退化した比較の概念しかサポートしていないものもあります。複素数とその他の組み込み数値型を比較するときや、オブジェクト同士が異なる型で比較できないときや、その他順序づけが定義されていないとき、演算子 < 、 <= 、 > 、 >= は 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 や、ユーザ定義の精度の浮動小数点数を保持する 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) |
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) |

注釈:

  1. 整数の除算とも呼ばれます。結果の型は整数型とは限りませんが、結果の値は整数です。結果は常に負の無限大の方向に丸められます: 1//2 は 0 、 (-1)//2 は -1 、 1//(-2) は -1 、そして (-1)//(-2) は 0 です。

  2. 複素数型には使えません。適用可能な場合には代わりに abs() で浮動小数点型に変換してください。

  3. 浮動小数点数から整数への変換はC言語と同様の方法で丸め、または切り捨てられます; より明確に定義された変換を行う場合は、 math.floor() と math.ceil() を参照してください。

  4. 浮動小数点数は、文字列 "nan" と "inf" を、オプションの接頭辞 "+" または "-" と共に、非数 (Not a Number (NaN)) や正、負の無限大として受け付けます。

  5. Python は、プログラム言語一般でそうであるように、 pow(0, 0) および 0 ** 0 を 1 と定義します。

  6. 受け付けられる数値リテラルは数字 0 から 9 または等価な Unicode (Nd プロパティを持つコードポイント) を含みます。

    Nd プロパティを持つコードポイントの完全なリストは http://www.unicode.org/Public/10.0.0/ucd/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 のビット反転 |

注釈:

  1. 負値のシフト数は不正であり、 ValueError が送出されます。
  2. n ビットの左シフトは、 pow(2, n) による乗算のオーバーフローチェックをしないものと等価です。
  3. n ビットの右シフトは、 pow(2, n) による除算のオーバーフローチェックをしないものと等価です。
  4. 桁の長い方の値に少なくとも 1 つ余計に符号ビットを付け加えた幅 (計算するビット幅は 1 + max(x.bit_length(), y.bit_length()) かそれ以上) でこれらの計算を行えば、無限個の符号ビットがあるかのように計算したのと同じ結果を得るのに十分です。

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

整数型は numbers.Integral 抽象基底クラス (abstract base class) を実装します。さらに、追加のメソッドをいくつか提供します:

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

バージョン 3.1 で追加.

int.to_bytes(length, byteorder, *, 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 バイトで表されます。整数が与えられた数のバイトで表せなければ、 OverflowError が送出されます。

byteorder 引数は、整数を表すのに使われるバイトオーダーを決定します。 byteorder が "big" なら、最上位のバイトがバイト配列の最初に来ます。 byteorder が "little" なら、最上位のバイトがバイト配列の最後に来ます。ホストシステムにネイティブのバイトオーダーを要求するには、 sys.byteorder をバイトオーダーの値として使ってください。

signed 引数は、整数を表すのに 2 の補数を使うかどうかを決定します。 signed が False で、負の整数が与えられたなら、 OverflowError が送出されます。 signed のデフォルト値は False です。

バージョン 3.2 で追加.

classmethod int.from_bytes(bytes, byteorder, *, 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 引数は、整数を表すのに使われるバイトオーダーを決定します。 byteorder が "big" なら、最上位のバイトがバイト配列の最初に来ます。 byteorder が "little" なら、最上位のバイトがバイト配列の最後に来ます。ホストシステムにネイティブのバイトオーダーを要求するには、 sys.byteorder をバイトオーダーの値として使ってください。

signed 引数は、整数を表すのに 2 の補数を使うかどうかを決定します。

バージョン 3.2 で追加.

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

浮動小数点数型は、 numbers.Real 抽象基底クラス (abstract base class) を実装しています。浮動小数点型はまた、以下の追加のメソッドを持ちます。

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 implementation detail: 現在使われている素数は、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 、 sys.hash_info.nan は、正の無限大、負の無限大、nan を (それぞれ) 表すのに使われます。(すべてのハッシュ可能な nan は同じハッシュ値を持ちます。)
  • 複素 (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 sys.hash_info.nan
    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

イテレータ型

Python はコンテナでの反復処理の概念をサポートしています。この概念は 2 つの別々のメソッドを使って実装されています; これらのメソッドを使ってユーザ定義のクラスで反復を行えるようにできます。後に詳しく述べるシーケンスは、必ず反復処理メソッドをサポートしています。

コンテナオブジェクトに反復処理をサポートさせるためには、以下のメソッドを定義しなければなりません:

container.__iter__()

イテレータオブジェクトを返します。オブジェクトは後述するイテレータプロトコルをサポートする必要があります。もしコンテナが異なる型の反復処理をサポートするなら、それらの反復処理毎に追加のメソッドを提供しても構いません (複数の形式の反復処理を提供するオブジェクトの例として、幅優先探索と深さ優先探索をサポートする木構造が挙げられます)。このメソッドは Python/C API での Python オブジェクトの型構造体の tp_iter スロットに対応します。

イテレータオブジェクト自体は以下の 2 つのメソッドをサポートする必要があります。これらのメソッドは 2 つ合わせて iterator protocol: (イテレータプロトコル) を成します:

iterator.__iter__()

イテレータオブジェクト自体を返します。このメソッドはコンテナとイテレータの両方を for および in 文で使えるようにするために必要です。このメソッドは Python/C API において Python オブジェクトを表す型構造体の tp_iter スロットに対応します。

iterator.__next__()

コンテナの次のアイテムを返します。もしそれ以上アイテムが無ければ 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 が出現する回数 |

同じ型のシーケンスは比較もサポートしています。特に、タプルとリストは対応する要素を比較することで辞書式順序で比較されます。つまり、等しいとされるためには、すべての要素が等しく、両シーケンスの型も長さも等しくなければなりません。(完全な詳細は言語リファレンスの 比較 を参照してください。)

注釈:

  1. in および not in 演算は、一般に単純な包含判定にのみ使われますが、(str, bytes, bytearray のような) 特殊なシーケンスでは部分シーケンス判定にも使われます:

    >>> "gg" in "eggs"
True

  2. 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 エントリ 多次元のリストを作るにはどうしますか？ にあります。

  3. i または j が負の数の場合、インデックスはシーケンスの末端からの相対インデックスになります: len(s) + i または len(s) + j が代わりに使われます。 ただし -0 はやはり 0 であることに注意してください。

  4. s の i から j へのスライスは i <= k < j となるようなインデックス k を持つ要素からなるシーケンスとして定義されます。 i または j が len(s) よりも大きい場合、 len(s) を使います。 i が省略されるか None だった場合、 0 を使います。 j が省略されるか None だった場合、 len(s) を使います。 i が j 以上の場合、スライスは空のシーケンスになります。

  5. 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 が指定されたものとして扱われます。

  6. イミュータブルなシーケンスの結合は、常に新しいオブジェクトを返します。これは、結合の繰り返しでシーケンスを構築する実行時間コストがシーケンスの長さの合計の二次式になることを意味します。実行時間コストを線形にするには、代わりに以下のいずれかにしてください:

    • str オブジェクトを結合するには、リストを構築して最後に str.join() を使うか、 io.StringIO インスタンスに書き込んで完成してから値を取得してください
    • bytes オブジェクトを結合するなら、同様に bytes.join() や io.BytesIO を使うか、 bytearray オブジェクトでインプレースに結合できます。 bytearray オブジェクトはミュータブルで、効率のいい割り当て超過機構を備えています
    • tuple オブジェクトを結合するなら、代わりに list を拡張してください
    • その他の型については、関連するクラスのドキュメントを調べてください

  7. シーケンス型には、 (range のように) 特殊なパターンに従う項目のシーケンスのみをサポートするものがあり、それらはシーケンスの結合や繰り返しをサポートしません。

  8. 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([i]) | s から i 番目の要素を取り出し、また取り除きます | (2)
s.remove(x) | s から s[i] が x が等価となる最初の要素を取り除きます | (3)
s.reverse() | s をインプレースに逆転させます | (4)

注釈:

  1. t は置き換えるスライスと同じ長さでなければいけません。

  2. オプションの引数 i は標準で -1 なので、標準では最後の要素をリストから除去して返します。

  3. remove は s に x が見つからなければ ValueError を送出します。

  4. reverse() メソッドは、大きなシーケンスを反転するときの容量の節約のため、シーケンスをインプレースに変化させます。副作用としてこの演算が行われることをユーザに気づかせるために、これは反転したシーケンスを返しません。

  5. clear() および copy() は、スライシング操作をサポートしないミュータブルなコンテナ (dict や set など) のインタフェースとの一貫性のために含まれています

    バージョン 3.3 で追加: clear() および copy() メソッド。

  6. 値 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() には２つの引数をキーワード引数 (keyword-only arguments) としてのみ渡せます :

key は一引数をとる関数を指定し、リストのそれぞれの要素から比較キーを取り出すのに使います (例えば、 key=str.lower)。それぞれの項目に対応するキーは一度計算され、ソート処理全体に使われます。デフォルトの値 None は、別のキー値を計算せず、リストの値が直接ソートされることを意味します。

2.x 形式の cmp 関数を key 関数に変換するために、functools.cmp_to_key() ユーティリティが利用できます。

reverse は真偽値です。 True がセットされた場合、リストの要素は個々の比較が反転したものとして並び替えられます。

このメソッドは、大きなシーケンスをソートするときの容量の節約のため、シーケンスをインプレースに変化させます。副作用としてこの演算が行われることをユーザに気づかせるために、これはソートしたシーケンスを返しません (新しいリストインスタンスを明示的に要求するには sorted() を使ってください)。

sort() メソッドは安定していることが保証されています。ソートは、等しい要素の相対順序が変更されないことが保証されていれば、安定しています。これは複数パスのソートを行なう (例えば部署でソートして、それから給与の等級でソートする) のに役立ちます。

CPython implementation detail: リストがソートされている間、または変更しようとする試みの影響中、あるいは検査中でさえ、リストは未定義です。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 オブジェクトをそれらが定義する値のシーケンスに基づいて比較するように '==' と '!=' を定義しました。

バージョン 3.3 で追加: 属性 start, stop および step。

参考

  • linspace レシピ には、遅延評価される浮動小数点版の range の実装方法が載っています。

テキストシーケンス型 --- 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.__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 や 文字列メソッド の節を参照してください。フォーマットされた文字列を出力するには、 フォーマット済み文字列リテラル と カスタムの文字列書式化 の節を参照してください。加えて、 テキスト処理サービス の節も参照してください。

文字列メソッド

文字列は 共通の シーケンス演算全てに加え、以下に述べるメソッドを実装します。

文字列は、二形式の文字列書式化をサポートします。一方は柔軟さが高くカスタマイズできます (str.format()、 書式指定文字列の文法 、および カスタムの文字列書式化 を参照してください)。他方は C 言語の printf 形式の書式化に基づいてより狭い範囲と型を扱うもので、正しく扱うのは少し難しいですが、扱える場合ではたいていこちらのほうが高速です (printf 形式の文字列書式化)。

標準ライブラリの テキスト処理サービス 節は、その他テキストに関する様々なユーティリティ (re モジュールによる正規表現サポートなど) を提供するいくつかのモジュールをカバーしています。

str.capitalize()

最初の文字を大文字にし、残りを小文字にした文字列のコピーを返します。

str.casefold()

文字列の casefold されたコピーを返します。casefold された文字列は、大文字小文字に関係ないマッチに使えます。

casefold は、小文字化と似ていますが、より積極的です。これは文字列の大文字小文字の区別をすべて取り去ることを意図しているためです。例えば、ドイツ語の小文字 'ß' は "ss" と同じです。これは既に小文字なので、lower() は 'ß' に何もしませんが、casefold() はこれを "ss" に変換します。

casefold のアルゴリズムは Unicode Standard のセクション 3.13 に記述されています。

バージョン 3.3 で追加.

str.center(width[, fillchar])

width の長さをもつ中央寄せされた文字列を返します。パディングには fillchar で指定された値 (デフォルトでは ASCII スペース) が使われます。 width が len(s) 以下なら元の文字列が返されます。

str.count(sub[, start[, end]])

[start, end] の範囲に、部分文字列 sub が重複せず出現する回数を返します。オプション引数 start および end はスライス表記と同じように解釈されます。

str.encode(encoding="utf-8", errors="strict")

文字列のエンコードされたバージョンをバイト列オブジェクトとして返します。標準のエンコーディングは 'utf-8' です。標準とは異なるエラー処理を行うために errors を与えることができます。標準のエラー処理は 'strict' で、エンコードに関するエラーは UnicodeError を送出します。他に利用できる値は 'ignore', 'replace', 'xmlcharrefreplace', 'backslashreplace' および関数 codecs.register_error() によって登録された名前です。これについてはセクション エラーハンドラ を参照してください。利用可能なエンコーディングの一覧は、セクション 標準エンコーディング を参照してください。

バージョン 3.1 で変更: キーワード引数のサポートが追加されました。

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'

バージョン 3.2 で追加.

str.index(sub[, start[, end]])

find() と同様ですが、部分文字列が見つからなかったとき ValueError を送出します。

str.isalnum()

文字列中の全ての文字が英数字で、かつ 1 文字以上あるなら真を、そうでなければ偽を返します。文字 c は以下のいずれかが True を返せば英数字です: c.isalpha() 、 c.isdecimal() 、 c.isdigit() 、 c.isnumeric() 。

str.isalpha()

文字列中の全ての文字が英字で、かつ 1 文字以上あるなら真を、そうでなければ偽を返します。英字は、Unicode 文字データベースで "Letter" として定義されているもので、すなわち、一般カテゴリプロパティ "Lm"、 "Lt"、 "Lu"、 "Ll"、 "Lo" のいずれかをもつものです。なお、これは Unicode 標準で定義されている "Alphabetic" プロパティとは異なるものです。

str.isascii()

文字列が空であるか、文字列の全ての文字が ASCII である場合に真を、それ以外の場合に偽を返します。 ASCII 文字のコードポイントは U+0000-U+007F の範囲にあります。

バージョン 3.7 で追加.

str.isdecimal()

文字列中の全ての文字が十進数字で、かつ 1 文字以上あるなら真を、そうでなければ偽を返します。十進数字とは十進数を書くのに使われる文字のことで、たとえば U+0660 (ARABIC-INDIC DIGIT ZERO) なども含みます。正式には、Unicode の一般カテゴリ "Nd" に含まれる文字を指します。

str.isdigit()

文字列中の全ての文字が数字で、かつ 1 文字以上あるなら真を、そうでなければ偽を返します。ここでの数字とは、十進数字に加えて、互換上付き数字のような特殊操作を必要とする数字を含みます。また 10 を基数とした表現ができないカローシュティー数字のような体系の文字も含みます。正式には、数字とは、プロパティ値 Numeric_Type=Digit または Numeric_Type=Decimal を持つ文字です。

str.isidentifier()

文字列が、 識別子 (identifier) およびキーワード (keyword) 節の言語定義における有効な識別子であれば真を返します。

def や class のような予約済みの識別子か判定するには、keyword.iskeyword() を使ってください。

str.islower()

文字列中の大小文字の区別のある文字 [4] 全てが小文字で、かつ大小文字の区別のある文字が 1 文字以上あるなら真を、そうでなければ偽を返します。

str.isnumeric()

文字列中の全ての文字が数を表す文字で、かつ 1 文字以上あるなら真を、そうでなければ偽を返します。数を表す文字は、数字と、Unicode の数値プロパティを持つ全ての文字を含みます。たとえば U+2155 (VULGAR FRACTION ONE FIFTH)。正式には、数を表す文字は、プロパティ値 Numeric_Type=Digit、 Numeric_Type=Decimal または Numeric_Type=Numeric を持つものです。

str.isprintable()

文字列中のすべての文字が印字可能であるか、文字列が空であれば真を、そうでなければ偽を返します。非印字可能文字は、 Unicode 文字データベースで "Other" または "Separator" と定義されている文字の、印字可能と見なされる ASCII space (0x20) 以外のものです。(なお、この文脈での印字可能文字は、文字列に repr() が呼び出されるときにエスケープすべきでない文字のことです。これは sys.stdout や sys.stderr に書き込まれる文字列の操作とは関係ありません。)

str.isspace()

文字列が空白文字のみで構成され、かつ 1 文字以上ある場合には真を、そうでなければ偽を返します。空白文字は、Unicode 文字データベースで "Other" または "Separator" と定義されていて、双方向プロパティが "WS"、 "B"、 "S" のいずれかである文字です。

str.istitle()

文字列がタイトルケース文字列であり、かつ 1 文字以上ある場合、例えば大文字は大小文字の区別のない文字の後にのみ続き、小文字は大小文字の区別のある文字の後ろにのみ続く場合には真を返します。そうでない場合は偽を返します。

str.isupper()

文字列中の大小文字の区別のある文字 [4] 全てが大文字で、かつ大小文字の区別のある文字が 1 文字以上あるなら真を、そうでなければ偽を返します。

str.join(iterable)

iterable 中の文字列を結合した文字列を返します。 iterable に bytes オブジェクトのような非文字列の値が存在するなら、 TypeError が送出されます。要素間のセパレータは、このメソッドを提供する文字列です。

str.ljust(width[, fillchar])

長さ width の左揃えした文字列を返します。パディングは指定された fillchar (デフォルトでは ASCII スペース) を使って行われます。 width が len(s) 以下ならば、元の文字列が返されます。

str.lower()

全ての大小文字の区別のある文字 [4] が小文字に変換された、文字列のコピーを返します。

使われる小文字化のアルゴリズムは Unicode Standard のセクション 3.13 に記述されています。

str.lstrip([chars])

文字列の先頭の文字を除去したコピーを返します。引数 chars は除去される文字の集合を指定する文字列です。 chars が省略されるか None の場合、空白文字が除去されます。 chars 文字列は接頭辞ではなく、その値に含まれる文字の組み合わせ全てがはぎ取られます:

>>> '   spacious   '.lstrip()
'spacious   '
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'
static str.maketrans(x[, y[, z]])

この静的メソッドは str.translate() に使える変換テーブルを返します。

引数を 1 つだけ与える場合、それは Unicode 序数 (整数) または文字 (長さ 1 の文字列) を、Unicode 序数、(任意長の) 文字列、または None に対応づける辞書でなければなりません。このとき、文字で指定したキーは序数に変換されます。

引数を 2 つ指定する場合、それらは同じ長さの文字列である必要があり、結果の辞書では、x のそれぞれの文字が y の同じ位置の文字に対応付けられます。第 3 引数を指定する場合、文字列を指定する必要があり、それに含まれる文字が None に対応付けられます。

str.partition(sep)

文字列を sep の最初の出現位置で区切り、 3 要素のタプルを返します。タプルの内容は、区切りの前の部分、区切り文字列そのもの、そして区切りの後ろの部分です。もし区切れなければ、タプルには元の文字列そのものとその後ろに二つの空文字列が入ります。

str.replace(old, new[, count])

文字列をコピーし、現れる部分文字列 old 全てを new に置換して返します。オプション引数 count が与えられている場合、先頭から count 個の old だけを置換します。

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

文字列を改行部分で分解し、各行からなるリストを返します。 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"

正規表現を使うことでアポストロフィに対応できます:

>>> import re
>>> def titlecase(s):
...     return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0)[0].upper() +
...                              mo.group(0)[1:].lower(),
...                   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 になりえます。

使われる大文字化のアルゴリズムは Unicode Standard のセクション 3.13 に記述されています。

str.zfill(width)

長さが width になるよう ASCII '0' で左詰めした文字列のコピーを返します。先頭が符号接頭辞 ('+'/'-') だった場合、 '0' は符号の前ではなく 後 に挿入されます。width が len(s) 以下の場合元の文字列を返します。

例えば:

>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'

printf 形式の文字列書式化

注釈

ここで解説されているフォーマット操作には、(タプルや辞書を正しく表示するのに失敗するなどの) よくある多くの問題を引き起こす、様々な欠陥が出現します。 新しい フォーマット済み文字列リテラル や str.format() インターフェースや テンプレート文字列 が、これらの問題を回避する助けになるでしょう。 これらの代替手段には、それ自身に、トレードオフや、簡潔さ、柔軟さ、拡張性といった利点があります。

文字列オブジェクトには固有の操作: % 演算子 (モジュロ) があります。この演算子は文字列 書式化 または 補間 演算子とも呼ばれます。format % values (format は文字列) とすると、format 中の % 変換指定は values 中のゼロ個またはそれ以上の要素で置換されます。この動作は C 言語における sprintf() に似ています。

format が単一の引数しか要求しない場合、 values はタプルでない単一のオブジェクトでもかまいません。 [5] それ以外の場合、 values はフォーマット文字列中で指定された項目と正確に同じ数の要素からなるタプルか、単一のマップオブジェクトでなければなりません。

一つの変換指定子は 2 またはそれ以上の文字を含み、その構成要素は以下からなりますが、示した順に出現しなければなりません:

  1. 指定子の開始を示す文字 '%' 。
  2. マップキー (オプション)。丸括弧で囲った文字列からなります (例えば (somename)) 。
  3. 変換フラグ (オプション)。一部の変換型の結果に影響します。
  4. 最小のフィールド幅 (オプション)。 '*' (アスタリスク) を指定した場合、実際の文字列幅が values タプルの次の要素から読み出されます。タプルには最小フィールド幅やオプションの精度指定の後に変換したいオブジェクトがくるようにします。
  5. 精度 (オプション)。 '.' (ドット) とその後に続く精度で与えられます。 '*' (アスタリスク) を指定した場合、精度の桁数は values タプルの次の要素から読み出されます。タプルには精度指定の後に変換したい値がくるようにします。
  6. 精度長変換子 (オプション)。
  7. 変換型。

% 演算子の右側の引数が辞書の場合 (またはその他のマップ型の場合), 文字列中のフォーマットには、辞書に挿入されているキーを丸括弧で囲い、文字 '%' の直後にくるようにしたものが含まれていなければ なりません 。マップキーはフォーマット化したい値をマップから選び出します。例えば:

>>> 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)
'%' | 引数を変換せず、返される文字列中では文字 '%' になります。 |

注釈:

  1. 別の形式を指定（訳注: 変換フラグ # を使用）すると 8 進数を表す接頭辞 ('0o') が最初の数字の前に挿入されます。

  2. 別の形式を指定（訳注: 変換フラグ # を使用）すると 16 進数を表す接頭辞 '0x' または '0X' (使用するフォーマット文字が 'x' か 'X' に依存します) が最初の数字の前に挿入されます。

  3. この形式にした場合、変換結果には常に小数点が含まれ、それはその後ろに数字が続かない場合にも適用されます。

    指定精度は小数点の後の桁数を決定し、そのデフォルトは 6 です。

  4. この形式にした場合、変換結果には常に小数点が含まれ他の形式とは違って末尾の 0 は取り除かれません。

    指定精度は小数点の前後の有効桁数を決定し、そのデフォルトは 6 です。

  5. 精度が N なら、出力は N 文字に切り詰められます。

  6. PEP 237 を参照してください。

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()

インスタンス内の 1 バイトにつき 2 つの 16 進数を含む、文字列オブジェクトを返します。

>>> b'\xf0\xf1\xf2'.hex()
'f0f1f2'

バージョン 3.5 で追加.

bytes オブジェクトは (タプルに似た) 整数のシーケンスなので、 bytes オブジェクト b について、 b[0] は整数になり、 b[0:1] は長さ 1 の bytes オブジェクトになります。 (この動作は、文字列に対するインデックス指定もスライスも長さ 1 の文字列を返すのと対照的です。)

bytes オブジェクトの repr 出力はリテラル形式 (b'...') になります。 bytes([46, 46, 46]) などの形式よりも便利な事が多いからです。 bytes オブジェクトはいつでも list(b) で整数のリストに変換できます。

注釈

Python 2.x ユーザーへ: Python 2.x では多くの場面で 8bit 文字列 (2.x が提供しているビルトインのバイナリデータ型) と Unicode 文字列の間の暗黙の変換が許可されていました。これは Python がもともと 8bit 文字列しか持っていなくて、あとから Unicode テキストが追加されたので、後方互換性を維持するためのワークアラウンドでした。 Python 3.x ではこれらの暗黙の変換はなくなりました。 8-bit バイナリデータと Unicode テキストは明確に違うもので、 bytes オブジェクトと文字列オブジェクトを比較すると常に等しくなりません。

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()

インスタンス内の 1 バイトにつき 2 つの 16 進数を含む、文字列オブジェクトを返します。

>>> bytearray(b'\xf0\xf1\xf2').hex()
'f0f1f2'

バージョン 3.5 で追加.

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 の範囲の整数にできます。

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

bytes.decode(encoding="utf-8", errors="strict")
bytearray.decode(encoding="utf-8", errors="strict")

与えられたバイト列からデコードされた文字列を返します。デフォルトのエンコーディングは 'utf-8' です。 errors を与えて異なるエラー処理法を設定できます。 errors のデフォルトは 'strict' で、エンコーディングエラーが UnicodeError を送出します。設定できる他の値は、 'ignore' 、 'replace' 、その他の codecs.register_error() を通して登録された名前で、節 エラーハンドラ を参照してください。可能なエンコーディングのリストは、 標準エンコーディング を参照してください。

注釈

引数 encoding を str に渡すと bytes-like object を直接デコードすることができます。つまり、一時的な bytes や bytearray オブジェクトを作成する必要はありません。

バージョン 3.1 で変更: キーワード引数のサポートが追加されました。

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 でなければなりません。

バージョン 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 の空白文字（訳注: 半角スペース）が除去されます。なお chars 引数と一致する接頭辞が除去されるのではなく、それに含まれるバイトの組み合わせ全てが除去されます:

>>> b'   spacious   '.lstrip()
b'spacious   '
>>> b'www.example.com'.lstrip(b'cmowz.')
b'example.com'

除去対象のバイト値を含むバイナリシーケンスには、任意の bytes-like object を指定できます。

注釈

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 の空白文字（訳注: 半角スペース）が除去されます。なお chars 引数と一致する接尾辞が除去されるのではなく、それに含まれるバイトの組み合わせ全てが除去されます:

>>> b'   spacious   '.rstrip()
b'   spacious'
>>> b'mississippi'.rstrip(b'ipz')
b'mississ'

除去対象のバイト値を含むバイナリシーケンスには、任意の bytes-like object を指定できます。

注釈

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 の空白文字（訳注: 半角スペース）が除去されます。なお 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 である場合に真を、それ以外の場合に偽を返します。 ASCII バイトは 0-0x7F の範囲にあります。

バージョン 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 またはそれ以上の文字を含み、その構成要素は以下からなりますが、示した順に出現しなければなりません:

  1. 指定子の開始を示す文字 '%' 。
  2. マップキー (オプション)。丸括弧で囲った文字列からなります (例えば (somename)) 。
  3. 変換フラグ (オプション)。一部の変換型の結果に影響します。
  4. 最小のフィールド幅 (オプション)。 '*' (アスタリスク) を指定した場合、実際の文字列幅が values タプルの次の要素から読み出されます。タプルには最小フィールド幅やオプションの精度指定の後に変換したいオブジェクトがくるようにします。
  5. 精度 (オプション)。 '.' (ドット) とその後に続く精度で与えられます。 '*' (アスタリスク) を指定した場合、精度の桁数は values タプルの次の要素から読み出されます。タプルには精度指定の後に変換したい値がくるようにします。
  6. 精度長変換子 (オプション)。
  7. 変換型。

% 演算子の右側の引数が辞書の場合 (またはその他のマッピング型の場合) 、 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)
'%' | 引数を変換せず、返される文字列中では文字 '%' になります。 |

注釈:

  1. 別の形式を指定（訳注: 変換フラグ # を使用）すると 8 進数を表す接頭辞 ('0o') が最初の数字の前に挿入されます。

  2. 別の形式を指定（訳注: 変換フラグ # を使用）すると 16 進数を表す接頭辞 '0x' または '0X' (使用するフォーマット文字が 'x' か 'X' に依存します) が最初の数字の前に挿入されます。

  3. この形式にした場合、変換結果には常に小数点が含まれ、それはその後ろに数字が続かない場合にも適用されます。

    指定精度は小数点の後の桁数を決定し、そのデフォルトは 6 です。

  4. この形式にした場合、変換結果には常に小数点が含まれ他の形式とは違って末尾の 0 は取り除かれません。

    指定精度は小数点の前後の有効桁数を決定し、そのデフォルトは 6 です。

  5. 精度が N なら、出力は N 文字に切り詰められます。

  6. b'%s' は非推奨ですが、3.x 系では削除されません。

  7. b'%r' は非推奨ですが、3.x 系では削除されません。

  8. PEP 237 を参照してください。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

参考

PEP 461 - bytes と bytearray への % 書式化の追加

バージョン 3.5 で追加.

メモリビュー

memoryview オブジェクトは、Python コードが バッファプロトコル をサポートするオブジェクトの内部データへ、コピーすることなくアクセスすることを可能にします。

class memoryview(obj)

obj を参照する memoryview を作成します。 obj はバッファプロトコルをサポートしていなければなりません。バッファプロトコルをサポートする組み込みオブジェクトには、 bytes 、 bytearray などがあります。

memoryview は元となるオブジェクト obj が扱うメモリーの最小単位を 要素 として扱います。多くの単純なオブジェクト、例えば bytes や bytearray では、要素は単バイトになりますが、他の array.array 等の型では、要素はより大きくなりえます。

メモリビューの長さ len(view) は、 tolist で得られるリストの長さとなります。view.ndim = 0 なら、長さは 1 です。view.ndim = 1 なら、長さはビューの要素数と等しいです。より高次元では、長さはビューのネストされたリスト表現の長さと等しいです。要素一つあたりのバイト数は 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 エクスポーターは、 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()

バッファ中のデータをバイト文字列として返します。これはメモリビューに対して bytes コンストラクタを呼び出すのと同等です。

>>> m = memoryview(b"abc")
>>> m.tobytes()
b'abc'
>>> bytes(m)
b'abc'

連続でない配列については、結果はすべての要素がバイトに変換されたものを含むフラットなリスト表現に等しくなります。 tobytes() は、 struct モジュール文法にないものを含むすべての書式文字列をサポートします。

hex()

バッファ中の各バイトを 2 つの 16 進数で表した文字列を返します:

>>> m = memoryview(b"abc")
>>> m.hex()
'616263'

バージョン 3.5 で追加.

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 フォーマットと多次元の表現をサポートするようになりました。

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

バージョン 3.2 で追加.

cast(format[, shape])

memoryview を新しいフォーマットか shape にキャストします。 shape はデフォルトで [byte_length//new_itemsize] で、 1次元配列になります。戻り値は memoryview ですが、バッファー自体はコピーされません。サポートされている変換は 1次元配列 -> C言語型の連続配列 と C言語型の連続配列 -> 1次元配列 です（参考: contiguous）。

キャスト後のフォーマットは struct 文法の単一要素ネイティブフォーマットに制限されます。フォーマットのうちの一つはバイトフォーマット ('B', 'b', 'c') でなければなりません。結果のバイト長はオリジナルの長さと同じでなければなりません。

1D/long から 1D/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

1D/unsigned byte から 1D/char へのキャスト:

>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: memoryview: invalid value for format "B"
>>> y = x.cast('c')
>>> y[0] = b'a'
>>> b
bytearray(b'ayz')

1D/byte から 3D/int へ、そして 1D/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

1D/unsigned char から 2D/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]]

バージョン 3.3 で追加.

バージョン 3.5 で変更: 単バイトのビューへキャストする場合、キャスト元のフォーマットについて制約は無くなりました。

読み出し専用の属性もいくつか使えます:

obj

memoryview が参照しているオブジェクト:

>>> b  = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True

バージョン 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

バージョン 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 ）。

バージョン 3.3 で追加.

f_contiguous

メモリーがFortran形式の順序で連続しているかどうかを示す真偽値（参考: contiguous ）。

バージョン 3.3 で追加.

contiguous

メモリーが連続しているかどうかを示す真偽値（参考: contiguous ）。

バージョン 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 が指定されない場合、新しい空の集合が返されます。

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()

s の浅いコピーを新しい集合として返します。

なお、演算子でない版の 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() メソッドの出力は未定義です。

集合の要素は、辞書のキーのように、ハッシュ可能 (hashable) でなければなりません。

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

マッピング (mapping) オブジェクトは、ハッシュ可能 (hashable) な値を任意のオブジェクトに対応付けます。マッピングはミュータブルなオブジェクトです。現在、標準マッピング型は辞書 (dictionary) だけです。 (他のコンテナについては組み込みの list, set, および tuple クラスと、 collections モジュールを参照してください。)

辞書のキーは ほぼ 任意の値です。ハッシュ可能 (hashable) でない値、つまり、リストや辞書その他のミュータブルな型 (オブジェクトの同一性ではなく値で比較されるもの) はキーとして使用できません。キーとして使われる数値型は通常の数値比較のルールに従います: もしふたつの数値が (例えば 1 と 1.0 のように) 等しければ、同じ辞書の項目として互換的に使用できます。 (ただし、コンピュータは浮動小数点数を近似値として保管するので、辞書型のキーとして使用するのはたいてい賢くありません。)

辞書は key: value 対のカンマ区切りのリストを波括弧でくくることで作成できます。例えば: {'jack': 4098, 'sjoerd': 4127} あるいは {4098: 'jack', 4127: 'sjoerd'} 。あるいは、 dict コンストラクタでも作成できます。

class dict(**kwarg)
class dict(mapping, **kwarg)
class dict(iterable, **kwarg)

オプションの位置引数と空の可能性もあるキーワード引数の集合により初期化された新しい辞書を返します。

位置引数が何も与えられなかった場合、空の辞書が作成されます。位置引数が与えられ、それがマッピングオブジェクトだった場合、そのマッピングオブジェクトと同じキーと値のペアを持つ辞書が作成されます。それ以外の場合、位置引数は 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})
>>> a == b == c == d == e
True

最初の例のようにキーワード引数を与える方法では、キーは有効な Python の識別子でなければなりません。それ以外の方法では、辞書のキーとして有効などんなキーでも使えます。

以下は辞書型がサポートする操作です (それゆえ、カスタムのマップ型もこれらの操作をサポートするべきです):

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(seq[, value])

Create a new dictionary with keys from seq and values set to value.

fromkeys() は新しい辞書を返すクラスメソッドです。 value のデフォルト値は None です。

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 対を返していました。

setdefault(key[, default])

もし、 key が辞書に存在すれば、その値を返します。そうでなければ、値を default として key を挿入し、 default を返します。 default のデフォルトは None です。

update([other])

辞書の内容を other のキーと値で更新します。既存のキーは上書きされます。返り値は None です。

update() は、他の辞書オブジェクトでもキー/値の対のイテラブル (タプル、もしくは、長さが2のイテラブル) でも、どちらでも受け付けます。キーワード引数が指定されれば、そのキー/値の対で辞書を更新します: d.update(red=1, blue=2)。

values()

辞書の値の新しいビューを返します。ビューオブジェクトのドキュメント を参照してください。

複数の辞書は、同じ (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 の実装詳細でした。

参考

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 を返します。

キーのビューは、項目が一意的でハッシュ可能であるという点で、集合に似ています。すべての値がハッシュ可能なら、 (key, value) 対も一意的でハッシュ可能なので、要素のビューも集合に似ています。(値のビューは、要素が一般に一意的でないことから、集合に似ているとは考えられません。) 集合に似ているビューに対して、抽象基底クラス 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'}

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

Python の with 文は、コンテキストマネージャによって定義される実行時コンテキストの概念をサポートします。これは、文の本体が実行される前に進入し文の終わりで脱出する実行時コンテキストを、ユーザ定義クラスが定義できるようにする一対のメソッドで実装されます:

contextmanager.__enter__()

Enter the runtime context and return either this object or another object related to the runtime context. The value returned by this method is bound to the identifier in the as clause of with statements using this context manager.

自分自身を返すコンテキストマネージャの例としてファイルオブジェクト (file object) があります。ファイルオブジェクトは __enter__() から自分自身を返し、 open() が with 文のコンテキスト式として使われるようにします。

An example of a context manager that returns a related object is the one returned by decimal.localcontext(). These managers set the active decimal context to a copy of the original decimal context and then return the copy. This allows changes to be made to the current decimal context in the body of the with statement without affecting code outside the with statement.

contextmanager.__exit__(exc_type, exc_val, exc_tb)

実行時コンテキストから抜け、(発生していた場合) 例外を抑制するかどうかを示すブール値フラグを返します。 with 文の本体の実行中に例外が発生した場合、引数にはその例外の型と値とトレースバック情報を渡します。そうでない場合、引数は全て None となります。

Returning a true value from this method will cause the with statement to suppress the exception and continue execution with the statement immediately following the with statement. Otherwise the exception continues propagating after this method has finished executing. Exceptions that occur during execution of this method will replace any exception that occurred in the body of the with statement.

渡された例外を明示的に再送出すべきではありません。その代わりに、このメソッドが偽の値を返すことでメソッドの正常終了と送出された例外を抑制しないことを伝えるべきです。このようにすればコンテキストマネージャは __exit__() メソッド自体が失敗したのかどうかを簡単に見分けることができます。

Python は、易しいスレッド同期、ファイルなどのオブジェクトの即時クローズ、アクティブな小数算術コンテキストの単純な操作をサポートするために、いくつかのコンテキストマネージャを用意しています。各型はコンテキスト管理プロトコルを実装しているという以上の特別の取り扱いを受けるわけではありません。例については contextlib モジュールを参照してください。

Python のジェネレータ (generator) と contextlib.contextmanager デコレータ (decorator) はこのプロトコルの簡便な実装方法を提供します。ジェネレータ関数を contextlib.contextmanager デコレータでデコレートすると、デコレートされないジェネレータ関数が作成するイテレータの代わりに、必要な __enter__() および __exit__() メソッドを実装したコンテキストマネージャを返すようになります。

これらのメソッドのために Python/C API の中の Python オブジェクトの型構造体に特別なスロットが作られたわけではないことに注意してください。これらのメソッドを定義したい拡張型はこれらを通常の Python からアクセスできるメソッドとして提供しなければなりません。実行時コンテキストを準備するオーバーヘッドに比べたら、一回のクラス辞書の探索のオーバーヘッドは無視できます。

その他の組み込み型

インタプリタは、その他いくつかの種類のオブジェクトをサポートしています。これらのほとんどは 1 つまたは 2 つの演算だけをサポートしています。

モジュール (module)

モジュールに対する唯一の特殊な演算は属性アクセス: 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() のような) 組み込みメソッドと、クラスインスタンスのメソッドです。組み込みメソッドは、それをサポートする型と一緒に記述されています。

インスタンスを通してメソッド (クラスの名前空間内で定義された関数) にアクセスすると、特殊なオブジェクトが得られます。それは束縛メソッド (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) の呼び出しと完全に等価です。

関数オブジェクトと同様に、メソッドオブジェクトは任意の属性の取得をサポートしています。しかし、メソッド属性は実際には下層の関数オブジェクト (meth.__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 モジュールも参照してください。

コードオブジェクトは、組み込み関数 exec() や eval() に (ソース文字列の代わりに) 渡すことで、実行や評価できます。

詳細は、 標準型の階層 を参照してください。

型オブジェクト

型オブジェクトは様々なオブジェクト型を表します。オブジェクトの型は組み込み関数 type() でアクセスされます。型オブジェクトには特有の操作はありません。標準モジュール types には全ての組み込み型名が定義されています。

型はこのように書き表されます: <class 'int'> 。

ヌルオブジェクト

このオブジェクトは明示的に値を返さない関数によって返されます。このオブジェクトには特有の操作はありません。ヌルオブジェクトは一つだけで、 None (組み込み名) と名づけられています。 type(None)() は同じシングルトンを作成します。

None と書き表されます。

Ellipsis オブジェクト

このオブジェクトは一般にスライシングによって使われます (スライス表記 (slicing) を参照してください)。特殊な演算は何もサポートしていません。Ellipsis オブジェクトは一つだけで、その名前は Ellipsis (組み込み名) です。type(Ellipsis)() は単一の Ellipsis を作成します。

Ellipsis または ... と書き表されます。

NotImplemented オブジェクト

このオブジェクトは、対応していない型に対して比較演算や二項演算が求められたとき、それらの演算から返されます。詳細は 比較 を参照してください。 NotImplemented オブジェクトは一つだけです。 type(NotImplemented)() はこの単一のインスタンスを作成します。

NotImplemented と書き表されます。

ブール値

ブール値は二つの定数オブジェクト False および True です。これらは真理値を表すのに使われます (ただし他の値も偽や真とみなされます)。 数値処理のコンテキスト (例えば算術演算子の引数として使われた場合) では、これらはそれぞれ 0 および 1 と同様に振舞います。任意の値に対して、真理値と解釈できる場合、組み込み関数 bool() は値をブール値に変換するのに使われます (上述の 真理値判定 の節を参照してください)。

それぞれ False および True と書き表されます。

内部オブジェクト

この情報は 標準型の階層 を参照してください。スタックフレームオブジェクト、トレースバックオブジェクト、スライスオブジェクトについて記述されています。

特殊属性

実装は、いくつかのオブジェクト型に対して、適切な場合には特殊な読み出し専用の属性を追加します。そのうちいくつかは dir() 組込み関数で報告されません。

object.__dict__

オブジェクトの (書き込み可能な) 属性を保存するために使われる辞書またはその他のマッピングオブジェクトです。

instance.__class__

クラスインスタンスが属しているクラスです。

class.__bases__

クラスオブジェクトの基底クラスのタプルです。

definition.__name__

クラス、関数、メソッド、デスクリプタ、ジェネレータインスタンスの名前です。

definition.__qualname__

クラス、関数、メソッド、デスクリプタ、ジェネレータインスタンスの 修飾名 です。

バージョン 3.3 で追加.

class.__mro__

この属性はメソッドの解決時に基底クラスを探索するときに考慮されるクラスのタプルです。

class.mro()

このメソッドは、メタクラスによって、そのインスタンスのメソッド解決の順序をカスタマイズするために、上書きされるかも知れません。このメソッドはクラスのインスタンス化時に呼ばれ、その結果は __mro__ に格納されます。

class.__subclasses__()

それぞれのクラスは、それ自身の直接のサブクラスへの弱参照を保持します。このメソッドはそれらの参照のうち、生存しているもののリストを返します。例:

>>> int.__subclasses__()
[<class 'bool'>]

脚注

[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 »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

組み込み例外

Python において、すべての例外は BaseException から派生したクラスのインスタンスでなければなりません。特定のクラスを言及する except 節を伴う try 文において、その節はそのクラスから派生した例外クラスも処理しますが、そのクラスの派生 元 の例外クラスは処理しません。サブクラス化の関係にない 2 つの例外クラスは、それらが同じ名前だった場合でも等しくなりえません。

以下に挙げる組み込み例外は、インタプリタや組み込み関数によって生成されます。特に注記しないかぎり、これらはエラーの詳しい原因を示す "関連値 (associated value)" を持ちます。この値は、複数の情報 (エラーコードや、そのコードを説明する文字列など) の文字列かタプルです。関連値は通常、例外クラスのコンストラクタに引数として渡されます。

ユーザによるコードも組み込み例外を送出できます。これを使って、例外ハンドラをテストしたり、インタプリタが同じ例外を送出する状況と "ちょうど同じような" エラー条件であることを報告したりできます。しかし、ユーザのコードが適切でないエラーを送出するのを妨げる方法はないので注意してください。

組み込み例外クラスは新たな例外を定義するためにサブクラス化することができます。新しい例外は、Exception クラスかそのサブクラスの一つから派生することをお勧めします。 BaseException からは派生しないで下さい。例外を定義する上での詳しい情報は、 Python チュートリアルの ユーザー定義例外 の項目にあります。

except または finally 節内で例外を送出 (または再送出) するとき、__context__ は自動的に最後に捕まった例外に設定されます。新しい例外が処理されなければ、最終的に表示されるトレースバックは先に起きた例外も最後の例外も含みます。

現在処理中の例外を raise を使って再送出するのではなく新規に例外を送出する場合、raise と一緒に from を使うことで暗黙の例外コンテキストを捕捉することができます:

raise new_exc from original_exc

The expression following from must be an exception or None. It will be set as __cause__ on the raised exception. Setting __cause__ also implicitly sets the __suppress_context__ attribute to True, so that using raise new_exc from None effectively replaces the old exception with the new one for display purposes (e.g. converting KeyError to AttributeError), while leaving the old exception available in __context__ for introspection when debugging.

デフォルトの traceback 表示コードは、例外自体の traceback に加え、これらの連鎖された例外を表示します。__cause__ で明示的に連鎖させた例外は、存在するならば常に表示されます。__context__ で暗黙に連鎖させた例外は、__cause__ が None かつ __suppress_context__ が false の場合にのみ表示されます。

いずれにせよ、連鎖された例外に続いて、その例外自体は常に表示されます。そのため、traceback の最終行には、常に送出された最後の例外が表示されます。

基底クラス

以下の例外は、主に他の例外の基底クラスとして使われます。

exception BaseException

全ての組み込み例外の基底クラスです。ユーザ定義の例外に直接継承されることは意図されていません (継承には Exception を使ってください)。このクラスのインスタンスに str() が呼ばれた場合、インスタンスへの引数の表現か、引数が無い場合には空文字列が返されます。

args

例外コンストラクタに与えられた引数のタプルです。組み込み例外は普通、エラーメッセージを与える一つの文字列だけを引数として呼ばれますが、中には (OSError など) いくつかの引数を必要とし、このタプルの要素に特別な意味を込めるものもあります。

with_traceback(tb)

このメソッドは tb を例外の新しいトレースバックとして設定し、例外オブジェクトを返します。これは通常次のような例外処理コードに使われます:

try:
    ...
except SomeException:
    tb = sys.exc_info()[2]
    raise OtherException(...).with_traceback(tb)
exception Exception

システム終了以外の全ての組み込み例外はこのクラスから派生しています。全てのユーザ定義例外もこのクラスから派生させるべきです。

exception ArithmeticError

算術上の様々なエラーに対して送出される組み込み例外 OverflowError, ZeroDivisionError, FloatingPointError の基底クラスです。

exception BufferError

バッファ に関連する操作が行えなかったときに送出されます。

exception LookupError

マッピングまたはシーケンスで使われたキーやインデクスが無効な場合に送出される例外 IndexError および KeyError の基底クラスです。 codecs.lookup() によって直接送出されることもあります。

具象例外

以下の例外は、通常送出される例外です。

exception AssertionError

assert 文が失敗した場合に送出されます。

exception AttributeError

属性参照 (属性参照 を参照) や代入が失敗した場合に送出されます (オブジェクトが属性の参照や属性の代入をまったくサポートしていない場合には TypeError が送出されます)。

exception EOFError

input() が何もデータを読まずに end-of-file (EOF) に達した場合に送出されます。(注意: io.IOBase.read() と io.IOBase.readline() メソッドは、EOF に達すると空文字列を返します。)

exception FloatingPointError

Not currently used.

exception GeneratorExit

ジェネレータ や コルーチン が閉じられたときに送出されます。 generator.close() と coroutine.close() を参照してください。この例外はエラーではなく技術的なものなので、 Exception ではなく BaseException を直接継承しています。

exception ImportError

import 文でモジュールをロードしようとして問題が発生すると送出されます。 from ... import の中の"from list" (訳注：... の部分)の名前が見つからないときにも送出されます。

コンストラクタのキーワード専用引数を使って name および path 属性を設定できます。設定された場合、インポートを試みられたモジュールの名前と、例外を引き起こしたファイルへのパスとを、それぞれ表します。

バージョン 3.3 で変更: name および path 属性が追加されました。

exception ModuleNotFoundError

ImportError のサブクラスで、import 文でモジュールが見つからない場合に送出されます。また、 sys.modules に None が含まれる場合にも送出されます。

バージョン 3.6 で追加.

exception IndexError

シーケンスの添字が範囲外の場合に送出されます。 (スライスのインデクスはシーケンスの範囲に収まるように暗黙のうちに調整されます; インデクスが整数でない場合、 TypeError が送出されます。)

exception KeyError

マッピング (辞書) のキーが、既存のキーの集合内に見つからなかった場合に送出されます。

exception KeyboardInterrupt

ユーザが割り込みキー (通常は Control-C または Delete) を押した場合に送出されます。実行中、割り込みは定期的に監視されます。Exception を捕捉するコードに誤って捕捉されてインタプリタの終了が阻害されないように、この例外は BaseException を継承しています。

exception MemoryError

ある操作中にメモリが不足したが、その状況は (オブジェクトをいくつか消去することで) まだ復旧可能かもしれない場合に送出されます。この例外の関連値は、メモリ不足になった (内部) 操作の種類を示す文字列です。下層のメモリ管理アーキテクチャ (C の malloc() 関数) のために、インタプリタが現状から完璧に復旧できるとはかぎらないので注意してください。それでも、プログラムの暴走が原因の場合に備えて実行スタックのトレースバックを出力できるように、例外が送出されます。

exception NameError

ローカルまたはグローバルの名前が見つからなかった場合に送出されます。これは非修飾の (訳注: spam.egg ではなく単に egg のような) 名前のみに適用されます。関連値は見つからなかった名前を含むエラーメッセージです。

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 属性がファイルシステムのエンコーディングでエンコードやデコードされた名前から、関数に渡された元々のファイル名になりました。 また、filename2 コンストラクタ引数が追加されました。

exception OverflowError

算術演算の結果が表現できない大きな値になった場合に送出されます。これは整数では起こりません (むしろ MemoryError が送出されることになるでしょう)。しかし、歴史的な理由のため、要求された範囲の外の整数に対して OverflowError が送出されることがあります。C の浮動小数点演算の例外処理は標準化されていないので、ほとんどの浮動小数点演算もチェックされません。

exception RecursionError

この例外は RuntimeError を継承しています。インタープリタが最大再帰深度 (sys.getrecursionlimit() を参照) の超過を検出すると送出されます。

バージョン 3.5 で追加: 以前は RuntimeError をそのまま送出していました。

exception ReferenceError

weakref.proxy() によって生成された弱参照 (weak reference) プロキシを使って、ガーベジコレクションによって回収された後の参照対象オブジェクトの属性にアクセスした場合に送出されます。弱参照については weakref モジュールを参照してください。

exception RuntimeError

他のカテゴリに分類できないエラーが検出された場合に送出されます。関連値は、何が問題だったのかをより詳細に示す文字列です。

exception StopIteration

組込み関数 next() と iterator の __next__() メソッドによって、そのイテレータが生成するアイテムがこれ以上ないことを伝えるために送出されます。

この例外オブジェクトには一つの属性 value があり、例外を構成する際に引数として与えられ、デフォルトは None です。

generator や coroutine 関数が返るとき、新しい StopIteration インスタンスが送出されます。 関数の返り値は例外のコンストラクタの value 引数として使われます。

If a generator code directly or indirectly raises StopIteration, it is converted into a RuntimeError (retaining the StopIteration as the new exception's cause).

バージョン 3.3 で変更: value 属性とジェネレータ関数が値を返すためにそれを使う機能が追加されました。

バージョン 3.5 で変更: Introduced the RuntimeError transformation via from __future__ import generator_stop, see PEP 479.

バージョン 3.7 で変更: Enable PEP 479 for all code by default: a StopIteration error raised in a generator is transformed into a RuntimeError.

exception StopAsyncIteration

イテレーションを停止するために、 asynchronous iterator オブジェクトの __anext__() メソッドによって返される必要があります。

バージョン 3.5 で追加.

exception SyntaxError

パーザが構文エラーに遭遇した場合に送出されます。この例外は import 文、組み込み関数 exec() や eval() 、初期化スクリプトの読み込みや標準入力で (対話的な実行時にも) 起こる可能性があります。

このクラスのインスタンスは、例外の詳細に簡単にアクセスできるようにするために、属性 filename, lineno, offset, text を持ちます。例外インスタンスに対する str() はメッセージのみを返します。

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`が渡された) :exc:`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

Raised when an operation or function receives an argument that has the right type but an inappropriate value, and the situation is not described by a more precise exception such as 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 を参照してください) 。

exception IsADirectoryError

ディレクトリに (os.remove() などの) ファイル操作が要求された場合に送出されます。errno EISDIR に対応します。

exception NotADirectoryError

ディレクトリ以外のものに (os.listdir() などの) ディレクトリ操作が要求された場合に送出されます。errno ENOTDIR に対応します。

exception PermissionError

十分なアクセス権、例えばファイルシステム権限のない操作が試みられた場合に送出されます。errno EACCES および EPERM に対応します。

exception ProcessLookupError

与えられたプロセスが存在しない場合に送出されます。errno ESRCH に対応します。

exception TimeoutError

システム関数がシステムレベルでタイムアウトした場合に送出されます。errno ETIMEDOUT に対応します。

バージョン 3.3 で追加: 上記のすべての OSError サブクラスが追加されました。

参考

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

警告

The following exceptions are used as warning categories; see the 警告カテゴリ documentation for more details.

exception Warning

警告カテゴリの基底クラスです。

exception UserWarning

ユーザコードによって生成される警告の基底クラスです。

exception DeprecationWarning

Base class for warnings about deprecated features when those warnings are intended for other Python developers.

exception PendingDeprecationWarning

将来廃止される予定の機能に対する警告の基底クラスです。

exception SyntaxWarning

曖昧な構文に対する警告の基底クラスです。

exception RuntimeWarning

あいまいなランタイム挙動に対する警告の基底クラスです。

exception FutureWarning

Base class for warnings about deprecated features when those warnings are intended for end users of applications that are written in Python.

exception ImportWarning

モジュールインポートの誤りと思われるものに対する警告の基底クラスです。

exception UnicodeWarning

Unicode に関連した警告の基底クラスです。

exception BytesWarning

bytes や bytearray に関連した警告の基底クラスです。

exception ResourceWarning

Base class for warnings related to resource usage. Ignored by the default warning filters.

バージョン 3.2 で追加.

例外のクラス階層

組み込み例外のクラス階層は以下のとおりです:

BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- StopAsyncIteration
      +-- ArithmeticError
      |    +-- FloatingPointError
      |    +-- OverflowError
      |    +-- ZeroDivisionError
      +-- AssertionError
      +-- AttributeError
      +-- BufferError
      +-- EOFError
      +-- 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
      +-- SyntaxError
      |    +-- IndentationError
      |         +-- TabError
      +-- SystemError
      +-- TypeError
      +-- ValueError
      |    +-- UnicodeError
      |         +-- UnicodeDecodeError
      |         +-- UnicodeEncodeError
      |         +-- UnicodeTranslateError
      +-- Warning
           +-- DeprecationWarning
           +-- PendingDeprecationWarning
           +-- RuntimeWarning
           +-- SyntaxWarning
           +-- UserWarning
           +-- FutureWarning
           +-- ImportWarning
           +-- UnicodeWarning
           +-- BytesWarning
           +-- ResourceWarning

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


テキスト処理サービス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

テキスト処理サービス

この章で説明するモジュールは幅広い文字列操作や様々なテキスト処理サービスを提供しています。

codecs モジュールはテキスト処理と高い関連性を持った バイナリデータ処理 のなかで説明されています。加えて Python の組み込み文字列型の テキストシーケンス型 --- str のドキュメントも参照して下さい。

  • string --- 一般的な文字列操作
    • 文字列定数
    • カスタムの文字列書式化
    • 書式指定文字列の文法
      • 書式指定ミニ言語仕様
      • 書式指定例
    • テンプレート文字列
    • ヘルパー関数
  • re --- 正規表現操作
    • 正規表現のシンタックス
    • モジュールコンテンツ
    • 正規表現オブジェクト
    • マッチオブジェクト
    • 正規表現の例
      • ペアの確認
      • scanf() をシミュレートする
      • search() vs. match()
      • 電話帳を作る
      • テキストの秘匿
      • 全ての副詞を見つける
      • 全ての副詞とその位置を見つける
      • Raw 文字列記法
      • トークナイザを書く
  • difflib --- 差分の計算を助ける
    • SequenceMatcherオブジェクト
    • SequenceMatcher の例
    • Differ オブジェクト
    • Differ の例
    • difflib のコマンドラインインタフェース
  • textwrap --- テキストの折り返しと詰め込み
  • unicodedata --- Unicode データベース
  • stringprep --- インターネットのための文字列調製
  • readline --- GNU readline のインタフェース
    • 初期化ファイル
    • 行バッファ
    • 履歴ファイル
    • 履歴リスト
    • 開始フック
    • 補完
    • 使用例
  • rlcompleter --- GNU readline向け補完関数
    • Completerオブジェクト

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


string --- 一般的な文字列操作

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • テキスト処理サービス »

string --- 一般的な文字列操作

ソースコード: 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 ロケールにおいて、句読点として扱われる ASCII 文字の文字列です。

string.printable

印刷可能な ASCII 文字で構成される文字列です。 digits, ascii_letters, punctuation および whitespace を組み合わせたものです。

string.whitespace

空白 (whitespace) として扱われる ASCII 文字全てを含む文字列です。ほとんどのシステムでは、これはスペース (space)、タブ (tab)、改行 (linefeed)、復帰 (return)、改頁 (formfeed)、垂直タブ (vertical tab) です。

カスタムの文字列書式化

組み込みの文字列 (string) クラスには、 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 に規定される "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       ::=  <described in the next section>

もっと簡単にいうと、置換フィールドは field_name で始められます。これによって指定したオブジェクトの値が、置換フィールドの代わりに書式化され出力に挿入されます。field_name の後に、感嘆符 '!' を挟んで conversion フィールドを続けることができます。最後にコロン ':' を挟んで、 format_spec を書くことができます。これは、置換される値の非デフォルトの書式を指定します。

書式指定ミニ言語仕様 節も参照して下さい。

field_name それ自身は、数かキーワードのいずれかである 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") は書式指定文字列の個々の値を表現する方法を指定するための、置換フィールドで使用されます (書式指定文字列の文法 および フォーマット済み文字列リテラル を参照してください) 。 それらは、組み込み関数の format() 関数に直接渡されます。 それぞれの書式指定可能な型について、書式指定がどのように解釈されるかが規定されます。

多くの組み込み型は、書式指定に関して以下のオプションを実装します。しかしながら、いくつかの書式指定オプションは数値型でのみサポートされます。

一般的な取り決めとして、空の書式指定文字列 ("") は、値に対して str() を呼び出したときと同じ結果を与えます。通常、空でない書式指定文字列はその結果を変更します。

一般的な書式指定子 (standard format specifier) の書式は以下です:

format_spec     ::=  [[fill]align][sign][#][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 オプションは数値型に対してのみ有効であり、以下のうちのひとつとなります:

オプション | 意味
'+' 符号の使用を、正数、負数の両方に対して指定します。
'-' 符号の使用を、負数に対してのみ指定します (デフォルトの挙動です)。
空白 | 空白を正数の前に付け、負号を負数の前に使用することを指定します。

'#' オプションは、変換に「別形式」を使用します。別形式は、異なる型に対して違った風に定義されます。このオプションは、整数、浮動小数点数、複素数、10進数の型でのみ有効です。整数に対して2進法、8進法、または16進法の出力が使用される場合、このオプションは出力される値にそれぞれ '0b', '0o', '0x' 接頭辞を加えます。浮動小数点数、複素数、10進数については、別形式では、小数点文字の後に数字がなくても変換結果には常に小数点文字が含まれます。通常は、数字が続く場合にのみ小数点文字がこれらの変換結果に現われます。さらに、'g' と 'G' の変換については、最後の 0 は結果から取り除かれません。

',' オプションは、千の位のセパレータにカンマを使うことを合図します。ロケール依存のセパレータには、代わりに 'n' の整数表現形式を使ってください。

バージョン 3.1 で変更: ',' オプションが追加されました ( PEP 378 も参照)。

'_' オプションは、浮動小数点数の表現型と整数の表現型 'd' における千倍ごとの区切り文字にアンダースコアを使うというしるしです。 整数の表現型の 'b', 'o', 'x', 'X' では、4桁ごとにアンダースコアが挿入されます。 他の表現型でこのオプションを指定するとエラーになります。

バージョン 3.6 で変更: '_' オプションが追加されました ( PEP 515 も参照)。

width は10進数の整数で、最小のフィールド幅を定義します。指定されない場合、フィールド幅はその内容により決定されます。

alignment が明示的に与えられない場合、 width フィールドにゼロ ('0') 文字を前置することは、数値型のための符号を意識した 0 パディングを可能にします。これは fill 文字に '0' を指定して、 alignment タイプに '=' を指定したことと等価です。

precision は10進数で、'f' および 'F' で指定される浮動小数点数の小数点以下、あるいは 'g' および 'G' で指定される浮動小数点数の小数点の前後に表示される桁数を指定します。非数型に対しては、最大フィールド幅を表します。言い換えると、フィールドの内容から何文字を使用するかということです。precision は整数型に対しては使うことができません。

最後に、type は、データがどのように表現されるかを決定します。

利用可能な文字列の表現型は以下です:

型 | 意味
's' | 文字列。これがデフォルトの値で、多くの場合省略されます。
None | 's' と同じです。

利用可能な整数の表現型は以下です:

型 | 意味
'b' | 2進数。出力される数値は2を基数とします。
'c' | 文字。数値を対応する Unicode 文字に変換します。
'd' | 10進数。出力される数値は10を基数とします。
'o' | 8進数。出力される数値は8を基数とします。
'x' | 16進数。出力される数値は16を基数とします。 10進で9を超える数字には小文字が使われます。
'X' | Hex format. Outputs the number in base 16, using upper-case letters for the digits above 9.
'n' | 数値。現在のロケールに従い、区切り文字を挿入することを除けば、 'd' と同じです。
None | 'd' と同じです。

これらの表現型に加えて、整数は ('n' と None を除く) 以下の浮動小数点数の表現型で書式指定できます。 そうすることで整数は書式変換される前に float() を使って浮動小数点数に変換されます。

利用可能な浮動小数点数と10進数の表現型は以下です:

型 | 意味
'e' | 指数表記です。指数を示す 'e' を使って数値を表示します。デフォルトの精度は 6 です。
'E' | 指数表記です。大文字の 'E' を使うことを除いては、 'e' と同じです。
'f' | 固定小数点数表記です。数値を固定小数点数として表示します。デフォルトの精度は 6 です。
'F' | 固定小数点数表記です。nan が NAN に、inf が INF に変換されることを除き 'f' と同じです。
'g'

汎用フォーマットです。精度を p >= 1 の数値で与えた場合、数値を有効桁 p で丸め、桁に応じて固定小数点か指数表記で表示します。

精度のルールは以下のように決まっています: 書式指定の結果が 'e' 型で p-1 の精度の場合、指数は exp になると仮定します。そうすると、 -4 <= exp < p のとき数値は表現型 'f' で精度 p-1-exp に書式変換されます。それ以外の場合、数値は 'e' 型で精度 p-1 に書式指定されます。この両方の場合で重要でない、連続した 0 は取り除かれます, そして残った桁が無い場合小数点は取り除かれます。

正と負の無限大と 0 および NaN は精度に関係なくそれぞれ inf, -inf, 0, -0 および nan となります。

0 の精度は 1 の精度と同等に扱われます。デフォルトの精度は 6 です。
'G' | 汎用フォーマットです。数値が大きくなったとき、 'E' に切り替わることを除き、 'g' と同じです。無限大と NaN の表示も大文字になります。
'n' | 数値です。現在のロケールに合わせて、数値分割文字が挿入されることを除き、 'g' と同じです。
'%' パーセンテージです。数値は 100 倍され、固定小数点数フォーマット ('f') でパーセント記号付きで表示されます。
None | 'g' に似ていますが、固定小数点表記を使ったとき、小数点の後に少なくとも 1 つの数字があることが異なります。デフォルトの精度は、その値を表現するのに必要なだけの高さです。全体的な効果は、他のフォーマット修飾子で変更されていても str() の出力と一致するようになっています。

書式指定例

この節では、 str.format() 構文の例を紹介し、さらに従来の %-書式と比較します。

多くの場合、新構文に {} を加え、 % の代わりに : を使うことで、古い %-書式に類似した書式になります。例えば、'%03.2f' は '{:03.2f}' と変換できます。

The new format syntax also supports new and different options, shown in the following examples.

位置引数を使ったアクセス:

>>> '{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 で解説されている単純な文字列置換ができます。 テンプレート文字列の主な使い道は国際化 (i18n) です。というのは、その国際化の文脈において、より簡潔な文法と機能を持つテンプレート文字列を使うと、 Python にある他の組み込みの文字列フォーマット機能よりも翻訳がしやすいからです。 テンプレート文字列の上に構築された国際化のためのライプラリの例として、 flufl.i18n を調べてみてください。

テンプレート文字列は $ に基づいた置換をサポートしていて、次の規則が使われています:

  • $$ はエスケープ文字です; $ 一つに置換されます。
  • $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 を送出せず単に $ を返します。

While other exceptions may still occur, this method is called "safe" because it always tries to return a usable string instead of raising an exception. In another sense, safe_substitute() may be anything other than safe, since it will silently ignore malformed templates containing dangling delimiters, unmatched braces, or placeholders that are not valid Python identifiers.

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.

    注釈

    Since default flags is re.IGNORECASE, pattern [a-z] can match with some non-ASCII characters. That's why we use the local a flag here.

    バージョン 3.7 で変更: braceidpattern can be used to define separate patterns used inside and outside the braces.

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

    バージョン 3.7 で追加.

  • flags -- 代入の認識のために使用される正規表現をコンパイルする際に適用される正規表現フラグ。デフォルト値は re.IGNORECASE です。re.VERBOSE が常にフラグに追加されるということに注意してください。したがって、カスタムな idpattern は verbose 正規表現の規約に従わなければなりません。

    バージョン 3.2 で追加.

他にも、クラス属性 pattern をオーバライドして、正規表現パターン全体を指定できます。オーバライドを行う場合、 pattern の値は 4 つの名前つきキャプチャグループ (capturing group) を持った正規表現オブジェクトでなければなりません。これらのキャプチャグループは、上で説明した規則と、無効なプレースホルダに対する規則に対応しています:

  • escaped -- このグループはエスケープシーケンス、すなわちデフォルトパターンにおける $$ に対応します。
  • named -- このグループは波括弧でくくらないプレースホルダ名に対応します; キャプチャグループに区切り文字を含めてはなりません。
  • braced -- このグループは波括弧でくくったプレースホルダ名に対応します; キャプチャグループに区切り文字を含めてはなりません。
  • invalid -- このグループはそのほかの区切り文字のパターン (通常は区切り文字一つ) に対応し、正規表現の末尾に出現しなければなりません。

ヘルパー関数

string.capwords(s, sep=None)

str.split() を使って引数を単語に分割し、 str.capitalize() を使ってそれぞれの単語の先頭の文字を大文字に変換し、 str.join() を使ってつなぎ合わせます。オプションの第2引数 sep が与えられないか None の場合、この置換処理は文字列中の連続する空白文字をスペース一つに置き換え、先頭と末尾の空白を削除します、それ以外の場合には sep は split と join に使われます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • テキスト処理サービス »


difflib --- 差分の計算を助ける

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • テキスト処理サービス »

difflib --- 差分の計算を助ける

ソースコード: Lib/difflib.py

このモジュールは、シーケンスを比較するためのクラスや関数を提供しています。例えば、ファイルの差分を計算して、それを HTML や context diff, unified diff などいろいろなフォーマットで出力するために、このモジュールを利用することができます。ディレクトリやファイル群を比較するためには、 filecmp モジュールも参照してください。

class difflib.SequenceMatcher

柔軟性のあるクラスで、二つのシーケンスの要素がハッシュ化できる(hashable)型であれば、どの型の要素を含むシーケンスも比較可能です。基本的なアルゴリズムは、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 で追加: autojunk パラメータ。

class difflib.Differ

テキスト行からなるシーケンスを比較するクラスです。人が読むことのできる差分を作成します。 Differ クラスは SequenceMatcher クラスを利用して、行からなるシーケンスを比較したり、(ほぼ)同一の行内の文字を比較したりします。

Differ クラスによる差分の各行は、2文字のコードで始まります:

コード 意味
'- ' 行はシーケンス1にのみ存在する
'+ ' 行はシーケンス2にのみ存在する
'  ' 行は両方のシーケンスで同一
'? ' 行は入力シーケンスのどちらにも存在しない

'?' で始まる行は、行内のどこに差異が存在するかに注意を向けようとします。その行は、入力されたシーケンスのどちらにも存在しません。シーケンスがタブ文字を含むとき、これらの行は判別しづらいものになることがあります。

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" ハイパーリンクを辿ると変更部分の強調表示がブラウザの最上部に表示されるようになります)。

バージョン 3.5 で変更: charset キーワード専用引数が追加されました。HTML 文書のデフォルトの文字集合が 'ISO-8859-1' から 'utf-8' に変更されました。

make_table(fromlines, tolines, fromdesc='', todesc='', context=False, numlines=5)

fromlines と tolines (いずれも文字列のリスト) を比較し、行間または行内の変更点が強調表示された行差分の入った完全な HTML テーブルを文字列で返します。

このメソッドの引数は、 make_file() メソッドの引数と同じです。

Tools/scripts/diff.py はこのクラスへのコマンドラインフロントエンドで、使い方を学ぶ上で格好の例題が入っています。

difflib.context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')

a と b (文字列のリスト) を比較し、差分 (差分形式の行を生成するジェネレータ(generator)) を、 context diff のフォーマット(以下「コンテクスト形式」)で返します。

コンテクスト形式は、変更があった行に前後数行を加えてある、コンパクトな表現方法です。変更箇所は、変更前/変更後に分けて表します。コンテクスト (変更箇所前後の行) の行数は n で指定し、デフォルト値は 3 です。

デフォルトで、 diff 制御行 (*** や --- を含む行) は改行付きで生成されます。 io.IOBase.readlines() で作られた入力が io.IOBase.writelines() で扱うのに適した diff になるので (なぜなら入力と出力の両方が改行付きのため) 、これは有用です。

行末に改行文字を持たない入力に対しては、出力でも改行文字を付加しないように lineterm 引数に "" を渡してください。

コンテクスト形式は、通常、ヘッダにファイル名と変更時刻を持っています。この情報は、文字列 fromfile, tofile, fromfiledate, tofiledate で指定できます。変更時刻の書式は、通常、ISO 8601 フォーマットで表されます。指定しなかった場合のデフォルト値は、空文字列です。

>>> 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 (文字列のリスト) を比較し、差分 (差分形式の行を生成するジェネレータ(generator)) を、 Differ のスタイルで返します。

オプションのキーワード引数 linejunk と charjunk には、フィルタ関数 (または None) を渡します。

linejunk: 文字列型の引数 1 つを受け取る関数です。文字列が junk の場合は真を、そうでない場合は偽を返します。デフォルトでは None です。モジュールレべルの関数 IS_LINE_JUNK() は、高々 1 つのシャープ記号('#')を除いて可視の文字を含まない行をフィルタリングするものです。しかし、下層にある SequenceMatcher クラスが、どの行が雑音となるほど頻繁に登場するかを動的に分析します。このクラスによる分析は、この関数を使用するよりも通常うまく動作します。

charjunk: 文字 (長さ1の文字列) を受け取る関数です。文字列が junk の場合は真を、そうでない場合は偽を返します。デフォルトでは、モジュールレべルの関数 IS_CHARACTER_JUNK() であり、これは空白文字類 (空白またはタブ、改行文字をこれに含めてはいけません) をフィルタして排除します。

Tools/scripts/ndiff.py は、この関数のコマンドラインのフロントエンド（インターフェイス）です。

>>> 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 (文字列のリスト) を比較し、差分 (差分形式の行を生成するジェネレータ(generator)) を、 unified diff フォーマット(以下「ユニファイド形式」)で返します。

ユニファイド形式は変更があった行にコンテキストとなる前後数行を加えた、コンパクトな表現方法です。変更箇所は (変更前/変更後を分離したブロックではなく) インラインスタイルで表されます。コンテクストの行数は、n で指定し、デフォルト値は 3 です。

デフォルトで、 diff 制御行 (---, +++, @@ を含む行) は改行付きで生成されます。 io.IOBase.readlines() で作られた入力が io.IOBase.writelines() で扱うのに適した diff になるので (なぜなら入力と出力の両方が改行付きのため) 、これは有用です。

行末に改行文字を持たない入力に対しては、出力でも改行文字を付加しないように lineterm 引数に "" を渡してください。

コンテクスト形式は、通常、ヘッダにファイル名と変更時刻を持っています。この情報は、文字列 fromfile, tofile, fromfiledate, tofiledate で指定できます。変更時刻の書式は、通常、ISO 8601 フォーマットで表されます。指定しなかった場合のデフォルト値は、空文字列です。

>>> 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 の未知または一貫性のないエンコーディングと同一になります。

バージョン 3.5 で追加.

difflib.IS_LINE_JUNK(line)

無視できる行のとき真を返します。行 line は空白、または '#' ひとつのときに無視できます。それ以外のときには無視できません。古いバージョンでは ndiff() の引数 linejunk にデフォルトで使用されました。

difflib.IS_CHARACTER_JUNK(ch)

無視できる文字のとき真を返します。文字 ch が空白、またはタブ文字のときには無視できます。それ以外の時には無視できません。 ndiff() の引数 charjunk としてデフォルトで使用されます。

参考

Pattern Matching: The Gestalt Approach
John W. Ratcliff と D. E. Metzener による類似のアルゴリズムに関する議論。Dr. Dobb's Journal 1988年7月号掲載。

SequenceMatcherオブジェクト

SequenceMatcher クラスには、以下のようなコンストラクタがあります:

class difflib.SequenceMatcher(isjunk=None, a='', b='', autojunk=True)

オプションの引数 isjunk は、None (デフォルトの値です) にするか、単一の引数をとる関数でなければなりません。後者の場合、関数はシーケンスの要素を受け取り、要素が junk であり、無視すべきである場合に限り真を返すようにしなければなりません。isjunk に None を渡すと、lambda x: 0 を渡したのと同じになります; すなわち、いかなる要素も無視しなくなります。例えば以下のような引数を渡すと:

lambda x: x in " \t"

空白とタブ文字を無視して文字のシーケンスを比較します。

オプションの引数 a と b は、比較される文字列で、デフォルトでは空の文字列です。両方のシーケンスの要素は、ハッシュ化可能(hashable)である必要があります。

オプションの引数 autojunk は、自動 junk ヒューリスティックを無効にするために使えます。

バージョン 3.2 で追加: autojunk パラメータ。

SequenceMatcher オブジェクトは3つのデータ属性を持っています: bjunk は、 isjunk が True であるような b の要素の集合です; bpopular は、 (無効でなければ) ヒューリスティックによって popular であると考えられる非ジャンク要素の集合です; b2j は、 b の残りの要素をそれらが生じる位置のリストに写像する dict です。この 3 つは set_seqs() または set_seq2() で b がリセットされる場合は常にリセットされます。

バージョン 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, ahi, blo, bhi)

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) を返します。

get_matching_blocks()

Return list of triples describing non-overlapping matching subsequences. Each triple is of the form (i, j, n), and means that a[i:i+n] == b[j:j+n]. The triples are monotonically increasing in i and j.

The last triple is a dummy, and has the value (len(a), len(b), 0). It is the only triple with n == 0. If (i, j, n) and (i', j', n') are adjacent triples in the list, and the second is not the last triple in the list, then i+n < i' or j+n < j'; in other words, adjacent triples always describe non-adjacent equal blocks.

>>> 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 行までのコンテクストを含むグループを生成するような、ジェネレータ(generator)を返します。

このメソッドは、 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() を最初に試してみる方がいいかもしれません。

quick_ratio()

ratio() の上界を、より高速に計算します。

real_quick_ratio()

ratio() の上界を、非常に高速に計算します。

この文字列全体のマッチ率を返す3つのメソッドは、精度の異なる近似値を返します。 quick_ratio() と real_quick_ratio() は、常に 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() は、[0, 1] の範囲の値を返し、シーケンスの類似度を測ります。経験によると、 ratio() の値が0.6を超えると、シーケンスがよく似ていることを示します:

>>> print(round(s.ratio(), 3))
0.866

シーケンスのどこがマッチしているかにだけ興味のある時には get_matching_blocks() が手軽でしょう:

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

get_matching_blocks() が返す最後のタプルが常にダミーであることに注目してください。このダミーは (len(a), len(b), 0) であり、これはタプルの最後の要素（マッチする要素の数）が 0 となる唯一のケースです。

はじめのシーケンスがどのようにして2番目のものになるのかを知るには、 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 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 の例

以下の例は2つのテキストを比較しています。最初に、テキストを行毎に改行で終わる文字列のシーケンスにセットアップします (そのようなシーケンスは、ファイル風オブジェクトの readlines() メソッドからも得ることができます):

>>> 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 のコマンドラインインタフェース

この例は、 difflib を使って diff に似たユーティリティーを作成する方法を示します。これは、 Python のソース配布物にも、 Tools/scripts/diff.py として含まれています。

#!/usr/bin/env python3
""" 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()

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • テキスト処理サービス »


textwrap --- テキストの折り返しと詰め込み

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • テキスト処理サービス »

textwrap --- テキストの折り返しと詰め込み

ソースコード: Lib/textwrap.py

textwrap モジュールは、実際の処理を行う TextWrapper とともに、いくつかの便利な関数を提供しています。1つか2つの文字列を wrap あるいは fill するだけの場合は便利関数で十分ですが、多くの処理を行う場合は効率のために TextWrapper のインスタンスを使うべきでしょう。

textwrap.wrap(text, width=70, **kwargs)

text (文字列)内の段落を一つだけ折り返しを行います。したがって、すべての行が高々 width 文字の長さになります。最後に改行が付かない出力行のリストを返します。

オプションのキーワード引数は、以下で説明する TextWrapper のインスタンス属性に対応しています。 width はデフォルトで 70 です。

wrap() の動作についての詳細は TextWrapper.wrap() メソッドを参照してください。

textwrap.fill(text, width=70, **kwargs)

text 内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。 fill() はこれの省略表現です

"\n".join(wrap(text, ...))

特に、 fill() は wrap() とまったく同じ名前のキーワード引数を受け取ります。

textwrap.shorten(text, width, **kwargs)

与えられた 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 の値を変更しても、意味がありません。

バージョン 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

バージョン 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 と現在のカラムに応じて、ゼロ以上のスペースに展開されます。

バージョン 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 に置き換えます。

バージョン 3.4 で追加.

placeholder

(デフォルト: ' [...]') 切り詰める場合に出力の最後の行に置く文字列です。

バージョン 3.4 で追加.

TextWrapper はモジュールレベルの簡易関数に類似したいくつかの公開メソッドも提供します:

wrap(text)

1段落の文字列 text を、各行が width 文字以下になるように wrap します。 wrap のすべてのオプションは TextWrapper インスタンスの属性から取得します。結果の、行末に改行のない行のリストを返します。出力の内容が空になる場合は、返すリストも空になります。

fill(text)

text 内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • テキスト処理サービス »


unicodedata --- Unicode データベース

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • テキスト処理サービス »

unicodedata --- Unicode データベース

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

このモジュールは、ユニコード標準付録 #44 「 ユニコード文字データベース 」で定義されているのと同じ名前およびシンボルを使用します。このモジュールは次のような関数を定義します:

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.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] http://www.unicode.org/Public/11.0.0/ucd/NameAliases.txt
[2] http://www.unicode.org/Public/11.0.0/ucd/NamedSequences.txt

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • テキスト処理サービス »


stringprep --- インターネットのための文字列調製

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • テキスト処理サービス »

stringprep --- インターネットのための文字列調製

ソースコード: Lib/stringprep.py

(ホスト名のような) インターネット上にある存在に識別名をつける際、しばしば識別名間の "等価性" 比較を行う必要があります。厳密には、例えば大小文字の区別をするかしないかいったように、比較をどのように行うかはアプリケーションの領域に依存します。また、例えば "印字可能な" 文字で構成された識別名だけを許可するといったように、可能な識別名を制限することも必要となるかもしれません。

RFC 3454 では、インターネットプロトコル上で Unicode 文字列を "調製 (prepare)" するためのプロシジャを定義しています。文字列は通信路に載せられる前に調製プロシジャで処理され、その結果ある正規化された形式になります。RFC ではあるテーブルの集合を定義しており、それらはプロファイルにまとめられています。各プロファイルでは、どのテーブルを使い、 stringprep プロシジャのどのオプション部分がプロファイルの一部になっているかを定義しています。 stringprep プロファイルの一つの例は nameprep で、国際化されたドメイン名に使われます。

The module stringprep only exposes the tables from RFC 3454. As these tables would be very large to represent them as dictionaries or lists, the module uses the Unicode character database internally. The module source code itself was generated using the mkstringprep.py utility.

その結果、これらのテーブルはデータ構造体ではなく、関数として公開されています。RFC には 2 種類のテーブル: 集合およびマップ、が存在します。集合については、 stringprep は "特性関数 (characteristic function)" 、すなわち引数が集合の一部である場合に真を返す関数を提供します。マップに対しては、マップ関数: キーが与えられると、それに関連付けられた値を返す関数、を提供します。以下はこのモジュールで利用可能な全ての関数を列挙したものです。

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 のインタフェース

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • テキスト処理サービス »

readline --- GNU readline のインタフェース

readline モジュールでは、補完や Python インタプリタからの履歴ファイルの読み書きを容易にするための多くの関数を定義しています。 このモジュールは直接、または rlcompleter モジュールを介して使うことができます。 rlcompleter モジュールは対話的プロンプトで Python 識別子の補完をサポートするものです。 このモジュールで利用される設定は、インタプリタの対話プロンプトならびに組み込みの input() 関数の両方の挙動に影響します。

readline のキーバインディングは初期化ファイルで設定できます。 このファイルは、たいていはホームディレクトリに .inputrc という名前で置いてあります。 GNU Readline マニュアルの 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.

libedit の設定ファイルは GNU readline のものとは異なります。もし設定文字列をプログラムからロードしているなら、 GNU readline と libedit を区別するために "libedit" という文字列が readline.__doc__ に含まれているかどうかチェックしてください。

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 がこの機能をサポートするライブラリーのバージョンでコンパイルされたときのみ、この関数は存在します。

バージョン 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.

バージョン 3.6 で追加.

CPython implementation detail: 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.

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 --- GNU readline向け補完関数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • テキスト処理サービス »

rlcompleter --- GNU readline向け補完関数

ソースコード: Lib/rlcompleter.py

rlcompleter モジュールではPythonの識別子やキーワードを定義した readline モジュール向けの補完関数を定義しています。

このモジュールが Unixプラットフォームでimportされ、 readline が利用できるときには、 Completer クラスのインスタンスが自動的に作成され、 complete() メソッドが readline 補完に設定されます。

以下はプログラム例です:

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

rlcompleter モジュールは、 Python の 対話モード と一緒に使用するのを意図して設計されています。Python を -S オプションをつけずに実行している場合、このモジュールが自動的にインポートされ、構成されます (readline の設定 を参照)。

readline のないプラットフォームでも、このモジュールで定義される Completer クラスは独自の目的に使えます。

Completerオブジェクト

Completerオブジェクトは以下のメソッドを持っています:

Completer.complete(text, state)

text の state 番目の補完候補を返します。

もし text がピリオド('.')を含まない場合、 __main__ 、 builtins で定義されている名前か、キーワード (keyword モジュールで定義されている) から補完されます。

ピリオドを含む名前の場合、副作用を出さずに名前を最後まで評価しようとします(関数を明示的に呼び出しはしませんが、 __getattr__() を呼んでしまうことはあります)そして、 dir() 関数でマッチする語を見つけます。式を評価中に発生した全ての例外は補足して無視され、 None を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • テキスト処理サービス »


バイナリデータ処理

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

バイナリデータ処理

この章で紹介されているモジュールはバイナリデータを扱うための基本的な処理を提供しています。ファイルフォーマットやネットワークプロトコルなど、その他のバイナリデータ処理については、それぞれの節で解説されています。

テキスト処理サービス で紹介する一部のライブラリには、 ASCII 互換のバイナリフォーマットで利用できるもの (例: re) や 、すべてのバイナリデータで利用できるもの (例: difflib) があります。

加えて、 バイナリシーケンス型 --- bytes, bytearray, memoryview に書かれているPythonビルトインデータ型についても参照してください。

  • struct --- バイト列をパックされたバイナリデータとして解釈する
    • 関数と例外
    • 書式文字列
      • バイトオーダ、サイズ、アラインメント
      • 書式指定文字
      • 使用例
    • クラス
  • codecs --- codec レジストリと基底クラス
    • 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 --- バイト列をパックされたバイナリデータとして解釈する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • バイナリデータ処理 »

struct --- バイト列をパックされたバイナリデータとして解釈する

ソースコード: Lib/struct.py

このモジュールは、 Python の値と Python bytes オブジェクトとして表される C の構造体データとの間の変換を実現します。このモジュールは特に、ファイルに保存されたり、ネットワーク接続を経由したバイナリデータを扱うときに使われます。このモジュールでは、C 構造体のレイアウトおよび Python の値との間で行いたい変換をコンパクトに表現するために、 書式文字列 を使います。

注釈

デフォルトでは、与えられた C の構造体をパックする際に、関連する C データ型を適切にアラインメント(alignment)するために数バイトのパディングを行うことがあります。この挙動が選択されたのは、パックされた構造体のバイト表現を対応する C 構造体のメモリレイアウトに正確に対応させるためです。プラットフォーム独立のデータフォーマットを扱ったり、隠れたパディングを排除したりするには、サイズ及びアラインメントとして native の代わりに standard を使うようにします: 詳しくは バイトオーダ、サイズ、アラインメント を参照して下さい。

いくつかの struct の関数 (および Struct のメソッド) は buffer 引数を取ります。 これは バッファプロトコル (buffer Protocol) を実装していて読み取り可能または読み書き可能なバッファを提供するオブジェクトのことです。この目的のために使われる最も一般的な型は bytes と bytearray ですが、バイトの配列とみなすことができるような他の多くの型がバッファプロトコルを実装しています。そのため、それらは bytes オブジェクトから追加のコピーなしで読み出しや書き込みができます。

関数と例外

このモジュールは以下の例外と関数を定義しています:

exception struct.error

様々な状況で送出される例外です。引数は何が問題なのかを記述する文字列です。

struct.pack(format, v1, v2, ...)

Return a bytes object containing the values v1, v2, ... packed according to the format string format. The arguments must match the values required by the format exactly.

struct.pack_into(format, buffer, offset, v1, v2, ...)

Pack the values v1, v2, ... according to the format string format and write the packed bytes into the writable buffer buffer starting at position offset. Note that offset is a required argument.

struct.unpack(format, buffer)

Unpack from the buffer buffer (presumably packed by pack(format, ...)) according to the format string format. The result is a tuple even if it contains exactly one item. The buffer's size in bytes must match the size required by the format, as reflected by calcsize().

struct.unpack_from(format, buffer, offset=0)

Unpack from buffer starting at position offset, according to the format string format. The result is a tuple even if it contains exactly one item. The buffer's size in bytes, minus offset, must be at least the size required by the format, as reflected by calcsize().

struct.iter_unpack(format, buffer)

Iteratively unpack from the buffer buffer according to the format string format. This function returns an iterator which will read equally-sized chunks from the buffer until all its contents have been consumed. The buffer's size in bytes must be a multiple of the size required by the format, as reflected by calcsize().

イテレーション毎に書式文字列で指定されたタプルを yield します。

バージョン 3.4 で追加.

struct.calcsize(format)

Return the size of the struct (and hence of the bytes object produced by pack(format, ...)) corresponding to the format string format.

書式文字列

書式文字列はデータをパックしたりアンパックしたりするときの期待されるレイアウトを指定するためのメカニズムです。文字列はパック/アンパックされるデータの型を指定する 書式指定文字 から組み立てられます。さらに、 バイトオーダ、サイズ、アラインメント を制御するための特殊文字もあります。

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

デフォルトでは、C での型はマシンのネイティブ (native) の形式およびバイトオーダ (byte order) で表され、適切にアラインメント (alignment) するために、必要に応じて数バイトのパディングを行ってスキップします (これは C コンパイラが用いるルールに従います)。

これに代わって、フォーマット文字列の最初の文字を使って、バイトオーダやサイズ、アラインメントを指定することができます。指定できる文字を以下のテーブルに示します:

文字 | バイトオーダ | サイズ | アラインメント
@ | native | native | native
= | native | standard | none
< | リトルエンディアン | standard | none
> | ビッグエンディアン | standard | none
! | ネットワーク (= ビッグエンディアン) | standard | none

フォーマット文字列の最初の文字が上のいずれかでない場合、'@' であるとみなされます。

ネイティブのバイトオーダはビッグエンディアンかリトルエンディアンで、ホスト計算機に依存します。例えば、Intel x86 および AMD64 (x86-64) はリトルエンディアンです。Motorola 68000 および PowerPC G5 はビッグエンディアンです。ARM および Intel Itanium はエンディアンを切り替えられる機能を備えています (バイエンディアン)。使っているシステムでのエンディアンは sys.byteorder を使って調べて下さい。

ネイティブのサイズおよびアラインメントは C コンパイラの sizeof 式で決定されます。ネイティブのサイズおよびアラインメントはネイティブのバイトオーダと同時に使われます。

標準のサイズはフォーマット文字だけで決まります。 書式指定文字 の表を参照して下さい。

'@' と '=' の違いに注意してください: 両方ともネイティブのバイトオーダですが、後者のバイトサイズとアラインメントは標準のものに合わせてあります。

'!' 表記は、ネットワークバイトオーダがビッグエンディアンかリトルエンディアンか忘れてしまったという不運な方のために用意されています。

バイトオーダに関して、「(強制的にバイトスワップを行う)ネイティブの逆」を指定する方法はありません。'<' または '>' のうちふさわしい方を選んでください。

注釈:

  1. パディングは構造体のメンバの並びの中にだけ自動で追加されます。最初や最後にパディングが追加されることはありません。
  2. ネイティブでないサイズおよびアラインメントが使われる場合にはパディングは行われません (たとえば '<', '>', '=', '!' を使った場合です)。
  3. 特定の型によるアラインメント要求に従うように構造体の末端をそろえるには、繰り返し回数をゼロにした特定の型でフォーマットを終端します。 使用例 を参照して下さい。

書式指定文字

フォーマット文字 (format character) は以下の意味を持っています; C と Python の間の変換では、値は正確に以下に指定された型でなくてはなりません: 「標準のサイズ」列は standard サイズ使用時にパックされた値が何バイトかを示します。つまり、フォーマット文字列が '<', '>', '!', '=' のいずれかで始まっている場合のものです。native サイズ使用時にはパックされた値の大きさはプラットフォーム依存です。

フォーマット | C の型 | Python の型 | 標準のサイズ | 注釈
x | パディングバイト | 値なし |  |
c | char | 長さ 1 のバイト列 | 1 |
b | signed char | 整数 | 1 | (1),(3)
B | unsigned char | 整数 | 1 | (3)
? | _Bool | 真偽値型(bool) | 1 | (1)
h | short | 整数 | 2 | (3)
H | unsigned short | 整数 | 2 | (3)
i | int | 整数 | 4 | (3)
I | unsigned int | 整数 | 4 | (3)
l | long | 整数 | 4 | (3)
L | unsigned long | 整数 | 4 | (3)
q | long long | 整数 | 8 | (2), (3)
Q | unsigned long long | 整数 | 8 | (2), (3)
n | ssize_t | 整数 |  | (4)
N | size_t | 整数 |  | (4)
e | (7) | 浮動小数点数 | 2 | (5)
f | float | 浮動小数点数 | 4 | (5)
d | double | 浮動小数点数 | 8 | (5)
s | char[] | bytes |  |
p | char[] | bytes |  |
P | void * | 整数 |  | (6)

バージョン 3.3 で変更: 'n' および 'N' フォーマットのサポートが追加されました。

バージョン 3.6 で変更: 'e' フォーマットのサポートが追加されました。

注釈:

  1. '?' 変換コードは C99 で定義された _Bool 型に対応します。その型が利用できない場合は、 char で代用されます。標準モードでは常に1バイトで表現されます。

  2. 変換コード 'q' および 'Q' は、ネイティブモードではプラットフォームの C コンパイラが C の long long 型をサポートする場合、または Windows では __int64 をサポートする場合にのみ利用できます。標準モードでは常に利用できます。

  3. 非整数を整数の変換コードを使ってパックしようとすると、非整数が __index__() メソッドを持っていた場合は、整数に変換するためにパックする前にそのメソッドが呼ばれます。

    バージョン 3.2 で変更: 非整数に対して __index__() メソッドが使われるようになったのは 3.2 の新機能です。

  4. 'n' および 'N' 変換コードは (デフォルトもしくはバイトオーダ文字 '@' 付きで選択される) native サイズ使用時のみ利用できます。standard サイズ使用時には、自身のアプリケーションに適する他の整数フォーマットを使うことができます。

  5. 'f' 、 'd' および 'e' 変換コードについて、パックされた表現は IEEE 754 binary32 ('f' の場合) 、 binary64 ('d' の場合) 、またはbinary16('e' の場合) フォーマットが、プラットフォームにおける浮動小数点数のフォーマットに関係なく使われます。

  6. 'P' フォーマット文字はネイティブバイトオーダでのみ利用可能です (デフォルトのネットワークバイトオーダに設定するか、'@' バイトオーダ指定文字を指定しなければなりません)。'=' を指定した場合、ホスト計算機のバイトオーダに基づいてリトルエンディアンとビッグエンディアンのどちらを使うかを決めます。struct モジュールはこの設定をネイティブのオーダ設定として解釈しないので、'P' を使うことはできません。

  7. IEEE 754 の binary16 "半精度" 型は、 IEEE 754 standard の2008 年の改訂で導入されました。 半精度型は、符号 bit 、5 bit の指数部、 11 bit の精度 (明示的には 10 bit が保存される) を持ち、おおよそ 6.1e-05 から 6.5e+04 までの数を完全な精度で表現できます。 この型は C コンパイラでは広くはサポートされていません: たいていのマシンでは、保存するのに unsigned short が使えますが、数学の演算には使えません。 詳しいことは Wikipedia の half-precision floating-point format のページを参照してください。

フォーマット文字の前に整数をつけ、繰り返し回数 (count) を指定することができます。例えば、フォーマット文字列 '4h' は 'hhhh' と全く同じ意味です。

フォーマット文字間の空白文字は無視されます; count とフォーマット文字の間にはスペースを入れてはいけません。

's' フォーマット文字での繰り返し回数 (count) は、他のフォーマット文字のような繰り返し回数ではなく、バイト長として解釈されます。例えば、'10s' は単一の 10 バイトの文字列を意味し、'10c' は 10 個の文字を意味します。繰り返し回数が指定されなかった場合は、デフォルト値の 1 とみなされます。パックでは、文字列はサイズに合うように切り詰められたり null バイトで埋められたりします。アンパックでは、返されるバイトオブジェクトのバイト数は、正確に指定した通りになります。特殊な場合として、'0s' は単一の空文字列を意味し、'0c' は 0 個の文字を意味します。

整数フォーマット ('b', 'B', 'h', 'H', 'i', 'I', 'l', 'L', 'q', 'Q') のいずれかを使って値 x をパックするとき x がフォーマットの適切な値の範囲に無い場合、 struct.error が送出されます。

バージョン 3.1 で変更: 3.0 では、いくつかの整数フォーマットが適切な範囲にない値を覆い隠して、 struct.error の代わりに DeprecationWarning を送出していました。

フォーマット文字 'p' は "Pascal 文字列 (pascal string)" をコードします。Pascal 文字列は count で与えられる 固定長のバイト列 に収められた短い可変長の文字列です。このデータの先頭の 1 バイトには文字列の長さか255 のうち、小さい方の数が収められます。その後に文字列のバイトデータが続きます。 pack() に渡された Pascal 文字列の長さが長すぎた (count-1 よりも長い) 場合、先頭の count-1 バイトが書き込まれます。文字列が count-1 よりも短い場合、指定した count バイトに達するまでの残りの部分はヌルで埋められます。 unpack() では、フォーマット文字 'p' は指定された count バイトだけデータを読み込みますが、返される文字列は決して 255 文字を超えることはないので注意してください。

'?' フォーマット文字では、返り値は True または False です。パックするときには、引数オブジェクトの論理値としての値が使われます。 0 または 1 のネイティブや標準の真偽値表現でパックされ、アンパックされるときはゼロでない値は True になります。

使用例

注釈

全ての例は、ビッグエンディアンのマシンで、ネイティブのバイトオーダ、サイズおよびアラインメントを仮定します。

基本的な例として、三つの整数をパック/アンパックします:

>>> from struct import *
>>> pack('hhl', 1, 2, 3)
b'\x00\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('hhl')
8

アンパックした結果のフィールドは、変数に割り当てるか 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)

アラインメントの要求を満たすために必要なパディングが異なるという理由により、フォーマット文字の順番がサイズの違いを生み出すことがあります:

>>> pack('ci', b'*', 0x12131415)
b'*\x00\x00\x00\x12\x13\x14\x15'
>>> pack('ic', 0x12131415, b'*')
b'\x12\x13\x14\x15*'
>>> calcsize('ci')
8
>>> calcsize('ic')
5

以下のフォーマット 'llh0l' は、long 型が 4 バイトを境界としてそろえられていると仮定して、末端に 2 バイトをパディングします:

>>> pack('llh0l', 1, 2, 3)
b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

この例はネイティブのサイズとアラインメントが使われているときだけ思った通りに動きます。標準のサイズとアラインメントはアラインメントの設定ではいかなるアラインメントも行いません。

参考

array モジュール
一様なデータ型からなるバイナリ記録データのパック。
xdrlib モジュール
XDR データのパックおよびアンパック。

クラス

struct モジュールは次の型を定義します:

class struct.Struct(format)

フォーマット文字列 format に従ってバイナリデータを読み書きする、新しい Struct オブジェクトを返します。 Struct オブジェクトを一度作ってからそのメソッドを使うと、フォーマット文字列のコンパイルが一度で済むので、 struct モジュールの関数を同じフォーマットで何度も呼び出すよりも効率的です。

注釈

The compiled versions of the most recent format strings passed to Struct and 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() 関数と同じ、コンパイルされたフォーマットを利用するメソッドです。 (buffer のバイト数 - offset は少なくとも size 以上でなければなりません)。

iter_unpack(buffer)

iter_unpack() 関数と同じ、コンパイルされたフォーマットを利用するメソッドです。 (buffer のバイト数は size の倍数でなければなりません)。

バージョン 3.4 で追加.

format

この Struct オブジェクトを作成する時に利用されたフォーマット文字列です。

バージョン 3.7 で変更: The format string type is now str instead of bytes.

size

format 属性に対応する構造体の (従って pack() メソッドによって作成されるバイト列オブジェクトの) サイズです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • バイナリデータ処理 »


データ型

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

データ型

この章で解説されるモジュールは日付や時間、型が固定された配列、ヒープキュー、同期キュー、集合のような種々の特殊なデータ型を提供します。

Python にはその他にもいくつかの組み込みデータ型があります。特に、 dict 、 list 、 set 、 frozenset 、そして tuple があります。 str クラスは Unicode データを扱うことができ、 bytes クラスはバイナリデータを扱うことができます。

この章では以下のモジュールが記述されています:

  • datetime --- 基本的な日付型および時間型
    • 利用可能なデータ型
    • timedelta オブジェクト
    • date オブジェクト
    • datetime オブジェクト
    • time オブジェクト
    • tzinfo オブジェクト
    • timezone オブジェクト
    • strftime() と strptime() の振る舞い
  • calendar --- 一般的なカレンダーに関する関数群
  • collections --- コンテナデータ型
    • ChainMap オブジェクト
      • ChainMap の例とレシピ
    • Counter オブジェクト
    • deque オブジェクト
      • deque のレシピ
    • defaultdict オブジェクト
      • defaultdict の使用例
    • namedtuple() 名前付きフィールドを持つタプルのファクトリ関数
    • OrderedDict オブジェクト
      • OrderedDict の例とレシピ
    • UserDict オブジェクト
    • UserList オブジェクト
    • UserString オブジェクト
  • collections.abc --- コレクションの抽象基底クラス
    • コレクション抽象基底クラス
  • heapq --- ヒープキューアルゴリズム
    • 基本的な例
    • 優先度キュー実装の注釈
    • 理論
  • bisect --- 配列二分法アルゴリズム
    • ソート済みリストの探索
    • その他の使用例
  • array --- 効率のよい数値アレイ
  • weakref --- 弱参照
    • 弱参照オブジェクト
    • 使用例
    • ファイナライザオブジェクト
    • ファイナライザと __del__() メソッドとの比較
  • types --- 動的な型生成と組み込み型に対する名前
    • 動的な型生成
    • 標準的なインタプリタ型
    • 追加のユーティリティクラスと関数
    • コルーチンユーティリティ関数
  • copy --- 浅いコピーおよび深いコピー操作
  • pprint --- データ出力の整然化
    • PrettyPrinter オブジェクト
    • 使用例
  • reprlib --- もう一つの repr() の実装
    • Reprオブジェクト
    • Reprオブジェクトをサブクラス化する
  • enum --- 列挙型のサポート
    • モジュールコンテンツ
    • Enum の作成
    • 列挙型メンバーおよびそれらの属性へのプログラム的アクセス
    • 列挙型メンバーと値の重複
    • 番号付けの値が同一であることの確認
    • 値の自動設定を使う
    • イテレーション
    • 比較
    • 列挙型で許されるメンバーと属性
    • Restricted Enum subclassing
    • Pickle 化
    • 機能 API
    • 派生列挙型
      • IntEnum
      • IntFlag
      • Flag
      • その他
    • 興味深い例
      • 値の省略
        • auto を使う
        • object を使う
        • 解説文字列を使う
        • 独自の __new__() を使う
      • OrderedEnum
      • DuplicateFreeEnum
      • Planet
      • TimePeriod
    • Enum はどう違うのか?
      • Enum クラス
      • Enum メンバー (インスタンス)
      • 細かい点
        • __dunder__ 名のサポート
        • _sunder_ 名のサポート
        • Enum メンバー型
        • Enum クラスとメンバーの真偽値
        • メソッド付きの Enum クラス
        • Flag のメンバーの組み合わせ

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


datetime --- 基本的な日付型および時間型

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

datetime --- 基本的な日付型および時間型

ソースコード: Lib/datetime.py

datetime モジュールでは、日付や時間データを簡単な方法と複雑な方法の両方で操作するためのクラスを提供しています。日付や時刻を対象にした四則演算がサポートされている一方で、このモジュールの実装では出力の書式化や操作を目的とした属性の効率的な取り出しに焦点を絞っています。機能については、 time および calendar も参照してください。

"naive" と "aware" の2種類の日付と時刻オブジェクトがあります。

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

date や datetime オブジェクトで許されている、年を表現する最小の数字です。 MINYEAR は 1 です。

datetime.MAXYEAR

date や datetime オブジェクトで許されている、年を表現する最大の数字です。 MAXYEAR は 9999 です。

参考

calendar モジュール
汎用のカレンダー関連関数。
time モジュール
時刻へのアクセスと変換。

利用可能なデータ型

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

date, time, あるいは datetime クラスの二つのインスタンス間の時間差をマイクロ秒精度で表す経過時間値です。

class datetime.tzinfo

タイムゾーン情報オブジェクトの抽象基底クラスです。 datetime および time クラスで用いられ、カスタマイズ可能な時刻修正の概念 (たとえばタイムゾーンや夏時間の計算）を提供します。

class datetime.timezone

tzinfo 抽象基底クラスを UTC からの固定オフセットとして実装するクラスです。

バージョン 3.2 で追加.

これらの型のオブジェクトは変更不可能 (immutable) です。

date 型のオブジェクトは常に naive です。

time や datetime 型のオブジェクトは naive か aware のどちらかになります。 datetime オブジェクト d は d.tzinfo が None でなく d.tzinfo.utcoffset(d) が None を返さない場合、aware です。d.tzinfo が None であるか d.tzinfo が None でないが d.tzinfo.utcoffset(d) が None を返す場合、 d は naive です。 time のオブジェクト t は t.tzinfo が None でなく t.tzinfo.utcoffset(None) が None を返さない場合に aware になって、それ以外の場合には t は naive になります。

naive なオブジェクトと aware なオブジェクトの区別は timedelta オブジェクトにはあてはまりません。

サブクラスの関係は以下のようになります:

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

timedelta オブジェクト

timedelta オブジェクトは経過時間、すなわち二つの日付や時刻間の差を表します。

class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

全ての引数がオプションで、デフォルト値は 0 です。引数は整数、浮動小数点数にすることができ、正でも負でもかまいません。

days, seconds, microseconds だけが内部的に保持されます. 引数は以下のようにして変換されます:

  • 1 ミリ秒は 1000 マイクロ秒に変換されます。
  • 1 分は 60 秒に変換されます。
  • 1 時間は 3600 秒に変換されます。
  • 1 週間は 7 日に変換されます。

さらに、値が一意に表されるように days, seconds, microseconds が以下のように正規化されます

  • 0 <= microseconds < 1000000
  • 0 <= seconds < 3600*24 (一日中の秒数)
  • -999999999 <= days <= 999999999

引数のいずれかが浮動小数点であり、小数のマイクロ秒が存在する場合、小数のマイクロ秒は全ての引数から一度取り置かれ、それらの和は最近接偶数のマイクロ秒に丸められます。浮動小数点の引数がない場合、値の変換と正規化の過程は厳密な (失われる情報がない) ものとなります。

日の値を正規化した結果、指定された範囲の外側になった場合には、 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) です。

正規化のために、 timedelta.max > -timedelta.min となるので注意してください。 -timedelta.max は timedelta オブジェクトとして表現することができません。

インスタンスの属性 (読み出しのみ):

属性 | 値
days | 両端値を含む -999999999 から 999999999 の間
seconds | 両端値を含む 0 から 86399 の間
microseconds | 両端値を含む 0 から 999999 の間

サポートされている演算を以下に示します:

演算 | 結果
t1 = t2 + t3 | t2 と t3 の和。演算後、t1-t2 == t3 および t1-t3 == t2 は真になります。(1)
t1 = t2 - t3 | t2 と t3 の差分です。演算後、 t1 == t2 - t3 および t2 == t1 + t3 は真になります。 (1)(6)
t1 = t2 * i または t1 = i * t2 | 時間差と整数の積。演算後、t1 // i == t2 は i != 0 であれば真となります。
 | 一般的に、t1 * i == t1 * (i-1) + t1 は真となります。(1)
t1 = t2 * f または t1 = f * t2 | 時間差と浮動小数点の積。結果は最近接偶数への丸めを利用して最も近い timedelta.resolution の倍数に丸められます。
f = t2 / t3 | t2 を t3 で除したもの (3)。float オブジェクトを返します。
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 | timedelta(-t1.days, -t1.seconds, -t1.microseconds)、および t1* -1 と同じです。 (1)(4)
abs(t) | t.days >= 0 のときには +t, t.days < 0 のときには -t となります。(2)
str(t) | [D day[s], ][H]H:MM:SS[.UUUUUU] という形式の文字列を返します。t が負の値の場合は D は負の値となります。(5)
repr(t) | timedelta オブジェクトの文字列表現を返します。その文字列は、正規の属性値を持つコンストラクタ呼び出しのコードになっています。

注釈:

  1. この演算は正確ですが、オーバフローするかもしれません。

  2. この演算は正確であり、オーバフローしないはずです。

  3. 0 による除算は ZeroDivisionError を送出します。

  4. -timedelta.max は timedelta オブジェクトで表現することができません。

  5. timedelta オブジェクトの文字列表現は内部表現に類似した形に正規化されます。そのため負の timedelta は少し変な結果になります。例えば:

    >>> timedelta(hours=-5)
datetime.timedelta(days=-1, seconds=68400)
>>> print(_)
-1 day, 19:00:00

  6. t3 が timedelta.max のときを除けば、式 t2 - t3 は常に、式 t2 + (-t3) と同等です。t3 が timedelta.max の場合、前者の式は結果の値が出ますが、後者はオーバーフローを起こします。

上に列挙した操作に加えて、 timedelta オブジェクトは date および datetime オブジェクトとの間で加減算をサポートしています (下を参照してください)。

バージョン 3.2 で変更: timedelta オブジェクトの別の timedelta オブジェクトによる、切り捨ての割り算と真の値の割り算、および剰余演算子と divmod() 関数がサポートされるようになりました。 timedelta オブジェクトと float オブジェクトの真の値の割り算と掛け算がサポートされるようになりました。

timedelta オブジェクト間の比較はサポートされており、より小さい経過時間を表す timedelta オブジェクトがより小さい timedelta と見なされます。型混合の比較がデフォルトのオブジェクトアドレス比較となってしまうのを抑止するために、 timedelta オブジェクトと異なる型のオブジェクトが比較されると、比較演算子が == または != でないかぎり TypeError が送出されます。後者の場合、それぞれ False または True を返します。

timedelta オブジェクトは hashable (ハッシュ可能、つまり、辞書のキーとして利用可能) であり、効率的な pickle 化をサポートします。また、ブール演算コンテキストでは、 timedelta オブジェクトは timedelta(0) に等しくない場合かつそのときに限り真となります。

インスタンスメソッド:

timedelta.total_seconds()

この期間に含まれるトータルの秒数を返します。td / timedelta(seconds=1) と等価です。

非常に長い期間 (多くのプラットフォームでは270年以上) については、このメソッドはマイクロ秒の精度を失うことがあることに注意してください。

バージョン 3.2 で追加.

使用例:

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)  # adds up to 365 days
>>> year.total_seconds()
31536000.0
>>> year == another_year
True
>>> ten_years = 10 * year
>>> ten_years, ten_years.days // 365
(datetime.timedelta(days=3650), 10)
>>> nine_years = ten_years - year
>>> nine_years, nine_years.days // 365
(datetime.timedelta(days=3285), 9)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)
>>> abs(three_years - ten_years) == 2 * three_years + year
True

date オブジェクト

date オブジェクトは日付 (年、月、および日) を表します。日付は理想的なカレンダー、すなわち現在のグレゴリオ暦を過去と未来の両方向に無限に延長したもので表されます。 1 年の 1 月 1 日は日番号 1, 1 年 1 月 2 日は日番号 2,となっていきます。この暦法は、全ての計算における基本カレンダーである、 Dershowitz と Reingold の書籍 Calendrical Calculations における先発グレゴリオ暦 (proleptic Gregorian) の定義に一致します。

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)

date.isoformat() から出力される形式の date_string に対応する date を返します。 具体的には、この関数は YYYY-MM-DD という形式の文字列をサポートしています。

ご用心

この関数は、任意の ISO 8601 文字列の構文解析をサポートしているわけではありません - これは date.isoformat() の逆演算を意図して実装されています。

バージョン 3.7 で追加.

以下にクラス属性を示します:

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 はから date1 から timedelta.days 日移動した日付です。(1)
date2 = date1 - timedelta | date2 + timedelta == date1 であるような日付 date2 を計算します。(2)
timedelta = date1 - date2 | (3)
date1 < date2 | date1 が時刻として date2 よりも前を表す場合に、date1 は date2 よりも小さいと見なされます。(4)

注釈:

  1. date2 は timedelta.days > 0 の場合進む方向に、 timedelta.days < 0 の場合戻る方向に移動します。演算後は、 date2 - date1 == timedelta.days となります。 timedelta.seconds および timedelta.microseconds は無視されます。 date2.year が MINYEAR になってしまったり、 MAXYEAR より大きくなってしまう場合には OverflowError が送出されます。
  2. timedelta.seconds と timedelta.microseconds は無視されます。
  3. この演算は厳密で、オーバフローしません。timedelta.seconds および timedelta.microseconds は 0 で、演算後には date2 + timedelta == date1 となります。
  4. 言い換えると、 date1 < date2 は date1.toordinal() < date2.toordinal() と同等です。 日付の比較は、比較相手が date オブジェクトでない場合には、 TypeError を送出します。 ただし、 比較相手に timetuple() 属性がある場合は、 NotImplemented が代わりに送出されます。 このフックによって、他の種類の日付オブジェクトに、違う型どうしの比較処理を実装できる可能性が生まれます。 相手が timetuple() 属性を持っていない場合に date と違う型のオブジェクトと比較すると、 == または != の比較でない限り TypeError が送出されます。 後者の場合では、それぞれ False および True が返されます。

date オブジェクトは辞書のキーとして用いることができます。ブール演算コンテキストでは、全ての date オブジェクトは真であるとみなされます。

インスタンスメソッド:

date.replace(year=self.year, month=self.month, day=self.day)

キーワード引数で指定されたパラメタが置き換えられることを除き、同じ値を持つ date オブジェクトを返します。例えば、d == date(2002, 12, 31) とすると、d.replace(day=26) == 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)) ただし yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 が 1月1日に 1 で始まる現在の年の日を表す。

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()

3 要素のタプル (ISO 年、ISO 週番号、ISO 曜日) を返します。

ISO カレンダーはグレゴリオ暦の変種として広く用いられています。 細かい説明については https://www.staff.science.uu.nl/~gent0113/calendar/isocalendar.htm を参照してください。

ISO 年は完全な週が 52 または 53 週あり、週は月曜から始まって日曜に終わります。ISO 年でのある年における最初の週は、その年の木曜日を含む最初の (グレゴリオ暦での) 週となります。この週は週番号 1 と呼ばれ、この木曜日での ISO 年はグレゴリオ暦における年と等しくなります。

例えば、2004 年は木曜日から始まるため、ISO 年の最初の週は 2003 年 12 月 29 日、月曜日から始まり、2004 年 1 月 4 日、日曜日に終わります。従って、date(2003, 12, 29).isocalendar() == (2004, 1, 1) であり、かつ date(2004, 1, 4).isocalendar() == (2004, 1, 7) となります。

date.isoformat()

ISO 8601 形式、 'YYYY-MM-DD' の日付を表す文字列を返します。例えば、date(2002, 12, 4).isoformat() == '2002-12-04' となります。

date.__str__()

date オブジェクト d において、str(d) は d.isoformat() と等価です。

date.ctime()

日付を表す文字列を、例えば date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002' のようにして返します。ネイティブの C 関数 ctime() (time.ctime() はこの関数を呼び出しますが、 date.ctime() は呼び出しません) が C 標準に準拠しているプラットフォームでは、 d.ctime() は time.ctime(time.mktime(d.timetuple())) と等価です。

date.strftime(format)

明示的な書式文字列で制御された、日付を表現する文字列を返します。 時間、分、秒を表す書式化コードは値 0 になります。完全な書式化ディレクティブのリストについては strftime() と strptime() の振る舞い を参照してください。

date.__format__(format)

date.strftime`と等価です。これにより、 :meth:`str.format() の使用時に date の書式文字列を指定できます。書式化コードの完全なリストについては strftime() と strptime() の振る舞い を参照してください。

イベントまでの日数を数える例を示します:

>>> 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)
>>> 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 )
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'

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)

年、月、および日の引数は必須です。 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()

現在のローカルな datetime を返します。 tzinfo は None です。 この関数は datetime.fromtimestamp(time.time()) と等価です。 now(), fromtimestamp() も参照してください。

classmethod datetime.now(tz=None)

現在のローカルな日付および時刻を返します。オプションの引数 tz が None であるか指定されていない場合、このメソッドは today() と同様ですが、可能ならば time.time() タイムスタンプを通じて得ることができる、より高い精度で時刻を提供します (例えば、プラットフォームが C 関数 gettimeofday() をサポートする場合には可能なことがあります)。

tz が None でない場合、 tz は tzinfo のサブクラスのインスタンスでなければならず、現在の日付および時刻は tz のタイムゾーンに変換されます。 この場合、結果は tz.fromutc(datetime.utcnow().replace(tzinfo=tz)) と等価になります。 today(), utcnow() も参照してください。

classmethod datetime.utcnow()

tzinfo が None である現在の UTC の日付および時刻を返します。 これは now() と似ていますが、 naive な datetime オブジェクトとして現在の UTC 日付および時刻を返します。 aware な現在の UTC datetime は datetime.now(timezone.utc) を呼び出すことで取得できます。 now() も参照してください。

classmethod datetime.fromtimestamp(timestamp, tz=None)

time.time() が返すような、 POSIX タイムスタンプに対応するローカルな日付と時刻を返します。オプションの引数 tz が None であるか、指定されていない場合、タイムスタンプはプラットフォームのローカルな日付および時刻に変換され、返される datetime オブジェクトは naive なものになります。

tz が None でない場合、 tz は tzinfo のサブクラスのインスタンスでなければならず、現在の日付および時刻は tz のタイムゾーンに変換されます。 この場合、結果は tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(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 タイムスタンプに対応する UTC の datetime で、 tzinfo が None に設定されたものを返します。 タイムスタンプがプラットフォームの C 関数 gmtime() でサポートされている範囲を超えている場合には 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 を含みます) をサポートします。

バージョン 3.3 で変更: timestamp がプラットフォームの C 関数 gmtime() のサポートする値の範囲から外れていた場合、 ValueError ではなく OverflowError を送出するようになりました。 gmtime() の呼び出し失敗で ValueError ではなく OSError を送出するようになりました。

classmethod datetime.fromordinal(ordinal)

1 年 1 月 1 日を序数 1 とする早期グレゴリオ暦序数に対応する datetime オブジェクトを返します。 1 <= ordinal <= datetime.max.toordinal() でなければ ValueError が送出されます。 返されるオブジェクトの時間、分、秒、およびマイクロ秒はすべて 0 で、 tzinfo は None となっています。

classmethod datetime.combine(date, time, tzinfo=self.tzinfo)

日付部分が与えられた date オブジェクトと等しく、時刻部分が与えられた time オブジェクトと等しいい新しい datetime オブジェクトを返します。 属性が与えられた場合、与えられた time の tzinfo 任意の datetime オブジェクト d で d == datetime.combine(d.date(), d.timetz()) が成立します。 date が datetime オブジェクトだった場合、その時刻部分と tzinfo 属性は無視されます。

任意の datetime オブジェクト d で d == datetime.combine(d.date(), d.timetz()) が成立します。 date が datetime オブジェクトだった場合、その datetime オブジェクトの時刻部分と tzinfo 属性は無視されます。

バージョン 3.6 で変更: tzinfo 引数が追加されました。

classmethod datetime.fromisoformat(date_string)

Return a datetime corresponding to a date_string in one of the formats emitted by date.isoformat() and datetime.isoformat(). Specifically, this function supports strings in the format(s) YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]], where * can match any single character.

ご用心

This does not support parsing arbitrary ISO 8601 strings - it is only intended as the inverse operation of datetime.isoformat().

バージョン 3.7 で追加.

classmethod datetime.strptime(date_string, format)

date_string に対応した datetime を返します。 format にしたがって構文解析されます。これは、 datetime(*(time.strptime(date_string, format)[0:6])) と等価です。 date_stringとformatが time.strptime() で構文解析できない場合や、この関数が時刻タプルを返してこない場合には ValueError を送出します。完全な書式化ディレクティブのリストについては strftime() と strptime() の振る舞い を参照してください。

以下にクラス属性を示します:

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 value 0 (1) represents the earlier (later) of the two moments with the same wall time representation.

バージョン 3.6 で追加.

サポートされている演算を以下に示します:

演算 | 結果
datetime2 = datetime1 + timedelta | (1)
datetime2 = datetime1 - timedelta | (2)
timedelta = datetime1 - datetime2 | (3)
datetime1 < datetime2 | datetime を datetime と比較します。 (4)

  1. datetime2 は datetime1 から時間 timedelta 移動したもので、 timedelta.days > 0 の場合未来へ、 timedelta.days < 0 の場合過去へ移動します。 結果は入力の datetime と同じ tzinfo 属性を持ち、演算後には datetime2 - datetime1 == timedelta となります。 datetime2.year が MINYEAR よりも小さいか、 MAXYEAR より大きい場合には OverflowError が送出されます。 入力が aware なオブジェクトの場合でもタイムゾーン修正は全く行われません。

  2. datetime2 + timedelta == datetime1 となるような datetime2 を計算します。 ちなみに、結果は入力の datetime と同じ tzinfo 属性を持ち、入力が aware だとしてもタイムゾーン修正は全く行われません。 この操作は date1 + (-timedelta) と等価ではありません。 なぜならば、 date1 - timedelta がオーバフローしない場合でも、-timedelta 単体がオーバフローする可能性があるからです。

  3. 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()) と同じになります。

  4. datetime1 が時刻として datetime2 よりも前を表す場合に、datetime1 は datetime2 よりも小さいと見なされます。

    比較の一方が naive であり、もう一方が aware の場合に、順序比較が行われると TypeError が送出されます。等価比較では、 naive インスタンスと aware インスタンスは等価になることはありません。

    比較対象が両方とも aware で、同じ tzinfo 属性を持つ場合、 tzinfo は無視され datetime だけで比較が行われます。 比較対象が両方とも aware であり、異なる tzinfo 属性を持つ場合、まず最初に (self.utcoffset() で取得できる) それぞれの UTC オフセットを引いて調整します。

    バージョン 3.3 で変更: naive な datetime インスタンスと aware な datetime インスタンスの等価比較では TypeError は送出されません。

    注釈

    型混合の比較がデフォルトのオブジェクトアドレス比較となってしまうのを抑止するために、被演算子のもう一方が datetime オブジェクトと異なる型のオブジェクトの場合には TypeError が送出されます。しかしながら、被比較演算子のもう一方が timetuple() 属性を持つ場合には NotImplemented が返されます。このフックにより、他種の日付オブジェクトに型混合比較を実装するチャンスを与えています。そうでない場合, datetime オブジェクトと異なる型のオブジェクトが比較されると、比較演算子が == または != でないかぎり TypeError が送出されます。後者の場合、それぞれ False または True を返します。

datetime オブジェクトは辞書のキーとして用いることができます。ブール演算コンテキストでは、全ての datetime オブジェクトは真であるとみなされます。

インスタンスメソッド:

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()

If tzinfo is None, returns None, else returns self.tzinfo.utcoffset(self), and raises an exception if the latter doesn't return None or a timedelta object with magnitude less than one day.

バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

datetime.dst()

If tzinfo is None, returns None, else returns self.tzinfo.dst(self), and raises an exception if the latter doesn't return None or a timedelta object with magnitude less than one day.

バージョン 3.7 で変更: The DST offset is not restricted to a whole number of minutes.

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)) と等価です。 ここで yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 はその年の1月1日を 1 としたときのその日の位置です。 返されるタプルの tm_isdst フラグは dst() メソッドに従って設定されます: tzinfo が None か dst() が None を返す場合、 tm_isdst は -1 に設定されます; そうでない場合、 dst() がゼロでない値を返すと tm_isdst は 1 となります; それ以外の場合には tm_isdst は 0 に設定されます。

datetime.utctimetuple()

datetime インスタンス d が naive の場合、このメソッドは d.timetuple() と同じであり、 d.dst() の返す内容にかかわらず tm_isdst が 0 に強制される点だけが異なります。 DST が UTC 時刻に影響を及ぼすことは決してありません。

d が aware だった場合、 d は d.utcoffset() を引いて UTC 時刻に正規化され、その時刻が time.struct_time として返されます。 tm_isdst は 0 に強制されます。 d.year が MINYEAR もしくは MAXYEAR であり、 UTC 時刻への調整により適切な年の範囲を越えた場合、 OverflowError が送出される可能性があることに注意してください。

datetime.toordinal()

先発グレゴリオ暦における日付序数を返します。self.date().toordinal() と同じです。

datetime.timestamp()

datetime インスタンスに対応する POSIX タイムスタンプを返します。 返り値は time.time() で返される値に近い float です。

このメソッドでは naive な datetime インスタンスはローカル時刻とし、プラットフォームの C 関数 mktime() に頼って変換を行います。 datetime は多くのプラットフォームの mktime() より広い範囲の値をサポートしているので、遥か過去の時刻や遥か未来の時刻に対し、このメソッドは OverflowError を送出するかもしれません。

aware な datetime インスタンスに対しては以下のように返り値が計算されます:

(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

バージョン 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()

3 要素のタプル (ISO 年、ISO 週番号、ISO 曜日) を返します。self.date().isocalendar() と等価です。

datetime.isoformat(sep='T', timespec='auto')

Return a string representing the date and time in ISO 8601 format, YYYY-MM-DDTHH:MM:SS.ffffff or, if microsecond is 0, YYYY-MM-DDTHH:MM:SS

If utcoffset() does not return None, a string is appended, giving the UTC offset: YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]] or, if microsecond is 0 YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]].

オプションの引数 sep (デフォルトでは 'T' です) は 1 文字のセパレータで、結果の文字列の日付と時刻の間に置かれます。例えば、

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     def utcoffset(self, dt): return timedelta(minutes=-399)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'

オプション引数 timespec は、含める追加の時間の要素の数を指定します(デフォルトでは 'auto' です)。以下の内一つを指定してください。

  • 'auto': microsecond が0である場合 'seconds' と等しく、そうでない場合は 'microseconds' と等しくなります。
  • 'hours': hour を2文字の HH 書式で含めます。
  • 'minutes': hour と minute を HH:MM の書式で含めます。
  • 'seconds': hour と minute を HH:MM の書式で含めます。
  • 'milliseconds': 全ての時間を含みますが、小数第二位をミリ秒に切り捨てます。 HH:MM:SS.sss の書式で表現します。
  • 'microseconds': Include full time in HH:MM:SS.ffffff format.

注釈

除外された要素は丸め込みではなく、切り捨てされます。

不正な timespec 引数には ValueError があげられます。

>>> from datetime import datetime
>>> datetime.now().isoformat(timespec='minutes')   # doctest: +SKIP
'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()

日付を表す文字列を、例えば datetime(2002, 12, 4, 20, 30, 40).ctime() == 'Wed Dec  4 20:30:40 2002' のようにして返します。ネイティブの C 関数 ctime() (time.ctime() はこの関数を呼び出しますが、 datetime.ctime() は呼び出しません) が C 標準に準拠しているプラットフォームでは、 d.ctime() は time.ctime(time.mktime(d.timetuple())) と等価です。

datetime.strftime(format)

明示的な書式文字列で制御された、日付および時刻を表現する文字列を返します。完全な書式化ディレクティブのリストについては strftime() と strptime() の振る舞い を参照してください。

datetime.__format__(format)

date.strftime`と等価です。これにより、 :meth:`str.format() の使用時に datetime の書式文字列を指定できます。書式化コードの完全なリストについては strftime() と strptime() の振る舞い を参照してください。

datetime オブジェクトを使う例:

>>> from datetime import datetime, date, time
>>> # 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() or datetime.utcnow()
>>> datetime.now()
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.utcnow()
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
>>> # 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 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.'

datetime を tzinfo と組み合わせて使う:

>>> from datetime import timedelta, datetime, tzinfo
>>> class GMT1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1) + self.dst(dt)
...     def dst(self, dt):
...         # DST starts last Sunday in March
...         d = datetime(dt.year, 4, 1)   # ends last Sunday in October
...         self.dston = d - timedelta(days=d.weekday() + 1)
...         d = datetime(dt.year, 11, 1)
...         self.dstoff = d - timedelta(days=d.weekday() + 1)
...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
...             return timedelta(hours=1)
...         else:
...             return timedelta(0)
...     def tzname(self,dt):
...          return "GMT +1"
...
>>> class GMT2(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=2) + self.dst(dt)
...     def dst(self, dt):
...         d = datetime(dt.year, 4, 1)
...         self.dston = d - timedelta(days=d.weekday() + 1)
...         d = datetime(dt.year, 11, 1)
...         self.dstoff = d - timedelta(days=d.weekday() + 1)
...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
...             return timedelta(hours=1)
...         else:
...             return timedelta(0)
...     def tzname(self,dt):
...         return "GMT +2"
...
>>> gmt1 = GMT1()
>>> # Daylight Saving Time
>>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1)
>>> dt1.dst()
datetime.timedelta(0)
>>> dt1.utcoffset()
datetime.timedelta(seconds=3600)
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
>>> dt2.dst()
datetime.timedelta(seconds=3600)
>>> dt2.utcoffset()
datetime.timedelta(seconds=7200)
>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(GMT2())
>>> dt3     # doctest: +ELLIPSIS
datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)
>>> dt2     # doctest: +ELLIPSIS
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)
>>> dt2.utctimetuple() == dt3.utctimetuple()
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].

引数がこれらの範囲外にある場合、 ValueError が送出されます。 tzinfo のデフォルト値が None である以外のデフォルト値は 0 です。

以下にクラス属性を示します:

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 value 0 (1) represents the earlier (later) of the two moments with the same wall time representation.

バージョン 3.6 で追加.

サポートされている演算を以下に示します:

  • time と time の比較では、 a が b より前の時刻だった場合 a が b より小さいとされます。比較の一方が naive であり、もう一方が aware の場合に、順序比較が行われると TypeError が送出されます。等価比較では、 naive インスタンスと aware インスタンスは等価になることはありません。

    比較対象が両方とも aware であり、同じ tzinfo 属性を持つ場合、 tzinfo は無視され datetime だけで比較が行われます。 比較対象が両方とも aware であり、異なる tzinfo 属性を持つ場合、まず最初に (self.utcoffset() で取得できる) それぞれの UTC オフセットを引いて調整します。 異なる型どうしの比較がデフォルトのオブジェクトアドレス比較となってしまうのを防ぐために、 time オブジェクトを異なる型のオブジェクトと比較すると、比較演算子が == または != でないかぎり TypeError が送出されます。 比較演算子が == または != である場合、それぞれ False または True を返します。

    バージョン 3.3 で変更: naive な time インスタンスと aware な time インスタンスの等価比較では、 TypeError は送出されません。

  • ハッシュ化、辞書のキーとしての利用

  • 効率的な pickle 化

ブール値の文脈では、 time オブジェクトは常に真とみなされます。

バージョン 3.5 で変更: Python 3.5 以前は、 time オブジェクトは UTC で深夜を表すときに偽とみなされていました。 この挙動は分かりにくく、エラーの元となると考えられ、Python 3.5 で削除されました。 全詳細については bpo-13936 を参照してください。

Other constructor:

classmethod time.fromisoformat(time_string)

Return a time corresponding to a time_string in one of the formats emitted by time.isoformat(). Specifically, this function supports strings in the format(s) HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]].

ご用心

This does not support parsing arbitrary ISO 8601 strings - it is only intended as the inverse operation of time.isoformat().

バージョン 3.7 で追加.

インスタンスメソッド:

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')

Return a string representing the time in ISO 8601 format, HH:MM:SS.ffffff or, if microsecond is 0, HH:MM:SS If utcoffset() does not return None, a string is appended, giving the UTC offset: HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]] or, if self.microsecond is 0, 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 を HH:MM の書式で含めます。
  • 'milliseconds': 全ての時間を含みますが、小数第二位をミリ秒に切り捨てます。 HH:MM:SS.sss の書式で表現します。
  • 'microseconds': Include full time in HH:MM:SS.ffffff format.

注釈

除外された要素は丸め込みではなく、切り捨てされます。

不正な 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.__format__(format)

time.strftime`と等価です。これにより、 :meth:`str.format() の使用時に time の書式文字列を指定できます。書式化コードの完全なリストについては strftime() と strptime() の振る舞い を参照してください。

time.utcoffset()

If tzinfo is None, returns None, else returns self.tzinfo.utcoffset(None), and raises an exception if the latter doesn't return None or a timedelta object with magnitude less than one day.

バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

time.dst()

If tzinfo is None, returns None, else returns self.tzinfo.dst(None), and raises an exception if the latter doesn't return None, or a timedelta object with magnitude less than one day.

バージョン 3.7 で変更: The DST offset is not restricted to a whole number of minutes.

time.tzname()

tzinfo が None の場合 None を返し、そうでない場合には self.tzinfo.tzname(None) を返します。 後者の式が None か文字列オブジェクトのいずれかを返さない場合には例外を送出します。

例:

>>> from datetime import time, tzinfo, timedelta
>>> class GMT1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "Europe/Prague"
...
>>> t = time(12, 10, 30, tzinfo=GMT1())
>>> t                               # doctest: +ELLIPSIS
datetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>)
>>> gmt = GMT1()
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'Europe/Prague'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 Europe/Prague'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'

tzinfo オブジェクト

class datetime.tzinfo

このクラスは抽象基底クラスで、直接インスタンス化すべきでないことを意味します。 具象サブクラスを作成し、(少なくとも) 使いたい datetime のメソッドが必要とする tzinfo のメソッドを実装する必要があります。 datetime モジュールは tzinfo のシンプルな具象サブクラス timezone を提供します。 これは UTC そのものか北アメリカの EST と EDT のような UTC からの固定されたオフセットを持つタイムゾーンを表せます。

tzinfo (の具体的なサブクラス) のインスタンスは datetime および time オブジェクトのコンストラクタに渡すことができます。後者のオブジェクトでは、データ属性をローカル時刻におけるものとして見ており、 tzinfo オブジェクトはローカル時刻の UTC からのオフセット、タイムゾーンの名前、 DST オフセットを、渡された日付および時刻オブジェクトからの相対で示すためのメソッドを提供します。

pickle 化についての特殊な要求事項: tzinfo のサブクラスは引数なしで呼び出すことのできる __init__() メソッドを持たなければなりません。そうでなければ、 pickle 化することはできますがおそらく unpickle 化することはできないでしょう。これは技術的な側面からの要求であり、将来緩和されるかもしれません。

tzinfo の具体的なサブクラスでは、以下のメソッドを実装する必要があります。厳密にどのメソッドが必要なのかは、 aware な datetime オブジェクトがこのサブクラスのインスタンスをどのように使うかに依存します。不確かならば、単に全てを実装してください。

tzinfo.utcoffset(dt)

Return offset of local time from UTC, as a timedelta object that is positive east of UTC. If local time is west of UTC, this should be negative. Note that this is intended to be the total offset from UTC; for example, if a tzinfo object represents both time zone and DST adjustments, utcoffset() should return their sum. If the UTC offset isn't known, return None. Else the value returned must be a timedelta object strictly between -timedelta(hours=24) and timedelta(hours=24) (the magnitude of the offset must be less than one day). Most implementations of utcoffset() will probably look like one of these two:

return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class

utcoffset() が None を返さない場合、 dst() も None を返してはなりません。

utcoffset() のデフォルトの実装は NotImplementedError を送出します。

バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

tzinfo.dst(dt)

Return the daylight saving time (DST) adjustment, as a timedelta object or None if DST information isn't known. Return timedelta(0) if DST is not in effect. If DST is in effect, return the offset as a timedelta object (see utcoffset() for details). Note that DST offset, if applicable, has already been added to the UTC offset returned by utcoffset(), so there's no need to consult dst() unless you're interested in obtaining DST info separately. For example, datetime.timetuple() calls its tzinfo attribute's dst() method to determine how the tm_isdst flag should be set, and tzinfo.fromutc() calls dst() to account for DST changes when crossing time zones.

標準および夏時間の両方をモデル化している tzinfo サブクラスのインスタンス tz は以下の式:

tz.utcoffset(dt) - tz.dst(dt)

が、 dt.tzinfo == tz 全ての datetime オブジェクト dt について常に同じ結果を返さなければならないという点で、一貫性を持っていなければなりません。正常に実装された tzinfo のサブクラスでは、この式はタイムゾーンにおける "標準オフセット (standard offset)" を表し、特定の日や時刻の事情ではなく地理的な位置にのみ依存していなくてはなりません。 datetime.astimezone() の実装はこの事実に依存していますが、違反を検出することができません; 正しく実装するのはプログラマの責任です。 tzinfo のサブクラスでこれを保証することができない場合、 tzinfo.fromutc() の実装をオーバライドして、 astimezone() に関わらず正しく動作するようにしてもかまいません。

ほとんどの 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.  Then

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)

デフォルトの dst() 実装は NotImplementedError を送出します。

バージョン 3.7 で変更: The DST offset is not restricted to a whole number of minutes.

tzinfo.tzname(dt)

datetime オブジェクト dt に対応するタイムゾーン名を文字列で返します。 datetime モジュールでは文字列名について何も定義しておらず、特に何かを意味するといった要求仕様もまったくありません。例えば、 "GMT","UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" は全て有効な応答となります。文字列名が未知の場合には None を返してください。 tzinfo のサブクラスでは、特に, tzinfo クラスが夏時間について記述している場合のように、渡された dt の特定の値によって異なった名前を返したい場合があるため、文字列値ではなくメソッドとなっていることに注意してください。

デフォルトの 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

In the following tzinfo_examples.py file there are some examples of tzinfo classes:

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
# http://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")

標準時間 (standard time) および夏時間 (daylight time) の両方を記述している tzinfo のサブクラスでは、回避不能の難解な問題が年に 2 度あるので注意してください。具体的な例として、東部アメリカ時刻 (US Eastern, UTC -5000) を考えます。 EDT は 3 月の第二日曜日の 1:59 (EST) 以後に開始し、11 月の最初の日曜日の 1:59 (EDT) に終了します:

  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 の形で表現される壁時間は意味をなさないので、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() は二つの 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

Note that the datetime instances that differ only by the value of the fold attribute are considered equal in comparisons.

壁時間に関する曖昧さは、明示的に fold 属性を検証するか、 timezone が使用されたハイブリッドな tzinfo サブクラスか、そのほかの絶対時間差を示す tzinfo サブクラス(EST (-5 時間の絶対時間差) のみを表すクラスや、 EDT (-4 時間の絶対時間差) のみを表すクラス)を使用すると回避できます。 このような曖昧さを許容できないアプリケーションは、このような手法によって回避すべきです。

参考

dateutil.tz

標準ライブラリにはUTCからの任意の固定オフセットを扱うために、 timezone クラスが、 UTCタイムゾーンのインスタンスとして、 timezone.utc があります。

dateutil.tz ライブラリは Python に IANA タイムゾーンデータベース (オルソンデータベースとしても知られています) を持ってきます、そしてそれの利用が推奨されます。

IANA タイムゾーンデータベース
(しばしば tz、tzdata や zoneinfo と呼ばれる) タイムゾーンデータベースはコードとデータを保持しており、それらは地球全体にわたる多くの代表的な場所のローカル時刻の履歴を表しています。政治団体によるタイムゾーンの境界、UTC オフセット、夏時間のルールの変更を反映するため、定期的にデータベースが更新されます。

timezone オブジェクト

timezone クラスは tzinfo のサブクラスで、各インスタンスは UTC からの固定されたオフセットで定義されたタイムゾーンを表しています。このクラスのオブジェクトは、一年のうち異なる日に異なるオフセットが使われていたり、常用時 (civil time) に歴史的な変化が起きた場所のタイムゾーン情報を表すのには使えないので注意してください。

class datetime.timezone(offset, name=None)

The offset argument must be specified as a timedelta object representing the difference between the local time and UTC. It must be strictly between -timedelta(hours=24) and timedelta(hours=24), otherwise ValueError is raised.

The name argument is optional. If specified it must be a string that will be used as the value returned by the datetime.tzname() method.

バージョン 3.2 で追加.

バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

timezone.utcoffset(dt)

timezone インスタンスの作成時に指定された固定の値を返します。 dt 引数は無視されます。返り値は、ローカル時刻と UTC の差分に等しい timedelta インスタンスです。

バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

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) メソッドをサポートしています。大雑把にいうと、 d.strftime(fmt) は time モジュールの time.strftime(fmt, d.timetuple()) のように動作します。ただし全てのオブジェクトが timetuple() メソッドをサポートしているわけではありません。

逆に datetime.strptime() クラスメソッドは日付や時刻に対応する書式文字列から datetime オブジェクトを生成します。 datetime.strptime(date_string, format) は datetime(*(time.strptime(date_string, format)[0:6])) と等価です。ただし、その書式に小数秒以下の要素またはタイムゾーン情報が含まれる、``datetime.strptime``ではサポートされるが``time.strptime``ではサポートされないような場合はその限りではありません。

time オブジェクトでは、年、月、日の値がないため、それらの書式化コードを使うことができません。無理矢理使った場合、年は 1900 に置き換えられ、月と日は 1 に置き換えられます。

date オブジェクトでは、時、分、秒、マイクロ秒の値がないため、それらの書式化コードを使うことができません。無理矢理使った場合、これらの値は 0 に置き換えられます。

Python はプラットフォームの C ライブラリの strftime() 関数を呼び出していて、プラットフォームごとにその実装が異なるのはよくあることなので、サポートされるフォーマット記号全体はプラットフォームごとに様々です。プラットフォームでサポートされているフォーマット記号全体を見るには、 strftime(3) のドキュメントを参照してください。

以下のリストはC標準(1989年版)が要求する全ての書式化コードで、標準C実装があれば全ての環境で動作します。1999 年版の 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 |
%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 |
%y | 0埋めした10進数で表記した世紀無しの年。 | 00, 01, ..., 99 |
%Y | 西暦 (4桁) の 10 進表記を表します。 | 0001, 0002, ..., 2013, 2014, ..., 9998, 9999 | (2)
%H | 0埋めした10進数で表記した時 (24時間表記)。 | 00, 01, ..., 23 |
%I | 0埋めした10進数で表記した時 (12時間表記)。 | 01, 02, ..., 12 |
%p | ロケールの AM もしくは PM と等価な文字列になります。 | AM, PM (en_US); am, pm (de_DE) | (1), (3)
%M | 0埋めした10進数で表記した分。 | 00, 01, ..., 59 |
%S | 0埋めした10進数で表記した秒。 | 00, 01, ..., 59 | (4)
%f | 10進数で表記したマイクロ秒 (左側から0埋めされます)。 | 000000, 000001, ..., 999999 | (5)
%z | UTC offset in the form ±HHMM[SS[.ffffff]] (empty string if the object is naive). | (empty), +0000, -0400, +1030, +063415, -030712.345216 | (6)
%Z | タイムゾーンの名前を表示します (オブジェクトがnaiveであれば空文字列)。 | (空文字列), UTC, EST, CST |
%j | 0埋めした10進数で表記した年中の日にち。 | 001, 002, ..., 366 |
%U | 0埋めした10進数で表記した年中の週番号 (週の始まりは日曜日とする)。新年の最初の日曜日に先立つ日は 0週に属するとします。 | 00, 01, ..., 53 | (7)
%W | 0埋めした10進数で表記した年中の週番号 (週の始まりは月曜日とする)。新年の最初の月曜日に先立つ日は 0週に属するとします。 | 00, 01, ..., 53 | (7)
%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の日付値に対応しています。これらが strftime() メソッドと一緒に使用された場合、すべてのプラットフォームで利用できるわけではありません。 ISO 8601 の年コードおよびISO 8601 週コードは、上記の年および週ナンバーコードと互換性がありません。不完全またはあいまいなISO 8601ディレクティブで strptime() を呼び出すと、 ValueError が送出されます。

ディレクティブ | 意味 | 使用例 | 注釈
%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)

バージョン 3.6 で追加: %G, %u および %V が追加されました。

注釈:

  1. フォーマットは現在のロケールに依存するので、出力値について何か仮定するときは注意すべきです。フィールドの順序は様々で (例えば、"月/日/年" と "日/月/年") 、出力はロケールのデフォルトエンコーディングでエンコードされた Unicode 文字列を含むかもしれません (例えば、現在のロケールが ja_JP だった場合、デフォルトエンコーディングは eucJP 、 SJIS 、 utf-8 のいずれかになりえます。 locale.getlocale() を使って現在のロケールのエンコーディングを確認します) 。

  2. strptime() メソッドは [1, 9999] の範囲の年数全てを構文解析できますが、 year < 1000 の範囲の年数は 0 埋めされた 4 桁の数字でなければなりません。

    バージョン 3.2 で変更: 以前のバージョンでは、 strftime() メソッドは years >= 1900 の範囲の年数しか扱えませんでした。

    バージョン 3.3 で変更: バージョン 3.2 では、 strftime() メソッドは years >= 1000 の範囲の年数しか扱えませんでした。

  3. strptime() メソッドと共に使われた場合、 %p 指定子は出力の時間フィールドのみに影響し、 %I 指定子が使われたかのように振る舞います。

  4. time モジュールと違い、 datetime モジュールはうるう秒をサポートしていません。

  5. strptime() メソッドと共に使われた場合、 %f 指定子は 1 桁から 6 桁の数字を受け付け、右側から 0 埋めされます。 %f は C 標準規格の書式セットに拡張されます。

  6. naive オブジェクトでは、書式化コード %z および %Z は空文字列に置き換えられます。

    aware オブジェクトでは以下のようになります:

    %z

    utcoffset() is transformed into a string of the form ±HHMM[SS[.ffffff]], where HH is a 2-digit string giving the number of UTC offset hours, MM is a 2-digit string giving the number of UTC offset minutes, SS is a 2-digit string giving the number of UTC offset seconds and ffffff is a 6-digit string giving the number of UTC offset microseconds. The ffffff part is omitted when the offset is a whole number of seconds and both the ffffff and the SS part is omitted when the offset is a whole number of minutes. For example, if utcoffset() returns timedelta(hours=-3, minutes=-30), %z is replaced with the string '-0330'.

    バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

    バージョン 3.7 で変更: When the %z directive is provided to the strptime() method, the UTC offsets can have a colon as a separator between hours, minutes and seconds. For example, '+01:00:00' will be parsed as an offset of one hour. In addition, providing 'Z' is identical to '+00:00'.

    %Z

    tzname() が None を返した場合、 %Z は空文字列に置き換わります。そうでない場合、 %Z は返された値に置き換わりますが、 これは文字列でなければなりません。

    バージョン 3.2 で変更: %z 指定子が strptime() メソッドに与えられた場合、 aware な datetime オブジェクトが作成されます。返り値の tzinfo は timezone インスタンスになっています。

  7. strptime() メソッドと共に使われた場合、 %U と %W 指定子は、曜日と年(%Y)が指定された場合の計算でのみ使われます。

  8. %U と %W と同様です。 %V は曜日と ISO year (%G)が strptime() 書式内で指定された場合に計算でのみ使われます。 %G と %Y は互いに完全な互換性を持たないことにも注意してください。

脚注

[1] もし相対性理論の効果を無視するならば、ですが

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ型 »


calendar --- 一般的なカレンダーに関する関数群

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

calendar --- 一般的なカレンダーに関する関数群

ソースコード: Lib/calendar.py

このモジュールは Unix の cal プログラムのようなカレンダー出力を行い、それに加えてカレンダーに関する有益な関数群を提供します。標準ではこれらのカレンダーは（ヨーロッパの慣例に従って）月曜日を週の始まりとし、日曜日を最後の日としています。 setfirstweekday() を用いることで、日曜日(6)や他の曜日を週の始まりに設定することができます。日付を表す引数は整数値で与えます。関連する機能として、 datetime と time モジュールも参照してください。

The functions and classes defined in this module use an idealized calendar, the current Gregorian calendar extended indefinitely in both directions. This matches the definition of the "proleptic Gregorian" calendar in Dershowitz and Reingold's book "Calendrical Calculations", where it's the base calendar for all computations. Zero and negative years are interpreted as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is 2 BC, and so on.

class calendar.Calendar(firstweekday=0)

Calendar オブジェクトを作ります。 firstweekday は整数で週の始まりの曜日を指定するものです。 0 が月曜(デフォルト)、 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.

バージョン 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.

バージョン 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 instances have the following methods:

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 には出力に使うエンコーディングを指定します (デフォルトではシステムデフォルトのエンコーディングです)。

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.

バージョン 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.

バージョン 3.7 で追加.

cssclass_month_head

The month's head CSS class (used by formatmonthname()). The default value is "month".

バージョン 3.7 で追加.

cssclass_month

The CSS class for the whole month's table (used by formatmonth()). The default value is "month".

バージョン 3.7 で追加.

cssclass_year

The CSS class for the whole year's table of tables (used by formatyear()). The default value is "year".

バージョン 3.7 で追加.

cssclass_year_head

The CSS class for the table head for the whole year (used by formatyear()). The default value is "year".

バージョン 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)

この TextCalendar のサブクラスではコンストラクタにロケール名を渡すことができ、メソッドの返り値で月や曜日が指定されたロケールのものになります。このロケールがエンコーディングを含む場合には、月や曜日の入った文字列はユニコードとして返されます。

class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)

この HTMLCalendar のサブクラスではコンストラクタにロケール名を渡すことができ、メソッドの返り値で月や曜日が指定されたロケールのものになります。このロケールがエンコーディングを含む場合には、月や曜日の入った文字列はユニコードとして返されます。

注釈

これら2つのクラスの formatweekday() と formatmonthname() メソッドは、一時的に現在の locale を指定された locale に変更します。現在の locale はプロセス全体に影響するので、これらはスレッドセーフではありません。

単純なテキストのカレンダーに関して、このモジュールには以下のような関数が提供されています。

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)

TextCalendar の formatmonth() メソッドを利用して、ひと月分のカレンダーを複数行の文字列で返します。

calendar.prcal(year, w=0, l=0, c=6, m=3)

calendar() 関数で返される一年間のカレンダーを出力します。

calendar.calendar(year, w=2, l=1, c=6, m=3)

TextCalendar の formatyear() メソッドを利用して、 3列からなる一年間のカレンダーを複数行の文字列で返します。

calendar.timegm(tuple)

カレンダーと直接は関係無いが、 time モジュールの gmtime() 関数が返す形式の時刻を表すタプルを引数に取り、1970 を基点とするエポック時刻で POSIX エンコーディングであると仮定して、対応する Unix タイムスタンプの値を返します。実際には、 time.gmtime() と timegm() はお互いの逆関数です。

calendar モジュールの以下のデータ属性を利用することができます:

calendar.day_name

現在のロケールでの曜日を表す配列です。

calendar.day_abbr

現在のロケールでの短縮された曜日を表す配列です。

calendar.month_name

現在のロケールでの月の名を表す配列です。この配列は通常の約束事に従って、1月を数字の 1 で表しますので、長さが 13 ある代わりに month_name[0] が空文字列になります。

calendar.month_abbr

現在のロケールでの短縮された月の名を表す配列です。この配列は通常の約束事に従って、1月を数字の 1 で表しますので、長さが 13 ある代わりに month_abbr[0] が空文字列になります。

参考

datetime モジュール
time モジュールと似た機能を持った日付と時間用のオブジェクト指向インタフェース。
time モジュール
時間に関連した低水準の関数群。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ型 »


collections --- コンテナデータ型

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

collections --- コンテナデータ型

ソースコード: Lib/collections/__init__.py

このモジュールは、汎用の Python 組み込みコンテナ dict, list, set, および tuple に代わる、特殊なコンテナデータ型を実装しています。

namedtuple() | 名前付きフィールドを持つタプルのサブクラスを作成するファクトリ関数
deque | 両端における append や pop を高速に行えるリスト風のコンテナ
ChainMap | 複数のマッピングの一つのビューを作成する辞書風のクラス
Counter | ハッシュ可能なオブジェクトを数え上げる辞書のサブクラス
OrderedDict | 項目が追加された順序を記憶する辞書のサブクラス
defaultdict | ファクトリ関数を呼び出して存在しない値を供給する辞書のサブクラス
UserDict | 辞書のサブクラス化を簡単にする辞書オブジェクトのラッパ
UserList | リストのサブクラス化を簡単にするリストオブジェクトのラッパ
UserString | 文字列のサブクラス化を簡単にする文字列オブジェクトのラッパ

バージョン 3.3 で変更: Moved コレクション抽象基底クラス to the collections.abc module. For backwards compatibility, they continue to be visible in this module through Python 3.7. Subsequently, they will be removed entirely.

ChainMap オブジェクト

バージョン 3.3 で追加.

ChainMap クラスは、複数のマッピングを素早く連結し、一つの単位として扱うために提供されています。これはたいてい、新しい辞書を作成して update() を繰り返すよりも早いです。

このクラスはネストされたスコープをシミュレートするのに使え、テンプレート化に便利です。

class collections.ChainMap(*maps)

ChainMap は、複数の辞書やその他のマッピングをまとめて、一つの、更新可能なビューを作成します。 maps が指定されないなら、一つの空辞書が与えられますから、新しいチェーンは必ず一つ以上のマッピングをもちます。

根底のマッピングはリストに保存されます。このリストはパブリックで、 maps 属性を使ってアクセスや更新できます。それ以外に状態はありません。

探索は、根底のマッピングをキーが見つかるまで引き続き探します。対して、書き込み、更新、削除は、最初のマッピングのみ操作します。

ChainMap は、根底のマッピングを参照によって組み込みます。ですから、根底のマッピングの一つが更新されると、その変更は ChainMap に反映されます。

通常の辞書のメソッドすべてがサポートされています。さらに、maps 属性、新しいサブコンテキストを作成するメソッド、最初のマッピング以外のすべてにアクセスするためのプロパティがあります:

maps

マッピングのユーザがアップデートできるリストです。このリストは最初に探されるものから最後に探されるものの順に並んでいます。これが唯一のソートされた状態であり、変更してマッピングが探される順番を変更できます。このリストは常に一つ以上のマッピングを含んでいなければなりません。

new_child(m=None)

新しい辞書の後ろに現在のインスタンスにある全ての辞書が続いたものを持つ、新しい ChainMap を返します。 m が指定された場合、それがマッピングのリストの先頭の新しい辞書になります; 指定されていない場合、 d.new_child() が ChainMap({}, *d.maps) と同等となるように空の辞書が使われます。このメソッドは、親マッピングを変更することなく値を更新できるサブコンテキストを作成するのに使われます。

バージョン 3.4 で変更: オプションの m 引数が追加されました。

parents

現在のインスタンスの最初のマッピング以外のすべてのマッピングを含む新しい ChainMap を返すプロパティです。これは最初のマッピングを検索から飛ばすのに便利です。使用例は nonlocal キーワードを ネストされたスコープ に使う例と似ています。この使用例はまた、組み込み super() 関数にも似ています。 d.parents への参照は ChainMap(*d.maps[1:]) と等価です。

参考

  • Enthought 社の CodeTools パッケージ に含まれる MultiContext クラス は、チェーン内のすべてのマッピングへの書き込みをサポートするオプションを持ちます。
  • Django's Context class for templating is a read-only chain of mappings. It also features pushing and popping of contexts similar to the new_child() method and the parents property.
  • Nested Contexts recipe は、書き込みその他の変更が最初のマッピングにのみ適用されるか、チェーンのすべてのマッピングに適用されるか、制御するオプションを持ちます。
  • 非常に単純化した読み出し専用バージョンの Chainmap。

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}

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']                # Get first key in the chain of contexts
d['x'] = 1            # Set value in current context
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])

A Counter is a dict subclass for counting hashable objects. It is a collection where elements are stored as dictionary keys and their counts are stored as dictionary values. Counts are allowed to be any integer value including zero or negative counts. The Counter class is similar to bags or multisets in other languages.

要素は、 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

バージョン 3.1 で追加.

カウンタオブジェクトは、すべての辞書で利用できるメソッドに加えて、次の 3 つのメソッドをサポートしています。

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])

Return a list of the n most common elements and their counts from the most common to the least. If n is omitted or None, most_common() returns all elements in the counter. Elements with equal counts are ordered arbitrarily:

>>> Counter('abracadabra').most_common(3)  # doctest: +SKIP
[('a', 5), ('r', 2), ('b', 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})

バージョン 3.2 で追加.

普通の辞書のメソッドは、以下の 2 つのメソッドがカウンタに対して異なる振る舞いをするのを除き、 Counter オブジェクトにも利用できます。

fromkeys(iterable)

このクラスメソッドは Counter オブジェクトには実装されていません。

update([iterable-or-mapping])

要素が iterable からカウントされるか、別の mapping (やカウンタ) が追加されます。 dict.update() に似ていますが、カウントを置き換えるのではなく追加します。また、 iterable には (key, value) 対のシーケンスではなく、要素のシーケンスが求められます。

Counter オブジェクトを使ったよくあるパターン:

sum(c.values())                 # 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 オブジェクトを組み合わせて多重集合 (1 以上のカウントをもつカウンタ) を作るために、いくつかの数学演算が提供されています。足し算と引き算は、対応する要素を足したり引いたりすることによってカウンタを組み合わせます。積集合と和集合は、対応するカウントの最大値と最小値を返します。それぞれの演算はカウントに符号がついた入力を受け付けますが、カウントが 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]) # doctest: +SKIP
Counter({'a': 1, 'b': 1})
>>> c | d                       # union:  max(c[x], d[x])
Counter({'a': 3, 'b': 2})

単項加算および減算は、空カウンタの加算や空カウンタからの減算へのショートカットです。

>>> c = Counter(a=2, b=-4)
>>> +c
Counter({'a': 2})
>>> -c
Counter({'b': 4})

バージョン 3.3 で追加: 単項加算、単項減算、in-place の多重集合操作のサポートが追加されました。

注釈

カウンタはもともと、推移するカウントを正の整数で表すために設計されました。しかし、他の型や負の値を必要とするユースケースを不必要に排除することがないように配慮されています。このようなユースケースの助けになるように、この節で最低限の範囲と型の制限について記述します。

  • Counter クラス自体は辞書のサブクラスで、キーと値に制限はありません。値はカウントを表す数であることを意図していますが、値フィールドに任意のものを保存 できます 。
  • The most_common() method requires only that the values be orderable.
  • For in-place operations such as c[key] += 1, the value type need only support addition and subtraction. So fractions, floats, and decimals would work and negative values are supported. The same is also true for update() and subtract() which allow negative and zero values for both inputs and outputs.
  • 多重集合メソッドは正の値を扱うユースケースに対してのみ設計されています。入力は負や 0 に出来ますが、正の値の出力のみが生成されます。型の制限はありませんが、値の型は足し算、引き算、比較をサポートしている必要があります。
  • The elements() method requires integer counts. It ignores zero and negative counts.

参考

  • Smalltalk の Bag class 。

  • Wikipedia の Multisets の項目。

  • C++ multisets の例を交えたチュートリアル。

  • 数学的な多重集合の演算とそのユースケースは、 Knuth, Donald. The Art of Computer Programming Volume II, Section 4.6.3, Exercise 19 を参照してください。

  • To enumerate all distinct multisets of a given size over a given set of elements, see 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 オブジェクトは空になります。

Deque とは、スタックとキューを一般化したものです (この名前は「デック」と発音され、これは「double-ended queue」の省略形です)。Deque はどちらの側からも append と pop が可能で、スレッドセーフでメモリ効率がよく、どちらの方向からもおよそ O(1) のパフォーマンスで実行できます。

list オブジェクトでも同様の操作を実現できますが、これは高速な固定長の操作に特化されており、内部のデータ表現形式のサイズと位置を両方変えるような pop(0) や insert(0, v) などの操作ではメモリ移動のために O(n) のコストを必要とします。

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 の浅いコピーを作成します。

バージョン 3.5 で追加.

count(x)

deque の x に等しい要素を数え上げます。

バージョン 3.2 で追加.

extend(iterable)

イテラブルな引数 iterable から得られる要素を deque の右側に追加し拡張します。

extendleft(iterable)

イテラブルな引数 iterable から得られる要素を deque の左側に追加し拡張します。注意: 左から追加した結果は、イテラブルな引数の順序とは逆になります。

index(x[, start[, stop]])

deque 内の x の位置を返します (インデックス start からインデックス stop の両端を含む範囲で)。最初のマッチを返すか、見つからない場合には ValueError を発生させます。

バージョン 3.5 で追加.

insert(i, x)

x を deque の位置 i に挿入します。

挿入によって、長さに制限のある deque の長さが maxlen を超える場合、IndexError が発生します。

バージョン 3.5 で追加.

pop()

deque の右側から要素をひとつ削除し、その要素を返します。要素がひとつも存在しない場合は IndexError を発生させます。

popleft()

deque の左側から要素をひとつ削除し、その要素を返します。要素がひとつも存在しない場合は IndexError を発生させます。

remove(value)

value の最初に現れるものを削除します。要素が見付からないない場合は ValueError を送出します。

reverse()

deque の要素をインプレースに反転し、None を返します。

バージョン 3.2 で追加.

rotate(n=1)

deque の要素を全体で n ステップだけ右にローテートします。n が負の値の場合は、左にローテートします。

deque が空でないときは、 deque をひとつ右にローテートすることは d.appendleft(d.pop()) と同じで、 deque をひとつ左にローテートすることは d.appendleft(d.popleft()) と同じです。

deque オブジェクトは読み出し専用属性も 1 つ提供しています:

maxlen

deque の最大長で、制限されていなければ None です。

バージョン 3.1 で追加.

上記に加え、deque はイテレーション、pickle、 len(d), reversed(d), copy.copy(d), copy.deepcopy(d), in 演算子による帰属検査、そして d[-1] などの添え字による参照をサポートしています。 両端への添字アクセスは O(1) ですが、中央部分へは O(n) と遅くなります。 高速なランダムアクセスが必要であればリストを使ってください。

バージョン 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
    # http://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

A round-robin scheduler can be implemented with input iterators stored in a deque. Values are yielded from the active iterator in position zero. If that iterator is exhausted, it can be removed with popleft(); otherwise, it can be cycled back to the end with the rotate() method:

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()

The rotate() method provides a way to implement deque slicing and deletion. For example, a pure Python implementation of del d[n] relies on the rotate() method to position elements to be popped:

def delete_nth(d, n):
    d.rotate(-n)
    d.popleft()
    d.rotate(n)

To implement deque slicing, use a similar approach applying rotate() to bring a target element to the left side of the deque. Remove old entries with popleft(), add new entries with extend(), and then reverse the rotation. With minor variations on that approach, it is easy to implement Forth style stack manipulations such as dup, drop, swap, over, pick, rot, and roll.

defaultdict オブジェクト

class collections.defaultdict([default_factory[, ...]])

新しいディクショナリ様のオブジェクトを返します。 defaultdict は組み込みの dict のサブクラスです。メソッドをオーバーライドし、書き込み可能なインスタンス変数を1つ追加している以外は dict クラスと同じです。同じ部分については以下では省略されています。

1つ目の引数は default_factory 属性の初期値です。デフォルトは None です。残りの引数はキーワード引数も含め、 dict のコンストラクタに与えられた場合と同様に扱われます。

defaultdict オブジェクトは標準の dict に加えて、以下のメソッドを実装しています:

__missing__(key)

もし default_factory 属性が None であれば、このメソッドは KeyError 例外を、 key を引数として発生させます。

もし default_factory 属性が None でない場合、このメソッドは引数なしで呼び出され、与えらえた key に対応するデフォルト値を提供します。この値は、辞書内に key に対応して登録され、最後に返されます。

もし default_factory の呼出が例外を発生させた場合には、変更せずそのまま例外を投げます。

このメソッドは dict クラスの __getitem__() メソッドで、キーが存在しなかった場合によびだされます。値を返すか例外を発生させるのどちらにしても、 __getitem__() からもそのまま値が返るか例外が発生します。

なお、 __missing__() は __getitem__() 以外のいかなる演算に対しても呼び出され ません 。よって get() は、普通の辞書と同様に、 default_factory を使うのではなくデフォルトとして None を返します。

defaultdict オブジェクトは以下のインスタンス変数をサポートしています:

default_factory

この属性は __missing__() メソッドによって使われます。これは存在すればコンストラクタの第1引数によって初期化され、そうでなければ None になります。

defaultdict の使用例

Using list as the default_factory, it is easy to group a sequence of key-value pairs into a dictionary of lists:

>>> 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])]

When each key is encountered for the first time, it is not already in the mapping; so an entry is automatically created using the default_factory function which returns an empty list. The list.append() operation then attaches the value to the new list. When keys are encountered again, the look-up proceeds normally (returning the list for that key) and the list.append() operation adds another value to the list. This technique is simpler and faster than an equivalent technique using dict.setdefault():

>>> d = {}
>>> for k, v in s:
...     d.setdefault(k, []).append(v)
...
>>> sorted(d.items())
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

Setting the default_factory to int makes the defaultdict useful for counting (like a bag or multiset in other languages):

>>> s = 'mississippi'
>>> d = defaultdict(int)
>>> for k in s:
...     d[k] += 1
...
>>> sorted(d.items())
[('i', 4), ('m', 1), ('p', 2), ('s', 4)]

When a letter is first encountered, it is missing from the mapping, so the default_factory function calls int() to supply a default count of zero. The increment operation then builds up the count for each letter.

常に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>'

Setting the default_factory to set makes the defaultdict useful for building a dictionary of sets:

>>> 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 can be None or an iterable of default values. Since fields with a default value must come after any fields without a default, the defaults are applied to the rightmost parameters. For example, if the fieldnames are ['x', 'y', 'z'] and the defaults are (1, 2), then x will be a required argument, y will default to 1, and z will default to 2.

もし module が指定されていれば、名前付きタプルの __module__ 属性は、指定された値に設定されます

名前付きタプルのインスタンスはインスタンスごとの辞書を持たないので、軽量で、普通のタプル以上のメモリを使用しません。

バージョン 3.1 で変更: rename のサポートが追加されました。

バージョン 3.6 で変更: verbose と rename 引数が キーワード専用引数 になりました.

バージョン 3.6 で変更: module 引数が追加されました。

バージョン 3.7 で変更: Remove the verbose parameter and the _source attribute.

バージョン 3.7 で変更: Added the defaults parameter and the _field_defaults attribute.

>>> # 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()

フィールド名を対応する値にマッピングする新しい:class:OrderedDict を返します:

>>> p = Point(x=11, y=22)
>>> p._asdict()
OrderedDict([('x', 11), ('y', 22)])

バージョン 3.1 で変更: 通常の dict の代わりに OrderedDict を返すようになりました。

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

Dictionary mapping field names to default values.

>>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])
>>> Account._fields_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__ に空のタプルをセットしています。これにより、インスタンス辞書の作成を抑制してメモリ使用量を低く保つのに役立ちます。

Subclassing is not useful for adding new, stored fields. Instead, simply create a new named tuple type from the _fields attribute:

>>> 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 で変更: 属性ドックストリングが書き込み可能になりました。

Default values can be implemented by using _replace() to customize a prototype instance:

>>> Account = namedtuple('Account', 'owner balance transaction_count')
>>> default_account = Account('<owner name>', 0.0, 0)
>>> johns_account = default_account._replace(owner='John')
>>> janes_account = default_account._replace(owner='Jane')

参考

  • Jan Kaliszewski による 名前付きタプル抽象基底クラスとメタクラス mix-in のレシピ 。名前付きタプルの abstract base class を提供するだけでなく、 metaclass に基づくコンストラクタの代わりもサポートするので、名前付きタプルがサブクラス化されるユースケースで便利です。
  • タプルではなく、辞書をもとにした変更可能な名前空間を作成するには types.SimpleNamespace() を参照してください。
  • 名前付きタプルに型ヒントを追加する方法については、 typing.NamedTuple() を参照してください。

OrderedDict オブジェクト

順序付き辞書 (ordered dictionary) は、ちょうど普通の辞書と同じようなものですが、項目が挿入された順序を記憶します。順序付き辞書に渡ってイテレートするとき、項目はそのキーが最初に追加された順序で返されます。

class collections.OrderedDict([items])

通常の dict メソッドをサポートする、辞書のサブクラスのインスタンスを返します。 OrderedDict は、キーが最初に追加された順序を記憶します。新しい項目が既存の項目を上書きしても、元の挿入位置は変わらないままです。項目を削除して再挿入するとそれが最後に移動します。

バージョン 3.1 で追加.

popitem(last=True)

順序付き辞書の popitem() メソッドは、(key, value) 対を返して消去します。この対は last が真なら LIFO で、偽なら FIFO (first-in, first-out 先入先出)` で返されます。

move_to_end(key, last=True)

既存の key を順序付き辞書の両端に移動します。項目は、 last が真 (デフォルト) なら右端に、 last が偽なら最初に移動されます。 key が存在しなければ KeyError を送出します:

>>> d = OrderedDict.fromkeys('abcde')
>>> d.move_to_end('b')
>>> ''.join(d.keys())
'acdeb'
>>> d.move_to_end('b', last=False)
>>> ''.join(d.keys())
'bacde'

バージョン 3.2 で追加.

通常のマッピングのメソッドに加え、順序付き辞書は reversed() による逆順の反復もサポートしています。

OrderedDict 間の等価判定は順序が影響し、 list(od1.items())==list(od2.items()) のように実装されます。 OrderedDict オブジェクトと他のマッピング (Mapping) オブジェクトの等価判定は、順序に影響されず、通常の辞書と同様です。これによって、 OrderedDict オブジェクトは通常の辞書が使われるところならどこでも使用できます。

バージョン 3.5 で変更: OrderedDict の項目、キー、値の ビュー が reversed() による逆順の反復をサポートするようになりました。

バージョン 3.6 で変更: PEP 468 の受理によって、OrderedDict のコンストラクタと、update() メソッドに渡したキーワード引数の順序は保持されます。

OrderedDict の例とレシピ

順序付き辞書は挿入順序を記憶するので、ソートと組み合わせて使うことで、ソートされた辞書を作れます:

>>> # 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)])

この新しい順序付き辞書は、項目が削除されてもソートされた順序を保持します。しかし、キーが追加されるとき、そのキーは最後に追加され、ソートは保持されません。

キーが 最後に 挿入された順序を記憶するような、順序付き辞書の変種を作るのも簡単です。新しい項目が既存の項目を上書きしたら、元の挿入位置は最後に移動します:

class LastUpdatedOrderedDict(OrderedDict):
    'Store items in the order the keys were last added'

    def __setitem__(self, key, value):
        if key in self:
            del self[key]
        OrderedDict.__setitem__(self, key, value)

順序付き辞書と Counter クラスを組み合わせると、要素が最初に現れた順を記憶するカウンタができます:

class OrderedCounter(Counter, OrderedDict):
    'Counter that remembers the order elements are first encountered'

    def __repr__(self):
        return '%s(%r)' % (self.__class__.__name__, OrderedDict(self))

    def __reduce__(self):
        return self.__class__, (OrderedDict(self),)

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)

Class that simulates a string object. The instance's content is kept in a regular string object, which is accessible via the data attribute of UserString instances. The instance's contents are initially set to a copy of seq. The seq argument can be any object which can be converted into a string using the built-in str() function.

In addition to supporting the methods and operations of strings, UserString instances provide the following attribute:

data

A real str object used to store the contents of the UserString class.

バージョン 3.5 で変更: 新たなメソッド __getnewargs__, __rmod__, casefold, format_map, isprintable, maketrans。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ型 »


collections.abc --- コレクションの抽象基底クラス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

collections.abc --- コレクションの抽象基底クラス

バージョン 3.3 で追加: 以前はこのモジュールは collections モジュールの一部でした。

ソースコード: Lib/_collections_abc.py

このモジュールは、 抽象基底クラス を提供します。抽象基底クラスは、クラスが特定のインタフェースを提供しているか、例えばハッシュ可能であるかやマッピングであるかを判定します。

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

collections モジュールは以下の ABC (抽象基底クラス) を提供します:

ABC | 継承しているクラス | 抽象メソッド | mixin メソッド
Container |  | __contains__ |
Hashable |  | __hash__ |
Iterable |  | __iter__ |
Iterator | Iterable | __next__ | __iter__
Reversible | Iterable | __reversed__ |
Generator | Iterator | send, throw | close, __iter__, __next__
Sized |  | __len__ |
Callable |  | __call__ |
Collection | Sized, Iterable, Container | __contains__, __iter__, __len__ |
Sequence | Reversible, Collection | __getitem__, __len__ | __contains__, __iter__, __reversed__, index, count
MutableSequence | Sequence | __getitem__, __setitem__, __delitem__, __len__, insert | Sequence から継承したメソッドと、 append, reverse, extend, pop, remove, __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 |  | __await__ |
Coroutine | Awaitable | send, throw | close
AsyncIterable |  | __aiter__ |
AsyncIterator | AsyncIterable | __anext__ | __aiter__
AsyncGenerator | AsyncIterator | asend, athrow | aclose, __aiter__, __anext__
class collections.abc.Container
class collections.abc.Hashable
class collections.abc.Sized
class collections.abc.Callable

それぞれメソッド __contains__(), __hash__(), __len__(), __call__() を提供するクラスの ABC です。

class collections.abc.Iterable

__iter__() メソッドを提供するクラスの ABC です。

メソッド isinstance(obj, Iterable) で使用すると、 Iterable や __iter__() メソッドを持っているクラスを検出できます。しかし、__getitem__() メソッドで反復するクラスは検出しません。 オブジェクトが iterable であるかどうかを判別するにあたって、信頼できる唯一の方法は iter(obj) を呼び出す方法です。

class collections.abc.Collection

サイズ付きのイテラブルなコンテナクラスの ABC です。

バージョン 3.6 で追加.

class collections.abc.Iterator

__iter__() メソッドと __next__() メソッドを提供するクラスの ABC です。 iterator の定義も参照してください。

class collections.abc.Reversible

__reversed__() メソッドを提供するイテラブルクラスの ABC です。

バージョン 3.6 で追加.

class collections.abc.Generator

PEP 342 で定義された、イテレータを send(), throw(), close() の各メソッドに拡張するプロトコルを実装する、ジェネレータクラスの ABC です。generator の定義も参照してください。

バージョン 3.5 で追加.

class collections.abc.Sequence
class collections.abc.MutableSequence
class collections.abc.ByteString

読み出し専用の シーケンス およびミュータブルな シーケンス の ABC です。

実装における注意: __iter__(), __reversed__(), index() など、一部の mixin メソッドは、下層の __getitem__() メソッドを繰り返し呼び出します。その結果、__getitem__() が定数のアクセス速度で実装されている場合、mixin メソッドは線形のパフォーマンスとなります。下層のメソッドが線形 (リンクされたリストの場合など) の場合、mixin は 2 乗のパフォーマンスとなるため、多くの場合上書きする必要があるでしょう。

バージョン 3.5 で変更: index() メソッドは stop と start 引数をサポートしました。

class collections.abc.Set
class collections.abc.MutableSet

読み出し専用の集合およびミュータブルな集合の ABC です。

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

await で使用できる awaitable オブジェクトの ABC です。カスタムの実装は、__await__() メソッドを提供しなければなりません。

Coroutine ABC の Coroutine オブジェクトとインスタンスは、すべてこの ABC のインスタンスです。

注釈

CPython では、ジェネレータベースのコルーチン (types.coroutine() または asyncio.coroutine() でデコレートされたジェネレータ) は、 __await__() メソッドを持ちませんが、待機可能 (awaitables) です。これらに対して isinstance(gencoro, Awaitable) を使用すると、 False が返されます。これらを検出するには、 inspect.isawaitable() を使用します。

バージョン 3.5 で追加.

class collections.abc.Coroutine

コルーチンと互換性のあるクラスの ABC です。これらは、コルーチンオブジェクト で定義された send(), throw(), close() のメソッドを実装します。カスタムの実装は、__await__() も実装しなければなりません。Coroutine のすべてのインスタンスは、 Awaitable のインスタンスでもあります。coroutine の定義も参照してください。

注釈

CPython では、ジェネレータベースのコルーチン (types.coroutine() または asyncio.coroutine() でデコレートされたジェネレータ) は、 __await__() メソッドを持ちませんが、待機可能 (awaitables) です。これらに対して isinstance(gencoro, Coroutine) を使用すると、 False が返されます。これらを検出するには、 inspect.isawaitable() を使用します。

バージョン 3.5 で追加.

class collections.abc.AsyncIterable

__aiter__ メソッドを提供するクラスの ABC です。asynchronous iterable の定義も参照してください。

バージョン 3.5 で追加.

class collections.abc.AsyncIterator

__aiter__ および __anext__ メソッドを提供するクラスの ABC です。asynchronous iterator の定義も参照してください。

バージョン 3.5 で追加.

class collections.abc.AsyncGenerator

PEP 525 と PEP 492 に定義されているプロトコルを実装した非同期ジェネレータクラスの ABC です。

バージョン 3.6 で追加.

これらの ABC はクラスやインスタンスが特定の機能を提供しているかどうかを調べるのに使えます。例えば:

size = None
if isinstance(myvar, collections.abc.Sized):
    size = len(myvar)

幾つかの ABC はコンテナ型 API を提供するクラスを開発するのを助ける mixin 型としても使えます。例えば、 Set API を提供するクラスを作る場合、3つの基本になる抽象メソッド __contains__(), __iter__(), __len__() だけが必要です。ABC が残りの __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 型として利用するときの注意点:

  1. 幾つかの set の操作は新しい set を作るので、デフォルトの mixin メソッドは iterable から新しいインスタンスを作成する方法を必要とします。クラスのコンストラクタは ClassName(iterable) の形のシグネチャを持つと仮定されます。内部の _from_iterable() というクラスメソッドが cls(iterable) を呼び出して新しい set を作る部分でこの仮定が使われています。コンストラクタのシグネチャが異なるクラスで Set を使う場合は、 iterable 引数から新しいインスタンスを生成するように _from_iterable() をオーバーライドする必要があります。
  2. (たぶん意味はそのままに速度を向上する目的で)比較をオーバーライドする場合、 __le__() と __ge__() だけを再定義すれば、その他の演算は自動的に追随します。
  3. Set mixin型は set のハッシュ値を計算する _hash() メソッドを提供しますが、すべての set が hashable や immutable とは限らないので、 __hash__() は提供しません。 mixin を使ってハッシュ可能な set を作る場合は、 Set と Hashable の両方を継承して、 __hash__ = Set._hash と定義してください。

参考

  • MutableSet を使った例として OrderedSet recipe。
  • ABCs についての詳細は、 abc モジュールと PEP 3119 を参照してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ型 »


bisect --- 配列二分法アルゴリズム

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

bisect --- 配列二分法アルゴリズム

ソースコード: Lib/bisect.py

このモジュールは、挿入の度にリストをソートすることなく、リストをソートされた順序に保つことをサポートします。大量の比較操作を伴うような、アイテムがたくさんあるリストでは、より一般的なアプローチに比べて、パフォーマンスが向上します。動作に基本的な二分法アルゴリズムを使っているので、 bisect と呼ばれています。ソースコードはこのアルゴリズムの実例として一番役に立つかもしれません (境界条件はすでに正しいです!)。

次の関数が用意されています:

bisect.bisect_left(a, x, lo=0, hi=len(a))

ソートされた順序を保ったまま x を a に挿入できる点を探し当てます。リストの中から検索する部分集合を指定するには、パラメータの lo と hi を使います。デフォルトでは、リスト全体が使われます。x がすでに a に含まれている場合、挿入点は既存のどのエントリーよりも前(左)になります。戻り値は、list.insert() の第一引数として使うのに適しています。a はすでにソートされているものとします。

返された挿入点 i は、配列 a を二つに分け、all(val < x for val in a[lo:i]) が左側に、all(val >= x for val in a[i:hi]) が右側になるようにします。

bisect.bisect_right(a, x, lo=0, hi=len(a))
bisect.bisect(a, x, lo=0, hi=len(a))

bisect_left() と似ていますが、 a に含まれる x のうち、どのエントリーよりも後ろ(右)にくるような挿入点を返します。

返された挿入点 i は、配列 a を二つに分け、all(val <= x for val in a[lo:i]) が左側に、all(val > x for val in a[i:hi]) が右側になるようにします。

bisect.insort_left(a, x, lo=0, hi=len(a))

x を a にソート順で挿入します。これは、a がすでにソートされている場合、a.insert(bisect.bisect_left(a, x, lo, hi), x) と等価です。なお、O(log n) の探索に対して、遅い O(n) の挿入の段階が律速となります。

bisect.insort_right(a, x, lo=0, hi=len(a))
bisect.insort(a, x, lo=0, hi=len(a))

insort_left() と似ていますが、 a に含まれる x のうち、どのエントリーよりも後ろに x を挿入します。

参考

bisect を利用して、直接の探索ができ、キー関数をサポートする、完全な機能を持つコレクションクラスを組み立てる SortedCollection recipe。キーは、探索中に不必要な呼び出しをさせないために、予め計算しておきます。

ソート済みリストの探索

上記の bisect() 関数群は挿入点を探索するのには便利ですが、普通の探索タスクに使うのはトリッキーだったり不器用だったりします。以下の 5 関数は、これらをどのように標準の探索やソート済みリストに変換するかを説明します:

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

その他の使用例

bisect() 関数は数値テーブルの探索に役に立ちます。この例では、 bisect() を使って、(たとえば)順序のついた数値の区切り点の集合に基づいて、試験の成績の等級を表す文字を調べます。区切り点は 90 以上は 'A'、 80 から 89 は 'B'、などです:

>>> 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']

sorted() 関数と違い、 bisect() 関数に key や reversed 引数を用意するのは、設計が非効率になるので、非合理的です (連続する bisect 関数の呼び出しは前回の key 参照の結果を "記憶" しません)。

代わりに、事前に計算しておいたキーのリストから検索して、レコードのインデックスを見つけます:

>>> data = [('red', 5), ('blue', 1), ('yellow', 8), ('black', 0)]
>>> data.sort(key=lambda r: r[1])
>>> keys = [r[1] for r in data]         # precomputed 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 --- 効率のよい数値アレイ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

array --- 効率のよい数値アレイ

このモジュールでは、基本的な値 (文字、整数、浮動小数点数) のアレイ (array、配列) をコンパクトに表現できるオブジェクト型を定義しています。アレイはシーケンス (sequence) 型であり、中に入れるオブジェクトの型に制限があることを除けば、リストとまったく同じように振る舞います。オブジェクト生成時に一文字の 型コード を用いて型を指定します。次の型コードが定義されています:

型コード | C の型 | Python の型 | 最小サイズ (バイト単位) | 注釈
'b' | signed char | int | 1 |
'B' | unsigned char | int | 1 |
'u' | Py_UNICODE | 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 | (2)
'Q' | unsigned long long | int | 8 | (2)
'f' | 浮動小数点数 | 浮動小数点数 | 4 |
'd' | double | 浮動小数点数 | 8 |

注釈:

  1. タイプコード 'u' は Python の古い Unicode 文字 (Py_UNICODE あるいは wchar_t) を表します。プラットフォームに依存して、これは 16bit か 32bit になります。

    'u' は将来的に他の Py_UNICODE API と一緒に削除されるでしょう。

    Deprecated since version 3.3, will be removed in version 4.0.

  2. タイプコード 'q' と 'Q' は Python をビルドしたプラットフォームのCコンパイラーが C言語の long long に対応しているか、 Windows で __int64 に対応している場合に利用可能です。

    バージョン 3.3 で追加.

値の実際の表現はマシンアーキテクチャ (厳密に言うとCの実装) によって決まります。値の実際のサイズは itemsize 属性から得られます。

このモジュールでは次の型を定義しています:

class array.array(typecode[, initializer])

要素のデータ型が typecode に限定される新しいアレイで、 オプションの値 initializer を渡すと初期値になりますが、 リスト、 bytes-like object または適当な型のイテレーション可能オブジェクトでなければなりません。

リストか文字列を渡した場合、initializer は新たに作成されたアレイの fromlist() 、 frombytes() あるいは fromunicode() メソッド (以下を参照) に渡され、アレイに初期項目を追加します。それ以外の場合には、イテラブルの initializer は extend() メソッドに渡されます。

array.typecodes

すべての利用可能なタイプコードを含む文字列

アレイオブジェクトでは、インデクス指定、スライス、連結および反復といった、 通常のシーケンスの演算をサポートしています。スライス代入を使うときは、 代入値は同じ型コードのアレイオブジェクトでなければなりません。 それ以外のオブジェクトを指定すると TypeError を送出します。 アレイオブジェクトはバッファインタフェースを実装しており、 bytes-like objects をサポートしている場所ならどこでも利用できます。

次のデータ要素やメソッドもサポートされています:

array.typecode

アレイを作るときに使う型コード文字です。

array.itemsize

アレイの要素 1 つの内部表現に使われるバイト長です。

array.append(x)

値 x の新たな要素をアレイの末尾に追加します。

array.buffer_info()

アレイの内容を記憶するために使っているバッファの、現在のメモリアドレスと要素数の入ったタプル (address, length) を返します。バイト単位で表したメモリバッファの大きさは array.buffer_info()[1] * array.itemsize で計算できます。例えば ioctl() 操作のような、メモリアドレスを必要とする低レベルな (そして、本質的に危険な) I/Oインタフェースを使って作業する場合に、ときどき便利です。アレイ自体が存在し、長さを変えるような演算を適用しない限り、有効な値を返します。

注釈

C やC++ で書いたコードからアレイオブジェクトを使う場合 (buffer_info() の情報を使う意味のある唯一の方法です) は、アレイオブジェクトでサポートしているバッファインタフェースを使う方がより理にかなっています。このメソッドは後方互換性のために保守されており、新しいコードでの使用は避けるべきです。バッファインタフェースの説明は バッファプロトコル (buffer Protocol) にあります。

array.byteswap()

アレイのすべての要素に対して「バイトスワップ」 (リトルエンディアンとビッグエンディアンの変換) を行います。このメソッドは大きさが 1、2、4 および 8 バイトの値のみをサポートしています。他の種類の値に使うと RuntimeError を送出します。異なるバイトオーダを使うマシンで書かれたファイルからデータを読み込むときに役に立ちます。

array.count(x)

シーケンス中の x の出現回数を返します。

array.extend(iterable)

iterable から要素を取り出し、アレイの末尾に要素を追加します。 iterable が別のアレイ型である場合、二つのアレイは 全く 同じ型コードでなければなりません。それ以外の場合には TypeError を送出します。 iterable がアレイでない場合、アレイに値を追加できるような正しい型の要素からなるイテレーション可能オブジェクトでなければなりません。

array.frombytes(s)

文字列から要素を追加します。文字列は、 (ファイルから fromfile() メソッドを使って値を読み込んだときのように) マシンのデータ形式で表された値の配列として解釈されます。

バージョン 3.2 で追加: 明確化のため fromstring() の名前が frombytes() に変更されました。

array.fromfile(f, n)

ファイルオブジェクト f から (マシンのデータ形式そのままで) n 個の要素を読み出し、アレイの末尾に要素を追加します。 n 個未満の要素しか読めなかった場合は EOFError を送出しますが、それまでに読み出せた値はアレイに追加されます。 f は本当の組み込みファイルオブジェクトでなければなりません。 read() メソッドをもつ他の型では動作しません。

array.fromlist(list)

リストから要素を追加します。型に関するエラーが発生した場合にアレイが変更されないことを除き、 for x in list: a.append(x) と同じです。

array.fromstring()

frombytes() に対する廃止予定のエイリアス

array.fromunicode(s)

指定した Unicode 文字列のデータを使ってアレイを拡張します。アレイの型コードは 'u' でなければなりません。それ以外の場合には、 ValueError を送出します。他の型のアレイに Unicode 型のデータを追加するには、 array.frombytes(unicodestring.encode(enc)) を使ってください。

array.index(x)

アレイ中で x が出現するインデクスのうち最小の値 i を返します。

array.insert(i, x)

アレイ中の位置 i の前に値 x をもつ新しい要素を挿入します。 i の値が負の場合、アレイの末尾からの相対位置として扱います。

array.pop([i])

アレイからインデクスが i の要素を取り除いて返します。オプションの引数はデフォルトで -1 になっていて、最後の要素を取り除いて返すようになっています。

array.remove(x)

アレイ中の x のうち、最初に現れたものを取り除きます。

array.reverse()

アレイの要素の順番を逆にします。

array.tobytes()

array をマシンの値の array に変換して、 bytes の形で返します (tofile() メソッドを使ってファイルに書かれるバイト列と同じです)。

バージョン 3.2 で追加: 明確化のため tostring() の名前が tobytes() に変更されました。

array.tofile(f)

すべての要素を (マシンの値の形式で) file object f に書き込みます。

array.tolist()

アレイを同じ要素を持つ普通のリストに変換します。

array.tostring()

tobytes() に対する廃止予定のエイリアス

array.tounicode()

アレイを Unicode 文字列に変換します。アレイの型コードは 'u' でなければなりません。それ以外の場合には ValueError を送出します。他の型のアレイから Unicode 文字列を得るには、 array.tobytes().decode(enc) を使ってください。

アレイオブジェクトを表示したり文字列に変換したりすると、 array(typecode, initializer) という形式で表現されます。 アレイが空の場合、 initializer の表示を省略します。 アレイが空でなければ、 typecode が 'u' の場合には文字列に、それ以外の場合には数値のリストになります。 array クラスが from array import array というふうにインポートされている限り、変換後の文字列に eval() を用いると元のアレイオブジェクトと同じデータ型と値を持つアレイに逆変換できることが保証されています。文字列表現の例を以下に示します:

array('l')
array('u', 'hello \u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])

参考

struct モジュール
異なる種類のバイナリデータのパックおよびアンパック。
xdrlib モジュール
遠隔手続き呼び出しシステムで使われる外部データ表現仕様 (External Data Representation, XDR) のデータのパックおよびアンパック。
Numerical Python ドキュメント
Numeric Python 拡張モジュール (NumPy) では、別の方法でシーケンス型を定義しています。 Numerical Python に関する詳しい情報は http://www.numpy.org/ を参照してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ型 »


weakref --- 弱参照

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

weakref --- 弱参照

ソースコード: 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 オブジェクト 、 generator 型のオブジェクト、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

tuple と int のような他の組み込み型はサブクラス化しても弱参照はサポートしません。(これは実装詳細であり、他の様々な Python 実装では異なる可能性があります。)。

拡張型は、簡単に弱参照をサポートできます。詳細については、 弱参照(Weak Reference)のサポート を参照してください。

class weakref.ref(object[, callback])

object への弱参照を返します。リファレントがまだ生きているならば、元のオブジェクトは参照オブジェクトの呼び出しで取り出せす。リファレントがもはや生きていないならば、参照オブジェクトを呼び出したときに None を返します。 callback に None 以外の値を与えた場合、オブジェクトをまさに後始末処理しようとするときに呼び出します。このとき弱参照オブジェクトは callback の唯一のパラメタとして渡されます。リファレントはもはや利用できません。

同じオブジェクトに対してたくさんの弱参照を作れます。それぞれの弱参照に対して登録されたコールバックは、もっとも新しく登録されたコールバックからもっとも古いものへと呼び出されます。

コールバックが発生させた例外は標準エラー出力に書き込まれますが、伝播されません。それらはオブジェクトの __del__() メソッドが発生させる例外と完全に同じ方法で処理されます。

object がハッシュ可能(hashable)ならば、弱参照はハッシュ可能です。それらは object が削除された後でもそれらのハッシュ値を保持します。 object が削除されてから初めて hash() が呼び出された場合に、その呼び出しは TypeError を発生させます。

弱参照は等価性のテストをサポートしていますが、順序をサポートしていません。参照がまだ生きているならば、 callback に関係なく二つの参照はそれらのリファレントと同じ等価関係を持ちます。リファレントのどちらか一方が削除された場合、参照オブジェクトが同一である場合に限り、その参照は等価です。

これはサブクラス化可能な型というよりファクトリ関数です。

__callback__

この読み出し専用の属性は、現在弱参照に関連付けられているコールバックを返します。コールバックが存在しないか、弱参照のリファレントが生きていない場合、この属性の値は None になります。

バージョン 3.4 で変更: __callback__ 属性が追加されました。

weakref.proxy(object[, callback])

弱参照を使う object へのプロキシを返します。弱参照オブジェクトを明示的な参照外しをしながら利用する代わりに、多くのケースでプロキシを利用することができます。返されるオブジェクトは、 object が呼び出し可能かどうかによって、 ProxyType または CallableProxyType のどちらかの型を持ちます。プロキシオブジェクトはリファレントに関係なくハッシュ可能(hashable)ではありません。これによって、それらの基本的な変更可能という性質による多くの問題を避けています。そして、辞書のキーとしての利用を妨げます。 callback は ref() 関数の同じ名前のパラメータと同じものです。(--- 訳注: リファレントが変更不能型であっても、プロキシはリファレントが消えるという状態の変更があるために、変更可能型です。---)

weakref.getweakrefcount(object)

object を参照する弱参照とプロキシの数を返します。

weakref.getweakrefs(object)

object を参照するすべての弱参照とプロキシオブジェクトのリストを返します。

class weakref.WeakKeyDictionary([dict])

キーを弱参照するマッピングクラス。キーへの強参照がなくなったときに、辞書のエントリは捨てられます。アプリケーションの他の部分が所有するオブジェクトへ属性を追加することもなく、それらのオブジェクトに追加データを関連づけるために使うことができます。これは属性へのアクセスをオーバーライドするオブジェクトに特に便利です。

注釈

警告: WeakKeyDictionary は Python 辞書型の上に作られているので、反復処理を行うときにはサイズ変更してはなりません。 WeakKeyDictionary の場合、反復処理の最中にプログラムが行った操作が、(ガベージコレクションの副作用として) 「魔法のように」辞書内の要素を消し去ってしまうため、確実なサイズ変更は困難なのです。

WeakKeyDictionary objects have an additional method that exposes the internal references directly. The references are not guaranteed to be "live" at the time they are used, so the result of calling the references needs to be checked before being used. This can be used to avoid creating references that will cause the garbage collector to keep the keys around longer than needed.

WeakKeyDictionary.keyrefs()

キーへの弱参照を持つ iterable オブジェクトを返します。

class weakref.WeakValueDictionary([dict])

値を弱参照するマッピングクラス。値への強参照が存在しなくなったときに、辞書のエントリは捨てられます。

注釈

警告: WeakValueDictionary は Python 辞書型の上に作られているので、反復処理を行うときにはサイズ変更してはなりません。 WeakValueDictionary の場合、反復処理の最中にプログラムが行った操作が、(ガベージコレクションの副作用として) 「魔法のように」辞書内の要素を消し去ってしまうため、確実なサイズ変更は困難なのです。

WeakValueDictionary オブジェクトは WeakKeyDictionary オブジェクトの keyrefs() メソッドと同じ目的を持つ追加のメソッドを持っています。

WeakValueDictionary.valuerefs()

値への弱参照を持つ iterable オブジェクトを返します。

class weakref.WeakSet([elements])

要素への弱参照を持つ集合型。要素への強参照が無くなったときに、その要素は削除されます。

class weakref.WeakMethod(method)

拡張された 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()
>>>

バージョン 3.4 で追加.

class weakref.finalize(obj, func, *args, **kwargs)

obj がガベージコレクションで回収されるときに呼び出される、呼び出し可能なファイナライザオブジェクトを返します。 通常の弱参照とは異なり、ファイナライザは参照しているオブジェクトが回収されるまで必ず生き残り、そのおかげでライフサイクル管理が大いに簡単になります。

ファイナライザは (直接もしくはガベージコレクションのときに) 呼び出されるまで 生きている と見なされ、呼び出された後には 死んでいます 。 生きているファイナライザを呼び出すと、 func(*arg, **kwargs) を評価した結果を返します。一方、死んでいるファイナライザを呼び出すと None を返します。

ガベージコレクション中にファイナライザコールバックが発生させた例外は、標準エラー出力に表示されますが、伝播することはできません。これらの例外は、オブジェクトの __del__() メソッドや弱参照のコールバックが発生させる例外と同じ方法で処理されます。

プログラムが終了するとき、生き残ったそれぞれのファイナライザは、自身の 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.

バージョン 3.4 で追加.

weakref.ReferenceType

弱参照オブジェクトのための型オブジェクト。

weakref.ProxyType

呼び出し可能でないオブジェクトのプロキシのための型オブジェクト。

weakref.CallableProxyType

呼び出し可能なオブジェクトのプロキシのための型オブジェクト。

weakref.ProxyTypes

プロキシのためのすべての型オブジェクトを含むシーケンス。これは両方のプロキシ型の名前付けに依存しないで、オブジェクトがプロキシかどうかのテストをより簡単にできます。

exception weakref.ReferenceError

プロキシオブジェクトが使われても、元のオブジェクトがガベージコレクションされてしまっているときに発生する例外。これは標準の ReferenceError 例外と同じです。

参考

PEP 205 - 弱参照
この機能の提案と理論的根拠。初期の実装と他の言語における類似の機能についての情報へのリンクを含んでいます。

弱参照オブジェクト

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(ExtendedRef, self).__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(ExtendedRef, self).__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!")  #doctest:+ELLIPSIS
<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()                                           #doctest:+ELLIPSIS
(<...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")  #doctest:+ELLIPSIS
<finalize object at ...; for 'Object' at ...>
>>> exit()                                               #doctest:+SKIP
obj dead or exiting

ファイナライザと __del__() メソッドとの比較

インスタンスが一時ディレクトリを表す、クラスを作成するとします。そのディレクトリは、次のイベントのいずれかが起きた時に、そのディレクトリの内容とともに削除されるべきです。

  • オブジェクトのガベージコレクションが行われた場合
  • オブジェクトの remove() メソッドが呼び出された場合
  • プログラムが終了した場合

ここでは、 __del__() メソッドを使用して次のようにクラスを実装します:

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 --- 動的な型生成と組み込み型に対する名前

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

types --- 動的な型生成と組み込み型に対する名前

ソースコード: Lib/types.py

This module defines utility function to assist in dynamic creation of new types.

さらに、標準の Python インタプリタによって使用されているものの、 int や str のように組み込みとして公開されていないようないくつかのオブジェクト型の名前を定義しています。

最後に、組み込みになるほど基本的でないような追加の型関連のユーティリティと関数をいくつか提供しています。

動的な型生成

types.new_class(name, bases=(), kwds=None, exec_body=None)

適切なメタクラスを使用して動的にクラスオブジェクトを生成します。

最初の3つの引数はクラス定義ヘッダーを構成する—クラス名、基底クラス (順番に)、キーワード引数 (例えば metaclass)—です。

exec_body 引数は、新規に生成されたクラスの名前空間を構築するために使用されるコールバックです。それは唯一の引数としてクラスの名前空間を受け取り、クラスの内容で名前空間を直接更新します。コールバックが渡されない場合、それは lambda ns: ns を渡すことと同じ効果があります。

バージョン 3.3 で追加.

types.prepare_class(name, bases=(), kwds=None)

適切なメタクラスを計算してクラスの名前空間を生成します。

引数はクラス定義ヘッダーを構成する要素—クラス名、基底クラス (順番に)、キーワード引数 (例えば metaclass)—です。

返り値は metaclass, namespace, kwds の3要素のタプルです

metaclass は適切なメタクラスです。namespace は用意されたクラスの名前空間です。また kwds は、'metaclass' エントリが削除された、渡された kwds 引数の更新されたコピーです。kwds 引数が渡されなければ、これは空の dict になります。

バージョン 3.3 で追加.

バージョン 3.6 で変更: 返されるタプルの namespace 要素のデフォルト値が変更されました。 現在では、メタクラスが __prepare__ メソッドを持っていないときは、挿入順序を保存するマッピングが使われます。

参考

メタクラス
これらの関数によってサポートされるクラス生成プロセスの完全な詳細
PEP 3115 - Metaclasses in Python 3000
__prepare__ 名前空間フックの導入
types.resolve_bases(bases)

Resolve MRO entries dynamically as specified by PEP 560.

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.

バージョン 3.7 で追加.

参考

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

標準的なインタプリタ型

このモジュールは、Python インタプリタを実装するために必要な多くの型に対して名前を提供します。それは、listiterator 型のような、単に処理中に付随的に発生するいくつかの型が含まれることを意図的に避けています。

これらの名前は典型的に isinstance() や issubclass() によるチェックに使われます。

以下の型に対して標準的な名前が定義されています:

types.FunctionType
types.LambdaType

ユーザ定義の関数と lambda 式によって生成された関数の型です。

types.GeneratorType

ジェネレータ関数によって生成された ジェネレータ イテレータオブジェクトの型です。

types.CoroutineType

async def 関数に生成される コルーチン オブジェクトです。

バージョン 3.5 で追加.

types.AsyncGeneratorType

非同期ジェネレータ関数によって作成された 非同期ジェネレータ イテレータオブジェクトの型です。

バージョン 3.6 で追加.

types.CodeType

compile() 関数が返すようなコードオブジェクトの型です。

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__().

バージョン 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__.

バージョン 3.7 で追加.

types.MethodDescriptorType

The type of methods of some built-in data types such as str.join().

バージョン 3.7 で追加.

types.ClassMethodDescriptorType

The type of unbound class methods of some built-in data types such as dict.__dict__['fromkeys'].

バージョン 3.7 で追加.

class types.ModuleType(name, doc=None)

module の型です。コンストラクタは生成するモジュールの名前と任意でその docstring を受け取ります。

注釈

インポートによりコントロールされる様々な属性を設定する場合、importlib.util.module_from_spec() を使用して新しいモジュールを作成してください。

__doc__

モジュールの docstring です。デフォルトは None です。

__loader__

モジュールをロードする loader です。デフォルトは None です。

バージョン 3.4 で変更: デフォルトが None になりました。以前はオプションでした。

__name__

モジュールの名前です。

__package__

モジュールがどの package に属しているかです。モジュールがトップレベルである (すなわち、いかなる特定のパッケージの一部でもない) 場合、この属性は '' に設定されます。そうでない場合、パッケージ名 (モジュールがパッケージ自身なら __name__) に設定されます。デフォルトは None です。

バージョン 3.4 で変更: デフォルトが None になりました。以前はオプションでした。

class types.TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)

sys.exc_info()[2] で得られるようなトレースバックオブジェクトの型です。

See the language reference for details of the available attributes and operations, and guidance on creating tracebacks dynamically.

types.FrameType

フレームオブジェクトの型です。トレースバックオブジェクト tb の tb.tb_frame などです。

See the language reference for details of the available attributes and operations.

types.GetSetDescriptorType

FrameType.f_locals や array.array.typecode のような、拡張モジュールにおいて PyGetSetDef によって定義されたオブジェクトの型です。この型はオブジェクト属性のディスクリプタとして利用されます。 property 型と同じ目的を持った型ですが、こちらは拡張モジュールで定義された型のためのものです。

types.MemberDescriptorType

datetime.timedelta.days のような、拡張モジュールにおいて PyMemberDef によって定義されたオブジェクトの型です。この型は、標準の変換関数を利用するような、Cのシンプルなデータメンバで利用されます。 property 型と同じ目的を持った型ですが、こちらは拡張モジュールで定義された型のためのものです。

CPython implementation detail: Pythonの他の実装では、この型は GetSetDescriptorType と同じかもしれません。

class types.MappingProxyType(mapping)

読み出し専用のマッピングのプロキシです。マッピングのエントリーに関する動的なビューを提供します。つまり、マッピングが変わった場合にビューがこれらの変更を反映するということです。

バージョン 3.3 で追加.

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 に対する新しいビューを返します。

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

class types.SimpleNamespace

名前空間への属性アクセスに加えて意味のある repr を提供するための、単純な object サブクラスです。

object とは異なり、 SimpleNamespace は、属性を追加したり削除したりすることができます。 SimpleNamespace オブジェクトがキーワード引数で初期化される場合、それらは元になる名前空間に直接追加されます。

この型は以下のコードとほぼ等価です:

class SimpleNamespace:
    def __init__(self, **kwargs):
        self.__dict__.update(kwargs)

    def __repr__(self):
        keys = sorted(self.__dict__)
        items = ("{}={!r}".format(k, self.__dict__[k]) for k in keys)
        return "{}({})".format(type(self).__name__, ", ".join(items))

    def __eq__(self, other):
        return self.__dict__ == other.__dict__

SimpleNamespace は class NS: pass を置き換えるものとして有用かもしれません。ですが、構造化されたレコード型に対しては、これよりはむしろ namedtuple() を使用してください。

バージョン 3.3 で追加.

types.DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)

クラスの属性アクセスを __getattr__ に振り替えます。

これは記述子で、インスタンス経由のアクセスとクラス経由のアクセスで振る舞いが異なる属性を定義するのに使います。インスタンスアクセスは通常通りですが、クラス経由の属性アクセスはクラスの __getattr__ メソッドに振り替えられます。これは AttributeError の送出により行われます。

これによって、インスタンス上で有効なプロパティを持ち、クラス上で同名の仮想属性を持つことができます (例については Enum を参照してください)。

バージョン 3.4 で追加.

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

types.coroutine(gen_func)

この関数は、 generator 関数を、ジェネレータベースのコルーチンを返す coroutine function に変換します。返されるジェネレータベースのコルーチンは依然として generator iterator ですが、同時に coroutine オブジェクトかつ awaitable であるとみなされます。ただし、必ずしも __await__() メソッドを実装する必要はありません。

gen_func はジェネレータ関数で、インプレースに変更されます。

gen_func がジェネレータ関数でない場合、この関数はラップされます。この関数が collections.abc.Generator のインスタンスを返す場合、このインスタンスは awaitable なプロキシオブジェクトにラップされます。それ以外のすべての型のオブジェクトは、そのまま返されます。

バージョン 3.5 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ型 »


copy --- 浅いコピーおよび深いコピー操作

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

copy --- 浅いコピーおよび深いコピー操作

ソースコード: Lib/copy.py

Python において代入文はオブジェクトをコピーしません。代入はターゲットとオブジェクトの間に束縛を作ります。ミュータブルなコレクションまたはミュータブルなアイテムを含むコレクションについては、元のオブジェクトを変更せずにコピーを変更できるように、コピーが必要になることが時々あります。このモジュールは、汎用的な浅い (shallow) コピーと深い (deep) コピーの操作 (以下で説明されます) を提供します。

以下にインタフェースをまとめます:

copy.copy(x)

x の浅い (shallow) コピーを返します。

copy.deepcopy(x[, memo])

x の深い (deep) コピーを返します。

exception copy.error

モジュール特有のエラーを送出します。

浅い (shallow) コピーと深い (deep) コピーの違いが関係するのは、複合オブジェクト (リストやクラスインスタンスのような他のオブジェクトを含むオブジェクト) だけです:

  • 浅いコピー (shallow copy) は新たな複合オブジェクトを作成し、その後 (可能な限り) 元のオブジェクト中に見つかったオブジェクトに対する 参照 を挿入します。
  • 深いコピー (deep copy) は新たな複合オブジェクトを作成し、その後元のオブジェクト中に見つかったオブジェクトの コピー を挿入します。

深いコピー操作には、しばしば浅いコピー操作の時には存在しない 2 つの問題がついてまわります:

  • 再帰的なオブジェクト (直接、間接に関わらず、自分自身に対する参照を持つ複合オブジェクト) は再帰ループを引き起こします。
  • 深いコピーは何もかもコピーしてしまうため、例えば複数のコピー間で共有するつもりだったデータも余分にコピーしてしまいます。

deepcopy() 関数では、これらの問題を以下のようにして回避しています:

  • keeping a memo dictionary of objects already copied during the current copying pass; and
  • ユーザ定義のクラスでコピー操作やコピーされる内容の集合を上書きできるようにします。

このモジュールでは、モジュール、メソッド、スタックトレース、スタックフレーム、ファイル、ソケット、ウィンドウ、アレイ、その他これらに類似の型をコピーしません。このモジュールでは元のオブジェクトを変更せずに返すことで関数とクラスを (浅くまたは深く)「コピー」します。これは pickle モジュールでの扱われかたと同じです。

辞書型の浅いコピーは dict.copy() で、リストの浅いコピーはリスト全体を指すスライス (例えば copied_list = original_list[:]) でできます。

クラスは、コピーを制御するために pickle の制御に使用するのと同じインターフェースを使用することができます。これらのメソッドについての情報はモジュール pickle の説明を参照してください。実際、 copy モジュールは、 copyreg モジュールによって登録された picle 関数を使用します。

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.

参考

pickle モジュール
オブジェクト状態の取得と復元をサポートするために使われる特殊メソッドについて議論されています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ型 »


pprint --- データ出力の整然化

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

pprint --- データ出力の整然化

ソースコード: Lib/pprint.py

pprint モジュールを使うと、Pythonの任意のデータ構造をインタープリタへの入力で使われる形式にして "pretty-print" できます。書式化された構造の中にPythonの基本的なタイプではないオブジェクトがあるなら、表示できないかもしれません。表示できないのは、ファイル、ソケット、あるいはクラスのようなオブジェクトや、 その他Pythonのリテラルとして表現できない様々なオブジェクトが含まれていた場合です。

可能であればオブジェクトを1行で整形しますが、与えられた幅に合わないなら複数行に分けて整形します。 出力幅を指定したい場合は、 PrettyPrinter オブジェクトを作成して明示してください。

辞書は表示される前にキーの順でソートされます。

pprint モジュールには1つのクラスが定義されています:

class pprint.PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, compact=False)

PrettyPrinter インスタンスを作ります。このコンストラクタにはいくつかのキーワード引数を設定できます。 stream キーワードで出力ストリームを設定できます；このストリームに対して呼び出されるメソッドはファイルプロトコルの write() メソッドだけです。もし設定されなければ、 PrettyPrinter は sys.stdout を使用します。再帰的なレベルごとに加えるインデントの量は indent で設定できます；デフォルト値は1です。他の値にすると出力が少しおかしく見えますが、ネスト化されたところが見分け易くなります。出力されるレベルは depth で設定できます；出力されるデータ構造が深いなら、指定以上の深いレベルのものは ... で置き換えられて表示されます。デフォルトでは、オブジェクトの深さを制限しません。 width 引数を使うと、出力する幅を望みの文字数に設定できます；デフォルトでは80文字です。もし指定した幅に書式化できない場合は、できるだけ近づけます。 compact が偽ならば(これがデフォルトです)、長いシーケンスのアイテム一つずつが、一行ずつ分けて書式化されます。 compact を真にすると、 width 幅に収まるだけの量のアイテムがそれぞれの出力行に書式化されます。

バージョン 3.4 で変更: compact 引数が追加されました。

>>> 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', (...)))))))

pprint モジュールは幾つかのショートカット関数も提供しています:

pprint.pformat(object, indent=1, width=80, depth=None, *, compact=False)

object を書式化して文字列として返します。 indent 、 width depth と、 compact は PrettyPrinter コンストラクタに書式化引数として渡されます。

バージョン 3.4 で変更: compact 引数が追加されました。

pprint.pprint(object, stream=None, indent=1, width=80, depth=None, *, compact=False)

stream 上に object の書式化された表現、続いて改行を出力します。 stream が None の場合、 sys.stdout が使用されます。これは、対話型インタプリタの中で値を調査するために print() 関数の代わりに使用されることがあります (さらに、スコープ内で使用するために print = pprint.pprint を再代入することができます)。 indent, width, depth, compact は、書式化引数として PrettyPrinter コンストラクタに渡されます。

バージョン 3.4 で変更: compact 引数が追加されました。

>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff)
>>> pprint.pprint(stuff)
[<Recursion on list with id=...>,
 'spam',
 'eggs',
 'lumberjack',
 'knights',
 'ni']
pprint.isreadable(object)

object を書式化して出力できる("readable") か、あるいは eval() を使って値を再構成できるかを返します。再帰的なオブジェクトに対しては常に False を返します。

>>> pprint.isreadable(stuff)
False
pprint.isrecursive(object)

object が再帰的な表現かどうかを返します。

さらにもう1つ、関数が定義されています:

pprint.saferepr(object)

object の文字列表現を、再帰的なデータ構造から保護した形式で返します。もし object の文字列表現が再帰的な要素を持っているなら、再帰的な参照は <Recursion on typename with id=number> で表示されます。出力は他と違って書式化されません。

>>> pprint.saferepr(stuff)
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"

PrettyPrinter オブジェクト

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 で現在のレベルを設定します。再帰呼び出しでは、現在の呼び出しより小さい値が渡されます。

使用例

pprint() 関数のいくつかの用途とそのパラメータを実証するために、PyPI からプロジェクトに関する情報を取って来ましょう:

>>> 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']

その基本形式では、 pprint() はオブジェクト全体を表示します:

>>> pprint.pprint(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.pprint(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.pprint(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 --- もう一つの repr() の実装

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

reprlib --- もう一つの repr() の実装

ソースコード: Lib/reprlib.py

reprlib モジュールは、結果の文字列のサイズに対する制限付きでオブジェクト表現を生成するための手段を提供します。これは Python デバッガの中で使用されており、他の文脈でも同様に役に立つかもしれません。

このモジュールはクラスとインスタンス、それに関数を提供します:

class reprlib.Repr

組み込み関数 repr() に似た関数を実装するために役に立つフォーマット用サービスを提供します。 過度に長い表現を作り出さないようにするための大きさの制限をオブジェクト型ごとに設定できます。

reprlib.aRepr

これは下で説明される repr() 関数を提供するために使われる Repr のインスタンスです。このオブジェクトの属性を変更すると、 repr() と Python デバッガが使うサイズ制限に影響します。

reprlib.repr(obj)

これは aRepr の repr() メソッドです。同じ名前の組み込み関数が返す文字列と似ていますが、最大サイズに制限のある文字列を返します。

サイズを制限するツールに加えて、このモジュールはさらに __repr__() に対する再帰呼び出しの検出とプレースホルダー文字列による置換のためのデコレータを提供します。

@reprlib.recursive_repr(fillvalue="...")

__repr__() メソッドに対する同一スレッド内の再帰呼び出しを検出するデコレータです。再帰呼び出しが行われている場合 fillvalue が返されます。そうでなければ通常の __repr__() 呼び出しが行われます。例えば:

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

バージョン 3.2 で追加.

Reprオブジェクト

Repr インスタンスはオブジェクト型毎に表現する文字列のサイズを制限するために使えるいくつかの属性と、特定のオブジェクト型をフォーマットするメソッドを提供します。

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.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オブジェクトをサブクラス化する

更なる組み込みオブジェクト型へのサポートを追加するため、あるいはすでにサポートされている型の扱いを変更するために、 Repr.repr1() による動的なディスパッチは Repr のサブクラス化に対応しています。 この例はファイルオブジェクトのための特別なサポートを追加する方法を示しています:

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ型 »


enum --- 列挙型のサポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ型 »

enum --- 列挙型のサポート

バージョン 3.4 で追加.

ソースコード: Lib/enum.py

列挙型は、一意の定数値に束縛された識別名 (メンバー) の集合です。列挙型の中でメンバーの同一性を比較でき、列挙型自身でイテレートが可能です。

モジュールコンテンツ

このモジュールでは一意の名前と値の集合を定義するのに使用できる 4 つの列挙型クラス Enum, IntEnum, Flag, IntFlag を定義しています。 このモジュールはデコレータの unique() とヘルパークラスの auto も定義しています。

class enum.Enum

列挙型定数を作成する基底クラスです。もうひとつの構築構文については 機能 API を参照してください。

class enum.IntEnum

int のサブクラスでもある列挙型定数を作成する基底クラスです。

class enum.IntFlag

列挙型定数を作成する基底クラスで、ビット演算子を使って組み合わせられ、その結果も IntFlag メンバーになります。 IntFlag は int のサブクラスでもあります。

class enum.Flag

列挙型定数を作成する基底クラスで、ビット演算を使って組み合わせられ、その結果も IntFlag メンバーになります。

enum.unique()

一つの名前だけがひとつの値に束縛されていることを保証する Enum クラスのデコレーターです。

class enum.auto

このインスタンスは列挙型のメンバーのための適切な値に置き換えられます。

バージョン 3.6 で追加: Flag, IntFlag, auto

Enum の作成

列挙型は読み書きが容易になるよう class 文を使って作成します。もうひとつの作成方法は 機能 API で説明しています。列挙型は以下のように Enum のサブクラスとして定義します:

>>> from enum import Enum
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3
...

注釈

列挙型のメンバー値

メンバー値は何であっても構いません: int, str などなど。 正確な値が重要でない場合は、 auto インスタンスを使っておくと、適切な値が選ばれます。 auto とそれ以外の値を混ぜて使う場合は注意する必要があります。

注釈

用語

  • クラス Color は 列挙型 (または Enum) です
  • 属性 Color.RED, Color.GREEN などは 列挙型のメンバー (または Enum メンバー) で、機能的には定数です。
  • 列挙型のメンバーは 名前 と 値 を持ちます (Color.RED の名前は RED 、 Color.BLUE の値は 3 など。)

注釈

Enum の作成に class 文を使用するものの、Enum は通常の Python クラスではありません。詳細は Enum はどう違うのか? を参照してください。

列挙型のメンバーは人が読める文字列表現を持ちます:

>>> print(Color.RED)
Color.RED

...その一方でそれらの repr はより多くの情報を持っています:

>>> print(repr(Color.RED))
<Color.RED: 1>

列挙型メンバーの データ型 はそれが所属する列挙型になります:

>>> type(Color.RED)
<enum 'Color'>
>>> isinstance(Color.GREEN, Color)
True
>>>

Enum メンバーは自身の名前を持つだけのプロパティも持っています:

>>> print(Color.RED.name)
RED

列挙型は定義順でのイテレーションをサポートしています:

>>> class Shake(Enum):
...     VANILLA = 7
...     CHOCOLATE = 4
...     COOKIES = 9
...     MINT = 3
...
>>> for shake in Shake:
...     print(shake)
...
Shake.VANILLA
Shake.CHOCOLATE
Shake.COOKIES
Shake.MINT

列挙型のメンバーはハッシュ化可能なため、辞書や集合で使用できます:

>>> apples = {}
>>> apples[Color.RED] = 'red delicious'
>>> apples[Color.GREEN] = 'granny smith'
>>> apples == {Color.RED: 'red delicious', Color.GREEN: 'granny smith'}
True

列挙型メンバーおよびそれらの属性へのプログラム的アクセス

プログラム的にメンバーに番号でアクセスしたほうが便利な場合があります (すなわち、プログラムを書いている時点で正確な色がまだわからなく、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: Attempted to reuse key: 'SQUARE'

ただし、複数の列挙型メンバーが同じ値を持つことはできます。同じ値を持つ 2 つのメンバー A および B (先に定義したのは A) が与えられたとき、B は A の別名になります。A および B を値で調べたとき、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>

注釈

すでに定義されている属性と同じ名前のメンバー (一方がメンバーでもう一方がメソッド、など) の作成、あるいはメンバーと同じ名前の属性の作成はできません。

番号付けの値が同一であることの確認

デフォルトでは、前述のように複数の名前への同じ値の定義は別名とすることで許されています。この挙動を望まない場合、以下のデコレーターを使用することで各値が列挙型内で一意かどうか確認できます:

@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

値の自動設定を使う

正確な値が重要でない場合、 auto が使えます:

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

その値は _generate_next_value_() によって選ばれ、この関数はオーバーライドできます:

>>> class AutoName(Enum):
...     def _generate_next_value_(name, start, count, last_values):
...         return name
...
>>> class Ordinal(AutoName):
...     NORTH = auto()
...     SOUTH = auto()
...     EAST = auto()
...     WEST = auto()
...
>>> list(Ordinal)
[<Ordinal.NORTH: 'NORTH'>, <Ordinal.SOUTH: 'SOUTH'>, <Ordinal.EAST: 'EAST'>, <Ordinal.WEST: 'WEST'>]

注釈

デフォルトの _generate_next_value_() メソッドの目的は、最後に提供した int の次から順々に int を提供することですが、この動作は実装詳細であり変更される可能性があります。

イテレーション

列挙型のメンバーのイテレートは別名をサポートしていません:

>>> list(Shape)
[<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]

特殊属性 __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']

比較

列挙型メンバーは同一性を比較できます:

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

The rules for what is allowed are as follows: names that start and end with a single underscore are reserved by enum and cannot be used; all other attributes defined within an enumeration will become members of this enumeration, with the exception of special methods (__str__(), __add__(), etc.), descriptors (methods are also descriptors), and variable names listed in _ignore_.

注意: 列挙型で __new__() および/または __init__() を定義した場合、列挙型メンバーに与えられた値はすべてこれらのメソッドに渡されます。例 Planet を参照してください。

Restricted Enum subclassing

A new Enum class must have one base Enum class, up to one concrete data type, and as many object-based mixin classes as needed. The order of these base classes is:

def EnumName([mix-in, ...,] [data-type,] base-enum):
    pass

Also, subclassing an enumeration is allowed only if the enumeration does not define any members. So this is forbidden:

>>> class MoreColor(Color):
...     PINK = 17
...
Traceback (most recent call last):
...
TypeError: Cannot extend enumerations

以下のような場合は許されます:

>>> class Foo(Enum):
...     def some_behavior(self):
...         pass
...
>>> class Bar(Foo):
...     HAPPY = 1
...     SAD = 2
...

メンバーが定義された列挙型のサブクラス化を許可すると、いくつかのデータ型およびインスタンスの重要な不変条件の違反を引き起こします。とはいえ、それが許可されると、列挙型のグループ間での共通の挙動を共有するという利点もあります。 (OrderedEnum の例を参照してください。)

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 化も容易です。

Enum メンバーをどう pickle 化/unpickle 化するかは、列挙型クラス内の __reduce_ex__() で定義することで変更できます。

機能 API

Enum クラスは呼び出し可能で、以下の機能 API を提供しています:

>>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
>>> Animal
<enum 'Animal'>
>>> Animal.ANT
<Animal.ANT: 1>
>>> Animal.ANT.value
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 でなければならないためです。

機能 API による Enum の pickle 化は、その列挙型がどのモジュールで作成されたかを見つけ出すためにフレームスタックの実装の詳細が使われるので、トリッキーになることがあります (例えば別のモジュールのユーティリティ関数を使うと失敗しますし、IronPython や Jython ではうまくいきません)。解決策は、以下のようにモジュール名を明示的に指定することです:

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

新しい Enum クラスに記録されるそれ自身の名前です。
名前:

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:

新しい Enum クラスが属するモジュールの名前です。
qualname:

新しい Enum クラスが属するモジュールの場所です。
type:

新しい Enum クラスに複合されるデータ型です。
start:

names のみが渡されたときにカウントを開始する数です。

バージョン 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]

IntFlag

提供されている 2 つ目の Enum の派生型 IntFlag も int を基底クラスとしています。 IntFlag メンバーが Enum メンバーと異なるのは、ビット演算子 (&, |, ^, ~) を使って組み合わせられ、その結果も IntFlag メンバーになることです。 しかし、名前が示すように、 IntFlag は int のサブクラスでもあり、 int が使われるところでもどこでも使えます。 IntFlag メンバーに対してビット演算以外のどんな演算をしても、その結果は IntFlag メンバーではなくなります。

バージョン 3.6 で追加.

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

IntFlag と Enum のもう 1 つの重要な違いは、フラグが設定されていない (値が0である) 場合、その真偽値としての評価は False になることです:

>>> Perm.R & Perm.X
<Perm.0: 0>
>>> bool(Perm.R & Perm.X)
False

IntFlag は int のサブクラスでもあるので、その両者を組み合わせられます:

>>> Perm.X | 8
<Perm.8|X: 9>

Flag

最後の派生型は Flag です。 IntFlag と同様に、 Flag メンバーもビット演算子 (&, |, ^, ~) を使って組み合わせられます。 しかし IntFlag とは違い、他のどの Flag 列挙型とも int とも組み合わせたり、比較したりできません。 値を直接指定することも可能ですが、値として auto を使い、 Flag に適切な値を選ばせることが推奨されています。

バージョン 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: 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

注釈

ほとんどの新しいコードでは、 Enum と Flag が強く推奨されます。 というのは、 IntEnum と IntFlag は (整数と比較でき、従って推移的に他の無関係な列挙型と比較できてしまうことにより) 列挙型の意味論的な約束に反するからです。 IntEnum と IntFlag は、 Enum や Flag では上手くいかない場合のみに使うべきです; 例えば、整数定数を列挙型で置き換えるときや、他のシステムとの相互運用性を持たせたいときです。

その他

IntEnum は enum モジュールの一部ですが、単独での実装もとても簡単に行なえます:

class IntEnum(int, Enum):
    pass

ここでは似たような列挙型の派生を定義する方法を紹介します; 例えば、StrEnum は int ではなく str で複合させたものです。

いくつかのルール:

  1. Enum のサブクラスを作成するとき、複合させるデータ型は、基底クラスの並びで Enum 自身より先に記述しなければなりません (上記 IntEnum の例を参照)。
  2. Enum のメンバーはどんなデータ型でも構いませんが、追加のデータ型 (例えば、上の例の int) と複合させてしまうと、すべてのメンバーの値はそのデータ型でなければならなくなります。 この制限は、メソッドの追加するだけの、 int や str のような他のデータ型を指定しない複合には適用されません。
  3. 他のデータ型と複合された場合、 value 属性は、たとえ等価であり等価であると比較が行えても、列挙型メンバー自身としては 同じではありません 。
  4. %-方式の書式: %s および %r はそれぞれ Enum クラスの __str__() および __repr__() を呼び出します; その他のコード (IntEnum の %i や %h など) は列挙型のメンバーを複合されたデータ型として扱います。
  5. フォーマット済み文字列リテラル 、 str.format() 、 format() では、複合されたデータ型の __format__() が使われます。 Enum クラスの str() や repr() を使って欲しいときは、フォーマットのコードで !s および !r を使ってください。

興味深い例

Enum, IntEnum, IntFlag, Flag は用途の大部分をカバーすると予想されますが、そのすべてをカバーできているわけではありません。 ここでは、そのまま、あるいは独自の列挙型を作る例として使える、様々なタイプの列挙型を紹介します。

値の省略

多くの用途では、列挙型の実際の値が何かは気にされません。 このタイプの単純な列挙型を定義する方法はいくつかあります:

  • 値に auto インスタンスを使用する
  • 値として object インスタンスを使用する
  • 値として解説文字列を使用する
  • 値としてタプルを使用し、独自の __new__() を使用してタプルを int 値で置き換える

これらのどの方法を使ってもユーザーに対して、値は重要ではなく、他のメンバーの番号の振り直しをする必要無しに、メンバーの追加、削除、並べ替えが行えるということを示せます。

どの方法を選んでも、(重要でない) 値を隠す repr() を提供すべきです:

>>> class NoValue(Enum):
...     def __repr__(self):
...         return '<%s.%s>' % (self.__class__.__name__, self.name)
...

auto を使う

auto を使うと次のようになります:

>>> class Color(NoValue):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.GREEN
<Color.GREEN>

object を使う

object を使うと次のようになります:

>>> class Color(NoValue):
...     RED = object()
...     GREEN = object()
...     BLUE = object()
...
>>> Color.GREEN
<Color.GREEN>

解説文字列を使う

値として文字列を使うと次のようになります:

>>> class Color(NoValue):
...     RED = 'stop'
...     GREEN = 'go'
...     BLUE = 'too fast!'
...
>>> Color.GREEN
<Color.GREEN>
>>> Color.GREEN.value
'go'

独自の __new__() を使う

自動で番号を振る __new__() を使うと次のようになります:

>>> class AutoNumber(NoValue):
...     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>
>>> Color.GREEN.value
2

注釈

__new__() メソッドが定義されていれば、Enum 番号の作成時に使用されます; これは Enum の __new__() と置き換えられ、クラスが作成された後の既存の番号を取得に使用されます。

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

An example to show the _ignore_ attribute in use:

>>> 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)>]

Enum はどう違うのか?

Enum は Enum 派生クラスやそれらのインスタンス (メンバー) 双方の多くの側面に影響を及ぼすカスタムメタクラスを持っています。

Enum クラス

The EnumMeta 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. EnumMeta is responsible for ensuring that various other methods on the final Enum class are correct (such as __new__(), __getnewargs__(), __str__() and __repr__()).

Enum メンバー (インスタンス)

Enum メンバーについて最も興味深いのは、それらがシングルトンであるということです。EnumMeta は Enum 自身を作成し、メンバーを作成し、新しいインスタンスが作成されていないかどうかを確認するために既存のメンバーインスタンスだけを返すカスタム __new__() を追加します。

細かい点

__dunder__ 名のサポート

__members__ は member_name:member を要素とする OrderedDict です。 これはクラスでのみ利用可能です。

__new__() が、もし指定されていた場合、列挙型のメンバーを作成し、返します; そのメンバー の _value_ を適切に設定するのも非常によい考えです。 いったん全てのメンバーが作成されると、それ以降 __new__() は使われません。

_sunder_ 名のサポート

  • _name_ -- メンバー名
  • _value_ -- メンバーの値; __new__ で設定したり、変更したりできます
  • _missing_ -- 値が見付からなかったときに使われる検索関数; オーバーライドされていることがあります
  • _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

バージョン 3.6 で追加: _missing_, _order_, _generate_next_value_

バージョン 3.7 で追加: _ignore_

To help keep Python 2 / Python 3 code in sync an _order_ attribute can be provided. It will be checked against the actual order of the enumeration and raise an error if the two do not match:

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

注釈

In Python 2 code the _order_ attribute is necessary as definition order is lost before it can be recorded.

Enum メンバー型

Enum メンバーは、それらの Enum クラスのインスタンスで、通常は EnumClass.member のようにアクセスします。 ある状況下では、 EnumClass.member.member としてもアクセスできますが、この方法は絶対に使うべきではありません。 というのは、この検索は失敗するか、さらに悪い場合には、探している Enum メンバー以外のものを返す場合もあるからです (これがメンバーの名前に大文字のみを使うのが良い理由の 1 つでもあります):

>>> class FieldTypes(Enum):
...     name = 0
...     value = 1
...     size = 2
...
>>> FieldTypes.value.size
<FieldTypes.size: 2>
>>> FieldTypes.size.value
2

バージョン 3.5 で変更.

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__', 'name', 'surface_gravity', 'value']

Flag のメンバーの組み合わせ

Flag メンバーの組み合わせに名前が無い場合、 repr() の出力には、その値にある全ての名前を持つフラグと全ての名前を持つ組み合わせが含まれます:

>>> 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.CYAN|MAGENTA|BLUE|YELLOW|GREEN|RED: 7>

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ型 »


数値と数学モジュール

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

数値と数学モジュール

この章で記述されているモジュールは、数値に関するあるいは数学関係の関数とデータ型を提供します。 numbers モジュールは、数値の型の抽象的な階層を定義します。 math と cmath モジュールは、浮動小数点数と複素数のための様々な数学関数を含んでいます。 decimal モジュールは、任意精度の計算を使用して、10進数の正確な表現をサポートします。

この章では以下のモジュールが記述されています:

  • numbers --- 数の抽象基底クラス
    • 数値塔
    • 型実装者のための注意事項
      • さらに数のABCを追加する
      • 算術演算の実装
  • math --- 数学関数
    • 数論および数表現の関数
    • 指数関数と対数関数
    • 三角関数
    • 角度変換
    • 双曲線関数
    • 特殊関数
    • 定数
  • cmath --- 複素数のための数学関数
    • 極座標変換
    • 指数関数と対数関数
    • 三角関数
    • 双曲線関数
    • 類別関数
    • 定数
  • decimal --- 十進固定及び浮動小数点数の算術演算
    • クイックスタートチュートリアル
    • Decimal オブジェクト
      • 論理引数
    • Context オブジェクト
    • 定数
    • 丸めモード
    • シグナル
    • 浮動小数点数に関する注意
      • 精度を上げて丸め誤差を抑制する
      • 特殊値
    • スレッドを使った処理
    • レシピ
    • Decimal FAQ
  • fractions --- 有理数
  • random --- 擬似乱数を生成する
    • 保守 (bookkeeping) 関数
    • 整数用の関数
    • シーケンス用の関数
    • 実数分布
    • 他の生成器
    • 再現性について
    • 例とレシピ
  • statistics --- 数理統計関数
    • 平均及び中心位置の測度
    • 分散の測度
    • 関数の詳細
    • 例外

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


numbers --- 数の抽象基底クラス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 数値と数学モジュール »

numbers --- 数の抽象基底クラス

ソースコード: Lib/numbers.py

numbers モジュール ( PEP 3141) は数の 抽象基底クラス の階層を定義します。この階層では、さらに多くの演算が順番に定義されます。このモジュールで定義される型はどれもインスタンス化できません。

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

Real は、Complex 上に、 実数に対して行える演算を加えます。

簡潔に言うとそれらは: float への変換, math.trunc(), round(), math.floor(), math.ceil(), divmod(), //, %, <, <=, > および >= です。

Real はまた complex(), real, imag および conjugate() のデフォルトを提供します。

class numbers.Rational

Real をサブタイプ化し numerator と denominator のプロパティを加えたものです。これらは既約分数のものでなければなりません。この他に float() のデフォルトも提供します。

numerator

抽象プロパティ。

denominator

抽象プロパティ。

class numbers.Integral

Rational をサブタイプ化し int への変換が加わります。 float(), numerator, denominator のデフォルトを提供します。 ** に対する抽象メソッドと、ビット列演算 <<, >>, &, ^, |, ~ を追加します。

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

実装する人は等しい数が等しく扱われるように同じハッシュを与えるように気を付けねばなりません。これは二つの異なった実数の拡張があるような場合にはややこしいことになるかもしれません。たとえば、 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)

算術演算の実装

算術演算を実装する際には、型混合(mixed-mode)演算を行うと、作者が両方の引数の型について知っているような実装を呼び出すか、両方の引数をそれぞれ最も似ている組み込み型に変換してその型で演算を行うか、どちらになるのが望ましい実装です。つまり、 Integral のサブタイプに対しては __add__() と __radd__() を次のように定義するべきです:

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 を考えます:

  1. A が b を受け付ける __add__() を定義している場合、何も問題はありません。
  2. A でボイラープレート部分に落ち込み、その結果 __add__() が値を返すならば、 B に良く考えられた __radd__() が定義されている可能性を見逃してしまいますので、ボイラープレートは __add__() から NotImplemented を返すのが良いでしょう。(若しくは、 A はまったく __add__() を実装すべきではなかったかもしれません。)
  3. そうすると、 B の __radd__() にチャンスが巡ってきます。ここで a が受け付けられるならば、結果は上々です。
  4. ここでボイラープレートに落ち込むならば、もう他に試すべきメソッドはありませんので、デフォルト実装の出番です。
  5. もし B <: A ならば、Python は A.__add__ の前に B.__radd__ を試します。これで良い理由は、 A についての知識を持って実装しており、 Complex に委ねる前にこれらのインスタンスを扱えるはずだからです。

もし A <: Complex かつ B <: Real で他に共有された知識が無いならば、適切な共通の演算は組み込みの complex を使ったものになり、どちらの __radd__() ともそこに着地するでしょうから、 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, numbers.Real):
            return fallback_operator(float(a), float(b))
        elif isinstance(a, numbers.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 --- 数学関数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 数値と数学モジュール »

math --- 数学関数

このモジュールはいつでも利用できます。標準 C で定義されている数学関数にアクセスすることができます。

これらの関数で複素数を使うことはできません。複素数に対応する必要があるならば、 cmath モジュールにある同じ名前の関数を使ってください。ほとんどのユーザーは複素数を理解するのに必要なだけの数学を勉強したくないので、複素数に対応した関数と対応していない関数の区別がされています。これらの関数では複素数が利用できないため、引数に複素数を渡されると、複素数の結果が返るのではなく例外が発生します。その結果、どういった理由で例外が送出されたかに早い段階で気づく事ができます。

このモジュールでは次の関数を提供しています。明示的な注記のない限り、戻り値は全て浮動小数点数になります。

数論および数表現の関数

math.ceil(x)

x の「天井」 (x 以上の最小の整数) を返します。 x が浮動小数点数でなければ、内部的に x.__ceil__() が実行され、 Integral 値が返されます。

math.copysign(x, y)

x の大きさ (絶対値) で y と同じ符号の浮動小数点数を返します。符号付きのゼロをサポートしているプラットフォームでは、copysign(1.0, -0.0) は -1.0 を返します。

math.fabs(x)

x の絶対値を返します。

math.factorial(x)

x の階乗を返します。 x が整数値でなかったり負であったりするときは、 ValueError を送出します。

math.floor(x)

x の「床」 (x 以下の最大の整数) を返します。 x が浮動小数点数でなければ、内部的に x.__floor__() が実行され、 Integral 値が返されます。

math.fmod(x, y)

プラットフォームの C ライブラリで定義されている fmod(x, y) を返します。 Python の x % y という式は必ずしも同じ結果を返さないということに注意してください。 C 標準の要求では、 fmod() は除算の結果が x と同じ符号になり、大きさが abs(y) より小さくなるような整数 n については fmod(x, y) が厳密に (数学的に、つまり無限の精度で) x - n*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)

iterable 中の値の浮動小数点数の正確な和を返します。複数の部分和を追跡することで精度のロスを防ぎます:

>>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
0.9999999999999999
>>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
1.0

アルゴリズムの正確性は、 IEEE-754 演算の保証と、丸めモードが偶数丸め (half-even) である典型的な場合に依存します。Windows 以外のいくつかのビルドでは、下層の C ライブラリが拡張精度の加算を行い、時々計算途中の和を double 型へ丸めてしまうため、最下位ビットが消失することがあります。

より詳細な議論と代替となる二つのアプローチについては、ASPN cookbook recipes for accurate floating point summation をご覧下さい。

math.gcd(a, b)

整数 a と b の最大公約数を返します。a と b のいずれかがゼロでない場合、gcd(a, b) の値は a と b の両方を割り切ることのできる、最も大きな正の整数です。gcd(0, 0) は 0 を返します。

バージョン 3.5 で追加.

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 は自身とのみ近いと見なされます。

バージョン 3.5 で追加.

参考

PEP 485 -- A function for testing approximate equality

math.isfinite(x)

x が無限でも NaN でもない場合に True を返します。それ以外の時には False を返します。 (注意: 0.0 は有限数と扱われます。)

バージョン 3.2 で追加.

math.isinf(x)

x が正ないし負の無限数ならば True を返します。それ以外の時には False を返します。

math.isnan(x)

x がNaN (not a number、非数) の時に True を返します。それ以外の場合には False を返します。

math.ldexp(x, i)

x * (2**i) を返します。これは本質的に frexp() の逆関数です。

math.modf(x)

x の小数部分と整数部分を返します。両方の結果は x の符号を受け継ぎます。整数部はfloat型で返されます。

math.remainder(x, y)

Return the IEEE 754-style remainder of x with respect to y. For finite x and finite nonzero y, this is the difference x - n*y, where n is the closest integer to the exact value of the quotient x / y. If x / y is exactly halfway between two consecutive integers, the nearest even integer is used for n. The remainder r = remainder(x, y) thus always satisfies abs(r) <= 0.5 * abs(y).

Special cases follow IEEE 754: in particular, remainder(x, math.inf) is x for any finite x, and remainder(x, 0) and remainder(math.inf, x) raise ValueError for any non-NaN x. If the result of the remainder operation is zero, that zero will have the same sign as x.

On platforms using IEEE 754 binary floating-point, the result of this operation is always exactly representable: no rounding error is introduced.

バージョン 3.7 で追加.

math.trunc(x)

x の Integral 値 (たいていは整数) へ切り捨てられた Real 値を返します。 x.__trunc__() に処理を委譲します。

frexp() と modf() は C のものとは異なった呼び出し/返しパターンを持っていることに注意してください。引数を1つだけ受け取り、1組のペアになった値を返すので、2つ目の戻り値を '出力用の引数' 経由で返したりはしません (Python には出力用の引数はありません)。

ceil() 、 floor() 、および modf() 関数については、非常に大きな浮動小数点数が 全て 整数そのものになるということに注意してください。通常、Python の浮動小数点型は 53 ビット以上の精度をもたない (プラットフォームにおける C double 型と同じ) ので、結果的に abs(x) >= 2**52 であるような浮動小数点型 x は小数部分を持たなくなるのです。

指数関数と対数関数

math.exp(x)

Return e raised to the power x, where e = 2.718281... is the base of natural logarithms. This is usually more accurate than math.e ** x or pow(math.e, x).

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

バージョン 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) よりも正確な値を返します。

バージョン 3.3 で追加.

参考

int.bit_length() は、その整数を二進法で表すのに何ビット必要かを返す関数です。符号と先頭のゼロは無視されます。

math.log10(x)

x の10を底とした対数(常用対数)を返します。この関数は通常、log(x, 10) よりも高精度です。

math.pow(x, y)

x の y 乗を返します。例外的な場合については、 C99 標準の付録 'F' に可能な限り従います。特に、 pow(1.0, x) と pow(x, 0.0) は、たとえ x が零や NaN でも、常に 1.0 を返します。もし x と y の両方が有限の値で、 x が負、 y が整数でない場合、 pow(x, y) は未定義で、 ValueError を送出します。

組み込みの ** 演算子と違って、 math.pow() は両方の引数を float 型に変換します。正確な整数の冪乗を計算するには ** もしくは組み込みの pow() 関数を使ってください。

math.sqrt(x)

x の平方根を返します。

三角関数

math.acos(x)

x の逆余弦を、ラジアンで返します。

math.asin(x)

x の逆正弦を、ラジアンで返します。

math.atan(x)

x の逆正接を、ラジアンで返します。

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.hypot(x, y)

ユークリッドノルム(sqrt(x*x + y*y))を返します。これは原点から点 (x, y) のベクトルの長さです。

math.sin(x)

x ラジアンの正弦を返します。

math.tan(x)

x ラジアンの正接を返します。

角度変換

math.degrees(x)

角 x をラジアンから度に変換します。

math.radians(x)

角 x を度からラジアンに変換します。

双曲線関数

双曲線関数 は円ではなく双曲線を元にした三角関数のようなものです。

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 の 誤差関数 を返します。

erf() 関数は、伝統的な統計関数を計算するのに使うことができます。例えば、 累積標準正規分布 を計算する関数は次のように定義できます:

def phi(x):
    'Cumulative distribution function for the standard normal distribution'
    return (1.0 + erf(x / sqrt(2.0))) / 2.0

バージョン 3.2 で追加.

math.erfc(x)

x の相補誤差関数を返します。相補誤差関数 は 1.0 - erf(x) と定義されます。この関数は、1との引き算では 桁落ち をするような大きな x に対し使われます。

バージョン 3.2 で追加.

math.gamma(x)

x の ガンマ関数 を返します。

バージョン 3.2 で追加.

math.lgamma(x)

x のガンマ関数の絶対値の自然対数を返します。

バージョン 3.2 で追加.

定数

math.pi

The mathematical constant π = 3.141592..., to available precision.

math.e

The mathematical constant e = 2.718281..., to available precision.

math.tau

The mathematical constant τ = 6.283185..., to available precision. Tau is a circle constant equal to 2π, the ratio of a circle's circumference to its radius. To learn more about Tau, check out Vi Hart's video Pi is (still) Wrong, and start celebrating Tau day by eating twice as much pie!

バージョン 3.6 で追加.

math.inf

浮動小数の正の無限大です。(負の無限大には -math.inf を使います。) float('inf') の出力と等価です。

バージョン 3.5 で追加.

math.nan

浮動小数の非数 "not a number" (NaN) です。float('nan') の出力と等価です。

バージョン 3.5 で追加.

CPython implementation detail: 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 --- 複素数のための数学関数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 数値と数学モジュール »

cmath --- 複素数のための数学関数

このモジュールは常に利用可能です。提供しているのは複素数を扱う数学関数へのアクセスです。このモジュール中の関数は整数、浮動小数点数または複素数を引数にとります。また、 __complex__() または __float__() どちらかのメソッドを提供している Python オブジェクトも受け付けます。これらのメソッドはそのオブジェクトを複素数または浮動小数点数に変換するのにそれぞれ使われ、呼び出された関数はそうして変換された結果を利用します。

注釈

ハードウェア及びシステムレベルでの符号付きゼロのサポートがあるプラットフォームでは、分枝切断 (branch cut) の関わる関数において切断された 両側 の分枝で連続になります。ゼロの符号でどちらの分枝であるかを区別するのです。符号付きゼロがサポートされないプラットフォームでは連続性は以下の仕様で述べるようになります。

極座標変換

Python の複素数 z は内部的には 直交座標 もしくは デカルト座標 と呼ばれる座標を使って格納されています。この座標はその複素数の 実部 z.real と 虚部 z.imag で決まります。言い換えると:

z == z.real + z.imag*1j

極座標 は複素数を表現する別の方法です。極座標では、複素数 z は半径 r と位相角 phi で定義されます。半径 r は z から原点までの距離です。位相 phi は x 軸の正の部分から原点と z を結んだ線分までの角度を反時計回りにラジアンで測った値です。

次の関数はネイティブの直交座標を極座標に変換したりその逆を行うのに使えます。

cmath.phase(x)

Return the phase of x (also known as the argument of x), as a float. phase(x) is equivalent to math.atan2(x.imag, x.real). The result lies in the range [-π, π], and the branch cut for this operation lies along the negative real axis, continuous from above. On systems with support for signed zeros (which includes most systems in current use), this means that the sign of the result is the same as the sign of x.imag, even when x.imag is zero:

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

Return e raised to the power x, where e is the base of natural logarithms.

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 を返します。

バージョン 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 は自身とのみ近いと見なされます。

バージョン 3.5 で追加.

参考

PEP 485 -- A function for testing approximate equality

定数

cmath.pi

定数 π (円周率)で、浮動小数点数です。

cmath.e

定数 e (自然対数の底)で、浮動小数点数です。

cmath.tau

数学定数 τ で、浮動小数点数です。

バージョン 3.6 で追加.

cmath.inf

浮動小数点数の正の無限大です。float('inf') と等価です。

バージョン 3.6 で追加.

cmath.infj

実部がゼロ、虚部が正の無限大の複素数です。complex(0.0, float('inf')) と等価です。

バージョン 3.6 で追加.

cmath.nan

浮動小数点数の非数 "not a number" (NaN) です。float('nan') と等価です。

バージョン 3.6 で追加.

cmath.nanj

実部がゼロ、虚部が NaN の複素数です。complex(0.0, float('nan')) と等価です。

バージョン 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 --- 十進固定及び浮動小数点数の算術演算

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 数値と数学モジュール »

decimal --- 十進固定及び浮動小数点数の算術演算

ソースコード: 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。

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

普通、 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

バージョン 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 を送出します。

バージョン 3.6 で追加.

as_tuple()

数値を表現するための名前付きタプル(named 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')
from_float(f)

浮動小数点数を正確に小数に変換するクラスメソッドです。

なお、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')

バージョン 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)

数値を正規化 (normalize) して、右端に連続しているゼロを除去し、 Decimal('0') と同じ結果はすべて Decimal('0e0') に変換します。等価クラスの属性から基準表現を生成する際に用います。たとえば、 Decimal('32.100') と Decimal('0.321000e+2') の正規化は、いずれも同じ値 Decimal('32.1') になります。

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)

with 文の入口でアクティブなスレッドのコンテキストを ctx のコピーに設定し、with 文を抜ける時に元のコンテキストに復旧する、コンテキストマネージャを返します。コンテキストが指定されなければ、現在のコンテキストのコピーが使われます。

たとえば、以下のコードでは精度を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

新たなコンテキストは、以下で説明する 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 コンストラクタが生成する新たなコンテキストに影響を及ぼします。

このコンテキストは、主に多重スレッド環境で便利です。スレッドを開始する前に何らかのフィールドを変更しておくと、システム全体のデフォルト設定に効果を及ぼすことができます。スレッドを開始した後にフィールドを変更すると、競合条件を抑制するためにスレッドを同期化しなければならないので、推奨しません。

単一スレッドの環境では、このコンテキストを使わないよう薦めます。下で述べるように明示的にコンテキストを作成してください。

デフォルトの値は、 prec=28, 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 にリセットします。

バージョン 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

バージョン 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 バージョンにおいて正しく丸められます。

バージョン 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 がスレッド無しでコンパイルされている場合、C 版は自動的にコストがかかるスレッドローカルなコンテキスト機構を使用不可にします。この場合、値は False です。

丸めモード

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

数値オーバフローを示すシグナルです。

このシグナルは、値丸めを行った後の指数部が 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. ある種の十進数値はいつも指数表記で表示されます。指数表記以外の表示にする方法はありますか?

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')

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 数値と数学モジュール »


fractions --- 有理数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 数値と数学モジュール »

fractions --- 有理数

ソースコード: 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)

最初のバージョンは numerator と denominator が numbers.Rational のインスタンスであることを要求し、 numerator/denominator の値を持つ新しい Fraction インスタンスを返します。 denominator が 0 ならば、 ZeroDivisionError を送出します。二番目のバージョンは other_fraction が numbers.Rational のインスタンスであることを要求し、同じ値を持つ新しい Fraction インスタンスを返します。その次の二つのバージョンは、 float と decimal.Decimal インスタンスを受け付け、それとちょうど同じ値を持つ Fraction インスタンスを返します。なお、二進浮動小数点数にお決まりの問題 (浮動小数点演算、その問題と制限 参照) のため、 Fraction(1.1) の引数は 11/10 と正確に等しいとは言えないので、 Fraction(1.1) は予期した通りの Fraction(11, 10) を返 しません 。(ただし、以下の limit_denominator() メソッドのドキュメントを参照してください。)最後のバージョンは、文字列またはユニコードのインスタンスを渡されることを想定します。このインスタンスは、通常、次のような形式です:

[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 インスタンスを受け付けるようになりました。

numerator

有理数を既約分数で表したときの分子。

denominator

有理数を既約分数で表したときの分母。

from_float(flt)

このクラスメソッドは float である flt の正確な値を表す Fraction を構築します。 Fraction.from_float(0.3) と Fraction(3, 10) の値は同じでないことに注意してください 。

注釈

Python 3.2 以降では、 float から直接 Fraction インスタンスを構築できるようになりました。

from_decimal(dec)

このクラスメソッドは decimal.Decimal インスタンスである dec の正確な値を表す Fraction を構築します。

注釈

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() 関数からでもアクセスできます。

fractions.gcd(a, b)

整数 a と b の最大公約数を返します。a も b もゼロでないとすると、gcd(a, b) の絶対値は a と b の両方を割り切る最も大きな整数です。gcd(a, b) は b がゼロでなければ b と同じ符号になります。そうでなければ a の符号を取ります。gcd(0, 0) は 0 を返します。

バージョン 3.5 で非推奨: 代わりに math.gcd() を使用してください。

参考

numbers モジュール
数値の塔を作り上げる抽象基底クラス。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 数値と数学モジュール »


random --- 擬似乱数を生成する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 数値と数学モジュール »

random --- 擬似乱数を生成する

ソースコード: Lib/random.py

このモジュールでは様々な分布をもつ擬似乱数生成器を実装しています。

整数用に、ある範囲からの一様な選択があります。シーケンス用には、シーケンスからのランダムな要素の一様な選択、リストのランダムな置換をインプレースに生成する関数、順列を置換せずにランダムサンプリングする関数があります。

実数用としては、一様分布、正規分布 (ガウス分布)、対数正規分布、負の指数分布、ガンマおよびベータ分布を計算する関数があります。角度の分布を生成するにはフォン・ミーゼス分布が利用できます。

ほとんど全てのモジュール関数は、基礎となる関数 random() に依存します。この関数はランダムな浮動小数点数を半開区間 [0.0, 1.0) 内に一様に生成します。Python は中心となる乱数生成器としてメルセンヌツイスタを使います。これは 53 ビット精度の浮動小数点を生成し、周期は 2**19937-1 です。本体は C で実装されていて、高速でスレッドセーフです。メルセンヌツイスタは、現存する中で最も広範囲にテストされた乱数生成器のひとつです。しかしながら、メルセンヌツイスタは完全に決定論的であるため、全ての目的に合致しているわけではなく、暗号化の目的には全く向いていません。

このモジュールで提供されている関数は、実際には random.Random クラスの隠蔽されたインスタンスのメソッドに束縛されています。内部状態を共有しない生成器を取得するため、自分で Random のインスタンスを生成することができます。

自分で考案した基本乱数生成器を使いたい場合、クラス Random をサブクラス化することもできます。この場合、メソッド random()、seed()、getstate()、setstate() をオーバライドしてください。オプションとして、新しいジェネレータは getrandbits() メソッドを提供することができます。これにより randrange() メソッドが任意に大きな範囲から選択を行えるようになります。

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 長い周期と比較的シンプルな更新操作を備えた互換性のある別の乱数生成器。

保守 (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スキームに移行。

random.getstate()

乱数生成器の現在の内部状態を記憶したオブジェクトを返します。このオブジェクトを setstate() に渡して内部状態を復元することができます。

random.setstate(state)

state は予め getstate() を呼び出して得ておかなくてはなりません。 setstate() は getstate() が呼び出された時の乱数生成器の内部状態を復元します。

random.getrandbits(k)

k 桁の乱数ビットで Python の整数を生成し、返します。このメソッドはメルセンヌツイスタ生成器で提供されており、その他の乱数生成器でもオプションの API として提供されている場合があります。randrange() メソッドを使用できる場合、getrandbits() はそのメソッドを有効にし、任意の大きな範囲を扱えるようになります。

整数用の関数

random.randrange(stop)
random.randrange(start, stop[, step])

range(start, stop, step) の要素からランダムに選ばれた要素を返します。この関数は choice(range(start, stop, step)) と等価ですが、実際には range オブジェクトを生成しません。

位置引数のパターンは range() のそれと一致します。キーワード引数は、この関数に望まれない方法で使われるかもしれないので、使うべきではありません。

バージョン 3.2 で変更: 一様に分布した値の生成に関して randrange() がより洗練されました。以前は int(random()*n) のようなやや一様でない分布を生成するスタイルを使用していました。

random.randint(a, b)

a <= N <= b であるようなランダムな整数 N を返します。randrange(a, b+1) のエイリアスです。

シーケンス用の関数

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 は除きます)。

バージョン 3.6 で追加.

random.shuffle(x[, random])

シーケンス x をインプレースにシャッフルします。

オプション引数 random は [0.0, 1.0) の範囲のランダムな浮動小数を返す引数なしの関数です。デフォルトでは random() 関数です。

イミュータブルなシーケンスをシャッフルしてシャッフルされたリストを新たに返すには、代わりに sample(x, k=len(x)) を使用してください。

たとえ len(x) が小さくても、x の並べ替えの総数 (訳注: 要素数の階乗) は大半の乱数生成器の周期よりもすぐに大きくなることに注意してください。つまり、長いシーケンスの大半の並べ替えは決して生成されないだろう、ということです。例えば、長さ 2080 のシーケンスがメルセンヌツイスタ生成器の周期に収まる中で最大のものになります。

random.sample(population, k)

母集団のシーケンスまたは集合から選ばれた長さ k の一意な要素からなるリストを返します。重複無しのランダムサンプリングに用いられます。

母集団自体を変更せずに、母集団内の要素を含む新たなリストを返します。返されたリストは選択された順に並んでいるので、このリストの部分スライスもランダムなサンプルになります。これにより、くじの当選者 (サンプル) を1等賞と2等賞（の部分スライス）に分けることも可能です。

母集団の要素は ハッシュ可能 でなくても、ユニークでなくてもかまいません。母集団が繰り返しを含む場合、出現するそれぞれがサンプルに選択されえます。

ある範囲の整数からサンプルを取る場合、引数に range() オブジェクトを使用してください。大きな母集団の場合、これは特に速く、メモリ効率が良いです: sample(range(10000000), k=60)。

サンプルの大きさが母集団の大きさより大きい場合 ValueError が送出されます。

実数分布

以下の関数は特定の実数値分布を生成します。関数の引数の名前は、一般的な数学の慣例で使われている分布の公式の対応する変数から取られています; これらの公式のほとんどはどんな統計学のテキストにも載っています。

random.random()

次のランダムな浮動小数点数（範囲は [0.0, 1.0) ）を返します。

random.uniform(a, b)

a <= b であれば a <= N <= b 、b < a であれば b <= N <= a であるようなランダムな浮動小数点数 N を返します。

端点の値 b が範囲に含まれるかどうかは、等式 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)

指数分布です。lambd は平均にしたい値の逆数です。(この引数は "lambda" と呼ぶべきなのですが、Python の予約語なので使えません。) 返す値の範囲は lambd が正なら 0 から正の無限大、lambd が負なら負の無限大から 0 です。

random.gammavariate(alpha, beta)

ガンマ分布です (ガンマ関数 ではありません ！)。引数の満たすべき条件は alpha > 0 および beta > 0 です。

確率分布関数は:

          x ** (alpha - 1) * math.exp(-x / beta)
pdf(x) =  --------------------------------------
            math.gamma(alpha) * beta ** alpha
random.gauss(mu, sigma)

ガウス分布です。 mu は平均であり、 sigma は標準偏差です。この関数は後で定義する関数 normalvariate() より少しだけ高速です。

random.lognormvariate(mu, sigma)

対数正規分布です。この分布を自然対数を用いた分布にした場合、平均 mu で標準偏差 sigma の正規分布になります。 mu は任意の値を取ることができ、sigma はゼロより大きくなければなりません。

random.normalvariate(mu, sigma)

正規分布です。 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.SystemRandom([seed])

オペレーティングシステムの提供する発生源によって乱数を生成する os.urandom() 関数を使うクラスです。すべてのシステムで使えるメソッドではありません。ソフトウェアの状態に依存してはいけませんし、一連の操作は再現不能です。従って、 seed() メソッドは何の影響も及ぼさず、無視されます。 getstate() と setstate() メソッドが呼び出されると、例外 NotImplementedError が送出されます。

再現性について

疑似乱数生成器から与えられたシーケンスを再現できると便利なことがあります。シード値を再利用することで、複数のスレッドが実行されていない限り、実行ごとに同じシーケンスが再現できます。

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
>>> # (a ten, jack, queen, or king).
>>> deck = collections.Counter(tens=16, low_cards=36)
>>> seen = sample(list(deck.elements()), k=20)
>>> seen.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.
>>> trial = lambda: choices('HT', cum_weights=(0.60, 1.00), k=7).count('H') >= 5
>>> sum(trial() for i in range(10000)) / 10000
0.4169

>>> # Probability of the median of 5 samples being in middle two quartiles
>>> trial = lambda : 2500 <= sorted(choices(range(10000), k=5))[2]  < 7500
>>> sum(trial() for i in range(10000)) / 10000
0.7958

5 サンプルの平均の信頼区間を推定するのに、重複ありでリサンプリングして 統計的ブートストラップ を行う例:

# http://statistics.about.com/od/Applications/a/Example-Of-Bootstrapping.htm
from statistics import mean
from random import choices

data = 1, 2, 4, 4, 10
means = sorted(mean(choices(data, k=5)) for i in range(20))
print(f'The sample mean of {mean(data):.1f} has a 90% confidence '
      f'interval from {means[1]:.1f} to {means[-2]:.1f}')

薬と偽薬の間に観察された効果の違いについて、統計的有意性、すなわち p 値 を決定するために、リサンプリング順列試験 を行う例:

# Example from "Statistics is Easy" by Dennis Shasha and Manda Wilson
from statistics import 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 = 10000
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 random import expovariate, gauss
from statistics import mean, median, stdev

average_arrival_interval = 5.6
average_service_time = 5.0
stdev_service_time = 0.5

num_waiting = 0
arrivals = []
starts = []
arrival = service_end = 0.0
for i in range(20000):
    if arrival <= service_end:
        num_waiting += 1
        arrival += expovariate(1.0 / average_arrival_interval)
        arrivals.append(arrival)
    else:
        num_waiting -= 1
        service_start = service_end if num_waiting else arrival
        service_time = gauss(average_service_time, stdev_service_time)
        service_end = service_start + service_time
        starts.append(service_start)

waits = [start - arrival for arrival, start in zip(arrivals, starts)]
print(f'Mean wait: {mean(waits):.1f}.  Stdev wait: {stdev(waits):.1f}.')
print(f'Median wait: {median(waits):.1f}.  Max wait: {max(waits):.1f}.')

参考

Statistics for Hackers Jake Vanderplas による統計解析のビデオ。シミュレーション、サンプリング、シャッフル、交差検定といった基本的な概念のみを用いています。

Economics Simulation Peter Norvig による市場価格のシミュレーション。このモジュールが提供する多くのツールや分布 (gauss, uniform, sample, betavariate, choice, triangular, randrange) の活用法を示しています。

A Concrete Introduction to Probability (using Python) Peter Norvig によるチュートリアル。確率論の基礎、シミュレーションの書き方、Python を使用したデータ解析法をカバーしています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 数値と数学モジュール »


statistics --- 数理統計関数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 数値と数学モジュール »

statistics --- 数理統計関数

バージョン 3.4 で追加.

ソースコード: Lib/statistics.py

このモジュールは、数値 (Real 型) データを数学的に統計計算するための関数を提供します。

注釈

特に明記しない限り、これらの関数は int, float, decimal.Decimal そして fractions.Fraction をサポートします。他の型 (算術型及びそれ以外) は現在サポートされていません。混合型 (mixed type) も未定義で実装依存です。入力データが混合型を含んでいる場合、map() を使用すると正しい結果が得られるでしょう。 e.g. map(float, input_data)。

平均及び中心位置の測度

これらの関数は母集団または標本の平均値や標準値を計算します。

mean() | データの算術平均。
harmonic_mean() | データの調和平均。
median() | データの中央値。
median_low() | データの low median。
median_high() | データの high median。
median_grouped() | grouped data の中央値、すなわち50パーセンタイル。
mode() | 離散データの最頻値。

分散の測度

これらの関数は母集団または標本が標準値や平均値からどれくらい離れているかについて計算します。

pstdev() | データの母標準偏差。
pvariance() | データの母分散。
stdev() | データの標本標準偏差。
variance() | データの標本標準分散。

関数の詳細

註釈: 関数の引数となるデータをソートしておく必要はありません。例の多くがソートされているのは見やすさのためです。

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')

注釈

平均値は外れ値に大きく影響を受けるため、中心位置のロバストな推定量ではありません。すなわち、平均値はデータ点の代表例では必ずしもありません。よりロバストですが低効率な中心位置の測度には median() および mode() があります。 ("効率" は計算効率ではなく統計効率を指します。)

標本平均は真の母平均の不偏推定量です。すなわち、出来る限り多くの標本から平均を求めると、mean(sample) は真の母平均に収束します (訳注: 大数の法則)。data が標本ではなく母集団全体の場合、mean(data) は真の母平均 μ を計算することと等価です。

statistics.harmonic_mean(data)

実数値のシーケンス型またはイテレータの data の調和平均を返します。

調和平均（harmonic mean, subcontrary mean）は、データの逆数の算術平均の逆数です。例えば、3つの値 a, b, c の調和平均は``3/(1/a + 1/b + 1/c)`` になります。

調和平均は平均の一種で、データの中心位置の測度です。速度のような率(rates)や比(ratios)の量を平均するときにしばしば適切です。例えば、

投資家がP / E（価格/収益）の比率が2.5,3,10という3つの会社のそれぞれに等しい価値の株式を購入したとします。投資家のポートフォリオの平均P / Eの比率はいくつでしょうか？

>>> harmonic_mean([2.5, 3, 10])  # For an equal investment portfolio.
3.6

算術平均を使うと平均は約5.167になり、高すぎる値になります。

もし data が空の場合、またはいずれの要素が0より小さい場合、例外 StatisticsError が送出されます。

バージョン 3.6 で追加.

statistics.median(data)

一般的な「中央2つの平均をとる」方法を使用して、数値データの中央値（中間値）を返します。もし data が空の場合、例外 StatisticsError が送出されます。data はシーケンス型またはイテレータにもなれます。

中央値は外れ値の影響を受けにくいため、中心位置のロバストな測度です。データ数が奇数の場合は中央の値を返します:

>>> median([1, 3, 5])
3

データ数が偶数の場合は、中央値は中央に最も近い2値の算術平均で補間されます:

>>> median([1, 3, 5, 7])
4.0

データが離散的で、中央値がデータ点にない値でも構わない場合に適しています。

もしあなたのデータが（注文操作をサポートする）序数で、（追加操作をサポートしない）数値でないならば、代わりに median_low() または median_high() を使うべきです。

参考

median_low(), median_high(), median_grouped()

statistics.median_low(data)

数値データの小さい方の中央値(low median)を返します。もし data が空の場合、:exc:`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)

補間を使用して、50番目のパーセンタイルとして計算されたグループ化された連続データの中央値を返します。もし data が空の場合、StatisticsError が送出されます。data はシーケンス型やイテレータにもなれます。

>>> median_grouped([52, 52, 53, 54])
52.5

次の例ではデータは丸められているため、各値はデータの中間です。例えば 1 は 0.5 と 1.5 の中間、2 は 1.5 と 2.5 の中間、3 は 2.5 と 3.5 の中間です。例では中央の値は 3.5 から 4.5 で、補間により推定されます:

>>> median_grouped([1, 2, 2, 3, 4, 4, 4, 4, 4, 5])
3.7

interval は間隔を表します。デフォルトは1です。間隔を変えると当然補間値は変わります:

>>> median_grouped([1, 3, 3, 5, 7], interval=1)
3.25
>>> median_grouped([1, 3, 3, 5, 7], interval=2)
3.5

この関数はデータ点が少なくとも interval だけ差があるかどうかチェックしません。

CPython implementation detail: 環境によっては median_grouped() はデータ点を強制的に浮動小数点に変換します。この挙動はいずれ変更されるでしょう。

参考

  • "Statistics for the Behavioral Sciences", Frederick J Gravetter and Larry B Wallnau (8th Edition).
  • The SSMEDIAN function in the Gnome Gnumeric spreadsheet, including this discussion.
statistics.mode(data)

離散データや名目データ data の最頻値を返します。最頻値は (存在するときは) 最も標準的な値で、中心位置のロバストな測度です。

data が空の場合や最頻値が1つでない場合 StatisticsError を送出します。

mode は離散データであることを想定していて、1つの値を返します。これは学校で教わるような最頻値の標準的な取扱いです:

>>> mode([1, 1, 2, 3, 3, 3, 3, 4])
3

最頻値は (数値でない) 名目データにも適用出来る統計量という点でユニークです:

>>> mode(["red", "blue", "blue", "red", "green", "red", "red"])
'red'
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 は実数の空でない iterable です。分散、すなわち2次の中心化モーメントはデータの散らばり具合の測度です。分散が大きいデータはばらつきが大きく、分散が小さいデータは平均値のまわりに固まっています。

第2引数 mu に値を渡す場合は data の平均値でなくてはなりません。mu が与えられない場合や None の場合 (デフォルト)、平均値は自動的に計算されます。

母集団全体から分散を計算する場合に用いてください。標本から分散を推定する場合は 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

この関数は引数として渡した mu が実際の平均値かどうかチェックしません。任意の値を mu に渡すと無効な結果やありえない結果が返ることがあります。

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 の分散を返します。

何らかの方法で真の母平均 μ を知っている場合、それを第2引数に渡して標本の分散を計算することが出来ます。与えられたデータ点が代表的 (たとえば独立で均等に分布) な場合、戻り値は母分散の不偏推定量になります。

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次の中心化モーメントはデータの散らばり具合の測度です。分散が大きいデータはばらつきが大きく、分散が小さいデータは平均値のまわりに固まっています。

第2引数 xbar に値を渡す場合は data の平均値でなくてはなりません。xbar が与えられない場合や None の場合 (デフォルト)、平均値は自動的に計算されます。

データが母集団の標本であるときに用いてください。母集団全体から分散を計算するには pvariance() を参照してください。

data の値が2より少ない場合 StatisticsError を送出します。

例:

>>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
>>> variance(data)
1.3720238095238095

既にデータの平均値を計算している場合、それを第2引数 xbar に渡して再計算を避けることが出来ます:

>>> 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 に渡して標本の分散を計算することが出来ます。

例外

例外が1つ定義されています:

exception statistics.StatisticsError

統計関係の例外。ValueError の派生クラス。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 数値と数学モジュール »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

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

この章では、関数型プログラミングスタイルをサポートする呼び出し可能で汎用な操作を実現する関数やクラスについて説明します。

この章では以下のモジュールが解説されています:

  • itertools --- 効率的なループ実行のためのイテレータ生成関数
    • Itertool関数
    • Itertools レシピ
  • functools --- 高階関数と呼び出し可能オブジェクトの操作
    • partial オブジェクト
  • operator --- 関数形式の標準演算子
    • 演算子から関数への対応表
    • インプレース演算子

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


itertools --- 効率的なループ実行のためのイテレータ生成関数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 関数型プログラミング用モジュール »

itertools --- 効率的なループ実行のためのイテレータ生成関数

このモジュールは イテレータ を構築する部品を実装しています。プログラム言語 APL, Haskell, SML からアイデアを得ていますが、 Python に適した形に修正されています。

このモジュールは、高速でメモリ効率に優れ、単独でも組合せても使用することのできるツールを標準化したものです。同時に、このツール群は "イテレータの代数" を構成していて、pure Python で簡潔かつ効率的なツールを作れるようにしています。

例えば、SML の作表ツール tabulate(f) は f(0), f(1), ... のシーケンスを作成します。同じことを Python では map() と count() を組合せて map(f, count()) という形で実現できます。

これらのツールと組み込み関数は operator モジュール内の高速な関数とともに使うことで見事に動作します。例えば、乗算演算子を2つのベクトルにわたってマップすることで効率的な内積計算を実現できます: sum(map(operator.mul, vector1, vector2)) 。

Infinite iterators:

イテレータ | 引数 | 結果 | 使用例
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
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() | pred, seq | seq[n], seq[n+1], pred が偽の場所から始まる | dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1
filterfalse() | pred, seq | pred(elem) が偽になるseqの要素 | filterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8
groupby() | iterable[, key] | sub-iterators grouped by value of key(v) |
islice() | seq, [start,] stop [, step] | seq[start:stop:step] | islice('ABCDEFG', 2, None) --> C D E F G
starmap() | func, seq | func(*seq[0]), func(*seq[1]), ... | starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000
takewhile() | pred, seq | seq[0], seq[1], pred が偽になるまで | 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-

Combinatoric iterators:

イテレータ | 引数 | 結果
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])

累計や加算ではない (func オプション引数で指定される) 2変数関数による累積結果を返すイテレータを作成します。 func が与えられた場合、2つの引数を取る関数でなければなりません。 入力 iterable の要素は、 func が引数として取れる型を持ちます。 (例えば、デフォルトの演算の加算では、要素は Decimal や Fraction を含む、加算ができる型を持ちます。) 入力のイテラブルが空の場合は、出力のイテラブルも空になります。

およそ次と等価です:

def accumulate(iterable, func=operator.add):
    'Return running totals'
    # accumulate([1,2,3,4,5]) --> 1 3 6 10 15
    # accumulate([1,2,3,4,5], operator.mul) --> 1 2 6 24 120
    it = iter(iterable)
    try:
        total = next(it)
    except StopIteration:
        return
    yield total
    for element in it:
        total = func(total, element)
        yield total

func 引数の利用法はたくさんあります。最小値にするために min() を、最大値にするために max() を、積にするために operator.mul() を使うことができます。金利を累積し支払いを適用して償還表を作成することもできます。初期値をイテラブルに与えて func 引数で累積和を利用するだけで一階の 漸化式 をモデル化できます:

>>> 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 4 annual payments of 90
>>> cashflows = [1000, -90, -90, -90, -90]
>>> list(accumulate(cashflows, lambda bal, pmt: bal*1.05 + pmt))
[1000, 960.0, 918.0, 873.9000000000001, 827.5950000000001]

# Chaotic recurrence relation https://en.wikipedia.org/wiki/Logistic_map
>>> logistic_map = lambda x, _:  r * x * (1 - x)
>>> r = 3.8
>>> x0 = 0.4
>>> inputs = repeat(x0, 36)     # only the initial value is used
>>> [format(x, '.2f') for x in accumulate(inputs, logistic_map)]
['0.40', '0.91', '0.30', '0.81', '0.60', '0.92', '0.29', '0.79', '0.63',
 '0.88', '0.39', '0.90', '0.33', '0.84', '0.52', '0.95', '0.18', '0.57',
 '0.93', '0.25', '0.71', '0.79', '0.63', '0.88', '0.39', '0.91', '0.32',
 '0.83', '0.54', '0.95', '0.20', '0.60', '0.91', '0.30', '0.80', '0.60']

最終的な累積値だけを返す類似の関数については functools.reduce() を見てください。

バージョン 3.2 で追加.

バージョン 3.3 で変更: オプションの func 引数が追加されました。

itertools.chain(*iterables)

先頭の iterable の全要素を返し、次に2番目の iterable の全要素を返し、と全 iterable の要素を返すイテレータを作成します。連続したシーケンスを一つのシーケンスとして扱う場合に使用します。およそ次と等価です:

def chain(*iterables):
    # chain('ABC', 'DEF') --> A B C D E F
    for it in iterables:
        for element in it:
            yield element
classmethod chain.from_iterable(iterable)

chain() のためのもう一つのコンストラクタです。遅延評価される iterable 引数一つから連鎖した入力を受け取ります。この関数は、以下のコードとほぼ等価です:

def from_iterable(iterables):
    # chain.from_iterable(['ABC', 'DEF']) --> A B C D E F
    for it in iterables:
        for element in it:
            yield element
itertools.combinations(iterable, r)

入力 iterable の要素からなる長さ r の部分列を返します。

組合せは辞書式順序で出力されます。したがって、入力 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 の要素の部分列を返します。

組合せは辞書式順序で出力されます。したがって、入力 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)! です。

バージョン 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)

バージョン 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 が False となる要素だけを返すイテレータを作成します。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])

iterable から要素を選択して返すイテレータを作成します。 start が0でない場合、iterable の要素は start に達するまでスキップされます。その後、 要素が順に返されます。

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, stop, step = s.start or 0, s.stop or sys.maxsize, s.step or 1
    it = iter(range(start, stop, step))
    try:
        nexti = next(it)
    except StopIteration:
        # Consume *iterable* up to the *start* position.
        for i, element in zip(range(start), iterable):
            pass
        return
    try:
        for i, element in enumerate(iterable):
            if i == nexti:
                yield element
                nexti = next(it)
    except StopIteration:
        # Consume to *stop*.
        for i, element in zip(range(i + 1, stop), iterable):
            pass

start が None の場合、イテレーションは0から始まります。step が None の場合、ステップはデフォルトの1になります。

itertools.permutations(iterable, r=None)

iterable の要素からなる長さ r の順列 (permutation) を連続的に返します。

r が指定されない場合や None の場合、r はデフォルトで iterable の長さとなり、可能な最長の順列の全てが生成されます。

順列は辞書ソートの順番で出力されます。したがって入力の iterable がソートされていた場合、順列のタプルはソートされた状態で出力されます。

要素は値ではなく位置に基づいて一意的に扱われます。したがって入力された要素が全て異なっている場合、それぞれの順列に重複した要素が現れないことになります。

およそ次と等価です:

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(*args, 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 args] * repeat
    result = [[]]
    for pool in pools:
        result = [x+[y] for x in result for y in pool]
    for prod in result:
        yield tuple(prod)
itertools.repeat(object[, times])

繰り返し object を返すイテレータを作成します。 times 引数を指定しなければ、無限に値を返し続けます。map() の引数にして、呼び出された関数に同じ引数を渡すのに使います。また zip() と使って、タプルの変わらない部分を作ります。

およそ次と等価です:

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)

iterable の要素を引数として funtion を計算するイテレータを作成します。 function の引数が一つの iterable からタプルに既にグループ化されている (データが "zip済み") 場合、map() の代わりに使用します。map() と starmap() の違いは function(a,b) と function(*c) の差に似ています。およそ次と等価です:

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
itertools.tee(iterable, n=2)

一つの iterable から n 個の独立したイテレータを返します。

以下の Python コードは tee がすることについての理解を助けるでしょう (ただし実際の実装はより複雑で、下層の FIFO キューを一つしか使いませんが)。

およそ次と等価です:

def tee(iterable, n=2):
    it = iter(iterable)
    deques = [collections.deque() for i in range(n)]
    def gen(mydeque):
        while True:
            if not mydeque:             # when the local deque is empty
                try:
                    newval = next(it)   # fetch a new value and
                except StopIteration:
                    return
                for d in deques:        # load it to all the deques
                    d.append(newval)
            yield mydeque.popleft()
    return tuple(gen(d) for d in deques)

一度 tee() でイテレータを分割すると、もとの iterable を他で使ってはいけません。さもなければ、 tee() オブジェクトの知らない間に iterable が先の要素に進んでしまうことになります。

tee() はかなり大きなメモリ領域を使用するかもしれません (使用するメモリ量はiterableの大きさに依存します)。一般には、一つのイテレータが他のイテレータよりも先にほとんどまたは全ての要素を消費するような場合には、 tee() よりも list() を使った方が高速です。

itertools.zip_longest(*iterables, fillvalue=None)

各 iterable の要素をまとめるイテレータを作成します。iterable の長さが違う場合、足りない値は fillvalue で埋められます。最も長い itarable が尽きるまでイテレーションします。およそ次と等価です:

def zip_longest(*args, fillvalue=None):
    # zip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-
    iterators = [iter(it) for it in args]
    num_active = len(iterators)
    if not num_active:
        return
    while True:
        values = []
        for i, it in enumerate(iterators):
            try:
                value = next(it)
            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 を素材としてツールセットを拡張するためのレシピを示します。

iterable 全体を一度にメモリ上に置くよりも、要素を一つづつ処理する方がメモリ効率上の有利さを保てます。関数形式のままツールをリンクしてゆくと、コードのサイズを減らし、一時変数を減らす助けになります。インタプリタのオーバヘッドをもたらす for ループやジェネレータ(generator) を使わずに、 "ベクトル化された" ビルディングブロックを使うと、高速な処理を実現できます。

def take(n, iterable):
    "Return first n items of the iterable as a list"
    return list(islice(iterable, n))

def prepend(value, iterator):
    "Prepend a single value in front of an iterator"
    # prepend(1, [2, 3, 4]) -> 1 2 3 4
    return chain([value], iterator)

def tabulate(function, start=0):
    "Return function(0), function(1), ..."
    return map(function, count(start))

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:
        # feed the entire iterator into a zero-length deque
        collections.deque(iterator, maxlen=0)
    else:
        # advance to the empty slice starting at position n
        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 all_equal(iterable):
    "Returns True if all the elements are equal to each other"
    g = groupby(iterable)
    return next(g, True) and not next(g, False)

def quantify(iterable, pred=bool):
    "Count how many times the predicate is true"
    return sum(map(pred, iterable))

def padnone(iterable):
    """Returns the sequence elements and then returns None indefinitely.

    Useful for emulating the behavior of the built-in map() function.
    """
    return chain(iterable, repeat(None))

def ncycles(iterable, n):
    "Returns the sequence elements n times"
    return chain.from_iterable(repeat(tuple(iterable), n))

def dotproduct(vec1, vec2):
    return sum(map(operator.mul, vec1, vec2))

def flatten(listOfLists):
    "Flatten one level of nesting"
    return chain.from_iterable(listOfLists)

def repeatfunc(func, times=None, *args):
    """Repeat calls to func with specified arguments.

    Example:  repeatfunc(random.random)
    """
    if times is None:
        return starmap(func, repeat(args))
    return starmap(func, repeat(args, times))

def pairwise(iterable):
    "s -> (s0,s1), (s1,s2), (s2, s3), ..."
    a, b = tee(iterable)
    next(b, None)
    return zip(a, b)

def grouper(iterable, n, fillvalue=None):
    "Collect data into fixed-length chunks or blocks"
    # grouper('ABCDEFG', 3, 'x') --> ABC DEF Gxx"
    args = [iter(iterable)] * n
    return zip_longest(*args, fillvalue=fillvalue)

def roundrobin(*iterables):
    "roundrobin('ABC', 'D', 'EF') --> A D E B F C"
    # Recipe credited to George Sakkis
    num_active = len(iterables)
    nexts = cycle(iter(it).__next__ for it in iterables)
    while num_active:
        try:
            for next in nexts:
                yield next()
        except StopIteration:
            # Remove the iterator we just exhausted from the cycle.
            num_active -= 1
            nexts = cycle(islice(nexts, num_active))

def partition(pred, iterable):
    'Use a predicate to partition entries into false entries and true entries'
    # partition(is_odd, range(10)) --> 0 2 4 6 8   and  1 3 5 7 9
    t1, t2 = tee(iterable)
    return filterfalse(pred, t1), filter(pred, t2)

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 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.lower) --> A B C D
    seen = set()
    seen_add = seen.add
    if key is None:
        for element in filterfalse(seen.__contains__, iterable):
            seen_add(element)
            yield element
    else:
        for element in iterable:
            k = key(element)
            if k not in seen:
                seen_add(k)
                yield element

def unique_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.lower) --> A B C A D
    return map(next, map(itemgetter(1), groupby(iterable, key)))

def iter_except(func, exception, first=None):
    """ Call a function repeatedly until an exception is raised.

    Converts a call-until-exception interface to an iterator interface.
    Like builtins.iter(func, sentinel) but uses an exception instead
    of a sentinel to end the loop.

    Examples:
        iter_except(functools.partial(heappop, h), IndexError)   # priority queue iterator
        iter_except(d.popitem, KeyError)                         # non-blocking dict iterator
        iter_except(d.popleft, IndexError)                       # non-blocking deque iterator
        iter_except(q.get_nowait, Queue.Empty)                   # loop over a producer Queue
        iter_except(s.pop, KeyError)                             # non-blocking set iterator

    """
    try:
        if first is not None:
            yield first()            # For database APIs needing an initial cast to db.first()
        while True:
            yield func()
    except exception:
        pass

def first_true(iterable, default=False, pred=None):
    """Returns the first true value in the iterable.

    If no true value is found, returns *default*

    If *pred* is not None, returns the first item
    for which pred(item) is true.

    """
    # first_true([a,b,c], x) --> a or b or c or x
    # first_true([a,b], x, f) --> a if f(a) else b if f(b) else x
    return next(filter(pred, iterable), default)

def random_product(*args, repeat=1):
    "Random selection from itertools.product(*args, **kwds)"
    pools = [tuple(pool) for pool in args] * repeat
    return tuple(random.choice(pool) for pool in 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):
    "Random selection from itertools.combinations_with_replacement(iterable, r)"
    pool = tuple(iterable)
    n = len(pool)
    indices = sorted(random.randrange(n) for i in range(r))
    return tuple(pool[i] for i in indices)

def nth_combination(iterable, r, index):
    'Equivalent to list(combinations(iterable, r))[index]'
    pool = tuple(iterable)
    n = len(pool)
    if r < 0 or r > n:
        raise ValueError
    c = 1
    k = min(r, n-r)
    for i in range(1, k+1):
        c = c * (n - k + i) // i
    if index < 0:
        index += c
    if index < 0 or index >= c:
        raise IndexError
    result = []
    while r:
        c, n, r = c*r//n, n-1, r-1
        while index >= c:
            index -= c
            c, n = c*(n-r)//n, n-1
        result.append(pool[-1-n])
    return tuple(result)

上記のレシピはデフォルト値を指定してグローバルな名前検索をローカル変数の検索に変えることで、より効率を上げることができます。例えば、dotproduct のレシピを書き換えるとすればこんな具合です:

def dotproduct(vec1, vec2, sum=sum, map=map, mul=operator.mul):
    return sum(map(mul, vec1, vec2))

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 関数型プログラミング用モジュール »


functools --- 高階関数と呼び出し可能オブジェクトの操作

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 関数型プログラミング用モジュール »

functools --- 高階関数と呼び出し可能オブジェクトの操作

ソースコード: Lib/functools.py

functools モジュールは高階関数、つまり関数に影響を及ぼしたり他の関数を返したりする関数のためのものです。一般に、どんな呼び出し可能オブジェクトでもこのモジュールの目的には関数として扱えます。

モジュール functools は以下の関数を定義します:

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

ソートの例と簡単なチュートリアルは ソート HOW TO を参照して下さい。

バージョン 3.2 で追加.

@functools.lru_cache(maxsize=128, typed=False)

関数をメモ化用の呼び出し可能オブジェクトでラップし、最近の呼び出し最大 maxsize 回まで保存するするデコレータです。高価な関数や I/O に束縛されている関数を定期的に同じ引数で呼び出すときに、時間を節約できます。

結果のキャッシュには辞書が使われるので、関数の位置引数およびキーワード引数はハッシュ可能でなくてはなりません。

引数のパターンが異なる場合は、異なる呼び出しと見なされ別々のキャッシュエントリーとなります。 例えば、 f(a=1, b=2) と f(b=2, a=1) はキーワード引数の順序が異なっているので、2つの別個のキャッシュエントリーになります。

maxsize が None に設定された場合は、LRU 機能は無効化され、キャッシュは際限無く大きくなります。 LRU 機能は maxsize が 2 の累乗であるときが最も効率的に動作します。

typed が真に設定された場合は、関数の異なる型の引数が別々にキャッシュされます。例えば、f(3) と f(3.0) は別の結果をもたらす別の呼び出しとして扱われます。

キャッシュ効率の測定や maxsize パラメータの調整をしやすくするため、ラップされた関数には cache_info() 関数が追加されます。この関数は hits, misses, maxsize, currsize を示す named tuple を返します。マルチスレッド環境では、hits と misses は概算です。

このデコレータは、キャッシュの削除と無効化のための cache_clear() 関数も提供します。

元々の基底の関数には、 __wrapped__ 属性を通してアクセスできます。これはキャッシュを回避して、または関数を別のキャッシュでラップして、内観するのに便利です。

LRU (least recently used) キャッシュ は、最新の呼び出しが次も呼び出される可能性が最も高い場合 (例えば、ニュースサーバーの最も人気のある記事は、毎日変わる傾向にあります) に最も効率が良くなります。キャッシュのサイズ制限は、キャッシュがウェブサーバーなどの長期間に渡るプロセスにおける限界を超えては大きくならないことを保証します。

一般的には、 LRU キャッシュは前回計算した値を再利用したいときにのみ使うべきです。 そのため、副作用のある関数、呼び出すごとに個別の可変なオブジェクトを作成する必要がある関数、 time() や random() のような純粋でない関数をキャッシュする意味はありません。

静的 web コンテンツ の LRU キャッシュの例:

@lru_cache(maxsize=32)
def get_pep(num):
    'Retrieve text of a Python Enhancement Proposal'
    resource = 'http://www.python.org/dev/peps/pep-%04d/' % num
    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)

キャッシュを使って 動的計画法 の技法を実装し、フィボナッチ数 を効率よく計算する例:

@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)

バージョン 3.2 で追加.

バージョン 3.3 で変更: typed オプションが追加されました。

@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 つの拡張比較メソッドをすべて実装すれば、簡単にスピードアップを図れるでしょう。

バージョン 3.2 で追加.

バージョン 3.4 で変更: 認識できない型に対して下層の比較関数から NotImplemented を返すことがサポートされるようになりました。

functools.partial(func, *args, **keywords)

新しい partial オブジェクト を返します。このオブジェクトは呼び出されると位置引数 args とキーワード引数 keywords 付きで呼び出された func のように振る舞います。呼び出しに際してさらなる引数が渡された場合、それらは args に付け加えられます。追加のキーワード引数が渡された場合には、それらで keywords を拡張または上書きします。おおよそ次のコードと等価です:

def partial(func, *args, **keywords):
    def newfunc(*fargs, **fkeywords):
        newkeywords = keywords.copy()
        newkeywords.update(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(object):
...     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

バージョン 3.4 で追加.

functools.reduce(function, iterable[, initializer])

2 引数の function を iterable の要素に対して左から右に累積的に適用し、イテラブルを単一の値に縮約します。例えば、reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) は ((((1+2)+3)+4)+5) を計算します。左引数 x は累計の値で、右引数 y は iterable から取り出した更新値です。オプションの initializer が存在する場合、計算の際にイテラブルの先頭に置かれ、またイテラブルが空の場合のデフォルトになります。initializer が与えられておらず、iterable が単一の要素しか持っていない場合、最初の要素が返されます。

およそ次と等価です:

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
@functools.singledispatch

関数を シングルディスパッチ ジェネリック関数 に変換します。

ジェネリック関数を定義するには、 @singledispatch デコレータを付けます。ディスパッチは 1 つ目の引数の型で行われることに注意して、関数を次のように作成してください:

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

型アノテーションを使っていないコードについては、デコレータに適切な型引数を明示的に渡せます:

>>> @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 which enables decorator stacking, pickling, as well as creating 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 型に登録されます。これは、他によりよい実装が見つからないことを意味します。

指定された型に対して、汎用関数がどの実装を選択するかを確認するには、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>

バージョン 3.4 で追加.

バージョン 3.7 で変更: register() 属性が型アノテーションの使用をサポートするようになりました。

functools.update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

wrapper 関数を wrapped 関数に見えるようにアップデートします。オプション引数はタプルで、元の関数のどの属性がラッパー関数の対応する属性に直接代入されるか、またラッパー関数のどの属性が元の関数の対応する属性でアップデートされるか、を指定します。これらの引数のデフォルト値は、モジュールレベル定数 WRAPPER_ASSIGNMENTS (これはラッパー関数の __module__, __name__, __qualname__, __annotations__ そしてドキュメンテーション文字列 __doc__ に代入する) と WRAPPER_UPDATES (これはラッパー関数の __dict__ すなわちインスタンス辞書をアップデートする) です。

内観や別の目的 (例えば、 lru_cache() のようなキャッシュするデコレータの回避) のために元の関数にアクセスできるように、この関数はラップされている関数を参照するラッパーに自動的に __wrapped__ 属性を追加します。

この関数は主に関数を包んでラッパーを返す デコレータ 関数の中で使われるよう意図されています。もしラッパー関数がアップデートされないとすると、返される関数のメタデータは元の関数の定義ではなくラッパー関数の定義を反映してしまい、これは通常あまり有益ではありません。

update_wrapper() は、関数以外の呼び出し可能オブジェクトにも使えます。 assigned または updated で指名され、ラップされるオブジェクトに存在しない属性は、すべて無視されます (すなわち、ラッパー関数にそれらの属性を設定しようとは試みられません)。しかし、 updated で指名された属性がラッパー関数自身に存在しないなら AttributeError が送出されます。

バージョン 3.2 で追加: __wrapped__ 属性の自動的な追加。

バージョン 3.2 で追加: デフォルトで __annotations__ 属性がコピーされます。

バージョン 3.2 で変更: 存在しない属性によって AttributeError を発生しなくなりました。

バージョン 3.4 で変更: ラップされた関数が __wrapped__ を定義していない場合でも、 __wrapped__ が常にラップされた関数を参照するようになりました。(bpo-17482 を参照)

@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 オブジェクトは function オブジェクトのように呼び出し可能で、弱参照可能で、属性を持つことができます。重要な相違点もあります。例えば、 __name__ と __doc__ 両属性は自動では作られません。また、クラス中で定義された partial オブジェクトはスタティックメソッドのように振る舞い、インスタンスの属性問い合わせの中で束縛メソッドに変換されません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 関数型プログラミング用モジュール »


operator --- 関数形式の標準演算子

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 関数型プログラミング用モジュール »

operator --- 関数形式の標準演算子

ソースコード: 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)

not obj の結果を返します。(オブジェクトインスタンスには __not__() メソッドは無いので注意してください; インタプリタコアがこの演算を定義しているだけです。結果は __bool__() および __len__() メソッドに影響されます。)

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__() と同等です。

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 を返します。

バージョン 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)

オブジェクト o の概算の長さを返します。最初に実際の長さを、次に object.__length_hint__() を使って概算の長さを、そして最後にデフォルトの値を返そうとします。

バージョン 3.4 で追加.

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)

演算対象からその __getitem__() メソッドを使って item を取得する呼び出し可能なオブジェクトを返します。 二つ以上のアイテムを要求された場合には、アイテムのタプルを返します。例えば:

  • 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

アイテムは被演算子の __getitem__() メソッドが受け付けるどんな型でも構いません。辞書ならば任意のハッシュ可能な値を受け付けます。リスト、タプル、文字列などはインデクスかスライスを受け付けます:

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

引数の 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)

インプレース演算子

多くの演算に「インプレース」版があります。 以下の関数はそうした演算子の通常の文法に比べてより素朴な呼び出し方を提供します。たとえば、文(statement) 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 と等価です。

バージョン 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 と等価です。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 関数型プログラミング用モジュール »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

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

この章で説明されるモジュールはディスクのファイルやディレクトリを扱います。たとえば、ファイルの属性を読むためのモジュール、ファイルパスを移植可能な方式で操作する、テンポラリファイルを作成するためのモジュールです。この章の完全な一覧は:

  • pathlib --- オブジェクト指向のファイルシステムパス
    • 基本的な使い方
    • 純粋パス
      • 全般的な性質
      • 演算子
      • 個別の構成要素へのアクセス
      • メソッドとプロパティ
    • 具象パス
      • メソッド
    • os モジュールにあるツールとの対応付け
  • os.path --- 共通のパス名操作
  • fileinput --- 複数の入力ストリームをまたいだ行の繰り返し処理をサポートする
  • stat --- stat() の結果を解釈する
  • filecmp --- ファイルおよびディレクトリの比較
    • dircmp クラス
  • tempfile --- 一時ファイルやディレクトリの作成
    • 使用例
    • 非推奨の関数と変数
  • glob --- Unix 形式のパス名のパターン展開
  • fnmatch --- Unix ファイル名のパターンマッチ
  • linecache --- テキストラインにランダムアクセスする
  • shutil --- 高水準のファイル操作
    • ディレクトリとファイルの操作
      • copytree の例
      • rmtree の例
    • アーカイブ化操作
      • アーカイブ化の例
    • 出力ターミナルのサイズの取得
  • macpath --- Mac OS 9 のパス操作関数

参考

os モジュール
オペレーティングシステムのインタフェース、Python の ファイルオブジェクト より低レベルでのファイル操作を含みます。
io モジュール
Python 組み込みの I/O ライブラリで、抽象クラスとファイル I/O のようないくつかの具象クラスを含みます。
open() 組込み関数
Python で読み書きのためにファイルを開く標準的な方法です。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


pathlib --- オブジェクト指向のファイルシステムパス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

pathlib --- オブジェクト指向のファイルシステムパス

バージョン 3.4 で追加.

ソースコード: Lib/pathlib.py

このモジュールはファイルシステムのパスを表すクラスを提供していて、様々なオペレーティングシステムについての適切な意味論をそれらのクラスに持たせています。 Path クラスは 純粋パス と 具象パス からなります。 純粋パスは I/O を伴わない純粋な計算操作を提供します。 具象パスは純粋パスを継承していますが、 I/O 操作も提供しています。

あなたが今までこのモジュールを使用したことがない場合や、タスクに適しているのがどのクラスかわからない場合は、 Path はきっとあなたに必要なものでしょう。 Path はコードが実行されているプラットフォーム用の 具象パス のインスタンスを作成します。

純粋パスは、以下のようないくつかの特殊なケースで有用です:

  1. Unix マシン上で Windows のパスを扱いたいとき (またはその逆)。Unix 上で実行しているときに WindowsPath のインスタンスを作成することはできませんが、PureWindowsPath なら可能になります。
  2. 実際に OS にアクセスすることなしにパスを操作するだけのコードを確認したいとき。この場合、純粋クラスのインスタンスを一つ作成すれば、それが OS にアクセスすることはないので便利です。

参考

PEP 428: 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 インターフェイスを実装しているオブジェクトか、その他の path オブジェクトです。

>>> 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 のパスでは、ローカルルートを変更してもそれまでのドライブ設定は破棄されません:

>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

誤ったスラッシュおよび単一ドットは無視されますが、2 個のドット ('..') は、シンボリックリンクのときにパスの意味の変更を意味するため受け付けれられます:

>>> 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 のサブクラスです。このパスフレーバーは Windows ファイルシステムパスを表します:

>>> PureWindowsPath('c:/Program Files/')
PureWindowsPath('c:/Program Files')

pathsegments の指定は PurePath と同じです。

これらクラスはあらゆるシステムコールを行わないため、起動しているシステムにかかわらずインスタンスを作成できます。

全般的な性質

パスオブジェクトはイミュータブルでハッシュ可能です。 同じフレーバーのパスオブジェクトは比較ならびに順序付け可能です。 これらのプロパティは、フレーバーのケースフォールディング (訳注: 比較のために正規化すること、例えば全て大文字にする) のセマンティクスに従います。

>>> 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() と似ています:

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')

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
'\\'
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:/')
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

末尾の要素に拡張子があればそれになります:

>>> PurePosixPath('my/library/setup.py').suffix
'.py'
>>> PurePosixPath('my/library.tar.gz').suffix
'.gz'
>>> PurePosixPath('my/library').suffix
''
PurePath.suffixes

パスのファイル拡張子のリストになります:

>>> 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()

file URI で表したパスを返します。絶対パスではない場合に ValueError を送出します。

>>> 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_reserved()

PureWindowsPath の場合はパスが Windows 上で予約されていれば True を返し、そうでなければ False を返します。PurePosixPath の場合は常に False を返します。

>>> PureWindowsPath('nul').is_reserved()
True
>>> PurePosixPath('nul').is_reserved()
False

ファイルシステムで予約されたパスを呼び出すと、原因不明で失敗したり、予期せぬ結果になります。

PurePath.joinpath(*other)

このメソッドの呼び出しは引数 other を順々に繋げることと等価になります:

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

現在のパスが glob 形式で与えられたパターンと一致したら True を、一致しなければ False を返します。

pattern が相対表記であればパスは相対および絶対パスを取ることができ、右から一致を調べます:

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

pattern が絶対表記であれば、パスは絶対パスでなければならず、パス全体が一致しなければなりません:

>>> PurePath('/a.py').match('/*.py')
True
>>> PurePath('a/b.py').match('/*.py')
False

他のメソッドと同様に、大文字小文字の区別はフレーバーに依存します:

>>> PureWindowsPath('b.py').match('*.PY')
True
PurePath.relative_to(*other)

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 694, in relative_to
    .format(str(self), str(formatted)))
ValueError: '/etc/passwd' does not start with '/usr'
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_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')

具象パス

具象パスは純粋パスクラスのサブクラスです。純粋パスが提供する操作に加え、パスオブジェクト上でシステムコールを呼ぶメソッドも提供しています。具象パスのインスタンスを作成するには 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 を送出します (例えばパスが存在しない場合):

classmethod Path.cwd()

(os.getcwd() が返す) 現在のディレクトリを表す新しいパスオブジェクトを返します:

>>> Path.cwd()
PosixPath('/home/antoine/pathlib')
classmethod Path.home()

ユーザーのホームディレクトリ (os.path.expanduser() での ~ の返り値) を表す新しいパスオブジェクトを返します:

>>> Path.home()
PosixPath('/home/antoine')

バージョン 3.5 で追加.

Path.stat()

(os.stat() と同様の) 現在のパスに関する情報を返します。値はそれぞれのメソッドを呼び出した時点のものになります。

>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554
Path.chmod(mode)

os.chmod() のようにファイルのモードとアクセス権限を変更します:

>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060
Path.exists()

パスが既存のファイルかディレクトリを指しているかどうかを返します:

>>> Path('.').exists()
True
>>> Path('setup.py').exists()
True
>>> Path('/etc').exists()
True
>>> Path('nonexistentfile').exists()
False

注釈

パスがシンボリックリンクを指している場合、exists() はシンボリックリンクが既存のファイルかディレクトリを指しているかどうかを返します。

Path.expanduser()

パス要素 ~ および ~user を os.path.expanduser() が返すように展開した新しいパスオブジェクトを返します:

>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')

バージョン 3.5 で追加.

Path.glob(pattern)

Glob the given pattern in the directory represented by this path, yielding all matching files (of any kind):

>>> sorted(Path('.').glob('*.py'))
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
>>> sorted(Path('.').glob('*/*.py'))
[PosixPath('docs/conf.py')]

パターン "**" は "このディレクトリおよびすべてのサブディレクトリを再帰的に走査" を意味します。言い換えれば、再帰的な Glob 走査が可能という意味です:

>>> sorted(Path('.').glob('**/*.py'))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]

注釈

パターン "**" を大きなディレクトリツリーで使用するととてつもなく時間がかかるかもしれません。

Path.group()

ファイルを所有するグループ名を返します。ファイルの GID がシステムのデータベースに見つからなかった場合は KeyError が送出されます。

Path.is_dir()

パスがディレクトリ (またはディレクトリへのシンボリックリンク) を指していた場合 True を返し、その他の種類のファイルだった場合 False を返します。

パスが存在しないか壊れたシンボリックリンクだった場合にも False が返されます; (パーミッションエラーのような) その他のエラーは伝搬されます。

Path.is_file()

パスが一般ファイル (または一般ファイルへのシンボリックリンク) を指していた場合 True を返します。その他の種類のファイルを指していた場合 False を返します。

パスが存在しないか壊れたシンボリックリンクだった場合にも False が返されます; (パーミッションエラーのような) その他のエラーは伝搬されます。

Path.is_mount()

パス名 path がマウントポイント mount point (ファイルシステムの中で異なるファイルシステムがマウントされているところ) なら True を返します。 POSIX では、この関数は path の親ディレクトリである path/.. が path と異なるデバイス上にあるか、あるいは path/.. と path が同じデバイス上の同じ i-node を指しているかをチェックします --- これによってすべての Unix と POSIX 系システムでマウントポイントが検出できます。 この関数は Windows では実装されていません。

バージョン 3.7 で追加.

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')
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 を送出します。

exist_ok の値が真の場合、パス要素の末尾がすでに存在するがディレクトリではないときは FileExistsError 例外を送出しますが、ディレクトリであれば送出しません (POSIX の mkdir -p コマンドの挙動と同じ)。

バージョン 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()

ファイルの所有者のユーザー名を返します。ファイルの UID がシステムのデータベースに見つからない場合 KeyError が送出されます。

Path.read_bytes()

指定されたファイルの内容をバイナリオブジェクトで返します:

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

バージョン 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() と同じです。

バージョン 3.5 で追加.

Path.rename(target)

このファイルかディレクトリを与えられた target にリネームします。 Unix では target が存在するファイルの場合、ユーザにパーミッションがあれば静かに置換されます。 target は文字列か別のパスオブジェクトです:

>>> p = Path('foo')
>>> p.open('w').write('some text')
9
>>> target = Path('bar')
>>> p.rename(target)
>>> target.open().read()
'some text'
Path.replace(target)

現在のファイルまたはディレクトリの名前を target に変更します。target が既存のファイルかディレクトリを指していた場合、無条件に置き換えられます。

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')

パスが存在せず strict が True の場合、 FileNotFoundError が送出されます。 strict が False の場合は、パスは可能な限り解決され、残りの部分は存在するかのチェックをせずに追加されます。 もしパスの解決にあたって無限ループする場合は、RuntimeError が送出されます。

バージョン 3.6 で追加: strict 引数

Path.rglob(pattern)

This is like calling Path.glob() with "**" added in front of the given pattern:

>>> sorted(Path().rglob("*.py"))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]
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

バージョン 3.5 で追加.

Path.symlink_to(target, target_is_directory=False)

現在のパスに target へのシンボリックリンクを作成します。Windows では、リンク対象がディレクトリの場合 target_is_directory が真でなければなりません (デフォルトは False)。POSIX では、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.touch(mode=0o666, exist_ok=True)

与えられたパスにファイルを作成します。mode が与えられた場合、プロセスの umask 値と組み合わせてファイルのモードとアクセスフラグが決定されます。ファイルがすでに存在した場合、exist_ok が真ならばこの関数は正常に終了します (そしてファイルの更新日付が現在の日時に変更されます)。その他の場合は FileExistsError が送出されます。

Path.unlink()

このファイルまたはシンボリックリンクを削除します。パスがディレクトリを指している場合は Path.rmdir() を使用してください。

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'

同じ名前のファイルがすでにあれば上書きされます。

バージョン 3.5 で追加.

Path.write_text(data, encoding=None, errors=None)

指定されたファイルをテキストモードで開き、data を書き込み、ファイルを閉じます:

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

バージョン 3.5 で追加.

os モジュールにあるツールとの対応付け

下にあるのは、様々な os 関数とそれに相当する PurePath あるいは Path の同等のものとの対応表です。

注釈

os.path.relpath() および PurePath.relative_to() は使い道が重なるところもありますが、それらの意味論は同等だと見なすには違い過ぎています。

os および os.path | pathlib
os.path.abspath() | Path.resolve()
os.chmod() | Path.chmod()
os.mkdir() | 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.path.isdir() | Path.is_dir()
os.path.isfile() | Path.is_file()
os.path.islink() | Path.is_symlink()
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.suffix

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルとディレクトリへのアクセス »


os.path --- 共通のパス名操作

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

os.path --- 共通のパス名操作

ソースコード: Lib/posixpath.py (POSIX), Lib/ntpath.py (Windows NT), Lib/macpath.py (Mac)

このモジュールには、パス名を操作する便利な関数が実装されています。ファイルの読み書きに関しては open() を、ファイルシステムへのアクセスに関しては os モジュールを参照してください。パスパラメータは文字列またはバイト列で渡すことができます。アプリケーションは、ファイル名を Unicode 文字列で表すことが推奨されています。残念ながら、Unix では文字列で表すことのできないファイル名があるため、Unix 上で任意のファイル名をサポートする必要のあるアプリケーションは、そのパス名にバイト列を使用すべきです。逆に、バイト列オブジェクトを使用すると Windows (標準の mbcs エンコーディング) 上ではすべてのファイル名を表すことができないため、Windows アプリケーションはファイルアクセスのために文字列オブジェクトを使用するべきです。

Unix シェルとは異なり、Python はあらゆるパス展開を 自動的には 行いません。アプリケーションがシェルのようなパス展開を必要とした場合は、 expanduser() や expandvars() といった関数を明示的に呼び出すことで行えます。(glob モジュールも参照してください)

参考

pathlib モジュールは高水準のパスオブジェクトを提供します。

注釈

以下のすべての関数は、そのパラメータにバイト列のみ、あるいは文字列のみ受け付けます。パスまたはファイル名を返す場合、返り値は同じ型のオブジェクトになります。

注釈

OS によって異なるパス名の決まりがあるため、標準ライブラリにはこのモジュールのいくつかのバージョンが含まれています。 os.path モジュールは常に現在 Python が動作している OS に適したパスモジュールであるため、ローカルのパスを扱うのに適しています。各々のモジュールをインポートして 常に 一つのフォーマットを利用することも可能です。これらはすべて同じインタフェースを持っています:

  • posixpath UNIX スタイルのパス用
  • ntpath Windows パス用
  • macpath 古いスタイルの MacOS パス用
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)

シーケンス paths 中の各パス名に共通するサブパスのうち、最も長いものを返します。paths に絶対パス名と相対パス名の両方が含まれているか、paths が空の場合、 ValueError を送出します。commonprefix() とは異なり、有効なパスを返します。

Availability: Unix, Windows.

バージョン 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)

path が実在するパスなら True を返します。壊れたシンボリックリンクについては True を返します。 os.lstat() がない環境では exists() と等価です。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.expanduser(path)

Unix および Windows では、与えられた引数の先頭のパス要素 ~ 、または ~user を、 user のホームディレクトリのパスに置き換えて返します。

Unix では、先頭の ~ は、環境変数 HOME が設定されているならその値に置き換えられます。設定されていない場合は、現在のユーザのホームディレクトリをビルトインモジュール pwd を使ってパスワードディレクトリから探して置き換えます。先頭の ~user については、直接パスワードディレクトリから探します。

Windows では、 HOME と USERPROFILE が設定されていればそれを使用します。設定されていない場合は、環境変数 HOMEPATH と HOMEDRIVE の組み合わせで置き換えられます。先頭の ~user は ~ で得られるユーザパスの最後のディレクトリ要素を除去したものを利用します。

置き換えに失敗したり、引数のパスがチルダで始まっていなかった場合は、パスをそのまま返します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.expandvars(path)

引数のパスの環境変数を展開して返します。引数の中の $name または ${name} のような形式の文字列は環境変数、 name の値に置き換えられます。不正な変数名や存在しない変数名の場合には変換されず、そのまま返します。

Windows では、 $name や ${name} の形式に加えて、 %name% の形式もサポートされています。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.getatime(path)

Return the time of last access of path. The return value is a floating point number giving the number of seconds since the epoch (see the time module). Raise OSError if the file does not exist or is inaccessible.

os.path.getmtime(path)

Return the time of last modification of path. The return value is a floating point number giving the number of seconds since the epoch (see the time module). Raise OSError if the file does not exist or is inaccessible.

バージョン 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)

path が絶対パスなら True を返します。すなわち、 Unix ではスラッシュで始まり、 Windows ではドライブレターに続く (バック) スラッシュで始まる場合です。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.isfile(path)

Return True if path is an existing regular file. This follows symbolic links, so both islink() and isfile() can be true for the same path.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.isdir(path)

Return True if path is an existing directory. This follows symbolic links, so both islink() and isdir() can be true for the same path.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.islink(path)

Return True if path refers to an existing directory entry that is a symbolic link. Always False if symbolic links are not supported by the Python runtime.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.ismount(path)

Return True if pathname path is a mount point: a point in a file system where a different file system has been mounted. On POSIX, the function checks whether path's parent, path/.., is on a different device than path, or whether path/.. and path point to the same i-node on the same device --- this should detect mount points for all Unix and POSIX variants. On Windows, a drive letter root and a share UNC are always mount points, and for any other path GetVolumePathName is called to see if it is different from the input path.

バージョン 3.4 で追加: Windows での、ルートでないマウントポイントの検出をサポートするようになっています。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.join(path, *paths)

1 つあるいはそれ以上のパスの要素を賢く結合します。戻り値は path、ディレクトリの区切り文字 (os.sep) を *paths の各パートの(末尾でない場合の空文字列を除いて)頭に付けたもの、これらの結合になります。最後の部分が空文字列の場合に限り区切り文字で終わる文字列になります。付け加える要素に絶対パスがあれば、それより前の要素は全て破棄され、以降の要素を結合します。

Windows の場合は、絶対パスの要素 (たとえば r'\foo') が見つかった場合はドライブレターはリセットされません。要素にドライブレターが含まれていれば、それより前の要素は全て破棄され、ドライブレターがリセットされます。各ドライブに対してカレントディレクトリがあるので、 os.path.join("c:", "foo") によって、 c:\foo ではなく、ドライブ C: 上のカレントディレクトリからの相対パス(c:foo) が返されることに注意してください。

バージョン 3.6 で変更: path と paths が path-like object を受け付けるようになりました。

os.path.normcase(path)

Normalize the case of a pathname. On Unix and Mac OS X, this returns the path unchanged; on case-insensitive filesystems, it converts the path to lowercase. On Windows, it also converts forward slashes to backward slashes. Raise a TypeError if the type of path is not str or bytes (directly or indirectly through the os.PathLike interface).

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.normpath(path)

パスを正規化します。余分な区切り文字や上位レベル参照を除去し、A//B、A/B/、A/./B や A/foo/../B などはすべて A/B になります。この文字列操作は、シンボリックリンクを含むパスの意味を変えてしまう場合があります。Windows では、スラッシュをバックスラッシュに変換します。大文字小文字の正規化には normcase() を使用してください。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.realpath(path)

パスの中のシンボリックリンク (もしそれが当該オペレーティングシステムでサポートされていれば) を取り除いて、指定されたファイル名を正規化したパスを返します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.relpath(path, start=os.curdir)

カレントディレクトリあるいはオプションの start ディレクトリからの path への相対パスを返します。これはパス計算で行っており、ファイルシステムにアクセスして path や start の存在や性質を確認することはありません。

start のデフォルト値は os.curdir です。

Availability: Unix, Windows.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.samefile(path1, path2)

引数の両パス名が同じファイルまたはディレクトリを参照している場合、 True を返します。これは、デバイス番号と i-node 番号で決定されます。どちらかのパス名への os.stat() 呼び出しが失敗した場合、例外が送出されます。

Availability: Unix, Windows.

バージョン 3.2 で変更: Windows サポートを追加しました。

バージョン 3.4 で変更: Windows が他のプラットフォームと同じ実装を使用するようになりました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.sameopenfile(fp1, fp2)

ファイル記述子 fp1 と fp2 が同じファイルを参照していたら True を返します。

Availability: Unix, Windows.

バージョン 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() を使用した比較に基いて実装しています。

Availability: Unix, Windows.

バージョン 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") を返します。

パスが UNC パスを含む場合、ドライブレターにはホスト名と共有名までが含まれますが、共有名の後の区切り文字は含まれません。例えば、splitdrive("//host/computer/dir") は ("//host/computer", "/dir") を返します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.splitext(path)

パス名 path を (root, ext) のペアに分割します。 root + ext == path になります。 ext は空文字列か 1 つのピリオドで始まり、多くても 1 つのピリオドを含みます。ベースネームを導出するピリオドは無視されます; splitext('.cshrc') は ('.cshrc', '') を返します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.supports_unicode_filenames

ファイル名に任意の Unicode 文字列を (システムの制限内で) 使用できる場合は True になります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルとディレクトリへのアクセス »


fileinput --- 複数の入力ストリームをまたいだ行の繰り返し処理をサポートする

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

fileinput --- 複数の入力ストリームをまたいだ行の繰り返し処理をサポートする

ソースコード: Lib/fileinput.py

このモジュールは標準入力やファイルの並びにまたがるループを素早く書くためのヘルパークラスと関数を提供しています。単一のファイルを読み書きしたいだけなら、 open() を参照してください。

典型的な使い方は以下の通りです:

import fileinput
for line in fileinput.input():
    process(line)

このプログラムは sys.argv[1:] に含まれる全てのファイルをまたいで繰り返します。もし該当するものがなければ、 sys.stdin がデフォルトとして扱われます。ファイル名として '-' が与えられた場合も、 sys.stdin に置き換えられます。別のファイル名リストを使いたい時には、 input() の最初の引数にリストを与えます。単一ファイル名の文字列も受け付けます。

全てのファイルはデフォルトでテキストモードでオープンされます。しかし、 input() や FileInput をコールする際に mode パラメータを指定すれば、これをオーバーライドすることができます。オープン中あるいは読み込み中にI/Oエラーが発生した場合には、 OSError が発生します。

バージョン 3.3 で変更: 以前は IOError が送出されました; それは現在 OSError のエイリアスです。

sys.stdin が2回以上使われた場合は、2回目以降は行を返しません。ただしインタラクティブに利用している時や明示的にリセット (sys.stdin.seek(0) を使う) を行った場合はその限りではありません。

空のファイルは開いた後すぐ閉じられます。空のファイルはファイル名リストの最後にある場合にしか外部に影響を与えません。

ファイルの各行は、各種改行文字まで含めて返されます。ファイルの最後が改行文字で終っていない場合には、改行文字で終わらない行が返されます。

ファイルのオープン方法を制御するためのオープン時フックは、 fileinput.input() あるいは FileInput() の openhook パラメータで設定します。このフックは、ふたつの引数 filename と mode をとる関数でなければなりません。そしてその関数の返り値はオープンしたファイルオブジェクトとなります。このモジュールには、便利なフックが既に用意されています。

以下の関数がこのモジュールの基本的なインタフェースです:

fileinput.input(files=None, inplace=False, backup='', bufsize=0, mode='r', openhook=None)

FileInput クラスのインスタンスを作ります。生成されたインスタンスは、このモジュールの関数群が利用するグローバルな状態として利用されます。この関数への引数は FileInput クラスのコンストラクタへ渡されます。

The FileInput instance can be used as a context manager in the with statement. In this example, input is closed after the with statement is exited, even if an exception occurs:

with fileinput.input(files=('spam.txt', 'eggs.txt')) as f:
    for line in f:
        process(line)

バージョン 3.2 で変更: コンテキストマネージャとして使うことができるようになりました。

Deprecated since version 3.6, will be removed in version 3.8: The bufsize parameter.

以下の関数は 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='', bufsize=0, mode='r', openhook=None)

FileInput クラスはモジュールの関数に対応するメソッド filename() 、 fileno() 、 lineno() 、 filelineno() 、 isfirstline() 、 isstdin() 、 nextfile() および close() を実装しています。それに加えて、次の入力行を返す readline() メソッドと、シーケンスの振舞いの実装をしている __getitem__() メソッドがあります。シーケンスはシーケンシャルに読み込むことしかできません。つまりランダムアクセスと readline() を混在させることはできません。

mode を使用すると、 open() に渡すファイルモードを指定することができます。これは 'r' 、 'rU' 、 'U' および 'rb' のうちのいずれかとなります。

openhook を指定する場合は、ふたつの引数 filename と mode をとる関数でなければなりません。この関数の返り値は、オープンしたファイルオブジェクトとなります。inplace と openhook を同時に使うことはできません。

A FileInput instance can be used as a context manager in the with statement. In this example, input is closed after the with statement is exited, even if an exception occurs:

with FileInput(files=('spam.txt', 'eggs.txt')) as input:
    process(input)

バージョン 3.2 で変更: コンテキストマネージャとして使うことができるようになりました。

バージョン 3.4 で非推奨: 'rU' および 'U' モード。

Deprecated since version 3.6, will be removed in version 3.8: The bufsize parameter.

インプレース(in-place)フィルタオプション: キーワード引数 inplace=True が fileinput.input() か FileInput クラスのコンストラクタに渡された場合には、入力ファイルはバックアップファイルに移動され、標準出力が入力ファイルに設定されます(バックアップファイルと同じ名前のファイルが既に存在していた場合には、警告無しに置き替えられます)。これによって入力ファイルをその場で書き替えるフィルタを書くことができます。キーワード引数 backup (通常は backup='.<拡張子>' という形で利用します)が与えられていた場合、バックアップファイルの拡張子として利用され、バックアップファイルは削除されずに残ります。デフォルトでは、拡張子は '.bak' になっていて、出力先のファイルが閉じられればバックアップファイルも消されます。インプレースフィルタ機能は、標準入力を読み込んでいる間は無効にされます。

このモジュールには、次のふたつのオープン時フックが用意されています:

fileinput.hook_compressed(filename, mode)

gzip や bzip2 で圧縮された (拡張子が '.gz' や '.bz2' の) ファイルを、 gzip モジュールや bz2 モジュールを使って透過的にオープンします。ファイルの拡張子が '.gz' や '.bz2' でない場合は、通常通りファイルをオープンします (つまり、 open() をコールする際に伸長を行いません)。

使用例: fi = fileinput.FileInput(openhook=fileinput.hook_compressed)

fileinput.hook_encoded(encoding, errors=None)

Returns a hook which opens each file with open(), using the given encoding and errors to read the file.

Usage example: fi = fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8", "surrogateescape"))

バージョン 3.6 で変更: Added the optional errors parameter.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルとディレクトリへのアクセス »


stat --- stat() の結果を解釈する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

stat --- stat() の結果を解釈する

ソースコード: Lib/stat.py

stat モジュールでは、 os.stat() 、 os.lstat() 、および os.fstat() が存在する場合に、これらの関数が返す内容を解釈するための定数や関数を定義しています。 stat() 、 fstat() 、および lstat() の関数呼び出しについての完全な記述はシステムのドキュメントを参照してください。

バージョン 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)

ファイルのモードがドアの場合にゼロでない値を返します。

バージョン 3.4 で追加.

stat.S_ISPORT(mode)

ファイルのモードがイベントポートの場合にゼロでない値を返します。

バージョン 3.4 で追加.

stat.S_ISWHT(mode)

ファイルのモードがホワイトアウトの場合にゼロでない値を返します。

バージョン 3.4 で追加.

より一般的なファイルのモードを操作するための二つの関数が定義されています:

stat.S_IMODE(mode)

os.chmod() で設定することのできる一部のファイルモード --- すなわち、ファイルの許可ビット (permission bits) に加え、 (サポートされているシステムでは) スティッキービット (sticky bit)、実行グループ ID 設定 (set-group-id) および実行ユーザ ID 設定 (set-user-id) ビット --- を返します。

stat.S_IFMT(mode)

ファイルの形式を記述しているファイルモードの一部 (上記の S_IS*() 関数で使われます) を返します。

通常、ファイルの形式を調べる場合には os.path.is*() 関数を使うことになります; ここで挙げた関数は同じファイルに対して複数のテストを同時に行いたいが、 stat() システムコールを何度も呼び出してオーバヘッドが生じるのを避けたい場合に便利です。これらはまた、ブロック型およびキャラクタ型デバイスに対するテストのように、 os.path で扱うことのできないファイルの情報を調べる際にも便利です。

以下はプログラム例です:

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.stat(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' 形式の文字列に変換します。

バージョン 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

ドア。

バージョン 3.4 で追加.

stat.S_IFPORT

イベントポート。

バージョン 3.4 で追加.

stat.S_IFWHT

ホワイトアウト。

バージョン 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

ファイルは圧縮して保存される (Mac OS X 10.6+)。

stat.UF_HIDDEN

ファイルは GUI で表示されるべきでない (Mac OS X 10.5+)。

stat.SF_ARCHIVED

ファイルはアーカイブされているかもしれません。

stat.SF_IMMUTABLE

ファイルは変更されない。

stat.SF_APPEND

ファイルは追記しかされない。

stat.SF_NOUNLINK

ファイルはリネームや削除されない。

stat.SF_SNAPSHOT

このファイルはスナップショットファイルです。

詳しい情報は *BSD か Mac OS システムの man page chflags(2) を参照してください。

Windows では、os.stat() が返す st_file_attributes メンバー内のビットを検証する際に、以下のファイル属性定数を使用できます。これらの定数の意味について詳しくは、Windows API documentation を参照してください。

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

バージョン 3.5 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルとディレクトリへのアクセス »


filecmp --- ファイルおよびディレクトリの比較

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

filecmp --- ファイルおよびディレクトリの比較

ソースコード: Lib/filecmp.py

filecmp モジュールでは、ファイルおよびディレクトリを比較するため、様々な時間／正確性のトレードオフに関するオプションを備えた関数を定義しています。ファイルの比較については、 difflib モジュールも参照してください。

filecmp モジュールでは以下の関数を定義しています:

filecmp.cmp(f1, f2, shallow=True)

名前が f1 および f2 のファイルを比較し、二つのファイルが同じらしければ True を返し、そうでなければ False を返します。

shallow が真の場合、同一の os.stat() シグニチャを持つファイルは等しいとみなされます。そうでなければ、ファイルの内容が比較されます。

可搬性と効率のために、この関数は外部プログラムを一切呼び出さないので注意してください。

この関数は過去の比較と結果のキャッシュを使用します。ファイルの 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 分解能未満でのファイル変更後にすぐに比較するような場合に有用です。

バージョン 3.4 で追加.

dircmp クラス

class filecmp.dircmp(a, b, ignore=None, hide=None)

ディレクトリ a および b を比較するための新しいディレクトリ比較オブジェクトを生成します。 ignore は比較の際に無視するファイル名のリストで、標準の設定では filecmp.DEFAULT_IGNORES です。 hide は表示しない名前のリストで、標準の設定では [os.curdir, os.pardir] です。

dircmp クラスは、 filecmp.cmp() で説明されているような 浅い 比較を行うことによりファイルを比較します。

dircmp クラスは以下のメソッドを提供しています:

report()

a と b の比較を (sys.stdout に) 表示します。

report_partial_closure()

a および b およびそれらの直下にある共通のサブディレクトリ間での比較結果を出力します。

report_full_closure()

a および b およびそれらの共通のサブディレクトリ間での比較結果を (再帰的に比較して) 出力します。

dircmp クラスは、比較されているディレクトリ階層に関する様々な情報のビットを得るために使用することのできる、興味深い属性を数多く提供しています。

すべての属性は __getattr__() フックによって遅延評価されるので、計算が軽い属性のみを使用した場合は、属性の計算による速度の低下は起こりません。

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

common_dirs のファイル名を dircmp オブジェクトに対応付けた辞書です。

filecmp.DEFAULT_IGNORES

バージョン 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 --- 一時ファイルやディレクトリの作成

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

tempfile --- 一時ファイルやディレクトリの作成

ソースコード: Lib/tempfile.py

このモジュールは一時ファイルやディレクトリを作成します。 サポートされている全てのプラットフォームで動作します。 TemporaryFile、NamedTemporaryFile、TemporaryDirectory、 SpooledTemporaryFile は自動的に後始末をし、コンテクスト管理者として使うことの出来る高水準のインターフェイスです。 mkstemp() と mkdtemp() は手動で後始末をしなければならない低水準の関数です。

ユーザが呼び出し可能な全ての関数とコンストラクタは追加の引数を受け取ります。 その引数によって一時ファイルやディレクトリの場所と名前を直接操作することが出来ます。 このモジュールに使用されるファイル名はランダムな文字を含みます。そのためファイルは共有された一時ディレクトリに安全に作成されます。 後方互換性を保つために引数の順序は若干奇妙です。 分かりやすさのためにキーワード引数を使用してください。

このモジュールではユーザが呼び出し可能な以下の項目を定義しています:

tempfile.TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None)

一時的な記憶領域として使うことの出来る file-like object を返します。 ファイルは mkstemp() と同じルールにより安全に作成されます。 オブジェクトは閉じられる (オブジェクトのガベージコレクションによる暗黙的なものも含みます) とすぐに破壊されます。 Unix では、そのファイルのディレクトリエントリは全く作成されないか、ファイル作成後すぐに削除されます。 これは他のプラットフォームではサポートされません。 よって、この関数で作成された一時ファイルがファイルシステムで可視な名前を持つかどうかをコードで当てにすべきではありません。

返されたオブジェクトをコンテクスト管理者として使うことが出来ます （使用例 を参照してください）。 コンテクストの完了やファイルオブジェクトの破壊で、一時ファイルはファイルシステムから削除されます。

作成されたファイルを閉じることなく読み書きできるように、 mode 引数のデフォルトは 'w+b' です。 保存されるデータに関わらず全てのプラットフォーム上で一貫して動作するようにバイナリモードが使用されます。 buffering、encoding、newline は、 open() に対する引数として解釈されます。

dir、prefix、suffix 引数の意味とデフォルトは mkstemp() のものと同じです。

返されたオブジェクトは、POSIXプラットフォームでは本物のファイルオブジェクトです。 それ以外のプラットフォームでは、file 属性が下層の本物のファイルであるファイル様オブジェクトです。

os.O_TMPFILE フラグは、利用可能で動作する場合に用いられます (Linux 固有で、Linux kernel 3.11 以降)。

バージョン 3.5 で変更: 利用可能であれば os.O_TMPFILE フラグが使用されます。

tempfile.NamedTemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True)

この関数は、ファイルシステム上でファイルが可視の名前を持つことが保証される (Unix においてはディレクトリエントリが unlink されない) 点以外は TemporaryFile() と正確に同じことを行います。 その名前は、返されたファイル様オブジェクトの name 属性から取得することができます。 名前付き一時ファイルがまだ開かれている間にこの名前を使って再度ファイルを開くことができるかどうかは、プラットフォームによって異なります (Unix 上では可能ですが、 Windows NT 以降ではできません)。 delete が真の場合 (デフォルト)、ファイルは閉じられたら即座に削除されます。 返されたオブジェクトは常にファイル様オブジェクトで、その file 属性は元になった本物のファイルオブジェクトです。 このファイルライクオブジェクトは、通常のファイルのように with 文の中で使用することができます。

tempfile.SpooledTemporaryFile(max_size=0, mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None)

この関数はファイルサイズが max_size を超えるかファイルの fileno() メソッドが呼ばれるまで、データがメモリにスプールされる点以外は TemporaryFile() と正確に同じことを行います。 上記条件を満たすと内容はディスクに書き込まれ、操作は TemporaryFile() と同様に進みます。

この関数が返すファイルは、追加で1つのメソッド rollover() を持っています。このメソッドが呼ばれると、(サイズに関係なく)メモリからディスクへのロールオーバーが実行されます。

返されたオブジェクトはファイル様オブジェクトで、その _file 属性は (バイナリかテキスト mode が指定されたかどうかに依存して) io.BytesIO か io.StringIO オブジェクト、あるいは rollover() が呼ばれたかどうかに依存して本物のファイルオブジェクトになります。 このファイル様オブジェクトは、通常のファイルオブジェクトと同じように with 文中で使用することが出来ます。

バージョン 3.3 で変更: truncate メソッドが size 引数を受け取るようになりました。

tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None)

この関数は mkdtemp() と同じルールを使用して安全に一時ディレクトリを作成します。 返されたオブジェクトは、コンテクスト管理者として使用することができます (with文とコンテキストマネージャ を参照)。 コンテクストの完了や一時ディレクトリの破壊で新規作成された一時ディレクトリとその中身はファイルシステムから削除されます。

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() メソッドを呼んでディレクトリを明示的に片付けることができます。

バージョン 3.2 で追加.

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() が返すものと同じ) とファイルの絶対パス名が順番に並んだタプルを返します。

バージョン 3.5 で変更: suffix、prefix、dir は bytes の返り値を得るために bytes で渡すことが出来ます。 それ以前は str のみ許されていました。 適切なデフォルト値を使用するよう、suffix と prefix は None を受け入れ、デフォルトにするようになりました。

tempfile.mkdtemp(suffix=None, prefix=None, dir=None)

可能な限り安全な方法で一時ディレクトリを作成します。 ディレクトリの生成で競合は発生しません。 ディレクトリを作成したユーザ ID だけが、このディレクトリに対して内容を読み出したり、書き込んだり、検索したりすることができます。

mkdtemp() のユーザは用済みになった時に一時ディレクトリとその中身を削除しなければなりません。

prefix, suffix, dir 引数は mkstemp() 関数のものと同じです。

mkdtemp() は新たに生成されたディレクトリの絶対パス名を返します。

バージョン 3.5 で変更: suffix、prefix、dir は bytes の返り値を得るために bytes で渡すことが出来ます。 それ以前は str のみ許されていました。 適切なデフォルト値を使用するよう、suffix と prefix は None を受け入れ、デフォルトにするようになりました。

tempfile.gettempdir()

一時ファイルに用いられるディレクトリの名前を返します。 これはモジュール内の全ての関数の dir 引数のデフォルト値を定義します。

Python は呼び出したユーザがファイルを作ることの出来るディレクトリを検索するのに標準的なリストを使用します。 そのリストは:

  1. 環境変数 TMPDIR で与えられているディレクトリ名。
  2. 環境変数 TEMP で与えられているディレクトリ名。
  3. 環境変数 TMP で与えられているディレクトリ名。
  4. プラットフォーム依存の場所:
    • Windows ではディレクトリ C:\TEMP 、 C:\TMP 、 \TEMP 、および \TMP の順。
    • その他の全てのプラットフォームでは、 /tmp 、 /var/tmp 、および /usr/tmp の順。
  5. 最後の手段として、現在の作業ディレクトリ。

この検索の結果はキャッシュされます。以下の tempdir の記述を参照してください。

tempfile.gettempdirb()

gettempdir() と同じですが返り値は bytesです。

バージョン 3.5 で追加.

tempfile.gettempprefix()

一時ファイルを生成する際に使われるファイル名の接頭辞を返します。 これにはディレクトリ部は含まれません。

tempfile.gettempprefixb()

gettempprefix() と同じですが返り値は bytes です。

バージョン 3.5 で追加.

モジュールはグローバル変数を使用して、 gettempdir() が返す、一時ファイルに用いられるディレクトリ名を記憶します。 直接設定して選考過程を上書き出来ますが、推奨されません。 このモジュールの全ての関数はディレクトリを指定する dir 引数を受け取ります。 この方法が推奨されます。

tempfile.tempdir

None 以外の値に設定された場合、このモジュールで定義されている全ての関数の dir 引数のデフォルト値として定義されます。

If tempdir is None (the default) at any call to any of the above functions except gettempprefix() it is initialized following the algorithm described in gettempdir().

使用例

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 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 形式のパス名のパターン展開

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

glob --- Unix 形式のパス名のパターン展開

ソースコード: Lib/glob.py

The glob module finds all the pathnames matching a specified pattern according to the rules used by the Unix shell, although results are returned in arbitrary order. No tilde expansion is done, but *, ?, and character ranges expressed with [] will be correctly matched. This is done by using the os.scandir() and fnmatch.fnmatch() functions in concert, and not by actually invoking a subshell. Note that unlike fnmatch.fnmatch(), glob treats filenames beginning with a dot (.) as special cases. (For tilde and shell variable expansion, use os.path.expanduser() and os.path.expandvars().)

リテラルにマッチさせるには、メタ文字を括弧に入れてください。例えば、'[?]' は文字 '?' にマッチします。

参考

pathlib モジュールは高水準のパスオブジェクトを提供します。

glob.glob(pathname, *, recursive=False)

pathname (パスの指定を含んだ文字列でなければいけません) にマッチする、空の可能性のあるパス名のリストを返します。pathname は (/usr/src/Python-1.5/Makefile のように) 絶対パスでも、(../../Tools/*/*.gif のように) 相対パスでもよく、シェル形式のワイルドカードを含んでいてもかまいません。結果には (シェルと同じく) 壊れたシンボリックリンクも含まれます。

recursive が真の場合、パターン "**" はあらゆるファイルや 0 個以上のディレクトリおよびサブディレクトリにマッチします。パターンの末尾が os.sep の場合、ディレクトリおよびサブディレクトリのみマッチします。

注釈

パターン "**" を大きなディレクトリツリーで使用するととてつもなく時間がかかるかもしれません。

バージョン 3.5 で変更: "**" を使った再帰的な glob がサポートされました。

glob.iglob(pathname, *, recursive=False)

実際には一度にすべてを格納せずに、glob() と同じ値を順に生成する イテレーター を返します。

glob.escape(pathname)

すべての特殊文字 ('?' 、 '*' 、 '[') をエスケープします。特殊文字を含んでいる可能性のある任意のリテラル文字列をマッチさせたいときに便利です。drive/UNC sharepoints の特殊文字はエスケープされません。たとえば Windows では escape('//?/c:/Quo vadis?.txt') は '//?/c:/Quo vadis[?].txt' を返します。

バージョン 3.4 で追加.

たとえば、次の 3 個のファイル 1.gif, 2.txt, card.gif と、ファイル 3.txt だけを含んだサブディレクトリ sub があった場合、glob() は以下の結果を返します。パスに接頭する要素がどう維持されるかに注意してください。:

>>> 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']

参考

fnmatch モジュール
シェル形式の (パスではない) ファイル名展開

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルとディレクトリへのアクセス »


fnmatch --- Unix ファイル名のパターンマッチ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

fnmatch --- Unix ファイル名のパターンマッチ

ソースコード: Lib/fnmatch.py

このモジュールは Unix のシェル形式のワイルドカードに対応しています。これらは、 (re モジュールでドキュメント化されている) 正規表現とは 異なります 。シェル形式のワイルドカードで使われる特殊文字は、次のとおりです。

Pattern | 意味
* | すべてにマッチします
? | 任意の一文字にマッチします
[seq] | seq にある任意の文字にマッチします
[!seq] | seq にない任意の文字にマッチします

リテラルにマッチさせるには、メタ文字を括弧に入れてください。例えば、'[?]' は文字 '?' にマッチします。

Note that the filename separator ('/' on Unix) is not special to this module. See module glob for pathname expansion (glob uses filter() to match pathname segments). Similarly, filenames starting with a period are not special for this module, and are matched by the * and ? patterns.

fnmatch.fnmatch(filename, pattern)

Test whether the filename string matches the pattern string, 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(filename, pattern)

Test whether filename matches pattern, returning True or False; the comparison is case-sensitive and does not apply os.path.normcase().

fnmatch.filter(names, pattern)

pattern にマッチする names のリストの部分集合を返します。[n for n in names if fnmatch(n, pattern)] と同じですが、もっと効率よく実装しています。

fnmatch.translate(pattern)

シェルスタイルの pattern を、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 --- テキストラインにランダムアクセスする

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

linecache --- テキストラインにランダムアクセスする

ソースコード: Lib/linecache.py

linecache モジュールは、キャッシュ (一つのファイルから何行も読んでおくのが一般的です) を使って、内部で最適化を図りつつ、Python ソースファイルの任意の行を取得するのを可能にします。 traceback モジュールは、整形されたトレースバックにソースコードを含めるためにこのモジュールを利用しています。

tokenize.open() 関数は、ファイルを開くために使用されます。この関数は、 tokenize.detect_encoding() を使用してファイルのエンコーディングを取得します。エンコーディングトークンが存在しない場合、デフォルトの UTF-8 になります。

linecache モジュールでは次の関数が定義されています:

linecache.getline(filename, lineno, module_globals=None)

filename という名前のファイルから lineno 行目を取得します。この関数は決して例外を発生させません --- エラーの際には '' を返します (行末の改行文字は、見つかった行に含まれます)。

filename という名前のファイルが見つからなかった場合、モジュールの、つまり、 sys.path でそのファイルを探します。 zipfileやその他のファイルシステムでないimport元に対応するためまず module_globals の PEP 302 __loader__ をチェックし、そのあと sys.path を探索します。

linecache.clearcache()

キャッシュをクリアします。それまでに getline() を使って読み込んだファイルの行が必要でなくなったら、この関数を使ってください。

linecache.checkcache(filename=None)

キャッシュが有効かどうかを確認します。キャッシュしたファイルがディスク上で変更された可能性があり、更新後のバージョンが必要な場合にこの関数を使用します。 filename が与えられない場合、全てのキャッシュエントリを確認します。

linecache.lazycache(filename, module_globals)

Capture enough detail about a non-file-based module to permit getting its lines later via getline() even if module_globals is None in the later call. This avoids doing I/O until a line is actually needed, without having to carry the module globals around indefinitely.

バージョン 3.5 で追加.

以下はプログラム例です:

>>> import linecache
>>> linecache.getline(linecache.__file__, 8)
'import sys\n'

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルとディレクトリへのアクセス »


shutil --- 高水準のファイル操作

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

shutil --- 高水準のファイル操作

ソースコード: Lib/shutil.py

shutil モジュールはファイルやファイルの集まりに対する高水準の操作方法を多数提供します。特にファイルのコピーや削除のための関数が用意されています。個別のファイルに対する操作については、 os モジュールも参照してください。

警告

高水準のファイルコピー関数 (shutil.copy(), shutil.copy2()) でも、ファイルのメタデータの全てをコピーすることはできません。

POSIXプラットフォームでは、これはACLやファイルのオーナー、グループが失われることを意味しています。 Mac OSでは、リソースフォーク(resource fork)やその他のメタデータが利用されません。これは、リソースが失われ、ファイルタイプや生成者コード(creator code)が正しくなくなることを意味しています。 Windowsでは、ファイルオーナー、ACL、代替データストリームがコピーされません。

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

shutil.copyfileobj(fsrc, fdst[, length])

ファイル形式のオブジェクト fsrc の内容を fdst へコピーします。整数値 length は与えられた場合バッファサイズを表します。特に length が負の場合、チャンク内のソースデータを繰り返し操作することなくデータをコピーします。デフォルトでは、制御不能なメモリ消費を避けるためにデータはチャンク内に読み込まれます。 fsrc オブジェクトの現在のファイル位置が0でない場合、現在の位置からファイル終端までの内容のみがコピーされることに注意してください。

shutil.copyfile(src, dst, *, follow_symlinks=True)

src という名前のファイルの内容 (メタデータを含まない) を dst という名前のファイルにコピーし、dst を返します。 src と dst は文字列でパス名を指定します。 dst は完全な対象ファイル名でなければなりません。対象としてディレクトリ名を指定したい場合は shutil.copy() を参照してください。 src と dst が同じファイルだった場合、 SameFileError を送出します。

dst は書き込み可能でなければなりません。そうでない場合、 OSError 例外を送出します。 dst がすでに存在する場合、そのファイルは置き換えられます。キャラクタデバイスやブロックデバイスなどの特殊なファイルとパイプをこの関数でコピーすることはできません。

follow_symlinks が偽で src がシンボリックリンクの場合、 src のリンク先をコピーする代わりに新しいシンボリックリンクを作成します。

バージョン 3.3 で変更: 以前は OSError の代わりに IOError が送出されていました。 follow_symlinks 引数が追加されました。 dst を返すようになりました。

バージョン 3.4 で変更: Error の代わりに SameFileError を送出します。後者は前者のサブクラスなのでこの変更は後方互換です。

exception shutil.SameFileError

copyfile() のコピー元と先が同じファイルの場合送出されます。

バージョン 3.4 で追加.

shutil.copymode(src, dst, *, follow_symlinks=True)

パーミッションを src から dst にコピーします。ファイルの内容、オーナー、グループには影響しません。 src と dst は文字列でファイルのパス名を指定します。 follow_symlinks が偽で、src および dst がシンボリックリンクの場合、 copymode() は (リンク先ではなく) dst 自体のモードを変更します。この機能は全てのプラットフォームで使えるわけではありません。詳しくは copystat() を参照してください。シンボリックリンクの変更をしようとした時、 copymode() がローカルのプラットフォームでシンボリックリンクを変更できない場合は何もしません。

バージョン 3.3 で変更: follow_symlinks 引数が追加されました。

shutil.copystat(src, dst, *, follow_symlinks=True)

パーミッション、最終アクセス時間、最終変更時間、その他のフラグを src から dst にコピーします。 Linux では、 copystat() は可能なら "拡張属性" もコピーします。ファイルの内容、オーナー、グループには影響しません。 src と dst は文字列でファイルのパス名を指定します。

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 を参照して下さい。

バージョン 3.3 で変更: follow_symlinks 引数と Linux の拡張属性がサポートされました。

shutil.copy(src, dst, *, follow_symlinks=True)

ファイル src をファイルまたはディレクトリ dst にコピーします。 src と dst は両方共文字列でなければなりません。 dst がディレクトリを指定している場合、ファイルは dst の中に、 src のベースファイル名を使ってコピーされます。新しく作成したファイルのパスを返します。

follow_symlinks が偽で、 src がシンボリックリンクの場合、 dst はシンボリックリンクとして作成されます。 follow_symlinks が真で src がシンボリックリンクの場合、 dst には src のリンク先のファイルがコピーされます。

copy() はファイルのデータとパーミッションをコピーします。 (os.chmod() を参照) その他の、ファイルの作成時間や変更時間などのメタデータはコピーしません。 コピー元のファイルのメタデータを保存したい場合は、 copy2() を利用してください。

バージョン 3.3 で変更: follow_symlinks 引数が追加されました。新しく作成されたファイルのパスを返すようになりました。

shutil.copy2(src, dst, *, follow_symlinks=True)

Identical to copy() except that copy2() also attempts to preserve file metadata.

follow_symlinks が偽で、 src がシンボリックリンクの場合、 copy2() は src のシンボリックリンクからすべてのメタデータを新規に作成した dst のシンボリックリンクにコピーしようとします。しかしながら、この機能は全てのプラットフォームで利用できるわけではありません。機能の幾つか、もしくは全てが利用できないプラットフォームの場合、 copy2() は可能な限り全てのメタデータをコピーします。copy2() が失敗を返すことはありません。

copy2() はファイルのメタデータをコピーするために copystat() を利用します。シンボリックリンクのメタデータを変更するためのプラットフォームサポートについては copystat() を参照して下さい。

バージョン 3.3 で変更: follow_symlinks 引数が追加されました。 拡張ファイルシステム属性もコピーしようと試みます (現在は Linux のみ)。新しく作成されたファイルへのパスを返すようになりました。

shutil.ignore_patterns(*patterns)

このファクトリ関数は、 copytree() 関数の ignore 引数に渡すための呼び出し可能オブジェクトを作成します。 glob形式の patterns にマッチするファイルやディレクトリが無視されます。下の例を参照してください。

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False)

src をルートにしたディレクトリツリー全体をコピーして、コピー先ディレクトリを返します。コピー先ディレクトリ dst は事前に存在していてはならず、足りない親ディレクトリと合わせて作成されます。ディレクトリの各種時間やパーミッションは copystat() でコピーし、各ファイルは shutil.copy2() でコピーします。

symlinks が真の場合、ソースツリー内のシンボリックリンクは新しいツリーでもシンボリックになり、元のシンボリックリンクのメタデータはプラットフォームが許す限りコピーされます。偽の場合や省略された場合、リンク先のファイルの内容とメタデータが新しいツリーにコピーされます。

symlinks が偽の場合、リンク先のファイルが存在しなければ、コピー処理終了時に送出される Error 例外のエラーリストに例外が追加されます。オプションの ignore_dangling_symlinks フラグを真に設定してこのエラーを送出させないこともできます。このオプションは os.symlink() をサポートしていないプラットフォーム上では効果がないことに注意してください。

ignore は copytree() が走査しているディレクトリと os.listdir() が返すその内容のリストを引数として受け取ることのできる呼び出し可能オブジェクトでなければなりません。 copytree() は再帰的に呼び出されるので、 ignore はコピーされる各ディレクトリ毎に呼び出されます。 ignore の戻り値はカレントディレクトリに相対的なディレクトリ名およびファイル名のシーケンス（すなわち第二引数の項目のサブセット）でなければなりません。それらの名前はコピー中に無視されます。 ignore_patterns() を用いて glob 形式のパターンによって無視する呼び出し可能オブジェクトを作成することが出来ます。

例外が発生した場合、理由のリストとともに Error を送出します。

copy_function は各ファイルをコピーするために利用される呼び出し可能オブジェクトでなければなりません。copy_function はコピー元のパスとコピー先のパスを引数に呼び出されます。デフォルトでは shutil.copy2() が利用されますが、同じ特徴を持つ関数 (shutil.copy() など) ならどれでも利用可能です。

バージョン 3.3 で変更: symlinks が偽の場合メタデータをコピーします。 dst を返すようになりました。

バージョン 3.2 で変更: カスタムコピー機能を提供できるように copy_function 引数が追加されました。 symlinks が偽の時にダングリング (宙ぶらりんの) シンボリックリンクエラーを送出させないために ignore_dangling_symlinks 引数が追加されました。

shutil.rmtree(path, ignore_errors=False, onerror=None)

ディレクトリツリー全体を削除します。 path はディレクトリを指していなければなりません (ただしディレクトリに対するシンボリックリンクではいけません)。ignore_errors が真である場合、削除に失敗したことによるエラーは無視されます。偽や省略された場合はこれらのエラーは onerror で与えられたハンドラを呼び出して処理され、onerror が省略された場合は例外を送出します。

注釈

必要な fd ベースの関数をサポートしているプラットフォームでは、 シンボリックリンク攻撃に耐性のあるバージョンの rmtree() がデフォルトで利用されます。それ以外のプラットフォームでは、 rmtree() の実装はシンボリックリンク攻撃の影響を受けます。適当なタイミングと環境で攻撃者はファイルシステム上のシンボリックリンクを操作して、それ以外の方法ではアクセス不可能なファイルを削除することが出来ます。アプリケーションは、どちらのバージョンの rmtree() が利用されているかを知るために関数のデータ属性 rmtree.avoids_symlink_attacks を利用することができます。

onerror を指定する場合、 function, path, excinfo の3つの引数を受け取る呼び出し可能オブジェクトでなければなりません。

最初の引数 function は例外を送出した関数で、プラットフォームや実装に依存します。第二引数 path は function に渡されたパス名です。第三引数 excinfo は sys.exc_info() が返した例外の情報です。 onerror が送出した例外は捕捉されません。

バージョン 3.3 で変更: プラットフォームが fd ベースの関数をサポートする場合に自動的に使用されるシンボリックリンク攻撃に耐性のあるバージョンが追加されました。

rmtree.avoids_symlink_attacks

プラットフォームと実装がシンボリックリンク攻撃に耐性のあるバージョンの rmtree() を提供しているかどうかを示します。現在のところ、この属性は fd ベースのディレクトリアクセス関数をサポートしているプラットフォームでのみ真になります。

バージョン 3.3 で追加.

shutil.move(src, dst, copy_function=copy2)

ファイルまたはディレクトリ (src) を再帰的に別の場所 (dst) に移動して、移動先を返します。

移動先が存在するディレクトリの場合、 src はそのディレクトリの中へ移動します。移動先が存在していてそれがディレクトリでない場合、 os.rename() の動作によっては上書きされることがあります。

ターゲットが現在のファイルシステム上にある場合、 os.rename() が使用されます。 それ以外の場合 copy_function を使用して src を dst にコピーし、その後削除します。 シンボリックリンクの場合には、 src のターゲットを指す新しいシンボリックリンクが、 dst の中または dst として作成され、 src が削除されます。

copy_function を指定する場合、 src と dst の 2 つの引数を持つ呼び出し可能オブジェクトを指定する必要があります。このオブジェクトは、os.rename() を使用できない場合に src を dest にコピーするために使用されます。ソースがディレクトリの場合、 copytree() が呼び出され、そのディレクトリを copy_function() に渡します。デフォルトの copy_function は copy2() です。copy() を copy_function として使用すると、メタデータをともにコピーすることができない場合に移動を成功させることができます。この場合、メタデータはまったくコピーされません。

バージョン 3.3 で変更: 異なるファイルシステムに対する明示的なシンボリックリンク処理が追加されました。これにより GNU mv の振る舞いに適応するようになります。 dst を返すようになりました。

バージョン 3.5 で変更: キーワード引数 copy_function が追加されました。

shutil.disk_usage(path)

指定されたパスについて、ディスクの利用状況を、名前付きタプル (named tuple) で返します。このタプルには total, used, free という属性があり、それぞれトータル、使用中、空きの容量をバイト単位で示します。Windowsでは、 path はディレクトリでなくてはいけません。 Unixではファイル、または、ディレクトリにすることができます。

バージョン 3.3 で追加.

Availability: Unix, Windows.

shutil.chown(path, user=None, group=None)

指定された path のオーナー user と/または group を変更します。

user はシステムのユーザー名か uid です。 group も同じです。少なくともどちらかの引数を指定する必要があります。

内部で利用している os.chown() も参照してください。

利用可能な環境: Unix。

バージョン 3.3 で追加.

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)

cmd を実行しようとした時に実行される実行ファイルのパスを返します。 cmd を呼び出せない場合は None を返します。

mode は os.access() に渡すパーミッションマスクで、デフォルトではファイルが存在して実行可能であることを確認します。

path が指定されなかった場合、 os.environ() が利用され、 "PATH" の値を返すか os.defpath にフォールバックします。

Windows では、 path を指定した場合もデフォルト値を使った場合も、カレントディレクトリが最初に探されます。これはコマンドシェルが実行ファイルを探すときの動作です。また、 cmd を path から検索するときに、 PATHEXT 環境変数も利用します。例えば、 shutil.which("python") を実行した場合、 which() は PATHEXT を参照して path ディレクトリから python.exe を探すべきだということを把握します。例えば、 Windows では:

>>> shutil.which("python")
'C:\\Python33\\python.EXE'

バージョン 3.3 で追加.

exception shutil.Error

この例外は複数ファイルの操作を行っているときに生じる例外をまとめたものです。 copytree() に対しては例外の引数は3つのタプル(srcname, dstname, exception)からなるリストです。

copytree の例

以下は前述の copytree() 関数のドキュメント文字列を省略した実装例です。本モジュールで提供される他の関数の使い方を示しています。

def copytree(src, dst, symlinks=False):
    names = os.listdir(src)
    os.makedirs(dst)
    errors = []
    for name in names:
        srcname = os.path.join(src, name)
        dstname = os.path.join(dst, name)
        try:
            if symlinks and os.path.islink(srcname):
                linkto = os.readlink(srcname)
                os.symlink(linkto, dstname)
            elif os.path.isdir(srcname):
                copytree(srcname, dstname, symlinks)
            else:
                copy2(srcname, dstname)
            # XXX What about devices, sockets etc.?
        except OSError as why:
            errors.append((srcname, dstname, str(why)))
        # catch the Error from the recursive copytree so that we can
        # continue with other files
        except Error as err:
            errors.extend(err.args[0])
    try:
        copystat(src, dst)
    except OSError as why:
        # can't copy file access times on Windows
        if why.winerror is None:
            errors.extend((src, dst, str(why)))
    if errors:
        raise Error(errors)

ignore_patterns() ヘルパ関数を利用する、もう1つの例です。

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 の例

次の例は、Windows で一部のファイルが読み取り専用のビットセットを含む場合に、ディレクトリツリーを削除する方法を示します。onerror コールバックを使用して、読み取り専用のビットを消去し、削除を再試行します。結果として失敗が発生した場合、それらは伝搬されます:

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, onerror=remove_readonly)

アーカイブ化操作

バージョン 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 は、作成するファイルの、パスを含み、フォーマットごとの拡張子を抜いた名前です。 format はアーカイブフォーマットで "zip" (zlib モジュールが利用可能な場合), "tar", "gztar" (zlib モジュールが利用可能な場合), "bztar" (bz2 モジュールが利用可能な場合), "xztar" (lzma モジュールが利用可能な場合) のいずれかです。

root_dir は、アーカイブのルートディレクトリとなるディレクトリです。例えば、一般的には、アーカイブを作成する前に root_dir をカレントディレクトリにします。

base_dir は、アーカイブを開始するディレクトリです。すなわち、 base_dir は、アーカイブのすべてのファイルとディレクトリに共通する接頭辞になります。

root_dir と base_dir のどちらも、デフォルトはカレントディレクトリです。

dry_run が真の場合、アーカイブは作成されませんが実行される操作は logger に記録されます。

owner と group は、tar アーカイブを作成するときに使われます。デフォルトでは、カレントのオーナーとグループを使います。

logger は PEP 282 に互換なオブジェクトでなければなりません。これは普通は logging.Logger のインスタンスです。

verbose 引数は使用されず、非推奨です。

shutil.get_archive_formats()

アーカイブ化をサポートしているフォーマットのリストを返します。返されるシーケンスのそれぞれの要素は、タプル (name, description) です。

デフォルトでは、 shutil は次のフォーマットを提供しています。

  • zip: ZIP ファイル (zlib モジュールが利用可能な場合)。
  • tar: 圧縮されていない tar ファイル。
  • 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() に渡されます)。

extra_args は、与えられた場合、 (name, value) の対のシーケンスで、アーカイバ呼び出し可能オブジェクトが使われるときに追加のキーワード引数として使われます。

description は、アーカイバのリストを返す get_archive_formats() で使われます。デフォルトでは空の文字列です。

shutil.unregister_archive_format(name)

アーカイブフォーマット name を、サポートされているフォーマットのリストから取り除きます。

shutil.unpack_archive(filename[, extract_dir[, format]])

アーカイブをアンパックします。 filename はアーカイブのフルパスです。

extract_dir はアーカイブをアンパックする先のディレクトリ名です。指定されなかった場合は現在の作業ディレクトリを利用します。

format はアーカイブフォーマットで、 "zip", "tar", "gztar", "bztar", "xztar" あるいは register_unpack_format() で登録したその他のフォーマットのどれかです。 指定されなかった場合、 unpack_archive() はアーカイブファイル名の拡張子に対して登録されたアンパッカーを利用します。 アンパッカーが見つからなかった場合、 ValueError を発生させます。

バージョン 3.7 で変更: Accepts a path-like object for filename and extract_dir.

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])

アンパック用のフォーマットを登録します。 name はフォーマット名で、 extensions はそのフォーマットに対応する拡張子 (例えば Zip ファイルに対して .zip) のリストです。

function はアーカイブをアンパックするための呼び出し可能オブジェクトです。このオブジェクトはアーカイブのパスと、アーカイブを展開するディレクトリのパスを引数に受け取ります。

extra_args は省略可能な引数で、呼び出し可能オブジェクトに渡すキーワード引数を (name, value) というタプルのシーケンスにしたものです。

フォーマットの説明として 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

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

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.

バージョン 3.3 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルとディレクトリへのアクセス »


macpath --- Mac OS 9 のパス操作関数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルとディレクトリへのアクセス »

macpath --- Mac OS 9 のパス操作関数

ソースコード: Lib/macpath.py

Deprecated since version 3.7, will be removed in version 3.8.

このモジュールは os.path モジュールの Macintosh 9 (およびそれ以前) 用の実装です。これを使用すると、古い形式の Macintosh のパス名を Mac OS X (あるいはその他の任意のプラットフォーム) 上で扱うことができます。

次の関数がこのモジュールで利用できます。 normcase() 、 normpath() 、 isabs() 、 join() 、 split() 、 isdir() 、 isfile() 、 walk() 、 exists() 。 os.path で利用できる他の関数については、ダミーの関数として相当する物が利用できます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルとディレクトリへのアクセス »


データの永続化

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

データの永続化

この章で解説されるモジュール群は Python データをディスクに永続的な形式で保存します。モジュール pickle とモジュール marshal は多くの Python データ型をバイト列に変換し、バイト列から再生成します。様々な DBM 関連モジュールはハッシュを基にした、文字列から他の文字列へのマップを保存するファイルフォーマット群をサポートします。

この章で解説されるモジュールのリスト:

  • pickle --- Python オブジェクトの直列化
    • 他の Python モジュールとの関係
      • marshal との比較
      • json との比較
    • データストリームの形式
    • モジュールインタフェース
    • pickle 化、非 pickle 化できるもの
    • クラスインスタンスの pickle 化
      • 外部オブジェクトの永続化
      • ディスパッチテーブル
      • 状態を持つオブジェクトの扱い
    • グローバル変数を制限する
    • 性能
    • 使用例
  • copyreg --- pickle サポート関数を登録する
    • 使用例
  • shelve --- Python オブジェクトの永続化
    • 制限事項
    • 使用例
  • marshal --- 内部使用向けの Python オブジェクト整列化
  • dbm --- Unix "データベース" へのインタフェース
    • dbm.gnu --- GNU による dbm 拡張
    • dbm.ndbm --- ndbm に基づくインタフェース
    • dbm.dumb --- 可搬性のある DBM 実装
  • sqlite3 --- SQLite データベースに対する DB-API 2.0 インタフェース
    • モジュールの関数と定数
    • Connection オブジェクト
    • カーソルオブジェクト
    • Row オブジェクト
    • 例外
    • SQLite と Python の型
      • はじめに
      • 追加された Python の型を SQLite データベースに格納するために適合関数を使う
        • オブジェクト自身で適合するようにする
        • 適合関数を登録する
      • SQLite の値を好きな Python 型に変換する
      • デフォルトの適合関数と変換関数
    • トランザクション制御
    • sqlite3 の効率的な使い方
      • ショートカットメソッドを使う
      • 位置ではなく名前でカラムにアクセスする
      • コネクションをコンテキストマネージャーとして利用する
    • 既知の問題
      • マルチスレッド

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


pickle --- Python オブジェクトの直列化

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データの永続化 »

pickle --- Python オブジェクトの直列化

ソースコード: Lib/pickle.py

pickle モジュールは Python オブジェクトの直列化および直列化されたオブジェクトの復元のためのバイナリプロトコルを実装しています。"Pickle 化" は Python オブジェクト階層をバイトストリームに変換する処理、"非 pickle 化" は (バイナリファイル または バイトライクオブジェクト から) バイトストリームをオブジェクト階層に復元する処理を意味します。pickle 化 (および非 pickle 化) は "直列化 (serialization)"、"整列化 (marshalling)"、あるいは [1] "平坦化 (flattening)" とも呼ばれますが、混乱を避けるため、ここでは "Pickle 化"、"非 pickle 化" で統一します。

警告

pickle モジュールはエラーや不正に生成されたデータに対して安全ではありません。信頼できない、あるいは認証されていないソースから受け取ったデータを非 pickle 化してはいけません。

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

marshal との比較

Python には marshal と呼ばれるより原始的な直列化モジュールがありますが、一般的に Python オブジェクトを直列化する方法としては pickle を選ぶべきです。 marshal は基本的に .pyc ファイルをサポートするために存在しています。

pickle モジュールはいくつかの点で marshal と明確に異なります:

  • pickle モジュールでは、同じオブジェクトが再度直列化されることのないよう、すでに直列化されたオブジェクトについて追跡情報を保持します。 marshal はこれを行いません。

    この機能は再帰的オブジェクトと共有オブジェクトの両方に重要な関わりをもっています。再帰的オブジェクトとは自分自身に対する参照を持っているオブジェクトです。再帰的オブジェクトは marshal で扱うことができず、実際、再帰的オブジェクトを marshal 化しようとすると Python インタプリタをクラッシュさせてしまいます。共有オブジェクトは、直列化しようとするオブジェクト階層の異なる複数の場所で同じオブジェクトに対する参照が存在する場合に生じます。共有オブジェクトを共有のままにしておくことは、変更可能なオブジェクトの場合には非常に重要です。

  • marshal はユーザ定義クラスやそのインスタンスを直列化するために使うことができません。 pickle はクラスインスタンスを透過的に保存したり復元したりすることができますが、クラス定義をインポートすることが可能で、かつオブジェクトが保存された際と同じモジュールで定義されていなければなりません。

  • The marshal serialization format is not guaranteed to be portable across Python versions. Because its primary job in life is to support .pyc files, the Python implementers reserve the right to change the serialization format in non-backwards compatible ways should the need arise. The pickle serialization format is guaranteed to be backwards compatible across Python releases provided a compatible pickle protocol is chosen and pickling and unpickling code deals with Python 2 to Python 3 type differences if your data is crossing that unique breaking change language boundary.

json との比較

pickle プロトコルと JSON (JavaScript Object Notation) との基本的な違いは以下のとおりです:

  • JSON はテキストの直列化フォーマット (大抵の場合 utf-8 にエンコードされますが、その出力は Unicode 文字列です) で、pickle はバイナリの直列化フォーマットです;
  • JSON は人間が読める形式ですが、pickle はそうではありません;
  • JSON は相互運用可能で Python 以外でも広く使用されていますが、pickle は Python 固有です;
  • JSON は、デフォルトでは Python の組み込み型の一部しか表現することができず、カスタムクラスに対しても行えません; pickle は極めて多くの Python 組み込み型を表現できます (その多くは賢い Python 内省機構によって自動的に行われます; 複雑なケースでは 固有のオブジェクト API によって対応できます)。

参考

json モジュール: JSON への直列化および復元を行うための標準ライブラリモジュール。

データストリームの形式

pickle によって使用されるデータフォーマットは Python 固有です。これは、JSON や XDR のような外部標準によって (例えばポインター共有を表わすことができないといったような) 制限を受けることがないという利点があります; ただし、これは非 Python プログラムが pickle された Python オブジェクトを再構成することができないということも意味します。

デフォルトでは、pickle データフォーマットは比較的コンパクトなバイナリ表現を使用します。サイズの抑制目的の最適化が必要なら、pickel されたデータを効率的に 圧縮する ことができます。

pickletools モジュールには pickle によって生成されたデータストリームを解析するためのツールが含まれます。pickletools のソースコードには、pickle プロトコルで使用される命令コードに関する詳細なコメントがあります。

現在 pickle 化には 5 種類のプロトコルを使用できます。より高いプロトコルを使用するほど、作成された pickle を読み込むためにより高い Python のバージョンが必要になります。

  • プロトコルバージョン 0 はオリジナルの「人間に判読可能な」プロトコルで、Python の初期のバージョンとの後方互換性を持ちます。
  • プロトコルバージョン 1 は旧形式のバイナリフォーマットで、これも Python の初期バージョンと互換性があります。
  • プロトコルバージョン 2 は Python 2.3 で導入されました。このバージョンでは 新方式のクラス のより効率的な pickle 化を提供しました。プロトコル 2 による改良に関する情報は PEP 307 を参照してください。
  • プロトコルバージョン 3 は Python 3.0 で追加されました。このバージョンで bytes オブジェクトをサポートしました。これは Python 2.x では非 pickle 化できません。これはデフォルトのプロトコルで、他の Python 3 バージョンとの互換性が求められる場合の推奨プロトコルです。
  • プロトコルバージョン 4 は Python 3.4 で追加されました。このバージョンでは巨大なオブジェクトのサポート、より多くの種類のオブジェクトの pickle 化、および一部のデータ形式の最適化が行われました。プロトコル 4 による改良に関する情報は PEP 3154 を参照してください。

注釈

直列化は永続性より原始的な概念です。 pickle はファイルオブジェクトの読み書きを行いますが、永続オブジェクトの命名に関する問題にも、(さらに困難な) 永続オブジェクトへの並列アクセスに関する問題にも対応しません。pickle モジュールは複雑なオブジェクトをバイトストリームに変換し、バイトストリームから同じ内部構造のオブジェクトに復元することができます。これらのバイトストリームはファイルに出力されることが多いでしょうが、ネットワークを介して送信したり、データベースに格納することもありえます。shelve モジュールは、オブジェクトを DBM 方式のデータベースファイル上で pickle 化および非 pickle 化するシンプルなインターフェイスを提供します。

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

オブジェクト階層を直列化するには、dumps() 関数を呼ぶだけです。同様に、データストリームを復元するには、loads() 関数を呼びます。しかし、直列化および復元に対してより多くのコントロールを行いたい場合、それぞれ Pickler または Unpickler オブジェクトを作成することができます。

pickle モジュールは以下の定数を提供しています:

pickle.HIGHEST_PROTOCOL

利用可能なうち最も高い プロトコルバージョン (整数)。この値は protocol 値として関数 dump() および dumps() と、Pickler コンストラクターに渡すことができます。

pickle.DEFAULT_PROTOCOL

pickle 化で使用されるデフォルトの プロトコルバージョン (整数)。HIGHEST_PROTOCOL より低い値になる場合があります。現在のデフォルトプロトコルは Python 3 用に設計された 3 です。

この pickle 化の手続きを便利にするために、 pickle モジュールでは以下の関数を提供しています:

pickle.dump(obj, file, protocol=None, *, fix_imports=True)

obj を pickle 化し、すでにオープンしている ファイルオブジェクト file に書き込みます。Pickler(file, protocol).dump(obj) と等価です。

任意の引数 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 でも読み込み可能です。

pickle.dumps(obj, protocol=None, *, fix_imports=True)

ファイルに書く代わりに、bytes オブジェクトとしてオブジェクトの pickle 表現を返します。

引数 protocol および fix_imports は dump() では同じ意味になります。

pickle.load(file, *, fix_imports=True, encoding="ASCII", errors="strict")

pickle オブジェクト表現を、オープンしている ファイルオブジェクト file から読み込み、その中で指定されているオブジェクト階層に再構成して返します。これは Unpickler(file).load() と等価です。

pickle のプロトコルバージョンは自動的に検出されます。したがって protocol 引数は必要ありません。pickle 化オブジェクト表現より後のバイト列は無視されます。

引数 file には 2 つのメソッド、整数引数をとる read() と、引数を要求しない readline() メソッドがなければなりません。両方のメソッドはバイト列を返す必要があります。そのため file には、バイナリ読み込みとしてオープンされたディスク上のファイル、io.BytesIO オブジェクト、あるいはこのインタフェースに適合するその他のカスタムオブジェクトなどを指定できます。

Optional keyword arguments are fix_imports, encoding and errors, which are used to control compatibility support for pickle stream generated by Python 2. If fix_imports is true, pickle will try to map the old Python 2 names to the new names used in Python 3. The encoding and errors tell pickle how to decode 8-bit string instances pickled by Python 2; these default to 'ASCII' and 'strict', respectively. The encoding can be 'bytes' to read these 8-bit string instances as bytes objects. Using encoding='latin1' is required for unpickling NumPy arrays and instances of datetime, date and time pickled by Python 2.

pickle.loads(bytes_object, *, fix_imports=True, encoding="ASCII", errors="strict")

bytes オブジェクトから pickle 化されたオブジェクト階層を読み込んで、その中で指定されたオブジェクト階層に再構成して返します。

pickle のプロトコルバージョンは自動的に検出されます。したがって protocol 引数は必要ありません。pickle 化オブジェクト表現より後のバイト列は無視されます。

Optional keyword arguments are fix_imports, encoding and errors, which are used to control compatibility support for pickle stream generated by Python 2. If fix_imports is true, pickle will try to map the old Python 2 names to the new names used in Python 3. The encoding and errors tell pickle how to decode 8-bit string instances pickled by Python 2; these default to 'ASCII' and 'strict', respectively. The encoding can be 'bytes' to read these 8-bit string instances as bytes objects. Using encoding='latin1' is required for unpickling NumPy arrays and instances of datetime, date and time pickled by Python 2.

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 モジュールでは、2 つのクラス Pickler および Unpickler を提供しています:

class pickle.Pickler(file, protocol=None, *, fix_imports=True)

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 でも読み込み可能です。

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 属性を持てば、そのクラスのインスタンスに対するデフォルトのディスパッチテーブルとして使用されます。

使用例については ディスパッチテーブル を参照してください。

バージョン 3.3 で追加.

fast

廃止予定です。真値が設定されれば高速モードを有効にします。高速モードは、メモの使用を無効にします。それにより余分な PUT 命令コードを生成しなくなるので pickle 化処理が高速化します。自己参照オブジェクトに対しては使用すべきではありません。さもなければ Pickler に無限再帰を起こさせるでしょう。

よりコンパクトな pickle 化を必要とする場合は、pickletools.optimize() を使用してください。

class pickle.Unpickler(file, *, fix_imports=True, encoding="ASCII", errors="strict")

これは pickle データストリームの読み込みのためにバイナリファイルをとります。

pickle のプロトコルバージョンは自動的に検出されます。したがって protocol 引数は必要ありません。

引数 file には2つのメソッド、整数引数をとる read() メソッドと、引数を要求しない readline() 引数がなければなりません。両方のメソッドはバイトを返す必要があります。そのため file には、バイナリ読み込みのために開かれたディスク上のファイルオブジェクト、 io.BytesIO オブジェクト、あるいはこのインタフェースに適合するその他のカスタムオブジェクトなどを指定することが可能です。

任意のキーワード引数 fix_imports、encoding および errors は Python 2 で作成された pickle ストリームとの互換性を制御するために使用します。fix_imports が真の場合、pickle は古い Python 2 の名前と Python 3 で使用されている新しい名前との対応付けを試みます。encoding と errors は Python 2 で pickle 化された 8 ビット文字列インスタンスのデコード方法を指定します; デフォルトではそれぞれ 'ASCII' および 'strict' になります。8 ビット文字列インスタンスをバイト列オブジェクトとして読み込みたい場合には、encoding に 'bytes' を指定します。

load()

コンストラクターで与えられたオープンしたファイルオブジェクトから pickle 化オブジェクト表現を読み込み、その中で指定されたオブジェクト階層に再構成して返します。pickle 化オブジェクト表現より後のバイト列は無視されます。

persistent_load(pid)

デフォルトで UnpicklingError を送出します。

もし定義されていれば、persistent_load() は永続的な ID pid によって指定されたオブジェクトを返す必要があります。永続的な ID が無効な場合、UnpicklingError を送出しなければなりません。

詳細および使用例については 外部オブジェクトの永続化 を参照してください。

find_class(module, name)

必要なら module をインポートして、そこから name という名前のオブジェクトを返します。ここで module および name 引数は str オブジェクトです。その名前が示唆することに反して find_class() は関数を探すためにも使われることに注意してください。

サブクラスは、どんな型のオブジェクトを、どのようにロードするか (潜在的にはセキュリティリスクの減少) に関する制御を得るためにこれをオーバーライドすることができます。詳細に関しては グローバル変数を制限する を参照してください。

pickle 化、非 pickle 化できるもの

以下の型は pickle 化できます:

  • None 、 True 、および False
  • 整数、浮動小数点数、複素数
  • 文字列、バイト列、バイト配列
  • pickle 化可能なオブジェクトからなるタプル、リスト、集合および辞書
  • モジュールのトップレベルで定義された関数 (def で定義されたもののみで lambda で定義されたものは含まない)
  • モジュールのトップレベルで定義されている組込み関数
  • モジュールのトップレベルで定義されているクラス
  • __dict__ 属性を持つクラス、あるいは __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 load(cls, attributes):
    obj = cls.__new__(cls)
    obj.__dict__.update(attributes)
    return obj

クラスは、いくつかの特殊メソッドを提供することによって、デフォルトの振る舞いを変更することができます:

object.__getnewargs_ex__()

In protocols 2 and newer, classes that implements the __getnewargs_ex__() method can dictate the values passed to the __new__() method upon unpickling. The method must return a pair (args, kwargs) where args is a tuple of positional arguments and kwargs a dictionary of named arguments for constructing the object. Those will be passed to the __new__() method upon unpickling.

クラスの __new__() メソッドにキーワード引数のみ定義されている場合はこのメソッドを実装すべきです。そうしない場合、互換性のため __getnewargs__() メソッドの実装を推奨します。

バージョン 3.6 で変更: __getnewargs_ex__() is now used in protocols 2 and 3.

object.__getnewargs__()

This method serves a similar purpose as __getnewargs_ex__(), but supports only positional arguments. It must return a tuple of arguments args which will be passed to the __new__() method upon unpickling.

__getnewargs__() will not be called if __getnewargs_ex__() is defined.

バージョン 3.6 で変更: Before Python 3.6, __getnewargs__() was called instead of __getnewargs_ex__() in protocols 2 and 3.

object.__getstate__()

クラスはそのインスタンスをどう pickle 化するかについてさらに影響を与えることができます; クラスに __getstate__() メソッドが定義されていた場合それが呼ばれ、返り値のオブジェクトはインスタンスの辞書ではなく、インスタンスの内容が pickle 化されたものになります。__getstate__() がないときは通常通りインスタンスの __dict__ が pickle 化されます。

object.__setstate__(state)

非 pickle 化に際して、クラスが __setstate__() を定義している場合、それは非 pickle 化された状態とともに呼び出されます。その場合、状態オブジェクトが辞書でなければならないという要求はありません。そうでなければ、 pickle された状態は辞書で、その要素は新しいインスタンスの辞書に割り当てられます。

注釈

__getstate__() が偽値を返す場合、非 pickle 化時に __setstate__() メソッドは呼ばれません。

__getstate__() および __setstate__() メソッドの使い方に関する詳細な情報については 状態を持つオブジェクトの扱い 節を参照してください。

注釈

非 pickle 化時、__getattr__()、__getattribute__() あるいは __setattr__() のような一部のメソッドがインスタンス上で呼び出されることがあります。この場合、これらのメソッドはいくつかの内部不変条件が真であることに依存しており、そのような不変条件を立証するために、データ型には __getnewargs__() または __getnewargs_ex__() が実装されていなければなりません; さもなくば、__new__() も __init__() も呼び出されません。

これらから見るように、pickle は上記のメソッドを直接使用しません。実際には、これらのメソッドは __reduce__() 特殊メソッドを実装するコピープロトコルの一部です。コピープロトコルは、pickle 化とオブジェクトのコピーに必要な、データを取得するための統一されたインタフェースを提供します。 [4]

強力ですが、クラスに __reduce__() メソッドを直接実装することはエラーを起こしやすくなります。この理由のため、クラスの設計者は可能なかぎり高レベルインタフェース (__getnewargs_ex__()、__getstate__() および __setstate__()) を使用するべきです。公開はしているものの、__reduce__() の使用は、あくまでオプションとして、より効果的な pickle 化につながる場合、あるいはその両方の場合のみにしてください。

object.__reduce__()

このインタフェースは現在、以下のように定義されています。 __reduce__() メソッドは引数を取らず、文字列あるいは (こちらの方が好まれますが) タプルのいずれかを返すべきです (返されたオブジェクトは、しばしば "reduce value" と呼ばれます)。

文字列が返された場合、その文字列はグローバル変数の名前として解釈されます。それはオブジェクトのモジュールから見たローカル名であるべきです; pickle モジュールは、オブジェクトのモジュールを決定するためにモジュールの名前空間を検索します。この振る舞いは、典型的にシングルトンで便利です。

タプルが返された場合、それは 2〜5 要素長でなければなりません。オプションのアイテムは省略することができます。あるいはそれらの値として None を渡すことができます。各要素の意味は順に:

  • オブジェクトの初期バージョンを作成するために呼ばれる呼び出し可能オブジェクト。
  • 呼出し可能オブジェクトに対する引数のタプル。呼出し可能オブジェクトが引数を受け取らない場合、空のタプルが与えられなければなりません。
  • 任意で、前述のオブジェクトの __setstate__() メソッドに渡されるオブジェクトの状態。オブジェクトがそのようなメソッドを持たない場合、値は辞書でなければならず、それはオブジェクトの __dict__ 属性に追加されます。
  • 任意で、連続した要素を yield する (シーケンスではなく) イテレーター。これらの要素は obj.append(item) を使用して、あるいはバッチでは obj.extend(list_of_items) を使用して、オブジェクトに追加されます。これは主としてリストのサブクラスに対して使用されますが、適切なシグネチャを持つ append() および extend() メソッドがあるかぎり、他のクラスで使用することもできます。 (append() または extend() のどちらが使用されるかは、どの pickle プロトコルバージョンが使われるかに加えて追加されるアイテムの数にも依存します。したがって、両方をサポートする必要があります)
  • 任意で、連続する key-value ペアを yield する (シーケンスでなく) イテレーター。これらの要素は obj[key] = value を使用して、オブジェクトに格納されます。これは主として辞書のサブクラスに対して使用されますが、__setitem__() を実装しているかぎり他のクラスで使用することもできます。
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)

も同じことをしますが、 MyPickler のすべてのインスタンスはデフォルトで同じディスパッチテーブルを共有します。 copyreg モジュールを使用する等価なコードは

copyreg.pickle(SomeClass, reduce_SomeClass)
f = io.BytesIO()
p = pickle.Pickler(f)

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

ここでは、クラスを pickle 化する振る舞いの変更手順を紹介しています。TextReader クラスはテキストファイルをオープンし、readline() メソッドが呼ばれると、その度に行番号と行の内容を返します。TextReader インスタンスが pickle 化されるとき、ファイルオブジェクトメンバーを 除く すべての属性が保存されます。インスタンスが非 pickle 化されるとき、ファイルは再びオープンされ、最後に読み込んだ位置から読み込みを再開します。このような振る舞いを実装するには __setstate__() および __getstate__() メソッドを使用します。

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!'

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

デフォルトで、非 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, 4+6j],
    '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] This is why lambda functions cannot be pickled: all lambda functions share the same name: <lambda>.
[3] 送出される例外は ImportError や AttributeError になるはずですが、他の例外も起こりえます。
[4] copy モジュールは、浅いコピーと深いコピーの操作にこのプロトコルを使用します。
[5] 英数文字に関する制限は、プロトコル 0 では永続的な ID が改行文字によって区切られるという事実によります。そのため、永続的な ID に何らかの改行文字が含まれると、結果として生じる pickle は判読不能になります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データの永続化 »


copyreg --- pickle サポート関数を登録する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データの永続化 »

copyreg --- pickle サポート関数を登録する

ソースコード: Lib/copyreg.py

copyreg モジュールは、特定のオブジェクトを pickle する際に使われる関数を定義する手段を提供します。 pickle モジュールと copy モジュールは、オブジェクトを pickle/コピーする場合にそれらの関数を使用します。このモジュールは、クラスでないオブジェクトコンストラクタに関する設定情報を提供します。そのようなコンストラクタは、ファクトリ関数か、クラスインスタンスかもしれません。

copyreg.constructor(object)

object を有効なコンストラクタであると宣言します。 object が呼び出し可能でなければ(したがってコンストラクタとして有効でなければ)、 TypeError を発生します。

copyreg.pickle(type, function, constructor=None)

function が型 type のオブジェクトに対する"リダクション"関数として使われるように宣言します。function は文字列か、2要素または3要素を含んだタプルを返さなければなりません。

オプションの constructor パラメータが与えられた場合、それは呼び出し可能オブジェクトで、 function が返した引数のタプルとともに pickle 化時に呼ばれてオブジェクトを再構築するために使われます。 object がクラスの場合、または constructor が呼び出し可能でない場合には TypeError が発生します。

function と constructor に期待されるインタフェースについての詳細については pickle モジュールを参照してください。 pickler オブジェクトまたは pickle.Pickler のサブクラスの dispatch_table 属性を、リダクション関数の宣言のために使うこともできるということは覚えておいてください。

使用例

下記の例は、pickle 関数を登録する方法と、それがどのように使用されるかを示そうとしています:

>>> import copyreg, copy, pickle
>>> class C(object):
...     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)  # doctest: +SKIP
pickling a C instance...
>>> p = pickle.dumps(c)  # doctest: +SKIP
pickling a C instance...

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データの永続化 »


shelve --- Python オブジェクトの永続化

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データの永続化 »

shelve --- Python オブジェクトの永続化

ソースコード: Lib/shelve.py

"シェルフ (shelf, 棚)" は辞書に似た永続性を持つオブジェクトです。 "dbm" データベースとの違いは、シェルフの値 (キーではありません！) は実質上どんな Python オブジェクトにも --- pickle モジュールが扱えるなら何でも --- できるということです。これにはほとんどのクラスインスタンス、再帰的なデータ型、沢山の共有されたサブオブジェクトを含むオブジェクトが含まれます。キーは通常の文字列です。

shelve.open(filename, flag='c', protocol=None, writeback=False)

永続的な辞書を開きます。指定された filename は、根底にあるデータベースの基本ファイル名となります。副作用として、 filename には拡張子がつけられる場合があり、ひとつ以上のファイルが生成される可能性もあります。デフォルトでは、根底にあるデータベースファイルは読み書き可能なように開かれます。オプションの flag パラメータは dbm.open() における flag パラメータと同様に解釈されます。

デフォルトでは、値を整列化する際にはバージョン 3 の pickle 化が用いられます。pickle 化プロトコルのバージョンは protocol パラメータで指定することができます。

Python の意味論により、シェルフには永続的な辞書の可変エントリがいつ変更されたかを知る術がありません。 デフォルトでは、変更されたオブジェクトはシェルフに代入されたとき だけ 書き込まれます (使用例 参照)。 オプションの writeback パラメータが True に設定されている場合は、アクセスされたすべてのエントリはメモリ上にキャッシュされ、 sync() および close() を呼び出した際に書き戻されます; この機能は永続的な辞書上の可変の要素に対する変更を容易にしますが、多数のエントリがアクセスされた場合、膨大な量のメモリがキャッシュのために消費され、アクセスされた全てのエントリを書き戻す (アクセスされたエントリが可変であるか、あるいは実際に変更されたかを決定する方法は存在しないのです) ために、ファイルを閉じる操作が非常に低速になります。

注釈

シェルフが自動的に閉じることに依存しないでください; それがもう必要ない場合は常に close() を明示的に呼ぶか、 shelve.open() をコンテキストマネージャとして使用してください:

with shelve.open('spam') as db:
    db['eggs'] = 'eggs'

警告

shelve モジュールは裏で pickle を使っているので、信頼できないソースからシェルフを読み込むのは危険です。 pickle と同じく、 shelf の読み込みでも任意のコードを実行できるからです。

シェルフオブジェクトは辞書がサポートする全てのメソッドをサポートしています。これにより、辞書ベースのスクリプトから永続的な記憶媒体を必要とするスクリプトに容易に移行できるようになります。

追加でサポートされるメソッドが二つあります:

Shelf.sync()

シェルフが writeback を True にセットして開かれている場合に、キャッシュ中の全てのエントリを書き戻します。また可能な場合は、キャッシュを空にしてディスク上の永続的な辞書を同期します。このメソッドはシェルフを close() によって閉じるとき自動的に呼び出されます。

Shelf.close()

永続的な 辞書 オブジェクトを同期して閉じます。既に閉じられているシェルフに対して呼び出すと ValueError を出し失敗します。

参考

通常の辞書に近い速度をもち、いろいろなストレージフォーマットに対応した、 永続化辞書のレシピ 。

制限事項

  • どのデータベースパッケージが使われるか (例えば dbm.ndbm 、 dbm.gnu) は、どのインタフェースが利用可能かに依存します。従って、データベースを dbm を使って直接開く方法は安全ではありません。データベースはまた、 dbm が使われた場合 (不幸なことに) その制約に縛られます --- これはデータベースに記録されたオブジェクト (の pickle 化された表現) はかなり小さくなければならず、キー衝突が生じた場合に、稀にデータベースを更新することができなくなることを意味します。
  • shelve モジュールは、シェルフに置かれたオブジェクトの 並列した 読み出し/書き込みアクセスをサポートしません (複数の同時読み出しアクセスは安全です)。あるプログラムが書き込みのために開かれたシェルフを持っているとき、他のプログラムはそのシェルフを読み書きのために開いてはいけません。この問題を解決するために Unix のファイルロック機構を使うことができますが、この機構は Unix のバージョン間で異なり、使われているデータベースの実装について知識が必要となります。
class shelve.Shelf(dict, protocol=None, writeback=False, keyencoding='utf-8')

collections.abc.MutableMapping のサブクラスで、 dict オブジェクト内にpickle化された値を保持します。

デフォルトでは、値を整列化する際にはバージョン 3 の pickle 化が用いられます。pickle 化プロトコルのバージョンは protocol パラメータで指定することができます。pickle 化プロトコルについては pickle のドキュメントを参照してください。

writeback パラメータが True に設定されていれば、アクセスされたすべてのエントリはメモリ上にキャッシュされ、ファイルを閉じる際に dict に書き戻されます; この機能により、可変のエントリに対して自然な操作が可能になりますが、さらに多くのメモリを消費し、辞書をファイルと同期して閉じる際に長い時間がかかるようになります。

keyencoding パラメータは、shelf の背後にある dict に対して使われる前にキーをエンコードするのに使用されるエンコーディングです。

Shelf オブジェクトは、コンテキストマネージャとしても使用できます。この場合、 with ブロックが終了する際に、自動的に閉じられます。

バージョン 3.2 で変更: keyencoding パラメータを追加; 以前はキーは常に UTF-8 でエンコードされていました。

バージョン 3.4 で変更: コンテキストマネージャーサポートが追加されました。

class shelve.BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8')

Shelf のサブクラスで、 first(), next(), previous(), last(), set_location() メソッドを外部に提供しています。これらのメソッドは pybsddb にあるサードパーティの bsddb モジュールでは利用可能ですが、他のデータベースモジュールでは利用できません。コンストラクタに渡される dict オブジェクトは上記のメソッドをサポートしていなくてはなりません。通常は、 bsddb.hashopen(), bsddb.btopen() または bsddb.rnopen() のいずれかを呼び出して得られるオブジェクトが条件を満たしています。オプションの protocol, writeback および keyencoding パラメータは Shelf クラスにおけるパラメータと同様に解釈されます。

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 --- 内部使用向けの Python オブジェクト整列化

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データの永続化 »

marshal --- 内部使用向けの Python オブジェクト整列化

このモジュールには Python 値をバイナリ形式で読み書きできるような関数が含まれています。このバイナリ形式は Python 特有のものですが、マシンアーキテクチャ非依存のものです (つまり、Python の値を PC 上でファイルに書き込み、Sun に転送し、そこで読み戻すことができます)。バイナリ形式の詳細は意図的にドキュメント化されていません; この形式は (稀にしかないことですが) Python のバージョン間で変更される可能性があるからです。[1]

このモジュールは汎用の "永続化 (persistence)" モジュールではありません。汎用的な永続化や、RPC 呼び出しを通じた Python オブジェクトの転送については、モジュール pickle および shelve を参照してください。 marshal モジュールは主に、 "擬似コンパイルされた (pseudo-compiled)" コードの .pyc ファイルへの読み書きをサポートするために存在します。したがって、 Python のメンテナンス担当者は、必要が生じれば marshal 形式を後方互換性のないものに変更する権利を有しています。 Python オブジェクトを直列化 (シリアライズ) および非直列化 (デシリアライズ) する場合には、 pickle モジュールを使ってください。 pickle は速度は同等で、バージョン間の互換性が保証されていて、 marshal より広範囲のオブジェクトをサポートしています。

警告

marshal モジュールは、誤ったデータや悪意を持って作成されたデータに対する安全性を考慮していません。信頼できない、もしくは認証されていない出所からのデータを非整列化してはなりません。

すべての Python オブジェクト型がサポートされているわけではありません。一般に、このモジュールによって読み書きすることができるオブジェクトは、その値が Python の特定の起動に依存していないオブジェクトに限ります。次の型がサポートされています。真偽値、整数、浮動小数点数、複素数、文字列、 byte 、bytearray 、タプル、リスト、 set 、frozenset 、辞書、コードオブジェクト。ここで、タプル、リスト、 set 、 frozenset 、辞書は、その中に含まれる値がそれ自身サポートされる場合に限りサポートされます。シングルトン None 、 Ellipsis 、 StopIteration も読み書き (marshalled and unmarshalled) できます。3 未満のフォーマット version では、再帰的なリスト、 set 、辞書を書き出すことはできません (下記参照)。

There are functions that read/write files as well as functions operating on bytes-like objects.

このモジュールでは、以下の関数が定義されています。

marshal.dump(value, file[, version])

Write the value on the open file. The value must be a supported type. The file must be a writeable binary file.

値 (または値に含まれるオブジェクト) がサポートされていない型の場合、 ValueError 例外が送出されます --- しかし、同時にごみのデータがファイルに書き込まれます。このオブジェクトは load() で適切に読み出されることはありません。

version 引数は dump が使用するデータフォーマットを指定します (下記を参照してください)。

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.

注釈

サポートされていない型を含むオブジェクトが dump() で整列化されている場合、 load() は整列化不能な値を None で置き換えます。

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 が使用するデータフォーマットを指定します (下記を参照してください)。

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.

これに加えて、以下の定数が定義されています:

marshal.version

このモジュールが利用するバージョンを表します。バージョン0 は歴史的なフォーマットです。バージョン1 は文字列の再利用をします。バージョン2 は浮動小数点数にバイナリフォーマットを使用します。バージョン3 はオブジェクトのインスタンス化と再帰をサポートします。現在のバージョンは4です。

脚注

[1] このモジュールの名前は (特に) Modula-3 の設計者の間で使われていた用語の一つに由来しています。彼らはデータを自己充足的な形式で輸送する操作に "整列化 (marshalling)" という用語を使いました。厳密に言えば、"整列させる (to marshal)" とは、あるデータを (例えば RPC バッファのように) 内部表現形式から外部表現形式に変換することを意味し、"非整列化 (unmarshalling)" とはその逆を意味します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データの永続化 »


dbm --- Unix "データベース" へのインタフェース

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データの永続化 »

dbm --- Unix "データベース" へのインタフェース

ソースコード: Lib/dbm/__init__.py

dbm は DBM データベースのいくつかの種類 ( dbm.gnu または dbm.ndbm ) に対する汎用的なインタフェースです。これらのモジュールのどれもインストールされていなければ、モジュール dbm.dumb に含まれる低速だが単純な実装が使用されます。Oracle Berkeley DB に対する サードパーティのインタフェース があります。

exception dbm.error

サポートされているモジュールそれぞれによって送出される可能性のある例外を含むタプル。これにはユニークな例外があり、最初の要素として同じく dbm.error という名前の例外が含まれます --- dbm.error が送出される場合、後者(訳注:タプルの dbm.error ではなく例外 dbm.error)が使用されます。

dbm.whichdb(filename)

この関数は、与えられたファイルを開くために、利用可能ないくつかの単純なデータベースモジュール --- dbm.gnu, dbm.ndbm, dbm.dumb --- のどれを使用すべきか推測を試みます。

次の値のうち１つを返します: ファイルが読み取れないか存在しないために開くことができない場合は None; ファイルのフォーマットを推測することができない場合は空文字列 (''); それ以外は 'dbm.ndbm' や 'dbm.gnu' のような、必要なモジュール名を含む文字列。

dbm.open(file, flag='r', mode=0o666)

データベースファイル file を開いて対応するオブジェクトを返します。

データベースファイルが既に存在する場合、その種類を決定するために whichdb() 関数が使用され、適切なモジュールが使用されます; データベースファイルが存在しない場合、上記のリストの中でインポート可能な最初のモジュールが使用されます。

オプションの flag は:

値 | 意味
'r' | 既存のデータベースを読み込み専用で開く (デフォルト)
'w' | 既存のデータベースを読み書き用に開く
'c' | データベースを読み書き用に開く。ただし存在しない場合には新たに作成する
'n' | 常に新たに読み書き用の新規のデータベースを作成する

オプションの mode 引数は、新たにデータベースを作成しなければならない場合に使われる Unix のファイルモードです。標準の値は 8 進数の 0o666 です (この値は現在有効な umask で修飾されます)。

open() によって返されたオブジェクトは辞書とほとんど同じ機能をサポートします; キーとそれに対応付けられた値を記憶し、取り出し、削除することができ、 in 演算子や keys() メソッド、また get() や setdefault() を使うことができます。

バージョン 3.2 で変更: get() と setdefault() がすべてのデータベースモジュールで利用できるようになりました。

キーと値は常に byte 列として格納されます。これは、文字列が使用された場合は格納される前に暗黙的にデフォルトエンコーディングに変換されるということを意味します。

これらのオブジェクトは、 with 文での使用にも対応しています。with 文を使用した場合、終了時に自動的に閉じられます。

バージョン 3.4 で変更: open() が返すオブジェクトに対するコンテキスト管理のプロトコルがネイティブにサポートされました。

以下の例ではホスト名と対応するタイトルをいくつか記録し、データベースの内容を出力します:

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 による dbm 拡張

ソースコード: Lib/dbm/gnu.py

このモジュールは dbm モジュールによく似ていますが、GNU ライブラリ gdbm を使っていくつかの追加機能を提供しています。 dbm.gnu と dbm.ndbm では生成されるファイル形式に互換性がないので注意してください。

dbm.gnu モジュールでは GNU DBM ライブラリへのインタフェースを提供します。 dbm.gnu.gdbm オブジェクトはキーと値が必ず保存の前にバイト列に変換されることを除き、マップ型 (辞書型) と同じように動作します。 gdbm オブジェクトに対して print() を適用してもキーや値を印字することはなく、 items() 及び values() メソッドはサポートされていません。

exception dbm.gnu.error

I/O エラーのような dbm.gnu 特有のエラーで送出されます。誤ったキーの指定のように、一般的なマップ型のエラーに対しては KeyError が送出されます。

dbm.gnu.open(filename[, flag[, mode]])

gdbm データベースを開いて gdbm オブジェクトを返します。 filename 引数はデータベースファイルの名前です。

オプションの flag は:

値 | 意味
'r' | 既存のデータベースを読み込み専用で開く (デフォルト)
'w' | 既存のデータベースを読み書き用に開く
'c' | データベースを読み書き用に開く。ただし存在しない場合には新たに作成する
'n' | 常に新たに読み書き用の新規のデータベースを作成する

以下の追加の文字を flag に追加して、データベースの開きかたを制御することができます:

値 | 意味
'f' | データベースを高速モードで開きます。書き込みが同期されません。
's' | 同期モード。データベースへの変更がすぐにファイルに書き込まれます。
'u' | データベースをロックしません。

全てのバージョンの gdbm で全てのフラグが有効とは限りません。モジュール定数 open_flags はサポートされているフラグ文字からなる文字列です。無効なフラグが指定された場合、例外 error が送出されます。

オプションの mode 引数は、新たにデータベースを作成しなければならない場合に使われる Unix のファイルモードです。標準の値は 8 進数の 0o666 です。

辞書型形式のメソッドに加えて、gdbm オブジェクトには以下のメソッドがあります:

gdbm.firstkey()

このメソッドと nextkey() メソッドを使って、データベースの全てのキーにわたってループ処理を行うことができます。探索は gdbm の内部ハッシュ値の順番に行われ、キーの値に順に並んでいるとは限りません。このメソッドは最初のキーを返します。

gdbm.nextkey(key)

データベースの順方向探索において、key よりも後に来るキーを返します。以下のコードはデータベース db について、キー全てを含むリストをメモリ上に生成することなく全てのキーを出力します:

k = db.firstkey()
while k != None:
    print(k)
    k = db.nextkey(k)
gdbm.reorganize()

大量の削除を実行した後、gdbm ファイルの占めるスペースを削減したい場合、このルーチンはデータベースを再組織化します。この再組織化を使用する方法以外に gdbm オブジェクトがデータベースファイルの大きさを短くすることはありません。サイズを縮小しない場合、削除された部分のファイルスペースは保持され、新たな (キー、値の) ペアが追加される際に再利用されます。

gdbm.sync()

データベースが高速モードで開かれていた場合、このメソッドはディスクにまだ書き込まれていないデータを全て書き込ませます。

gdbm.close()

gdbm データベースをクローズします。

dbm.ndbm --- ndbm に基づくインタフェース

ソースコード: Lib/dbm/ndbm.py

dbm.ndbm モジュールはUnixの"(n)dbm"ライブラリのインタフェースを提供します。 dbmオブジェクトは、キーと値が必ずバイト列である以外は辞書オブジェクトのようなふるまいをします。 print関数などで dbm オブジェクトを出力してもキーと値は出力されません。また、 items() と values() メソッドはサポートされません。

このモジュールは、GNU GDBM互換インタフェースを持った "クラシックな" ndbmインタフェースを使うことができます。 Unix上のビルド時に configure スクリプトで適切なヘッダファイルが割り当られます。

exception dbm.ndbm.error

I/O エラーのような dbm.ndbm 特有のエラーで送出されます。誤ったキーの指定のように、一般的なマップ型のエラーに対しては KeyError が送出されます。

dbm.ndbm.library

ndbm が使用している実装ライブラリ名です。

dbm.ndbm.open(filename[, flag[, mode]])

dbmデータベースを開いて ndbm オブジェクトを返します。引数 filename はデータベースのファイル名を指定します。 (拡張子 .dir や .pag は付けません)。

オプションの flag は以下の値のいずれかです:

値 | 意味
'r' | 既存のデータベースを読み込み専用で開く (デフォルト)
'w' | 既存のデータベースを読み書き用に開く
'c' | データベースを読み書き用に開く。ただし存在しない場合には新たに作成する
'n' | 常に新たに読み書き用の新規のデータベースを作成する

オプションの mode 引数は、新たにデータベースを作成しなければならない場合に使われる Unix のファイルモードです。標準の値は 8 進数の 0o666 です (この値は現在有効な umask で修飾されます)。

辞書型様のメソッドに加えて、ndbm オブジェクトには以下のメソッドがあります。

ndbm.close()

ndbm データベースをクローズします。

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

ソースコード: Lib/dbm/dumb.py

注釈

dbm.dumb モジュールは、 dbm が頑健なモジュールを他に見つけることができなかった際の最後の手段とされています。 dbm.dumb モジュールは速度を重視して書かれているわけではなく、他のデータベースモジュールのように重い使い方をするためのものではありません。

dbm.dumb モジュールは永続性辞書に類似したインタフェースを提供し、全て Python で書かれています。 dbm.gnu のようなモジュールと異なり、外部ライブラリは必要ありません。他の永続性マップ型のように、キーおよび値は常にバイト列として保存されます。

このモジュールは以下を定義します:

exception dbm.dumb.error

I/O エラーのような dbm.dumb 特有のエラーの際に送出されます。不正なキーを指定したときのような、一般的な対応付けエラーの際には KeyError が送出されます。

dbm.dumb.open(filename[, flag[, mode]])

dumbdbm データベースを開き、 dubmdbm オブジェクトを返します。 filename 引数はデータベースファイル名の雛型 (特定の拡張子をもたないもの) です。dumbdbm データベースが生成される際、 .dat および .dir の拡張子を持ったファイルが生成されます。

オプションの flag 引数は値 'c' と値 'n' のセマンティクスのみをサポートしています。他の値を指定すると、デフォルトの常に更新のために開かれたデータベースになり、存在しない場合には新たに作成されます。

オプションの mode 引数は、新たにデータベースを作成しなければならない場合に使われる Unix のファイルモードです。標準の値は 8 進数の 0o666 です (この値は現在有効な umask で修飾されます)。

警告

It is possible to crash the Python interpreter when loading a database with a sufficiently large/complex entry due to stack depth limitations in Python's AST compiler.

バージョン 3.5 で変更: フラグに値 'n' を与えると、 open() が常に新しいデータベースを作成するようになりました。

Deprecated since version 3.6, will be removed in version 3.8: 'r' と 'w' モードでデータベースの作成。 'r' モードでデータベースを変更。

collections.abc.MutableMapping クラスによって提供されるメソッドに加えて、 dumbdbm オブジェクトは以下のメソッドを提供します:

dumbdbm.sync()

ディスク上の辞書とデータファイルを同期します。このメソッドは Shelve.sync() メソッドから呼び出されます。

dumbdbm.close()

dumbdbm データベースをクローズします。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データの永続化 »


sqlite3 --- SQLite データベースに対する DB-API 2.0 インタフェース

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データの永続化 »

sqlite3 --- SQLite データベースに対する DB-API 2.0 インタフェース

ソースコード: Lib/sqlite3/

SQLite は、軽量なディスク上のデータベースを提供する C ライブラリです。別のサーバプロセスを用意する必要なく、 SQL クエリー言語の非標準的な一種を使用してデータベースにアクセスできます。一部のアプリケーションは内部データ保存に SQLite を使えます。また、SQLite を使ってアプリケーションのプロトタイプを作り、その後そのコードを PostgreSQL や Oracle のような大規模データベースに移植するということも可能です。

sqlite3 モジュールの著者は Gerhard Häring です。 PEP 249 で記述されている DB-API 2.0 に準拠した SQL インターフェイスを提供します。

このモジュールを使うには、最初にデータベースを表す Connection オブジェクトを作ります。ここではデータはファイル example.db に格納されているものとします:

import sqlite3
conn = sqlite3.connect('example.db')

特別な名前である :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)")

# Save (commit) the changes
conn.commit()

# We can also close the connection if we are done with it.
# Just be sure any changes have been committed or they will be lost.
conn.close()

保存されたデータは永続的であり、次回のセッションでもそのまま使用できます:

import sqlite3
conn = sqlite3.connect('example.db')
c = conn.cursor()

たいてい、SQL 操作では Python 変数の値を使う必要があります。この時、クエリーを Python の文字列操作を使って構築することは安全とは言えないので、すべきではありません。そのようなことをするとプログラムが SQL インジェクション攻撃に対し脆弱になります (https://xkcd.com/327/ ではどうなってしまうかをユーモラスに描いています)。

代わりに、DB-API のパラメータ割り当てを使います。 ? を変数の値を使いたいところに埋めておきます。その上で、値のタプルをカーソルの execute() メソッドの第2引数として引き渡します。(他のデータベースモジュールでは変数の場所を示すのに %s や :1 などの異なった表記を用いることがあります。) 例を示します:

# Never do this -- insecure!
symbol = 'RHAT'
c.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)

# Do this instead
t = ('RHAT',)
c.execute('SELECT * FROM stocks WHERE symbol=?', t)
print(c.fetchone())

# Larger example that inserts many records at a time
purchases = [('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
             ('2006-04-05', 'BUY', 'MSFT', 1000, 72.00),
             ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
            ]
c.executemany('INSERT INTO stocks VALUES (?,?,?,?,?)', purchases)

SELECT 文を実行した後データを取得する方法は3つありどれを使っても構いません。一つはカーソルをイテレータ (iterator) として扱う、一つはカーソルの fetchone() メソッドを呼んで一致した内の一行を取得する、もう一つは fetchall() メソッドを呼んで一致した全ての行のリストとして受け取る、という3つです。

以下の例ではイテレータの形を使います:

>>> for row in c.execute('SELECT * FROM stocks ORDER BY price'):
        print(row)

('2006-01-05', 'BUY', 'RHAT', 100, 35.14)
('2006-03-28', 'BUY', 'IBM', 1000, 45.0)
('2006-04-06', 'SELL', 'IBM', 500, 53.0)
('2006-04-05', 'BUY', 'MSFT', 1000, 72.0)

参考

https://github.com/ghaering/pysqlite
pysqlite のウェブページ -- sqlite3 は「pysqlite」という名の下、外部で開発されています。
https://www.sqlite.org
SQLite のウェブページ。ここの文書ではサポートされる SQL 方言の文法と使えるデータ型を説明しています。
https://www.w3schools.com/sql/
SQL 学習に効くチュートリアル、リファレンス、実例集。
PEP 249 - Database API Specification 2.0
Marc-Andre Lemburg により書かれた PEP。

モジュールの関数と定数

sqlite3.version

文字列で表現されたモジュールのバージョン番号です。これは SQLite ライブラリのバージョンではありません。

sqlite3.version_info

整数のタプルで表現されたモジュールのバージョン番号です。これは SQLite ライブラリのバージョンではありません。

sqlite3.sqlite_version

文字列で表現された SQLite ランタイムライブラリのバージョン番号です。

sqlite3.sqlite_version_info

整数のタプルで表現された SQLite ランタイムライブラリのバージョン番号です。

sqlite3.PARSE_DECLTYPES

この定数は connect() 関数の detect_types パラメータとして使われます。

この定数を設定すると sqlite3 モジュールは戻り値のカラムの宣言された型を読み取るようになります。意味を持つのは宣言の最初の単語です。すなわち、"integer primary key" においては "integer" が読み取られます。また、 "number(10)" では、 "number" が読み取られます。そして、そのカラムに対して、変換関数の辞書を探してその型に対して登録された関数を使うようにします。

sqlite3.PARSE_COLNAMES

この定数は connect() 関数の detect_types パラメータとして使われます。

この定数を設定すると SQLite のインタフェースは戻り値のそれぞれのカラムの名前を読み取るようになります。文字列の中の [mytype] といった形の部分を探し、'mytype' がそのカラムの名前であると判断します。そして 'mytype' のエントリを変換関数辞書の中から見つけ、見つかった変換関数を値を返す際に用います。 Cursor.description で見つかるカラム名はその最初の単語だけです。すなわち、もし 'as "x [datetime]"' のようなものを SQL の中で使っていたとすると、読み取るのはカラム名の中の最初の空白までの全てですので、カラム名として使われるのは単純に "x" ということになります。

sqlite3.connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])

Opens a connection to the SQLite database file database. By default returns a Connection object, unless a custom factory is given.

database is a path-like object giving the pathname (absolute or relative to the current working directory) of the database file to be opened. You can use ":memory:" to open a database connection to a database that resides in RAM instead of on disk.

データベースが複数の接続からアクセスされている状況で、その内の一つがデータベースに変更を加えたとき、SQLite データベースはそのトランザクションがコミットされるまでロックされます。timeout パラメータで、例外を送出するまで接続がロックが解除されるのをどれだけ待つかを決めます。デフォルトは 5.0 (5秒) です。

isolation_level パラメータについては、 Connection オブジェクトの、 isolation_level プロパティを参照してください。

SQLite はネイティブで TEXT、INTEGER、REAL、BLOB および NULL のみをサポートしています。その他のタイプを使用したい場合はあなた自身で追加しなければなりません。detect_types パラメータおよび、register_converter() 関数でモジュールレベルで登録できるカスタム 変換関数 を使用することで簡単に追加できます。

パラメータ detect_types のデフォルトは 0 (つまりオフ、型検知無し)です。型検知を有効にするためには、 PARSE_DECLTYPES と PARSE_COLNAMES の適当な組み合わせをこのパラメータにセットします。

By default, check_same_thread is True and only the creating thread may use the connection. If set False, the returned connection may be shared across multiple threads. When using multiple threads with the same connection writing operations should be serialized by the user to avoid data corruption.

デフォルトでは、 sqlite3 モジュールは connect の呼び出しの際にモジュールの Connection クラスを使います。しかし、 Connection クラスを継承したクラスを factory パラメータに渡して connect() にそのクラスを使わせることもできます。

詳しくはこのマニュアルの SQLite と Python の型 節を参考にしてください。

sqlite3 モジュールは SQL 解析のオーバーヘッドを避けるために内部で文キャッシュを使っています。接続に対してキャッシュされる文の数を自分で指定したいならば、 cached_statements パラメータに設定してください。現在の実装ではデフォルトでキャッシュされる SQL 文の数を 100 にしています。

uri が真の場合、 database は URI として解釈されます。これにより、オプションを指定することができます。例えば、データベースを読み出し専用モードで使用できるように開くには、次のようにします:

db = sqlite3.connect('file:path/to/database?mode=ro', uri=True)

More information about this feature, including a list of recognized options, can be found in the SQLite URI documentation.

バージョン 3.4 で変更: uri パラメータが追加されました。

バージョン 3.7 で変更: database can now also be a path-like object, not only a string.

sqlite3.register_converter(typename, callable)

Registers a callable to convert a bytestring from the database into a custom Python type. The callable will be invoked for all database values that are of the type typename. Confer the parameter detect_types of the connect() function for how the type detection works. Note that typename and the name of the type in your query are matched in case-insensitive manner.

sqlite3.register_adapter(type, callable)

自分が使いたい Python の型 type を SQLite がサポートしている型に変換する呼び出し可能オブジェクト (callable) を登録します。その呼び出し可能オブジェクト callable はただ一つの引数に Python の値を受け取り、int, float, str または bytes のいずれかの型の値を返さなければなりません。

sqlite3.complete_statement(sql)

文字列 sql がセミコロンで終端された一つ以上の完全な SQL 文を含んでいる場合、 True を返します。判定は SQL 文として文法的に正しいかではなく、閉じられていない文字列リテラルが無いことおよびセミコロンで終端されていることだけで行われます。

この関数は以下の例にあるような SQLite のシェルを作る際に使われます:

# A minimal SQLite shell for experiments

import sqlite3

con = sqlite3.connect(":memory:")
con.isolation_level = None
cur = con.cursor()

buffer = ""

print("Enter your SQL commands to execute in sqlite3.")
print("Enter a blank line to exit.")

while True:
    line = input()
    if line == "":
        break
    buffer += line
    if sqlite3.complete_statement(buffer):
        try:
            buffer = buffer.strip()
            cur.execute(buffer)

            if buffer.lstrip().upper().startswith("SELECT"):
                print(cur.fetchall())
        except sqlite3.Error as e:
            print("An error occurred:", e.args[0])
        buffer = ""

con.close()
sqlite3.enable_callback_tracebacks(flag)

デフォルトでは、ユーザ定義の関数、集計関数、変換関数、認可コールバックなどはトレースバックを出力しません。デバッグの際にはこの関数を flag に True を指定して呼び出します。そうした後は先に述べたような関数のトレースバックが sys.stderr に出力されます。元に戻すには False を使います。

Connection オブジェクト

class sqlite3.Connection

SQLite データベースコネクション。以下の属性やメソッドを持ちます:

isolation_level

Get or set the current default isolation level. None for autocommit mode or one of "DEFERRED", "IMMEDIATE" or "EXCLUSIVE". See section トランザクション制御 for a more detailed explanation.

in_transaction

トランザクションがアクティブなら (未コミットの変更があるなら) True 、そうでなければ False 。リードオンリー属性です。

バージョン 3.2 で追加.

cursor(factory=Cursor)

cursor メソッドはオション引数 factory を 1 つだけ受け付けます。 渡された場合は、 Cursor またはそのサブクラスのインスタンスを返す呼び出し可能オブジェクトでなければなりません。

commit()

このメソッドは現在のトランザクションをコミットします。このメソッドを呼ばないと、前回 commit() を呼び出してから行ったすべての変更は、他のデータベースコネクションから見ることができません。もし、データベースに書き込んだはずのデータが見えなくて悩んでいる場合は、このメソッドの呼び出しを忘れていないかチェックしてください。

rollback()

このメソッドは最後に行った commit() 後の全ての変更をロールバックします。

close()

このメソッドはデータベースコネクションを閉じます。このメソッドが自動的に commit() を呼び出さないことに注意してください。 commit() をせずにコネクションを閉じると、変更が消えてしまいます！

execute(sql[, parameters])

This is a nonstandard shortcut that creates a cursor object by calling the cursor() method, calls the cursor's execute() method with the parameters given, and returns the cursor.

executemany(sql[, parameters])

This is a nonstandard shortcut that creates a cursor object by calling the cursor() method, calls the cursor's executemany() method with the parameters given, and returns the cursor.

executescript(sql_script)

This is a nonstandard shortcut that creates a cursor object by calling the cursor() method, calls the cursor's executescript() method with the given sql_script, and returns the cursor.

create_function(name, num_params, func)

Creates a user-defined function that you can later use from within SQL statements under the function name name. num_params is the number of parameters the function accepts (if num_params is -1, the function may take any number of arguments), and func is a Python callable that is called as the SQL function.

The function can return any of the types supported by SQLite: bytes, str, int, float and None.

例:

import sqlite3
import hashlib

def md5sum(t):
    return hashlib.md5(t).hexdigest()

con = sqlite3.connect(":memory:")
con.create_function("md5", 1, md5sum)
cur = con.cursor()
cur.execute("select md5(?)", (b"foo",))
print(cur.fetchone()[0])
create_aggregate(name, num_params, aggregate_class)

ユーザ定義の集計関数を作成します。

The aggregate class must implement a step method, which accepts the number of parameters num_params (if num_params is -1, the function may take any number of arguments), and a finalize method which will return the final result of the aggregate.

The finalize method can return any of the types supported by SQLite: bytes, str, int, float and None.

例:

import sqlite3

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.cursor()
cur.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])
create_collation(name, callable)

name と callable で指定される照合順序を作成します。呼び出し可能オブジェクトには二つの文字列が渡されます。一つめのものが二つめのものより低く順序付けられるならば -1 を返し、等しければ 0 を返し、一つめのものが二つめのものより高く順序付けられるならば 1 を返すようにしなければなりません。この関数はソート(SQL での ORDER BY)をコントロールするもので、比較を行なうことは他の SQL 操作には影響を与えないことに注意しましょう。

また、呼び出し可能オブジェクトに渡される引数は Python のバイト文字列として渡されますが、それは通常 UTF-8 で符号化されたものになります。

以下の例は「間違った方法で」ソートする自作の照合順序です:

import sqlite3

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.cursor()
cur.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 を指定して create_collation を呼び出します:

con.create_collation("reverse", None)
interrupt()

このメソッドを別スレッドから呼び出して接続上で現在実行中であろうクエリを中断させられます。クエリが中断されると呼び出し元は例外を受け取ります。

set_authorizer(authorizer_callback)

このルーチンはコールバックを登録します。コールバックはデータベースのテーブルのカラムにアクセスしようとするたびに呼び出されます。コールバックはアクセスが許可されるならば SQLITE_OK を、SQL 文全体がエラーとともに中断されるべきならば SQLITE_DENY を、カラムが NULL 値として扱われるべきなら SQLITE_IGNORE を返さなければなりません。これらの定数は sqlite3 モジュールに用意されています。

コールバックの第一引数はどの種類の操作が許可されるかを決めます。第二第三引数には第一引数に依存して本当に使われる引数か None かが渡されます。第四引数はもし適用されるならばデータベースの名前("main", "temp", etc.)です。第五引数はアクセスを試みる要因となった最も内側のトリガまたはビューの名前、またはアクセスの試みが入力された SQL コードに直接起因するものならば None です。

第一引数に与えることができる値や、その第一引数によって決まる第二第三引数の意味については、SQLite の文書を参考にしてください。必要な定数は全て sqlite3 モジュールに用意されています。

set_progress_handler(handler, n)

このメソッドはコールバックを登録します。コールバックは SQLite 仮想マシン上の n 個の命令を実行するごとに呼び出されます。これは、GUI 更新などのために、長時間かかる処理中に SQLite からの呼び出しが欲しい場合に便利です。

以前登録した progress handler をクリアしたい場合は、このメソッドを、 handler 引数に None を渡して呼び出してください。

Returning a non-zero value from the handler function will terminate the currently executing query and cause it to raise an OperationalError exception.

set_trace_callback(trace_callback)

各 SQL 文が SQLite バックエンドによって実際に実行されるたびに呼び出される trace_callback を登録します。

コールバックに渡される唯一の引数は、実行されている SQL 文 (の文字列)です。コールバックの戻り値は無視されます。バックエンドは Cursor.execute() メソッドに渡された SQL 文だけを実行するわけではないことに注意してください。他のソースには、 Python モジュールのトランザクション管理や、現在のデータベースに定義されたトリガーの実行が含まれます。

trace_callback として None を渡すと、トレースコールバックを無効にできます。

バージョン 3.3 で追加.

enable_load_extension(enabled)

このメソッドは SQLite エンジンが共有ライブラリから SQLite 拡張を読み込むのを許可したり、禁止したりします。SQLite 拡張は新しい関数や集計関数や仮想テーブルの実装を定義できます。1つの有名な拡張は SQLite によって頒布されている全テキスト検索拡張です。

SQLite 拡張はデフォルトで無効にされています。[1] を見てください。

バージョン 3.2 で追加.

import sqlite3

con = sqlite3.connect(":memory:")

# enable extension loading
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)

このメソッドは共有ライブラリから SQLite 拡張を読み込みます。このメソッドを使う前に enable_load_extension() で拡張の読み込みを許可しておかなくてはなりません。

SQLite 拡張はデフォルトで無効にされています。[1] を見てください。

バージョン 3.2 で追加.

row_factory

この属性を変更して、カーソルと元の行をタプル形式で受け取り、本当の結果の行を返す呼び出し可能オブジェクトにすることができます。これによって、より進んだ結果の返し方を実装することができます。例えば、各列に列名でもアクセスできるようなオブジェクトを返すことができます。

例:

import sqlite3

def dict_factory(cursor, row):
    d = {}
    for idx, col in enumerate(cursor.description):
        d[col[0]] = row[idx]
    return d

con = sqlite3.connect(":memory:")
con.row_factory = dict_factory
cur = con.cursor()
cur.execute("select 1 as a")
print(cur.fetchone()["a"])

タプルを返すのでは物足りず、名前に基づいて列へアクセスしたい場合は、 row_factory に高度に最適化された sqlite3.Row 型を設定することを検討してください。 Row クラスではインデックスでも大文字小文字を無視した名前でも列にアクセスでき、しかもほとんどメモリーを浪費しません。おそらく独自実装の辞書を使うアプローチよりも良いもので、もしかすると db の行に基づいた解法よりも優れているかもしれません。

text_factory

この属性を使って TEXT データ型をどのオブジェクトで返すかを制御できます。デフォルトではこの属性は str に設定されており、 sqlite3 モジュールは TEXT を Unicode オブジェクトで返します。もしバイト列で返したいならば、 bytes に設定してください。

バイト列を受け取って望みの型のオブジェクトを返すような呼び出し可能オブジェクトを何でも設定して構いません。

以下の説明用のコード例を参照してください:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()

AUSTRIA = "\xd6sterreich"

# by default, rows are returned as Unicode
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert row[0] == AUSTRIA

# but we can make sqlite3 always return bytestrings ...
con.text_factory = bytes
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert type(row[0]) is bytes
# the bytestrings will be encoded in UTF-8, unless you stored garbage in the
# database ...
assert row[0] == AUSTRIA.encode("utf-8")

# we can also implement a custom text_factory ...
# here we implement one that appends "foo" to all strings
con.text_factory = lambda x: x.decode("utf-8") + "foo"
cur.execute("select ?", ("bar",))
row = cur.fetchone()
assert row[0] == "barfoo"
total_changes

データベース接続が開始されて以来の行の変更・挿入・削除がなされた行の総数を返します。

iterdump()

データベースをSQL testフォーマットでダンプするためのイテレータを返します。 メモリ内のデータベースの内容を、後で復元するために保存する場合に便利です。この関数には、 sqlite3 シェルの中の .dump コマンドと同じ機能があります。

以下はプログラム例です:

# Convert file existing_db.db to SQL dump file dump.sql
import sqlite3

con = sqlite3.connect('existing_db.db')
with open('dump.sql', 'w') as f:
    for line in con.iterdump():
        f.write('%s\n' % line)
backup(target, *, pages=0, progress=None, name="main", sleep=0.250)

This method makes a backup of a SQLite database even while it's being accessed by other clients, or concurrently by the same connection. The copy will be written into the mandatory argument target, that must be another Connection instance.

By default, or when pages is either 0 or a negative integer, the entire database is copied in a single step; otherwise the method performs a loop copying up to pages pages at a time.

If progress is specified, it must either be None or a callable object that will be executed at each iteration with three integer arguments, respectively the status of the last iteration, the remaining number of pages still to be copied and the total number of pages.

The name argument specifies the database name that will be copied: it must be a string containing either "main", the default, to indicate the main database, "temp" to indicate the temporary database or the name specified after the AS keyword in an ATTACH DATABASE statement for an attached database.

The sleep argument specifies the number of seconds to sleep by between successive attempts to backup remaining pages, can be specified either as an integer or a floating point value.

Example 1, copy an existing database into another:

import sqlite3

def progress(status, remaining, total):
    print(f'Copied {total-remaining} of {total} pages...')

con = sqlite3.connect('existing_db.db')
with sqlite3.connect('backup.db') as bck:
    con.backup(bck, pages=1, progress=progress)

Example 2, copy an existing database into a transient copy:

import sqlite3

source = sqlite3.connect('existing_db.db')
dest = sqlite3.connect(':memory:')
source.backup(dest)

Availability: SQLite 3.6.11 or higher

バージョン 3.7 で追加.

カーソルオブジェクト

class sqlite3.Cursor

Cursor インスタンスは以下の属性やメソッドを持ちます。

execute(sql[, parameters])

SQL 文を実行します。SQL 文はパラメータ化できます(すなわち SQL リテラルの代わりの場所確保文字 (placeholder) を入れておけます)。 sqlite3 モジュールは2種類の場所確保記法をサポートします。一つは疑問符(qmark スタイル)、もう一つは名前(named スタイル)です。

両方のスタイルの例です:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table people (name_last, age)")

who = "Yeltsin"
age = 72

# This is the qmark style:
cur.execute("insert into people values (?, ?)", (who, age))

# And this is the named style:
cur.execute("select * from people where name_last=:who and age=:age", {"who": who, "age": age})

print(cur.fetchone())

execute() will only execute a single SQL statement. If you try to execute more than one statement with it, it will raise a Warning. Use executescript() if you want to execute multiple SQL statements with one call.

executemany(sql, seq_of_parameters)

Executes an SQL command against all parameter sequences or mappings found in the sequence seq_of_parameters. The sqlite3 module also allows using an iterator yielding parameters instead of a sequence.

import sqlite3

class IterChars:
    def __init__(self):
        self.count = ord('a')

    def __iter__(self):
        return self

    def __next__(self):
        if self.count > ord('z'):
            raise StopIteration
        self.count += 1
        return (chr(self.count - 1),) # this is a 1-tuple

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table characters(c)")

theIter = IterChars()
cur.executemany("insert into characters(c) values (?)", theIter)

cur.execute("select c from characters")
print(cur.fetchall())

もう少し短いジェネレータ (generator) を使った例です:

import sqlite3
import string

def char_generator():
    for c in string.ascii_lowercase:
        yield (c,)

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table characters(c)")

cur.executemany("insert into characters(c) values (?)", char_generator())

cur.execute("select c from characters")
print(cur.fetchall())
executescript(sql_script)

これは非標準の便宜メソッドで、一度に複数の SQL 文を実行することができます。メソッドは最初に COMMIT 文を発行し、次いで引数として渡された SQLスクリプトを実行します。

sql_script can be an instance of str.

例:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.executescript("""
    create table person(
        firstname,
        lastname,
        age
    );

    create table book(
        title,
        author,
        published
    );

    insert into book(title, author, published)
    values (
        'Dirk Gently''s Holistic Detective Agency',
        'Douglas Adams',
        1987
    );
    """)
fetchone()

クエリ結果から次の row をフェッチして、1つのシーケンスを返します。これ以上データがない場合は None を返します。

fetchmany(size=cursor.arraysize)

クエリ結果から次の幾つかの row をフェッチして、リストを返します。これ以上データがない場合は空のリストを返します。

一回の呼び出しで返される row の数は、size 引数で指定できます。この引数が与えられない場合、cursor の arraysize 属性が利用されます。このメソッドは可能な限り指定された size の数の row を fetch しようとするべきです。もし、指定された数の row が利用可能でない場合、それより少ない数の row が返されます。

size 引数とパフォーマンスの関係についての注意です。パフォーマンスを最適化するためには、大抵、 arraysize 属性を利用するのがベストです。 size 引数を利用したのであれば、次の fetchmany() の呼び出しでも同じ数を利用するのがベストです。

fetchall()

全ての(残りの)クエリ結果の row をフェッチして、リストを返します。cursor の arraysize 属性がこの操作のパフォーマンスに影響することに気をつけてください。これ以上の row がない場合は、空のリストが返されます。

close()

Close the cursor now (rather than whenever __del__ is called).

The cursor will be unusable from this point forward; a ProgrammingError exception will be raised if any operation is attempted with the cursor.

rowcount

一応 sqlite3 モジュールの Cursor クラスはこの属性を実装していますが、データベースエンジン自身の「影響を受けた行」/「選択された行」の決定方法は少し風変わりです。

executemany() では、変更数が rowcount に合計されます。

Python DB API 仕様で要求されるように、rowcount 属性は「カーソルに対して executeXX() が行なわれていないか、最後の操作の rowcount がインターフェースによって決定できなかった場合は -1 」です。これには SELECT 文も含まれます。すべての列を取得するまでクエリによって生じた列の数を決定できないからです。

SQLite のバージョン 3.6.5 以前は、条件なしで DELETE FROM table を実行すると rowcount が 0 にセットされます。

lastrowid

This read-only attribute provides the rowid of the last modified row. It is only set if you issued an INSERT or a REPLACE statement using the execute() method. For operations other than INSERT or REPLACE or when executemany() is called, lastrowid is set to None.

If the INSERT or REPLACE statement failed to insert the previous successful rowid is returned.

バージョン 3.6 で変更: Added support for the REPLACE statement.

arraysize

Read/write attribute that controls the number of rows returned by fetchmany(). The default value is 1 which means a single row would be fetched per call.

description

この読み出し専用の属性は、最後のクエリの結果のカラム名を提供します。 Python DB API との互換性を維持するために、各カラムに対して 7つのタプルを返しますが、タプルの後ろ6つの要素は全て None です。

この属性は SELECT 文にマッチする row が1つもなかった場合でもセットされます。

connection

この読み出し専用の属性は、 Cursor オブジェクトが使用する SQLite データベースの Connection を提供します。con.cursor() を呼び出すことにより作成される Cursor オブジェクトは、 con を参照する connection 属性を持ちます:

>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True

Row オブジェクト

class sqlite3.Row

Row インスタンスは、 Connection オブジェクトの row_factory として高度に最適化されています。タプルによく似た機能を持つ row を作成します。

カラム名とインデックスによる要素へのアクセス, イテレーション, repr(), 同値テスト, len() をサポートしています。

もし、2つの Row オブジェクトが完全に同じカラムと値を持っていた場合、それらは同値になります。

keys()

このメソッドはカラム名のリストを返します。クエリ直後から、これは Cursor.description の各タプルの最初のメンバになります。

バージョン 3.5 で変更: スライスがサポートされました。

Rowの例のために、まずサンプルのテーブルを初期化します:

conn = sqlite3.connect(":memory:")
c = conn.cursor()
c.execute('''create table stocks
(date text, trans text, symbol text,
 qty real, price real)''')
c.execute("""insert into stocks
          values ('2006-01-05','BUY','RHAT',100,35.14)""")
conn.commit()
c.close()

そして、 Row を使ってみます:

>>> conn.row_factory = sqlite3.Row
>>> c = conn.cursor()
>>> c.execute('select * from stocks')
<sqlite3.Cursor object at 0x7f4e7dd8fa80>
>>> r = c.fetchone()
>>> type(r)
<class 'sqlite3.Row'>
>>> tuple(r)
('2006-01-05', 'BUY', 'RHAT', 100.0, 35.14)
>>> len(r)
5
>>> r[2]
'RHAT'
>>> r.keys()
['date', 'trans', 'symbol', 'qty', 'price']
>>> r['qty']
100.0
>>> for member in r:
...     print(member)
...
2006-01-05
BUY
RHAT
100.0
35.14

例外

exception sqlite3.Warning

A subclass of Exception.

exception sqlite3.Error

このモジュールにおける他の例外クラスの基底クラスです。 Exception のサブクラスです。

exception sqlite3.DatabaseError

Exception raised for errors that are related to the database.

exception sqlite3.IntegrityError

Exception raised when the relational integrity of the database is affected, e.g. a foreign key check fails. It is a subclass of DatabaseError.

exception sqlite3.ProgrammingError

Exception raised for programming errors, e.g. table not found or already exists, syntax error in the SQL statement, wrong number of parameters specified, etc. It is a subclass of DatabaseError.

exception sqlite3.OperationalError

Exception raised for errors that are related to the database's operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, etc. It is a subclass of DatabaseError.

exception sqlite3.NotSupportedError

Exception raised in case a method or database API was used which is not supported by the database, e.g. calling the rollback() method on a connection that does not support transaction or has transactions turned off. It is a subclass of 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 モジュールの型システムは二つの方法で拡張できます。一つはオブジェクト適合(adaptation)を通じて追加された Python の型を SQLite に格納することです。もう一つは変換関数(converter)を通じて sqlite3 モジュールに SQLite の型を違った Python の型に変換させることです。

追加された Python の型を SQLite データベースに格納するために適合関数を使う

既に述べたように、SQLite が最初からサポートする型は限られたものだけです。それ以外の Python の型を SQLite で使うには、その型を sqlite3 モジュールがサポートしている型の一つに 適合 させなくてはなりません。サポートしている型というのは、NoneType, int, float, str, bytes です。

sqlite3 モジュールで望みの Python の型をサポートされている型の一つに適合させる方法は二つあります。

オブジェクト自身で適合するようにする

自分でクラスを書いているならばこの方法が良いでしょう。次のようなクラスがあるとします:

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

さてこの点を SQLite の一つのカラムに収めたいと考えたとしましょう。最初にしなければならないのはサポートされている型の中から点を表現するのに使えるものを選ぶことです。ここでは単純に文字列を使うことにして、座標を区切るのにはセミコロンを使いましょう。次に必要なのはクラスに変換された値を返す __conform__(self, protocol) メソッドを追加することです。引数 protocol は PrepareProtocol になります。

import sqlite3

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __conform__(self, protocol):
        if protocol is sqlite3.PrepareProtocol:
            return "%f;%f" % (self.x, self.y)

con = sqlite3.connect(":memory:")
cur = con.cursor()

p = Point(4.0, -3.2)
cur.execute("select ?", (p,))
print(cur.fetchone()[0])

適合関数を登録する

もう一つの可能性は型を文字列表現に変換する関数を作り register_adapter() でその関数を登録することです。

import sqlite3

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

def adapt_point(point):
    return "%f;%f" % (point.x, point.y)

sqlite3.register_adapter(Point, adapt_point)

con = sqlite3.connect(":memory:")
cur = con.cursor()

p = Point(4.0, -3.2)
cur.execute("select ?", (p,))
print(cur.fetchone()[0])

sqlite3 モジュールには二つの Python 標準型 datetime.date と datetime.datetime に対するデフォルト適合関数があります。いま datetime.datetime オブジェクトを ISO 表現でなく Unix タイムスタンプとして格納したいとしましょう。

import sqlite3
import datetime
import time

def adapt_datetime(ts):
    return time.mktime(ts.timetuple())

sqlite3.register_adapter(datetime.datetime, adapt_datetime)

con = sqlite3.connect(":memory:")
cur = con.cursor()

now = datetime.datetime.now()
cur.execute("select ?", (now,))
print(cur.fetchone()[0])

SQLite の値を好きな Python 型に変換する

適合関数を書くことで好きな Python 型を SQLite に送り込めるようになりました。しかし、本当に使い物になるようにするには Python から SQLite さらに Python へという往還(roundtrip)の変換ができる必要があります。

そこで変換関数(converter)です。

Point クラスの例に戻りましょう。x, y 座標をセミコロンで区切った文字列として SQLite に格納したのでした。

まず、文字列を引数として取り Point オブジェクトをそれから構築する変換関数を定義します。

注釈

変換関数は SQLite に送り込んだデータ型に関係なく 常に bytes オブジェクトを渡されます。

def convert_point(s):
    x, y = map(float, s.split(b";"))
    return Point(x, y)

次に sqlite3 モジュールにデータベースから取得したものが本当に点であることを教えなければなりません。二つの方法があります:

  • 宣言された型を通じて暗黙的に
  • カラム名を通じて明示的に

どちらの方法も モジュールの関数と定数 節の中で説明されています。それぞれ PARSE_DECLTYPES 定数と PARSE_COLNAMES 定数の項目です。

以下の例で両方のアプローチを紹介します。

import sqlite3

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return "(%f;%f)" % (self.x, self.y)

def adapt_point(point):
    return ("%f;%f" % (point.x, point.y)).encode('ascii')

def convert_point(s):
    x, y = list(map(float, s.split(b";")))
    return Point(x, y)

# Register the adapter
sqlite3.register_adapter(Point, adapt_point)

# Register the converter
sqlite3.register_converter("point", convert_point)

p = Point(4.0, -3.2)

#########################
# 1) Using declared types
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.cursor()
cur.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()

#######################
# 1) Using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.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()

デフォルトの適合関数と変換関数

datetime モジュールの date 型および datetime 型のためのデフォルト適合関数があります。これらの型は ISO 日付 / ISO タイムスタンプとして SQLite に送られます。

デフォルトの変換関数は datetime.date 用が "date" という名前で、 datetime.datetime 用が "timestamp" という名前で登録されています。

これにより、多くの場合特別な細工無しに Python の日付 / タイムスタンプを使えます。適合関数の書式は実験的な SQLite の date/time 関数とも互換性があります。

以下の例でこのことを確かめます。

import sqlite3
import datetime

con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.execute("create table test(d date, ts timestamp)")

today = datetime.date.today()
now = datetime.datetime.now()

cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
cur.execute("select d, ts from test")
row = cur.fetchone()
print(today, "=>", row[0], type(row[0]))
print(now, "=>", row[1], type(row[1]))

cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
row = cur.fetchone()
print("current_date", row[0], type(row[0]))
print("current_timestamp", row[1], type(row[1]))

SQLite に格納されているタイムスタンプが6桁より長い小数部を持っている場合、タイムスタンプの変換関数によってマイクロ秒精度に丸められます。

トランザクション制御

The underlying sqlite3 library operates in autocommit mode by default, but the Python sqlite3 module by default does not.

autocommit mode means that statements that modify the database take effect immediately. A BEGIN or SAVEPOINT statement disables autocommit mode, and a COMMIT, a ROLLBACK, or a RELEASE that ends the outermost transaction, turns autocommit mode back on.

The Python sqlite3 module by default issues a BEGIN statement implicitly before a Data Modification Language (DML) statement (i.e. INSERT/UPDATE/DELETE/REPLACE).

You can control which kind of BEGIN statements sqlite3 implicitly executes via the isolation_level parameter to the connect() call, or via the isolation_level property of connections. If you specify no isolation_level, a plain BEGIN is used, which is equivalent to specifying DEFERRED. Other possible values are IMMEDIATE and EXCLUSIVE.

You can disable the sqlite3 module's implicit transaction management by setting isolation_level to None. This will leave the underlying sqlite3 library operating in autocommit mode. You can then completely control the transaction state by explicitly issuing BEGIN, ROLLBACK, SAVEPOINT, and RELEASE statements in your code.

バージョン 3.6 で変更: sqlite3 used to implicitly commit an open transaction before DDL statements. This is no longer the case.

sqlite3 の効率的な使い方

ショートカットメソッドを使う

Connection オブジェクトの非標準的なメソッド execute(), executemany(), executescript() を使うことで、 (しばしば余計な) Cursor オブジェクトをわざわざ作り出さずに済むので、コードをより簡潔に書くことができます。 Cursor オブジェクトは暗黙裡に生成されショートカットメソッドの戻り値として受け取ることができます。この方法を使えば、 SELECT 文を実行してその結果について反復することが、 Connection オブジェクトに対する呼び出し一つで行なえます。

import sqlite3

persons = [
    ("Hugo", "Boss"),
    ("Calvin", "Klein")
    ]

con = sqlite3.connect(":memory:")

# Create the table
con.execute("create table person(firstname, lastname)")

# Fill the table
con.executemany("insert into person(firstname, lastname) values (?, ?)", persons)

# Print the table contents
for row in con.execute("select firstname, lastname from person"):
    print(row)

print("I just deleted", con.execute("delete from person").rowcount, "rows")

位置ではなく名前でカラムにアクセスする

sqlite3 モジュールの有用な機能の一つに、行生成関数として使われるための sqlite3.Row クラスがあります。

このクラスでラップされた行は、位置インデクス(タプルのような)でも大文字小文字を区別しない名前でもアクセスできます:

import sqlite3

con = sqlite3.connect(":memory:")
con.row_factory = sqlite3.Row

cur = con.cursor()
cur.execute("select 'John' as name, 42 as age")
for row in cur:
    assert row[0] == row["name"]
    assert row["name"] == row["nAmE"]
    assert row[1] == row["age"]
    assert row[1] == row["AgE"]

コネクションをコンテキストマネージャーとして利用する

Connection オブジェクトはコンテキストマネージャーとして利用して、トランザクションを自動的にコミットしたりロールバックすることができます。例外が発生したときにトランザクションはロールバックされ、それ以外の場合、トランザクションはコミットされます:

import sqlite3

con = sqlite3.connect(":memory:")
con.execute("create table person (id integer primary key, firstname varchar unique)")

# Successful, con.commit() is called automatically afterwards
with con:
    con.execute("insert into person(firstname) values (?)", ("Joe",))

# 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 person(firstname) values (?)", ("Joe",))
except sqlite3.IntegrityError:
    print("couldn't add Joe twice")

既知の問題

マルチスレッド

古いバージョンの SQLite はスレッド間でのコネクションの共有に問題がありました。その理由は、Python のモジュールではスレッド間のコネクションとカーソルの共有ができないためです。依然としてそのようなことをしようとすると、実行時に例外を受け取るでしょう。

唯一の例外は interrupt() メソッドで、これだけが異なるスレッドから呼び出せます。

脚注

[1] (1, 2) いくつかのプラットフォームでこの機能なしでコンパイルされる SQLite ライブラリがあるので (特にMac OS X)、sqlite3 モジュールはデフォルトで SQLite 拡張サポートなしで構築されます。SQLite 拡張サポートを有効にするには、configure に --enable-loadable-sqlite-extensions を渡す必要があります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データの永続化 »


データ圧縮とアーカイブ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

データ圧縮とアーカイブ

この章で説明されるモジュールは zlib, gzip, bzip2, lzma アルゴリズムによるデータの圧縮と、 ZIP, tar フォーマットのアーカイブ作成をサポートします。 shutil モジュールで提供される アーカイブ化操作 も参照してください。

  • zlib --- gzip 互換の圧縮
  • gzip --- gzip ファイルのサポート
    • 使い方の例
  • bz2 --- bzip2 圧縮のサポート
    • ファイルの圧縮/解凍
    • 逐次圧縮および展開
    • 一括圧縮/解凍
  • lzma --- LZMA アルゴリズムを使用した圧縮
    • 圧縮ファイルへの読み書き
    • メモリ上での圧縮と展開
    • その他
    • カスタムフィルタチェインの指定
    • 使用例
  • zipfile --- ZIP アーカイブの処理
    • ZipFile オブジェクト
    • PyZipFile オブジェクト
    • ZipInfo オブジェクト
    • コマンドラインインターフェイス
      • コマンドラインオプション
  • tarfile --- tar アーカイブファイルの読み書き
    • TarFile オブジェクト
    • TarInfo オブジェクト
    • コマンドラインインターフェイス
      • コマンドラインオプション
    • 使用例
    • サポートしている tar フォーマット
    • Unicode に関する問題

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


zlib --- gzip 互換の圧縮

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ圧縮とアーカイブ »

zlib --- gzip 互換の圧縮

このモジュールは、データ圧縮を必要とするアプリケーションが zlib ライブラリを使って圧縮および展開を行えるようにします。zlib ライブラリ自身の Webページは http://www.zlib.net です。Python モジュールと zlib ライブラリの 1.1.3 より前のバージョンには互換性のない部分があることが知られています。1.1.3 にはセキュリティホールが存在するため、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 で変更: 常に符号のない値を返します。すべてのバージョンとプラットフォームの Python に渡って同一の数値を生成するには、 adler32(data) & 0xffffffff を使用します。

zlib.compress(data, level=-1)

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). Raises the error exception if any error occurs.

バージョン 3.6 で変更: level can now be used as a keyword parameter.

zlib.compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

一度にメモリ上に置くことができないようなデータストリームを圧縮するための圧縮オブジェクトを返します。

level is the compression level -- an integer from 0 to 9 or -1. A value of 1 (Z_BEST_SPEED) is fastest and produces the least compression, while a value of 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).

method is the compression algorithm. Currently, the only supported value is DEFLATED.

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.

memLevel 引数は内部圧縮状態用に使用されるメモリ量を制御します。有効な値は 1 から 9 です。大きい値ほど多くのメモリを消費しますが、より速く、より小さな出力を作成します。

strategy is used to tune the compression algorithm. Possible values are Z_DEFAULT_STRATEGY, Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE (zlib 1.2.0.1) and Z_FIXED (zlib 1.2.2.2).

zdict は定義済み圧縮辞書です。これは圧縮されるデータ内で繰り返し現れると予想されるサブシーケンスを含む (bytes オブジェクトのような) バイト列のシーケンスです。最も一般的と思われるサブシーケンスは辞書の末尾に来なければなりません。

バージョン 3.3 で変更: zdict パラメータとキーワード引数のサポートが追加されました。

zlib.crc32(data[, value])

data の CRC (Cyclic Redundancy Check, 巡回冗長検査) チェックサムを計算します。結果は、符号のない 32 ビットの整数です。 value が与えられている場合、チェックサム計算の初期値として使われます。与えられていない場合、デフォルト値の 1 が使われます。 value を与えることで、複数の入力を結合したデータ全体にわたり、通しのチェックサムを計算できます。このアルゴリズムは暗号論的には強力ではなく、認証やデジタル署名などに用いるべきではありません。また、チェックサムアルゴリズムとして設計されているため、汎用のハッシュアルゴリズムには向きません。

バージョン 3.0 で変更: 常に符号のない値を返します。すべてのバージョンとプラットフォームの Python に渡って同一の数値を生成するには、crc32(data) & 0xffffffff を使用します。

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 is the initial size of the buffer used to hold decompressed data. If more space is required, the buffer size will be increased as needed, so you don't have to get this value exactly right; tuning it will only save a few calls to 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])

All pending input is processed, and a bytes object containing the remaining compressed output is returned. mode can be selected from the constants Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_BLOCK (zlib 1.2.3.4), or Z_FINISH, defaulting to Z_FINISH. Except Z_FINISH, all constants allow compressing further bytestrings of data, while Z_FINISH finishes the compressed stream and prevents compressing any more data. After calling flush() with mode set to Z_FINISH, the compress() method cannot be called again; the only realistic action is to delete the object.

Compress.copy()

圧縮オブジェクトのコピーを返します。これを使うと先頭部分が共通している複数のデータを効率的に圧縮することができます。

展開オブジェクトは以下のメソッドと属性をサポートしています:

Decompress.unused_data

圧縮データの末尾より後のバイト列が入ったバイト列オブジェクトです。すなわち、この値は圧縮データの入っているバイト列の最後の文字が利用可能になるまでは b"" のままとなります。入力バイト文字列すべてが圧縮データを含んでいた場合、この属性は b"" 、すなわち空バイト列になります。

Decompress.unconsumed_tail

展開されたデータを収めるバッファの長さ制限を超えたために、直近の decompress() 呼び出しで処理しきれなかったデータを含むバイト列オブジェクトです。このデータはまだ zlib 側からは見えていないので、正しい展開出力を得るには以降の decompress() メソッド呼び出しに (場合によっては後続のデータが追加された) データを差し戻さなければなりません。

Decompress.eof

圧縮データストリームの終了に達したかどうかを示すブール値です。

これは、正常な形式の圧縮ストリームと、不完全あるいは切り詰められたストリームとを区別することを可能にします。

バージョン 3.3 で追加.

Decompress.decompress(data, max_length=0)

data を展開し、少なくとも string の一部分に対応する展開されたデータを含むバイト列オブジェクトを返します。このデータは以前に decompress() メソッドを呼んだ時に返された出力と結合することができます。入力データの一部分が以後の処理のために内部バッファに保存されることもあります。

If the optional parameter max_length is non-zero then the return value will be no longer than max_length. This may mean that not all of the compressed input can be processed; and unconsumed data will be stored in the attribute unconsumed_tail. This bytestring must be passed to a subsequent call to decompress() if decompression is to continue. If max_length is zero then the whole input is decompressed, and unconsumed_tail is empty.

バージョン 3.6 で変更: max_length can be used as a keyword argument.

Decompress.flush([length])

未処理の入力データをすべて処理し、最終的に圧縮されなかった残りの出力バイト列オブジェクトを返します。flush() を呼んだ後、decompress() を再度呼ぶべきではありません。このときできる唯一の現実的な操作はオブジェクトの削除だけです。

オプション引数 length には出力バッファの初期サイズを指定します。

Decompress.copy()

展開オブジェクトのコピーを返します。これを使うとデータストリームの途中にある展開オブジェクトの状態を保存でき、未来のある時点で行なわれるストリームのランダムなシークをスピードアップするのに利用できます。

使用している zlib ライブラリのバージョン情報を以下の定数で確認できます:

zlib.ZLIB_VERSION

モジュールのビルド時に使用された zlib ライブラリのバージョン文字列です。これは ZLIB_RUNTIME_VERSION で確認できる、実行時に使用している実際の zlib ライブラリのバージョンとは異なる場合があります。

zlib.ZLIB_RUNTIME_VERSION

インタプリタが読み込んだ実際の zlib ライブラリのバージョン文字列です。

バージョン 3.3 で追加.

参考

gzip モジュール
gzip 形式ファイルへの読み書きを行うモジュール。
http://www.zlib.net
zlib ライブラリホームページ。
http://www.zlib.net/manual.html
zlib ライブラリの多くの関数の意味と使い方を解説したマニュアル。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ圧縮とアーカイブ »


gzip --- gzip ファイルのサポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ圧縮とアーカイブ »

gzip --- gzip ファイルのサポート

ソースコード: 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 を受け入れるようになりました。

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

GzipFile クラスのコンストラクタです。GzipFile オブジェクトは truncate() メソッドを除くほとんどの ファイルオブジェクト のメソッドをシミュレートします。少なくとも fileobj および filename は有効な値でなければなりません。

クラスの新しいインスタンスは、 fileobj に基づいて作成されます。 fileobj は通常のファイル、 io.BytesIO オブジェクト、 そしてその他ファイルをシミュレートできるオブジェクトでかまいません。 値はデフォルトでは None で、その場合ファイルオブジェクトを生成するために filename を開きます。

fileobj が None でない場合、filename 引数は gzip ファイルヘッダにインクルードされることのみに使用されます。gzip ファイルヘッダは圧縮されていないファイルの元の名前をインクルードするかもしれません。認識可能な場合、規定値は fileobj のファイル名です。そうでない場合、規定値は空の文字列で、元のファイル名はヘッダにはインクルードされません。

引数 mode は、ファイルを読み込むのか書き出すのかによって、'r'、'rb'、'a'、'ab'、'w'、'wb'、'x'、および 'xb' のいずれかになります。fileobj のファイルモードが認識可能な場合、mode はデフォルトで fileobj のモードと同じになります。そうでない場合、デフォルトのモードは 'rb' です。

ファイルは常にバイナリモードで開かれることに注意してください。圧縮ファイルをテキストモードで開く場合、open() (または GzipFile を io.TextIOWrapper でラップしたオブジェクト) を使ってください。

引数 compresslevel は 0 から 9 の整数を取り、圧縮レベルを制御します; 1 は最も高速で最小限の圧縮を行い、9 は最も低速ですが最大限の圧縮を行います。0 は圧縮しません。デフォルトは 9 です。

mtime 引数は、圧縮時にストリームの最終更新日時フィールドに書き込まれるオプションの数値のタイムスタンプです。これは、圧縮モードでのみ提供することができます。省略された場合か None である場合、現在時刻が使用されます。詳細については、 mtime 属性を参照してください。

圧縮したデータの後ろにさらに何か追加したい場合もあるので、GzipFile オブジェクトの close() メソッド呼び出しは fileobj を閉じません。 このため、書き込みのためにオープンした io.BytesIO オブジェクトを fileobj として渡し、(GzipFile を close() した後に) io.BytesIO オブジェクトの getvalue() メソッドを使って書き込んだデータの入っているメモリバッファを取得することができます。

GzipFile は、イテレーションと with 文を含む io.BufferedIOBase インターフェイスをサポートしています。truncate() メソッドのみ実装されていません。

GzipFile は以下のメソッドと属性も提供しています:

peek(n)

ファイル内の位置を移動せずに展開した n バイトを読み込みます。呼び出し要求を満たすために、圧縮ストリームに対して最大 1 回の単一読み込みが行われます。返されるバイト数はほぼ要求した値になります。

注釈

peek() の呼び出しでは GzipFile のファイル位置は変わりませんが、下層のファイルオブジェクトの位置が変わる惧れがあります。(e.g. GzipFile が fileobj 引数で作成された場合)

バージョン 3.2 で追加.

mtime

展開時に、最後に読み取られたヘッダーの最終更新日時フィールドの値は、この属性から整数として読み取ることができます。ヘッダーを読み取る前の初期値は None です。

gzip で圧縮されたすべてのストリームは、このタイムスタンプフィールドを含む必要があります。gunzip などの一部のプログラムがこのタイムスタンプを使用します。形式は、 time.time() の返り値や、os.stat() が返すオブジェクトの st_mtime 属性と同一です。

バージョン 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 を受け入れるようになりました。

gzip.compress(data, compresslevel=9)

data を圧縮し、圧縮データを含む bytes オブジェクトを返します。compresslevel の意味は上記 GzipFile コンストラクタと同じです。

バージョン 3.2 で追加.

gzip.decompress(data)

data を展開し、展開データを含む bytes オブジェクトを返します。

バージョン 3.2 で追加.

使い方の例

圧縮されたファイルを読み込む例:

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 ファイル形式のサポートを行うために必要な基本ライブラリモジュール。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ圧縮とアーカイブ »


bz2 --- bzip2 圧縮のサポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ圧縮とアーカイブ »

bz2 --- bzip2 圧縮のサポート

ソースコード: Lib/bz2.py

このモジュールは、bzip2 アルゴリズムを用いて圧縮・展開を行う包括的なインターフェイスを提供します。

bz2 モジュールには以下のクラスや関数があります:

  • 圧縮ファイルを読み書きするための open() 関数と BZ2File クラス。
  • インクリメンタルにデータを圧縮・展開するための BZ2Compressor および BZ2Decompressor クラス。
  • 一度に圧縮・展開を行う compress() および decompress() 関数。

このモジュールのクラスはすべて、複数のスレッドから安全にアクセスできます。

ファイルの圧縮/解凍

bz2.open(filename, mode='r', 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 にラップされます。

バージョン 3.3 で追加.

バージョン 3.4 で変更: 'x' (排他的作成) モードが追加されました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

class bz2.BZ2File(filename, mode='r', buffering=None, compresslevel=9)

bzip2 圧縮ファイルをバイナリモードでオープンします。

filename が str あるいは bytes オブジェクトの場合、それを名前とするファイルを直接開きます。そうでない場合、filename は圧縮データを読み書きする ファイルオブジェクト でなくてはなりません。

引数 mode は読み込みモードの 'r' (デフォルト)、上書きモードの 'w'、排他的作成モードの 'x'、あるいは追記モードの 'a' のいずれかを指定できます。これらはそれぞれ 'rb'、'wb'、'xb' および 'ab' と等価です。

filename が (実際のファイル名でなく) ファイルオブジェクトの場合、'w' はファイルを上書きせず、'a' と等価になります。

引数 buffering は無視されます。この引数の使用は非推奨です。

mode が 'w' あるいは 'a' の場合、compresslevel に圧縮レベルを 1 から 9 の整数で指定できます。圧縮率は 1 が最低で、9 (デフォルト値) が最高です。

mode の値が 'r' の場合、入力ファイルは複数の圧縮ストリームでも構いません。

BZ2File には、 io.BufferedIOBase で規定されているメソッドや属性のうち、 detach() と truncate() を除くすべてが備わっています。イテレーションと with 文をサポートしています。

BZ2File は以下のメソッドも提供しています:

peek([n])

ファイル上の現在位置を変更せずにバッファのデータを返します。このメソッドは少なくとも 1 バイトのデータを返します (EOF の場合を除く)。返される正確なバイト数は規定されていません。

注釈

peek() の呼び出しでは BZ2File のファイル位置は変わりませんが、下層のファイルオブジェクトの位置が変わる惧れがあります(e.g. BZ2File を filename にファイルオブジェクトを渡して作成した場合)。

バージョン 3.3 で追加.

バージョン 3.1 で変更: with 構文のサポートが追加されました。

バージョン 3.3 で変更: fileno() 、 readable() 、 seekable() 、 writable() 、 read1() 、 readinto() メソッドが追加されました。

バージョン 3.3 で変更: filename が実際のファイル名でなく ファイルオブジェクト だった場合のサポートが追加されました。

バージョン 3.3 で変更: 'a' (追記) モードが追加され、複数のストリームの読み込みがサポートされました。

バージョン 3.4 で変更: 'x' (排他的作成) モードが追加されました。

バージョン 3.5 で変更: read() メソッドが None を引数として受け取るようになりました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

逐次圧縮および展開

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 を返します。

バージョン 3.3 で追加.

unused_data

圧縮ストリームの末尾以降に存在したデータを表します。

ストリームの末尾に達する前には、この属性には b'' という値が収められています。

needs_input

decompress() メソッドが、新しい非圧縮入力を必要とせずにさらに展開データを提供できる場合、 False です。

バージョン 3.5 で追加.

一括圧縮/解凍

bz2.compress(data, compresslevel=9)

data を圧縮します。

引数 compresslevel を指定する場合は、1 から 9 までの数字を与えてください。デフォルト値は 9 です。

逐次的にデータを圧縮したい場合は、BZ2Compressor を使ってください。

bz2.decompress(data)

data を展開します。

data が複数の圧縮ストリームから成る場合、そのすべてを展開します。

逐次的に展開を行う場合は、BZ2Decompressor を使ってください。

バージョン 3.3 で変更: 複数ストリームの入力をサポートしました。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ圧縮とアーカイブ »


lzma --- LZMA アルゴリズムを使用した圧縮

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ圧縮とアーカイブ »

lzma --- LZMA アルゴリズムを使用した圧縮

バージョン 3.3 で追加.

ソースコード: 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 は io.BufferedIOBase で規定されているメンバのうち、detach() と truncate() を除くすべてをサポートします。イテレーションと with 文をサポートしています。

次のメソッドを提供しています:

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 です。

バージョン 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)

指定したインテグリティチェックがシステムでサポートされていれば真を返します。

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 --- ZIP アーカイブの処理

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ圧縮とアーカイブ »

zipfile --- ZIP アーカイブの処理

ソースコード: Lib/zipfile.py

ZIP は一般によく知られているアーカイブ (書庫化) および圧縮の標準ファイルフォーマットです。このモジュールでは ZIP 形式のファイルの作成、読み書き、追記、書庫内のファイル一覧の作成を行うためのツールを提供します。より高度な使い方でこのモジュールを利用したいのであれば、 PKZIP Application Note に定義されている ZIP ファイルフォーマットの理解が必要になるでしょう。

このモジュールは現在マルチディスク ZIP ファイルを扱うことはできません。ZIP64 拡張を利用する ZIP ファイル (サイズが 4 GiB を超えるような ZIP ファイル) は扱えます。このモジュールは暗号化されたアーカイブの復号をサポートしますが、現在暗号化ファイルを作成することはできません。C 言語ではなく、Python で実装されているため、復号は非常に遅くなっています。

このモジュールは以下の項目を定義しています:

exception zipfile.BadZipFile

正常ではない ZIP ファイルに対して送出されるエラーです。

バージョン 3.2 で追加.

exception zipfile.BadZipfile

BadZipFile の別名です。過去のバージョンの Python との互換性のために用意されています。

バージョン 3.2 で非推奨.

exception zipfile.LargeZipFile

ZIP ファイルが ZIP64 の機能を必要としているが、その機能が有効化されていない場合に送出されるエラーです。

class zipfile.ZipFile

ZIP ファイルの読み書きのためのクラスです。コンストラクタの詳細については、ZipFile オブジェクト 節を参照してください。

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 モジュールが必要です。

バージョン 3.3 で追加.

zipfile.ZIP_LZMA

LZMA 圧縮方法を表す数値定数です。これには lzma モジュールが必要です。

バージョン 3.3 で追加.

注釈

ZIP ファイルフォーマット仕様は 2001 年より bzip2 圧縮を、2006 年より LZMA 圧縮をサポートしていますが、(過去の Python リリースを含む) 一部のツールはこれら圧縮方式をサポートしていないため、ZIP ファイルの処理を全く受け付けないか、あるいは個々のファイルの抽出に失敗する場合があります。

参考

PKZIP Application Note
ZIP ファイルフォーマットおよびアルゴリズムを作成した Phil Katz によるドキュメント。
Info-ZIP Home Page
Info-ZIP プロジェクトによる ZIP アーカイブプログラムおよびプログラム開発ライブラリに関する情報。

ZipFile オブジェクト

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None)

Open a ZIP file, where file can be a path to a file (a string), a file-like object or a path-like object.

The mode parameter should be 'r' to read an existing file, 'w' to truncate and write a new file, 'a' to append to an existing file, or 'x' to exclusively create and write a new file. If mode is 'x' and file refers to an existing file, a FileExistsError will be raised. If mode is 'a' and file refers to an existing ZIP file, then additional files are added to it. If file does not refer to a ZIP file, then a new ZIP archive is appended to the file. This is meant for adding a ZIP archive to another file (such as python.exe). If mode is 'a' and the file does not exist at all, it is created. If mode is 'r' or 'a', the file should be seekable.

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

ファイルがモード 'w'、 'x' または 'a' で作成され、その後そのアーカイブにファイルを追加することなく クローズ された場合、空のアーカイブのための適切な ZIP 構造がファイルに書き込まれます。

ZipFile is also a context manager and therefore supports the with statement. In the example, myzip is closed after the with statement's suite is finished---even if an exception occurs:

with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')

バージョン 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 で変更: The file parameter accepts a path-like object.

バージョン 3.7 で変更: Add the compresslevel parameter.

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.

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 で変更: 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)

メンバをアーカイブから現在の作業ディレクトリに展開します。member は展開するファイルのフルネームまたは ZipInfo オブジェクトでなければなりません。ファイル情報は可能な限り正確に展開されます。path は展開先のディレクトリを指定します。member はファイル名または ZipInfo オブジェクトです。pwd は暗号化ファイルに使われるパスワードです。

作成された (ディレクトリか新ファイルの) 正規化されたパスを返します。

注釈

メンバのファイル名が絶対パスなら、ドライブ/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)

すべてのメンバをアーカイブから現在の作業ディレクトリに展開します。path は展開先のディレクトリを指定します。members は、オプションで、namelist() で返されるリストの部分集合でなければなりません。pwd は、暗号化ファイルに使われるパスワードです。

警告

信頼できないソースからきた 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)

pwd を展開する圧縮ファイルのデフォルトパスワードとして指定します。

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 and, if specified, it will override 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'.

注釈

アーカイブ名はアーカイブルートに対する相対パスでなければなりません。言い換えると、アーカイブ名はパスセパレータで始まってはいけません。

注釈

もし、arcname (arcname が与えられない場合は、filename) が null byte を含むなら、アーカイブ中のファイルのファイル名は、null byte までで切り詰められます。

バージョン 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.filename

Name of the ZIP file.

ZipFile.debug

使用するデバッグ出力レベルです。この属性は 0 (デフォルト、何も出力しない) から 3 (最も多く出力する) までの値に設定することができます。デバッグ情報は sys.stdout に出力されます。

ZipFile.comment

The comment associated with the ZIP file as a bytes object. If assigning a comment to a ZipFile instance created with mode 'w', 'x' or 'a', it should be no longer than 65535 bytes. Comments longer than this will be truncated.

PyZipFile オブジェクト

PyZipFile コンストラクタは ZipFile コンストラクタと同じパラメータに加え、optimize パラメータをとります。

class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)

バージョン 3.2 で追加: パラメータに optimize を追加しました。

バージョン 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 で追加: filterfunc パラメータ。

バージョン 3.6.2 で変更: The pathname parameter accepts a 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)

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.

バージョン 3.6 で追加.

バージョン 3.6.2 で変更: The filename parameter accepts a path-like object.

Instances have the following methods and attributes:

ZipInfo.is_dir()

Return True if this archive member is a directory.

This uses the entry's name: directories should always end with /.

バージョン 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

Expansion field data. The PKZIP Application Note contains some comments on the internal structure of the data contained in this bytes object.

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 が有効かどうか調べます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ圧縮とアーカイブ »


tarfile --- tar アーカイブファイルの読み書き

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • データ圧縮とアーカイブ »

tarfile --- tar アーカイブファイルの読み書き

ソースコード: 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 圧縮をサポートしました。

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 であることを前提に動作します。

'w:gz'、'r:gz'、'w:bz2'、'r:bz2', 'x:gz', 'x:bz2' モードの場合、tarfile.open() はファイルの圧縮レベルを指定するキーワード引数 compresslevel (デフォルトは 9) を受け付けます。

特別な目的のために、mode には 2 番目の形式: 'ファイルモード|[圧縮]' があります。この形式を使うと、tarfile.open() が返すのは、データをブロックからなるストリームとして扱う TarFile オブジェクトになります。この場合、ファイルに対してランダムなシークが行えなくなります。fileobj を指定する場合、 read() および write() メソッドを持つ (mode に依存した) 任意のオブジェクトにできます。bufsize にはブロックサイズを指定します。デフォルトは 20 * 512 バイトです。sys.stdin、ソケット file object、あるいはテープデバイスと組み合わせる場合にはこの形式を使ってください。ただし、このような TarFile オブジェクトにはランダムアクセスを行えないという制限があります。使用例 節を参照してください。現在可能なモードは以下のとおりです。

モード | 動作
'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 を受け付けるようになりました。

class tarfile.TarFile

tar アーカイブを読み書きするためのクラスです。このクラスを直接使わないこと: 代わりに tarfile.open() を使ってください。TarFile オブジェクト を参照してください。

tarfile.is_tarfile(name)

もし name が tar アーカイブファイルであり、tarfile モジュールで読み込める場合に True を返します。

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() メソッドが取得したバッファーが不正だったときに送出されます。

モジュールレベルで以下の定数が利用できます。

tarfile.ENCODING

既定の文字エンコーディング。Windows では 'utf-8' 、それ以外では sys.getfilesystemencoding() の返り値です。

以下の各定数は、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

アーカイブを作成する際のデフォルトのフォーマット。現在は GNU_FORMAT です。

参考

zipfile モジュール
zipfile 標準モジュールのドキュメント。
アーカイブ化操作
shutil が提供するより高水準のアーカイブ機能についてのドキュメント。
GNU tar manual, Basic Tar Format
GNU tar 拡張機能を含む、tar アーカイブファイルのためのドキュメント。

TarFile オブジェクト

TarFile オブジェクトは、tar アーカイブへのインターフェースを提供します。tar アーカイブは一連のブロックです。アーカイブメンバー (保存されたファイル) は、ヘッダーブロックとそれに続くデータブロックで構成されています。一つの tar アーカイブにファイルを何回も保存することができます。各アーカイブメンバーは、TarInfo オブジェクトで確認できます。詳細については TarInfo オブジェクト を参照してください。

TarFile オブジェクトは with 文のコンテキストマネージャーとして利用できます。with ブロックが終了したときにオブジェクトはクローズされます。例外が発生した時、内部で利用されているファイルオブジェクトのみがクローズされ、書き込み用にオープンされたアーカイブのファイナライズは行われないことに注意してください。使用例 節のユースケースを参照してください。

バージョン 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=0)

以下のすべての引数はオプションで、インスタンス属性としてもアクセスできます。

name はアーカイブのパス名です。name は path-like object でも構いません。fileobj が渡された場合は省略可能です。その場合、ファイルオブジェクトに name 属性があれば、それを利用します。

mode は、既存のアーカイブから読み込むための 'r'、既存のアーカイブに追記するための 'a'、既存のファイルがあれば上書きして新しいファイルを作成する 'w' 、あるいは存在しない場合にのみ新しいファイルを作成する 'x' のいずれかです。

fileobj が与えられていれば、それを使ってデータを読み書きします。もしそれが決定できれば、mode は fileobj のモードで上書きされます。fileobj は位置 0 から利用されます。

注釈

TarFile をクローズした時、fileobj はクローズされません。

format はアーカイブのフォーマットを制御します。モジュールレベルで定義されている、USTAR_FORMAT、GNU_FORMAT、あるいは PAX_FORMAT のいずれかである必要があります。

tarinfo 引数を利用して、デフォルトの TarInfo クラスを別のクラスで置き換えることができます。

dereference が False だった場合、シンボリックリンクやハードリンクがアーカイブに追加されます。True だった場合、リンクのターゲットとなるファイルの内容がアーカイブに追加されます。シンボリックリンクをサポートしていないシステムでは効果がありません。

ignore_zeros が False だった場合、空ブロックをアーカイブの終端として扱います。True だった場合、空の (無効な) ブロックをスキップして、可能な限り多くのメンバーを取得しようとします。このオプションは、連結されたり、壊れたアーカイブファイルを扱うときにのみ、意味があります。

debug は 0 (デバッグメッセージ無し) から 3 (全デバッグメッセージ) まで設定できます。このメッセージは sys.stderr に書き込まれます。

errorlevel が 0 の場合、TarFile.extract() 使用時にすべてのエラーが無視されます。エラーが無視された場合でも、debug が有効であれば、エラーメッセージは出力されます。1 の場合、すべての 致命的な(fatal) エラーは OSError を送出します。2 の場合、すべての 致命的でない(non-fatal) エラーも TarError 例外として送出されます。

引数 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)

すべてのメンバーをアーカイブから現在の作業ディレクトリまたは path に抽出します。オプションの members が与えられるときには、getmembers() で返されるリストの一部でなければなりません。所有者、変更時刻、アクセス権限のようなディレクトリ情報はすべてのメンバーが抽出された後にセットされます。これは二つの問題を回避するためです。一つはディレクトリの変更時刻はその中にファイルが作成されるたびにリセットされるということ、もう一つはディレクトリに書き込み許可がなければその中のファイル抽出は失敗してしまうということです。

numeric_owner が True の場合、tarfile の uid と gid 数値が抽出されたファイルのオーナー/グループを設定するために使用されます。False の場合、tarfile の名前付きの値が使用されます。

警告

内容を信頼できない tar アーカイブを、事前の内部チェック前に展開してはいけません。ファイルが path の外側に作られる可能性があります。例えば、"/" で始まる絶対パスのファイル名や、2 重ドット ".." で始まるパスのファイル名です。

バージョン 3.5 で変更: numeric_owner 引数が追加されました。

バージョン 3.6 で変更: path パラメタが path-like object を受け付けるようになりました。

TarFile.extract(member, path="", set_attrs=True, *, numeric_owner=False)

アーカイブからメンバーの完全な名前を使って、現在のディレクトリに展開します。ファイル情報はできる限り正確に展開されます。 member はファイル名もしくは TarInfo オブジェクトです。 path を使って別のディレクトリを指定することもできます。 path は　path-like object でも構いません。set_attrs が false でない限り、ファイルの属性 (所有者、最終更新時刻、モード) は設定されます。

numeric_owner が True の場合、tarfile の uid と gid 数値が抽出されたファイルのオーナー/グループを設定するために使用されます。False の場合、tarfile の名前付きの値が使用されます。

注釈

extract() メソッドはいくつかの展開に関する問題を扱いません。ほとんどの場合、extractall() メソッドの利用を考慮するべきです。

警告

extractall() の警告を参してください。

バージョン 3.2 で変更: パラメーターに set_attrs を追加しました。

バージョン 3.5 で変更: numeric_owner 引数が追加されました。

バージョン 3.6 で変更: path パラメタが path-like object を受け付けるようになりました。

TarFile.extractfile(member)

アーカイブからメンバーをファイルオブジェクトとして抽出します。member はファイル名でも TarInfo オブジェクトでも構いません。member が一般ファイルまたはリンクの場合、io.BufferedReader オブジェクトが返されます。それ以外の場合、None が返されます。

バージョン 3.3 で変更: 戻り値が io.BufferedReader オブジェクトになりました。

TarFile.add(name, arcname=None, recursive=True, *, filter=None)

Add the file name to the archive. name may be any type of file (directory, fifo, symbolic link, etc.). If given, arcname specifies an alternative name for the file in the archive. Directories are added recursively by default. This can be avoided by setting recursive to False. Recursion adds entries in sorted order. If filter is given, it should be a function that takes a TarInfo object argument and returns the changed TarInfo object. If it instead returns None the TarInfo object will be excluded from the archive. See 使用例 for an example.

バージョン 3.2 で変更: filter パラメータが追加されました。

バージョン 3.7 で変更: Recursion adds entries in sorted order.

TarFile.addfile(tarinfo, fileobj=None)

TarInfo オブジェクト tarinfo をアーカイブに追加します。fileobj を与える場合、binary file にしなければならず、 tarinfo.size バイトがそれから読まれ、アーカイブに追加されます。TarInfo オブジェクトを直接作成するか、gettarinfo() を使って作成することができます。

TarFile.gettarinfo(name=None, arcname=None, fileobj=None)

os.stat() の結果か、既存のファイルに相当するものから、TarInfo オブジェクトを作成します。このファイルは、name で名付けられるか、ファイル記述子を持つ file object fileobj として指定されます。name は:term: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

pax グローバルヘッダーに含まれる key-value ペアの辞書です。

TarInfo オブジェクト

TarInfo オブジェクトは TarFile の一つのメンバーを表します。ファイルに必要なすべての属性 (ファイルタイプ、ファイルサイズ、時刻、アクセス権限、所有者等のような) を保存する他に、そのタイプを決定するのに役に立ついくつかのメソッドを提供します。これにはファイルのデータそのものは 含まれません 。

TarInfo オブジェクトは TarFile のメソッド getmember()、 getmembers() および gettarinfo() によって返されます。

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

アーカイブメンバーの名前。

TarInfo.size

バイト単位でのサイズ。

TarInfo.mtime

最後に変更された時刻。

TarInfo.mode

許可ビット。

TarInfo.type

ファイルタイプ。type は通常、定数 REGTYPE、AREGTYPE、LNKTYPE、SYMTYPE、DIRTYPE、FIFOTYPE、CONTTYPE、CHRTYPE、BLKTYPE、あるいは GNUTYPE_SPARSE のいずれかです。TarInfo オブジェクトのタイプをもっと簡単に解決するには、下記の is*() メソッドを使って下さい。

TarInfo.linkname

リンク先ファイルの名前。これはタイプ LNKTYPE と SYMTYPE の TarInfo オブジェクトにだけ存在します。

TarInfo.uid

ファイルメンバーを保存した元のユーザーのユーザー ID。

TarInfo.gid

ファイルメンバーを保存した元のユーザーのグループ ID。

TarInfo.uname

ファイルメンバーを保存した元のユーザーのユーザー名。

TarInfo.gname

ファイルメンバーを保存した元のユーザーのグループ名。

TarInfo.pax_headers

pax 拡張ヘッダーに関連付けられた、key-value ペアの辞書。

TarInfo オブジェクトは便利な照会用のメソッドもいくつか提供しています:

TarInfo.isfile()

Tarinfo オブジェクトが一般ファイルの場合に、True を返します。

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 を返します。

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

バージョン 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

詳細も出力します。

使用例

tar アーカイブから現在のディレクトリにすべて抽出する方法:

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall()
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 モジュールは長いファイル名を完全にサポートしています。 スパースファイルは読み込みのみサポートしています。

  • POSIX.1-2001 pax フォーマット (PAX_FORMAT)。最も柔軟性があり、ほぼ制限が無いフォーマットです。長いファイル名やリンク名、大きいファイルをサポートし、パス名をポータブルな方法で保存します。しかし、現在のところ、すべての tar の実装が pax フォーマットを正しく扱えるわけではありません。

    pax フォーマットは既存の ustar フォーマットの拡張です。ustar では保存できない情報を追加のヘッダーを利用して保存します。pax には 2 種類のヘッダーがあります。1 つ目は拡張ヘッダーで、その次のファイルヘッダーに影響します。2 つ目はグローバルヘッダーで、アーカイブ全体に対して有効で、それ以降のすべてのファイルに影響します。すべての pax ヘッダーの内容は、ポータブル性のために UTF-8 で保存されます。

他にも、読み込みのみサポートしている 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 ヘッダーがデコードされた場合、あるいはサロゲート文字を含む文字列が格納されていた場合に使用されます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • データ圧縮とアーカイブ »


ファイルフォーマット

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

ファイルフォーマット

この章で説明されるモジュールはマークアップやEメールでない様々なファイルフォーマットを構文解析します。

  • csv --- CSV ファイルの読み書き
    • モジュールコンテンツ
    • Dialect クラスと書式化パラメータ
    • reader オブジェクト
    • writer オブジェクト
    • 使用例
  • configparser --- 設定ファイルのパーサー
    • クイックスタート
    • サポートされるデータ型
    • 代替値
    • サポートするINI ファイルの構造
    • 値の補間
    • マップ型プロトコルアクセス
    • パーサーの振る舞いをカスタマイズする
    • レガシーな API の例
    • ConfigParser オブジェクト
    • RawConfigParser オブジェクト
    • 例外
  • netrc --- netrc ファイルの処理
    • netrc オブジェクト
  • xdrlib --- XDR データのエンコードおよびデコード
    • Packer オブジェクト
    • Unpacker オブジェクト
    • 例外
  • plistlib --- Mac OS X .plist ファイルの生成と解析
    • 使用例

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


csv --- CSV ファイルの読み書き

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルフォーマット »

csv --- CSV ファイルの読み書き

ソースコード: Lib/csv.py

CSV (Comma Separated Values、カンマ区切り値列) と呼ばれる形式は、 スプレッドシートやデータベース間でのデータのインポートやエクスポートにおける最も一般的な形式です。 CSVフォーマットは、 RFC 4180 によって標準的な方法でフォーマットを記述する試みが行われる以前から長年使用されました。明確に定義された標準がないということは、異なるアプリケーション によって生成されたり取り込まれたりするデータ間では、しばしば微妙な違いが発生するということを意味します。こうした違いのために、複数のデータ源から得られた CSV ファイルを処理する作業が鬱陶しいものになることがあります。とはいえ、デリミタ (delimiter) やクオート文字の 相違はあっても、全体的な形式は十分似通っているため、こうしたデータを効率的に操作し、データの読み書きにおける細々としたことをプログラマ から隠蔽するような単一のモジュールを書くことは可能です。

csv モジュールでは、CSV 形式で書かれたテーブル状のデータを読み書きするためのクラスを実装しています。このモジュールを使うことで、プログラマは Excel で使われている CSV 形式に関して詳しい知識をもっていなくても、 "このデータを Excel で推奨されている形式で書いてください" とか、 "データを Excel で作成されたこのファイルから読み出してください" と言うことができます。プログラマはまた、他のアプリケーションが解釈できる CSV 形式を記述したり、独自の特殊な目的をもった CSV 形式を定義することができます。

csv モジュールの reader および writer オブジェクトはシーケンス型を読み書きします。プログラマは DictReader や DictWriter クラスを使うことで、データを辞書形式で読み書きすることもできます。

参考

PEP 305 - CSV File API
Python へのこのモジュールの追加を提案している Python 改良案 (PEP: Python Enhancement Proposal)。

モジュールコンテンツ

csv モジュールでは以下の関数を定義しています:

csv.reader(csvfile, dialect='excel', **fmtparams)

与えられた csvfile 内の行を反復処理するような reader オブジェクトを返します。 csvfile はイテレータ(iterator)プロトコルをサポートし、 __next__() メソッドが呼ばれた際に常に文字列を返すような任意のオブジェクトにすることができます --- ファイルオブジェクト でもリストでも構いません。 csvfile がファイルオブジェクトの場合、 newline='' として開くべきです。 [1] オプションとして dialect パラメータを与えることができ、特定の CSV 表現形式 (dialect) 特有のパラメータの集合を定義するために使われます。 dialect 引数は Dialect クラスのサブクラスのインスタンスか、 list_dialects() 関数が返す文字列の一つにすることができます。別のオプションである fmtparams キーワード引数は、現在の表現形式における個々の書式パラメータを上書きするために与えることができます。表現形式および書式化パラメータの詳細については、 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 のように動作しますが、個々の列の情報を OrderedDict にマップするオブジェクトを生成します。マップのキーは省略可能な fieldnames パラメータで与えられます。

fieldnames パラメータは sequence です。 fieldnames が省略された場合、ファイル f の最初の列の値が fieldnames として使われます。 fieldnames がどのように決定されるかに関わらず、整列された (ordered) 辞書はそれらのオリジナルの順番を維持します。

列が fieldnames より多くのフィールドを持っていた場合、残りのデータはリストに入れられて、 restkey により指定されたフィールド名 (デフォルトでは None) で保存されます。非ブランクの列が fieldnames よりも少ないフィールドしか持たない場合、不明の値は None によって埋められます。

その他の省略可能またはキーワード形式のパラメータは、ベースになっている reader インスタンスに渡されます。

バージョン 3.6 で変更: 返される列の型は OrderedDict になりました。

短い利用例:

>>> 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)
OrderedDict([('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 インスタンスに渡されます。

Note that unlike the DictReader class, the fieldnames parameter of the DictWriter class is not optional.

短い利用例:

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 クラスはコンテナクラスで、基本的な用途としては、その属性を特定の reader や writer インスタンスのパラメータを定義するために用います。

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 として登録されています。

バージョン 3.2 で追加.

class csv.Sniffer

Sniffer クラスは CSV ファイルの書式を推理するために用いられるクラスです。

Sniffer クラスではメソッドを二つ提供しています:

sniff(sample, delimiters=None)

与えられた sample を解析し、発見されたパラメータを反映した Dialect サブクラスを返します。オプションの delimiters パラメータを与えた場合、有効なデリミタ文字を含んでいるはずの文字列として解釈されます。

has_header(sample)

(CSV 形式と仮定される) サンプルテキストを解析して、最初の行がカラムヘッダの羅列のように推察される場合 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 モジュールでは以下の例外を定義しています:

exception csv.Error

全ての関数において、エラーが検出された際に送出される例外です。

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

レコードに対する入出力形式の指定をより簡単にするために、特定の書式化パラメータは表現形式 (dialect) にまとめてグループ化されます。表現形式は Dialect クラスのサブクラスで、様々なクラス特有のメソッドと、 validate() メソッドを一つ持っています。 reader または writer オブジェクトを生成するとき、プログラマは文字列または Dialect クラスのサブクラスを表現形式パラメータとして渡さなければなりません。さらに、 dialect パラメータの代りに、プログラマは上で定義されている属性と同じ名前を持つ個々の書式化パラメータを Dialect クラスに指定することができます。

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 で、エスケープを行ないません。

Dialect.lineterminator

writer が作り出す各行を終端する際に用いられる文字列です。デフォルトでは '\r\n' です。

注釈

reader は '\r' または '\n' のどちらかを行末と認識するようにハードコードされており、 lineterminator を無視します。この振る舞いは将来変更されるかもしれません。

Dialect.quotechar

delimiter や quotechar といった特殊文字を含むか、改行文字を含むフィールドをクオートする際に用いられる 1 文字からなる文字列です。デフォルトでは '"' です。

Dialect.quoting

クオートがいつ writer によって生成されるか、また reader によって認識されるかを制御します。 QUOTE_* 定数のいずれか (モジュールコンテンツ 節参照) をとることができ、デフォルトでは QUOTE_MINIMAL です。

Dialect.skipinitialspace

True の場合、 delimiter の直後に続く空白は無視されます。デフォルトでは False です。

Dialect.strict

True の場合、 不正な CSV 入力に対して Error を送出します。デフォルトでは False です。

reader オブジェクト

reader オブジェクト(DictReader インスタンス、および reader() 関数によって返されたオブジェクト) は、以下の public なメソッドを持っています:

csvreader.__next__()

reader の反復可能なオブジェクトから、現在の表現形式に基づいて次の行を解析してリスト（オブジェクトが reader() から返された場合）または辞書 （ DictReader のインスタンスの場合）として返します。通常は next(reader) のようにして呼び出すことになります。

reader オブジェクトには以下の公開属性があります:

csvreader.dialect

パーサで使われる表現形式の読み出し専用の記述です。

csvreader.line_num

ソースイテレータから読んだ行数です。この数は返されるレコードの数とは、レコードが複数行に亘ることがあるので、一致しません。

DictReader オブジェクトは、以下の public な属性を持っています:

csvreader.fieldnames

オブジェクトを生成するときに渡されなかった場合、この属性は最初のアクセス時か、ファイルから最初のレコードを読み出したときに初期化されます。

writer オブジェクト

Writer オブジェクト(DictWriter インスタンス、および writer() 関数によって返されたオブジェクト) は、以下の public なメソッドを持っています: row には、 Writer オブジェクトの場合には文字列か数値のイテラブルを指定し、 DictWriter オブジェクトの場合はフィールド名をキーとして対応する文字列か数値を格納した辞書オブジェクトを指定します(数値は str() で変換されます)。複素数を出力する場合、値をかっこで囲んで出力します。このため、CSV ファイルを読み込むアプリケーションで（そのアプリケーションが複素数をサポートしていたとしても）問題が発生する場合があります。

csvwriter.writerow(row)

row パラメータを現在の表現形式に基づいて書式化し、 writer のファイルオブジェクトに書き込みます。

バージョン 3.5 で変更: 任意のイテラブルのサポートの追加。

csvwriter.writerows(rows)

Write all elements in rows (an iterable of row objects as described above) to the writer's file object, formatted according to the current dialect.

writer オブジェクトには以下の公開属性があります:

csvwriter.dialect

writer で使われる表現形式の読み出し専用の記述です。

DictWriter のオブジェクトは以下の public メソッドを持っています:

DictWriter.writeheader()

(コンストラクタで指定された)フィールド名の行を出力します。

バージョン 3.2 で追加.

使用例

最も簡単な 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.getpreferredencoding() を参照)。他のエンコーディングを用いてデコードするには、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 newlines) の改行処理を行うため、newline='' を指定することは常に安全なはずです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルフォーマット »


configparser --- 設定ファイルのパーサー

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルフォーマット »

configparser --- 設定ファイルのパーサー

ソースコード: Lib/configparser.py

このモジュールは、 Microsoft Windows の INI ファイルに似た構造を持ったベーシックな設定用言語を実装した ConfigParser クラスを提供します。このクラスを使ってユーザーが簡単にカスタマイズできる Python プログラムを作ることができます。

注釈

このライブラリでは、Windowsのレジストリ用に拡張された INI 文法はサポート していません 。

参考

shlex モジュール
アプリケーション設定ファイルのフォーマットとして使える、Unix シェルに似たミニ言語の作成を支援します。
json モジュール
json モジュールは、同じ目的に利用できる JavaScript の文法のサブセットを実装しています。

クイックスタート

次のような、非常に簡単な設定ファイルを例に考えましょう:

[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes

[bitbucket.org]
User = hg

[topsecret.server.com]
Port = 50022
ForwardX11 = no

INI ファイルの構造は 下のセクション で解説します。 基本的に、ファイルは複数のセクションからなり、各セクションは複数のキーと値を持ちます。 configparser のクラス群はそれらのファイルを読み書きできます。 まずは上のような設定ファイルをプログラムから作成してみましょう。

>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
...                      'Compression': 'yes',
...                      'CompressionLevel': '9'}
>>> config['bitbucket.org'] = {}
>>> config['bitbucket.org']['User'] = 'hg'
>>> config['topsecret.server.com'] = {}
>>> topsecret = config['topsecret.server.com']
>>> 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()
['bitbucket.org', 'topsecret.server.com']
>>> 'bitbucket.org' in config
True
>>> 'bytebong.com' in config
False
>>> config['bitbucket.org']['User']
'hg'
>>> config['DEFAULT']['Compression']
'yes'
>>> topsecret = config['topsecret.server.com']
>>> topsecret['ForwardX11']
'no'
>>> topsecret['Port']
'50022'
>>> for key in config['bitbucket.org']:
...     print(key)
user
compressionlevel
serveraliveinterval
compression
forwardx11
>>> config['bitbucket.org']['ForwardX11']
'yes'

上の例からわかるように、API はとても直感的です。唯一の魔術は、DEFAULT セクションが他の全てのセクションのためのデフォルト値を提供していることです [1]。 また、セクション内の各キーは大文字小文字を区別せず、全て小文字で保存されていることにも注意してください [1]。

サポートされるデータ型

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['bitbucket.org'].getboolean('ForwardX11')
True
>>> config.getboolean('bitbucket.org', 'Compression')
True

config parser では、 getboolean() 以外に getint() と getfloat() メソッドも提供されています。独自のコンバーターの登録、提供されたメソッドのカスタマイズもできます。 [1]

代替値

辞書と同じように、セクションの get() メソッドは代替値を提供しています:

>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Cipher')
>>> topsecret.get('Cipher', '3des-cbc')
'3des-cbc'

デフォルト値は代替値よりも優先されることに注意してください。例えば上の例では、'CompressionLevel' キーは 'DEFAULT' セクションにしか存在しません。その値を 'topsecret.server.com' から取得しようとした場合、代替値を指定しても常にデフォルト値を返します:

>>> topsecret.get('CompressionLevel', '3')
'9'

もう一つ注意すべき点は、パーサーレベルの(訳注: ConfigParserクラスの) get() メソッドは、後方互換性のために、カスタムのより複雑なインターフェースを提供します。このメソッドを使用する際には、フォールバック値はキーワード引数としてのみ指定できる fallback 引数を介して提供されます:

>>> config.get('bitbucket.org', '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 ファイルの構造

設定ファイルは複数のセクションから構成されます。セクションは、[section] ヘッダに続いた、特定の文字列(デフォルトでは = または : [1] )で区切られたキーと値のエントリです。デフォルトでは、セクション名は大文字と小文字を区別しますが、キーはそうではありません [1]。キーと値、それぞれの先頭と末尾の空白は取り除かれます。値は省略することができ、その際でも、キーと値の区切り文字は残しておけます。値はまた、値の先頭の行より深くインデントされていれば、複数の行にまたがっても構いません。パーサーのモードによって、空白行は、複数行からなる値の一部として扱われるか、無視されます。

設定ファイルには先頭に特定の文字 (デフォルトでは # および ; [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

上の例では、 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

他のセクションから値を持ってくることもできます:

[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}

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

バージョン 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"]

  • All sections include DEFAULTSECT values as well which means that .clear() on a section may not leave the section visibly empty. This is because default values cannot be deleted from the section (because technically they are not there). If they are overridden in the section, deleting causes the default value to be visible again. Trying to delete a default value causes a KeyError.

  • DEFAULTSECT はパーサーから取り除けません:

    • trying to delete it raises 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 スタイルを集めた集合をサポートするために、非常に役立ちます。デフォルトの機能は主に歴史的背景によって決められたので、機能によってはカスタマイズしてお使いください。

特定の設定パーサーのはたらきを変える最も一般的な方法は __init__() オプションを使うことです:

  • defaults, デフォルト値: None

    このオプションは最初に DEFAULT セクションに加えられるキー-値の対の辞書を受け付けます。

    ヒント: 特定のセクションにデフォルト値を指定したいなら、実際のファイルを読み込む前に read_dict() を使ってください。

  • dict_type, デフォルト値: collections.OrderedDict

    このオプションはマップ型プロトコルの振る舞い方や書き込まれる設定ファイルの見た目に大きく影響します。デフォルトの順序付き辞書では、全てのセクションはパーサーに加えられた順に並びます。同じことがセクション内のオプションにも言えます。

    セクションとオプションをライトバック時にソートするためなどに、別の辞書型も使えます。パフォーマンスの理由のために普通の辞書を使うこともできます。

    Please note: there are ways to add a set of key-value pairs in a single operation. When you use a regular dictionary in those operations, the order of the keys may be random. For example:

    >>> parser = configparser.ConfigParser()
>>> parser.read_dict({'section1': {'key1': 'value1',
...                                'key2': 'value2',
...                                'key3': 'value3'},
...                   'section2': {'keyA': 'valueA',
...                                'keyB': 'valueB',
...                                'keyC': 'valueC'},
...                   'section3': {'foo': 'x',
...                                'bar': 'y',
...                                'baz': 'z'}
... })
>>> parser.sections()
['section3', 'section2', 'section1']
>>> [option for option in parser['section3']]
['baz', 'foo', 'bar']

    In these operations you need to use an ordered dictionary as well:

    >>> from collections import OrderedDict
>>> parser = configparser.ConfigParser()
>>> parser.read_dict(
...   OrderedDict((
...     ('s1',
...      OrderedDict((
...        ('1', '2'),
...        ('3', '4'),
...        ('5', '6'),
...      ))
...     ),
...     ('s2',
...      OrderedDict((
...        ('a', 'b'),
...        ('c', 'd'),
...        ('e', 'f'),
...      ))
...     ),
...   ))
... )
>>> parser.sections()
['s1', 's2']
>>> [option for option in parser['s1']]
['1', '3', '5']
>>> [option for option in parser['s2'].values()]
['b', 'd', 'f']

  • 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

    True に設定された場合、パーサーは単一のソースから (read_file(), read_string() または read_dict() を使って) 読み込むときにセクションやオプションの重複を許さなくなります。新しいアプリケーションには strict なパーサーを使うことが推奨されます。

    バージョン 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, デフォルト値: 未設定

    設定パーサーは、型変換を実行するオプションの値ゲッターを提供します。デフォルトでは、 getint()、 getfloat()、 getboolean() が実装されています。他のゲッターが必要な場合、ユーザーはそれらをサブクラスで定義するか、辞書を渡します。辞書を渡す場合、各キーはコンバーターの名前で、値は当該変換を実装する呼び出し可能オブジェクトです。例えば、 {'decimal': decimal.Decimal} を渡すと、パーサーオブジェクトとすべてのセクションプロキシの両方に、 getdecimal() が追加されます。つまり、parser_instance.getdecimal('section', 'key', fallback=0) と 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']
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 となり、後端のデリミタを除いてシリアル化されます。

default_section が与えられた場合、他のセクションへのデフォルト値や補間のためのデフォルト値を保持する特別なセクションの名前を指定します (通常は "DEFAULT" という名前です)。この値は実行時に default_section インスタンス属性を使って取得や変更ができます。

補間の動作は、 interpolation 引数を通してカスタムハンドラを与えることでカスタマイズできます。 None 引数を使うと補間を完全に無効にできます。 ExtendedInterpolation() は、 zc.buildout に影響を受けたより高度な補間を提供します。この件に 特化したドキュメントのセクション を参照してください。

補間に使われるすべてのオプション名は、他のオプション名参照と同様に、 optionxform() メソッドを通して渡されます。例えば、 optionxform() のデフォルトの実装を使うと、値 foo %(bar)s と foo %(BAR)s は等しくなります。

converters が与えられた場合、各キーが型コンバーターの名前を表し、各値が文字列から目的のデータ型への変換を実装する呼び出し可能オブジェクトです。各コンバーターは、自身の対応する get*() メソッドをパーサーオブジェクトとセクションプロキシで取得します。

バージョン 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.7 で変更: 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)

Attempt to read and parse an iterable of filenames, returning a list of filenames which were successfully parsed.

If filenames is a string, a bytes object or a path-like object, it is treated as a single filename. If a file named in filenames cannot be opened, that file will be ignored. This is designed so that you can specify an iterable of potential configuration file locations (for example, the current directory, the user's home directory, and some system-wide directory), and all existing configuration files in the iterable will be read.

どの設定ファイルも存在しなかった場合、 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 で追加: encoding 引数。以前は、すべてのファイルが open() のデフォルトエンコーディングを使って読まれていました。

バージョン 3.6.1 で追加: filenames 引数が path-like object を受け入れるようになりました。

バージョン 3.7 で追加: The filenames parameter accepts a bytes object.

read_file(f, source=None)

設定データを f から読み込んで解析します。f は Unicode 文字列を yield するイテラブル (例えばテキストモードで開かれたファイル) です。

オプションの引数 source は読み込まれるファイルの名前を指定します。与えられず、 f に name 属性があれば、それが source として使われます。デフォルトは '<???>' です。

バージョン 3.2 で追加: readfp() を置き換えます。

read_string(string, source='<string>')

設定データを文字列から解析します。

オプションの引数 source はコンテキストにおける渡された文字列の名前を指定します。与えられなければ、'<string>' が使われます。これは一般にファイルシステムパスや URL にします。

バージョン 3.2 で追加.

read_dict(dictionary, source='<dict>')

辞書的な items() メソッドを提供する任意のオブジェクトから設定を読み込みます。キーはセクション名で、値はそのセクションに現れるキーと値をもつ辞書です。使われた辞書型が順序を保存するなら、セクションおよびそのキーは順に加えられます。値は自動で文字列に変換されます。

オプションの引数 source はコンテキストにおける渡された辞書の名前を指定します。与えられなければ、<dict> が使われます。

このメソッドを使ってパーサー間で状態をコピーできます。

バージョン 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() メソッドに与えるものと同じ意味を持ちます。

set(section, option, value)

与えられたセクションが存在すれば、与えられたオプションを指定された値に設定します。そうでなければ NoSectionError を送出します。 option および value は文字列でなければなりません。そうでなければ TypeError が送出されます。

write(fileobject, space_around_delimiters=True)

設定の表現を指定された file object に書き込みます。 fileobject は (文字列を受け付ける) テキストモードで開かれていなければなりません。この表現は後で read() を呼び出すことでパースできます。 space_around_delimiters が真なら、キーと値の間のデリミタはスペースで囲まれます。

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() が呼び出される前に取り除かれます。

readfp(fp, filename=None)

バージョン 3.2 で非推奨: 代わりに read_file() を使ってください。

バージョン 3.2 で変更: readfp() は fp.readline() を呼び出す代わりに fp をイテレートするようになりました。

readfp() をイテレーションをサポートしない引数で呼び出す既存のコードには、ファイル的なオブジェクトまわりのラッパーとして以下のジェネレーターが使えます:

def readline_generator(fp):
    line = fp.readline()
    while line:
        yield line
        line = fp.readline()

parser.readfp(fp) の代わりに parser.read_file(readline_generator(fp)) を使ってください。

configparser.MAX_INTERPOLATION_DEPTH

get() の raw が偽であるときの再帰的な補間の最大の深さです。これはデフォルトの interpolation を使うときのみ関係します。

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.7 で変更: 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

add_section() がすでに存在するセクションの名前で呼び出された場合や、strict なパーサーで単一の入力ファイル、文字列、辞書中に同じセクションが複数回現れたときに送出される例外です。

バージョン 3.2 で追加: オプションの source と lineno が属性および __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.2 で変更: filename という属性および __init__() の引数は source に名前が変更されました。

脚注

[1] (1, 2, 3, 4, 5, 6, 7, 8, 9, 10) 設定パーサーは大々的にカスタマイズできます。脚注の参照で概説された挙動の変更に関心がある場合、Customizing Parser Behaviour セクションを参照してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルフォーマット »


netrc --- netrc ファイルの処理

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルフォーマット »

netrc --- netrc ファイルの処理

ソースコード: Lib/netrc.py

netrc クラスは、Unix ftp プログラムや他の FTP クライアントで用いられる netrc ファイル形式を解析し、カプセル化 (encapsulate) します。

class netrc.netrc([file])

A netrc instance or subclass instance encapsulates data from a netrc file. The initialization argument, if present, specifies the file to parse. If no argument is given, the file .netrc in the user's home directory -- as determined by os.path.expanduser() -- will be read. Otherwise, a FileNotFoundError exception will be raised. Parse errors will raise NetrcParseError with diagnostic information including the file name, line number, and terminating token. If no argument is specified on a POSIX system, the presence of passwords in the .netrc file will raise a NetrcParseError if the file ownership or permissions are insecure (owned by a user other than the user running the process, or accessible for read or write by any other user). This implements security behavior equivalent to that of ftp and other programs that use .netrc.

バージョン 3.4 で変更: POSIX パーミッションのチェックが追加されました。

バージョン 3.7 で変更: os.path.expanduser() is used to find the location of the .netrc file when file is not passed as argument.

exception netrc.NetrcParseError

ソースファイルのテキスト中で文法エラーに遭遇した場合に netrc クラスによって送出される例外です。 この例外のインスタンスは 3 つのインスタンス変数を持っています: msg はテキストによるエラーの説明、 filename はソースファイルの名前、そして lineno はエラーが発見された行番号です。

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

マクロ名を文字列のリストに対応付けている辞書です。

注釈

利用可能なパスワードの文字セットは、ASCII のサブセットのみです。全ての ASCII の記号を使用することができます。しかし、空白文字と印刷不可文字を使用することはできません。この制限は .netrc ファイルの解析方法によるものであり、将来解除されます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルフォーマット »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルフォーマット »

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

ソースコード: Lib/xdrlib.py

xdrlib モジュールは外部データ表現標準 (External Data Representation Standard) のサポートを実現します。この標準は 1987 年に Sun Microsystems, Inc. によって書かれ、 RFC 1014 で定義されています。このモジュールでは RFC で記述されているほとんどのデータ型をサポートしています。

xdrlib モジュールでは 2 つのクラスが定義されています。一つは変数を XDR 表現にパックするためのクラスで、もう一方は XDR 表現からアンパックするためのものです。2 つの例外クラスが同様にして定義されています。

class xdrlib.Packer

Packer はデータを XDR 表現にパックするためのクラスです。 Packer クラスのインスタンス生成は引数なしで行われます。

class xdrlib.Unpacker(data)

Unpacker は Packer と対をなしていて、文字列バッファから XDR をアンパックするためのクラスです。入力バッファ data を引数に与えてインスタンスを生成します。

参考

RFC 1014 - XDR: External Data Representation Standard
この RFC が、かつてこのモジュールが最初に書かれた当時に XDR 標準であったデータのエンコード方法を定義していました。現在は RFC 1832 に更新されているようです。
RFC 1832 - 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)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルフォーマット »


plistlib --- Mac OS X .plist ファイルの生成と解析

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ファイルフォーマット »

plistlib --- Mac OS X .plist ファイルの生成と解析

ソースコード: Lib/plistlib.py

このモジュールは主に Mac OS X で使われる「プロパティーリスト」ファイルを読み書きするインターフェイスを提供します。バイナリと XML の plist ファイルの両方をサポートします。

プロパティーリスト (.plist) ファイル形式は基本的型のオブジェクト、たとえば辞書やリスト、数、文字列など、に対する単純な直列化です。たいてい、トップレベルのオブジェクトは辞書です。

plist ファイルを書き出したり解析したりするには dump() や load() 関数を利用します。

バイトオブジェクトの plist データを扱うためには dumps() や loads() を利用します。

値は文字列、整数、浮動小数点数、ブール型、タプル、リスト、辞書 (ただし文字列だけがキーになれます)、 Data、bytes、bytesarray または datetime.datetime のオブジェクトです。

バージョン 3.4 で変更: 新しい API。古い API は撤廃されました。バイナリ形式の plist がサポートされました。

参考

PList manual page
このファイル形式の Apple の文書。

このモジュールは以下の関数を定義しています:

plistlib.load(fp, *, fmt=None, use_builtin_types=True, dict_type=dict)

plist ファイルを読み込みます。fp は読み込み可能かつバイナリのファイルオブジェクトです。展開されたルートオブジェクト (通常は辞書です) を返します。

fmt はファイルの形式で、次の値が有効です。

  • None: ファイル形式を自動検出します
  • FMT_XML: XML ファイル形式です
  • FMT_BINARY: バイナリの plist 形式です

use_builtin_types が真 (デフォルト) の場合、バイナリデータが bytes のインスタンスとして返されます。偽の場合、 Data のインスタンスとして返されます。

The dict_type is the type used for dictionaries that are read from the plist file.

FMT_XML 形式の XML データは xml.parsers.expat にある Expat パーサーを使って解析されます。不正な形式の XML に対して送出される可能性のある例外については、そちらの文書を参照してください。plist 解析器では、未知の要素は単純に無視されます。

バイナリ形式のパーサーは、ファイルを解析できない場合に InvalidFileException を送出します。

バージョン 3.4 で追加.

plistlib.loads(data, *, fmt=None, use_builtin_types=True, dict_type=dict)

バイナリオブジェクトから plist をロードします。キーワード引数の説明については、 load() を参照してください。

バージョン 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 が送出されます。

バージョン 3.4 で追加.

plistlib.dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)

value を plist 形式のバイトオブジェクトとして返します。この関数のキーワード引数の説明については、 dump() を参照してください。

バージョン 3.4 で追加.

以下の関数は廃止されています。

plistlib.readPlist(pathOrFile)

plist ファイルを読み込みます。pathOrFile はファイル名もしくは (読み込み可能かつバイナリの) ファイルです。展開されたルートオブジェクト (通常は辞書です) を返します。

この関数は、実際の動作のために load() を呼び出します。キーワード引数の説明については、その関数 のドキュメントを参照してください。

バージョン 3.4 で非推奨: 代わりに load() を使ってください。

バージョン 3.7 で変更: Dict values in the result are now normal dicts. You no longer can use attribute access to access items of these dictionaries.

plistlib.writePlist(rootObject, pathOrFile)

rootObject を XML plist ファイルに書き込みます。 pathOrFile は、ファイル名もしくは (書き込み可能かつバイナリの) ファイルオブジェクトです。

バージョン 3.4 で非推奨: 代わりに dump() を使ってください。

plistlib.readPlistFromBytes(data)

バイト列オブジェクトから plist データを読み取ります。ルートオブジェクトを返します。

キーワード引数の説明については、 load() を参照してください。

バージョン 3.4 で非推奨: 代わりに loads() を使ってください。

バージョン 3.7 で変更: Dict values in the result are now normal dicts. You no longer can use attribute access to access items of these dictionaries.

plistlib.writePlistToBytes(rootObject)

rootObject を XML plist 形式のバイト列オブジェクトとして返します。

バージョン 3.4 で非推奨: 代わりに dumps() を使ってください。

以下のクラスが使用可能です:

class plistlib.Data(data)

バイト列オブジェクト data を包むラッパオブジェクトを返します。plist 中に入れられる <data> 型を表すものとして plist への/からの変換関数で使われます。

これには data という一つの属性があり、そこに収められた Python バイト列オブジェクトを取り出すのに使えます。

バージョン 3.4 で非推奨: 代わりに bytes オブジェクトを使ってください。

以下の定数が利用可能です:

plistlib.FMT_XML

plist ファイルの XML 形式です

バージョン 3.4 で追加.

plistlib.FMT_BINARY

plist ファイルのバイナリ形式です

バージョン 3.4 で追加.

使用例

plist を作ります:

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.fromtimestamp(time.mktime(time.gmtime())),
)
with open(fileName, 'wb') as fp:
    dump(pl, fp)

plist を解析します:

with open(fileName, 'rb') as fp:
    pl = load(fp)
print(pl["aKey"])

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ファイルフォーマット »


暗号関連のサービス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

暗号関連のサービス

この章で説明しているモジュールは、暗号的な性質の様々なアルゴリズムを実装しています。これらはインストールする際の選択によって利用可能です。 Unix システムにおいては、さらに crypt モジュールが利用可能な場合があります。これは概観です:

  • hashlib --- セキュアハッシュおよびメッセージダイジェスト
    • ハッシュアルゴリズム
    • SHAKE 可変長ダイジェスト
    • 鍵導出
    • BLAKE2
      • ハッシュオブジェクトの作成
      • 定数
      • 使用例
        • 簡単なハッシュ化
        • Using different digest sizes
        • Keyed hashing
        • Randomized hashing
        • Personalization
        • ツリーモード
      • クレジット:
  • hmac --- メッセージ認証のための鍵付きハッシュ化
  • secrets --- 機密を扱うために安全な乱数を生成する
    • 乱数
    • トークンの生成
      • トークンは何バイト使うべきか？
    • その他の関数
    • レシピとベストプラクティス

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


hashlib --- セキュアハッシュおよびメッセージダイジェスト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 暗号関連のサービス »

hashlib --- セキュアハッシュおよびメッセージダイジェスト

ソースコード: Lib/hashlib.py

このモジュールは、セキュアハッシュやメッセージダイジェスト用のさまざまなアルゴリズムを実装したものです。FIPSのセキュアなハッシュアルゴリズムである SHA1、SHA224、SHA256、SHA384およびSHA512 (FIPS 180-2 で定義されているもの) だけでなくRSAのMD5アルゴリズム (Internet RFC 1321 で定義されています)も実装しています。「セキュアなハッシュ」と「メッセージダイジェスト」はどちらも同じ意味です。古くからあるアルゴリズムは「メッセージダイジェスト」と呼ばれていますが、最近は「セキュアハッシュ」という用語が用いられています。

注釈

adler32 や crc32 ハッシュ関数は zlib モジュールで提供されています。

警告

幾つかのアルゴリズムはハッシュの衝突に弱いことが知られています。最後の "参考" セクションを見てください。

ハッシュアルゴリズム

各 hash の名前が付いたコンストラクタがあります。いずれも同一で簡単なインターフェイスのあるハッシュオブジェクトを返します。例えば、SHA-256 ハッシュオブジェクトを作るには sha256() を使います。このオブジェクトには update() メソッドを用いて bytes-like オブジェクト (通常 bytes) を渡すことができます。digest() や hexdigest() メソッドを用いて、それまでに渡したデータを連結したものの digest をいつでも要求することができます。

注釈

マルチスレッドにおける良好なパフォーマンスを得るために、オブジェクトの生成時または更新時に与えるデータが 2047 バイトを超えている場合、Python GIL が解除されます。

注釈

文字列オブジェクトを update() に渡すのはサポートされていません。ハッシュはバイトには機能しますが、文字には機能しないからです。

このモジュールで常に使用できるハッシュアルゴリズムのコンストラクタは sha1()、 sha224()、 sha256()、 sha384()、 sha512()、 blake2b()、 および blake2s() です。 通常は md5() も使用できますが、もしあなたが珍しいFIPS準拠のPythonビルドを使用しているのであれば、md5() は使用できないでしょう。 Pythonがプラットフォームで利用しているOpenSSLライブラリによっては、追加のアルゴリズムが利用できます。多くのプラットフォームでは sha3_224`や :func:`sha3_256()、 sha3_384()、 sha3_512()、 shake_128()、 shake_256() も利用できます。

バージョン 3.6 で追加: SHA3 (Keccak) ならびに SHAKE コンストラクタ sha3_224(), sha3_256(), sha3_384(), sha3_512(), shake_128(), shake_256()。

バージョン 3.6 で追加: blake2b() と blake2s() が追加されました。

たとえば、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.digest_size
32
>>> m.block_size
64

もっと簡潔に書くと、このようになります:

>>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
hashlib.new(name[, data])

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. The named constructors are much faster than new() and should be preferred.

new() にOpenSSLのアルゴリズムを指定する例です:

>>> h = hashlib.new('ripemd160')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'

Hashlib は以下の定数属性を提供しています:

hashlib.algorithms_guaranteed

このモジュールによってすべてのプラットフォームでサポートされていることが保証されるハッシュアルゴリズムの名前を含む集合です。一部のアップストリームのベンダーが提供する奇妙な "FIPS準拠の" Pythonビルドではmd5のサポートを除外していますが、その場合であっても 'md5' がリストに含まれることに注意してください。

バージョン 3.2 で追加.

hashlib.algorithms_available

実行中の Python インタープリタで利用可能なハッシュアルゴリズム名の set です。これらの名前は new() に渡すことができます。algorithms_guaranteed は常にサブセットです。この set の中に同じアルゴリズムが違う名前で複数回現れることがあります (OpenSSL 由来)。

バージョン 3.2 で追加.

コンストラクタが返すハッシュオブジェクトには、次のような定数属性が用意されています:

hash.digest_size

生成されたハッシュのバイト数。

hash.block_size

内部で使われるハッシュアルゴリズムのブロックのバイト数。

ハッシュオブジェクトには次のような属性があります:

hash.name

このハッシュの正規名です。常に小文字で、new() の引数として渡してこのタイプの別のハッシュを生成することができます。

バージョン 3.4 で変更: name 属性は CPython には最初からありましたが、Python 3.4 までは正式に明記されていませんでした。そのため、プラットフォームによっては存在しないかもしれません。

ハッシュオブジェクトには次のようなメソッドがあります:

hash.update(data)

Update the hash object with the bytes-like object. Repeated calls are equivalent to a single call with the concatenation of all the arguments: m.update(a); m.update(b) is equivalent to m.update(a+b).

バージョン 3.1 で変更: ハッシュアルゴリズムが OpenSSL によって提供されていて、データが 2047 バイトを超えている場合には、ハッシュの更新が実行中でも他のスレッドが実行できるように、Python GIL が解放されます。

hash.digest()

これまで update() メソッドに渡されたデータのダイジェスト値を返します。これは digest_size と同じ長さの、0 から 255 の範囲全てを含み得るバイトの列です。

hash.hexdigest()

digest() と似ていますが、倍の長さの、16進形式文字列を返します。これは、電子メールなどの非バイナリ環境で値を交換する場合に便利です。

hash.copy()

ハッシュオブジェクトのコピー ("クローン") を返します。これは、最初の部分文字列が共通なデータのダイジェストを効率的に計算するために使用します。

SHAKE 可変長ダイジェスト

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)

digest() と似ていますが、倍の長さの、16進形式文字列を返します。これは、電子メールなどの非バイナリ環境で値を交換する場合に便利です。

鍵導出

鍵の導出 (derivation) と引き伸ばし (stretching) のアルゴリズムはセキュアなパスワードのハッシュ化のために設計されました。 sha1(password) のような甘いアルゴリズムは、ブルートフォース攻撃に抵抗できません。良いパスワードハッシュ化は調節可能で、遅くて、 salt を含まなければなりません。

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 バイトかそれ以上のバイト列にするべきです。

iterations 数はハッシュアルゴリズムと計算機の能力に基づいて決めるべきです。2013 年現在の場合、 SHA-256 に対して最低でも 100,000 反復が推奨されています。

dklen は、導出された鍵の長さです。 dklen が None の場合、ハッシュアルゴリズム hash_name のダイジェストサイズが使われます。例えば SHA-512 では 64 です。

>>> import hashlib, binascii
>>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
>>> binascii.hexlify(dk)
b'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5'

バージョン 3.4 で追加.

注釈

pbkdf2_hmac の高速な実装は OpenSSL 使用版で利用可能です。Python 実装は hmac のインラインバージョンを使います。それはおよそ 3 倍遅く、GIL を解放しません。

hashlib.scrypt(password, *, salt, n, r, p, maxmem=0, dklen=64)

この関数は、 RFC 7914 で定義されるscrypt のパスワードに基づいた鍵導出関数を提供します。

password and salt must be bytes-like objects. Applications and libraries should limit password to a sensible length (e.g. 1024). salt should be about 16 or more bytes from a proper source, e.g. os.urandom().

n is the CPU/Memory cost factor, r the block size, p parallelization factor and maxmem limits memory (OpenSSL 1.1.0 defaults to 32 MiB). dklen is the length of the derived key.

Availability: OpenSSL 1.1+.

バージョン 3.6 で追加.

BLAKE2

BLAKE2 is a cryptographic hash function defined in RFC 7693 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), salted hashing, personalization, and tree hashing.

このモジュールのハッシュオブジェクトは標準ライブラリーの hashlib オブジェクトの API に従います。

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

New hash objects are created by calling constructor functions:

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

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: size of output digest in bytes.
  • 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 で利用できます。

Constructor functions also accept the following tree hashing parameters:

  • fanout: fanout (0 to 255, 0 if unlimited, 1 in sequential mode).
  • depth: maximal depth of tree (1 to 255, 255 if unlimited, 1 in sequential mode).
  • 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).
Explanation of tree mode parameters.

See section 2.10 in BLAKE2 specification for comprehensive review of tree hashing.

定数

blake2b.SALT_SIZE
blake2s.SALT_SIZE

Salt length (maximum length accepted by constructors).

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 has configurable size of digests up to 64 bytes for BLAKE2b and up to 32 bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without changing the size of output, we can tell BLAKE2b to produce 20-byte digests:

>>> 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 (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")

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 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, 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 は*Jean-Philippe Aumasson*、 Luca Henzen、 Willi Meier そして Raphael C.-W. Phan によって作成された SHA-3 の最終候補である BLAKE を元に、Jean-Philippe Aumasson、 Samuel Neves、 Zooko Wilcox-O'Hearn, そして Christian Winnerlein によって設計されました。

それは、 Daniel J. Bernstein によって設計されたChaCha 暗号由来のアルゴリズムを用いています。

標準ライブラリは pyblake2 モジュールを基礎として実装されています。 このモジュールは Dmitry Chestnykh によって、Samuel Neves が作成した C実装を元に書かれました。 このドキュメントは、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://blake2.net
BLAKE2 の公式ウェブサイト
https://csrc.nist.gov/csrc/media/publications/fips/180/2/archive/2002-08-01/documents/fips180-2.pdf
FIPS 180-2 のセキュアハッシュアルゴリズムについての説明。
https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_algorithms (日本語版: https://暗号学的ハッシュ関数)
どのアルゴリズムにどんな既知の問題があって、それが実際に利用する際にどう影響するかについての Wikipedia の記事。
https://www.ietf.org/rfc/rfc2898.txt
PKCS #5: Password-Based Cryptography Specification Version 2.0

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 暗号関連のサービス »


hmac --- メッセージ認証のための鍵付きハッシュ化

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 暗号関連のサービス »

hmac --- メッセージ認証のための鍵付きハッシュ化

ソースコード: Lib/hmac.py

このモジュールでは RFC 2104 で記述されている HMAC アルゴリズムを実装しています。

hmac.new(key, msg=None, digestmod=None)

新しい hmac オブジェクトを返します。 key は秘密鍵を与える bytes または bytearray オブジェクトです。msg が与えられると、update(msg) が呼び出されます。digestmod は利用するダイジェスト名、ダイジェストコンストラクターまたは HMAC オブジェクトのモジュールです。hashlib.new() に与えることができる任意の名前をサポートし、デフォルトは hashlib.md5 のコンストラクターです。

バージョン 3.4 で変更: 引数 key に bytes または bytearray オブジェクトを渡せるようになりました。引数 msg に hashlib がサポートする全てのタイプを渡せるようになりました。引数 digestmod にハッシュアルゴリズム名を渡せるようになりました。

Deprecated since version 3.4, will be removed in version 3.8: MD5 が digestmod の暗黙のデフォルトダイジェストとなるのは廃止予定です。

hmac.digest(key, msg, digest)

Return digest of msg for given secret key and digest. The function is equivalent to HMAC(key, msg, digest).digest(), but uses an optimized C or inline implementation, which is faster for messages that fit into memory. The parameters key, msg, and digest have the same meaning as in new().

CPython implementation detail, the optimized C implementation is only used when digest is a string and name of a digest algorithm, which is supported by OpenSSL.

バージョン 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 文字が含まれることがあります。

警告

digest() の出力結果と外部から供給されたダイジェストを検証ルーチン内で比較しようとするのであれば、タイミング攻撃への脆弱性を減らすために、 == 演算子ではなく compare_digest() を使うことをお奨めします。

HMAC.hexdigest()

digest() と似ていますが、返される文字列は倍の長さとなり、16進形式となります。これは、電子メールなどの非バイナリ環境で値を交換する場合に便利です。

警告

hexdigest() の出力結果と外部から供給されたダイジェストを検証ルーチン内で比較しようとするのであれば、タイミング攻撃への脆弱性を減らすために、 == 演算子ではなく compare_digest() を使うことをお奨めします。

HMAC.copy()

hmac オブジェクトのコピー ("クローン") を返します。このコピーは最初の部分文字列が共通になっている文字列のダイジェスト値を効率よく計算するために使うことができます。

ハッシュオブジェクトには次のような属性があります:

HMAC.digest_size

生成された HMAC ダイジェストのバイト数。

HMAC.block_size

内部で使われるハッシュアルゴリズムのブロックのバイト数。

バージョン 3.4 で追加.

HMAC.name

このHMAC の正規名で、例えば hmac-md5 のように常に小文字です。

バージョン 3.4 で追加.

このモジュールは以下のヘルパ関数も提供しています:

hmac.compare_digest(a, b)

a == b を返します。この関数は、内容ベースの短絡的な振る舞いを避けることによってタイミング分析を防ぐよう設計されたアプローチを用い、暗号化に用いるのに相応しいものとしています。 a と b は両方が同じ型でなければなりません: (例えば HMAC.hexdigest() が返したような ASCII のみの) str または bytes-like object のどちらか一方。

注釈

a と b が異なる長さであったりエラーが発生した場合には、タイミング攻撃で理論上 a と b の型と長さについての情報が暴露されますが、その値は明らかになりません。

バージョン 3.3 で追加.

参考

hashlib モジュール
セキュアハッシュ関数を提供する Python モジュールです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 暗号関連のサービス »


secrets --- 機密を扱うために安全な乱数を生成する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 暗号関連のサービス »

secrets --- 機密を扱うために安全な乱数を生成する

バージョン 3.6 で追加.

ソースコード: Lib/secrets.py

secrets モジュールを使って、パスワードやアカウント認証、セキュリティトークンなどの機密を扱うのに適した、暗号学的に強い乱数を生成することができます。

特に、 random モジュールのデフォルトの擬似乱数よりも secrets を使用するべきです。 random モジュールはモデル化やシミュレーション向けで、セキュリティや暗号学的に設計されてはいません。

参考

PEP 506

乱数

secrets モジュールは OS が提供する最も安全な乱雑性のソースへのアクセスを提供します。

class secrets.SystemRandom

OS が提供する最も高品質なソースを用いて乱数を生成するためのクラスです。更に詳しいことについては random.SystemRandom を参照してください。

secrets.choice(sequence)

空でないシーケンスから要素をランダムに選択して返します。

secrets.randbelow(n)

[0, n) のランダムな整数を返します。

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'

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

総当たり攻撃 に耐えるには、トークンは十分にランダムでなければなりません。残念なことに、コンピュータの性能が向上し、より短時間により多くの推測ができるようになるにつれ、十分とされるランダムさというのは必然的に増えます。2015 年の時点で、secrets モジュールに想定される通常の用途では、32 バイト (256 ビット) のランダムさは十分と考えられています。

独自の長さのトークンを扱いたい場合、様々な token_* 関数に int 引数で渡すことで、トークンに使用するランダムさを明示的に指定することができます。引数はランダムさのバイト数として使用されます。

それ以外の場合、すなわち引数がない場合や None の場合、token_* 関数は妥当なデフォルト値を代わりに使います。

注釈

デフォルトはメンテナンスリリースの間を含め、いつでも変更される可能性があります。

その他の関数

secrets.compare_digest(a, b)

Return True if strings a and b are equal, otherwise False, in such a way as to reduce the risk of timing attacks. See hmac.compare_digest() for additional details.

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

この節では secrets を使用してセキュリティの基礎的なレベルを扱う際のレシピとベストプラクティスを説明します。

8文字のアルファベットと数字を含むパスワードを生成するには:

import string
alphabet = string.ascii_letters + string.digits
password = ''.join(choice(alphabet) for i in range(8))

注釈

アプリケーションは、平文であろうと暗号化されていようと、復元可能な形式でパスワードを保存 してはいけません。パスワードは暗号学的に強い一方向 (非可逆) ハッシュ関数を用いてソルトしハッシュしなければなりません。

アルファべットと数字からなり、小文字を少なくとも1つと数字を少なくとも3つ含む、10文字のパスワードを生成するには:

import string
alphabet = string.ascii_letters + string.digits
while True:
    password = ''.join(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

Generate an XKCD-style passphrase:

# 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(choice(words) for i in range(4))

パスワードの復元用途に適したセキュリティトークンを含む、推測しにくい一時 URL を生成するには:

url = 'https://mydomain.com/reset=' + token_urlsafe()

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 暗号関連のサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

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

本章に記述されたモジュールは、ファイルの取り扱いや時間計測のような (ほぼ)すべてのオペレーティングシステムで利用可能な機能にインタフェースを提供します。これらのインタフェースは、Unix もしくは C のインタフェースを基に作られますが、ほとんどの他のシステムで同様に利用可能です。概要を以下に記述します:

  • os --- 雑多なオペレーティングシステムインタフェース
    • ファイル名、コマンドライン引数、および環境変数
    • プロセスのパラメーター
    • ファイルオブジェクトの生成
    • ファイル記述子の操作
      • ターミナルのサイズの問い合わせ
      • ファイル記述子の継承
    • ファイルとディレクトリ
      • Linux 拡張属性
    • プロセス管理
    • スケジューラーへのインターフェイス
    • 雑多なシステム情報
    • 乱数
  • io --- ストリームを扱うコアツール
    • 概要
      • テキスト I/O
      • バイナリ I/O
      • Raw I/O
    • 高水準のモジュールインターフェイス
      • インメモリー ストリーム
    • クラス階層
      • I/O 基底クラス
      • 生ファイルI/O
      • バッファ付きストリーム
      • テキスト I/O
    • 性能
      • バイナリ I/O
      • テキスト I/O
      • マルチスレッディング
      • リエントラント性
  • time --- 時刻データへのアクセスと変換
    • 関数
    • Clock ID Constants
    • Timezone Constants
  • argparse --- コマンドラインオプション、引数、サブコマンドのパーサー
    • 使用例
      • パーサーを作る
      • 引数を追加する
      • 引数を解析する
    • ArgumentParser オブジェクト
      • prog
      • usage
      • description
      • epilog
      • parents
      • formatter_class
      • prefix_chars
      • fromfile_prefix_chars
      • argument_default
      • allow_abbrev
      • conflict_handler
      • add_help
    • add_argument() メソッド
      • name または flags
      • action
      • nargs
      • const
      • default
      • type
      • choices
      • required
      • help
      • metavar
      • dest
      • Action クラス
    • parse_args() メソッド
      • オプション値の文法
      • 不正な引数
      • - を含む引数
      • 引数の短縮形 (先頭文字でのマッチング)
      • sys.argv 以外
      • Namespace オブジェクト
    • その他のユーティリティ
      • サブコマンド
      • FileType オブジェクト
      • 引数グループ
      • 相互排他
      • パーサーのデフォルト値
      • ヘルプの表示
      • 部分解析
      • ファイル解析のカスタマイズ
      • 終了メソッド
      • Intermixed parsing
    • optparse からのアップグレード
  • getopt --- C 言語スタイルのコマンドラインオプションパーサ
  • logging --- Python 用ロギング機能
    • ロガーオブジェクト
    • ロギングレベル
    • ハンドラオブジェクト
    • フォーマッタオブジェクト
    • フィルタオブジェクト
    • LogRecord オブジェクト
    • LogRecord 属性
    • LoggerAdapter オブジェクト
    • スレッドセーフ性
    • モジュールレベルの関数
    • モジュールレベル属性
    • warnings モジュールとの統合
  • logging.config --- ロギングの環境設定
    • 環境設定のための関数
    • 環境設定辞書スキーマ
      • 辞書スキーマの詳細
      • 増分設定
      • オブジェクトの接続
      • ユーザ定義オブジェクト
      • 外部オブジェクトへのアクセス
      • 内部オブジェクトへのアクセス
      • インポート解決とカスタムインポーター
    • 環境設定ファイルの書式
  • logging.handlers --- ロギングハンドラ
    • StreamHandler
    • FileHandler
    • NullHandler
    • WatchedFileHandler
    • BaseRotatingHandler
    • RotatingFileHandler
    • TimedRotatingFileHandler
    • SocketHandler
    • DatagramHandler
    • SysLogHandler
    • NTEventLogHandler
    • SMTPHandler
    • MemoryHandler
    • HTTPHandler
    • QueueHandler
    • QueueListener
  • getpass --- 可搬性のあるパスワード入力機構
  • curses --- 文字セル表示を扱うための端末操作
    • 関数
    • Window オブジェクト
    • 定数
  • curses.textpad --- curses プログラムのためのテキスト入力ウィジェット
    • Textbox オブジェクト
  • curses.ascii --- ASCII 文字に関するユーティリティ
  • curses.panel --- curses のためのパネルスタック拡張
    • 関数
    • Panel オブジェクト
  • platform --- 実行中プラットフォームの固有情報を参照する
    • クロスプラットフォーム
    • Java プラットフォーム
    • Windows プラットフォーム
      • Win95/98 固有
    • Mac OS プラットフォーム
    • Unix プラットフォーム
  • errno --- 標準の errno システムシンボル
  • ctypes --- Pythonのための外部関数ライブラリ
    • ctypesチュートリアル
      • 動的リンクライブラリをロードする
      • ロードしたdllから関数にアクセスする
      • 関数を呼び出す
      • 基本データ型
      • 続・関数を呼び出す
      • 自作のデータ型とともに関数を呼び出す
      • 要求される引数の型を指定する (関数プロトタイプ)
      • 戻り値の型
      • ポインタを渡す(または、パラメータの参照渡し)
      • 構造体と共用体
      • 構造体/共用体アライメントとバイトオーダー
      • 構造体と共用体におけるビットフィールド
      • 配列
      • ポインタ
      • 型変換
      • 不完全型
      • コールバック関数
      • dllからエクスポートされた値へアクセスする
      • びっくり仰天
      • 可変サイズのデータ型
    • ctypesリファレンス
      • 共有ライブラリを見つける
      • 共有ライブラリをロードする
      • 外部関数
      • 関数プロトタイプ
      • ユーティリティー関数
      • データ型
      • 基本データ型
      • 構造化データ型
      • 配列とポインタ

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


os --- 雑多なオペレーティングシステムインタフェース

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

os --- 雑多なオペレーティングシステムインタフェース

ソースコード: Lib/os.py

このモジュールは、 OS 依存の機能を利用するポータブルな方法を提供します。単純なファイルの読み書きについては、 open() を参照してください。パス操作については、 os.path モジュールを参照してください。コマンドラインに与えられたすべてのファイルから行を読み込んでいくには、 fileinput モジュールを参照してください。一時ファイルや一時ディレクトリの作成については、 tempfile モジュールを参照してください。高水準のファイルとディレクトリの操作については、 shutil モジュールを参照してください。

利用可能性に関する注意 :

  • Python の、すべての OS 依存モジュールの設計方針は、可能な限り同一のインタフェースで同一の機能を利用できるようにする、というものです。例えば、 os.stat(path) は path に関する stat 情報を、 (POSIX を元にした ) 同じフォーマットで返します。
  • 特定のオペレーティングシステム固有の拡張も os を介して利用することができますが、これらの利用はもちろん、可搬性を脅かします。
  • パスやファイル名を受け付けるすべての関数は、バイト列型および文字列型両方のオブジェクトを受け付け、パスやファイル名を返す時は、同じ型のオブジェクトを返します。

注釈

このモジュール内のすべての関数は、間違った、あるいはアクセス出来ないファイル名やファイルパス、その他型が合っていても OS が受理しない引数に対して、 OSError を送出します。

exception os.error

組み込みの OSError 例外に対するエイリアスです。

os.name

import されているオペレーティングシステムに依存するモジュールの名前です。現在次の名前が登録されています: 'posix', 'nt', 'java'。

参考

sys.platform はより細かな粒度を持っています。 os.uname() はシステム依存のバージョン情報を提供します。

platform モジュールはシステムの詳細な識別情報をチェックする機能を提供しています。

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

Python では、ファイル名、コマンドライン引数、および環境変数を表すのに文字列型を使用します。一部のシステムでは、これらをオペレーティングシステムに渡す前に、文字列からバイト列へ、またはその逆のデコードが必要です。Python はこの変換を行うためにファイルシステムのエンコーディングを使用します (sys.getfilesystemencoding() 参照)。

バージョン 3.1 で変更: 一部のシステムでは、ファイルシステムのエンコーディングを使用して変換すると失敗する場合があります。この場合、Python は surrogateescape エンコーディングエラーハンドラー を使用します。これは、デコード時にデコードできないバイト列は Unicode 文字 U+DCxx に置き換えられ、それらはエンコード時に再び元のバイト列に変換されることを意味します。

ファイルシステムのエンコーディングでは、すべてが 128 バイト以下に正常にデコードされることが保証されなくてはなりません。ファイルシステムのエンコーディングでこれが保証されなかった場合は、API 関数が UnicodeError を送出します。

プロセスのパラメーター

これらの関数とデータアイテムは、現在のプロセスおよびユーザーに対する情報提供および操作のための機能を提供しています。

os.ctermid()

プロセスの制御端末に対応するファイル名を返します。

利用可能な環境: Unix。

os.environ

文字列の環境を表す マップ型 オブジェクトです。例えば、 environ['HOME'] は (一部のプラットフォームでは) ホームディレクトリのパス名であり、 C における getenv("HOME") と等価です。

このマップ型の内容は、 os モジュールの最初の import の時点、通常は Python の起動時に site.py が処理される中で取り込まれます。それ以後に変更された環境変数は os.environ を直接変更しない限り os.environ には反映されません。

プラットフォーム上で putenv() がサポートされている場合、このマップ型オブジェクトは環境変数に対する変更に使うこともできます。 putenv() はマップ型オブジェクトが修正される時に、自動的に呼ばれることになります。

Unix では、キーと値に sys.getfilesystemencoding()、エラーハンドラーに 'surrogateescape' を使用します。異なるエンコーディングを使用したい場合は environb を使用します。

注釈

putenv() を直接呼び出しても os.environ の内容は変わらないので、 os.environ を直接変更する方が良いです。

注釈

FreeBSD と Mac OS X を含む一部のプラットフォームでは、 environ の値を変更するとメモリリークの原因になる場合があります。システムの putenv() に関するドキュメントを参照してください。

putenv() が提供されていない場合、このマップ型オブジェクトに変更を加えたコピーを適切なプロセス生成機能に渡すことで、生成された子プロセスが変更された環境変数を利用するようにできます。

プラットフォームが unsetenv() 関数をサポートしている場合、このマップ型オブジェクトからアイテムを削除することで環境変数を消すことができます。 unsetenv() は os.environ からアイテムが取り除かれた時に自動的に呼ばれます。 pop() または clear() が呼ばれた時も同様です。

os.environb

environ のバイト列版です。環境変数をバイト文字列で表す マップ型 オブジェクトです。environ と environb は同期されます。(environb を変更すると environ が更新され、逆の場合も同様に更新されます)。

environb は supports_bytes_environ が True の場合のみ利用可能です。

バージョン 3.2 で追加.

os.chdir(path)
os.fchdir(fd)
os.getcwd()

これらの関数は、 ファイルとディレクトリ 節で説明されています。

os.fsencode(filename)

Encode path-like filename to the filesystem encoding with 'surrogateescape' error handler, or 'strict' on Windows; return bytes unchanged.

fsdecode() はこの逆変換を行う関数です。

バージョン 3.2 で追加.

バージョン 3.6 で変更: os.PathLike インタフェースを実装したオブジェクトを受け入れるようになりました。

os.fsdecode(filename)

Decode the path-like filename from the filesystem encoding with 'surrogateescape' error handler, or 'strict' on Windows; return str unchanged.

fsencode() はこの逆変換を行う関数です。

バージョン 3.2 で追加.

バージョン 3.6 で変更: os.PathLike インタフェースを実装したオブジェクトを受け入れるようになりました。

os.fspath(path)

path のファイルシステム表現を返します。

もし str か bytes: のオブジェクトが渡された場合は、変更せずにそのまま返します。さもなければ、 :meth:`~os.PathLike.__fspath__ が呼び出され、その戻り値が str か bytes のオブジェクトであれば、その値を返します。他のすべてのケースでは TypeError が送出されます。

バージョン 3.6 で追加.

class os.PathLike

ファイルシステムパスを表すオブジェクト(例: pathlib.PurePath) 向けの abstract base class です。

バージョン 3.6 で追加.

abstractmethod __fspath__()

このオブジェクトが表現するファイルシステムパスを返します。

このメソッドは str か bytes のオブジェクトのみを返す必要があります(str が好まれます)。

os.getenv(key, default=None)

環境変数 key が存在すればその値を返し、存在しなければ default を返します。key、default、および返り値は文字列です。

Unix では、キーと値は sys.getfilesystemencoding()、エラーハンドラー 'surrogateescape' でデコードされます。異なるエンコーディングを使用したい場合は os.getenvb() を使用します。

Availability: most flavors of Unix, Windows.

os.getenvb(key, default=None)

環境変数 key が存在すればその値を返し、存在しなければ default を返します。key、default、および返り値はバイト列型です。

getenvb() は supports_bytes_environ が True の場合のみ利用可能です。

Availability: most flavors of Unix.

バージョン 3.2 で追加.

os.get_exec_path(env=None)

プロセスを起動する時に名前付き実行ファイルを検索するディレクトリのリストを返します。 env が指定されると、それを環境変数の辞書とみなし、その辞書からキー PATH の値を探します。 デフォルトでは env は None であり、environ が使用されます。

バージョン 3.2 で追加.

os.getegid()

現在のプロセスの実効グループ id を返します。この id は現在のプロセスで実行されているファイルの "set id" ビットに対応します。

利用可能な環境: Unix。

os.geteuid()

現在のプロセスの実効ユーザー id を返します。

利用可能な環境: Unix。

os.getgid()

現在のプロセスの実グループ id を返します。

利用可能な環境: Unix。

os.getgrouplist(user, group)

user が所属するグループ id のリストを返します。group がリストにない場合、それを追加します。通常、group にはユーザー user のパスワードレコードに書かれているグループ ID を指定します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.getgroups()

現在のプロセスに関連付けられた従属グループ id のリストを返します。

利用可能な環境: Unix。

注釈

Mac OS X では getgroups() の挙動は他の Unix プラットフォームとはいくぶん異なります。 Python のインタープリタが 10.5 以前の Deployment Target でビルドされている場合、 getgroups() は現在のユーザープロセスに関連付けられている実効グループ id を返します。このリストはシステムで定義されたエントリ数 ( 通常は 16) に制限され、適切な特権があれば setgroups() の呼び出しによって変更することができます。 10.5 より新しい Deployment Target でビルドされている場合、 getgroups() はプロセスの実効ユーザー id に関連付けられたユーザーの現在のグループアクセスリストを返します。このグループアクセスリストは、プロセスのライフタイムで変更される可能性があり、 setgroups() の呼び出しの影響を受けず、長さ 16 の制限を受けません。 Deployment Target の値 MACOSX_DEPLOYMENT_TARGET は、 sysconfig.get_config_var() で取得することができます。

os.getlogin()

Return the name of the user logged in on the controlling terminal of the process. For most purposes, it is more useful to use getpass.getuser() since the latter checks the environment variables LOGNAME or USERNAME to find out who the user is, and falls back to pwd.getpwuid(os.getuid())[0] to get the login name of the current real user id.

Availability: Unix, Windows.

os.getpgid(pid)

プロセス id pid のプロセスのプロセスグループ id を返します。 pid が 0 の場合、現在のプロセスのプロセスグループ id を返します。

利用可能な環境: Unix。

os.getpgrp()

現在のプロセスグループの id を返します。

利用可能な環境: Unix。

os.getpid()

現在のプロセス id を返します。

os.getppid()

親プロセスのプロセス id を返します。親プロセスが終了していた場合、Unix では init プロセスの id (1) が返され、Windows では親のプロセス id だったもの (別のプロセスで再利用されているかもしれない) がそのまま返されます。

Availability: Unix, Windows.

バージョン 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 を (それぞれ) 意味します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.PRIO_PROCESS
os.PRIO_PGRP
os.PRIO_USER

getpriority() と setpriority() 用のパラメータです。

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.getresuid()

現在のプロセスの実ユーザー id 、実効ユーザー id 、および保存ユーザー id を示す、 (ruid, euid, suid) のタプルを返します。

利用可能な環境: Unix。

バージョン 3.2 で追加.

os.getresgid()

現在のプロセスの実グループ id 、実効グループ id 、および保存グループ id を示す、 (rgid, egid, sgid) のタプルを返します。

利用可能な環境: Unix。

バージョン 3.2 で追加.

os.getuid()

現在のプロセスの実ユーザー id を返します。

利用可能な環境: Unix。

os.initgroups(username, gid)

システムの initgroups() を呼び出し、指定された username がメンバーである全グループと gid で指定されたグループでグループアクセスリストを初期化します。

利用可能な環境: Unix。

バージョン 3.2 で追加.

os.putenv(key, value)

key という名前の環境変数に文字列 value を設定します。このような環境変数の変更は、os.system()、popen()、または fork() と execv() で起動されたサブプロセスに影響を与えます。

Availability: most flavors of Unix, Windows.

注釈

FreeBSD と Mac OS X を含む一部のプラットフォームでは、 environ の値を変更するとメモリリークの原因になる場合があります。システムの putenv に関するドキュメントを参照してください。

putenv() がサポートされている場合、 os.environ のアイテムに対する代入を行うと、自動的に putenv() の対応する呼び出しに変換されます。直接 putenv() を呼び出した場合 os.environ は更新されないため、実際には os.environ のアイテムに代入する方が望ましい操作です。

os.setegid(egid)

現在のプロセスに実効グループ id をセットします。

利用可能な環境: Unix。

os.seteuid(euid)

現在のプロセスに実効ユーザー id をセットします。

利用可能な環境: Unix。

os.setgid(gid)

現在のプロセスにグループ id をセットします。

利用可能な環境: Unix。

os.setgroups(groups)

現在のグループに関連付けられた従属グループ id のリストを groups に設定します。 groups はシーケンス型でなくてはならず、各要素はグループを特定する整数でなくてはなりません。通常、この操作はスーパユーザーしか利用できません。

利用可能な環境: Unix。

注釈

Mac OS X では、 groups の長さはシステムで定義された実効グループ id の最大数 ( 通常は 16) を超えない場合があります。 setgroups() 呼び出しで設定されたものと同じグループリストが返されないケースについては、 getgroups() のドキュメントを参照してください。

os.setpgrp()

システムコール setpgrp() か setpgrp(0, 0) のどちらか(実装されているもの)を呼び出します。機能については UNIX マニュアルを参照して下さい。

利用可能な環境: Unix。

os.setpgid(pid, pgrp)

システムコール setpgid() を呼び出してプロセス id pid のプロセスのプロセスグループ id を pgrp に設定します。この動作に関しては Unix のマニュアルを参照してください。

利用可能な環境: Unix。

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 です。小さい数値ほど優先されるスケジューリングとなります。

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.setregid(rgid, egid)

現在のプロセスの実グループ id および実効グループ id を設定します。

利用可能な環境: Unix。

os.setresgid(rgid, egid, sgid)

現在のプロセスの、実グループ id 、実効グループ id 、および保存グループ id を設定します。

利用可能な環境: Unix。

バージョン 3.2 で追加.

os.setresuid(ruid, euid, suid)

現在のプロセスの実ユーザー id 、実効ユーザー id 、および保存ユーザー id を設定します。

利用可能な環境: Unix。

バージョン 3.2 で追加.

os.setreuid(ruid, euid)

現在のプロセスの実ユーザー id および実効ユーザー id を設定します。

利用可能な環境: Unix。

os.getsid(pid)

getsid() システムコールを呼び出します。機能については Unix のマニュアルを参照してください。

利用可能な環境: Unix。

os.setsid()

setsid() システムコールを呼び出します。機能については Unix のマニュアルを参照してください。

利用可能な環境: Unix。

os.setuid(uid)

現在のプロセスのユーザー id を設定します。

利用可能な環境: Unix。

os.strerror(code)

エラーコード code に対応するエラーメッセージを返します。未知のエラーコードの対して strerror() が NULL を返すプラットフォームでは、 ValueError が送出されます。

os.supports_bytes_environ

環境のネイティブ OS タイプがバイト型の場合、 True です (例: Windows では、 False です)。

バージョン 3.2 で追加.

os.umask(mask)

現在の数値 umask を設定し、以前の umask 値を返します。

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()) でもかまいません。

Availability: recent flavors of Unix.

バージョン 3.3 で変更: 返り値の型が、タプルから属性名のついたタプルライクオブジェクトに変更されました。

os.unsetenv(key)

key という名前の環境変数を unset (削除) します。このような環境変数の変更は、os.system()、popen()、または fork() と execv() で起動されたサブプロセスに影響を与えます。

unsetenv() がサポートされている場合、 os.environ のアイテムの削除を行うと、自動的に unsetenv() の対応する呼び出しに変換されます。直接 unsetenv() を呼び出した場合 os.environ は更新されないため、実際には os.environ のアイテムを削除する方が望ましい操作です。

Availability: most flavors of Unix, Windows.

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

以下の関数は新しい ファイルオブジェクト を作成します。(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.device_encoding(fd)

fd に関連付けられたデバイスが端末 (ターミナル) に接続されている場合に、そのデバイスのエンコーディングを表す文字列を返します。端末に接続されていない場合、 None を返します。

os.dup(fd)

ファイル記述子 fd の複製を返します。新しいファイル記述子は 継承不可 です。

Windows では、標準ストリーム (0: 標準入力、1: 標準出力、2: 標準エラー出力) を複製する場合、新しいファイル記述子は 継承可能 です。

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

os.dup2(fd, fd2, inheritable=True)

Duplicate file descriptor fd to fd2, closing the latter first if necessary. Return fd2. The new file descriptor is inheritable by default or non-inheritable if inheritable is False.

バージョン 3.4 で変更: オプションの inheritable 引数が追加されました。

バージョン 3.7 で変更: Return fd2 on success. Previously, None was always returned.

os.fchmod(fd, mode)

fd で指定されたファイルのモードを mode に変更します。mode に指定できる値については、chmod() のドキュメントを参照してください。Python 3.3 以降では os.chmod(fd, mode) と等価です。

利用可能な環境: Unix。

os.fchown(fd, uid, gid)

fd で指定されたファイルの所有者 id およびグループ id を数値 uid および gid に変更します。いずれかの id を変更せずにおくにはその値として -1 を指定します。chown() を参照してください。Python 3.3 以降では os.chown(fd, uid, gid) と等価です。

利用可能な環境: Unix。

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)

ファイル記述子 fd を持つファイルのディスクへの書き込みを強制します。 Unix では、ネイティブの fsync() 関数を、 Windows では _commit() 関数を呼び出します。

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) と等価です。

Availability: Unix, Windows.

バージョン 3.5 で変更: Windows サポートを追加しました。

os.get_blocking(fd)

記述子のブロッキングモードを取得します。 O_NONBLOCK フラグが設定されている場合は False で、フラグがクリアされている場合は True です。

set_blocking() および socket.socket.setblocking() も参照してください。

利用可能な環境: Unix。

バージョン 3.5 で追加.

os.isatty(fd)

ファイル記述子 fd がオープンされていて、 tty (のような) デバイスに接続されている場合、 True を返します。そうでない場合は False を返します。

os.lockf(fd, cmd, len)

オープンされたファイル記述子に対して、POSIX ロックの適用、テスト、解除を行います。fd はオープンされたファイル記述子です。cmd には使用するコマンド (F_LOCK、F_TLOCK、F_ULOCK、あるいは F_TEST のいずれか一つ) を指定します。len にはロックするファイルのセクションを指定します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.F_LOCK
os.F_TLOCK
os.F_ULOCK
os.F_TEST

lockf() がとる動作を指定するフラグです。

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.lseek(fd, pos, how)

ファイル記述子 fd の現在の位置を pos に設定します。 pos の意味は how で次のように修飾されます。ファイルの先頭からの相対位置には SEEK_SET か 0 を、現在の位置からの相対位置には SEEK_CUR か 1 を、ファイルの末尾からの相対位置には SEEK_END か 2 を設定します。戻り値は、新しいカーソル位置のファイルの先頭からのバイト数です。

os.SEEK_SET
os.SEEK_CUR
os.SEEK_END

lseek() 関数に渡すパラメーター。値は順に 0, 1, 2 です。

バージョン 3.3 で追加: 一部のオペレーティングシステムは os.SEEK_HOLE や os.SEEK_DATA など、追加の値をサポートすることがあります。

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 パラメタで ディレクトリ記述子への相対パス をサポートしています。

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

注釈

この関数は低水準の I/O 向けのものです。 通常の利用では、組み込み関数 open() を使用してください。 open() は read() や write() (そしてさらに多くの) メソッドを持つ ファイルオブジェクト を返します。 ファイル記述子をファイルオブジェクトでラップするには fdopen() を使用してください。

バージョン 3.3 で追加: 引数 dir_fd が追加されました。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、この関数は InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

以下の定数は open() 関数の flags 引数に利用します。これらの定数は、ビット単位に OR 演算子 | で組み合わせることができます。一部、すべてのプラットフォームでは使用できない定数があります。利用可能かどうかや使い方については、Unix では open(2)、Windows では MSDN を参照してください。

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_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: some flavors of Unix.

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

os.pipe()

パイプを作成します。読み込み、書き込みに使うことの出来るファイル記述子のペア (r, w) を返します。新しいファイル記述子は 継承不可 です。

Availability: Unix, Windows.

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

os.pipe2(flags)

flags を設定したパイプをアトミックに作成します。flags には値 O_NONBLOCK と O_CLOEXEC を一つ以上論理和指定できます。読み込み、書き込みに使うことの出来るファイル記述子のペア (r, w) を返します。

Availability: some flavors of Unix.

バージョン 3.3 で追加.

os.posix_fallocate(fd, offset, len)

fd で指定されたファイルに対し、開始位置 offset から len バイト分割り当てるに十分なディスクスペースを確保します。

利用可能な環境: Unix。

バージョン 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。

バージョン 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。

バージョン 3.3 で追加.

os.pread(fd, n, offset)

Read at most n bytes from file descriptor fd at a position of offset, leaving the file offset unchanged.

Return a bytestring containing the bytes read. If the end of the file referred to by fd has been reached, an empty bytes object is returned.

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.preadv(fd, buffers, offset, flags=0)

Read from a file descriptor fd at a position of offset into mutable bytes-like objects buffers, leaving the file offset unchanged. Transfer data into each buffer until it is full and then move on to the next buffer in the sequence to hold the rest of the data.

The flags argument contains a bitwise OR of zero or more of the following flags:

  • RWF_HIPRI
  • RWF_NOWAIT

Return the total number of bytes actually read which can be less than the total capacity of all the objects.

The operating system may set a limit (sysconf() value 'SC_IOV_MAX') on the number of buffers that can be used.

Combine the functionality of os.readv() and os.pread().

Availability: Linux 2.6.30 and newer, FreeBSD 6.0 and newer, OpenBSD 2.7 and newer. Using flags requires Linux 4.6 or newer.

バージョン 3.7 で追加.

os.RWF_NOWAIT

Do not wait for data which is not immediately available. If this flag is specified, the system call will return instantly if it would have to read data from the backing storage or wait for a lock.

If some data was successfully read, it will return the number of bytes read. If no bytes were read, it will return -1 and set errno to errno.EAGAIN.

Availability: Linux 4.14 and newer.

バージョン 3.7 で追加.

os.RWF_HIPRI

High priority read/write. Allows block-based filesystems to use polling of the device, which provides lower latency, but may use additional resources.

Currently, on Linux, this feature is usable only on a file descriptor opened using the O_DIRECT flag.

Availability: Linux 4.6 and newer.

バージョン 3.7 で追加.

os.pwrite(fd, str, offset)

Write the bytestring in str to file descriptor fd at position of offset, leaving the file offset unchanged.

Return the number of bytes actually written.

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.pwritev(fd, buffers, offset, flags=0)

Write the buffers contents to file descriptor fd at a offset offset, leaving the file offset unchanged. buffers must be a sequence of bytes-like objects. Buffers are processed in array order. Entire contents of the first buffer is written before proceeding to the second, and so on.

The flags argument contains a bitwise OR of zero or more of the following flags:

  • RWF_DSYNC
  • RWF_SYNC

Return the total number of bytes actually written.

The operating system may set a limit (sysconf() value 'SC_IOV_MAX') on the number of buffers that can be used.

Combine the functionality of os.writev() and os.pwrite().

Availability: Linux 2.6.30 and newer, FreeBSD 6.0 and newer, OpenBSD 2.7 and newer. Using flags requires Linux 4.7 or newer.

バージョン 3.7 で追加.

os.RWF_DSYNC

Provide a per-write equivalent of the O_DSYNC open(2) flag. This flag effect applies only to the data range written by the system call.

Availability: Linux 4.7 and newer.

バージョン 3.7 で追加.

os.RWF_SYNC

Provide a per-write equivalent of the O_SYNC open(2) flag. This flag effect applies only to the data range written by the system call.

Availability: Linux 4.7 and newer.

バージョン 3.7 で追加.

os.read(fd, n)

Read at most n bytes from file descriptor fd.

Return a bytestring containing the bytes read. If the end of the file referred to by fd has been reached, an empty bytes object is returned.

注釈

この関数は低水準の I/O 向けのもので、 os.open() や pipe() が返すファイル記述子に対して使用されなければなりません。 組み込み関数 open() や popen() 、 fdopen() 、あるいは sys.stdin が返す "ファイルオブジェクト" を読み込むには、オブジェクトの read() か readline() メソッドを使用してください。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、この関数は InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

os.sendfile(out, in, offset, count)
os.sendfile(out, in, offset, count, [headers, ][trailers, ]flags=0)

ファイル記述子 in からファイル記述子 out への開始位置 offset へ count バイトコピーします。 送信バイト数を返します。 EOF に達した場合は 0 を返します。

前者の関数表記は sendfile() が定義されているすべてのプラットフォームでサポートされています。

Linux では、offset に None が与えられると、バイト列は in の現在の位置から読み込まれ、in の位置は更新されます。

後者は Mac OS X および FreeBSD で使用される場合があります。headers および trailers は任意のバッファのシーケンス型オブジェクトで、in からのデータが書き出される前と後に書き出されます。返り値は前者と同じです。

Mac OS X と FreeBSD では、count の値に 0 を指定すると、in の末尾に達するまで送信します。

全てのプラットフォームはソケットをファイル記述子 out としてサポートし、あるプラットフォームは他の種類 (例えば、通常のファイル、パイプ) も同様にサポートします。

クロスプラットフォームのアプリケーションは headers、trailers ならびに flags 引数を使用するべきではありません。

利用可能な環境: Unix。

注釈

sendfile() のより高水準のラッパについては socket.socket.sendfile() を参照してください。

バージョン 3.3 で追加.

os.set_blocking(fd, blocking)

指定されたファイル記述子のブロッキングモードを設定します。 ブロッキングが False の場合 O_NONBLOCK フラグを設定し、そうでない場合はクリアします。

get_blocking() および socket.socket.setblocking() も参照してください。

利用可能な環境: Unix。

バージョン 3.5 で追加.

os.SF_NODISKIO
os.SF_MNOWAIT
os.SF_SYNC

実装がサポートしている場合 sendfile() 関数に渡すパラメーターです。

利用可能な環境: Unix。

バージョン 3.3 で追加.

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.

Return the total number of bytes actually read which can be less than the total capacity of all the objects.

The operating system may set a limit (sysconf() value 'SC_IOV_MAX') on the number of buffers that can be used.

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.tcgetpgrp(fd)

fd (os.open() が返すオープンしたファイル記述子 ) で与えられる端末に関連付けられたプロセスグループを返します。

利用可能な環境: Unix。

os.tcsetpgrp(fd, pg)

fd (os.open() が返すオープンしたファイル記述子 ) で与えられる端末に関連付けられたプロセスグループを pg に設定します。

利用可能な環境: Unix。

os.ttyname(fd)

ファイル記述子 fd に関連付けられている端末デバイスを特定する文字列を返します。 fd が端末に関連付けられていない場合、例外が送出されます。

利用可能な環境: Unix。

os.write(fd, str)

Write the bytestring in str to file descriptor fd.

Return the number of bytes actually written.

注釈

この関数は低水準の I/O 向けのもので、 os.open() や pipe() が返すファイル記述子に対して使用しなければなりません。 組み込み関数 open() や popen() 、 fdopen() 、あるいは sys.stdout や sys.stderr が返す "ファイルオブジェクト" に書き込むには、オブジェクトの write() メソッドを使用してください。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、この関数は InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

os.writev(fd, buffers)

Write the contents of buffers to file descriptor fd. buffers must be a sequence of bytes-like objects. Buffers are processed in array order. Entire contents of the first buffer is written before proceeding to the second, and so on.

Returns the total number of bytes actually written.

The operating system may set a limit (sysconf() value 'SC_IOV_MAX') on the number of buffers that can be used.

利用可能な環境: Unix。

バージョン 3.3 で追加.

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

バージョン 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

ターミナルウィンドウの高さ (文字数) です。

ファイル記述子の継承

バージョン 3.4 で追加.

ファイル記述子には「継承可能 (inheritable)」フラグというものがあって、これにより子プロセスにファイル記述子が引き継がれるかどうかが決定されます。Python 3.4 より、 Python によって作成されるファイル記述子はデフォルトで継承不可 (non-inheritable) となりました。

UNIX の場合、継承不可のファイル記述子は新規プロセス実行時にクローズされ、そうでないファイル記述子は引き継がれます。

Windows の場合は、標準ストリームを除き、継承不可のハンドルと継承不可のファイル記述子は子プロセスでクローズされます。標準ストリーム (ファイル記述子の 0, 1, 2: 標準入力, 標準出力, 標準エラー出力) は常に引き継がれます。 spawn* 関数を使う場合、全ての継承可能なハンドルと全ての継承可能なファイル記述子は引き継がれます。 subprocess モジュールを使う場合、標準ストリームを除く全てのファイル記述子はクローズされ、継承可能なハンドルは close_fds 引数が False の場合にのみ引き継がれます。

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 プラットフォームでは、このセクションの関数の多くが以下の機能を一つ以上サポートしています。

  • ファイル記述子の指定: 一部の関数では、path 引数はパス名を示す文字列だけでなく、ファイル記述子でも指定できます。関数はファイル記述子が参照するファイルを操作します。(POSIX システムでは、Python は関数の f... バージョンを呼び出します)

    そのプラットフォーム上で path にファイル記述子を使用できるかどうかは、os.supports_fd で確認できます。使用できない場合 NotImplementedError が送出されます。

    その関数が引数に dir_fd または follow_symlinks もサポートしている場合、path にファイル記述子を指定した時にそれらのいずれかを指定するとエラーになります。

  • ディレクトリ記述子への相対パス: dir_fd が None ではない場合、そのファイル記述子はディレクトリを参照しているはずであり、操作するパスは相対パスであるべきです; パスはそのディレクトリへの相対パスになります。パスが絶対パスであった場合、dir_fd は無視されます。(POSIX システムでは、Python は関数の ...at または f...at バージョンを呼び出します)

    そのプラットフォーム上で 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) の 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 に設定します。

この関数は ファイル記述子の指定 をサポートしています。記述子は、オープンしているファイルではなく、オープンしているディレクトリを参照していなければなりません。

バージョン 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

この関数は シンボリックリンクをたどらない をサポートしています。

利用可能な環境: Unix。

バージョン 3.3 で追加: 引数 follow_symlinks を追加しました。

バージョン 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

この関数は ファイル記述子の指定 、 ディレクトリ記述子への相対パス 、および シンボリックリンクをたどらない をサポートしています。

注釈

Windows は chmod() をサポートしていますが、ファイルの読み出し専用フラグを (stat.S_IWRITE および stat.S_IREAD 定数または対応する整数値によって) 設定できるだけです。その他のビットはすべて無視されます。

バージョン 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() を参照してください。

利用可能な環境: Unix。

バージョン 3.3 で追加: path にオープンしているファイル記述子の指定のサポート、および引数 dir_fd と follow_symlinks を追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.chroot(path)

現在のプロセスのルートディレクトリを path に変更します。

利用可能な環境: Unix。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.fchdir(fd)

現在の作業ディレクトリをファイル記述子 fd が表すディレクトリに変更します。記述子はオープンしているファイルではなく、オープンしたディレクトリを参照していなければなりません。Python 3.3 以降では os.chdir(fd) と等価です。

利用可能な環境: Unix。

os.getcwd()

現在の作業ディレクトリを表す文字列を返します。

os.getcwdb()

現在の作業ディレクトリを表すバイト列を返します。

os.lchflags(path, flags)

path のフラグを数値 flags に設定します。chflags() に似ていますが、シンボリックリンクをたどりません。Python 3.3 以降では os.chflags(path, flags, follow_symlinks=False) と等価です。

利用可能な環境: Unix。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.lchmod(path, mode)

path のモードを数値 mode に変更します。パスがシンボリックリンクの場合はそのリンク先ではなくシンボリックリンクそのものに対して作用します。mode に指定できる値については chmod() のドキュメントを参照してください。Python 3.3 以降では os.chmod(path, mode, follow_symlinks=False) と等価です。

利用可能な環境: Unix。

バージョン 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) と等価です。

利用可能な環境: 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 の両方またはどちらかに対し ディレクトリ記述子への相対パス および シンボリックリンクをたどらない をサポートしています。

Availability: Unix, Windows.

バージョン 3.2 で変更: Windows サポートを追加しました。

バージョン 3.3 で追加: 引数 src_dir_fd、dst_dir_fd、および follow_symlinks を追加しました。

バージョン 3.6 で変更: src と dst が path-like object を受け付けるようになりました。

os.listdir(path='.')

path で指定されたディレクトリ内のエントリ名が入ったリストを返します。リスト内の順番は不定です。特殊エントリ '.' および '..' は、それらがディレクトリ内に存在してもリストには含められません。

path may be a path-like object. If path is of type bytes (directly or indirectly through the PathLike interface), the filenames returned will also be of type bytes; in all other circumstances, they will be of type str.

この関数は ファイル記述子の指定 もサポートしています; ファイル記述子はディレクトリを参照していなくてはなりません。

注釈

文字列型 のファイル名を バイト列型 にエンコードするには、fsencode() を使用します。

参考

ディレクトリエントリに加えてファイル属性情報も返す scandir() 関数の方が、多くの一般的な用途では使い勝手が良くなります。

バージョン 3.2 で変更: 引数 path は任意になりました。

バージョン 3.3 で追加: path にオープンしているファイル記述子の指定をサポートしました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.lstat(path, *, dir_fd=None)

与えられたパスに対して lstat() システムコールと同じ処理を行います。stat() と似ていますが、シンボリックリンクをたどりません。 stat_result オブジェクトを返します。

シンボリックリンクをサポートしていないプラットフォームでは 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 で変更: src と dst が path-like object を受け付けるようになりました。

os.mkdir(path, mode=0o777, *, dir_fd=None)

ディレクトリ path を数値モード mode で作成します。

すでにディレクトリが存在したら、 FileExistsError が上げられます。

いくつかのシステムにおいては mode は無視されます。それが使われる時には、最初に現在の umask 値でマスクされます。もし最後の 9 ビット (つまり mode の8進法表記の最後の3桁) を除いたビットが設定されていたら、それらの意味はプラットフォームに依存します。いくつかのプラットフォームではそれらは無視され、それらを設定するためには明示的に chmod() を呼ぶ必要があるでしょう。

この関数は ディレクトリ記述子への相対パス もサポートすることができます。

一時ディレクトリを作成することもできます : tempfile モジュールの tempfile.mkdtemp() 関数を参照してください。

バージョン 3.3 で追加: 引数 dir_fd が追加されました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

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 である場合、ターゲットのディレクトリが既に存在していれば OSError が送出されます。

注釈

作成するパス要素に pardir (UNIX では "..") が含まれる場合、makedirs() は混乱します。

この関数は UNC パスを正しく扱えるようになりました。

バージョン 3.2 で追加: 引数 exist_ok が追加されました。

バージョン 3.4.1 で変更: Python 3.4.1 より前、 exist_ok が True でそのディレクトリが既存の場合でも、 makedirs() は mode が既存ディレクトリのモードと合わない場合にはエラーにしようとしていました。このモードチェックの振る舞いを安全に実装することが出来なかったため、 Python 3.4.1 でこのチェックは削除されました。 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 をオープンしない --- 単にランデブーポイントを作成するだけ --- なので注意してください。

利用可能な環境: Unix。

バージョン 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() を使って) 定義し、それ以外の定数を指定した場合は無視されます。

この関数は ディレクトリ記述子への相対パス もサポートすることができます。

利用可能な環境: Unix。

バージョン 3.3 で追加: 引数 dir_fd が追加されました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.major(device)

RAW デバイス番号から、デバイスのメジャー番号を取り出します ( 通常 stat の st_dev か st_rdev フィールドです ) 。

os.minor(device)

RAW デバイス番号から、デバイスのマイナー番号を取り出します ( 通常 stat の st_dev か st_rdev フィールドです ) 。

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.

この関数は ディレクトリ記述子への相対パス もサポートすることができます。

Availability: Unix, Windows.

バージョン 3.2 で変更: Windows 6.0 (Vista) のシンボリックリンクをサポートしました。

バージョン 3.3 で追加: 引数 dir_fd が追加されました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.remove(path, *, dir_fd=None)

ファイル path を削除します。 path がディレクトリの場合、OSError が送出されます; ディレクトリの削除には rmdir() を使用してください。

この関数は ディレクトリ記述子への相対パス をサポートしています。

Windows では、使用中のファイルを削除しようとすると例外を送出します; Unixでは、ディレクトリエントリは削除されますが、記憶装置上に割り当てられたファイル領域は元のファイルが使われなくなるまで残されます。

この関数は意味論的に unlink() と同一です。

バージョン 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 が送出されます。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

ファイルまたはディレクトリ src の名前を dst へ変更します。dst がディレクトリの場合 OSError が送出されます。Unixでは、dst が存在し、かつファイルの場合、ユーザーの権限があるかぎり暗黙のうちに置き換えられます。この操作は、一部の Unix 系システムにおいて src と dst が異なるファイルシステム上にあると失敗することがあります。ファイル名の変更が成功する場合はアトミック操作となります (これは POSIX 要求仕様です)。Windows では、dst がすでに存在する場合には、たとえファイルの場合でも OSError が送出されます。

この関数は src_dir_fd と dst_dir_fd のどちらかまたは両方の指定に ディレクトリ記述子への相対パス をサポートしています。

対象の上書きがクロスプラットフォームになる場合は replace() を使用してください。

バージョン 3.3 で追加: 引数 src_dir_fd および dst_dir_fd が追加されました。

バージョン 3.6 で変更: src と dst が path-like object を受け付けるようになりました。

os.renames(old, new)

再帰的にディレクトリやファイル名を変更する関数です。 rename() のように動作しますが、新たなパス名を持つファイルを配置するために必要な途中のディレクトリ構造をまず作成しようと試みます。名前変更の後、元のファイル名のパス要素は removedirs() を使って右側から順に削除されます。

注釈

この関数はコピー元の末端のディレクトリまたはファイルを削除する権限がない場合には失敗します。

バージョン 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 のどちらかまたは両方の指定に ディレクトリ記述子への相対パス をサポートしています。

バージョン 3.3 で追加.

バージョン 3.6 で変更: src と dst が path-like object を受け付けるようになりました。

os.rmdir(path, *, dir_fd=None)

ディレクトリ path を削除します。ディレクトリが空の場合にだけ正常に動作します。そうでなければ OSError が送出されます。ディレクトリツリー全体を削除するには shutil.rmtree() を使います。

この関数は ディレクトリ記述子への相対パス をサポートしています。

バージョン 3.3 で追加: 引数 dir_fd が追加されました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.scandir(path='.')

path で指定されたディレクトリ内のエントリに対応する os.DirEntry オブジェクトのイテレータを返します。このエントリは、任意の順序で yield され、特殊エントリ '.' および '..' は含められません。

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.

この関数は ファイル記述子の指定 もサポートしています; ファイル記述子はディレクトリを参照していなくてはなりません。

scandir() イテレータは、 コンテキストマネージャ プロトコルをサポートし、次のメソッドを持ちます。

scandir.close()

イテレータを閉じ、獲得した資源を開放します。

この関数は、イテレータがすべて消費されるか、ガーベージコレクトされた、もしくはイテレート中にエラーが発生した際に自動的に呼び出されます。しかし、 with 文を用いるか、明示的に呼び出すことを推奨します。

バージョン 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() and readdir() functions. On Windows, it uses the Win32 FindFirstFileW and FindNextFileW functions.

バージョン 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 で変更: Added support for file descriptors on 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 は捕捉され送出されません。

stat(*, follow_symlinks=True)

この項目の stat_result オブジェクトを返します。このメソッドは、デフォルトでシンボリックリンクをたどります。シンボリックリンクを開始するには、 follow_symlinks=False 引数を追加します。

Unix では、このメソッドは常にシステムコールを必要とします。Windows では、 follow_symlinks が True かつ、項目がシンボリックリンクの場合にのみシステムコールが必要となります。

Windows では、stat_result の st_ino 、 st_dev 、 st_nlink 属性は常にゼロに設定されます。これらの属性を取得するには、 os.stat() を呼び出します。

結果は os.DirEntry オブジェクトにキャッシュされます。follow_symlinks が True の場合と False の場合とでは、別のオブジェクトにキャッシュされます。最新の情報を取得するには、 os.stat() を呼び出してください。

os.DirEntry と pathlib.Path では、いくつかの属性やメソッドがよい対応関係にあります。特に、 name 属性は同じ意味を持ちます。is_dir() 、 is_file() 、 is_symlink() 、 stat() メソッドも同じ意味を持ちます。

バージョン 3.5 で追加.

バージョン 3.6 で変更: PathLike インターフェースをサポートしました。Windowsで:class:bytes パスをサポートしました。

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() を利用してください。

この関数は ファイル記述子の指定 および シンボリックリンクをたどらない をサポートしています。

以下はプログラム例です:

>>> 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 で追加: dir_fd, follow_symlinks 引数の追加、ファイル記述子の指定の追加。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

class os.stat_result

おおむね stat 構造体のメンバーに対応する属性を持つオブジェクトです。os.stat() 、 os.fstat() 、 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 on Windows
st_dev

このファイルが存在するデバイスの識別子。

st_nlink

ハードリンクの数。

st_uid

ファイル所有者のユーザ識別子。

st_gid

ファイル所有者のグループ識別子。

st_size

ファイルが通常のファイルまたはシンボリックリンクの場合、そのファイルのバイト単位でのサイズです。シンボリックリンクのサイズは、含まれるパス名の長さで、null バイトで終わることはありません。

タイムスタンプ:

st_atime

秒で表した最終アクセス時刻。

st_mtime

秒で表した最終内容更新時刻。

st_ctime

プラットフォーム依存:

  • Unix ではメタデータの最終更新時刻
  • Windows では作成時刻、単位は秒
st_atime_ns

ナノ秒 (整数) で表した最終アクセス時刻。

st_mtime_ns

ナノ秒 (整数) で表した最終内容更新時刻。

st_ctime_ns

プラットフォーム依存:

  • Unix ではメタデータの最終更新時刻
  • Windows で、ナノ秒 (整数) で表した作成時刻。

注釈

st_atime 、 st_mtime 、および st_ctime 属性の厳密な意味や精度はオペレーティングシステムやファイルシステムによって変わります。例えば、 FAT や FAT32 ファイルシステムを使用している Windows システムでは、 st_mtime の精度は 2 秒であり、 st_atime の精度は 1 日に過ぎません。詳しくはお使いのオペレーティングシステムのドキュメントを参照してください。

同じように、st_atime_ns、st_mtime_ns、および st_ctime_ns は常にナノ秒で表されますが、多くのシステムではナノ秒単位の精度では提供していません。ナノ秒単位の精度を提供するシステムであっても、st_atime、st_mtime、および st_ctime についてはそれらが格納される浮動小数点オブジェクトがそのすべてを保持できず、それ自体が少々不正確です。正確なタイムスタンプが必要な場合は、st_atime_ns、st_mtime_ns、および st_ctime_ns を使用するべきです。

(Linux のような ) 一部の Unix システムでは、以下の属性が利用できる場合があります :

st_blocks

ファイルに対して割り当てられている 512 バイトのブロックの数です。ファイルにホール (hole) が含まれている場合、st_size/512 より小さくなる場合があります。

st_blksize

効率的なファイルシステム I/O のための「推奨される」ブロックサイズです。ファイルに、これより小さいチャンクで書き込むと、非効率的な読み込み、編集、再書き込みが起こる場合があります。

st_rdev

inode デバイスの場合デバイスタイプ

st_flags

ファイルのユーザ定義フラグ

他の (FreeBSD のような ) Unix システムでは、以下の属性が利用できる場合があります ( ただし root ユーザ以外が使うと値が入っていない場合があります ):

st_gen

ファイル生成番号

st_birthtime

ファイル作成時刻

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.

Mac OS システムでは、以下の属性も利用できる場合があります:

st_rsize

ファイルの実際のサイズ

st_creator

ファイルの作成者

st_type

ファイルタイプ

Windows システムでは以下の属性も利用できます:

st_file_attributes

Windows のファイルの属性。GetFileInformationByHandle() の返す BY_HANDLE_FILE_INFORMATION 構造の dwFileAttributes メンバーです。stat モジュールの FILE_ATTRIBUTE_* 定数を参照してください。

標準モジュール stat は stat 構造体からの情報の取り出しに役立つ関数と定数を定義しています。 (Windows では、一部のアイテムにダミー値が入ります )

後方互換性のため、stat_result インスタンスには、 stat 構造体の最も重要な (そして移植性の高い) メンバーを表す少なくとも 10 個の整数からなるタプルとしてもアクセス可能です。このタプルは、 st_mode、st_ino、st_dev、st_nlink、st_uid、st_gid、st_size、st_atime、st_mtime、st_ctime の順になります。実装によってはそれ以上のアイテムが末尾に追加されます。古いバージョンの Python との互換性のため、 stat_result にタプルとしてアクセスすると、常に整数を返します。

バージョン 3.3 で追加: st_atime_ns、st_mtime_ns、st_ctime_ns メンバが追加されました。

バージョン 3.5 で追加: Windows において st_file_attributes メンバが追加されました。

バージョン 3.5 で変更: Windows now returns the file index as st_ino when available.

バージョン 3.7 で追加: Added the st_fstype member to Solaris/derivatives.

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

os.supports_dir_fd

os モジュールのどの関数が dir_fd 引数の使用を許可するかを示す、Set オブジェクト。異なるプラットフォームでは、異なる機能を持ち、あるプラットフォームで動作するオプションが、別のプラットフォームでは動作しない場合があります。一貫性を保つため、 dir_fd をサポートする関数は常に引数の指定を許可しますが、機能が実際に使用できない場合には、例外を送出します。

特定の関数が dir_fd 引数の使用を許可しているかどうか確認するには、supports_dir_fd と in 演算子で比較します。例えば、以下の式では os.stat() の dir_fd 引数がローカルシステム上で利用できるかどうか確認できます:

os.stat in os.supports_dir_fd

現在 dir_fd 引数は Unix プラットフォームでのみ動作します。Windows で動作する関数はありません。

バージョン 3.3 で追加.

os.supports_effective_ids

os モジュールのどの関数が os.access() の effective_ids 引数の使用を許可するかを示す、Set オブジェクト。ローカルプラットフォームでサポートされている場合、このコレクションは os.access() を含みます。サポートされていない場合、空になります。

os.access() で effective_ids 引数が使用できるかどうか確認するには、以下のように supports_effective_ids に in 演算子を使用します:

os.access in os.supports_effective_ids

現在 effective_ids は Unix プラットフォームでのみが動作します。Windows では動作しません。

バージョン 3.3 で追加.

os.supports_fd

os モジュールのどの関数が、path 引数をオープンしているファイル記述子として指定するかを示す、Set オブジェクト。異なるプラットフォームでは、異なる機能を持ち、あるプラットフォームで動作するオプションが、別のプラットフォームでは動作しない場合があります。一貫性を保つため、 fd をサポートする関数は常に引数の指定を許可しますが、機能が実際に使用できない場合には、例外を送出します。

特定の関数が path 引数にオープンしているファイル記述子の指定を許可しているかどうか確認するには、supports_fd に in 演算子を使用します。例えば、以下の式では os.chdir() がローカルプラットフォーム上で呼び出された時にオープンしているファイル記述子を受け付けるかどうか確認できます:

os.chdir in os.supports_fd

バージョン 3.3 で追加.

os.supports_follow_symlinks

os モジュールのどの関数が follow_symlinks 引数の使用を許可するかを示す、Set オブジェクト。異なるプラットフォームでは、異なる機能を持ち、あるプラットフォームで動作するオプションが、別のプラットフォームでは動作しない場合があります。一貫性を保つため、 follow_symlinks をサポートする関数は常に引数の指定を許可しますが、機能が実際に使用できない場合には、例外を送出します。

特定の関数が follow_symlinks 引数をサポートしているかどうか確認するには、supports_follow_symlinks に in 演算子を使用します。例えば、以下の式では os.stat() がローカルシステム上で follow_symlinks 引数を利用できるかどうか確認できます:

os.stat in os.supports_follow_symlinks

バージョン 3.3 で追加.

os.symlink(src, dst, target_is_directory=False, *, dir_fd=None)

src を指し示すシンボリックリンク dst を作成します。

On Windows, a symlink represents either a file or a directory, and does not morph to the target dynamically. If the target is present, the type of the symlink will be created to match. Otherwise, the symlink will be created as a directory if target_is_directory is True or a file symlink (the default) otherwise. On non-Windows platforms, target_is_directory is ignored.

シンボリックリンクのサポートは Windows 6.0 (Vista) から導入されました。Windows がそれより古い場合 symlink() は NotImplementedError を送出します。

この関数は ディレクトリ記述子への相対パス をサポートしています。

注釈

Windowsでは、シンボリックリンクを作成するには特権 SeCreateSymbolicLinkPrivilege が必要です。この特権は通常一般ユーザーには与えられていませんが、管理者レベルに特権をエスカレートしたアカウントで利用できます。この特権を取得するか、アプリケーションを管理者として実行すると、シンボリックリンクを作成することができます。

この関数が特権を持たないユーザーに呼び出されると、OSError が送出されます。

Availability: Unix, Windows.

バージョン 3.2 で変更: Windows 6.0 (Vista) のシンボリックリンクをサポートしました。

バージョン 3.3 で追加: 引数 dir_fd が追加され、非 Windows プラットフォームでの target_is_directory 指定がサポートされました。

バージョン 3.6 で変更: src と dst が path-like object を受け付けるようになりました。

os.sync()

ディスクキャッシュのディスクへの書き出しを強制します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.truncate(path, length)

path に対応するファイルを、サイズが最大で length バイトになるよう切り詰めます。

この関数は ファイル記述子の指定 をサポートしています。

Availability: Unix, Windows.

バージョン 3.3 で追加.

バージョン 3.5 で変更: Windows サポートを追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.unlink(path, *, dir_fd=None)

ファイル path を削除します。意味上は remove() と等価です。 unlink の名前は伝統的な Unix の関数名です。詳細は 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 の両方にタプルが指定されるとエラーになります。

path にディレクトリを指定できるかどうかは、オペレーティングシステムがディレクトリをファイルとして実装しているかどうかによります (例えば Windows はそうではありません)。ここで設定した時刻が、後に stat() の呼び出し時正確に返されない場合があります。これはオペレーティングシステムが記録するアクセスおよび修正時刻の精度に依存しています; stat() を参照してください。正確な時刻を保持する最善の方法は、utime で ns 引数を指定し、os.stat() の返り値オブジェクトから st_atime_ns および st_mtime_ns フィールドを使用することです。

この関数は ファイル記述子の指定 、 ディレクトリ記述子への相対パス 、および シンボリックリンクをたどらない をサポートしています。

バージョン 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 は文字列で、ディレクトリへのパスです。 dirnames は dirpath 内のサブディレクトリ名のリスト ('.' と '..' は除く）です。 filenames は dirpath 内の非ディレクトリ・ファイル名のリストです。このリスト内の名前にはファイル名までのパスが含まれません。 dirpath 内のファイルやディレクトリへの (top からたどった ) フルパスを得るには、 os.path.join(dirpath, name) を使用してください。

オプション引数 topdown が True であるか、指定されなかった場合、各ディレクトリからタプルを生成した後で、サブディレクトリからタプルを生成します。 ( ディレクトリはトップダウンで生成 ) 。 topdown が False の場合、ディレクトリに対応するタプルは、そのディレクトリ以下の全てのサブディレクトリに対応するタプルの後で ( ボトムアップで ) 生成されます。 topdown の値によらず、サブディレクトリのリストは、ディレクトリとそのサブディレクトリのタプルを生成する前に取り出されます。

topdown が True のとき、呼び出し側は dirnames リストを、インプレースで ( たとえば、 del やスライスを使った代入で ) 変更でき、 walk() は dirnames に残っているサブディレクトリ内のみを再帰します。これにより、検索を省略したり、特定の訪問順序を強制したり、呼び出し側が walk() を再開する前に、呼び出し側が作った、または名前を変更したディレクトリを、 walk() に知らせたりすることができます。 topdown が False のときに dirnames を変更しても効果はありません。ボトムアップモードでは dirpath 自身が生成される前に dirnames 内のディレクトリの情報が生成されるからです。

By default, errors from the scandir() call are ignored. If optional argument onerror is specified, it should be a function; it will be called with one argument, an OSError instance. It can report the error to continue with the walk, or raise the exception to abort the walk. Note that the filename is available as the filename attribute of the exception object.

デフォルトでは、 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))

バージョン 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)

利用可能な環境: Unix。

バージョン 3.3 で追加.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.7 で変更: Added support for bytes paths.

Linux 拡張属性

バージョン 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.

この関数は ファイル記述子の指定 および シンボリックリンクをたどらない をサポートしています。

バージョン 3.6 で変更: path と attribute が path-like object を受け付けるようになりました。

os.listxattr(path=None, *, follow_symlinks=True)

path の拡張ファイルシステム属性のリストを返します。リスト内の属性はファイルシステムのエンコーディングでデコードされた文字列で表されます。path が None の場合、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.

この関数は ファイル記述子の指定 および シンボリックリンクをたどらない をサポートしています。

バージョン 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. flags may be XATTR_REPLACE or XATTR_CREATE. If XATTR_REPLACE is given and the attribute does not exist, EEXISTS will be raised. If XATTR_CREATE is given and the attribute already exists, the attribute will not be created and ENODATA will be raised.

この関数は ファイル記述子の指定 および シンボリックリンクをたどらない をサポートしています。

注釈

Linux カーネル 2.6.39 以前では、バグのため一部のファイルシステムで引数 flags が無視されます。

バージョン 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.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() を利用してバッファをフラッシュしておく必要があります。

"l" および "v" のついた exec* 関数は、コマンドライン引数をどのように渡すかが異なります。 "l" 型は、コードを書くときにパラメタ数が決まっている場合に、おそらくもっとも簡単に利用できます。個々のパラメタは単に execl*() 関数の追加パラメタとなります。 "v" 型は、パラメタの数が可変の時に便利で、リストかタプルの引数が args パラメタとして渡されます。どちらの場合も、子プロセスに渡す引数は動作させようとしているコマンドの名前から始まるべきですが、これは強制されません。

末尾近くに "p" をもつ型 (execlp(), execlpe(), execvp(), および execvpe()) は、プログラム file を探すために環境変数 PATH を利用します。環境変数が ( 次の段で述べる exec*e 型関数で ) 置き換えられる場合、環境変数は PATH を決定する上の情報源として使われます。その他の型、 execl(), execle(), execv(), および execve() では、実行コードを探すために PATH を使いません。 path には適切に設定された絶対パスまたは相対パスが入っていなくてはなりません。

execle() 、 execlpe() 、 execve() 、および execvpe() (すべて末尾に "e" がついています) では、 env 引数は新たなプロセスで利用される環境変数を定義するためのマップ型でなくてはなりません ( 現在のプロセスの環境変数の代わりに利用されます ); execl() 、 execlp() 、 execv() 、および execvp() では、すべて新たなプロセスは現在のプロセスの環境を引き継ぎます。

一部のプラットフォームの execve() では、path はオープンしているファイル記述子で指定することもできます。この機能をサポートしていないプラットフォームもあります; os.supports_fd を使うことで利用可能かどうか調べることができます。利用できない場合、NotImplementedError が送出されます。

Availability: Unix, Windows.

バージョン 3.3 で追加: execve() において、path へのオープンしているファイル記述子の指定のサポートを追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os._exit(n)

終了ステータス n でプロセスを終了します。この時クリーンアップハンドラーの呼び出しや、標準入出力バッファのフラッシュなどは行いません。

注釈

終了する標準的な方法は sys.exit(n) です。 _exit() は通常、 fork() された後の子プロセスでのみ使われます。

以下の終了コードは必須ではありませんが _exit() で使うことができます。一般に、メールサーバーの外部コマンド配送プログラムのような、 Python で書かれたシステムプログラムに使います。

注釈

いくつかのバリエーションがあって、これらのすべてがすべての Unix プラットフォームで使えるわけではありません。以下の定数は下層のプラットフォームで定義されていれば定義されます。

os.EX_OK

エラーが起きなかったことを表す終了コード。

利用可能な環境: Unix。

os.EX_USAGE

誤った個数の引数が渡された時など、コマンドが間違って使われたことを表す終了コード。

利用可能な環境: Unix。

os.EX_DATAERR

入力データが誤っていたことを表す終了コード。

利用可能な環境: Unix。

os.EX_NOINPUT

入力ファイルが存在しなかった、または、読み込み不可だったことを表す終了コード。

利用可能な環境: Unix。

os.EX_NOUSER

指定されたユーザーが存在しなかったことを表す終了コード。

利用可能な環境: Unix。

os.EX_NOHOST

指定されたホストが存在しなかったことを表す終了コード。

利用可能な環境: Unix。

os.EX_UNAVAILABLE

要求されたサービスが利用できないことを表す終了コード。

利用可能な環境: Unix。

os.EX_SOFTWARE

内部ソフトウェアエラーが検出されたことを表す終了コード。

利用可能な環境: Unix。

os.EX_OSERR

fork できない、 pipe の作成ができないなど、オペレーティングシステムのエラーが検出されたことを表す終了コード。

利用可能な環境: Unix。

os.EX_OSFILE

システムファイルが存在しなかった、開けなかった、あるいはその他のエラーが起きたことを表す終了コード。

利用可能な環境: Unix。

os.EX_CANTCREAT

ユーザーには作成できない出力ファイルを指定したことを表す終了コード。

利用可能な環境: Unix。

os.EX_IOERR

ファイルの I/O を行っている途中にエラーが発生した時の終了コード。

利用可能な環境: Unix。

os.EX_TEMPFAIL

一時的な失敗が発生したことを表す終了コード。これは、再試行可能な操作の途中に、ネットワークに接続できないというような、実際にはエラーではないかも知れないことを意味します。

利用可能な環境: Unix。

os.EX_PROTOCOL

プロトコル交換が不正、不適切、または理解不能なことを表す終了コード。

利用可能な環境: Unix。

os.EX_NOPERM

操作を行うために十分な許可がなかった（ファイルシステムの問題を除く）ことを表す終了コード。

利用可能な環境: Unix。

os.EX_CONFIG

設定エラーが起こったことを表す終了コード。

利用可能な環境: Unix。

os.EX_NOTFOUND

"an entry was not found" のようなことを表す終了コード。

利用可能な環境: Unix。

os.fork()

子プロセスを fork します。子プロセスでは 0 が返り、親プロセスでは子プロセスの id が返ります。エラーが発生した場合は、 OSError を送出します。

FreeBSD 6.3 以下、Cygwinを含む一部のプラットフォームにおいて、fork() をスレッド内から利用した場合に既知の問題があることに注意してください。

警告

SSL モジュールを fork() とともに使うアプリケーションについて、 ssl を参照して下さい。

利用可能な環境: Unix。

os.forkpty()

子プロセスを fork します。この時新しい擬似端末を子プロセスの制御端末として使います。親プロセスでは (pid, fd) からなるペアが返り、 fd は擬似端末のマスター側のファイル記述子となります。可搬性のあるアプローチを取るには、 pty モジュールを利用してください。エラーが発生した場合は、 OSError を送出します。

Availability: some flavors of Unix.

os.kill(pid, sig)

プロセス pid にシグナル sig を送ります。ホストプラットフォームで利用可能なシグナルを特定する定数は signal モジュールで定義されています。

Windows: signal.CTRL_C_EVENT と signal.CTRL_BREAK_EVENT は、同じコンソールウィンドウを共有しているコンソールプロセス ( 例 : 子プロセス ) にだけ送ることができる特別なシグナルです。その他の値を sig に与えると、そのプロセスが無条件に TerminateProcess API によって kill され、終了コードが sig に設定されます。 Windows の kill() は kill するプロセスのハンドルも受け取ります。

signal.pthread_kill() も参照してください。

バージョン 3.2 で追加: Windows をサポートしました。

os.killpg(pgid, sig)

プロセスグループ pgid にシグナル sig を送ります。

利用可能な環境: Unix。

os.nice(increment)

プロセスの "nice 値 " に increment を加えます。新たな nice 値を返します。

利用可能な環境: Unix。

os.plock(op)

プログラムのセグメントをメモリ内にロックします。 op (<sys/lock.h> で定義されています ) にはどのセグメントをロックするかを指定します。

利用可能な環境: Unix。

os.popen(cmd, mode='r', buffering=-1)

コマンド cmd への、または cmd からのパイプ入出力を開きます。戻り値はパイプに接続されている開かれたファイルオブジェクトで、 mode が 'r' (デフォルト) または 'w' かによって読み出しまたは書き込みを行うことができます。引数 bufsize は、組み込み関数 open() における対応する引数と同じ意味を持ちます。 返されるファイルオブジェクトは、バイトではなくテキスト文字列を読み書きします。

close メソッドは、サブプロセスが正常に終了した場合は None を返し、エラーが発生した場合にはサブプロセスの返りコードを返します。POSIX システムでは、返りコードが正の場合、そのコードは1バイト左にシフトしてプロセスが終了したことを示します。返りコードが負の場合、プロセスは返りコードの符号を変えた信号により終了します 。 (例えば、サブプロセスが kill された場合、返り値は - signal.SIGKILL となる場合があります。) Windows システムでは、返り値には子プロセスからの符号のついた整数の返りコードを含まれます。

これは、subprocess.Popen を使用して実装されています。サブプロセスを管理し、サブプロセスと通信を行うためのより強力な方法については、クラスのドキュメンテーションを参照してください。

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.

利用可能な環境: Unix。

バージョン 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() 関数で使えます。

"l" および "v" のついた spawn* 関数は、コマンドライン引数をどのように渡すかが異なります。 "l" 型は、コードを書くときにパラメタ数が決まっている場合に、おそらくもっとも簡単に利用できます。個々のパラメタは単に spawnl*() 関数の追加パラメタとなります。 "v" 型は、パラメタの数が可変の時に便利で、リストかタプルの引数が args パラメタとして渡されます。どちらの場合も、子プロセスに渡す引数は動作させようとしているコマンドの名前から始まらなければなりません。

末尾近くに "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)

Availability: Unix, Windows. spawnlp(), spawnlpe(), spawnvp() and spawnvpe() are not available on Windows. spawnle() and spawnve() are not thread-safe on Windows; we advise you to use the subprocess module instead.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.P_NOWAIT
os.P_NOWAITO

spawn* 関数ファミリに対する mode パラメタとして取れる値です。この値のいずれかを mode として与えた場合、 spawn*() 関数は新たなプロセスが生成されるとすぐに、プロセスの ID を戻り値として返ります。

Availability: Unix, Windows.

os.P_WAIT

spawn* 関数ファミリに対する mode パラメタとして取れる値です。この値を mode として与えた場合、 spawn*() 関数は新たなプロセスを起動して完了するまで返らず、プロセスがうまく終了した場合には終了コードを、シグナルによってプロセスが kill された場合には -signal を返します。

Availability: Unix, Windows.

os.P_DETACH
os.P_OVERLAY

spawn* 関数ファミリに対する mode パラメタとして取れる値です。これらの値は上の値よりもやや可搬性において劣っています。 P_DETACH は P_NOWAIT に似ていますが、新たなプロセスは呼び出しプロセスのコンソールから切り離され (detach) ます。 P_OVERLAY が使われた場合、現在のプロセスは置き換えられます。したがって spawn* は返りません。

利用可能な環境: Windows 。

os.startfile(path[, operation])

ファイルを関連付けられたアプリケーションを使ってスタートします。

operation が指定されないか、または 'open' である時、この動作は、 Windows の Explorer 上でのファイルをダブルクリックした、あるいはコマンドプロンプト上でファイル名を start コマンドの引数としての実行した場合と等価です : ファイルは拡張子が関連付けされているアプリケーション ( が存在する場合 ) を使って開かれます。

他の operation が与えられる場合、それはファイルに対して何がなされるべきかを表す "command verb" ( コマンドを表す動詞 ) でなければなりません。 Microsoft が文書化している動詞は、 'print' と 'edit' ( ファイルに対して ) および 'explore' と 'find' ( ディレクトリに対して ) です。

startfile() は関連付けされたアプリケーションが起動すると同時に返ります。アプリケーションが閉じるまで待機させるためのオプションはなく、アプリケーションの終了状態を取得する方法もありません。引数 path はカレントディレクトリからの相対パスです。絶対パスで指定したい場合は、最初の文字はスラッシュ ('/') ではないので注意してください。最初の文字がスラッシュの場合、下層の Win32 ShellExecute() 関数は動作しません。 os.path.normpath() 関数を使って、 Win32 用に正しくコード化されたパスになるようにしてください。

インタープリタの起動時のオーバーヘッドを削減するため、この関数が最初に呼ばれるまで、Win32 ShellExecute() 関数は決定されません。関数を決定できない場合、 NotImplementedError が送出されます。

利用可能な環境: Windows 。

os.system(command)

サブシェル内でコマンド (文字列) を実行します。この関数は標準 C 関数 system() を使って実装されており、system() と同じ制限があります。sys.stdin などに対する変更を行っても、実行されるコマンドの環境には反映されません。command が何らかの出力を生成した場合、インタープリターの標準出力ストリームに送られます。

Unix では、返り値はプロセスの終了ステータスで、 wait() で定義されている書式にコード化されています。 POSIX は system() 関数の返り値の意味について定義していないので、 Python の system() における返り値はシステム依存となることに注意してください。

Windows では、返り値は command を実行した後にシステムシェルから返される値です。シェルは通常 cmd.exe であり、返す値は実行したコマンドの終了ステータスになります。シェルの種類は Windows の環境変数 COMSPEC: に指定されています。ネイティブでないシェルを使用している場合は、そのドキュメントを参照してください。

subprocess モジュールは、新しいプロセスを実行して結果を取得するためのより強力な機能を提供しています。この関数の代わりに subprocess モジュールを利用することが推奨されています。 subprocess モジュールのドキュメントの 古い関数を subprocess モジュールで置き換える 節のレシピを参考にして下さい。

Availability: Unix, Windows.

os.times()

現在の全体的なプロセス時間を返します。返り値は 5 個の属性を持つオブジェクトになります:

  • user - ユーザー時間
  • system - システム時間
  • children_user - すべての子プロセスのユーザー時間
  • children_system - すべての子プロセスのシステム時間
  • elapsed - 去のある固定時点からの経過実時間

後方互換性のため、このオブジェクトは 5 個のアイテム user 、 system 、 children_user 、 children_system 、および elapsed を持つタプルのようにも振る舞います。

times(2) の Unix マニュアルページ、または対応する Windows プラットフォーム API ドキュメントを参照してください。Windows では、user および system のみ有効で、その他の属性にはゼロが入ります。

Availability: Unix, Windows.

バージョン 3.3 で変更: 返り値の型が、タプルから属性名のついたタプルライクオブジェクトに変更されました。

os.wait()

子プロセスの実行完了を待機し、子プロセスの pid と終了コードインジケーター --- 16 ビットの数値で、下位バイトがプロセスを kill したシグナル番号、上位バイトが終了ステータス ( シグナル番号がゼロの場合 ) --- の入ったタプルを返します ; コアダンプファイルが生成された場合、下位バイトの最上桁ビットが立てられます。

利用可能な環境: Unix。

os.waitid(idtype, id, options)

一つ以上のプロセスの完了を待機します。idtype には P_PID、P_PGID、または P_ALL を指定できます。id は待機する pid を指定します。options は WEXITED、WSTOPPED、または WCONTINUED を一つ以上、論理和で指定でき、他に WNOHANG または WNOWAIT も追加できます。返り値は siginfo_t 構造体に含まれるデータ (si_pid、si_uid、si_signo、si_status、および si_code) を表すオブジェクトになります。WNOHANG が指定され、待機状態の子プロセスがない場合は None を返します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.P_PID
os.P_PGID
os.P_ALL

waitid() の idtype に指定できる値です。これらは id がどう解釈されるかに影響します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.WEXITED
os.WSTOPPED
os.WNOWAIT

waitid() の options で使用できるフラグです。子プロセスのどのシグナルを待機するかを指定します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

os.CLD_EXITED
os.CLD_DUMPED
os.CLD_TRAPPED
os.CLD_CONTINUED

waitid() の返り値の si_code に設定され得る値です。

利用可能な環境: Unix。

バージョン 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 の絶対値 ) 内の任意のプロセスに対する要求です。

システムコールが -1 を返した時、 OSError を errno と共に送出します。

Windows では、プロセスハンドル pid を指定してプロセスの終了を待って、 pid と、終了ステータスを 8bit 左シフトした値のタプルを返します。 ( シフトは、この関数をクロスプラットフォームで利用しやすくするために行われます ) 0 以下の pid は Windows では特別な意味を持っておらず、例外を発生させます。 options の値は効果がありません。 pid は、子プロセスで無くても、プロセス ID を知っているどんなプロセスでも参照することが可能です。 spawn* 関数を P_NOWAIT と共に呼び出した場合、適切なプロセスハンドルが返されます。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、この関数は InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

os.wait3(options)

waitpid() に似ていますが、プロセス id を引数に取らず、子プロセス id 、終了ステータスインジケータ、リソース使用情報の 3 要素からなるタプルを返します。リソース使用情報の詳しい情報は resource. getrusage() を参照してください。 オプション引数は waitpid() および wait4() と同じです。

利用可能な環境: Unix。

os.wait4(pid, options)

waitpid() に似ていますが、子プロセス id 、終了ステータスインジケータ、リソース使用情報の 3 要素からなるタプルを返します。リソース使用情報の詳しい情報は resource. getrusage() を参照してください。 wait4() の引数は waitpid() に与えられるものと同じです。

利用可能な環境: Unix。

os.WNOHANG

子プロセス状態がすぐに取得できなかった場合に直ちに終了するようにするための waitpid() のオプションです。この場合、関数は (0, 0) を返します。

利用可能な環境: Unix。

os.WCONTINUED

このオプションによって子プロセスは前回状態が報告された後にジョブ制御による停止状態から実行を再開された場合に報告されるようになります。

Availability: some Unix systems.

os.WUNTRACED

このオプションによって子プロセスは停止されていながら停止されてから状態が報告されていない場合に報告されるようになります。

利用可能な環境: Unix。

以下の関数は system() 、 wait() 、あるいは waitpid() が返すプロセス状態コードを引数にとります。これらの関数はプロセスの配置を決めるために利用できます。

os.WCOREDUMP(status)

プロセスに対してコアダンプが生成されていた場合には True を、それ以外の場合は False を返します。

利用可能な環境: Unix。

os.WIFCONTINUED(status)

プロセスがジョブ制御による停止状態から実行を再開された (continue) 場合に True を、それ以外の場合は False を返します。

利用可能な環境: Unix。

os.WIFSTOPPED(status)

プロセスが停止された (stop) 場合に True を、それ以外の場合は False を返します。

利用可能な環境: Unix。

os.WIFSIGNALED(status)

プロセスがシグナルによって終了した (exit) 場合に True を、それ以外の場合は False を返します。

利用可能な環境: Unix。

os.WIFEXITED(status)

プロセスが exit(2) システムコールで終了した場合に True を、それ以外の場合は False を返します。

利用可能な環境: Unix。

os.WEXITSTATUS(status)

WIFEXITED(status) が真の場合、 exit(2) システムコールに渡された整数の引数を返します。そうでない場合、返り値に意味はありません。

利用可能な環境: Unix。

os.WSTOPSIG(status)

プロセスを停止させたシグナル番号を返します。

利用可能な環境: Unix。

os.WTERMSIG(status)

プロセスを終了させたシグナル番号を返します。

利用可能な環境: Unix。

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

以下の関数は、オペレーティングシステムがプロセスに CPU 時間を割り当てる方法を制御します。これらは一部の Unix プラットフォームでのみ利用可能です。詳しくは Unix マニュアルページを参照してください。

バージョン 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)

PID pid のプロセス (0 の場合、現在のプロセス) が制限されている CPU の集合を返します。

雑多なシステム情報

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()

システムの CPU 数を返します。未定の場合は None を返します。

この数は現在のプロセスが使える CPU 数と同じものではありません。 使用可能な CPU 数は len(os.sched_getaffinity(0)) で取得できます。

バージョン 3.4 で追加.

os.getloadavg()

過去 1 分、 5 分、および 15 分間の、システムの実行キューの平均プロセス数を返します。平均負荷が得られない場合には OSError を送出します。

利用可能な環境: Unix。

os.sysconf(name)

整数値のシステム設定値を返します。 name で指定された設定値が定義されていない場合、 -1 が返されます。 name に関するコメントとしては、 confstr() で述べた内容が同様に当てはまります ; 既知の設定名についての情報を与える辞書は sysconf_names で与えられています。

利用可能な環境: Unix。

os.sysconf_names

sysconf() が受理する名前を、ホストオペレーティングシステムで定義されている整数値に対応付けている辞書です。この辞書はシステムでどの設定名が定義されているかを決定するために利用できます。

利用可能な環境: Unix。

以下のデータ値はパス名編集操作をサポートするために利用されます。これらの値はすべてのプラットフォームで定義されています。

パス名に対する高水準の操作は 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) ページを参照してください。

バージョン 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 も参照してください。

Availability: Linux 3.17 and newer.

バージョン 3.6 で追加.

os.urandom(size)

暗号に関する用途に適した size バイトからなるランダムな文字列を返します。

この関数は OS 固有の乱数発生源からランダムなバイト列を生成して返します。この関数の返すデータは暗号を用いたアプリケーションで十分利用できる程度に予測不能ですが、実際のクオリティは OS の実装によって異なります。

On Linux, if the getrandom() syscall is available, it is used in blocking mode: block until the system urandom entropy pool is initialized (128 bits of entropy are collected by the kernel). See the PEP 524 for the rationale. On Linux, the getrandom() function can be used to get random bytes in non-blocking mode (using the GRND_NONBLOCK flag) or to poll until the system urandom entropy pool is initialized.

On a Unix-like system, random bytes are read from the /dev/urandom device. If the /dev/urandom device is not available or not readable, the NotImplementedError exception is raised.

Windowsで、 CryptGenRandom() を使用します。

参考

The secrets module provides higher level functions. For an easy-to-use interface to the random number generator provided by your platform, please see random.SystemRandom.

バージョン 3.6.0 で変更: Linuxで、 セキュリティを高めるために、getrandom() をブロッキングモードで使用するようになりました。

バージョン 3.5.2 で変更: Linux において、 getrandom() システムコールがブロックするなら (urandom エントロピープールが初期化されていなければ) 、 /dev/urandom を読む方法にフォールバックします。

バージョン 3.5 で変更: Linux 3.17 以降では、使用可能な場合に getrandom() システムコールが使用されるようになりました。OpenBSD 5.6 以降では、C getentropy() 関数が使用されるようになりました。これらの関数は、内部ファイル記述子を使用しません。

os.GRND_NONBLOCK

By default, when reading from /dev/random, getrandom() blocks if no random bytes are available, and when reading from /dev/urandom, it blocks if the entropy pool has not yet been initialized.

If the GRND_NONBLOCK flag is set, then getrandom() does not block in these cases, but instead immediately raises BlockingIOError.

バージョン 3.6 で追加.

os.GRND_RANDOM

If this bit is set, then random bytes are drawn from the /dev/random pool instead of the /dev/urandom pool.

バージョン 3.6 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 汎用オペレーティングシステムサービス »


io --- ストリームを扱うコアツール

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

io --- ストリームを扱うコアツール

ソースコード: Lib/io.py

概要

io モジュールは様々な種類の I/O を扱う Python の主要な機能を提供しています。 I/O には主に3つの種類があります; テキスト I/O, バイナリ I/O, raw I/O です。これらは汎用的なカテゴリで、各カテゴリには様々なストレージが利用されます。これらのいずれかのカテゴリに属する具象オブジェクトは全て file object と呼ばれます。他によく使われる用語として ストリーム と file-like オブジェクト があります。

Independent of its category, each concrete stream object will also have various capabilities: it can be read-only, write-only, or read-write. It can also allow arbitrary random access (seeking forwards or backwards to any location), or only sequential access (for example in the case of a socket or pipe).

All streams are careful about the type of data you give to them. For example giving a 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 のドキュメントで詳しく解説します。

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

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() 関数のエイリアスです。

exception io.BlockingIOError

互換性のための、組み込みの BlockingIOError 例外のエイリアスです。

exception io.UnsupportedOperation

OSError と ValueError を継承した例外です。ストリームがサポートしていない操作を行おうとした時に送出されます。

インメモリー ストリーム

str や bytes-like オブジェクト を、読み書き可能なファイルのように扱うことができます。 StringIO は文字列に対して、テキストモードで開かれたファイルのように使うことができます。 BytesIO はバイナリーモードで開いたファイルのように扱うことができます。この2つのクラスは、読み書き可能で、ランダムアクセス可能です。

参考

sys
標準 IO ストリームを持っています: sys.stdin, sys.stdout, sys.stderr。

クラス階層

I/O ストリームの実装はクラス階層に分けて整理されています。まずストリームのカテゴリを分類するための抽象基底クラス群(abstract base class, ABC) があり、続いて標準のストリーム実装を行う具象クラス群があります。

注釈

抽象基底クラス群は、具象ストリームクラスの実装を助けるために、いくつかのデフォルトの実装を提供しています。例えば、 BufferedIOBase は readinto() と readline() の最適化されていない実装を提供しています。

I/O 階層の最上位には抽象基底クラスの IOBase があります。 IOBase ではストリームに対して基本的なインタフェースを定義しています。 しかしながら、ストリームに対する読み込みと書き込みが分離されていないことに注意してください。 実装においては与えられた操作をサポートしない場合は UnsupportedOperation を送出することが許されています。

RawIOBase ABC は IOBase を拡張します。このクラスはストリームからの bytes の読み書きを扱います。 FileIO は、 RawIOBase を継承してマシンのファイルシステム中のファイルへのインタフェースを提供します。

BufferedIOBase ABC は生のバイトストリーム (RawIOBase) 上にバッファ処理を追加します。そのサブクラスの BufferedWriter, BufferedReader, BufferedRWPair では、 それぞれ読み込み専用、書き込み専用、読み書き可能なストリームをバッファします。 BufferedRandom ではランダムアクセスストリームに対してバッファされたインタフェースを提供します。 BytesIO も BufferedIOBase のサブクラスで、インメモリのバイト列へのシンプルなストリームです。

もう一つの IOBase のサブクラスである TextIOBase ABC は、 テキストを表すバイトストリームを扱い、文字列とのエンコードやデコードといった処理を行います。 TextIOWrapper はその拡張で、バッファ付き raw ストリーム (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

すべての I/O クラスの抽象基底クラスです。バイトストリームへの操作を行います。パブリックなコンストラクタはありません。

継承先のクラスが選択的にオーバライドできるように、このクラスは多くのメソッドに空の抽象実装をしています。デフォルトの実装では、読み込み、書き込み、シークができないファイルを表現します。

IOBase では read(), readinto(), write() が宣言されていませんが、これはシグナチャが変化するためで、実装やクライアントはこれらのメソッドをインタフェースの一部として考えるべきです。また、実装はサポートしていない操作を呼び出されたときは ValueError (または UnsupportedOperation) を発生させるかもしれません。

ファイルへのバイナリデータの読み書きに用いられる基本型は bytes です。他の bytes-like オブジェクト もメソッドの引数として受け付けられます。いくつかのケース、たとえば readinto() では、 bytearray のような書き込み可能なオブジェクトが要求されます。テキスト I/O クラスは str データを扱います。

閉じられたストリームに対するメソッド呼び出しは (問い合わせであっても) 未定義です。この場合、実装は ValueError を送出することがあります。

IOBase (とそのサブクラス) はイテレータプロトコルをサポートします。 IOBase オブジェクトをイテレートすると、ストリーム内の行が yield されます。ストリーム内の行の定義は、そのストリームが (バイト列を yield する) バイナリストリームか (文字列を yield する) テキストストリームかによって、 少し異なります。下の readline() を参照してください。

IOBase is also a context manager and therefore supports the with statement. In this example, file is closed after the with statement's suite is finished---even if an exception occurs:

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()

ストリームが読み込める場合 True を返します。 False の場合は read() は OSError を発生させます。

readline(size=-1)

ストリームから 1 行読み込んで返します。もし size が指定された場合、最大で size バイトが読み込まれます。

バイナリファイルでは行末文字は常に b'\n' となります。テキストファイルでは、認識される行末文字を選択するために open() に対する newline 引数が使われます。

readlines(hint=-1)

ストリームから行のリストを読み込んで返します。 hint を指定することで、読み込む行数を制御できます。もし読み込んだすべての行のサイズ (バイト数、もしくは文字数) が hint の値を超えた場合、読み込みをそこで終了します。

ただし、 file.readlines() を呼びださなくても for line in file: ... のように file オブジェクトを直接イテレートすることができます。

seek(offset[, whence])

ストリーム位置を指定された offset バイトに変更します。offset は whence で指定された位置からの相対位置として解釈されます。 whence のデフォルト値は SEEK_SET です。 whence に指定できる値は:

  • SEEK_SET または 0 -- ストリームの先頭 (デフォルト)。 offset は 0 もしくは正の値でなければなりません。
  • SEEK_CUR または 1 -- 現在のストリーム位置。 offset は負の値も可能です。
  • SEEK_END または 2 -- ストリームの末尾。 offset は通常負の値です。

新しい絶対位置を返します。

バージョン 3.1 で追加: SEEK_* 定数.

バージョン 3.3 で追加: 一部のオペレーティングシステムは os.SEEK_HOLE や os.SEEK_DATA など、追加の値をサポートすることがあります。ファイルに対して利用できる値は、そのファイルがテキストモードで開かれたかバイナリモードで開かれたかに依存します。

seekable()

ストリームがランダムアクセスをサポートしている場合、 True を返します。 False の場合、 seek()、 tell()、 truncate() を使用すると OSError を発生させます。

tell()

現在のストリーム位置を返します。

truncate(size=None)

ストリームのサイズを、指定された size バイト (または size が指定されていない場合、現在位置) に変更します。現在のストリーム位置は変更されません。このサイズ変更により、現在のファイルサイズを拡大または縮小させることができます。拡大の場合には、新しいファイル領域の内容はプラットホームによって異なります (ほとんどのシステムでは、追加のバイトが 0 で埋められます)。新しいファイルサイズが返されます。

バージョン 3.5 で変更: Windows で、拡大時に追加領域を 0 で埋めるようになりました。

writable()

ストリームが書き込みをサポートしている場合 True を返します。 False の場合は write()、 truncate() は OSError を返します。

writelines(lines)

ストリームに行のリストを書き込みます。行区切り文字は追加されないので、書き込む各行の行末に行区切り文字を含ませるのが一般的です。

__del__()

オブジェクトの破壊の用意をします。このメソッドはインスタンスの close() メソッドを呼びます。 IOBase はこのメソッドのデフォルトの実装を提供します

class io.RawIOBase

生のバイナリ I/O への基底クラスです。 IOBase を継承しています。パブリックコンストラクタはありません。

raw バイナリ I/O は典型的に、下にある OS デバイスや API への低水準のアクセスを提供し、高水準の基本要素へとカプセル化しようとはしません (これはこのページで後述する Buffered I/O や Text I/O に任せます)。

IOBase の属性やメソッドに加えて、 RawIOBase は次のメソッドを提供します:

read(size=-1)

オブジェクトを size バイトまで読み込み、それを返します。 簡単のため、 size が指定されていないか -1 の場合は、 EOF までの全てのバイトを返します。 そうでない場合は、システムコール呼び出しが一度だけ行われます。 オペレーティングシステムコールから返ってきたものが size バイトより少なければ、 size バイトより少ない返り値になることがあります。

size が 0 でないのに 0 バイトが返った場合、それはファイルの終端を表します。オブジェクトがノンブロッキングモードで、1 バイトも読み込めなければ、None が返されます。

デフォルトの実装は readall() と readinto() に従います。

readall()

EOF までストリームからすべてのバイトを読み込みます。必要な場合はストリームに対して複数の呼び出しをします。

readinto(b)

あらかじめ確保された書き込み可能な bytes-like object b にバイト列を読み込み、読み込んだバイト数を返します。オブジェクトがノンブロッキングモードで、 1 バイトも読み込めなければ、 None が返されます。

write(b)

与えられた bytes-like オブジェクト b を生ストリームに書き込み、書き込んだバイト数を返します。これは、根底の生ストリームの性質や、特にノンブロッキングである場合に、 b のバイト数より小さくなることがあります。生ストリームがブロックされないように設定されていて、かつ1バイトも即座に書き込むことができなければ、 None が返されます。このメソッドから返った後で呼び出し元は b を解放したり変更したりするかもしれないので、実装はメソッド呼び出しの間だけ b にアクセスすべきです。

class io.BufferedIOBase

何らかのバッファリングをサポートするバイナリストリームの基底クラスです。 IOBase を継承します。パブリックなコンストラクタはありません。

RawIOBase との主な違いは、メソッド read()、 readinto() および write() は 、ことによると複数回のシステムコールを行って、(それぞれ) 要求されただけの入力を読み込もうとしたり与えられた出力の全てを消費しようとしたりする点です。

加えて、元になる生ストリームが非ブロッキングモードでかつ準備ができていない場合に、これらのメソッドは、 BlockingIOError を送出するかもしれません。対応する RawIOBase バージョンと違って、 None を返すことはありません。

さらに、 read() メソッドは、 readinto() に従うデフォルト実装を持ちません。

通常の BufferedIOBase 実装は RawIOBase 実装を継承せずに、 BufferedWriter と BufferedReader がするようにこれをラップすべきです。

BufferedIOBase は IOBase からのメソッドと属性に加えて、以下のメソッドを提供もしくはオーバーライドします:

raw

BufferedIOBase が扱う根底の生ストリーム (RawIOBase インスタンス) を返します。これは BufferedIOBase API には含まれず、よって実装に含まれないことがあります。

detach()

根底の生ストリームをバッファから分離して返します。

生ストリームが取り外された後、バッファは使用不能状態になります。

バッファには、 BytesIO など、このメソッドで返される単体のストリームという概念を持たないものがあります。これらは UnsupportedOperation を送出します。

バージョン 3.1 で追加.

read(size=-1)

最大で size バイト読み込んで返します。 引数が省略されるか、 None か、または負の値であった場合、 データは EOF に到達するまで読み込まれます。 ストリームが既に EOF に到達していた場合は空の bytes オブジェクトが返されます。

引数が正で、元になる生ストリームが対話的でなければ、必要なバイト数を満たすように複数回の生 read が発行されるかもしれません (先に EOF に到達しない限りは)。対話的な場合は、最大で一回の raw read しか発行されず、短い結果でも EOF に達したことを意味しません。

元になる生ストリームがノンブロッキングモードで、呼び出された時点でデータを持っていなければ、 BlockingIOError が送出されます。

read1([size])

根底の raw ストリームの read() (または readinto() ) メソッドを高々 1 回呼び出し、最大で size バイト読み込み、返します。これは、 BufferedIOBase オブジェクトの上に独自のバッファリングを実装するときに便利です。

If size is -1 (the default), an arbitrary number of bytes are returned (more than zero unless EOF is reached).

readinto(b)

あらかじめ確保された書き込み可能な bytes-like オブジェクト b にバイト列を読み込み、読み込んだバイト数を返します。

read() と同様に、下層の raw ストリームが対話的でない限り、複数の読み込みは下層の raw ストリームに与えられるかもしれません。

元になる生ストリームがノンブロッキングモードで、呼び出された時点でデータを持っていなければ、 BlockingIOError が送出されます。

readinto1(b)

根底の raw ストリームの read() (または readinto()) メソッドを高々 1 回呼び出し、あらかじめ確保された書き込み可能な bytes-like オブジェクト b にバイト列を読み込みます。読み込んだバイト数を返します。

元になる生ストリームがノンブロッキングモードで、呼び出された時点でデータを持っていなければ、 BlockingIOError が送出されます。

バージョン 3.5 で追加.

write(b)

与えられた bytes-like オブジェクト b を書き込み、書き込んだバイト数を返します (これは常に b のバイト数と等しくなります。なぜなら、もし書き込みに失敗した場合は OSError が発生するからです)。実際の実装に依存して、これらのバイト列は根底のストリームに即座に書き込まれることもあれば、パフォーマンスやレイテンシの関係でバッファに保持されることもあります。

ノンブロッキングモードであるとき、バッファが満杯で根底の生ストリームが書き込み時点でさらなるデータを受け付けられない場合 BlockingIOError が送出されます。

このメソッドが戻った後で、呼び出し元は b を解放、または変更するかもしれないので、実装はメソッド呼び出しの間だけ b にアクセスすべきです。

生ファイルI/O

class io.FileIO(name, mode='r', closefd=True, opener=None)

FileIO はバイトデータを含む OS レベルのファイルを表します。 RawIOBase インタフェースを (したがって IOBase インタフェースも) 実装しています。

name は、次の 2 つのいずれかです。

  • 開くファイルへのパスを表す文字列または bytes オブジェクト。 この場合、closefd は True (デフォルト) でなければなりません。 True でない場合、エラーが送出されます。
  • 結果の FileIO オブジェクトがアクセスを与える、既存の OS レベルファイル記述子の数を表す整数。FileIO オブジェクトが閉じられると、closefd が False に設定されていない場合、この fd も閉じられます。

mode は 読み込み（デフォルト）、書き込み、排他的作成、追記に対し 'r' 、 'w' 、 'x' 、 'a' です。ファイルは書き込みや追記で開かれたときに存在しない場合作成されます。書き込みのときにファイルの内容は破棄されます。作成時に既に存在する場合は FileExistsError が送出されます。作成のためにファイルを開くのは暗黙的に書き込みなので、このモードは 'w' と同じように振る舞います。読み込みと書き込みを同時に許可するにはモードに '+' を加えてください。

このクラスの read() (正の引数で呼び出されたとき), readinto() および write() メソッドは、単にシステムコールを一度呼び出します。

呼び出し可能オブジェクトを opener として与えることで、カスタムのオープナーが使えます。そしてファイルオブジェクトの基底のファイルディスクリプタは、opener を (name, flags) で呼び出して得られます。opener は開いたファイルディスクリプタを返さなければなりません。 (os.open を opener として渡すと、None を渡したのと同様の機能になります。)

新たに作成されたファイルは 継承不可 です。

opener 引数を使う例については open() 組み込み関数を参照してください。

バージョン 3.3 で変更: opener 引数が追加されました。'x' モードが追加されました。

バージョン 3.4 で変更: ファイルが継承不可になりました。

IOBase と RawIOBase の属性やメソッドに加え、FileIO は以下のデータ属性を提供します:

mode

コンストラクタに渡されたモードです。

name

ファイル名。コンストラクタに名前が渡されなかったときはファイル記述子になります。

バッファ付きストリーム

バッファ付き I/O ストリームは、I/O デバイスに生 I/O より高レベルなインタフェースを提供します。

class io.BytesIO([initial_bytes])

インメモリの bytes バッファを利用したストリームの実装です。 BufferedIOBase を継承します。バッファは close() メソッドが呼び出された際に破棄されます。

省略可能な引数 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 オブジェクトはリサイズやクローズされません。

バージョン 3.2 で追加.

getvalue()

バッファの全内容を含む bytes を返します。

read1([size])

In BytesIO, this is the same as read().

バージョン 3.7 で変更: The size argument is now optional.

readinto1(b)

In BytesIO, this is the same as readinto().

バージョン 3.5 で追加.

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

読み込み可能でシーケンシャルな RawIOBase オブジェクトへの高水準のアクセスを提供するバッファです。 BufferedIOBase を継承します。このオブジェクトからデータを読み込むとき、より大きい量のデータが根底の raw ストリームから要求され、内部バッファに保存される場合があります。バッファされたデータは、その次の読み込み時に直接返されます。

このコンストラクタは与えられた raw ストリームと buffer_size に対し BufferedReader を生成します。 buffer_size が省略された場合、代わりに DEFAULT_BUFFER_SIZE が使われます。

BufferedReader は BufferedIOBase または IOBase からのメソッドに加えて、以下のメソッドを提供もしくはオーバーライドします:

peek([size])

位置を進めずにストリームからバイト列を返します。これを果たすために生ストリームに対して行われる read は高々一度だけです。返されるバイト数は、要求より少ないかもしれませんし、多いかもしれません。

read([size])

size バイトを読み込んで返します。size が与えられないか負の値ならば、EOF まで、または非ブロッキングモード中で read 呼び出しがブロックされるまでを返します。

read1([size])

raw ストリームに対しただ一度の呼び出しで最大 size バイトを読み込んで返します。少なくとも 1 バイトがバッファされていれば、バッファされているバイト列だけが返されます。それ以外の場合は raw ストリームの読み込みが一回呼び出されます。

バージョン 3.7 で変更: The size argument is now optional.

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

書き込み可能でシーケンシャルな RawIOBase オブジェクトへの、高レベルなアクセスを提供するバッファです。 BufferedIOBase を継承します。このオブジェクトに書き込むとき、データは通常内部バッファに保持されます。このバッファは、以下のような種々の状況で根底の RawIOBase オブジェクトに書き込まれます。

  • 保留中の全データに対してバッファが足りなくなったとき;
  • flush() が呼び出されたとき;
  • seek() が (BufferedRandom オブジェクトに対して) 呼び出されたとき;
  • 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)

ランダムアクセスストリームへのバッファ付きインタフェース。 BufferedReader および BufferedWriter を継承し、さらに seek() および tell() をサポートしています。

このコンストラクタは第一引数として与えられるシーク可能な生ストリームに対し、リーダーおよびライターを作成します。 buffer_size が省略された場合、 DEFAULT_BUFFER_SIZE がデフォルトになります。

BufferedRandom は BufferedReader や BufferedWriter にできることは何でもできます。

class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)

2つの単方向 RawIOBase オブジェクト -- 一つは読み込み可能、他方が書き込み可能 -- を組み合わせてバッファ付きの双方向 I/O オブジェクトにしたものです。 BufferedIOBase を継承しています。

reader と writer はそれぞれ読み込み可能、書き込み可能な RawIOBase オブジェクトです。 buffer_size が省略された場合 DEFAULT_BUFFER_SIZE がデフォルトになります。

BufferedRWPair は、 UnsupportedOperation を送出する detach() を除く、 BufferedIOBase の全てのメソッドを実装します。

警告

BufferedRWPair は下層の生ストリームのアクセスを同期しようとはしません。同じオブジェクトをリーダとライタとして渡してはいけません。その場合は代わりに BufferedRandom を使用してください。

テキスト I/O

class io.TextIOBase

テキストストリームの基底クラスです。このクラスはストリーム I/O への文字と行に基づいたインタフェースを提供します。 Python の unicode 文字列は変更不可能なので、 readinto() メソッドは存在しません。 IOBase を継承します。パブリックなコンストラクタはありません。

IOBase から継承した属性とメソッドに加えて、 TextIOBase は以下のデータ属性とメソッドを提供しています:

encoding

エンコーディング名で、ストリームのバイト列を文字列にデコードするとき、また文字列をバイト列にエンコードするときに使われます。

errors

このエンコーダやデコーダのエラー設定です。

newlines

文字列、文字列のタプル、または None で、改行がどのように読み換えられるかを指定します。実装や内部コンストラクタのフラグに依って、これは利用できないことがあります。

buffer

TextIOBase が扱う根底のバイナリバッファ (BufferedIOBase インスタンス) です。これは TextIOBase API には含まれず、よって実装に含まれない場合があります。

detach()

根底のバイナリバッファを TextIOBase から分離して返します。

根底のバッファが取り外された後、 TextIOBase は使用不能状態になります。

TextIOBase 実装には、 StringIO など、根底のバッファという概念を持たないものがあります。これらを呼び出すと UnsupportedOperation を送出します。

バージョン 3.1 で追加.

read(size=-1)

最大 size 文字をストリームから読み込み、一つの str にして返します。 size が負の値または None ならば、 EOF まで読みます。

readline(size=-1)

改行または EOF まで読み込み、一つの str を返します。ストリームが既に EOF に到達している場合、空文字列が返されます。

size が指定された場合、最大 size 文字が読み込まれます。

seek(offset[, whence])

指定された offset にストリーム位置を変更します。 挙動は whence 引数によります。 whence のデフォルト値は SEEK_SET です。:

  • SEEK_SET または 0: ストリームの先頭からシークします (デフォルト)。 offset は TextIOBase.tell() が返す数か0のどちらかでなければなりません。それ以外の offset 値は未定義の挙動を起こします。
  • SEEK_CUR または 1: 現在の位置に "シークします"。 offset は 0 でなければなりません。つまり何もしません (他の値はサポートされていません)。
  • SEEK_END または 2: ストリーム終端へシークします。 offset は 0 でなければなりません (他の値はサポートされていません)．

新しい絶対位置を、不透明な数値で返します。

バージョン 3.1 で追加: SEEK_* 定数.

tell()

ストリームの現在位置を不透明な数値で返します。この値は根底のバイナリストレージ内でのバイト数を表すとは限りません。

write(s)

文字列 s をストリームに書き出し、書き出された文字数を返します。

class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)

BufferedIOBase バイナリストリーム上のバッファ付きテキストストリーム。 TextIOBase を継承します。

encoding はストリームがエンコードやデコードされるエンコード名です。デフォルトは locale.getpreferredencoding(False) です。

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 が None の場合、全ての '\n' 文字はシステムのデフォルトの行セパレータ os.linesep に変換されます。 newline が '' または '\n' の場合は変換されません。newline がその他の正当な値の場合、全ての '\n' 文字は与えられた文字列に変換されます。

line_buffering が True の場合、 write への呼び出しが改行文字もしくはキャリッジリターンを含んでいれば、暗黙的に flush() が呼び出されます。

write_through が True の場合、write() の呼び出しはバッファされないことが保証されます。 TextIOWrapper オブジェクトに書かれた全てのデータは直ちに下層のバイナリ buffer に処理されます。

バージョン 3.3 で変更: write_through 引数が追加されました。

バージョン 3.3 で変更: encoding の規定値が locale.getpreferredencoding() から locale.getpreferredencoding(False) になりました。 locale.setlocale() を用いてロケールのエンコーディングを一時的に変更してはいけません。ユーザが望むエンコーディングではなく現在のロケールのエンコーディングを使用してください。

TextIOWrapper provides these members in addition to those of TextIOBase and its parents:

line_buffering

行バッファリングが有効かどうか。

write_through

Whether writes are passed immediately to the underlying binary buffer.

バージョン 3.7 で追加.

reconfigure(*[, encoding][, errors][, newline][, line_buffering][, write_through])

Reconfigure this text stream using new settings for encoding, errors, newline, line_buffering and write_through.

Parameters not specified keep current settings, except errors='strict is used when encoding is specified but errors is not specified.

It is not possible to change the encoding or newline if some data has already been read from the stream. On the other hand, changing encoding after write is possible.

This method does an implicit stream flush before setting the new parameters.

バージョン 3.7 で追加.

class io.StringIO(initial_value='', newline='\n')

テキストIO のためのインメモリストリーム。テキストバッファは close() メソッドが呼び出された際に破棄されます。

バッファの初期値を initial_value で与えることが出来ます。改行変換を有効にすると、改行コードは write() によってエンコードされます。ストリームはバッファの開始位置に配置されます。

newline 引数は TextIOWrapper のものと同じように働きます。デフォルトでは \n 文字だけを行末とみなし、また、改行の変換は行いません。 newline に None をセットすると改行コードを全てのプラットフォームで \n で書き込みますが、読み込み時にはそれでもユニバーサル改行としてのデコードは実行されます。

TextIOBase およびその親クラスから継承したメソッドに加えて StringIO は以下のメソッドを提供しています:

getvalue()

バッファの全内容を含む str を返します。改行コードのデコードは read() によって行われますが、これによるストリーム位置の変更は起こりません。

使用例:

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

改行を universal newlines モードにデコードするヘルパーコーデックです。 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

(ファイルなどの) バイナリストレージ上のテキスト I/O は、同じストレージ上のバイナリ I/O より非常に遅いです。なぜならこれには、文字コーデックを使った Unicode とバイナリデータ間の変換を必要とするからです。これは大量のテキストデータ、例えば大きなログファイルを扱うときに顕著に成り得ます。同様に、 TextIOWrapper.tell() や TextIOWrapper.seek() はどちらも、使われている復元アルゴリズムのために遅くなります。

しかし StringIO は、ネイティブなインメモリ Unicode コンテナで、 BytesIO と同程度の速度を示します。

マルチスレッディング

(Unix における read(2) のような) オペレーティングシステムコールの、それがラッピングするものがスレッドセーフであるような範囲内では、 FileIO オブジェクトもまた、スレッドセーフです。

バイナリバッファ付きオブジェクト (BufferedReader, BufferedWriter, BufferedRandom および BufferedRWPair のインスタンス) は、その内部構造をロックを使って保護します。このため、これらを複数のスレッドから同時に呼び出しても安全です。

TextIOWrapper オブジェクトはスレッドセーフではありません。

リエントラント性

バイナリバッファ付きオブジェクト (BufferedReader, BufferedWriter, BufferedRandom および BufferedRWPair のインスタンス) は、リエントラント (再入可能) ではありません。リエントラントな呼び出しは普通の状況では起こりませんが、 I/O を signal ハンドラで行なっているときに起こりえます。スレッドが、すでにアクセスしているバッファ付きオブジェクトに再び入ろうとすると RuntimeError が送出されます。これは、バッファ付きオブジェクトに複数のスレッドから入ることを禁止するわけではありません。

open() 関数は TextIOWrapper 内部のバッファ付きオブジェクトをラップするため、テキストファイルにも暗黙に拡張されます。これは、標準ストリームを含むので、組み込み関数 print() にも同様に影響します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 汎用オペレーティングシステムサービス »


time --- 時刻データへのアクセスと変換

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

time --- 時刻データへのアクセスと変換

このモジュールでは、時刻に関するさまざまな関数を提供します。関連した機能について、datetime, calendar モジュールも参照してください。

このモジュールは常に利用可能ですが、すべての関数がすべてのプラットフォームで利用可能なわけではありません。このモジュールで定義されているほとんどの関数は、プラットフォーム上の同名の C ライブラリ関数を呼び出します。これらの関数に対する意味付けはプラットフォーム間で異なるため、プラットフォーム提供のドキュメントを読んでおくと便利でしょう。

まずいくつかの用語の説明と慣習について整理します。

  • エポック (epoch) は時刻の起点のことで、これはプラットフォーム依存です。 Unix では、エポックは (UTC で) 1970 年 1 月 1 日 0 時 0 分 0 秒です。 与えられたプラットフォームでエポックが何なのかを知るには、 time.gmtime(0) の値を見てください。
  • エポック秒 (seconds since the epoch) は、エポックからの総経過秒数を示していますが、たいていはうるう秒 (leap seconds) は含まれていません。 全ての POSIX 互換のプラットフォームで、うるう秒はこの総秒数には含まれません。
  • このモジュールの中の関数は、エポック以前あるいは遠い未来の日付や時刻を扱うことができません。将来カットオフ（関数が正しく日付や時刻を扱えなくなる）が起きる時点は、C ライブラリによって決まります。32-bit システムではカットオフは通常 2038 年です。
  • 2000年問題 (Y2K): Python はプラットフォームの C ライブラリに依存しています。C ライブラリは日付および時刻をエポックからの経過秒で表現するので、一般的に 2000 年問題は存在しません。関数 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 秒に過ぎません。

  • 一方、time() および sleep() は Unix の同等の関数よりましな精度を持っています。時刻は浮動小数点数で表され、time() は可能なかぎり最も正確な時刻を (Unix の gettimeofday() があればそれを使って) 返します。また sleep() にはゼロでない端数を与えることができます (Unix の select() があれば、それを使って実装しています)。

  • gmtime(), localtime(), strptime() が返す時刻値、および asctime(), mktime(), strftime() がとる時刻値は 9 個の整数からなるシーケンスです。gmtime(), localtime(), strptime() の戻り値は個々の値を属性名で取得することもできます。

    これらのオブジェクトについての解説は struct_time を参照してください。

    バージョン 3.3 で変更: struct_time オブジェクトは、プラットフォームが、対応する struct tm メンバーをサポートしている場合、tm_gmtoff および tm_zone 属性が拡張されるようになりました。

    バージョン 3.6 で変更: struct_time の属性 tm_gmtoff および tm_zone が全てのプラットフォームで利用できるようになりました。

  • 時間の表現を変換するには、以下の関数を利用してください:

    対象 | 変換先 | 関数
    エポックからの秒数 | UTC の struct_time | gmtime()
    エポックからの秒数 | ローカル時間の struct_time | localtime()
    UTC の struct_time | エポックからの秒数 | calendar.timegm()
    ローカル時間の struct_time | エポックからの秒数 | mktime()

関数

time.asctime([t])

gmtime() や localtime() が返す時刻を表現するタプルまたは struct_time を、'Sun Jun 20 23:21:05 1993' といった書式の文字列に変換します。t が与えられていない場合には、localtime() が返す現在の時刻が使われます。asctime() はロケール情報を使いません。

注釈

同名の C の関数と違って、asctime() は末尾に改行文字を加えません。

time.clock()

Unix では、現在のプロセッサー時間秒を浮動小数点数で返します。時刻の精度および "プロセッサー時間" の定義そのものは同じ名前の C 関数に依存します。

Windows では、最初にこの関数が呼び出されてからの経過時間を wall-clock 秒で返します。この関数は Win32 関数 QueryPerformanceCounter() に基づいていて、その精度は通常 1 マイクロ秒以下です。

バージョン 3.3 で非推奨: この関数の挙動はプラットフォームに依存します: 必要に応じて挙動が明確に定義されている perf_counter() または process_time() を使用してください。

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) の man を参照してください)。

バージョン 3.7 で追加.

time.clock_getres(clk_id)

指定された clk_id クロックの分解能(精度)を返します。 clk_id として受け付けられる値の一覧は Clock ID Constants を参照してください。

利用可能な環境: Unix。

バージョン 3.3 で追加.

time.clock_gettime(clk_id) → float

指定された clk_id クロックの時刻を返します。 clk_id として受け付けられる値の一覧は Clock ID Constants を参照してください。

利用可能な環境: Unix。

バージョン 3.3 で追加.

time.clock_gettime_ns(clk_id) → int

clock_gettime() に似ていますが、ナノ秒単位の時刻を返します。

利用可能な環境: Unix。

バージョン 3.7 で追加.

time.clock_settime(clk_id, time: float)

指定された clk_id クロックの時刻を設定します。 現在、 CLOCK_REALTIME は clk_id が受け付ける唯一の値です。

利用可能な環境: Unix。

バージョン 3.3 で追加.

time.clock_settime_ns(clk_id, time: int)

clock_settime() に似ていますが、ナノ秒単位の時刻を設定します。

利用可能な環境: Unix。

バージョン 3.7 で追加.

time.ctime([secs])

エポックからの経過秒数で表現された時刻を、ローカルの時刻を表現する文字列に変換します。secs を指定しないか None を指定した場合、time() が返す値を現在の時刻として使用します。ctime(secs) は asctime(localtime(secs)) と等価です。ローカル情報は ctime() には使用されません。

time.get_clock_info(name)

指定されたクロックの情報を名前空間オブジェクトとして取得します。サポートされているクロック名およびそれらの値を取得する関数は以下の通りです:

  • 'clock': time.clock()
  • '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) で表します。

バージョン 3.3 で追加.

time.gmtime([secs])

エポックからの経過時間で表現された時刻を、UTC で struct_time に変換します。このとき dst フラグは常にゼロとして扱われます。secs を指定しないか None を指定した場合、time() が返す値を現在の時刻として使用します。秒の端数は無視されます。struct_time オブジェクトについては前述の説明を参照してください。calendar.timegm() はこの関数と逆の変換を行います。

time.localtime([secs])

gmtime() に似ていますが、ローカル時間に変換します。secs を指定しないか None を指定した場合、time() が返す値を現在の時刻として使用します。DST が適用されている場合は dst フラグには 1 が設定されます。

time.mktime(t)

localtime() の逆を行う関数です。引数は struct_time か 9 個の要素すべての値を持つ完全なタプル (dst フラグも必要です; 時刻に DST が適用されるか不明の場合は -1 を使用してください) で、UTC ではなく ローカル 時間を指定します。戻り値は time() との互換性のために浮動小数点数になります。入力した値を正しい時刻として表現できない場合、例外 OverflowError または ValueError が送出されます (どちらが送出されるかは、無効な値を受け取ったのが Python と下層の C ライブラリのどちらなのかによって決まります)。この関数で時刻を生成できる最も古い日付はプラットフォームに依存します。

time.monotonic() → float

モノトニッククロックの値 (小数点以下がミリ秒) を返します。戻り値の基準点は定義されていませんが、このクロックは値が後戻りすることはなく、システムクロックの更新の影響も受けません。すなわち、モノトニック時間の重要な点はその値ではなく、値が厳密に増加していくことが保証されている点です。このため、正しい利用法は、呼び出した 2 点間の時間差を計測することです。

On Windows versions older than Vista, monotonic() detects GetTickCount() integer overflow (32 bits, roll-over after 49.7 days). It increases an internal epoch (reference time) by 232 each time that an overflow is detected. The epoch is stored in the process-local state and so the value of monotonic() may be different in two Python processes running for more than 49 days. On more recent versions of Windows and on other operating systems, monotonic() is system-wide.

バージョン 3.3 で追加.

バージョン 3.5 で変更: The function is now always available.

time.monotonic_ns() → int

monotonic() に似ていますが、ナノ秒単位の時刻を返します。

バージョン 3.7 で追加.

time.perf_counter() → float

パフォーマンスカウンターの値 (小数点以下がミリ秒) を返します。クロックは短期間の計測が行えるよう、可能な限り高い分解能をもちます。これにはスリープ中の経過時間も含まれ、システム全体で一意です。

バージョン 3.3 で追加.

time.perf_counter_ns() → int

perf_counter() に似ていますが、ナノ秒単位の時刻を返します。

バージョン 3.7 で追加.

time.process_time() → float

現在のプロセスのシステムおよびユーザー CPU 時間の合計値 (小数点以下はミリ秒) を返します。プロセスごとに定義され、スリープ中の経過時間は含まれません。戻り値の参照点は定義されていないため、正しい利用法は、呼び出した 2 点間の時間差を計測することです。

バージョン 3.3 で追加.

time.process_time_ns() → int

process_time() に似ていますが、ナノ秒単位の時刻を返します。

バージョン 3.7 で追加.

time.sleep(secs)

与えられた秒数の間、呼び出したスレッドの実行を停止します。より精度の高い実行停止時間を指定するために、引数は浮動小数点にしてもかまいません。何らかのシステムシグナルがキャッチされた場合、それに続いてシグナル処理ルーチンが実行され、sleep() を停止します。従って実際の実行停止時間は要求した時間よりも短くなるかもしれません。また、システムが他の処理をスケジュールするために、実行停止時間が要求した時間よりも多少長い時間になることもあります。

バージョン 3.5 で変更: スリープがシグナルに中断されてもシグナルハンドラが例外を送出しない限り、少なくとも secs だけスリープするようになりました (論拠については PEP 475 を参照してください)。

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]。
%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 と等価な文字列になります。 | (1)
%S | 秒の 10 進表記になります [00,61]。 | (2)
%U | 年の初めから何週目か (日曜を週の始まりとします) を表す 10 進数になります [00,53]。年が明けてから最初の日曜日までのすべての曜日は 0 週目に属すると見なされます。 | (3)
%w | 曜日の 10 進表記になります [0 (日曜日),6]。
%W | 年の初めから何週目か (月曜を週の始まりとします) を表す 10 進数になります [00,53]。年が明けてから最初の月曜日までの全ての曜日は 0 週目に属すると見なされます。 | (3)
%x | ロケールの日付を適切な形式で表します。
%X | ロケールの時間を適切な形式で表します。
%y | 西暦の下 2 桁の 10 進表記になります [00,99]。
%Y | 西暦 ( 4桁) の 10 進表記を表します。
%z | タイムゾーンと UTC/GMT との時差を表す正または負の時間を +HHMM、-HHMM で表します。H は時間の、M は分の 10 進表記になります [-23:59, +23:59]。
%Z | タイムゾーンの名前を表します (タイムゾーンがない場合には空文字列)。
%% 文字 '%' を表します。

注釈:

  1. strptime() 関数で使う場合、%p ディレクティブが出力結果の時刻フィールドに影響を及ぼすのは、時刻を解釈するために %I を使ったときのみです。
  2. 値の幅は実際に 0 から 61 です; 60 は うるう秒<leap seconds> を表し、 61 は歴史的理由によりサポートされています。
  3. strptime() 関数で使う場合、%U および %W を計算に使うのは曜日と年を指定したときだけです。

以下に RFC 2822 インターネット電子メール標準で定義されている日付表現と互換の書式の例を示します。 [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) のドキュメントを参照してください。

一部のプラットフォームでは、フィールドの幅や精度を指定するオプションがディレクティブの先頭の文字 '%' の直後に付けられるようになっていました; この機能も移植性はありません。フィールドの幅は通常 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")   # doctest: +NORMALIZE_WHITESPACE
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() が返す時刻値シーケンスの型です。これは名前付きタプル (named tuple) のインタフェースをもったオブジェクトです。値はインデックスでも属性名でもアクセス可能です。以下の値があります:

インデックス | 属性 | 値
0 | tm_year | (例えば 1993)
1 | tm_mon | [1,12] の間の数
2 | tm_mday | [1,31] の間の数
3 | tm_hour | [0,23] の間の数
4 | tm_min | [0,59] の間の数
5 | tm_sec | [0,61] の間の数 strftime() の説明にある (2) を読んで下さい
6 | tm_wday | [0,6] の間の数、月曜が 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

エポック からの秒数を浮動小数点数で返します。 エポックの具体的な日付とうるう秒 (leap seconds) の扱いはプラットフォーム依存です。 Windows とほとんどの Unix システムでは、エポックは (UTC で) 1970 年 1 月 1 日 0 時 0 分 0 秒で、うるう秒はエポック秒の時間の勘定には入りません。 これは一般に Unix 時間 と呼ばれています。 与えられたプラットフォームでエポックが何なのかを知るには、 time.gmtime(0) の値を見てください。

時刻は常に浮動小数点数で返されますが、すべてのシステムが 1 秒より高い精度で時刻を提供するとは限らないので注意してください。 この関数が返す値は通常減少していくことはありませんが、この関数を 2 回呼び出し、その呼び出しの間にシステムクロックの時刻を巻き戻して設定した場合には、以前の呼び出しよりも低い値が返ることがあります。

time() が返す数値は、 gmtime() 関数に渡されて UTC の、あるいは localtime() 関数に渡されて現地時間の、より一般的な時間のフォーマット (つまり、年、月、日、時間など) に変換されているかもしれません。 どちらの場合でも struct_time オブジェクトが返され、このオブジェクトの属性としてカレンダー日付の構成要素へアクセスできます。

time.thread_time() → float

現在のスレッドのシステムおよびユーザーの CPU 時間の合計値 (小数点以下ありの秒数) を返します。 スリープ中の経過時間は含まれません。 この値は定義によりスレッドごとの値です。 返り値の参照点は定義されていないため、同一のスレッドで連続して呼び出した返り値の差分のみが有効な値です。

利用可能な環境: Windows, Linux, CLOCK_THREAD_CPUTIME_ID をサポートしている Unix システム。

バージョン 3.7 で追加.

time.thread_time_ns() → int

thread_time() に似ていますが、ナノ秒単位の時刻を返します。

バージョン 3.7 で追加.

time.time_ns() → int

time() に似ていますが、時刻を epoch を基点としたナノ秒単位の整数で返します。

バージョン 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)) データベースを使ったほうが、タイムゾーンごとの規則を指定する上で便利です。これを行うには、必要なタイムゾーンデータファイルへのパスをシステムの '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.

Availability: Linux 2.6.39 or later.

バージョン 3.7 で追加.

time.CLOCK_HIGHRES

The Solaris OS has a CLOCK_HIGHRES timer that attempts to use an optimal hardware source, and may give close to nanosecond resolution. CLOCK_HIGHRES is the nonadjustable, high-resolution clock.

Availability: Solaris.

バージョン 3.3 で追加.

time.CLOCK_MONOTONIC

設定不可で、モノトニック時刻 (不特定のエポックからの単調増加な時刻) を表します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

time.CLOCK_MONOTONIC_RAW

CLOCK_MONOTONIC と似ていますが、NTP の影響を受けていない、ハードウェアベースの時刻へのアクセスを提供します。

Availability: Linux 2.6.28 or later.

バージョン 3.3 で追加.

time.CLOCK_PROCESS_CPUTIME_ID

CPU による高分解能のプロセスごとのタイマーです。

利用可能な環境: Unix。

バージョン 3.3 で追加.

time.CLOCK_PROF

CPU による高分解能のプロセスごとのタイマーです。

Availability: FreeBSD, NetBSD 7 or later, OpenBSD.

バージョン 3.7 で追加.

time.CLOCK_THREAD_CPUTIME_ID

スレッド固有の CPU タイムクロックです。

Availability: Unix.

バージョン 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 or later.

バージョン 3.7 で追加.

The following constant is the only parameter that can be sent to clock_settime().

time.CLOCK_REALTIME

システム全体のリアルタイムクロックです。このクロックを設定するには適切な権限が必要です。

利用可能な環境: Unix。

バージョン 3.3 で追加.

Timezone Constants

time.altzone

The offset of the local DST timezone, in seconds west of UTC, if one is defined. This is negative if the local DST timezone is east of UTC (as in Western Europe, including the UK). Only use this if daylight is nonzero. See note below.

time.daylight

Nonzero if a DST timezone is defined. See note below.

time.timezone

The offset of the local (non-DST) timezone, in seconds west of UTC (negative in most of Western Europe, positive in the US, zero in the UK). See note below.

time.tzname

A tuple of two strings: the first is the name of the local non-DST timezone, the second is the name of the local DST timezone. If no DST timezone is defined, the second string should not be used. See note below.

注釈

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] %Z の使用は現在非推奨です。ただし、ここで実現したい時間および分オフセットへの展開を行ってくれる %z エスケープはすべての ANSI C ライブラリでサポートされているわけではありません。また、1982 年に提出されたオリジナルの RFC 822 標準では西暦の表現を 2 桁とするよう要求している (%Y でなく%y ) ものの、実際には 2000 年になるだいぶ以前から 4 桁の西暦表現に移行しています。その後 RFC 822 は撤廃され、4 桁の西暦表現は RFC 1123 で初めて勧告され、 RFC 2822 において義務付けられました。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 汎用オペレーティングシステムサービス »


argparse --- コマンドラインオプション、引数、サブコマンドのパーサー

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

argparse --- コマンドラインオプション、引数、サブコマンドのパーサー

バージョン 3.2 で追加.

ソースコード: Lib/argparse.py

チュートリアル

このページは API のリファレンス情報が記載しています。argparse チュートリアル では、コマンドラインの解析についてより優しく説明しています。

argparse モジュールはユーザーフレンドリなコマンドラインインターフェースの作成を簡単にします。プログラムがどんな引数を必要としているのかを定義すると、argparse が sys.argv からそのオプションを解析する方法を見つけ出します。argparse モジュールは自動的にヘルプと使用方法メッセージを生成し、ユーザーが不正な引数をプログラムに指定したときにエラーを発生させます。

使用例

次のコードは、整数のリストを受け取って合計か最大値を返す 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

optional arguments:
 -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)

新しい ArgumentParser オブジェクトを生成します。すべての引数はキーワード引数として渡すべきです。各引数についてはあとで詳しく説明しますが、簡単に言うと:

  • prog - プログラム名 (デフォルト: sys.argv[0])
  • usage - プログラムの利用方法を記述する文字列 (デフォルト: パーサーに追加された引数から生成されます)
  • description - 引数のヘルプの前に表示されるテキスト (デフォルト: none)
  • epilog - 引数のヘルプの後で表示されるテキスト (デフォルト: none)
  • parents - ArgumentParser オブジェクトのリストで、このオブジェクトの引数が追加されます
  • formatter_class - ヘルプ出力をカスタマイズするためのクラス
  • prefix_chars - オプションの引数の prefix になる文字集合 (デフォルト: '-')
  • fromfile_prefix_chars - 追加の引数を読み込むファイルの prefix になる文字集合 (デフォルト: None)
  • argument_default - 引数のグローバルなデフォルト値 (デフォルト: None)
  • conflict_handler - 衝突するオプションを解決する方法 (通常は不要)
  • add_help - -h/--help オプションをパーサーに追加する (デフォルト: True)
  • allow_abbrev - 長いオプションが先頭の 1 文字に短縮可能 (先頭の文字が一意) である場合に短縮指定を許可する。(デフォルト: True)

バージョン 3.5 で変更: allow_abbrev 引数が追加されました。

以下の節では各オプションの利用方法を説明します。

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]

optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

optional arguments:
 -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]

optional arguments:
 -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]

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

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

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

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

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

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

optional arguments:
 -h, --help  show this help message and exit

RawTextHelpFormatter maintains whitespace for all sorts of help text, including argument descriptions. However, multiple new lines are replaced with one. If you wish to preserve multiple blank lines, add spaces between the newlines.

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 [bar ...]]

positional arguments:
 bar         BAR! (default: [1, 2, 3])

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

optional arguments:
  -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') 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'] と等価になります。

fromfile_prefix_chars= 引数のデフォルト値は None で、引数がファイル参照として扱われることがないことを意味しています。

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

バージョン 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]

optional arguments:
 -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]

optional arguments:
 -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]

optional arguments:
 --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]

optional arguments:
  +h, ++help  show this help message and exit

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 - コマンドラインに引数がなかった場合に生成される値。
  • type - コマンドライン引数が変換されるべき型。
  • choices - 引数として許される値のコンテナー。
  • required - コマンドラインオプションが省略可能かどうか (オプション引数のみ)。
  • help - 引数が何なのかを示す簡潔な説明。
  • metavar - 使用法メッセージの中で使われる引数の名前。
  • dest - parse_args() が返すオブジェクトに追加される属性名。

以下の節では各オプションの利用方法を説明します。

name または flags

add_argument() メソッドは、指定されている引数が -f や --foo のようなオプション引数なのか、ファイル名リストなどの位置引数なのかを知る必要があります。そのため、add_argument() の第1引数は、フラグのリストか、シンプルな引数名のどちらかになります。例えば、オプション引数は次のようにして作成します:

>>> 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 キーワード引数で指定された値を格納します。'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')
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)

  • '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

Action のサブクラスまたは同じインターフェイスを実装したほかのオブジェクト渡すことで、任意のアクションを指定することもできます。これをするお奨めの方法は、 argparse.Action を継承して、 __call__ と、必要であれば __init__ をオーバライドすることです。

カスタムアクションの例です:

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super(FooAction, self).__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

  • argparse.REMAINDER -- コマンドライン引数の残りすべてをリストとして集めます。これは他のコマンドラインツールに対して処理を渡すようなツールによく使われます。例えば:

    >>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo')
>>> parser.add_argument('command')
>>> parser.add_argument('args', nargs=argparse.REMAINDER)
>>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()))
Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')

nargs キーワード引数が指定されない場合、受け取る引数の数は action によって決定されます。通常これは、1つのコマンドライン引数は1つのアイテムになる (リストにはならない) ことを意味します。

const

add_argument() の const 引数は、コマンドライン引数から読み込まれないけれども ArgumentParser のいくつかのアクションで必要とされる値のために使われます。この引数のよくある2つの使用法は:

  • add_argument() が action='store_const' か action='append_const' で呼び出されたとき、これらのアクションは const の値を parse_args() が返すオブジェクトの属性に追加します。サンプルは action の説明を参照してください。
  • add_argument() がオプション文字列 (-f や --foo) と nargs='?' で呼び出された場合。この場合0個か1つのコマンドライン引数を取るオプション引数が作られます。オプション引数にコマンドライン引数が続かなかった場合、 const の値が代わりに利用されます。サンプルは nargs の説明を参照してください。

'store_const' と 'append_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)

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)

Providing default=argparse.SUPPRESS causes no attribute to be added if the command-line argument was not present:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')

type

デフォルトでは、ArgumentParser オブジェクトはコマンドライン引数を単なる文字列として読み込みます。しかし、コマンドラインの文字列は float, int など別の型として扱うべき事がよくあります。add_argument() の type キーワード引数により型チェックと型変換を行うことができます。一般的なビルトインデータ型や関数を type 引数の値として直接指定できます:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=open)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)

type 引数がデフォルト引数に適用されている場合の情報は、default キーワード引数の節を参照してください。

いろいろな種類のファイルを簡単に扱うために、 argparse モジュールは open() 関数の mode=, bufsize=, encoding= および errors= 引数を取る FileType ファクトリを提供しています。例えば、書き込み可能なファイルを作るために FileType('w') を利用できます:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)

type= には1つの文字列を引数に受け取って変換結果を返すような任意の呼び出し可能オブジェクトを渡すことができます:

>>> def perfect_square(string):
...     value = int(string)
...     sqrt = math.sqrt(value)
...     if sqrt != int(sqrt):
...         msg = "%r is not a perfect square" % string
...         raise argparse.ArgumentTypeError(msg)
...     return value
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square

さらに、choices キーワード引数を使って、値の範囲をチェックすることもできます:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=range(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)

詳細は 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)

in 演算をサポートしている任意のオブジェクトを choices に渡すことができます。すなわち、dict 、 set、カスタムコンテナーなどはすべてサポートされています。

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: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required

上の例のように、引数が 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

optional arguments:
 -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)

optional arguments:
 -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]

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

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

optional arguments:
 -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]

optional arguments:
 -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 に属性をセットすることでしょう。

parse_args() メソッド

ArgumentParser.parse_args(args=None, namespace=None)

引数の文字列をオブジェクトに変換し、namespace オブジェクトの属性に代入します。結果の namespace オブジェクトを返します。

事前の add_argument() メソッドの呼び出しにより、どのオブジェクトが生成されてどう代入されるかが決定されます。詳細は add_argument() のドキュメントを参照してください。

  • args - List of strings to parse. The default is taken from sys.argv.
  • namespace - An object to take the attributes. The default is a new empty Namespace object.

オプション値の文法

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)

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

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() が属性を格納して返すためのオブジェクトにデフォルトで使用されるシンプルなクラスです。

デフォルトでは、 parse_args() は Namespace の新しいオブジェクトに必要な属性を設定して返します。このクラスはシンプルに設計されており、単に読みやすい文字列表現を持った 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_string][, 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 - Whether or not a subcommand must be provided, by default False.
  • 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

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

optional arguments:
  -h, --help  show this help message and exit

>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]

optional arguments:
  -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} ...

optional arguments:
  -h, --help  show this help message and exit

subcommands:
  valid subcommands

  {foo,bar}   additional help

さらに、add_parser は aliases 引数もサポートしており、同じサブパーサーに対して複数の文字列で参照することもできます。以下の例では svn のように checkout の短縮形として co を使用できるようにしています:

>>> 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()
>>>
>>> # 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')

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 で追加: encoding および 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

ユーザー定義グループにないすべての引数は通常の "位置引数" と "オプション引数" セクションに表示されます。

相互排他

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

現在のところ、相互排他引数グループは add_argument_group() の title と description 引数をサポートしていません。

パーサーのデフォルト値

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 つの引数として扱えます。次の例でその方法を示します:

class MyArgumentParser(argparse.ArgumentParser):
    def convert_arg_line_to_args(self, arg_line):
        return arg_line.split()

終了メソッド

ArgumentParser.exit(status=0, message=None)

このメソッドは、message が指定されていればそれを表示した後、指定された終了ステータス status でプログラムを終了します。

ArgumentParser.error(message)

このメソッドは message を含む使用法メッセージを標準エラーに表示して、終了ステータス 2 でプログラムを終了します。

Intermixed parsing

ArgumentParser.parse_intermixed_args(args=None, namespace=None)
ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)

A number of Unix commands allow the user to intermix optional arguments with positional arguments. The parse_intermixed_args() and parse_known_intermixed_args() methods support this parsing style.

These parsers do not support all the argparse features, and will raise exceptions if unsupported features are used. In particular, subparsers, argparse.REMAINDER, and mutually exclusive groups that include both optionals and positionals are not supported.

The following example shows the difference between parse_known_args() and parse_intermixed_args(): the former returns ['2', '3'] as unparsed arguments, while the latter collects all the positionals into 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() returns a two item tuple containing the populated namespace and the list of remaining argument strings. parse_intermixed_args() raises an error if there are any remaining unparsed argument strings.

バージョン 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() の呼び出しに置き換える。
  • Replace (options, args) = parser.parse_args() with args = parser.parse_args() and add additional ArgumentParser.add_argument() calls for the positional arguments. Keep in mind that what was previously called options, now in the argparse context is called args.
  • Replace optparse.OptionParser.disable_interspersed_args()
by using parse_intermixed_args() instead of
parse_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>') に置き換える

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 汎用オペレーティングシステムサービス »


getopt --- C 言語スタイルのコマンドラインオプションパーサ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

getopt --- C 言語スタイルのコマンドラインオプションパーサ

ソースコード: Lib/getopt.py

注釈

getopt モジュールは、C 言語の getopt() 関数に慣れ親しんだ人ためにデザインされた API を持つコマンドラインオプションのパーサです。getopt() 関数に慣れ親しんでない人や、コードを少なくしてよりよいヘルプメッセージを表示させたい場合は、argparse モジュールの使用を検討してください。

このモジュールは sys.argv に入っているコマンドラインオプションの構文解析を支援します。'-' や '--' の特別扱いも含めて、Unix の getopt() と同じ記法をサポートしています。3番目の引数 (省略可能) を設定することで、GNU のソフトウェアでサポートされているような長形式のオプションも利用できます。

このモジュールは2つの関数と1つの例外を提供しています:

getopt.getopt(args, shortopts, longopts=[])

コマンドラインオプションとパラメータのリストを構文解析します。args は構文解析の対象になる引数のリストです。これは先頭のプログラム名を除いたもので、通常 sys.argv[1:] で与えられます。shortopts はスクリプトで認識させたいオプション文字と、引数が必要な場合にはコロン (':') をつけます。つまり Unix の getopt() と同じフォーマットになります。

注釈

GNU の getopt() とは違って、オプションでない引数の後は全てオプションではないと判断されます。これは GNUでない、Unix システムの挙動に近いものです。

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() 関数はオプションでない引数を見つけると解析を停止します。

オプション文字列の最初の文字を '+' にするか、環境変数 POSIXLY_CORRECT を設定することで、オプションでない引数を見つけると解析を停止するように振舞いを変えることができます。

exception getopt.GetoptError

引数リストの中に認識できないオプションがあった場合か、引数が必要なオプションに引数が与えられなかった場合に発生します。例外の引数は原因を示す文字列です。長形式のオプションについては、不要な引数が与えられた場合にもこの例外が発生します。 msg 属性と opt 属性で、エラーメッセージと関連するオプションを取得できます。特に関係するオプションが無い場合には opt は空文字列となります。

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.config --- ロギングの環境設定

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

logging.config --- ロギングの環境設定

ソースコード: 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() はちょうどデフォルトの、カスタマイズされていない状態のように呼び出せます。

バージョン 3.2 で追加.

logging.config.fileConfig(fname, defaults=None, disable_existing_loggers=True)

ログ記録の環境設定を configparser 形式ファイルから読み出します。そのファイルの形式は 環境設定ファイルの書式 で記述されているとおりにしなければなりません。この関数はアプリケーションから何度も呼び出すことができ、これによって、 (設定を選択し、選択された設定を読み出す機構をデベロッパが提供していれば) 複数の準備済みの設定からエンドユーザが選択するようにできます。

パラメータ:
  • fname -- ファイル名、あるいはファイルのようなオブジェクト、または RawConfigParser 派生のインスタンス。 RawConfigParser 派生のインスタンスが与えられれば、それはそのまま使われます。そうでない場合 Configparser がインスタンス化され、設定はそれを使って fname が指すオブジェクトから読み込まれます。それが readline() メソッドを持っていればそれはファイルのようなオブジェクトと仮定され、 read_file() で読み込まれます; そうでない場合、それはファイル名と仮定されて、 read() に渡されます。
  • defaults -- ConfigParser に渡されるデフォルト値をこの引数で指定することができます。
  • disable_existing_loggers -- If specified as False, loggers which exist when this call is made are left enabled. The default is True because this enables old behaviour in a backward-compatible way. This behaviour is to disable any existing loggers unless they or their ancestors are explicitly named in the logging configuration.

バージョン 3.4 で変更: fname として RawConfigParser のサブクラスのインスタンスが渡せ得るようになっています。これによってこのようなことが容易になります:

  • ロギングの設定が、アプリケーション全体の設定における単なる一部であるような設定ファイルの使用。
  • ファイルから設定を読み込み、 fileConfig に通す前に(例えばコマンドラインパラメータやランタイム環境の他のなにかで)アプリケーションによって修正するようなこと。
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 引数が追加されました。

注釈

If you want to send configurations to the listener which don't disable existing loggers, you will need to use a JSON format for the configuration, which will use dictConfig() for configuration. This method allows you to specify disable_existing_loggers as False in the configuration you send.

logging.config.stopListening()

listen() を呼び出して作成された、待ち受け中のサーバを停止します。通常 listen() の戻り値に対して join() が呼ばれる前に呼び出します。

環境設定辞書スキーマ

ロギング設定を記述するには、生成するさまざまなオブジェクトと、それらのつながりを列挙しなければなりません。例えば、 'console' という名前のハンドラを生成し、'startup' という名前のロガーがメッセージを 'console' ハンドラに送るというようなことを記述します。これらのオブジェクトは、 logging モジュールによって提供されるものに限らず、独自のフォーマッタやハンドラクラスを書くことも出来ます。このクラスへのパラメータは、 sys.stderr のような外部オブジェクトを必要とすることもあります。これらのオブジェクトとつながりを記述する構文は、以下の オブジェクトの接続 で定義されています。

辞書スキーマの詳細

dictConfig() に渡される辞書は、以下のキーを含んでいなければなりません:

  • version - スキーマのバージョンを表す整数値に設定されます。現在有効な値は 1 だけですが、このキーがあることで、このスキーマは後方互換性を保ちながら発展できます。

その他すべてのキーは省略可能ですが、与えられたなら以下に記述するように解釈されます。以下のすべての場合において、 '環境設定辞書' と記載されている所では、その辞書に特殊な '()' キーがあるかを調べることで、カスタムのインスタント化が必要であるか判断されます。その場合は、以下の ユーザ定義オブジェクト で記述されている機構がインスタンス生成に使われます。そうでなければ、インスタンス化するべきものを決定するのにコンテキストが使われます。

  • formatters - 対応する値は辞書で、そのそれぞれのキーがフォーマッタ id になり、それぞれの値が対応する Formatter インスタンスをどのように環境設定するかを記述する辞書になります。

    環境設定辞書から、 (デフォルトが None の) キー format と datefmt を検索し、それらが Formatter インスタンスを構成するのに使われます。

  • filters - 対応する値は辞書で、そのそれぞれのキーがフィルタ id になり、それぞれの値が対応する Filter インスタンスをどのように環境設定するかを記述する辞書になります。

    環境設定辞書は、(デフォルトが空文字列の) キー name を検索され、それらが logging.Filter インスタンスを構成するのに使われます。

  • handlers - 対応する値は辞書で、そのそれぞれのキーがハンドラ id になり、それぞれの値が対応する Handler インスタンスをどのように環境設定するかを記述する辞書になります。

    環境設定辞書は、以下のキーを検索されます:

    • class (必須)。これはハンドラクラスの完全に修飾された名前です。
    • level (任意)。ハンドラのレベルです。
    • formatter (任意)。このハンドラへのフォーマッタの id です。
    • 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 のリストです。
    • handlers (任意)。このロガーへのハンドラの id のリストです。

    指定されたロガーは、指定されたレベル、伝播、ハンドラに従って環境設定されます。

  • root - これは、ルートロガーへの設定になります。この環境設定の進行は、propagate 設定が適用されないことを除き、他のロガーと同じです。

  • incremental - この環境設定が既存の環境設定に対する増分として解釈されるかどうかです。この値のデフォルトは False で、指定された環境設定は、既存の fileConfig() API によって使われているのと同じ意味上で、既存の環境設定を置き換えます。

    指定された値が True なら、環境設定は 増分設定 の節で記述されているように進行します。

  • disable_existing_loggers - whether any existing loggers are to be disabled. This setting mirrors the parameter of the same name in fileConfig(). If absent, this parameter defaults to True. This value is ignored if incremental is 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)

キー '()' が特殊キーとして使われるのは、キーワードパラメータ名として不正で、呼び出しに使われるキーワード引数と衝突し得ないからです。'()' はまた、対応する値が呼び出し可能オブジェクトであると覚えやすくします。

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

環境設定が、例えば 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 を取って、適切な送信先オブジェクトを決定します。

However, a more generic mechanism is needed for user-defined objects which are not known to the logging module. For example, consider logging.handlers.MemoryHandler, which takes a target argument which is another handler to delegate to. Since the system already knows about this class, then in the configuration, the given target just needs to be the object id of the relevant target handler, and the system will resolve to the handler from the id. If, however, a user defines a my.package.MyHandler which has an alternate handler, the configuration system would not know that the alternate referred to a handler. To cater for this, a generic resolution system allows the user to specify:

handlers:
  file:
    # configuration of file handler goes here

  custom:
    (): my.package.MyHandler
    alternate: cfg://handlers.file

The literal string 'cfg://handlers.file' will be resolved in an analogous way to strings with the ext:// prefix, but looking in the configuration itself rather than the import namespace. The mechanism allows access by dot or by index, in a similar way to that provided by str.format. Thus, given the following snippet:

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.

文字列 'cfg://handlers' は、キー handlers をもつ辞書であると分析され、文字列 'cfg://handlers.email' は、handlers 辞書内の、email キーをもつ辞書であると分析されます。文字列 'cfg://handlers.email.toaddrs[1] は、'dev_team@domain.tld' と分析され、'cfg://handlers.email.toaddrs[0]' は値 'support_team@domain.tld' と分析されます。subject の値には、'cfg://handlers.email.subject' または等価な 'cfg://handlers.email[subject]' でアクセスできます。後者が必要なのは、キーがスペースや非アルファベット文字を含むときのみです。インデックス値が十進数字のみで構成されているなら、まず対応する整数値を使ってアクセスが試みられ、必要なら文字列値で代替します。

文字列 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() でラップする必要はありません。

環境設定ファイルの書式

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 パッケージの名前空間のコンテキストにおいて eval() されます。

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] セクションになくてはならず、対応するセクションが設定ファイル中になければなりません。

The args entry, when eval()uated in the context of the logging package's namespace, is the list of arguments to the constructor for the handler class. Refer to the constructors for the relevant handlers, or to the examples below, to see how typical entries are constructed. If not provided, it defaults to ().

The optional kwargs entry, when eval()uated in the context of the logging package's namespace, is the keyword argument dict to the constructor for the handler class. If not provided, it defaults to {}.

[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
datefmt=
class=logging.Formatter

The format entry is the overall format string, and the datefmt entry is the strftime()-compatible date/time format string. If empty, the package substitutes something which is almost equivalent to specifying the date format string '%Y-%m-%d %H:%M:%S'. This format also specifies milliseconds, which are appended to the result of using the above format string, with a comma separator. An example time in this format is 2003-01-23 00:29:50,411.

class エントリはオプションです。これはフォーマッタクラスの名前を (モジュール名とクラス名をドットでつないだもので) 指し示すものです。このオプションは Formatter の子クラスをインスタンス化するのに便利です。 Formatter の子クラスが、展開もしくは要約された形式の例外トレースバックを表示することができます。

注釈

eval() を使用していることで、上述のようにソケット経由で設定を送受信するために listen() を使用していることに起因する潜在的なセキュリティリスクがあります。そのリスクは、相互に信頼できない多数のユーザが同じマシン上でコードを実行する場合に制限されています; 詳細は listen() ドキュメンテーションを参照してください。

参考

logging モジュール
logging モジュールの API リファレンス。
logging.handlers モジュール
logging モジュールに含まれる、便利なハンドラです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 汎用オペレーティングシステムサービス »


logging.handlers --- ロギングハンドラ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

logging.handlers --- ロギングハンドラ

ソースコード: 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)

フォーマッタが指定されていれば、フォーマッタを使ってレコードを書式化します。 次に、レコードが終端記号とともにストリームに書き込まれます。 例外情報が存在する場合、 traceback.print_exception() を使って書式化され、 ストリームの末尾につけられます。

flush()

ストリームの flush() メソッドを呼び出してバッファをフラッシュします。 close() メソッドは Handler から継承しているため何も出力を行わないので、 flush() 呼び出しを明示的に行う必要があるかもしれません。

setStream(stream)

Sets the instance's stream to the specified value, if it is different. The old stream is flushed before the new stream is set.

パラメータ: stream -- The stream that the handler should use.
戻り値: the old stream, if the stream was changed, or None if it wasn't.

バージョン 3.7 で追加.

バージョン 3.2 で変更: StreamHandler クラスに terminator 属性が追加されました (デフォルト値は '\n')。これは、書式化されたレコードをストリームに書き込むときの終端記号として使用されます。このような改行による終端を望まなければ、ハンドラ・インスタンスの terminator 属性を空の文字列に設定することができます。初期のバージョンでは、終端記号は '\n' としてハードコードされていました。

FileHandler

logging コアパッケージに含まれる FileHandler クラスは、ログ出力をディスク上のファイルに送信します。このクラスは出力機能を StreamHandler から継承しています。

class logging.FileHandler(filename, mode='a', encoding=None, delay=False)

FileHandler クラスの新たなインスタンスを返します。 指定されたファイルが開かれ、ログ記録のためのストリームとして使われます。 mode が指定されなかった場合、 'a' が使われます。 encoding が None でない場合、その値はファイルを開くときのエンコーディングとして使われます。 delay が真ならば、ファイルを開くのは最初の emit() 呼び出しまで遅らせられます。 デフォルトでは、ファイルは無制限に大きくなりつづけます。

バージョン 3.6 で変更: As well as string values, Path objects are also accepted for the filename argument.

close()

ファイルを閉じます。

emit(record)

record をファイルに出力します。

NullHandler

バージョン 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)

WatchedFileHandler クラスの新たなインスタンスを返します。 指定されたファイルが開かれ、ログ記録のためのストリームとして使われます。 mode が指定されなかった場合、 'a' が使われます。 encoding が None でない場合、その値はファイルを開くときのエンコーディングとして使われます。 delay が真ならば、ファイルを開くのは最初の emit() 呼び出しまで遅らせられます。 デフォルトでは、ファイルは無制限に大きくなりつづけます。

バージョン 3.6 で変更: As well as string values, Path objects are also accepted for the filename argument.

reopenIfNeeded()

Checks to see if the file has changed. If it has, the existing stream is flushed and closed and the file opened again, typically as a precursor to outputting the record to the file.

バージョン 3.6 で追加.

emit(record)

Outputs the record to the file, but first calls reopenIfNeeded() to reopen the file if it has changed.

BaseRotatingHandler

logging.handlers モジュールに存在する BaseRotatingHandler クラスは、ローテートを行うファイルハンドラ RotatingFileHandler と TimedRotatingFileHandler のベースクラスです。このクラスをインスタンス化する必要はありませんが、オーバーライドすることになるかもしれない属性とメソッドを持っています。

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False)

パラメータは FileHandler と同じです。属性は次の通りです:

namer

この属性に callable がセットされた場合、 rotation_filename() メソッドはこの callable に委譲されます。 callable に渡されるパラメータは rotation_filename() に渡されたものです。

注釈

namer 関数はロールオーバー中にかなりの回数呼ばれます。そのため、できるだけ単純で、速くあるべきです。さらに、それは与えられた入力に対しては常に同じ出力を返すべきです。そうでなければ、ロールオーバーの振る舞いは期待通りに動かないかもしれません。

バージョン 3.3 で追加.

rotator

この属性に callable がセットされた場合、 rotate() メソッドはこの callable に委譲されます。 callable に渡されるパラメータは rotate() に渡されたものです。

バージョン 3.3 で追加.

rotation_filename(default_name)

ローテートを行う際にログファイルのファイル名を変更します。

このメソッドは、ファイル名をカスタマイズするために提供されます。

デフォルト実装は、ハンドラの 'namer' 属性が callable だった場合、その callable を呼んでデフォルト名を渡します。属性が callable でない場合 (デフォルトは None です)、名前は変更せずに返されます。

パラメータ: default_name -- ログファイルのデフォルトのファイル名。

バージョン 3.3 で追加.

rotate(source, dest)

ローテートが行われる時、現在のログをローテートします。

デフォルト実装は、 ハンドラの 'rotator' 属性が callable だった場合、その callable を呼んで source と dest 引数を渡します。属性が callable でない場合 (デフォルトは None です)、単に source が destination に改名されます。

パラメータ:
  • source -- ソースファイル名。これは通常ベースファイル名 、例えば 'test.log' となります。
  • dest -- 変更先ファイル名。これは通常ソースファイルをローテートしたもの (例えば 'test.log.1') です。

バージョン 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)

RotatingFileHandler クラスの新たなインスタンスを返します。 指定されたファイルが開かれ、ログ記録のためのストリームとして使われます。 mode が指定されなかった場合、 'a' が使われます。 encoding が None でない場合、その値はファイルを開くときのエンコーディングとして使われます。 delay が真ならば、ファイルを開くのは最初の emit() 呼び出しまで遅らせられます。 デフォルトでは、ファイルは無制限に大きくなりつづけます。

You can use the maxBytes and backupCount values to allow the file to rollover at a predetermined size. When the size is about to be exceeded, the file is closed and a new file is silently opened for output. Rollover occurs whenever the current log file is nearly maxBytes in length; but if either of maxBytes or backupCount is zero, rollover never occurs, so you generally want to set backupCount to at least 1, and have a non-zero maxBytes. When backupCount is non-zero, the system will save old log files by appending the extensions '.1', '.2' etc., to the filename. For example, with a backupCount of 5 and a base file name of app.log, you would get app.log, app.log.1, app.log.2, up to app.log.5. The file being written to is always app.log. When this file is filled, it is closed and renamed to app.log.1, and if files app.log.1, app.log.2, etc. exist, then they are renamed to app.log.2, app.log.3 etc. respectively.

バージョン 3.6 で変更: As well as string values, Path objects are also accepted for the filename argument.

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)

TimedRotatingFileHandler クラスの新たなインスタンスを返します。 filename に指定したファイルを開き、ログ出力先のストリームとして使います。ログファイルのローテーション時には、ファイル名に拡張子 (suffix) をつけます。ログファイルのローテーションは when および interval の積に基づいて行います。

when は interval の単位を指定するために使います。使える値は下表の通りです。大小文字の区別は行いません。

値 | interval の単位 | If/how atTime is used
'S' | 秒 | 無視
'M' | 分 | 無視
'H' | 時間 | 無視
'D' | 日 | 無視
'W0'-'W6' | 曜日 (0=月曜) | Used to compute initial rollover time
'midnight' | Roll over at midnight, if atTime not specified, else at time atTime | Used to compute initial rollover time

曜日ベースのローテーションを使う場合は、月曜として 'W0' を、火曜として 'W1' を、…、日曜として 'W6' を指定します。このケースの場合は、 interval は使われません。

古いログファイルの保存時、ロギングシステムによりファイル名に拡張子が付けられます。 ロールオーバ間隔によって、strftime の %Y-%m-%d_%H-%M-%S 形式またはその前方の一部を使って、日付と時間に基づいた拡張子が付けられます。

最初に次のロールオーバー時間を計算するとき (ハンドラが生成されるとき)、次のローテーションがいつ起こるかを計算するために、既存のログファイルの最終変更時刻または現在の時間が使用されます。

utc 引数が true の場合時刻は UTC になり、それ以外では現地時間が使われます。

backupCount がゼロでない場合、保存されるファイル数は高々 backupCount 個で、それ以上のファイルがロールオーバされる時に作られるならば、一番古いものが削除されます。削除のロジックは interval で決まるファイルを削除するので、 interval を変えると古いファイルが残ったままになることもあります。

delay が true なら、ファイルを開くのは emit() の最初の呼び出しまで延期されます。

If atTime is not None, it must be a datetime.time instance which specifies the time of day when rollover occurs, for the cases where rollover is set to happen "at midnight" or "on a particular weekday". Note that in these cases, the atTime value is effectively used to compute the initial rollover, and subsequent rollovers would be calculated via the normal interval calculation.

注釈

Calculation of the initial rollover time is done when the handler is initialised. Calculation of subsequent rollover times is done only when rollover occurs, and rollover occurs only when emitting output. If this is not kept in mind, it might lead to some confusion. For example, if an interval of "every minute" is set, that does not mean you will always see log files with times (in the filename) separated by a minute; if, during application execution, logging output is generated more frequently than once a minute, then you can expect to see log files with times separated by a minute. If, on the other hand, logging messages are only output once every five minutes (say), then there will be gaps in the file times corresponding to the minutes where no output (and hence no rollover) occurred.

バージョン 3.4 で変更: atTime パラメータが追加されました。

バージョン 3.6 で変更: As well as string values, Path objects are also accepted for the filename argument.

doRollover()

上述のような方法でロールオーバを行います。

emit(record)

上で説明した方法でロールオーバを行いながら、レコードをファイルに出力します。

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 してから先頭に長さ情報を付けてバイナリ形式にして、ソケットを介して送信できるようにして返します。

pickle が完全に安全というわけではないことに注意してください。セキュリティに関して心配なら、より安全なメカニズムを実装するためにこのメソッドをオーバーライドすると良いでしょう。例えば、 HMAC を使って pickle に署名して、受け取る側ではそれを検証することができます。あるいはまた、受け取る側でグローバルなオブジェクトの unpickle を無効にすることができます。

send(packet)

pickle された文字列 packet をソケットに送信します。この関数はネットワークがビジーの時に発生する部分的送信に対応しています。

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 クラスのインスタンスを生成して返します。

バージョン 3.4 で変更: If port is specified as None, a Unix domain socket is created using the value in host - otherwise, a UDP socket is created.

emit()

レコードの属性辞書を pickle して、バイナリ形式でソケットに書き込みます。ソケット操作でエラーが生じた場合、暗黙のうちにパケットは捨てられます。事前に接続が失われていた場合、接続を再度確立します。受信端でレコードを unpickle して LogRecord にするには、 makeLogRecord() 関数を使ってください。

makeSocket()

ここで SocketHandler のファクトリメソッドをオーバライドして、 UDP ソケット (socket.SOCK_DGRAM) を生成しています。

send(s)

pickle された文字列をソケットに送信します。

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 オプションを使用する必要があります。

バージョン 3.2 で変更: socktype が追加されました。

close()

遠隔ホストへのソケットを閉じます。

emit(record)

レコードは書式化された後、 syslog サーバに送信されます。例外情報が存在しても、サーバには 送信されません 。

バージョン 3.2.1 で変更: (See: bpo-12168.) In earlier versions, the message sent to the syslog daemons was always terminated with a NUL byte, because early versions of these daemons expected a NUL terminated message - even though it's not in the relevant specification ( RFC 5424). More recent versions of these daemons don't expect the NUL byte but strip it off if it's there, and even more recent daemons (which adhere more closely to RFC 5424) pass the NUL byte on as part of the message.

このような異なるデーモンの振る舞いすべてに対して syslog メッセージの取り扱いをより容易にするため、 NUL バイトの追加はクラスレベル属性 append_nul を使用して設定できるようになりました。これはデフォルトで True (既存の振る舞いを保持) ですが、 SysLogHandler インスタンスが NUL 終端文字を追加 しない ように False にセットすることができます。

バージョン 3.3 で変更: (参照: 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 で追加: timeout 引数が追加されました。

emit(record)

レコードを書式化し、指定されたアドレスに送信します。

getSubject(record)

レコードに応じたサブジェクト行を指定したいなら、このメソッドをオーバライドしてください。

MemoryHandler

logging.handlers モジュールに含まれる MemoryHandler は、ログ記録するレコードをメモリ上にバッファリングし、定期的にその内容をターゲット (target) となるハンドラにフラッシュする機能をサポートしています。フラッシュ処理はバッファが一杯になるか、ある深刻度かそれ以上のレベルを持つイベントが観測された際に行われます。

MemoryHandler はより一般的な抽象クラス、 BufferingHandler のサブクラスです。この抽象クラスでは、ログ記録するレコードをメモリ上にバッファリングします。各レコードがバッファに追加される毎に、 shouldFlush() を呼び出してバッファをフラッシュすべきかどうか調べます。フラッシュする必要がある場合、 flush() がフラッシュ処理を行うものと想定されます。

class logging.handlers.BufferingHandler(capacity)

指定した許容量のバッファでハンドラを初期化します。

emit(record)

レコードをバッファに追加します。 shouldFlush() が true を返す場合、バッファを処理するために flush() を呼び出します。

flush()

このメソッドをオーバライドして、自作のフラッシュ動作を実装することができます。このクラスのバージョンのメソッドでは、単にバッファの内容を削除して空にします。

shouldFlush(record)

バッファが許容量に達している場合に true を返します。このメソッドは自作のフラッシュ処理方針を実装するためにオーバライドすることができます。

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

Returns a new instance of the MemoryHandler class. The instance is initialized with a buffer size of capacity. If flushLevel is not specified, ERROR is used. If no target is specified, the target will need to be set using setTarget() before this handler does anything useful. If flushOnClose is specified as False, then the buffer is not flushed when the handler is closed. If not specified or specified as True, the previous behaviour of flushing the buffer will occur when the handler is closed.

バージョン 3.6 で変更: The flushOnClose parameter was added.

close()

flush() を呼び出し、ターゲットを None に設定してバッファを消去します。

flush()

MemoryHandler の場合、フラッシュ処理は単に、バッファされたレコードをターゲットがあれば送信することを意味します。これと異なる動作を行いたい場合、オーバライドしてください。

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

バージョン 3.2 で追加.

logging.handlers モジュールに含まれる QueueHandler クラスは、 queue モジュールや multiprocessing のモジュールで実装されるようなキューにログメッセージを送信する機能をサポートしています。

QueueListener クラスとともに QueueHandler を使うと、ロギングを行うスレッドから分離されたスレッド上でハンドラを動かすことができます。これは、クライアントに対してサービスするスレッドができるだけ速く応答する必要がある一方、別のスレッド上で (SMTPHandler によって電子メールを送信するような) 潜在的に遅い操作が行われるような、ウェブアプリケーションおよびその他のサービスアプリケーションにおいて重要です。

class logging.handlers.QueueHandler(queue)

QueueHandler クラスの新しいインスタンスを返します。インスタンスは、キューにメッセージを送るように初期化されます。キューは任意のキューのようなオブジェクトが可能です; それはそのまま enqueue() メソッドによって使用されます。そのメソッドはメッセージを送る方法を知っている必要があります。

emit(record)

準備した LogRecord の結果をキューに追加します。

prepare(record)

キューに追加するためレコードを準備します。このメソッドが返したオブジェクトがキューに追加されます。

The base implementation formats the record to merge the message, arguments, and exception information, if present. It also removes unpickleable items from the record in-place.

レコードを dict や JSON 文字列に変換したい場合や、オリジナルのレコードを変更せずに修正済のコピーを送りたい場合は、このメソッドをオーバーライドすると良いでしょう。

enqueue(record)

キューにレコードを put_nowait() を使ってエンキューします; ブロッキングやタイムアウト、あるいはなにか特別なキューの実装を使いたければ、これをオーバライドしてみてください。

QueueListener

バージョン 3.2 で追加.

logging.handlers モジュールに含まれる QueueListener クラスは、 queue モジュールや multiprocessing のモジュールで実装されるようなキューからログメッセージを受信する機能をサポートしています。メッセージは内部スレッドのキューから受信され、同じスレッド上の複数のハンドラに渡されて処理されます。 QueueListener それ自体はハンドラではありませんが、 QueueHandler と連携して動作するのでここで文書化されています。

QueueHandler クラスとともに QueueListener を使うと、ロギングを行うスレッドから分離されたスレッド上でハンドラを動かすことができます。これは、クライアントに対してサービスするスレッドができるだけ速く応答する必要がある一方、別のスレッド上で (SMTPHandler によって電子メールを送信するような) 潜在的に遅い操作が行われるような、ウェブアプリケーションおよびその他のサービスアプリケーションにおいて重要です。

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)

QueueListener クラスの新しいインスタンスを返します。インスタンスは、メッセージの送信先キューと、キュー上に配置されたエントリーを扱うハンドラのリストとともに初期化されます。キューには、任意のキューのようなオブジェクトを使用できます。キューのようなオブジェクトは、そのまま dequeue() メソッドに渡されます。そのメソッドはメッセージをキューから取得する方法を知っている必要があります。 respect_handler_level が True の場合、メッセージをそのハンドラーに渡すかどうかを判断する際、(メッセージに対するレベルと比較して)ハンドラのレベルは尊重されます。False の場合、以前の Python のバージョンと同様に動作し、各メッセージを各ハンドラに常に渡します。

バージョン 3.5 で変更: The respect_handler_levels argument was added.

dequeue(block)

キューからレコードを取り除き、それを返します。ブロッキングすることがあります。

ベース実装は get() を使用します。タイムアウトを有効にしたい場合や、カスタムのキュー実装を使いたい場合は、このメソッドをオーバーライドすると良いでしょう。

prepare(record)

レコードを扱うための準備をします。

この実装は渡されたレコードをそのまま返します。その値をハンドラに渡す前に何らかのカスタムな整列化 (marshalling) あるいはレコードに対する操作を行う必要があれば、このメソッドをオーバーライドすると良いでしょう。

handle(record)

レコードを処理します。

これは、ハンドラをループしてそれらに処理すべきレコードを渡します。ハンドラに渡される実際のオブジェクトは、 prepare() から返されたものです。

start()

リスナーを開始します。

これは、 LogRecord を処理するキューを監視するために、バックグラウンドスレッドを開始します。

stop()

リスナーを停止します。

スレッドに終了するように依頼し、終了するまで待ちます。アプリケーションの終了前にこのメソッドを呼ばないと、いくつかのレコードがキューに残り、処理されなくなるかもしれないことに注意してください。

enqueue_sentinel()

リスナーに停止するように指示するためキューに番兵を書き込みます。この実装は put_nowait() を使用します。タイムアウトを有効にしたい場合や、カスタムのキュー実装を使いたい場合は、このメソッドをオーバーライドすると良いでしょう。

バージョン 3.3 で追加.

参考

logging モジュール
logging モジュールの API リファレンス。
logging.config モジュール
logging モジュールの環境設定 API です。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 汎用オペレーティングシステムサービス »


getpass --- 可搬性のあるパスワード入力機構

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

getpass --- 可搬性のあるパスワード入力機構

ソースコード: Lib/getpass.py

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()

ユーザーの "ログイン名"を返します。

この関数は環境変数 LOGNAME USER LNAME USERNAME の順序でチェックして、最初の空ではない文字列が設定された値を返します。もし、なにも設定されていない場合は pwd モジュールが提供するシステム上のパスワードデータベースから返します。それ以外は、例外が上がります。

一般的に、この関数は os.getlogin() よりも優先されるべきです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 汎用オペレーティングシステムサービス »


curses --- 文字セル表示を扱うための端末操作

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

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.

注釈

version 5.4 から、ncurses ライブラリは nl_langinfo 関数を利用して非 ASCII データをどう解釈するかを決定するようになりました。これは、アプリケーションは locale.setlocale() 関数を呼び出して、Unicode 文字列をシステムの利用可能なエンコーディングのどれかでエンコードする必要があることを意味します。この例では、システムのデフォルトエンコーディングを利用しています:

import locale
locale.setlocale(locale.LC_ALL, '')
code = locale.getpreferredencoding()

この後、str.encode() を呼び出すときに code を利用します。

参考

curses.ascii モジュール
ロケール設定に関わらず ASCII 文字を扱うためのユーティリティ。
curses.panel モジュール
curses ウィンドウにデプス機能を追加するパネルスタック拡張。
curses.textpad モジュール
Emacs ライクなキーバインディングをサポートする編集可能な curses 用テキストウィジェット。
Python で Curses プログラミング
Andrew Kuchling および Eric Raymond によって書かれた、curses を Python で使うためのチュートリアルです。

Python ソースコードの Tools/demo/ ディレクトリには、このモジュールで提供されている curses バインディングを使ったプログラム例がいくつか収められています。

関数

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)

Return the intensity of the red, green, and blue (RGB) components in the color color_number, which must be between 0 and COLORS. Return a 3-tuple, containing the R,G,B values for the given color, which will be between 0 (no component) and 1000 (maximum amount of component).

curses.color_pair(color_number)

指定された色の表示テキストにおける属性値を返します。属性値は A_STANDOUT, A_REVERSE 、およびその他の A_* 属性と組み合わせられています。pair_number() はこの関数の逆です。

curses.curs_set(visibility)

Set the cursor state. visibility can be set to 0, 1, or 2, for invisible, normal, or very visible. If the terminal supports the visibility requested, return the previous cursor state; otherwise raise an exception. On many terminals, the "visible" mode is an underline cursor and the "very visible" mode is a block cursor.

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() は更新を適用し、物理スクリーンを仮想スクリーンに一致させます。

The virtual screen may be updated by a noutrefresh() call after write operations such as addstr() have been performed on a window. The normal refresh() call is simply noutrefresh() followed by doupdate(); if you have to update multiple windows, you can speed performance and perhaps reduce screen flicker by issuing noutrefresh() calls on all windows, followed by a single doupdate().

curses.echo()

echo モードに入ります。echo モードでは、各文字入力はスクリーン上に入力された通りにエコーバックされます。

curses.endwin()

ライブラリの非初期化を行い、端末を通常の状態に戻します。

curses.erasechar()

Return the user's current erase character as a one-byte bytes object. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself.

curses.filter()

The filter() routine, if used, must be called before initscr() is called. The effect is that, during those calls, LINES is set to 1; the capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home string is set to the value of cr. The effect is that the cursor is confined to the current line, and so are screen updates. This may be used for enabling character-at-a-time line editing without touching the rest of the screen.

curses.flash()

スクリーンを点滅します。すなわち、画面を色反転して、短時間でもとにもどします。人によっては、beep() で生成される注意音よりも、このような "目に見えるベル" を好みます。

curses.flushinp()

すべての入力バッファをフラッシュします。この関数は、ユーザによってすでに入力されているが、まだプログラムによって処理されていないすべての先行入力文字を破棄します。

curses.getmouse()

After getch() returns KEY_MOUSE to signal a mouse event, this method should be call to retrieve the queued mouse event, represented as a 5-tuple (id, x, y, z, bstate). id is an ID value used to distinguish multiple devices, and x, y, z are the event's coordinates. (z is currently unused.) bstate is an integer value whose bits will be set to indicate the type of event, and will be the bitwise OR of one or more of the following constants, where n is the button number from 1 to 4: BUTTONn_PRESSED, BUTTONn_RELEASED, BUTTONn_CLICKED, BUTTONn_DOUBLE_CLICKED, BUTTONn_TRIPLE_CLICKED, BUTTON_SHIFT, BUTTON_CTRL, BUTTON_ALT.

curses.getsyx()

Return the current coordinates of the virtual screen cursor as a tuple (y, x). If leaveok is currently True, then return (-1, -1).

curses.getwin(file)

以前の putwin() 呼び出しでファイルに保存されている、ウィンドウ関連データを読み出します。次に、このルーチンはそのデータを使って新たなウィンドウを生成し初期化して、その新規ウィンドウオブジェクトを返します。

curses.has_colors()

端末が色表示を行える場合には True を返します。そうでない場合には False を返します。

curses.has_ic()

端末が文字の挿入/削除機能を持つ場合に True を返します。最近の端末エミュレータはどれもこの機能を持っており、この関数は歴史的な理由のためだけに存在しています。

curses.has_il()

端末が行の挿入/削除機能を持つ場合に True を返します。最近の端末エミュレータはどれもこの機能を持っていて、この関数は歴史的な理由のためだけに存在しています。

curses.has_key(ch)

キー値 ch をとり、現在の端末タイプがその値のキーを認識できる場合に True を返します。

curses.halfdelay(tenths)

Used for half-delay mode, which is similar to cbreak mode in that characters typed by the user are immediately available to the program. However, after blocking for tenths tenths of seconds, raise an exception if nothing has been typed. The value of tenths must be a number between 1 and 255. Use nocbreak() to leave half-delay mode.

curses.init_color(color_number, r, g, b)

Change the definition of a color, taking the number of the color to be changed followed by three RGB values (for the amounts of red, green, and blue components). The value of color_number must be between 0 and COLORS. Each of r, g, b, must be a value between 0 and 1000. When init_color() is used, all occurrences of that color on the screen immediately change to the new definition. This function is a no-op on most terminals; it is active only if can_change_color() returns True.

curses.init_pair(pair_number, fg, bg)

色ペアの定義を変更します。3 つの引数: 変更したい色ペア、前景色の色番号、背景色の色番号、をとります。pair_number は 1 から COLOR_PAIRS -1 の間でなければなりません (0 色ペアは黒色背景に白色前景となるように設定されており、変更することができません)。fg および bg 引数は 0 と COLORS の間でなければなりません。色ペアが以前に初期化されていれば、スクリーンを更新して、指定された色ペアの部分を新たな設定に変更します。

curses.initscr()

Initialize the library. Return a window object which represents the whole screen.

注釈

端末のオープン時にエラーが発生した場合、curses ライブラリによってインタープリタが終了される場合があります。

curses.is_term_resized(nlines, ncols)

resize_term() によってウィンドウ構造が変更されている場合に True を、そうでない場合は False を返します。

curses.isendwin()

endwin() がすでに呼び出されている (すなわち、curses ライブラリが非初期化されてしまっている) 場合に True を返します。

curses.keyname(k)

Return the name of the key numbered k as a bytes object. The name of a key generating printable ASCII character is the key's character. The name of a control-key combination is a two-byte bytes object consisting of a caret (b'^') followed by the corresponding printable ASCII character. The name of an alt-key combination (128--255) is a bytes object consisting of the prefix b'M-' followed by the name of the corresponding ASCII character.

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()

Return a bytes object containing the terminfo long name field describing the current terminal. The maximum length of a verbose description is 128 characters. It is defined only after the call to initscr().

curses.meta(flag)

If flag is True, allow 8-bit characters to be input. If flag is False, allow only 7-bit chars.

curses.mouseinterval(interval)

ボタンが押されてから離されるまでの時間をマウスクリック一回として認識する最大の時間間隔をミリ秒で設定します。返り値は以前の内部設定値になります。デフォルトは 200 ミリ秒 (5 分の 1 秒) です。

curses.mousemask(mousemask)

Set the mouse events to be reported, and return a tuple (availmask, oldmask). availmask indicates which of the specified mouse events can be reported; on complete failure it returns 0. oldmask is the previous value of the given window's mouse event mask. If this function is never called, no mouse events are ever reported.

curses.napms(ms)

ms ミリ秒間スリープします。

curses.newpad(nlines, ncols)

Create and return a pointer to a new pad data structure with the given number of lines and columns. Return a pad as a window object.

A pad is like a window, except that it is not restricted by the screen size, and is not necessarily associated with a particular part of the screen. Pads can be used when a large window is needed, and only a part of the window will be on the screen at one time. Automatic refreshes of pads (such as from scrolling or echoing of input) do not occur. The refresh() and noutrefresh() methods of a pad require 6 arguments to specify the part of the pad to be displayed and the location on the screen to be used for the display. The arguments are pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; the p arguments refer to the upper left corner of the pad region to be displayed and the s arguments define a clipping box on the screen within which the pad region is to be displayed.

curses.newwin(nlines, ncols)
curses.newwin(nlines, ncols, begin_y, begin_x)

Return a new window, whose left-upper corner is at (begin_y, begin_x), and whose height/width is nlines/ncols.

デフォルトでは、ウィンドウは指定された位置からスクリーンの右下まで広がります。

curses.nl()

newlime モードに入ります。このモードはリターンキーを入力中の改行として変換し、出力時に改行文字を復帰 (return) と改行 (line-feed) に変換します。newline モードは初期化時にはオンになっています。

curses.nocbreak()

cbreak モードを終了します。行バッファリングを行う通常の "cooked" モードに戻ります。

curses.noecho()

echo モードを終了します。入力のエコーバックはオフにされます。

curses.nonl()

newline モードを終了します。入力時のリターンキーから改行への変換、および出力時の改行から復帰/改行への低レベル変換を無効化します (ただし、addch('\n') の振る舞いは変更せず、仮想スクリーン上では常に復帰と改行に等しくなります)。変換をオフにすることで、curses は水平方向の動きを少しだけ高速化できることがあります; また、入力中のリターンキーの検出ができるようになります。

curses.noqiflush()

When the noqiflush() routine is used, normal flush of input and output queues associated with the INTR, QUIT and SUSP characters will not be done. You may want to call noqiflush() in a signal handler if you want output to continue as though the interrupt had not occurred, after the handler exits.

curses.noraw()

raw モードから離れます。行バッファリングを行う通常の "cooked" モードに戻ります。

curses.pair_content(pair_number)

要求された色ペアの色を含むタプル (fg, bg) を返します。pair_number は 1 から 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)

Backend function used by resizeterm(), performing most of the work; when resizing the windows, resize_term() blank-fills the areas that are extended. The calling application should fill in these areas with appropriate data. The resize_term() function attempts to resize all windows. However, due to the calling convention of pads, it is not possible to resize these without additional interaction with the application.

curses.resizeterm(nlines, ncols)

現在の標準ウィンドウのサイズを指定された寸法に変更し、curses ライブラリが使用する、その他のウィンドウサイズを記憶しているデータ (特に SIGWINCH ハンドラ) を調整します。

curses.savetty()

resetty() で使用される、バッファ内の端末モードの現在の状態を保存します。

curses.setsyx(y, x)

Set the virtual screen cursor to y, x. If y and x are both -1, then leaveok is set True.

curses.setupterm(term=None, fd=-1)

Initialize the terminal. term is a string giving the terminal name, or None; if omitted or None, the value of the TERM environment variable will be used. fd is the file descriptor to which any initialization sequences will be sent; if not supplied or -1, the file descriptor for sys.stdout will be used.

curses.start_color()

プログラマがカラーを利用したい場合で、かつ他の何らかのカラー操作ルーチンを呼び出す前に呼び出さなくてはなりません。この関数は initscr() を呼んだ直後に呼ぶようにしておくとよいでしょう。

start_color() は 8 つの基本色 (黒、赤、緑、黄、青、マゼンタ、シアン、および白) と、色数の最大値と端末がサポートする色ペアの最大数が入っている、curses モジュールにおける二つのグローバル変数、COLORS および COLOR_PAIRS を初期化します。この関数はまた、色設定を端末のスイッチが入れられたときの状態に戻します。

curses.termattrs()

端末がサポートするすべてのビデオ属性を論理和した値を返します。この情報は、curses プログラムがスクリーンの見え方を完全に制御する必要がある場合に便利です。

curses.termname()

Return the value of the environment variable TERM, as a bytes object, truncated to 14 characters.

curses.tigetflag(capname)

Return the value of the Boolean capability corresponding to the terminfo capability name capname as an integer. Return the value -1 if capname is not a Boolean capability, or 0 if it is canceled or absent from the terminal description.

curses.tigetnum(capname)

Return the value of the numeric capability corresponding to the terminfo capability name capname as an integer. Return the value -2 if capname is not a numeric capability, or -1 if it is canceled or absent from the terminal description.

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[, ...])

Instantiate the bytes object str with the supplied parameters, where str should be a parameterized string obtained from the terminfo database. E.g. tparm(tigetstr("cup"), 5, 3) could result in b'\033[6;4H', the exact result depending on terminal type.

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)

Push ch so the next getch() will return it.

注釈

Only one ch can be pushed before getch() is called.

curses.update_lines_cols()

LINES と COLS についての更新。マニュアルでスクリーンのサイズを変更したことを検知するために有用です。

バージョン 3.5 で追加.

curses.unget_wch(ch)

Push ch so the next get_wch() will return it.

注釈

Only one ch can be pushed before get_wch() is called.

バージョン 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()

Allow use of default values for colors on terminals supporting this feature. Use this to support transparency in your application. The default color is assigned to the color number -1. After calling this function, init_pair(x, curses.COLOR_RED, -1) initializes, for instance, color pair x to a red foreground color on the default background.

curses.wrapper(func, ...)

Initialize curses and call another callable object, func, which should be the rest of your curses-using application. If the application raises an exception, this function will restore the terminal to a sane state before re-raising the exception and generating a traceback. The callable object func is then passed the main window 'stdscr' as its first argument, followed by any other arguments passed to wrapper(). Before calling func, wrapper() turns on cbreak mode, turns off echo, enables the terminal keypad, and initializes colors if the terminal has color support. On exit (whether normally or by exception) it restores cooked mode, turns on echo, and disables the terminal keypad.

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])

Paint at most n characters of the character string str at (y, x) with attributes attr, overwriting anything previously on the display.

window.addstr(str[, attr])
window.addstr(y, x, str[, attr])

Paint the character string str at (y, x) with attributes attr, overwriting anything previously on the display.

注釈

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.

window.attroff(attr)

現在のウィンドウに書き込まれたすべての内容に対し "バックグラウンド" に設定された属性 attr を除去します。

window.attron(attr)

現在のウィンドウに書き込まれたすべての内容に対し "バックグラウンド" に属性 attr を追加します。

window.attrset(attr)

Set the "background" set of attributes to attr. This set is initially 0 (no attributes).

window.bkgd(ch[, attr])

ウィンドウ上の背景プロパティを、attr を属性とする文字 ch に設定します。変更はそのウィンドウ中のすべての文字に以下のようにして適用されます:

  • ウィンドウ中のすべての文字の属性が新たな背景属性に変更されます。
  • 以前の背景文字が出現すると、常に新たな背景文字に変更されます。
window.bkgdset(ch[, attr])

ウィンドウの背景を設定します。ウィンドウの背景は、文字と何らかの属性の組み合わせから成り立ちます。背景情報の属性の部分は、ウィンドウ上に描画されている空白でないすべての文字と組み合わされ (OR され) ます。空白文字には文字部分と属性部分の両方が組み合わされます。背景は文字のプロパティとなり、スクロールや行/文字の挿入/削除操作の際には文字と一緒に移動します。

window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])

Draw a border around the edges of the window. Each parameter specifies the character to use for a specific part of the border; see the table below for more details.

注釈

どの引数も、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)

If flag is True, the next call to refresh() will clear the window completely.

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 を返します。スクリーン上のウィンドウの一部がマウスイベントの発生場所を含むかどうかを調べる上で便利です。

window.encoding

encode メソッドの引数 (Unicode 文字列および文字) で使用されるエンコーディングです。例えば window.subwin() などでサブウィンドウを生成した時、エンコーディング属性は親ウィンドウから継承します。デフォルトでは、そのロケールのエンコーディングが使用されます (locale.getpreferredencoding() 参照)。

バージョン 3.3 で追加.

window.erase()

ウィンドウをクリアします。

window.getbegyx()

左上の角の座標をあらわすタプル (y, x) を返します。

window.getbkgd()

与えられたウィンドウの現在の背景文字と属性のペアを返します。

window.getch([y, x])

Get a character. Note that the integer returned does not have to be in ASCII range: function keys, keypad keys and so on are represented by numbers higher than 255. In no-delay mode, return -1 if there is no input, otherwise wait until a key is pressed.

window.get_wch([y, x])

Get a wide character. Return a character for most keys, or an integer for function keys, keypad keys, and other special keys. In no-delay mode, raise an exception if there is no input.

バージョン 3.3 で追加.

window.getkey([y, x])

Get a character, returning a string instead of an integer, as getch() does. Function keys, keypad keys and other special keys return a multibyte string containing the key name. In no-delay mode, raise an exception if there is no input.

window.getmaxyx()

ウィンドウの高さおよび幅を表すタプル (y, x) を返します。

window.getparyx()

Return the beginning coordinates of this window relative to its parent window as a tuple (y, x). Return (-1, -1) if this window has no parent.

window.getstr()
window.getstr(n)
window.getstr(y, x)
window.getstr(y, x, n)

Read a bytes object from the user, with primitive line editing capacity.

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)

If flag is True, curses will try and use hardware line editing facilities. Otherwise, line insertion/deletion are disabled.

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])

Return a bytes object of characters, extracted from the window starting at the current cursor position, or at y, x if specified. Attributes are stripped from the characters. If n is specified, instr() returns a string at most n characters long (exclusive of the trailing NUL).

window.is_linetouched(line)

指定した行が、最後に refresh() を呼んだ時から変更されている場合に True を返します; そうでない場合には False を返します。line が現在のウィンドウ上の有効な行でない場合、curses.error 例外を送出します。

window.is_wintouched()

指定したウィンドウが、最後に refresh() を呼んだ時から変更されている場合に True を返します; そうでない場合には False を返します。

window.keypad(flag)

If flag is True, escape sequences generated by some keys (keypad, function keys) will be interpreted by curses. If flag is False, escape sequences will be left as is in the input stream.

window.leaveok(flag)

If flag is True, cursor is left where it is on update, instead of being at "cursor position." This reduces cursor movement where possible. If possible the cursor will be made invisible.

If flag is False, cursor will always be at "cursor position" after an update.

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)

If flag is True, getch() will be non-blocking.

window.notimeout(flag)

If flag is True, escape sequences will not be timed out.

If flag is False, after a few milliseconds, an escape sequence will not be interpreted, and will be left in the input stream as is.

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)

Control what happens when the cursor of a window is moved off the edge of the window or scrolling region, either as a result of a newline action on the bottom line, or typing the last character of the last line. If flag is False, the cursor is left on the bottom line. If flag is True, the window is scrolled up one line. Note that in order to get the physical scrolling effect on the terminal, it is also necessary to call 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)

If flag is True, then syncup() is called automatically whenever there is a change in the window.

window.syncup()

ウィンドウ内で更新 (touch) した場所を、上位のすべてのウィンドウ内でも更新します。

window.timeout(delay)

Set blocking or non-blocking read behavior for the window. If delay is negative, blocking read is used (which will wait indefinitely for input). If delay is zero, then non-blocking read is used, and getch() will return -1 if no input is waiting. If delay is positive, then getch() will block for delay milliseconds, and return -1 if there is still no input at the end of that time.

window.touchline(start, count[, changed])

Pretend count lines have been changed, starting with line start. If changed is supplied, it specifies whether the affected lines are marked as having been changed (changed=True) or unchanged (changed=False).

window.touchwin()

描画を最適化するために、すべてのウィンドウが変更されたかのように振舞わせます。

window.untouchwin()

ウィンドウ内のすべての行を、最後に refresh() を呼んだ際から変更されていないものとしてマークします。

window.vline(ch, n)
window.vline(y, x, ch, n)

(y, x) から始まり、n の長さを持つ、文字 ch で作られる垂直線を表示します。

定数

curses モジュールでは以下のデータメンバを定義しています:

curses.ERR

getch() のような整数を返す curses ルーチンのいくつかは、失敗した際に ERR を返します。

curses.OK

napms() のような整数を返す curses ルーチンのいくつかは、成功した際に OK を返します。

curses.version

A bytes object representing the current version of the module. Also available as __version__.

Some constants are available to specify character cell attributes. The exact constants available are system dependent.

属性 | 意味
A_ALTCHARSET | Alternate character set mode
A_BLINK | Blink mode
A_BOLD | Bold mode
A_DIM | Dim mode
A_INVIS | Invisible or blank mode
A_ITALIC | Italic mode
A_NORMAL | Normal attribute
A_PROTECT | Protected mode
A_REVERSE | Reverse background and foreground colors
A_STANDOUT | Standout mode
A_UNDERLINE | Underline mode
A_HORIZONTAL | Horizontal highlight
A_LEFT | Left highlight
A_LOW | Low highlight
A_RIGHT | Right highlight
A_TOP | Top highlight
A_VERTICAL | Vertical highlight
A_CHARTEXT | Bit-mask to extract a character

バージョン 3.7 で追加: A_ITALIC was added.

Several constants are available to extract corresponding attributes returned by some methods.

Bit-mask | 意味
A_ATTRIBUTES | Bit-mask to extract attributes
A_CHARTEXT | Bit-mask to extract a character
A_COLOR | Bit-mask to extract color-pair field information

キーは KEY_ で始まる名前をもつ整数定数です。利用可能なキーキャップはシステムに依存します。

キー定数 | キー
KEY_MIN | 最小のキー値
KEY_BREAK | ブレークキー (Break, 信頼できません)
KEY_DOWN | 下矢印
KEY_UP | 上矢印
KEY_LEFT | 左矢印
KEY_RIGHT | 右矢印
KEY_HOME | ホームキー (Home, または上左矢印)
KEY_BACKSPACE | バックスペース (Backspace, 信頼できません)
KEY_F0 | ファンクションキー。64 個までサポートされています。
KEY_Fn | ファンクションキー n の値
KEY_DL | 行削除 (Delete line)
KEY_IL | 行挿入 (Insert line)
KEY_DC | 文字削除 (Delete char)
KEY_IC | 文字挿入、または文字挿入モードへ入る
KEY_EIC | 文字挿入モードから抜ける
KEY_CLEAR | 画面消去
KEY_EOS | 画面の末端まで消去
KEY_EOL | 行末端まで消去
KEY_SF | 前に 1 行スクロール
KEY_SR | 後ろ (逆方向) に 1 行スクロール
KEY_NPAGE | 次のページ (Page Next)
KEY_PPAGE | 前のページ (Page Prev)
KEY_STAB | タブ設定
KEY_CTAB | タブリセット
KEY_CATAB | すべてのタブをリセット
KEY_ENTER | 入力または送信 (信頼できません)
KEY_SRESET | ソフトウェア (部分的) リセット (信頼できません)
KEY_RESET | リセットまたはハードリセット (信頼できません)
KEY_PRINT | 印刷 (Print)
KEY_LL | 下ホーム (Home down) または最下行 (左下)
KEY_A1 | キーパッドの左上キー
KEY_A3 | キーパッドの右上キー
KEY_B2 | キーパッドの中央キー
KEY_C1 | キーパッドの左下キー
KEY_C3 | キーパッドの右下キー
KEY_BTAB | Back tab
KEY_BEG | 開始 (Beg)
KEY_CANCEL | キャンセル (Cancel)
KEY_CLOSE | Close [閉じる]
KEY_COMMAND | コマンド (Cmd)
KEY_COPY | Copy [コピー]
KEY_CREATE | 生成 (Create)
KEY_END | 終了 (End)
KEY_EXIT | Exit [終了]
KEY_FIND | 検索 (Find)
KEY_HELP | ヘルプ (Help)
KEY_MARK | マーク (Mark)
KEY_MESSAGE | メッセージ (Message)
KEY_MOVE | 移動 (Move)
KEY_NEXT | 次へ (Next)
KEY_OPEN | 開く (Open)
KEY_OPTIONS | オプション
KEY_PREVIOUS | 前へ (Prev)
KEY_REDO | Redo [やり直し]
KEY_REFERENCE | 参照 (Ref)
KEY_REFRESH | 更新 (Refresh)
KEY_REPLACE | 置換 (Replace)
KEY_RESTART | 再起動 (Restart)
KEY_RESUME | 再開 (Resume)
KEY_SAVE | Save [保存]
KEY_SBEG | シフト付き Beg
KEY_SCANCEL | シフト付き Cancel
KEY_SCOMMAND | シフト付き Command
KEY_SCOPY | シフト付き Copy
KEY_SCREATE | シフト付き Create
KEY_SDC | シフト付き Delete char
KEY_SDL | シフト付き Delete line
KEY_SELECT | 選択 (Select)
KEY_SEND | シフト付き End
KEY_SEOL | シフト付き Clear line
KEY_SEXIT | シフト付き Exit
KEY_SFIND | シフト付き Find
KEY_SHELP | シフト付き Help
KEY_SHOME | シフト付き Home
KEY_SIC | シフト付き Input
KEY_SLEFT | シフト付き Left arrow
KEY_SMESSAGE | シフト付き Message
KEY_SMOVE | シフト付き Move
KEY_SNEXT | シフト付き Next
KEY_SOPTIONS | シフト付き Options
KEY_SPREVIOUS | シフト付き Prev
KEY_SPRINT | シフト付き Print
KEY_SREDO | シフト付き Redo
KEY_SREPLACE | シフト付き Replace
KEY_SRIGHT | シフト付き Right arrow
KEY_SRSUME | シフト付き Resume
KEY_SSAVE | シフト付き Save
KEY_SSUSPEND | シフト付き Suspend
KEY_SUNDO | シフト付き Undo
KEY_SUSPEND | 一時停止 (Suspend)
KEY_UNDO | Undo [元に戻す]
KEY_MOUSE | マウスイベント通知
KEY_RESIZE | 端末リサイズイベント
KEY_MAX | 最大キー値

VT100 や、X 端末エミュレータのようなソフトウェアエミュレーションでは、通常少なくとも 4 つのファンクションキー (KEY_F1, KEY_F2, KEY_F3, KEY_F4) が利用可能で、矢印キーは KEY_UP, KEY_DOWN, KEY_LEFT および KEY_RIGHT が対応付けられています。計算機に PC キーボードが付属している場合、矢印キーと 12 個のファンクションキー (古い PC キーボードには 10 個しかファンクションキーがないかもしれません) が利用できると考えてよいでしょう; また、以下のキーパッド対応付けは標準的なものです:

キーキャップ | 定数
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 コード | 意味
ACS_BBSS | 右上角の別名
ACS_BLOCK | 黒四角ブロック
ACS_BOARD | 白四角ブロック
ACS_BSBS | 水平線の別名
ACS_BSSB | 左上角の別名
ACS_BSSS | 上向き T 字罫線の別名
ACS_BTEE | 下向き T 字罫線
ACS_BULLET | 黒丸(bullet)
ACS_CKBOARD | チェッカーボードパタン (点描)
ACS_DARROW | 下向き矢印
ACS_DEGREE | 度記号
ACS_DIAMOND | ダイアモンド
ACS_GEQUAL | 大なりイコール
ACS_HLINE | 水平線
ACS_LANTERN | ランタン(lantern) シンボル
ACS_LARROW | 左向き矢印
ACS_LEQUAL | 小なりイコール
ACS_LLCORNER | 左下角
ACS_LRCORNER | 右下角
ACS_LTEE | 左向き T 字罫線
ACS_NEQUAL | 不等号
ACS_PI | パイ記号
ACS_PLMINUS | プラスマイナス記号
ACS_PLUS | 大プラス記号
ACS_RARROW | 右向き矢印
ACS_RTEE | 右向き T 字罫線
ACS_S1 | スキャンライン 1
ACS_S3 | スキャンライン 3
ACS_S7 | スキャンライン 7
ACS_S9 | スキャンライン 9
ACS_SBBS | 右下角の別名
ACS_SBSB | 垂直線の別名
ACS_SBSS | 右向き T 字罫線の別名
ACS_SSBB | 左下角の別名
ACS_SSBS | 下向き T 字罫線の別名
ACS_SSSB | 左向き T 字罫線の別名
ACS_SSSS | 交差罫線または大プラス記号の別名
ACS_STERLING | ポンドスターリング記号
ACS_TTEE | 上向き T 字罫線
ACS_UARROW | 上向き矢印
ACS_ULCORNER | 左上角
ACS_URCORNER | 右上角
ACS_VLINE | 垂直線

以下のテーブルは定義済みの色を列挙したものです:

定数 | 色
COLOR_BLACK | 黒
COLOR_BLUE | 青
COLOR_CYAN | シアン (薄く緑がかった青)
COLOR_GREEN | 緑
COLOR_MAGENTA | マゼンタ (紫がかった赤)
COLOR_RED | 赤
COLOR_WHITE | 白
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)

Return a textbox widget object. The win argument should be a curses window object in which the textbox is to be contained. The edit cursor of the textbox is initially located at the upper left hand corner of the containing window, with coordinates (0, 0). The instance's stripspaces flag is initially on.

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 --- ASCII 文字に関するユーティリティ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

curses.ascii --- ASCII 文字に関するユーティリティ

curses.ascii モジュールでは、 ASCII 文字を指す名前定数と、様々な ASCII 文字区分についてある文字が帰属するかどうかを調べる関数を提供します。このモジュールで提供されている定数は以下の制御文字の名前です:

名前 | 意味
NUL |
SOH | ヘディング開始、コンソール割り込み
STX | テキスト開始
ETX | テキスト終了
EOT | テキスト伝送終了
ENQ | 問い合わせ、 ACK フロー制御時に使用
ACK | 肯定応答
BEL | ベル
BS | 一文字後退
TAB | タブ
HT | TAB の別名: "水平タブ"
LF | 改行
NL | LF の別名: "改行"
VT | 垂直タブ
FF | 改頁
CR | 復帰
SO | シフトアウト、他の文字セットの開始
SI | シフトイン、標準の文字セットに復帰
DLE | データリンクでのエスケープ
DC1 | 装置制御 1、フロー制御のための XON
DC2 | 装置制御 2、ブロックモードフロー制御
DC3 | 装置制御 3、フロー制御のための XOFF
DC4 | 装置制御 4
NAK | 否定応答
SYN | 同期信号
ETB | ブロック転送終了
CAN | キャンセル (Cancel)
EM | 媒体終端
SUB | 代入文字
ESC | エスケープ文字
FS | ファイル区切り文字
GS | グループ区切り文字
RS | レコード区切り文字、ブロックモード終了子
US | 単位区切り文字
SP | 空白文字
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 またはそれ以上の値) かどうかを調べます。

These functions accept either integers or single-character strings; when the argument is a string, it is first converted using the built-in function ord().

Note that all these functions check ordinal bit values derived from the character of the string you pass in; they do not actually know anything about the host machine's character encoding.

以下の 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 --- curses のためのパネルスタック拡張

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

curses.panel --- 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()

Returns True if the panel is hidden (not visible), False otherwise.

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 --- 実行中プラットフォームの固有情報を参照する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

platform --- 実行中プラットフォームの固有情報を参照する

ソースコード: 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インタープリタでない場合には適切なデフォルト値が返ります。

注釈

Mac OS X (とひょっとすると他のプラットフォーム) では、実行可能ファイルは複数のアーキテクチャを含んだユニバーサル形式かもしれません。

現在のインタプリタが "64-bit" であるかどうかを調べるには、 sys.maxsize の方が信頼できます:

is_64bits = sys.maxsize > 2**32
platform.machine()

'i386' のような、機種を返します。不明な場合は空文字列を返します。

platform.node()

コンピュータのネットワーク名を返します。ネットワーク名は完全修飾名とは限りません。不明な場合は空文字列を返します。

platform.platform(aliased=0, terse=0)

実行中プラットフォームを識別する文字列を返します。この文字列には、有益な情報をできるだけ多く付加しています。

戻り値は機械で処理しやすい形式ではなく、人間にとって読みやすい 形式となっています。異なったプラットフォームでは異なった戻り値となるようになっています。

aliased が真なら、システムの名称として一般的な名称ではなく、別名を使用して結果を返します。たとえば、SunOS は Solaris となります。この機能は system_alias() で実装されています。

terse が真なら、プラットフォームを特定するために最低限必要な情報だけを返します。

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', 'Windows', 'Java' のような、システム/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() を返します。

この関数が os.uname() の結果には含まれない 6番目の属性 (processor) を追加することに注意してください。さらに、最初の2つの属性については属性名が異なります; os.uname() はそれらを sysname と nodename と命名します。

不明な項目は '' となります。

バージョン 3.3 で変更: 結果が tuple から namedtuple に変更されました。

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='')

Windows レジストリから追加のバージョン情報を取得して、タプル (release, version, csd, ptype) を返します。それぞれ、OS リリース、バージョン番号、CSD レベル (サービスパック)、OS タイプ (マルチ/シングルプロセッサー) を指しています。

参考: ptype はシングルプロセッサのNT上では 'Uniprocessor Free'、マルチプロセッサでは 'Multiprocessor Free' となります。'Free' がついている場合はデバッグ用のコードが含まれていないことを示し、'Checked' がついていれば引数や範囲のチェックなどのデバッグ用コードが含まれていることを示します。

注釈

この関数は、Mark Hammondの win32all がインストールされた環境で良く動作しますが、Python 2.3 以上なら一応動作します。(Python 2.6からサポートされました) もちろん、この関数が使えるのはWin32互換プラットフォームのみです。

Win95/98 固有

platform.popen(cmd, mode='r', bufsize=-1)

可搬性の高い popen() インターフェースで、可能なら win32pipe.popen() を使用します。 win32pipe.popen() はWindows NTでは利用可能ですが、Windows 9xではハングしてしまいます。

バージョン 3.3 で非推奨: この関数は廃止予定です。 subprocess モジュールを使用してください。特に 古い関数を subprocess モジュールで置き換える セクションをチェックしてください。

Mac OS プラットフォーム

platform.mac_ver(release='', versioninfo=('', '', ''), machine='')

Mac OSのバージョン情報を、タプル (release, versioninfo, machine) で返します。versioninfo は、タプル (version, dev_stage, non_release_version) です。

不明な項目は '' となります。タプルの要素は全て文字列です。

Unix プラットフォーム

platform.dist(distname='', version='', id='', supported_dists=('SuSE', 'debian', 'redhat', 'mandrake', ...))

これは linux_distribution() の別名です。

Deprecated since version 3.5, will be removed in version 3.8: distro パッケージなどの他の選択肢を調べてください。

platform.linux_distribution(distname='', version='', id='', supported_dists=('SuSE', 'debian', 'redhat', 'mandrake', ...), full_distribution_name=1)

OSディストリビューション名の取得を試みます。

supported_dists は、検索するLinuxディストリビューションを定義するために利用します。デフォルトでは、リリースファイル名で定義されている、現在サポートされているLinuxディストリビューションのリストです。

full_distribution_name が True (デフォルト)の場合、OSから読み込まれた完全なディストリビューション名が返されます。それ以外の場合、supported_dists で利用された短い名前が返されます。

戻り値はタプル (distname, version, id) で、不明な項目は引数で指定した値となります。id はバージョン番号に続く括弧内の要素です。これは通常バージョンコードネームです。

Deprecated since version 3.5, will be removed in version 3.8: distro パッケージなどの他の選択肢を調べてください。

platform.libc_ver(executable=sys.executable, lib='', version='', chunksize=16384)

executableで指定したファイル（省略時はPythonインタープリタ）がリンクしているlibcバージョンの取得を試みます。戻り値は文字列のタプル (lib, version) で、不明な項目は引数で指定した値となります。

この関数は、実行形式に追加されるシンボルの細かな違いによって、libcのバージョンを特定します。この違いは gcc でコンパイルされた実行可能ファイルでのみ有効だと思われます。

chunksize にはファイルから情報を取得するために読み込むバイト数を指定します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 汎用オペレーティングシステムサービス »


errno --- 標準の errno システムシンボル

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

errno --- 標準の errno システムシンボル

このモジュールから標準の errno システムシンボルを取得することができます。個々のシンボルの値は errno に対応する整数値です。これらのシンボルの名前は、 linux/include/errno.h から借用されており、かなり網羅的なはずです。

errno.errorcode

errno 値を背後のシステムにおける文字列表現に対応付ける辞書です。例えば、errno.errorcode[errno.EPERM] は 'EPERM' に対応付けられます。

数値のエラーコードをエラーメッセージに変換するには、 os.strerror() を使ってください。

以下のリストの内、現在のプラットフォームで使われていないシンボルはモジュール上で定義されていません。定義されているシンボルだけを挙げたリストは errno.errorcode.keys() として取得することができます。取得できるシンボルには以下のようなものがあります:

errno.EPERM

許可されていない操作です (Operation not permitted)

errno.ENOENT

そのようなファイルまたはディレクトリは存在しません (No such file or directory)

errno.ESRCH

指定したプロセスは存在しません (No such process)

errno.EINTR

システムコールが中断されました (Interrupted system call)

参考

このエラーは例外 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)

errno.EAGAIN

再試行してください (Try again)

errno.ENOMEM

空きメモリがありません (Out of memory)

errno.EACCES

許可がありません (Permission denied)

errno.EFAULT

不正なアドレスです (Bad address)

errno.ENOTBLK

ブロックデバイスが必要です (Block device required)

errno.EBUSY

そのデバイスまたはリソースは使用中です (Device or resource busy)

errno.EEXIST

ファイルがすでに存在します (File exists)

errno.EXDEV

デバイスをまたいだリンクです (Cross-device link)

errno.ENODEV

そのようなデバイスはありません (No such device)

errno.ENOTDIR

ディレクトリではありません (Not a directory)

errno.EISDIR

ディレクトリです (Is a directory)

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)

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)

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

errno.ECONNRESET

接続がピアによってリセットされました (Connection reset by peer)

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)

errno.ETOOMANYREFS

参照が多すぎます: 接続できません (Too many references: cannot splice)

errno.ETIMEDOUT

接続がタイムアウトしました (Connection timed out)

errno.ECONNREFUSED

接続を拒否されました (Connection refused)

errno.EHOSTDOWN

ホストはシステムダウンしています (Host is down)

errno.EHOSTUNREACH

ホストへの経路がありません (No route to host)

errno.EALREADY

すでに処理中です (Operation already in progress)

errno.EINPROGRESS

現在処理中です (Operation now in progress)

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)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 汎用オペレーティングシステムサービス »


ctypes --- Pythonのための外部関数ライブラリ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 汎用オペレーティングシステムサービス »

ctypes --- Pythonのための外部関数ライブラリ

ctypes は Python のための外部関数ライブラリです。このライブラリは C と互換性のあるデータ型を提供し、動的リンク/共有ライブラリ内の関数呼び出しを可能にします。動的リンク/共有ライブラリを純粋な Python でラップするために使うことができます。

ctypesチュートリアル

注意: このチュートリアルのコードサンプルは動作確認のために doctest を使います。コードサンプルの中には Linux、 Windows、あるいは Mac OS X 上で異なる動作をするものがあるため、サンプルのコメントに doctest 命令を入れてあります。

注意: いくつかのコードサンプルで ctypes の c_int 型を参照しています。 sizeof(long) == sizeof(int) であるようなプラットフォームでは、この型は c_long のエイリアスです。そのため、 c_int 型を想定しているときに c_long が表示されたとしても、混乱しないようにしてください --- 実際には同じ型なのです。

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

動的リンクライブラリをロードするために、 ctypes は cdll をエクスポートします。 Windows では windll と oledll オブジェクトをエクスポートします。

これらのオブジェクトの属性としてライブラリにアクセスすることでライブラリをロードします。 cdll は、標準 cdecl 呼び出し規約を用いて関数をエクスポートしているライブラリをロードします。それに対して、 windll ライブラリは stdcall 呼び出し規約を用いる関数を呼び出します。 oledll も stdcall 呼び出し規約を使いますが、関数が Windows HRESULT エラーコードを返すことを想定しています。このエラーコードは関数呼び出しが失敗したとき、 OSError 例外を自動的に送出させるために使われます。

バージョン 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 モジュールをインポートして使用してください。

Linux ではライブラリをロードするために拡張子を 含む ファイル名を指定する必要があるので、ロードしたライブラリに対する属性アクセスはできません。 dll ローダーの LoadLibrary() メソッドを使うか、コンストラクタを呼び出して CDLL のインスタンスを作ることでライブラリをロードするかのどちらかを行わなければなりません:

>>> 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 オブジェクトの属性として関数にアクセスします:

>>> from ctypes import *
>>> 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
>>>

関数を呼び出す

これらの関数は他の Python 呼び出し可能オブジェクトと同じように呼び出すことができます。この例では time() 関数 (Unixエポックからのシステム時間を秒単位で返す) と、 GetModuleHandleA() 関数 (win32モジュールハンドルを返す) を使います。

この例は両方の関数を NULL ポインタとともに呼び出します (None を NULL ポインタとして使う必要があります):

>>> print(libc.time(None))
1150640792
>>> print(hex(windll.kernel32.GetModuleHandleA(None)))
0x1d000000
>>>

注釈

不正な数の引数が渡されたことを検知した場合、 ctypes は関数を呼び出した後に ValueError を送出することがあります。 この動作には依存するべきではありません。 この動作は 3.6.2 で非推奨であり、 3.7 で削除予定です。

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 、整数、バイト列オブジェクトおよび (Unicode) 文字列だけが、こうした関数呼び出しにおいてパラメータとして直接使えるネイティブの Python オブジェクトです。 None は C の NULL ポインタとして渡され、バイト文字列とユニコード文字列はそのデータを含むメモリブロックへのポインタ (char * または wchar_t *) として渡されます。 Python 整数はプラットホームのデフォルトの C int 型として渡され、その値は C int 型に合うようにマスクされます。

他のパラメータ型をもつ関数呼び出しに移る前に、 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 または Py_ssize_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
  1. コンストラクタは任意のオブジェクトをその真偽値として受け取ります。

これら全ての型はその型を呼び出すことによって作成でき、オプションとして型と値が合っている初期化子を指定することができます:

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

create_string_buffer() 関数は初期の ctypes リリースにあった c_string() 関数だけでなく、 (エイリアスとしてはまだ利用できる) c_buffer() 関数をも置き換えるものです。 C の型 wchar_t の Unicode 文字を含む変更可能なメモリブロックを作成するには、 create_unicode_buffer() 関数を使ってください。

続・関数を呼び出す

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

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

自作のクラスのインスタンスを関数引数として使えるように、 ctypes 引数変換をカスタマイズすることもできます。 ctypes は _as_parameter_ 属性を探し出し、関数引数として使います。もちろん、整数、文字列もしくはバイト列オブジェクトの中の一つでなければなりません:

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

_as_parameter_ インスタンス変数にインスタンスのデータを保持したくない場合は、必要に応じて利用できる属性を作る property を定義しても構いません。

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

argtypes 属性を設定することによって、 DLL からエクスポートされている関数に要求される引数の型を指定することができます。

argtypes は C データ型のシーケンスでなければなりません (この場合 printf 関数はおそらく良い例ではありません。なぜなら、引数の数が可変であり、フォーマット文字列に依存した異なる型のパラメータを取るからです。一方では、この機能の実験にはとても便利です)。:

>>> 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: exceptions.TypeError: wrong type
>>> printf(b"%s %d %f\n", b"X", 2, 3)
X 2 3.000000
13
>>>

関数呼び出しへ渡す自作のクラスを定義した場合には、 argtypes シーケンスの中で使えるようにするために、そのクラスに from_param() クラスメソッドを実装しなければなりません。 from_param() クラスメソッドは関数呼び出しへ渡された Python オブジェクトを受け取り、型チェックもしくはこのオブジェクトが受け入れ可能であると確かめるために必要なことはすべて行ってから、オブジェクト自身、 _as_parameter_ 属性、あるいは、この場合に C 関数引数として渡したい何かの値を返さなければなりません。繰り返しになりますが、その返される結果は整数、文字列、バイト列、 ctypes インスタンス、あるいは _as_parameter_ 属性をもつオブジェクトであるべきです。

戻り値の型

デフォルトでは、関数は C int を返すと仮定されます。他の戻り値の型を指定するには、関数オブジェクトの restype 属性に設定します。

さらに高度な例として、 strchr 関数を使います。この関数は文字列ポインタと char を受け取り、文字列へのポインタを返します。:

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

上の ord("x") 呼び出しを避けたいなら、 argtypes 属性を設定することができます。二番目の引数が一文字の Python バイト列オブジェクトから C の char へ変換されます:

>>> strchr.restype = c_char_p
>>> strchr.argtypes = [c_char_p, c_char]
>>> strchr(b"abcdef", b"d")
'def'
>>> strchr(b"abcdef", b"def")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ArgumentError: argument 2: exceptions.TypeError: one character string expected
>>> print(strchr(b"abcdef", b"x"))
None
>>> strchr(b"abcdef", b"d")
'def'
>>>

外部関数が整数を返す場合は、 restype 属性として呼び出し可能な Python オブジェクト (例えば、関数またはクラス) を使うこともできます。呼び出し可能オブジェクトは C 関数が返す 整数 とともに呼び出され、この呼び出しの結果は関数呼び出しの結果として使われるでしょう。これはエラーの戻り値をチェックして自動的に例外を送出させるために役に立ちます。:

>>> 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() を呼び出します。

errcheck 属性によってもっと強力なエラーチェック機構を利用できることに注意してください。詳細はリファレンスマニュアルを参照してください。

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

時には、 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'
>>>

構造体と共用体

構造体と共用体は ctypes モジュールに定義されている Structure および Union ベースクラスからの派生クラスでなければなりません。それぞれのサブクラスは _fields_ 属性を定義する必要があります。 _fields_ は フィールド名 と フィールド型 を持つ 2要素タプル のリストでなければなりません。

フィールド型は 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>
ValueError: 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 環境では動くかもしれませんが、このライブラリでは一般の場合に動作することは保証していません。

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

デフォルトでは、構造体 (Structure) と共用体(Union) のフィールドは C コンパイラが行うのと同じ方法でアライメントされています。サブクラスを定義するときに _pack_ クラス属性を指定することでこの動作を変えることは可能です。このクラス属性には正の整数を設定する必要があり、フィールドの最大アライメントを指定します。これは MSVC で #pragma pack(n) が行っていること同じです。

ctypes は Structure と Union に対してネイティブのバイトオーダーを使います。ネイティブではないバイトオーダーの構造体を作成するには、 BigEndianStructure, LittleEndianStructure, BigEndianUnion および LittleEndianUnion ベースクラスの中の一つを使います。これらのクラスにポインタフィールドを持たせることはできません。

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

ビットフィールドを含む構造体と共用体を作ることができます。ビットフィールドは整数フィールドに対してのみ作ることができ、ビット幅は _fields_ タプルの第三要素で指定します。:

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

型変換

たいていの場合、 ctypes は厳密な型チェックを行います。これが意味するのは、関数の argtypes リスト内に、もしくは、構造体定義におけるメンバーフィールドの型として POINTER(c_int) がある場合、厳密に同じ型のインスタンスだけを受け取るということです。このルールには ctypes が他のオブジェクトを受け取る場合に例外がいくつかあります。例えば、ポインタ型の代わりに互換性のある配列インスタンスを渡すことができます。このように、 POINTER(c_int) に対して、 ctypes は 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
>>>

それに加えて、 argtypes で関数の引数が明示的に (POINTER(c_int) などの) ポインタ型であると宣言されていた場合、ポインタ型が指し示している型のオブジェクト (この場合では c_int) を関数に渡すことができます。この場合 ctypes は、必要となる byref() での変換を自動的に適用します。

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

なぜなら、新しい class cell はクラス文自体の中では利用できないからです。 ctypes では、 cell クラスを定義して、 _fields_ 属性をクラス文の後で設定することができます。:

>>> from ctypes import *
>>> class cell(Structure):
...     pass
...
>>> cell._fields_ = [("name", c_char_p),
...                  ("next", POINTER(cell))]
>>>

試してみましょう。 cell のインスタンスを二つ作り、互いに参照し合うようにします。最後に、つながったポインタを何度かたどります。:

>>> c1 = cell()
>>> c1.name = "foo"
>>> c2 = cell()
>>> c2.name = "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 呼び出し規約を用いてコールバック関数の型を作成します。

これらのファクトリ関数はともに最初の引数に戻り値の型、残りの引数としてコールバック関数が想定する引数の型を渡して呼び出されます。

標準 C ライブラリの qsort() 関数を使う例を示します。これはコールバック関数の助けをかりて要素をソートするために使われます。 qsort() は整数の配列をソートするために使われます:

>>> IntArray5 = c_int * 5
>>> ia = IntArray5(5, 1, 7, 33, 99)
>>> qsort = libc.qsort
>>> qsort.restype = None
>>>

qsort() はソートするデータを指すポインタ、データ配列の要素の数、要素の一つの大きさ、およびコールバック関数である比較関数へのポインタを引数に渡して呼び出さなければなりません。そして、コールバック関数は要素を指す二つのポインタを渡されて呼び出され、一番目が二番目より小さいなら負の数を、等しいならゼロを、それ以外なら正の数を返さなければなりません。

コールバック関数は整数へのポインタを受け取り、整数を返す必要があります。まず、コールバック関数のための 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
>>>

The function factories can be used as decorator factories, so we may as well write:

>>> @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からエクスポートされた値へアクセスする

共有ライブラリの一部は関数だけでなく変数もエクスポートしています。 Python ライブラリにある例としては Py_OptimizeFlag 、起動時の -O または -OO フラグに依存して、 0 , 1 または 2 が設定される整数があります。

ctypes は型の in_dll() クラスメソッドを使ってこのように値にアクセスできます。 pythonapi はPython C api へアクセスできるようにするための予め定義されたシンボルです。:

>>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag")
>>> print(opt_flag)
c_long(0)
>>>

インタープリタが -O を指定されて動き始めた場合、サンプルは c_long(1) を表示するでしょうし、 -OO が指定されたならば c_long(2) を表示するでしょう。

ポインタの使い方を説明する拡張例では、 Python がエクスポートする PyImport_FrozenModules ポインタにアクセスします。

この値のドキュメントから引用すると:

このポインタは struct _frozen のレコードからなり、終端の要素のメンバが NULL かゼロになっているような配列を指すよう初期化されます。フリーズされたモジュールをインポートするとき、このテーブルを検索します。サードパーティ製のコードからこのポインタに仕掛けを講じて、動的に生成されたフリーズ化モジュールの集合を提供するようにできます。

これで、このポインタを操作することが役に立つことを証明できるでしょう。例の大きさを制限するために、このテーブルを ctypes を使って読む方法だけを示します。:

>>> from ctypes import *
>>>
>>> class struct_frozen(Structure):
...     _fields_ = [("name", c_char_p),
...                 ("code", POINTER(c_ubyte)),
...                 ("size", c_int)]
...
>>>

私たちは struct _frozen データ型を定義済みなので、このテーブルを指すポインタを得ることができます:

>>> FrozenTable = POINTER(struct_frozen)
>>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules")
>>>

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
__hello__ 161
__phello__ -161
__phello__.spam 161
>>>

標準 Python はフローズンモジュールとフローズンパッケージ (負のサイズのメンバーで表されています) を持っているという事実はあまり知られておらず、テストにだけ使われています。例えば、 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 = "abc def ghi"
>>> s.value
'abc def ghi'
>>> s.value is s.value
False
>>>

なぜ 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リファレンス

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

コンパイルされる言語でプログラミングしている場合、共有ライブラリはプログラムをコンパイル/リンクしているときと、そのプログラムが動作しているときにアクセスされます。

ctypes ライブラリローダーはプログラムが動作しているときのように振る舞い、ランタイムローダーを直接呼び出すのに対し、 find_library() 関数の目的はコンパイラまたはランタイムローダーが行うのと似た方法でライブラリを探し出すことです。 (複数のバージョンの共有ライブラリがあるプラットホームでは、一番最近に見つかったものがロードされます)。

ctypes.util モジュールはロードするライブラリを決めるのに役立つ関数を提供します。

ctypes.util.find_library(name)

ライブラリを見つけてパス名を返そうと試みます。 name は lib のような接頭辞、 .so, .dylib のような接尾辞、あるいは、バージョン番号が何も付いていないライブラリの名前です (これは posix リンカのオプション -l に使われている形式です)。 ライブラリが見つからないときは None を返します。

厳密な機能はシステムに依存します。

Linux では、 find_library() はライブラリファイルを見つけるために外部プログラム (/sbin/ldconfig, gcc, objdump と ld) を実行しようとします。ライブラリファイルのファイル名を返します。

バージョン 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'
>>>

OS X では、 find_library() はライブラリの位置を探すために、予め定義された複数の命名方法とパスを試し、成功すればフルパスを返します。:

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

Windows では、 find_library() はシステムの探索パスに沿って探し、フルパスを返します。しかし、予め定義された命名方法がないため、 find_library("c") のような呼び出しは失敗し、 None を返します。

ctypes で共有ライブラリをラップする場合、 find_library() を使って実行時にライブラリの場所を特定するのではなく、共有ライブラリの名前を開発時に決めておいて、ラッパーモジュールにハードコードする方が良い かもしれません 。

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

共有ライブラリを Python プロセスへロードする方法はいくつかあります。一つの方法は下記のクラスの一つをインスタンス化することです:

class ctypes.CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)

このクラスのインスタンスはロードされた共有ライブラリをあらわします。これらのライブラリの関数は標準 C 呼び出し規約を使用し、 int を返すと仮定されます。

class ctypes.OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)

Windows 用: このクラスのインスタンスはロードされた共有ライブラリをあらわします。これらのライブラリの関数は stdcall 呼び出し規約を使用し、 windows 固有の HRESULT コードを返すと仮定されます。 HRESULT 値には関数呼び出しが失敗したのか成功したのかを特定する情報とともに、補足のエラーコードが含まれます。戻り値が失敗を知らせたならば、 OSError が自動的に送出されます。

バージョン 3.3 で変更: 以前は WindowsError を送出していました。

class ctypes.WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)

Windows 用: このクラスのインスタンスはロードされた共有ライブラリをあらわします。これらのライブラリの関数は stdcall 呼び出し規約を使用し、デフォルトでは int を返すと仮定されます。

Windows CE では標準呼び出し規約だけが使われます。便宜上、このプラットフォームでは、 WinDLL と OleDLL が標準呼び出し規約を使用します。

これらのライブラリがエクスポートするどの関数でも呼び出す前に Python GIL (global interpreter lock) は解放され、後でまた獲得されます。

class ctypes.PyDLL(name, mode=DEFAULT_MODE, handle=None)

Python GIL が関数呼び出しの間解放 されず 、関数実行の後に Python エラーフラグがチェックされるということを除けば、このクラスのインスタンスは CDLL インスタンスのように振る舞います。エラーフラグがセットされた場合、 Python 例外が送出されます。

要するに、これは Python C api 関数を直接呼び出すのに便利だというだけです。

これらすべてのクラスは少なくとも一つの引数、すなわちロードする共有ライブラリのパスを渡して呼び出すことでインスタンス化されます。すでにロード済みの共有ライブラリへのハンドルがあるなら、 handle 名前付き引数として渡すことができます。土台となっているプラットフォームの dlopen または LoadLibrary 関数がプロセスへライブラリをロードするために使われ、そのライブラリに対するハンドルを得ます。

mode パラメータを使うと、ライブラリがどうやってロードされたかを特定できます。 詳細は dlopen(3) マニュアルページを参考にしてください。 Windows では mode は無視されます。 POSIX システムでは RTLD_NOW が常に追加され、設定変更はできません。

use_errno 変数が真に設定されたとき、システムの errno エラーナンバーに安全にアクセスする ctypes の仕組みが有効化されます。 ctypes はシステムの errno 変数のスレッド限定のコピーを管理します。もし、 use_errno=True の状態で作られた外部関数を呼び出したなら、関数呼び出し前の errno 変数は ctypes のプライベートコピーと置き換えられ、同じことが関数呼び出しの直後にも発生します。

ctypes.get_errno() 関数は ctypes のプライベートコピーの値を返します。そして、 ctypes.set_errno() 関数は ctypes のプライベートコピーを置き換え、以前の値を返します。

use_last_error パラメータは、真に設定されたとき、 GetLastError() と SetLastError() Windows API によって管理される Windows エラーコードに対するのと同じ仕組みが有効化されます。 ctypes.get_last_error() と ctypes.set_last_error() は Windows エラーコードの ctypes プライベートコピーを変更したり要求したりするのに使われます。

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

コンストラクタに渡されたライブラリの名前。

共有ライブラリは (LibraryLoader クラスのインスタンスである) 前もって作られたオブジェクトの一つを使うことによってロードすることもできます。それらの LoadLibrary() メソッドを呼び出すか、ローダーインスタンスの属性としてライブラリを取り出すかのどちらかによりロードします。

class ctypes.LibraryLoader(dlltype)

共有ライブラリをロードするクラス。 dlltype は CDLL 、 PyDLL 、 WinDLL もしくは OleDLL 型の一つであるべきです。

__getattr__() は次のような特別なはたらきをします。ライブラリローダーインスタンスの属性として共有ライブラリにアクセスするとそれがロードされるということを可能にします。結果はキャッシュされます。そのため、繰り返し属性アクセスを行うといつも同じライブラリが返されます。

LoadLibrary(name)

共有ライブラリをプロセスへロードし、それを返します。このメソッドはライブラリの新しいインスタンスを常に返します。

これらの前もって作られたライブラリローダーを利用することができます。:

ctypes.cdll

CDLL インスタンスを作ります。

ctypes.windll

Windows 用: WinDLL インスタンスを作ります。

ctypes.oledll

Windows 用: OleDLL インスタンスを作ります。

ctypes.pydll

PyDLL インスタンスを作ります。

C Python api に直接アクセスするために、すぐに使用できる Python 共有ライブラリオブジェクトが次のように用意されています。

ctypes.pythonapi

属性として Python C api 関数を公開する PyDLL のインスタンス。これらすべての関数は C int を返すと仮定されますが、もちろん常に正しいとは限りません。そのため、これらの関数を使うためには正しい restype 属性を代入しなければなりません。

外部関数

前節で説明した通り、外部関数はロードされた共有ライブラリの属性としてアクセスできます。デフォルトではこの方法で作成された関数オブジェクトはどんな数の引数でも受け取り、引数としてどんな ctypes データのインスタンスをも受け取り、そして、ライブラリローダーが指定したデフォルトの結果の値の型を返します。関数オブジェクトはプライベートクラスのインスタンスです。:

class ctypes._FuncPtr

C の呼び出し可能外部関数のためのベースクラス。

外部関数のインスタンスも C 互換データ型です。それらは C の関数ポインタを表しています。

この振る舞いは外部関数オブジェクトの特別な属性に代入することによって、カスタマイズすることができます。

restype

外部関数の結果の型を指定するために ctypes 型を代入する。何も返さない関数を表す void に対しては None を使います。

ctypes 型ではない呼び出し可能な Python オブジェクトを代入することは可能です。このような場合、関数が C int を返すと仮定され、呼び出し可能オブジェクトはこの整数を引数に呼び出されます。さらに処理を行ったり、エラーチェックをしたりできるようにするためです。これの使用は推奨されません。より柔軟な後処理やエラーチェックのためには restype として ctypes 型を使い、 errcheck 属性へ呼び出し可能オブジェクトを代入してください。

argtypes

関数が受け取る引数の型を指定するために ctypes 型のタプルを代入します。stdcall 呼び出し規約を使う関数はこのタプルの長さと同じ数の引数で呼び出されます。C 呼び出し規約を使う関数は、追加の不特定の引数も取ります。

外部関数が呼ばれたとき、それぞれの実引数は argtypes タプルの要素の from_param() クラスメソッドへ渡されます。このメソッドは実引数を外部関数が受け取るオブジェクトに合わせて変えられるようにします。例えば、 argtypes タプルの c_char_p 要素は、 ctypes 変換規則にしたがって引数として渡された文字列をバイト列オブジェクトへ変換するでしょう。

新: ctypes 型でない要素を argtypes に入れることができますが、個々の要素は引数として使える値 (整数、文字列、 ctypes インスタンス) を返す from_param() メソッドを持っていなければなりません。これにより関数パラメータとしてカスタムオブジェクトを適合するように変更できるアダプタが定義可能となります。

errcheck

Python 関数または他の呼び出し可能オブジェクトをこの属性に代入します。呼び出し可能オブジェクトは三つ以上の引数とともに呼び出されます。

callable(result, func, arguments)

result は外部関数が返すもので、 restype 属性で指定されます。

func は外部関数オブジェクト自身で、これにより複数の関数の処理結果をチェックまたは後処理するために、同じ呼び出し可能オブジェクトを再利用できるようになります。

arguments は関数呼び出しに最初に渡されたパラメータが入ったタプルです。これにより使われた引数に基づいた特別な振る舞いをさせることができるようになります。

この関数が返すオブジェクトは外部関数呼び出しから返された値でしょう。しかし、戻り値をチェックして、外部関数呼び出しが失敗しているなら例外を送出させることもできます。

exception ctypes.ArgumentError

この例外は外部関数呼び出しが渡された引数を変換できなかったときに送出されます。

関数プロトタイプ

Foreign functions can also be created by instantiating function prototypes. Function prototypes are similar to function prototypes in C; they describe a function (return type, argument types, calling convention) without defining an implementation. The factory functions must be called with the desired result type and the argument types of the function, and can be used as decorator factories, and as such, be applied to functions through the @wrapper syntax. See コールバック関数 for examples.

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 呼び出し規約を使う関数を作成します。ただし、 WINFUNCTYPE() が CFUNCTYPE() と同じである Windows CE を除きます。関数は呼び出されている間 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 メソッドは特殊な呼び出し規約を用います。このメソッドは argtypes タプルに指定されたパラメータに加えて、第一引数として COM インターフェイスへのポインタを必要とします。

オプションの paramflags パラメータは上述した機能より多機能な外部関数ラッパーを作成します。

paramflags は argtypes と同じ長さのタプルでなければなりません。

このタプルの個々の要素はパラメータについてのより詳細な情報を持ち、 1 、 2 もしくは 3 要素を含むタプルでなければなりません。

第一要素はパラメータについてのフラグの組み合わせを含んだ整数です。

1
入力パラメータを関数に指定します。
2
出力パラメータ。外部関数が値を書き込みます。
4
デフォルトで整数ゼロになる入力パラメータ。

オプションの第二要素はパラメータ名の文字列です。これが指定された場合は、外部関数を名前付きパラメータで呼び出すことができます。

オプションの第三要素はこのパラメータのデフォルト値です。

この例では、デフォルトパラメータと名前付き引数をサポートするために Windows の MessageBoxW 関数をラップする方法を示します。 windows のヘッダファイルの C の宣言は次の通りです:

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 インスタンスを返します。

さらに出力処理やエラーチェックを行うために、出力パラメータを errcheck プロトコルと組み合わせることができます。 win32 GetWindowRect api 関数は成功したか失敗したかを知らせるために BOOL を返します。そのため、この関数はエラーチェックを行って、 api 呼び出しが失敗した場合に例外を送出させることができます。:

>>> def errcheck(result, func, args):
...     if not result:
...         raise WinError()
...     return args
...
>>> GetWindowRect.errcheck = errcheck
>>>

errcheck 関数が受け取った引数タプルを変更なしに返した場合、 ctypes は出力パラメータに対する通常の処理を続けます。 RECT インスタンスの代わりに window 座標のタプルを返すには、関数のフィールドを取り出し、代わりにそれらを返すことができます。この場合、通常処理は行われなくなります:

>>> 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 型のインスタンスでなければなりません。

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 つ長いバッファを作成します。バイト列の長さを使うべきではない場合は、第二引数として整数を渡して、配列の長さを指定することができます。

ctypes.create_unicode_buffer(init_or_size, size=None)

この関数は変更可能な Unicode 文字バッファを作成します。返されるオブジェクトは c_wchar の ctypes 配列です。

init_or_size は配列のサイズを指定する整数もしくは配列要素を初期化するために使われる文字列である必要があります。

第一引数として文字列が指定された場合は、バッファが文字列の長さより一要素分大きく作られます。配列の最後の要素が NUL 終端文字であるためです。文字列の長さを使うべきでない場合は、配列のサイズを指定するために整数を第二引数として渡すことができます。

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_last_error()

Windows 用: システムの LastError 変数の、スレッドローカルなプライベートコピーを返します。

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)

このファクトリ関数は新しい ctypes ポインタ型を作成して返します。ポインタ型はキャッシュされ、内部で再利用されます。したがって、この関数を繰り返し呼び出してもコストは小さいです。type は ctypes 型でなければなりません。

ctypes.pointer(obj)

この関数は obj を指す新しいポインタインスタンスを作成します。戻り値は POINTER(type(obj)) 型のオブジェクトです。

注意: 外部関数呼び出しへオブジェクトへのポインタを渡したいだけなら、はるかに高速な byref(obj) を使うべきです。

ctypes.resize(obj, size)

この関数は obj の内部メモリバッファのサイズを変更します。 obj は ctypes 型のインスタンスでなければなりません。バッファを sizeof(type(obj)) で与えられるオブジェクト型の本来のサイズより小さくすることはできませんが、バッファを拡大することはできます。

ctypes.set_errno(value)

システム変数 errno の、呼び出し元スレッドでの ctypes のプライベートコピーの現在値を value に設定し、前の値を返します。

ctypes.set_last_error(value)

Windows 用: システム変数 LastError の、呼び出し元スレッドでの ctypes のプライベートコピーの現在値を value に設定し、前の値を返します。

ctypes.sizeof(obj_or_type)

ctypes の型やインスタンスのメモリバッファのサイズをバイト数で返します。C の sizeof 演算子と同様の動きをします。

ctypes.string_at(address, size=-1)

この関数はメモリアドレス address から始まる C 文字列を返します。size が指定された場合はサイズとして使われます。指定されなければ、文字列がゼロ終端されていると仮定します。

ctypes.WinError(code=None, descr=None)

Windows 用: この関数はおそらく ctypes の中で最悪の名前でしょう。これは OSError のインスタンスを作成します。 code が指定されていなかった場合、エラーコードを判別するために GetLastError が呼び出されます。 descr が指定されていなかった場合、エラーの説明文を得るために FormatError() が呼び出されます。

バージョン 3.3 で変更: 以前は WindowsError インスタンスが作成されていました。

ctypes.wstring_at(address, size=-1)

この関数は文字列としてメモリアドレス address から始まるワイドキャラクタ文字列を返します。size が指定されたならば、文字列の文字数として使われます。指定されなければ、文字列がゼロ終端されていると仮定します。

データ型

class ctypes._CData

この非公開クラスはすべての ctypes データ型の共通のベースクラスです。他のことはさておき、すべての ctypes 型インスタンスは C 互換データを保持するメモリブロックを内部に持ちます。このメモリブロックのアドレスは addressof() ヘルパー関数が返します。別のインスタンス変数が _objects として公開されます。これはメモリブロックがポインタを含む場合に存続し続ける必要のある他の Python オブジェクトを含んでいます。

ctypes データ型の共通メソッド、すべてのクラスメソッドが存在します (正確には、 メタクラス のメソッドです):

from_buffer(source[, offset])

このメソッドは source オブジェクトのバッファを共有する ctypes のインスタンスを返します。 source オブジェクトは書き込み可能バッファインターフェースをサポートしている必要があります。オプションの offset 引数では source バッファのオフセットをバイト単位で指定します。デフォルトではゼロです。もし source バッファが十分に大きくなければ、 ValueError が送出されます。

from_buffer_copy(source[, offset])

このメソッドは source オブジェクトの読み出し可能バッファをコピーすることで、ctypes のインスタンスを生成します。オプションの offset 引数では source バッファのオフセットをバイト単位で指定します。デフォルトではゼロです。もし source バッファが十分に大きくなければ、 ValueError が送出されます。

from_address(address)

このメソッドは address で指定されたメモリを使って ctypes 型のインスタンスを返します。 address は整数でなければなりません。

from_param(obj)

このメソッドは obj を ctypes 型に適合させます。外部関数の argtypes タプルに、その型があるとき、外部関数呼び出しで実際に使われるオブジェクトと共に呼び出されます。

すべての 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 オブジェクトインスタンスに対しても言えます。

基本データ型は、外部関数呼び出しの結果として返されたときや、例えば構造体のフィールドメンバーや配列要素を取り出すときに、ネイティブの Python 型へ透過的に変換されます。言い換えると、外部関数が c_char_p の restype を持つ場合は、 c_char_p インスタンスでは なく 常に Python バイト列オブジェクトを受け取ることでしょう。

基本データ型のサブクラスはこの振る舞いを継承 しません 。したがって、外部関数の restype が c_void_p のサブクラスならば、関数呼び出しからこのサブクラスのインスタンスを受け取ります。もちろん、 value 属性にアクセスしてポインタの値を得ることができます。

これらが基本 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 データ型を表します。

バージョン 3.2 で追加.

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用: HRESULT 値を表し、関数またはメソッド呼び出しに対する成功またはエラーの情報を含んでいます。

class ctypes.py_object

C PyObject * データ型を表します。引数なしでこれを呼び出すと NULL PyObject * ポインタを作成します。

ctypes.wintypes モジュールは他の Windows 固有のデータ型を提供します。例えば、 HWND, WPARAM, DWORD です。 MSG や RECT のような有用な構造体も定義されています。

構造化データ型

class ctypes.Union(*args, **kw)

ネイティブのバイトオーダーでの共用体のための抽象ベースクラス。

class ctypes.BigEndianStructure(*args, **kw)

ビックエンディアン バイトオーダーでの構造体のための抽象ベースクラス。

class ctypes.LittleEndianStructure(*args, **kw)

リトルエンディアン バイトオーダーでの構造体のための抽象ベースクラス。

ネイティブではないバイトオーダーを持つ構造体にポインタ型フィールドあるいはポインタ型フィールドを含む他のどんなデータ型をも入れることはできません。

class ctypes.Structure(*args, **kw)

ネイティブ のバイトオーダーでの構造体のための抽象ベースクラス。

具象構造体型と具象共用体型はこれらの型の一つをサブクラス化することで作らなければなりません。少なくとも、 _fields_ クラス変数を定義する必要があります。 ctypes は、属性に直接アクセスしてフィールドを読み書きできるようにする記述子 (descriptor) を作成するでしょう。これらは、

_fields_

構造体のフィールドを定義するシーケンス。要素は2要素タプルか3要素タプルでなければなりません。第一要素はフィールドの名前です。第二要素はフィールドの型を指定します。それはどんな ctypes データ型でも構いません。

c_int のような整数型のために、オプションの第三要素を与えることができます。フィールドのビット幅を定義する正の小整数である必要があります。

一つの構造体と共用体の中で、フィールド名はただ一つである必要があります。これはチェックされません。名前が繰り返しでてきたときにアクセスできるのは一つのフィールドだけです。

Structure サブクラスを定義するクラス文の 後で 、 _fields_ クラス変数を定義することができます。これにより、次のように自身を直接または間接的に参照するデータ型を作成できるようになります:

class List(Structure):
    pass
List._fields_ = [("pnext", POINTER(List)),
                 ...
                ]

しかし、 _fields_ クラス変数はその型が最初に使われる (インスタンスが作成される、それに対して sizeof() が呼び出されるなど) より前に定義されていなければなりません。その後 _fields_ クラス変数へ代入すると AttributeError が送出されます。

構造体型のサブクラスを定義することができ、もしあるならサブクラス内で定義された _fields_ に加えて、ベースクラスのフィールドも継承します。

_pack_

インスタンスの構造体フィールドのアライメントを上書きできるようにするオブションの小整数。 _pack_ は _fields_ が代入されたときすでに定義されていなければなりません。そうでなければ、何の効果もありません。

_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

ポインタが指すオブジェクトを返します。この属性に割り当てると、ポインタが割り当てられたオブジェクトを指すようになります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 汎用オペレーティングシステムサービス »


並行実行

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

並行実行

この章で記述されているモジュールは、コードの並行実行のサポートを提供します。ツールの適切な選択は、実行されるタスク(IO bound vs CPU bound) や推奨される開発スタイル (イベントドリブンな協調的マルチタスク vs プリエンプティブマルチタスク) に依存します。ここに概観を示します:

  • threading --- スレッドベースの並列処理
    • スレッドローカルデータ
    • Thread オブジェクト
    • Lock オブジェクト
    • RLock オブジェクト
    • Condition オブジェクト
    • Semaphore オブジェクト
      • Semaphore の例
    • Event オブジェクト
    • Timer オブジェクト
    • バリアオブジェクト
    • Using locks, conditions, and semaphores in the with statement
  • multiprocessing --- プロセスベースの並列処理
    • はじめに
      • Process クラス
      • コンテキストと開始方式
      • プロセス間でのオブジェクト交換
      • プロセス間の同期
      • プロセス間での状態の共有
      • ワーカープロセスのプールを使用
    • リファレンス
      • Process クラスと例外
      • パイプ (Pipe) とキュー (Queue)
      • その他
      • Connection オブジェクト
      • 同期プリミティブ
      • 共有 ctypes オブジェクト
        • multiprocessing.sharedctypes モジュール
      • マネージャー
        • カスタマイズされたマネージャー
        • リモートマネージャーを使用する
      • Proxy オブジェクト
        • クリーンアップ
      • プロセスプール
      • リスナーとクライアント
        • アドレスフォーマット
      • 認証キー
      • ログ記録
      • multiprocessing.dummy モジュール
    • プログラミングガイドライン
      • すべての開始方式について
      • 開始方式が spawn および forkserver の場合
    • 使用例
  • concurrent パッケージ
  • concurrent.futures -- 並列タスク実行
    • Executor オブジェクト
    • ThreadPoolExecutor
      • ThreadPoolExecutor の例
    • ProcessPoolExecutor
      • ProcessPoolExecutor の例
    • Future オブジェクト
    • モジュール関数
    • 例外クラス
  • subprocess --- サブプロセス管理
    • subprocess モジュールを使う
      • よく使われる引数
      • Popen コンストラクター
      • 例外
    • セキュリティで考慮すべき点
    • Popen オブジェクト
    • Windows Popen ヘルパー
      • Windows Constants
    • 古い高水準 API
    • 古い関数を subprocess モジュールで置き換える
      • /bin/sh シェルのバッククォートを置き換える
      • シェルのパイプラインを置き換える
      • os.system() を置き換える
      • os.spawn 関数群を置き換える
      • os.popen(), os.popen2(), os.popen3() を置き換える
      • popen2 モジュールの関数群を置き換える
    • レガシーなシェル呼び出し関数
    • 注釈
      • Windows における引数シーケンスから文字列への変換
  • sched --- イベントスケジューラ
    • スケジューラオブジェクト
  • queue --- 同期キュークラス
    • キューオブジェクト
    • SimpleQueue Objects

以下のモジュールは上記のサービスの一部で使われるサポートモジュールです:

  • _thread --- 低水準の スレッド API
  • _dummy_thread --- _thread の代替モジュール
  • dummy_threading --- threading の代替モジュール

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


multiprocessing --- プロセスベースの並列処理

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 並行実行 »

multiprocessing --- プロセスベースの並列処理

ソースコード: Lib/multiprocessing/

はじめに

multiprocessing は、 threading と似た API で複数のプロセスの生成をサポートするパッケージです。 multiprocessing パッケージは、ローカルとリモート両方の並行処理を提供します。また、このパッケージはスレッドの代わりにサブプロセスを使用することにより、グローバルインタープリタロック の問題を避ける工夫が行われています。このような特徴があるため multiprocessing モジュールを使うことで、マルチプロセッサーマシンの性能を最大限に活用することができるでしょう。なお、このモジュールは Unix と 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]

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 に比べ遅くなります。

Unix と Windows で利用可能。Windows でのデフォルト。

fork

親プロセスは os.fork() を使用して Python インタープリターをフォークします。子プロセスはそれが開始されるとき、事実上親プロセスと同一になります。親プロセスのリソースはすべて子プロセスに継承されます。マルチスレッドプロセスのフォークは安全性に問題があることに注意してください。

Unix でのみ利用可能。Unix でのデフォルト。

forkserver

プログラムを開始するとき forkserver 方式を選択した場合、サーバープロセスが開始されます。それ以降、新しいプロセスが必要になったときはいつでも、親プロセスはサーバーに接続し、新しいプロセスのフォークを要求します。フォークサーバープロセスはシングルスレッドなので os.fork() の使用に関しても安全です。不要なリソースは継承されません。

Unix パイプを経由したファイル記述子の受け渡しをサポートする Unix で利用可能。

バージョン 3.4 で変更: すべての Unix プラットフォームで spawn が、一部のプラットフォームで forkserver が追加されました。Windows では親プロセスの継承可能な全ハンドルが子プロセスに継承されることがなくなりました。

On Unix using the spawn or forkserver start methods will also start a semaphore tracker process which tracks the unlinked named semaphores created by processes of the program. When all processes have exited the semaphore tracker unlinks any remaining semaphores. Usually there should be none, but if a process was killed by a signal there may be some "leaked" semaphores. (Unlinking the named semaphores is a serious matter since the system allows only a limited number, and they will not be automatically unlinked until the next reboot.)

開始方式はメインモジュールの 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()

Note that objects related to one context may not be compatible with processes for a different context. In particular, locks created using the fork context cannot be passed to processes started using the spawn or forkserver start methods.

特定の開始方式の使用を要求するライブラリは get_context() を使用してライブラリ利用者の選択を阻害しないようにするべきです。

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

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 secs
        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
...
>>> p.map(f, [1,2,3])
Process PoolWorker-1:
Process PoolWorker-2:
Process PoolWorker-3:
Traceback (most recent call last):
AttributeError: 'module' object has no attribute 'f'
AttributeError: 'module' object has no attribute 'f'
AttributeError: 'module' object has no attribute 'f'

(このサンプルを試すと、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 には引数が渡されないようになっています。

サブクラスがコンストラクターをオーバーライドする場合は、そのプロセスに対する処理を行う前に基底クラスのコンストラクター (Process.__init__()) を実行しなければなりません。

バージョン 3.3 で変更: daemon 引数が追加されました。

run()

プロセスが実行する処理を表すメソッドです。

このメソッドはサブクラスでオーバーライドすることができます。標準の run() メソッドは、コンストラクターの target 引数として渡された呼び出し可能オブジェクトを呼び出します。もしコンストラクターに args もしくは kwargs 引数が渡されていれば、呼び出すオブジェクトにこれらの引数を渡します。

start()

プロセスの処理を開始するためのメソッドです。

各 Process オブジェクトに対し、このメソッドが2回以上呼び出されてはいけません。各プロセスでオブジェクトの run() メソッドを呼び出す準備を行います。

join([timeout])

オプションの引数 timeout が None (デフォルト) の場合、 join() メソッドが呼ばれたプロセスは処理が終了するまでブロックします。 timeout が正の数である場合、最大 timeout 秒ブロックします。 プロセスが終了あるいはタイムアウトした場合、メソッドは None を返すことに注意してください。 プロセスの exitcode を確認し終了したかどうかを判断してください。

1つのプロセスは何回も join されることができます。

プロセスは自分自身を join することはできません。それはデッドロックを引き起こすことがあるからです。プロセスが start される前に join しようとするとエラーが発生します。

name

プロセスの名前。名前は識別のためだけに使用される文字列です。それ自体には特別な意味はありません。複数のプロセスに同じ名前が与えられても構いません。

最初の名前はコンストラクターによってセットされます。コンストラクターに明示的な名前が渡されない場合、 'Process-N1:N2:...:Nk' 形式の名前が構築されます。ここでそれぞれの Nk はその親のN番目の子供です。

is_alive()

プロセスが実行中かを判別します。

おおまかに言って、プロセスオブジェクトは start() メソッドを呼び出してから子プロセス終了までの期間が実行中となります。

daemon

デーモンプロセスであるかのフラグであり、ブール値です。この属性は start() が呼び出される前に設定されている必要があります。

初期値は作成するプロセスから継承します。

あるプロセスが終了するとき、そのプロセスはその子プロセスであるデーモンプロセスすべてを終了させようとします。

デーモンプロセスは子プロセスを作成できないことに注意してください。もし作成できてしまうと、そのデーモンプロセスの親プロセスが終了したときにデーモンプロセスの子プロセスが孤児になってしまう場合があるからです。さらに言えば、デーモンプロセスはUnix デーモンやサービスでは なく 通常のプロセスであり、非デーモンプロセスが終了すると終了されます (そして join されません)。

threading.Thread クラスの API に加えて Process クラスのオブジェクトには以下の属性およびメソッドがあります:

pid

プロセスIDを返します。プロセスの生成前は None が設定されています。

exitcode

子プロセスの終了コードです。子プロセスがまだ終了していない場合は None が返されます。負の値 -N は子プロセスがシグナル N で終了したことを表します。

authkey

プロセスの認証キーです (バイト文字列です)。

multiprocessing モジュールがメインプロセスにより初期化される場合には、 os.urandom() 関数を使用してランダムな値が設定されます。

Process クラスのオブジェクトの作成時にその親プロセスから認証キーを継承します。もしくは authkey に別のバイト文字列を設定することもできます。

詳細は 認証キー を参照してください。

sentinel

プロセスが終了するときに "ready" となるシステムオブジェクトの数値ハンドル。

multiprocessing.connection.wait() を使用していくつかのイベントを同時に wait したい場合はこの値を使うことができます。それ以外の場合は join() を呼ぶ方がより単純です。

Windows においては、これは WaitForSingleObject および WaitForMultipleObjects ファミリーの API 呼び出しで使用可能な OS ハンドルです。 Unix においては、これは select モジュールのプリミティブで使用可能なファイル記述子です。

バージョン 3.3 で追加.

terminate()

プロセスを終了します。Unix 環境では SIGTERM シグナルを、 Windows 環境では TerminateProcess() を使用して終了させます。終了ハンドラーや finally 節などは、実行されないことに注意してください。

このメソッドにより終了するプロセスの子孫プロセスは、終了 しません 。そういった子孫プロセスは単純に孤児になります。

警告

このメソッドの使用時に、関連付けられたプロセスがパイプやキューを使用している場合には、使用中のパイプやキューが破損して他のプロセスから使用できなくなる可能性があります。同様に、プロセスがロックやセマフォなどを取得している場合には、このプロセスが終了してしまうと他のプロセスのデッドロックの原因になるでしょう。

kill()

Same as terminate() but using the SIGKILL signal on Unix.

バージョン 3.7 で追加.

close()

Close the Process object, releasing all resources associated with it. ValueError is raised if the underlying process is still running. Once close() returns successfully, most other methods and attributes of the Process object will raise ValueError.

バージョン 3.7 で追加.

プロセスオブジェクトが作成したプロセスのみが start(), join(), is_alive(), terminate() と exitcode のメソッドを呼び出すべきです。

以下の例では Process のメソッドの使い方を示しています:

>>> import multiprocessing, time, signal
>>> p = multiprocessing.Process(target=time.sleep, args=(1000,))
>>> print(p, p.is_alive())
<Process(Process-1, initial)> False
>>> p.start()
>>> print(p, p.is_alive())
<Process(Process-1, started)> True
>>> p.terminate()
>>> time.sleep(0.1)
>>> print(p, p.is_alive())
<Process(Process-1, stopped[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 を使ってキューを作成することができるからです。

  1. 空のキューの中にオブジェクトを追加した後、キューの empty() メソッドが False を返すまでの間にごくわずかな遅延が起きることがあり、get_nowait() が queue.Empty を発生させることなく制御が呼び出し元に返ってしまうことがあります。
  2. 複数のプロセスがオブジェクトをキューに詰めている場合、キューの反対側ではオブジェクトが詰められたのとは違う順序で取得される可能性があります。ただし、同一のプロセスから詰め込まれたオブジェクトは、それらのオブジェクト間では、必ず期待どおりの順序になります。

警告

Queue を利用しようとしている最中にプロセスを Process.terminate() や os.kill() で終了させる場合、キューにあるデータは破損し易くなります。終了した後で他のプロセスがキューを利用しようとすると、例外を発生させる可能性があります。

警告

上述したように、もし子プロセスがキューへ要素を追加するなら (かつ JoinableQueue.cancel_join_thread を使用しないなら) そのプロセスはバッファーされたすべての要素がパイプへフラッシュされるまで終了しません。

これは、そのプロセスを join しようとする場合、キューに追加されたすべての要素が消費されたことが確実でないかぎり、デッドロックを発生させる可能性があることを意味します。似たような現象で、子プロセスが非デーモンプロセスの場合、親プロセスは終了時に非デーモンのすべての子プロセスを join しようとしてハングアップする可能性があります。

マネージャーを使用して作成されたキューではこの問題はありません。詳細は プログラミングガイドライン を参照してください。

プロセス間通信におけるキューの使用例を知りたいなら 使用例 を参照してください。

multiprocessing.Pipe([duplex])

Returns a pair (conn1, conn2) of Connection objects representing the ends of a pipe.

duplex が True (デフォルト) ならパイプは双方向性です。duplex が False ならパイプは一方向性で、conn1 はメッセージの受信専用、conn2 はメッセージの送信専用になります。

class multiprocessing.Queue([maxsize])

パイプや2～3個のロック/セマフォを使用して実装されたプロセス共有キューを返します。あるプロセスが最初に要素をキューへ追加するとき、バッファーからパイプの中へオブジェクトを転送する供給スレッドが開始されます。

標準ライブラリの queue モジュールの通常の queue.Empty や queue.Full 例外がタイムアウトを伝えるために送出されます。

Queue は task_done() や join() を除く queue.Queue のすべてのメソッドを実装します。

qsize()

おおよそのキューのサイズを返します。マルチスレッディング/マルチプロセスの特性上、この数値は信用できません。

これは sem_getvalue() が実装されていない Mac OS X のような Unix プラットホーム上で NotImplementedError を発生させる可能性があることを覚えておいてください。

empty()

キューが空っぽなら True を、そうでなければ False を返します。マルチスレッディング/マルチプロセシングの特性上、これは信用できません。

full()

キューがいっぱいなら True を、そうでなければ False を返します。マルチスレッディング/マルチプロセシングの特性上、これは信用できません。

put(obj[, block[, timeout]])

キューの中へ obj を追加します。オプションの引数 block が True (デフォルト) 且つ timeout が None (デフォルト) なら、空きスロットが利用可能になるまで必要であればブロックします。 timeout が正の数なら、最大 timeout 秒ブロックして、その時間内に空きスロットが利用できなかったら queue.Full 例外を発生させます。それ以外 (block が False) で、空きスロットがすぐに利用可能な場合はキューに要素を追加します。そうでなければ queue.Full 例外が発生します(その場合 timeout は無視されます)。

put_nowait(obj)

put(obj, False) と等価です。

get([block[, timeout]])

キューから要素を取り出して削除します。オプションの引数 block が True (デフォルト) 且つ timeout が None (デフォルト) なら、要素が取り出せるまで必要であればブロックします。 timeout が正の数なら、最大 timeout 秒ブロックして、その時間内に要素が取り出せなかったら queue.Empty 例外を発生させます。それ以外 (block が False) で、要素がすぐに取り出せる場合は要素を返します。そうでなければ queue.Empty 例外が発生します(その場合 timeout は無視されます)。

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 を参照してください。同様のことが、以下に列挙されている特殊なキューでも成り立ちます。

class multiprocessing.SimpleQueue

単純化された Queue 型です。ロックされた Pipe と非常に似ています。

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 数を返します。

この数は現在のプロセスが使える CPU 数と同じものではありません。 使用可能な CPU 数は len(os.sched_getaffinity(0)) で取得できます。

NotImplementedError を送出するかもしれません。

参考

os.cpu_count()

multiprocessing.current_process()

カレントプロセスに対応する Process オブジェクトを返します。

threading.current_thread() とよく似た関数です。

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()

サポートしている開始方式のリストを返します。先頭の要素がデフォルトを意味します。利用可能な開始方式には 'fork'、'spawn' および 'forkserver' があります。Windows では 'spawn' のみが利用可能です。Unix では 'fork' および 'spawn' は常にサポートされており、'fork' がデフォルトになります。

バージョン 3.4 で追加.

multiprocessing.get_context(method=None)

multiprocessing モジュールと同じ属性を持つコンテキストオブジェクトを返します。

method が None の場合、デフォルトのコンテキストが返されます。その他の場合 method は 'fork'、'spawn' あるいは 'forkserver' でなければなりません。指定された開始方式が利用できない場合は ValueError が送出されます。

バージョン 3.4 で追加.

multiprocessing.get_start_method(allow_none=False)

開始するプロセスで使用する開始方式名を返します。

開始方式がまだ確定しておらず、allow_none の値が偽の場合、開始方式はデフォルトに確定され、その名前が返されます。開始方式が確定しておらず、allow_none の値が真の場合、 None が返されます。

返り値は 'fork'、'spawn'、'forkserver' あるいは None になります。Unix では 'fork' が、Windows では 'spawn' がデフォルトになります。

バージョン 3.4 で追加.

multiprocessing.set_executable()

子プロセスを開始するときに、使用する Python インタープリターのパスを設定します。(デフォルトでは sys.executable が使用されます)。コードに組み込むときは、おそらく次のようにする必要があります

set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))

子プロセスを作成する前に行ってください。

バージョン 3.4 で変更: Unix で開始方式に 'spawn' を使用している場合にサポートされました。

multiprocessing.set_start_method(method)

子プロセスの開始方式を指定します。method には 'fork'、'spawn' あるいは 'forkserver' を指定できます。

これは一度しか呼び出すことができず、その場所もメインモジュールの if __name__ == '__main__' 節内で保護された状態でなければなりません。

バージョン 3.4 で追加.

注釈

multiprocessing には threading.active_count(), threading.enumerate(), threading.settrace(), threading.setprofile(), threading.Timer や threading.local のような関数はありません。

Connection オブジェクト

Connection オブジェクトは pickle でシリアライズ可能なオブジェクトか文字列を送ったり、受け取ったりします。そういったオブジェクトはメッセージ指向の接続ソケットと考えられます。

Connection objects are usually created using Pipe -- see also リスナーとクライアント.

class multiprocessing.connection.Connection
send(obj)

コネクションの相手側へ recv() を使用して読み込むオブジェクトを送ります。

The object must be picklable. Very large pickles (approximately 32 MiB+, though it depends on the OS) may raise a ValueError exception.

recv()

Return an object sent from the other end of the connection using send(). Blocks until there is something to receive. Raises EOFError if there is nothing left to receive and the other end was closed.

fileno()

コネクションが使用するハンドラーか、ファイル記述子を返します。

close()

コネクションをクローズします。

コネクションがガベージコレクトされるときに自動的に呼び出されます。

poll([timeout])

読み込み可能なデータがあるかどうかを返します。

timeout が指定されていなければすぐに返します。 timeout に数値を指定すると、最大指定した秒数をブロッキングします。 timeout に None を指定するとタイムアウトせずにずっとブロッキングします。

multiprocessing.connection.wait() を使って複数のコネクションオブジェクトを同時にポーリングできることに注意してください。

send_bytes(buffer[, offset[, size]])

bytes-like object から完全なメッセージとしてバイトデータを送ります。

If offset is given then data is read from that position in buffer. If size is given then that many bytes will be read from buffer. Very large buffers (approximately 32 MiB+, though it depends on the OS) may raise a ValueError exception

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 オブジェクト自体をプロセス間で転送できるようになりました。

バージョン 3.3 で追加: Connection オブジェクトがコンテキストマネージメント・プロトコルをサポートするようになりました。 -- コンテキストマネージャ型 を参照してください。 __enter__() は Connection オブジェクトを返します。また __exit__() は 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 のクローンです。

バージョン 3.3 で追加.

class multiprocessing.BoundedSemaphore([value])

有限セマフォオブジェクト: threading.BoundedSemaphore の類似物です。

よく似た threading.BoundedSemaphore とは、次の一点だけ異なります。 acquire メソッドの第一引数名は block で、Lock.acquire() と一致しています。

注釈

Mac OS X では 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() と一致しています。

注釈

Mac OS X では 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 を参照してください。

共有 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[, authkey]])

BaseManager オブジェクトを作成します。

作成後、start() または get_server().serve_forever() を呼び出して、マネージャーオブジェクトが、開始されたマネージャープロセスを確実に参照するようにしてください。

address はマネージャープロセスが新たなコネクションを待ち受けるアドレスです。address が None の場合、任意のアドレスが設定されます。

authkey はサーバープロセスへ接続しようとするコネクションの正当性を検証するために 使用される認証キーです。authkey が None の場合 current_process().authkey が使用されます。authkey を使用する場合はバイト文字列でなければなりません。

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', 5000), 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 オブジェクトを作成して、そのプロキシを返します。

バージョン 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 オブジェクトのためにプロキシを使用するとき '_' が先頭に付く属性はプロキシの属性になり、参照対象の属性にはなりません:

>>> manager = multiprocessing.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(Worker, self).__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 オブジェクト

プロキシは別のプロセスで(おそらく)有効な共有オブジェクトを 参照する オブジェクトです。共有オブジェクトはプロキシの 参照対象 になるということができます。複数のプロキシオブジェクトが同じ参照対象を持つ可能性もあります。

プロキシオブジェクトはその参照対象の対応するメソッドを呼び出すメソッドを持ちます (そうは言っても、参照対象のすべてのメソッドが必ずしもプロキシ経由で利用可能なわけではありません)。 この方法で、プロキシオブジェクトはまるでその参照先と同じように使えます:

>>> from multiprocessing import Manager
>>> manager = 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 は使用するワーカープロセスの数です。processes が None の場合 os.cpu_count() が返す値を使用します。

initializer が None ではない場合、各ワーカープロセスは開始時に initializer(*initargs) を呼び出します。

maxtasksperchild は、ワーカープロセスが exit して新たなワーカープロセスと置き替えられるまでの間に、ワーカープロセスが完了することのできるタスクの数です。この設定により未利用のリソースが解放されるようなります。デフォルトの maxtasksperchild は None で、これはワーカープロセスがプールと同じ期間だけ生き続けるということを意味します。

context はワーカープロセスを開始するために使用されるコンテキストの指定に使用できます。通常プールは関数 multiprocessing.Pool() かコンテキストオブジェクトの Pool() メソッドを使用して作成されます。どちらの場合でも context は適切に設定されます。

プールオブジェクトのメソッドは、そのプールを作成したプロセスのみが呼び出すべきです。

バージョン 3.2 で追加: maxtasksperchild

バージョン 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() メソッドの派生版で結果オブジェクトを返します。

callback が指定された場合、それは単一の引数を受け取る呼び出し可能オブジェクトでなければなりません。結果を返せるようになったときに callback が結果オブジェクトに対して適用されます。ただし呼び出しが失敗した場合は、代わりに error_callback が適用されます。

error_callback が指定された場合、それは単一の引数を受け取る呼び出し可能オブジェクトでなければなりません。対象の関数が失敗した場合、例外インスタンスを伴って error_callback が呼ばれます。

コールバックは直ちに完了すべきです。なぜなら、そうしなければ、結果を扱うスレッドがブロックするからです。

map(func, iterable[, chunksize])

map() 組み込み関数の並列版です (iterable な引数を1つだけサポートするという違いはありますが)。結果が出るまでブロックします。

このメソッドはイテラブルをいくつものチャンクに分割し、プロセスプールにそれぞれ独立したタスクとして送ります。(概算の) チャンクサイズは chunksize を正の整数に設定することで指定できます。

map_async(func, iterable[, chunksize[, callback[, error_callback]]])

map() メソッドの派生版で結果オブジェクトを返します。

callback が指定された場合、それは単一の引数を受け取る呼び出し可能オブジェクトでなければなりません。結果を返せるようになったときに callback が結果オブジェクトに対して適用されます。ただし呼び出しが失敗した場合は、代わりに error_callback が適用されます。

error_callback が指定された場合、それは単一の引数を受け取る呼び出し可能オブジェクトでなければなりません。対象の関数が失敗した場合、例外インスタンスを伴って error_callback が呼ばれます。

コールバックは直ちに完了すべきです。なぜなら、そうしなければ、結果を扱うスレッドがブロックするからです。

imap(func, iterable[, chunksize])

A lazier version of 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)] になります。

バージョン 3.3 で追加.

starmap_async(func, iterable[, chunksize[, callback[, error_callback]]])

starmap() と map_async() の組み合わせです。 イテレート可能オブジェクトの iterable をイテレートして、 unpack したイテレート可能オブジェクトを伴って func を呼び出します。結果オブジェクトを返します。

バージョン 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()

その呼び出しが例外を発生させることなく完了したかどうかを返します。その結果が返せる状態でない場合 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

リスナーとクライアント

Usually message passing between processes is done using queues or by using Connection objects returned by Pipe().

しかし 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]])

Attempt to set up a connection to the listener which is using address address, returning a 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()

Accept a connection on the bound socket or named pipe of the listener object and return a Connection object. If authentication is attempted and fails, then AuthenticationError is raised.

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と等価です。

Unix と Windows の両方で、 object_list には以下のオブジェクトを含めることが出来ます

  • a readable Connection object;
  • 接続された読み取り可能な socket.socket オブジェクト; または
  • Process オブジェクトの sentinel 属性。

読み取ることのできるデータがある場合、あるいは相手側の端が閉じられている場合、コネクションまたはソケットオブジェクトは準備ができています。

Unix: wait(object_list, timeout) は select.select(object_list, [], [], timeout) とほとんど等価です。違いは、 select.select() がシグナルによって中断される場合、 EINTR のエラー番号付きで OSError を上げるということです。 wait() はそのようなことは行いません。

Windows: object_list の要素は、 (Win32 関数 WaitForMultipleObjects() のドキュメントで使われている定義から) wait 可能な整数ハンドルか、ソケットハンドルまたはパイプハンドルを返す fileno() メソッドを持つオブジェクトのどちらかでなければなりません。 (パイプハンドルとソケットハンドラーは wait 可能なハンドルでは ない ことに注意してください。)

バージョン 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' として推測されることに注意してください。

認証キー

When one uses Connection.recv, the data received is automatically unpickled. Unfortunately unpickling data from an untrusted source is a security risk. Therefore Listener and Client() use the hmac module to provide digest authentication.

認証キーはパスワードとして見なされるバイト文字列です。コネクションが確立すると、双方の終点で正しい接続先であることを証明するために 知っているお互いの認証キーを要求します。(双方の終点が同じキーを使用して通信しようとしても、コネクション上でそのキーを送信することは できません。)

認証が要求されているにもかかわらず認証キーが指定されていない場合 current_process().authkey の返す値が使用されます。 (詳細は Process を参照してください。) この値はカレントプロセスを作成する Process オブジェクトによって自動的に継承されます。 これは(デフォルトでは)複数プロセスのプログラムの全プロセスが相互にコネクションを 確立するときに使用される1つの認証キーを共有することを意味します。

適当な認証キーを os.urandom() を使用して生成することもできます。

ログ記録

ロギングのためにいくつかの機能が利用可能です。しかし logging パッケージは、 (ハンドラー種別に依存して)違うプロセスからのメッセージがごちゃ混ぜになるので、プロセスの共有ロックを使用しないことに注意してください。

multiprocessing.get_logger()

multiprocessing が使用するロガーを返します。必要に応じて新たなロガーを作成します。

最初に作成するとき、ロガーはレベルに logging.NOTSET が設定されていてデフォルトハンドラーがありません。このロガーへ送られるメッセージはデフォルトではルートロガーへ伝播されません。

Windows 上では子プロセスが親プロセスのロガーレベルを継承しないことに注意してください。さらにその他のロガーのカスタマイズ内容もすべて継承されません。

multiprocessing.log_to_stderr()

この関数は get_logger() に対する呼び出しを実行しますが、 get_logger によって作成されるロガーを返すことに加えて、 '[%(levelname)s/%(processName)s] %(message)s' のフォーマットを使用して sys.stderr へ出力を送るハンドラーを追加します。

以下にロギングを有効にした例を紹介します:

>>> 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 モジュールのラッパーでしかありません。

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

multiprocessing を使用するときに守るべき一定のガイドラインとイディオムを挙げます。

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

以下はすべての開始方式に当てはまります。

共有状態を避ける

できるだけプロセス間で巨大なデータを移動することは避けるようにすべきです。

プロセス間の通信には、threading モジュールの低レベルな同期プリミティブを使うのではなく、キューやパイプを使うのが良いでしょう。

pickle 化の可能性

プロキシのメソッドへの引数は、 pickle 化できるものにしてください。

プロキシのスレッドセーフ性

1 つのプロキシオブジェクトは、ロックで保護しないかぎり、2 つ以上のスレッドから使用してはいけません。

(異なるプロセスで 同じ プロキシを使用することは問題ではありません。)

ゾンビプロセスを join する

Unix 上ではプロセスが終了したときに join しないと、そのプロセスはゾンビになります。新たなプロセスが開始する (または active_children() が呼ばれる) ときに、join されていないすべての完了プロセスが join されるので、あまり多くにはならないでしょう。また、終了したプロセスの Process.is_alive はそのプロセスを join します。そうは言っても、自分で開始したすべてのプロセスを明示的に join することはおそらく良いプラクティスです。

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() の行を削除します)。

明示的に子プロセスへリソースを渡す

Unix で開始方式に fork を使用している場合、子プロセスはグローバルリソースを使用した親プロセス内で作成された共有リソースを使用できます。しかし、オブジェクトを子プロセスのコンストラクターに引数として渡すべきです。

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 、 bpo-5313 、 bpo-5331 を見てください

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

開始方式に fork を適用しない場合にいくつかの追加の制限事項があります。

さらなる pickle 化の可能性

Process.__init__() へのすべての引数は pickle 化できることを確認してください。また Process をサブクラス化する場合、そのインスタンスが Process.start メソッドが呼ばれたときに pickle 化できるようにしてください。

グローバル変数

子プロセスで実行されるコードがグローバル変数にアクセスしようとする場合、子プロセスが見るその値は Process.start が呼ばれたときの親プロセスの値と同じではない可能性があります。

しかし、単にモジュールレベルの定数であるグローバル変数なら問題にはなりません。

メインモジュールの安全なインポート

新たな Python インタプリタによるメインモジュールのインポートが、意図しない副作用 (新たなプロセスを開始する等) を起こさずできるようにしてください。

例えば、開始方式に 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()

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 並行実行 »


concurrent パッケージ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 並行実行 »

concurrent パッケージ

現在のところ、このパッケージにはモジュールが1つだけあります:

  • concurrent.futures -- 並列タスク実行

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 並行実行 »


concurrent.futures -- 並列タスク実行

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 並行実行 »

concurrent.futures -- 並列タスク実行

バージョン 3.2 で追加.

ソースコード: Lib/concurrent/futures/thread.py および Lib/concurrent/futures/process.py

concurrent.futures モジュールは、非同期に実行できる呼び出し可能オブジェクトの高水準のインタフェースを提供します。

非同期実行は ThreadPoolExecutor を用いてスレッドで実行することも、 ProcessPoolExecutor を用いて別々のプロセスで実行することもできます. どちらも Executor 抽象クラスで定義された同じインターフェースを実装します。

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(func, *iterables, timeout=None, chunksize=1)

Similar to map(func, *iterables) except:

  • the iterables are collected immediately rather than lazily;
  • func is executed asynchronously and several calls to func may be made concurrently.

The returned iterator raises a concurrent.futures.TimeoutError if __next__() is called and the result isn't available after timeout seconds from the original call to Executor.map(). timeout can be an int or a float. If timeout is not specified or None, there is no limit to the wait time.

If a func 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)

executor に対して、現在保留中のフューチャーが実行された後で、使用中のすべての資源を解放するように伝えます。シャットダウンにより後に Executor.submit() と Executor.map() を呼び出すと RuntimeError が送出されます。

wait が True の場合、すべての未完了のフューチャの実行が完了して Executor に関連付けられたリソースが解放されるまで、このメソッドは返りません。 wait が False の場合、このメソッドはすぐに返り、すべての未完了のフューチャの実行が完了したときに、 Executor に関連付けられたリソースが解放されます。 wait の値に関係なく、すべての未完了のフューチャの実行が完了するまで Python プログラム全体は終了しません。

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')

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 のサブクラスです。

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 で追加: The thread_name_prefix argument was added to allow users to control the threading.Thread names for worker threads created by the pool for easier debugging.

バージョン 3.7 で変更: Added the initializer and initargs arguments.

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://some-made-up-domain.com/']

# 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=())

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 lower or equal to 0, then a ValueError will be raised. 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.

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 any attempt to submit more jobs to the pool.

バージョン 3.3 で変更: ワーカプロセスの1つが突然終了した場合、BrokenProcessPool エラーが送出されるようになりました。 以前は挙動は未定義でしたが、 executor や futures がフリーズしたりデッドロックを起こすことがしばしばでした。

バージョン 3.7 で変更: The mp_context argument was added to allow users to control the start_method for worker processes created by the pool.

Added the initializer and initargs arguments.

ProcessPoolExecutor の例

import concurrent.futures
import math

PRIMES = [
    112272535095293,
    112582705942171,
    112272535095293,
    115280095190773,
    115797848077099,
    1099726899285419]

def is_prime(n):
    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()

呼び出しのキャンセルを試みます。もし呼び出しが現在実行中でキャンセルすることができない場合、メソッドは False を返します。そうでない場合呼び出しはキャンセルされ、True を返します。

cancelled()

呼び出しが正常にキャンセルされた場合 True を返します。

running()

現在呼び出しが実行中でキャンセルできない場合 True を返します。

done()

呼び出しが正常にキャンセルされたか終了した場合 True を返します。

result(timeout=None)

呼び出しによって返された値を返します。呼び出しがまだ完了していない場合、このメソッドは timeout 秒の間待機します。呼び出しが timeout 秒間の間に完了しない場合、 concurrent.futures.TimeoutError が送出されます。 timeout にはintかfloatを指定できます。timeout が指定されていないか、 None である場合、待機時間に制限はありません。

future が完了する前にキャンセルされた場合 CancelledError が送出されます。

呼び出しが例外を送出した場合、このメソッドは同じ例外を送出します。

exception(timeout=None)

呼び出しによって送出された例外を返します。呼び出しがまだ完了していない場合、このメソッドは timeout 秒だけ待機します。呼び出しが timeout 秒の間に完了しない場合、 concurrent.futures.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 の実装またはユニットテストによってのみ使用してください。

set_exception(exception)

Future に関連付けられたワークの結果を Exception exception に設定します。

このメソッドは、 Executor の実装またはユニットテストによってのみ使用してください。

モジュール関数

concurrent.futures.wait(fs, timeout=None, return_when=ALL_COMPLETED)

fs によって与えられた (別の Executor インスタンスによって作成された可能性のある) 複数の Future インスタンスの完了を待機します。集合型を 2 要素含む名前付きのタプルを返します。1 つめの集合 done には、待機の完了前に完了したフューチャ (完了またはキャンセル済み) が含まれます。2 つめの集合 not_done には、未完了のフューチャが含まれます。

timeout で結果を返すまで待機する最大秒数を指定できます。timeout は整数か浮動小数点数をとります。timeout が指定されないか None の場合、無期限に待機します。

return_when でこの関数がいつ結果を返すか指定します。指定できる値は以下の 定数のどれか一つです:

定数 | 説明
FIRST_COMPLETED | いずれかのフューチャが終了したかキャンセルされたときに返します。
FIRST_EXCEPTION | いずれかのフューチャが例外の送出で終了した場合に返します。例外を送出したフューチャがない場合は、ALL_COMPLETED と等価になります。
ALL_COMPLETED | すべてのフューチャが終了したかキャンセルされたときに返します。
concurrent.futures.as_completed(fs, timeout=None)

フューチャの完了時 (完了またはキャンセル) に yield する fs によって与えられた (別の Executor インスタンスによって作成された可能性のある) 複数の Future インスタンスのイテレータを返します。 as_completed() が呼び出される前に完了したすべてのフューチャは最初に yield されます。__next__() が呼び出され、その結果が as_completed() の元々の呼び出しから timeout 秒経った後も利用できない場合、返されるイタレータは concurrent.futures.TimeoutError を送出します。timeout は整数または浮動小数点数です。timeout が指定されないか None である場合、待ち時間に制限はありません。

参考

PEP 3148 -- futures - execute computations asynchronously
この機能を Python 標準ライブラリに含めることを述べた提案です。

例外クラス

exception concurrent.futures.CancelledError

future がキャンセルされたときに送出されます。

exception concurrent.futures.TimeoutError

future の操作が与えられたタイムアウトを超過したときに送出されます。

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.

バージョン 3.7 で追加.

exception concurrent.futures.thread.BrokenThreadPool

Derived from BrokenExecutor, this exception class is raised when one of the workers of a ThreadPoolExecutor has failed initializing.

バージョン 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).

バージョン 3.3 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 並行実行 »


subprocess --- サブプロセス管理

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 並行実行 »

subprocess --- サブプロセス管理

ソースコード: Lib/subprocess.py

subprocess モジュールは新しいプロセスの開始、入力/出力/エラーパイプの接続、リターンコードの取得を可能とします。このモジュールは以下の古いモジュールや関数を置き換えることを目的としています：

os.system
os.spawn*

これらのモジュールや関数の代わりに、subprocess モジュールをどのように使うかについてを以下の節で説明します。

参考

PEP 324 -- subprocess モジュールを提案している PEP

subprocess モジュールを使う

サブプロセスを起動する推奨手段は、すべての用法を扱える run() 関数を使用することです。より高度な用法では下層の Popen インターフェースを直接使用することもできます。

run() 関数は Python 3.5 で追加されました; 過去のバージョンとの互換性の維持が必要な場合は、古い高水準 API 節をご覧ください。

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)

args で指定されたコマンドを実行します。コマンドの完了を待って、CompletedProcess インスタンスを返します。

The arguments shown above are merely the most common ones, described below in よく使われる引数 (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the same as that of the Popen constructor - most of the arguments to this function are passed through to that interface. (timeout, input, check, and capture_output are not.)

If capture_output is true, stdout and stderr will be captured. When used, the internal Popen object is automatically created with stdout=PIPE and stderr=PIPE. The stdout and stderr arguments may not be used as well.

引数 timeout は Popen.communicate() に渡されます。タイムアウトが発生すると、子プロセスは kill され、待機されます。子プロセスが中断されたあと TimeoutExpired が再び送出されます。

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=PIPE, and the stdin argument may not be used as well.

check に真を指定した場合、プロセスが非ゼロの終了コードで終了すると CalledProcessError 例外が送出されます。 この例外の属性には、引数、終了コード、標準出力および標準エラー出力が捕捉できた場合に格納されます。

If encoding or errors are specified, or text is true, file objects for stdin, stdout and stderr are opened in text mode using the specified encoding and errors or the io.TextIOWrapper default. The universal_newlines argument is equivalent to text and is provided for backwards compatibility. By default, file objects are opened in binary mode.

If env is not None, it must be a mapping that defines the environment variables for the new process; these are used instead of the default behavior of inheriting the current process' environment. It is passed directly to Popen.

例:

>>> 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'')

バージョン 3.5 で追加.

バージョン 3.6 で変更: Added encoding and errors parameters

バージョン 3.7 で変更: Added the text parameter, as a more understandable alias of universal_newlines. Added the capture_output parameter.

class subprocess.CompletedProcess

run() の戻り値。プロセスが終了したことを表します。

args

プロセスを起動するときに使用された引数。1 個のリストか 1 個の文字列になります。

returncode

子プロセスの終了コード。一般に、終了ステータス 0 はプロセスが正常に終了したことを示します。

負の値 -N は子プロセスがシグナル N により中止させられたことを示します (POSIX のみ)。

stdout

Captured stdout from the child process. A bytes sequence, or a string if run() was called with an encoding, errors, or text=True. None if stdout was not captured.

プロセスが stderr=subprocess.STDOUT で実行された場合、標準出力と標準エラー出力が混合されたものがこの属性に格納され、stderr は None になります。

stderr

Captured stderr from the child process. A bytes sequence, or a string if run() was called with an encoding, errors, or text=True. None if stderr was not captured.

check_returncode()

returncode が非ゼロの場合、CalledProcessError が送出されます。

バージョン 3.5 で追加.

subprocess.DEVNULL

Popen の stdin, stdout, stderr 引数に渡して、標準入出力を os.devnull から入出力するように指定するための特殊値です。

バージョン 3.3 で追加.

subprocess.PIPE

Popen の stdin, stdout, stderr 引数に渡して、標準ストリームに対するパイプを開くことを指定するための特殊値です。Popen.communicate() に非常に有用です。

subprocess.STDOUT

Popen の stderr 引数に渡して、標準エラー出力が標準出力と同じハンドルに出力されるように指定するための特殊値です。

exception subprocess.SubprocessError

このモジュールの他のすべての例外のための基底クラスです。

バージョン 3.3 で追加.

exception subprocess.TimeoutExpired

SubprocessError のサブクラスです。子プロセスの終了を待機している間にタイムアウトが発生した場合に送出されます。

cmd

子プロセスの生成に使用されるコマンド本文。

timeout

タイムアウト秒数。

output

run() または check_output() によって捕捉された子プロセスの出力。捕捉されなかったら None になります。

stdout

output の別名。stderr と対になります。

stderr

run() によって捕捉された子プロセスの標準エラー出力。捕捉されなかったら None になります。

バージョン 3.3 で追加.

バージョン 3.5 で変更: 属性 stdout および stderr が追加されました。

exception subprocess.CalledProcessError

SubprocessError のサブクラスです。check_call() または check_output() によって実行されたプロセスが非ゼロの終了ステータスを返した場合に送出されます。

returncode

子プロセスの終了ステータスです。もしプロセスがシグナルによって終了したなら、これは負のシグナル番号になります。

cmd

子プロセスの生成に使用されるコマンド本文。

output

run() または check_output() によって捕捉された子プロセスの出力。捕捉されなかったら None になります。

stdout

output の別名。stderr と対になります。

stderr

run() によって捕捉された子プロセスの標準エラー出力。捕捉されなかったら None になります。

バージョン 3.5 で変更: 属性 stdout および stderr が追加されました。

よく使われる引数

幅広い使用例をサポートするために、Popen コンストラクター (とその他の簡易関数) は、多くのオプション引数を受け付けます。一般的な用法については、これらの引数の多くはデフォルト値のままで問題ありません。通常必要とされる引数は以下の通りです:

args はすべての呼び出しに必要で、文字列あるいはプログラム引数のシーケンスでなければなりません。一般に、引数のシーケンスを渡す方が望ましいです。なぜなら、モジュールが必要な引数のエスケープやクオート (例えばファイル名中のスペースを許すこと) の面倒を見ることができるためです。単一の文字列を渡す場合、shell は True でなければなりません (以下を参照)。もしくは、その文字列は引数を指定せずに実行される単なるプログラムの名前でなければなりません。

stdin, stdout および stderr には、実行するプログラムの標準入力、標準出力、および標準エラー出力のファイルハンドルをそれぞれ指定します。有効な値は PIPE、DEVNULL、既存のファイル記述子 (正の整数)、既存のファイルオブジェクトおよび None です。PIPE を指定すると新しいパイプが子プロセスに向けて作られます。DEVNULL を指定すると特殊ファイル os.devnull が使用されます。デフォルト設定の None を指定するとリダイレクトは起こりません。子プロセスのファイルハンドルはすべて親から受け継がれます。加えて、stderr を STDOUT にすると、子プロセスの stderr からの出力は 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.

For stdin, line ending characters '\n' in the input will be converted to the default line separator os.linesep. For stdout and stderr, all line endings in the output will be converted to '\n'. For more information see the documentation of the io.TextIOWrapper class when the newline argument to its constructor is 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 encoding and errors parameters.

バージョン 3.7 で追加: Added the text parameter as an alias for universal_newlines.

注釈

ファイルオブジェクト 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=(), *, encoding=None, errors=None, text=None)

新しいプロセスで子のプログラムを実行します。POSIX においては、子のプログラムを実行するために、このクラスは os.execvp() のような挙動を使用します。Windows においては、このクラスは Windows の CreateProcess() 関数を使用します。Popen への引数は以下の通りです。

args はプログラム引数のシーケンスか、単一の文字列でなければなりません。デフォルトでは、args がシーケンスの場合に実行されるプログラムは args の最初の要素です。args が文字列の場合、解釈はプラットフォーム依存であり、下記に説明されます。デフォルトの挙動からの追加の違いについては shell および executable 引数を参照してください。特に明記されない限り、args をシーケンスとして渡すことが推奨されます。

POSIX 上では、args が文字列の場合、その文字列は実行すべきプログラムの名前またはパスとして解釈されます。しかし、これはプログラムに引数を渡さない場合にのみ可能です。

注釈

args を正しくトークン化するには、shlex.split() が便利です。このメソッドは特に複雑な状況で活躍します:

>>> 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() が文字列上で動作するからです。

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 はバッファーされないことを意味します (読み込みおよび書き出しのたびにシステムコールが行われ、すぐに復帰します)。
  • 1 はラインバッファーを意味します (universal_newlines=True、すなわちテキストモードの場合のみ使用可能)。
  • それ以外の正の整数はバッファーのおよそのサイズになることを意味します。
  • 負のサイズ (デフォルト) は io.DEFAULT_BUFFER_SIZE のシステムデフォルトが使用されることを意味します。

バージョン 3.3.1 で変更: ほとんどのコードが期待する振る舞いに合わせてデフォルトでバッファリングが有効となるよう bufsize のデフォルト値が -1 になりました。Python 3.2.4 および 3.3.1 より前のバージョンでは、誤ってバッファーされず短い読み込みを許可する 0 がデフォルトになっていました。これは意図したものではなく、ほとんどのコードが期待する Python 2 での振る舞いとも一致していませんでした。

executable 引数は、実行する置換プログラムを指定します。これが必要になるのは極めて稀です。shell=False のときは、executable は args で指定されている実行プログラムを置換します。しかし、オリジナルの args は依然としてプログラムに渡されます。ほとんどのプログラムは、args で指定されたプログラムをコマンド名として扱います。そして、それは実際に実行されたプログラムとは異なる可能性があります。POSIX において、ps のようなユーティリティの中では、args 名が実行ファイルの表示名になります。shell=True の場合、POSIX において executable 引数はデフォルトの /bin/sh に対する置換シェルを指定します。

stdin、stdout および stderr には、実行するプログラムの標準入力、標準出力、および標準エラー出力のファイルハンドルをそれぞれ指定します。有効な値は PIPE, DEVNULL, 既存のファイル記述子 (正の整数)、既存の ファイルオブジェクト 、そして None です。PIPE を指定すると新しいパイプが子プロセスに向けて作られます。DEVNULL を指定すると特殊ファイル os.devnull が使用されます。デフォルト設定の None を指定するとリダイレクトは起こりません。子プロセスのファイルハンドルはすべて親から受け継がれます。加えて、stderr を STDOUT にすると、子プロセスの標準エラー出力からの出力は標準出力と同じファイルハンドルに出力されます。

preexec_fn に呼び出し可能オブジェクトが指定されている場合、このオブジェクトは子プロセスが実行される直前 (fork されたあと、exec される直前) に子プロセス内で呼ばれます。(POSIXのみ)

警告

アプリケーション中に複数のスレッドが存在する状態で preexec_fn 引数を使用するのは安全ではありません。exec が呼ばれる前に子プロセスがデッドロックを起こすことがあります。それを使用しなければならない場合、プログラムを自明なものにしておいてください! 呼び出すライブラリの数を最小にしてください。

注釈

子プロセスのために環境を変更する必要がある場合は、preexec_fn の中でそれをするのではなく env 引数を使用します。start_new_session 引数は、子プロセスの中で os.setsid() を呼ぶ過去の一般的な preexec_fn の使用方法の代わりになります。

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 str and path-like object. In particular, the function looks for executable (or for the first item in args) relative to cwd if the executable path is a relative path.

バージョン 3.6 で変更: cwd parameter accepts a path-like object.

restore_signals が真の場合 (デフォルト)、Python が SIG_IGN に設定したすべてのシグナルは子プロセスが exec される前に子プロセスの SIG_DFL に格納されます。現在これには SIGPIPE, SIGXFZ および SIGXFSZ シグナルが含まれています。(POSIX のみ)

バージョン 3.2 で変更: restore_signals が追加されました。

start_new_session が真の場合、サブプロセスの実行前に子プロセス内で setsid() システムコールが作成されます。(POSIX のみ)

バージョン 3.2 で変更: start_new_session が追加されました。

env が None 以外の場合、これは新しいプロセスでの環境変数を定義します。デフォルトでは、子プロセスは現在のプロセスの環境変数を引き継ぎます。

注釈

env を指定する場合、プログラムを実行するのに必要な変数すべてを与えなければなりません。Windows で Side-by-Side アセンブリ を実行するためには、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.

バージョン 3.6 で追加: encoding and errors were added.

バージョン 3.7 で追加: text was added as a more readable alias for universal_newlines.

If given, startupinfo will be a STARTUPINFO object, which is passed to the underlying CreateProcess function. creationflags, if given, 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

Popen オブジェクトは with 文によってコンテキストマネージャーとしてサポートされます: 終了時には標準ファイル記述子が閉じられ、プロセスを待機します:

with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())

バージョン 3.2 で変更: コンテキストマネージャーサポートが追加されました。

バージョン 3.6 で変更: Popen destructor now emits a ResourceWarning warning if the child process is still running.

例外

Exceptions raised in the child process, before the new program has started to execute, will be re-raised in the parent. Additionally, the exception object will have one extra attribute called child_traceback, which is a string containing traceback information from the child's point of view.

もっとも一般的に起こる例外は OSError です。これは、たとえば存在しないファイルを実行しようとしたときなどに発生します。アプリケーションは OSError 例外に備えておかなければなりません。

不正な引数で Popen が呼ばれた場合は ValueError が発生します。

呼び出されたプロセスが非ゼロのリターンコードを返した場合 check_call() や check_output() は CalledProcessError を送出します。

call() や Popen.communicate() のような timeout 引数を受け取るすべての関数とメソッドは、プロセスが終了する前にタイムアウトが発生した場合に TimeoutExpired を送出します。

このモジュールで定義されたすべての例外は SubprocessError を継承しています。

バージョン 3.3 で追加: SubprocessError 基底クラスが追加されました。

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

その他一部の popen 関数と異なり、この実装は暗黙的にシステムシェルを呼び出すことはありません。これはシェルのメタ文字を含むすべての文字が子プロセスに安全に渡されることを意味します。shell=True でシェルを明示的に呼びだした場合、シェルインジェクション の脆弱性に対処するための、すべての空白やメタ文字の適切なクオートの保証はアプリケーションの責任になります。

shell=True を使用するときは、シェルコマンドで使用される文字列の空白やメタ文字は shlex.quote() 関数を使うと正しくエスケープできます。

Popen オブジェクト

Popen クラスのインスタンスには、以下のようなメソッドがあります:

Popen.poll()

Check if child process has terminated. Set and return returncode attribute. Otherwise, returns None.

Popen.wait(timeout=None)

子プロセスが終了するまで待ちます。returncode 属性を設定して返します。

プロセスが timeout 秒後に終了してない場合、TimeoutExpired 例外を送出します。この例外を捕捉して wait を再試行するのは安全です。

注釈

stdout=PIPE や stderr=PIPE を使っていて、より多くのデータを受け入れるために OS のパイプバッファーをブロックしているパイプに子プロセスが十分な出力を生成した場合、デッドロックが発生します。これを避けるには Popen.communicate() を使用してください。

注釈

この関数はビジーループ (非ブロック化呼び出しと短いスリープ) を使用して実装されています。非同期の待機には asyncio モジュールを使用してください (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. 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 シグナルを子プロセスに送ります。

注釈

Windows では、SIGTERM は terminate() の別名です。CTRL_C_EVENT と CTRL_BREAK_EVENT を、CREATE_NEW_PROCESS_GROUP を含む creationflags で始まった、プロセスに送れます。

Popen.terminate()

子プロセスを停止します。Posix OS では、このメソッドは SIGTERM シグナルを子プロセスに送ります。Windows では、Win32 API の TerminateProcess() 関数を利用して子プロセスを止めます。

Popen.kill()

子プロセスを kill します。Posix OS では SIGKILL シグナルを子プロセスに送ります。Windows では、kill() は terminate() の別名です。

以下の属性も利用可能です:

Popen.args

Popen に渡された引数 args です -- プログラム引数のシーケンスまたは 1 個の文字列になります。

バージョン 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 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 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 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

poll() か wait() (か、間接的に communicate()) から設定された、子プロセスの終了ステータスが入ります。None はまだその子プロセスが終了していないことを示します。

負の値 -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 structure is used for Popen creation. The following attributes can be set by passing them as keyword-only arguments.

バージョン 3.7 で変更: Keyword-only argument support was added.

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 関数の nCmdShow 引数で指定された値なら、 SW_SHOWDEFAULT 以外の任意のものにできます。しかし、この属性は無視されます。

この属性には SW_HIDE が提供されています。これは、Popen が shell=True として呼び出されたときに使われます。

lpAttributeList

A dictionary of additional attributes for process creation as given in STARTUPINFOEX, see UpdateProcThreadAttribute.

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.

バージョン 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.

バージョン 3.7 で追加.

subprocess.BELOW_NORMAL_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have a below average priority.

バージョン 3.7 で追加.

subprocess.HIGH_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have a high priority.

バージョン 3.7 で追加.

subprocess.IDLE_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have an idle (lowest) priority.

バージョン 3.7 で追加.

subprocess.NORMAL_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have an normal priority. (default)

バージョン 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.

バージョン 3.7 で追加.

subprocess.CREATE_NO_WINDOW

A Popen creationflags parameter to specify that a new process will not create a window

バージョン 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.

バージョン 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.

バージョン 3.7 で追加.

subprocess.CREATE_BREAKAWAY_FROM_JOB

A Popen creationflags parameter to specify that a new process is not associated with the job.

バージョン 3.7 で追加.

古い高水準 API

Python 3.5 より前のバージョンでは、サブプロセスに対して以下の 3 つの関数からなる高水準 API が用意されていました。現在多くの場合 run() の使用で済みますが、既存の多くのコードではこれらの関数が使用されています。

subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None)

args で指定されたコマンドを実行します。コマンドの終了を待ち、returncode 属性を返します。

これは次と等価です:

run(...).returncode

(input および check 引数がサポートされていない点を除いて)

上記の引数は、もっともよく使われるものだけ示しています。関数の全使用法は大部分が Popen コンストラクターの内容と同じになります - この関数は、このインターフェースに直接指定される timeout 以外は与えられた全引数を渡します。

注釈

この関数を使用する際は stdout=PIPE および stderr=PIPE を使用しないでください。子プロセスが OS のパイプバッファーを埋めてしまうほどの出力データを生成した場合、パイプからは読み込まれないので、子プロセスがブロックされることがあります。

バージョン 3.3 で変更: timeout が追加されました

subprocess.check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None)

指定された引数でコマンドを実行し、完了を待ちます。コマンドのリターンコードがゼロならば返りますが、非ゼロなら CalledProcessError 例外が送出されます。CalledProcessError オブジェクトにはリターンコードが returncode 属性として格納されています。

これは次と等価です:

run(..., check=True)

(input 引数が無い点を除いて)

上記の引数は、もっともよく使われるものだけ示しています。関数の全使用法は大部分が Popen コンストラクターの内容と同じになります - この関数は、このインターフェースに直接指定される timeout 以外は与えられた全引数を渡します。

注釈

この関数を使用する際は stdout=PIPE および stderr=PIPE を使用しないでください。子プロセスが OS のパイプバッファーを埋めてしまうほどの出力データを生成した場合、パイプからは読み込まれないので、子プロセスがブロックされることがあります。

バージョン 3.3 で変更: timeout が追加されました

subprocess.check_output(args, *, stdin=None, stderr=None, shell=False, cwd=None, encoding=None, errors=None, universal_newlines=None, timeout=None, text=None)

引数でコマンドを実行し、その出力を返します。

コマンドのリターンコードが非ゼロならば CalledProcessError 例外が送出されます。CalledProcessError オブジェクトには、リターンコードが returncode 属性に、コマンドからの出力が output 属性に、それぞれ格納されています。

これは次と等価です:

run(..., check=True, stdout=PIPE).stdout

上記の引数は、もっともよく使われるものだけ示しています。関数の全使用法は大部分が run() の内容と同じになります - ほとんどの引数は直接そのインターフェースに渡されますが、親の標準入力ファイルハンドルの継承がサポートされていない場合は input=None を明示的に指定する必要があります。

デフォルトで、この関数はデータをエンコードされたバイトとして返します。出力されたデータの実際のエンコードは起動されているコマンドに依存するため、テキストへのデコードは通常アプリケーションレベルで扱う必要があります。

この振る舞いは、上記 よく使われる引数 で説明されているように universal_newlines に True を設定することでオーバーライドされます。

標準エラー出力も結果に含めるには、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'

バージョン 3.1 で追加.

バージョン 3.3 で変更: timeout が追加されました

バージョン 3.4 で変更: キーワード引数 input が追加されました。

バージョン 3.6 で変更: encoding and errors were added. See run() for details.

バージョン 3.7 で追加: text was added as a more readable alias for universal_newlines.

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

この節では、 "a becomes b" と書かれているものは a の代替として b が使えるということを表します。

注釈

この節で紹介されている "a" 関数は全て、実行するプログラムが見つからないときは (おおむね) 静かに終了します。それに対して "b" 代替手段は OSError 例外を送出します。

また、要求された操作が非ゼロの終了コードを返した場合、check_output() を使用した置き換えは CalledProcessError で失敗します。その出力は、送出された例外の output 属性として利用可能です。

以下の例では、適切な関数が subprocess モジュールからすでにインポートされていることを前提としています。

/bin/sh シェルのバッククォートを置き換える

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
sts = call("mycmd" + " myarg", shell=True)

注釈:

  • このプログラムは普通シェル経由で呼び出す必要はありません。

より現実的な例ではこうなるでしょう:

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")

popen2 モジュールの関数群を置き換える

注釈

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)

Return (exitcode, output) of executing cmd in a shell.

Execute the string cmd in a shell with Popen.check_output() and return a 2-tuple (exitcode, output). The locale encoding is used; 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: POSIX & Windows.

バージョン 3.3.4 で変更: Windows support was added.

The function now returns (exitcode, output) instead of (status, output) as it did in Python 3.3.3 and earlier. exitcode has the same value as returncode.

subprocess.getoutput(cmd)

シェル中の cmd を実行して出力 (stdout と stderr) を返します。

Like getstatusoutput(), except the exit code is ignored and the return value is a string containing the command's output. Example:

>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'

Availability: POSIX & Windows.

バージョン 3.3.4 で変更: Windowsで利用可能になりました

注釈

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

Windows では、 args シーケンスは以下の (MS C ランタイムで使われる規則に対応する) 規則を使って解析できる文字列に変換されます:

  1. 引数は、スペースかタブのどちらかの空白で分けられます。
  2. ダブルクオーテーションマークで囲まれた文字列は、空白が含まれていたとしても 1 つの引数として解釈されます。クオートされた文字列は引数に埋め込めます。
  3. バックスラッシュに続くダブルクオーテーションマークは、リテラルのダブルクオーテーションマークと解釈されます。
  4. バックスラッシュは、ダブルクオーテーションが続かない限り、リテラルとして解釈されます。
  5. 複数のバックスラッシュにダブルクオーテーションマークが続くなら、バックスラッシュ 2 つで 1 つのバックスラッシュ文字と解釈されます。バックスラッシュの数が奇数なら、最後のバックスラッシュは規則 3 に従って続くダブルクオーテーションマークをエスケープします。

参考

shlex
コマンドラインを解析したりエスケープしたりする関数を提供するモジュール。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 並行実行 »


sched --- イベントスケジューラ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 並行実行 »

sched --- イベントスケジューラ

ソースコード: Lib/sched.py

sched モジュールは一般的な目的のためのイベントスケジューラを実装するクラスを定義します:

class sched.scheduler(timefunc=time.monotonic, delayfunc=time.sleep)

scheduler クラスはイベントをスケジュールするための一般的なインタフェースを定義します。それは "外の世界" を実際に扱うための2つの関数を必要とします --- timefunc は引数なしで呼ばれて 1 つの数値を返す callable オブジェクトでなければなりません (戻り値は任意の単位で「時間」を表します)。 time.monotonic が利用出来ない場合、 timefunc のデフォルトには time.time が代わりに使われます。 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',))
...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
...     s.run()
...     print(time.time())
...
>>> print_some_times()
930343690.257
From print_time 930343695.274 positional
From print_time 930343695.275 keyword
From print_time 930343700.273 default
930343700.276

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

scheduler インスタンスは以下のメソッドと属性を持っています:

scheduler.enterabs(time, priority, action, argument=(), kwargs={})

Schedule a new event. The time argument should be a numeric type compatible with the return value of the timefunc function passed to the constructor. Events scheduled for the same time will be executed in the order of their priority. A lower number represents a higher priority.

イベントを実行することは、 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)

すべてのスケジュールされたイベントを実行します。このメソッドは次のイベントを待ち、それを実行し、スケジュールされたイベントがなくなるまで同じことを繰り返します。(イベントの待機は、 コンストラクタへ渡された関数 delayfunc() を使うことで行います。)

blocking が False の場合、最も早く期限が来るスケジュールされたイベントを (存在する場合) 実行し、スケジューラ内で次にスケジュールされた呼び出しの期限を (存在する場合) 返します。

action あるいは delayfunc は例外を投げることができます。いずれの場合も、スケジューラは一貫した状態を維持し、例外を伝播するでしょう。例外が action によって投げられる場合、イベントは run() への呼出しを未来に行なわないでしょう。

イベントのシーケンスが、次イベントの前に、利用可能時間より実行時間が長いと、スケジューラは単に遅れることになるでしょう。イベントが落ちることはありません; 呼出しコードはもはや適切でないキャンセルイベントに対して責任があります。

バージョン 3.3 で追加: blocking 引数が追加されました。

scheduler.queue

読み出し専用の属性で、これから起こるイベントが実行される順序で格納されたリストを返します。各イベントは、次の属性 time, priority, action, argument, kwargs を持った named tuple の形式になります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 並行実行 »


queue --- 同期キュークラス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 並行実行 »

queue --- 同期キュークラス

ソースコード: Lib/queue.py

queue モジュールは、複数プロデューサ-複数コンシューマ(multi-producer, multi-consumer)キューを実装します。これは、複数のスレッドの間で情報を安全に交換しなければならないときのマルチスレッドプログラミングで特に有益です。このモジュールの Queue クラスは、必要なすべてのロックセマンティクスを実装しています。これはPythonのスレッドサポートの状況に依存します。 threading モジュールを参照してください。

このモジュールでは3種類のキューが実装されています。それらはキューから取り出されるエントリの順番だけが違います。 FIFO キューでは、最初に追加されたエントリが最初に取り出されます。 LIFO キューでは、最後に追加されたエントリが最初に取り出されます(スタックのように振る舞います)。 優先順位付きキュー(priority queue)では、エントリは(heapq モジュールを利用して)ソートされ、 最も低い値のエントリが最初に取り出されます。

Internally, those three types of queues use locks to temporarily block competing threads; however, they are not designed to handle reentrancy within a thread.

In addition, the module implements a "simple" 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以下であるならば、キューの大きさは無限です。

最小の値を持つ要素が最初に検索されます (最小の値を持つ値は、sorted(list(entries))[0] によって返されるものです)。典型的な要素のパターンは、(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.

バージョン 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, False) と等価です。

Queue.get(block=True, timeout=None)

キューからアイテムを取り除き、それを返します。 オプション引数 block が真で timeout が None (デフォルト) の場合は、必要であればアイテムが取り出せるようになるまでブロックします。 もし timeout が正の数の場合は、最大で timeout 秒間ブロックし、その時間内でアイテムが取り出せるようにならなければ、例外 Empty を送出します。 そうでない場合 (block が偽) は、直ちにアイテムが取り出せるならば、それを返します。 できないならば、例外 Empty を送出します (この場合 timeout は無視されます)。

Queue.get_nowait()

get(False) と等価です。

キューに入れられたタスクが全てコンシューマスレッドに処理されたかどうかを追跡するために 2つのメソッドが提供されます。

Queue.task_done()

過去にキューに入れられたタスクが完了した事を示します。キューのコンシューマスレッドに利用されます。タスクの取り出しに使われた各 get() の後に task_done() を呼び出すと、取り出したタスクに対する処理が完了した事をキューに教えます。

join() がブロックされていた場合、全itemが処理された (キューに put() された全てのitemに対して task_done() が呼び出されたことを意味します) 時に復帰します。

キューにある要素より多く呼び出された場合 ValueError が発生します。

Queue.join()

キューにあるすべてのアイテムが取り出されて処理されるまでブロックします。

キューにitemが追加される度に、未完了タスクカウントが増やされます。コンシューマスレッドが task_done() を呼び出して、itemを受け取ってそれに対する処理が完了した事を知らせる度に、未完了タスクカウントが減らされます。未完了タスクカウントが0になったときに、 join() のブロックが解除されます。

キューに入れたタスクが完了するのを待つ例:

def worker():
    while True:
        item = q.get()
        if item is None:
            break
        do_work(item)
        q.task_done()

q = queue.Queue()
threads = []
for i in range(num_worker_threads):
    t = threading.Thread(target=worker)
    t.start()
    threads.append(t)

for item in source():
    q.put(item)

# block until all tasks are done
q.join()

# stop workers
for i in range(num_worker_threads):
    q.put(None)
for t in threads:
    t.join()

SimpleQueue Objects

SimpleQueue objects provide the public methods described below.

SimpleQueue.qsize()

Return the approximate size of the queue. Note, qsize() > 0 doesn't guarantee that a subsequent get() will not block.

SimpleQueue.empty()

Return True if the queue is empty, False otherwise. If empty() returns False it doesn't guarantee that a subsequent call to get() will not block.

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 implementation detail: 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)

Equivalent to put(item), provided for compatibility with Queue.put_nowait().

SimpleQueue.get(block=True, timeout=None)

Remove and return an item from the queue. If optional args block is true and timeout is None (the default), block if necessary until an item is available. If timeout is a positive number, it blocks at most timeout seconds and raises the Empty exception if no item was available within that time. Otherwise (block is false), return an item if one is immediately available, else raise the Empty exception (timeout is ignored in that case).

SimpleQueue.get_nowait()

get(False) と等価です。

参考

multiprocessing.Queue クラス
(マルチスレッドではなく) マルチプロセスの文脈で使用されるキュークラス。

collections.deque は、ロックなしで append() や popleft() といったアトミック操作が可能なキューの実装です。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 並行実行 »


_thread --- 低水準の スレッド API

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 並行実行 »

_thread --- 低水準の スレッド API

このモジュールはマルチスレッド (別名 軽量プロセス (light-weight processes)または タスク (tasks)) に用いられる低水準プリミティブを提供します --- グローバルデータ空間を共有するマルチスレッドを制御します。同期のための単純なロック (別名 mutexes またはバイナリセマフォ (binary semaphores))が提供されています。 threading モジュールは、このモジュール上で、より使い易く高級なスレッディングの API を提供します。

バージョン 3.7 で変更: This module used to be optional, it is now always available.

This module defines the following constants and functions:

exception _thread.error

スレッド固有の例外です。

バージョン 3.3 で変更: 現在は組み込みの RuntimeError の別名です。

_thread.LockType

これはロックオブジェクトのタイプです。

_thread.start_new_thread(function, args[, kwargs])

新しいスレッドを開始して、そのIDを返します。スレッドは引数リスト args (タプルでなければなりません)の関数 function を実行します。オプション引数 kwargs はキーワード引数の辞書を指定します。関数が戻るとき、スレッドは静かに終了します。関数が未定義の例外でターミネートしたとき、スタックトレースが表示され、そしてスレッドが終了します (しかし他のスレッドは走り続けます)。

_thread.interrupt_main()

メインスレッドで KeyboardInterrupt を送出します。サブスレッドはこの関数を使ってメインスレッドに割り込みをかけることができます。

_thread.exit()

SystemExit を送出します。それが捕えられないときは、静かにスレッドを終了させます。

_thread.allocate_lock()

新しいロックオブジェクトを返します。ロックのメソッドはこの後に記述されます。ロックは初期状態としてアンロック状態です。

_thread.get_ident()

現在のスレッドの 'スレッドID' を返します。非ゼロの整数です。この値は直接の意味を持っていません; 例えばスレッド特有のデータの辞書に索引をつけるためのような、マジッククッキーとして意図されています。スレッドが終了し、他のスレッドが作られたとき、スレッド ID は再利用されるかもしれません。

_thread.stack_size([size])

Return the thread stack size used when creating new threads. The optional size argument specifies the stack size to be used for subsequently created threads, and must be 0 (use platform or configured default) or a positive integer value of at least 32,768 (32 KiB). If size is not specified, 0 is used. If changing the thread stack size is unsupported, a RuntimeError is raised. If the specified stack size is invalid, a ValueError is raised and the stack size is unmodified. 32 KiB is currently the minimum supported stack size value to guarantee sufficient stack space for the interpreter itself. Note that some platforms may have particular restrictions on values for the stack size, such as requiring a minimum stack size > 32 KiB or requiring allocation in multiples of the system memory page size - platform documentation should be referred to for more information (4 KiB pages are common; using multiples of 4096 for the stack size is the suggested approach in the absence of more specific information).

Availability: Windows, systems with POSIX threads.

_thread.TIMEOUT_MAX

Lock.acquire() の timeout 引数に許される最大値です。これ以上の値を timeout に指定すると OverflowError を発生させます。

バージョン 3.2 で追加.

ロックオブジェクトは次のようなメソッドを持っています:

lock.acquire(waitflag=1, timeout=-1)

オプションの引数なしで使用すると、このメソッドは他のスレッドがロックしているかどうかにかかわらずロックを獲得します。ただし、他のスレッドがすでにロックしている場合には解除されるまで待ってからロックを獲得します (同時にロックを獲得できるスレッドはひとつだけであり、これこそがロックの存在理由です)。

整数の引数 waitflag を指定すると、その値によって動作が変わります。引数が 0 のときは、待たずにすぐ獲得できる場合にだけロックを獲得します。0 以外の値を与えると、先の例と同様、ロックの状態にかかわらず獲得をおこないます。

timeout 引数に正の float 値が指定された場合、返る前に待つ最大の時間を秒数で指定します。負の timeout 引数は無制限に待つことを指定します。waitflag が 0 の時は timeout を指定することはできません。

なお、ロックを獲得できた場合は 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() を呼び出すことと同じです。
  • ロックの acquire() メソッドに割り込むことはできません --- KeyboardInterrupt 例外は、ロックが獲得された後に発生します。
  • メインスレッドが終了したとき、他のスレッドが生き残るかどうかは、システムに依存します。多くのシステムでは、 try ... finally 節や、オブジェクトデストラクタを実行せずに終了されます。
  • メインスレッドが終了したとき、それの通常のクリーンアップは行なわれず、 (try ... finally 節が尊重されることは除きます)、標準 I/O ファイルはフラッシュされません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 並行実行 »


_dummy_thread --- _thread の代替モジュール

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 並行実行 »

_dummy_thread --- _thread の代替モジュール

ソースコード: Lib/_dummy_thread.py

バージョン 3.7 で非推奨: Python now always has threading enabled. Please use _thread (or, better, threading) instead.

This module provides a duplicate interface to the _thread module. It was meant to be imported when the _thread module was not provided on a platform.

生成するスレッドが、他のブロックしたスレッドを待ち、デッドロック発生の可能性がある場合には、このモジュールを使わないようにしてください。ブロッキング I/O を使っている場合によく起きます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 並行実行 »


dummy_threading --- threading の代替モジュール

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 並行実行 »

dummy_threading --- threading の代替モジュール

ソースコード: Lib/dummy_threading.py

バージョン 3.7 で非推奨: Python now always has threading enabled. Please use threading instead.

This module provides a duplicate interface to the threading module. It was meant to be imported when the _thread module was not provided on a platform.

生成するスレッドが、他のブロックしたスレッドを待ち、デッドロック発生の可能性がある場合には、このモジュールを使わないようにしてください。ブロッキング I/O を使っている場合によく起きます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 並行実行 »


contextvars --- コンテキスト変数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

contextvars --- コンテキスト変数

このモジュールは、コンテキストローカルな状態を管理し、保持し、アクセスするための API を提供します。 ContextVar クラスは コンテキスト変数 を宣言し、取り扱うために使われます。 非同期フレームワークで現時点のコンテキストを管理するのには、 copy_context() 関数と Context クラスを使うべきです。

状態を持っているコンテキストマネージャは threading.local() ではなくコンテキスト変数を使い、並行処理のコードから状態が意図せず他のコードへ漏れ出すのを避けるべきです。

より詳しくは PEP 567 を参照をしてください。

バージョン 3.7 で追加.

コンテキスト変数

class contextvars.ContextVar(name[, *, default])

このクラスは新しいコンテキスト変数を宣言するのに使われます。例えば、次の通りです:

var: ContextVar[int] = ContextVar('var', default=42)

必須のパラメータの name は内観やデバッグの目的で使われます。

オプションのキーワードのみ引数 default は、現在のコンテキストにその変数の値が見付からなかったときに ContextVar.get() から返されます。

Important: Context Variables should be created at the top module level and never in closures. Context objects hold strong references to context variables which prevents context variables from being properly garbage collected.

name

The name of the variable. This is a read-only property.

バージョン 3.7.1 で追加.

get([default])

Return a value for the context variable for the current context.

If there is no value for the variable in the current context, the method will:

  • return the value of the default argument of the method, if provided; or
  • return the default value for the context variable, if it was created with one; or
  • raise a LookupError.
set(value)

Call to set a new value for the context variable in the current context.

The required value argument is the new value for the context variable.

Returns a Token object that can be used to restore the variable to its previous value via the ContextVar.reset() method.

reset(token)

Reset the context variable to the value it had before the ContextVar.set() that created the token was used.

例えば:

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 objects are returned by the ContextVar.set() method. They can be passed to the ContextVar.reset() method to revert the value of the variable to what it was before the corresponding set.

Token.var

A read-only property. Points to the ContextVar object that created the token.

Token.old_value

A read-only property. Set to the value the variable had before the ContextVar.set() method call that created the token. It points to Token.MISSING is the variable was not set before the call.

Token.MISSING

A marker object used by Token.old_value.

Manual Context Management

contextvars.copy_context()

Returns a copy of the current Context object.

The following snippet gets a copy of the current context and prints all variables and their values that are set in it:

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

A mapping of ContextVars to their values.

Context() creates an empty context with no values in it. To get a copy of the current context use the copy_context() function.

Context implements the collections.abc.Mapping interface.

run(callable, *args, **kwargs)

Execute callable(*args, **kwargs) code in the context object the run method is called on. Return the result of the execution or propagate an exception if one occurred.

Any changes to any context variables that callable makes will be contained in the context object:

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'

The method raises a RuntimeError when called on the same context object from more than one OS thread, or when called recursively.

copy()

Return a shallow copy of the context object.

var in context

Return True if the context has a value for var set; return False otherwise.

context[var]

Return the value of the var ContextVar variable. If the variable is not set in the context object, a KeyError is raised.

get(var[, default])

Return the value for var if var has the value in the context object. Return default otherwise. If default is not given, return None.

iter(context)

Return an iterator over the variables stored in the context object.

len(proxy)

Return the number of variables set in the context object.

keys()

Return a list of all variables in the context object.

values()

Return a list of all variables' values in the context object.

items()

Return a list of 2-tuples containing all variables and their values in the context object.

asyncio support

Context variables are natively supported in asyncio and are ready to be used without any extra configuration. For example, here is a simple echo server, that uses a context variable to make the address of a remote client available in the Task that handles that client:

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


Networking and Interprocess Communication

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

Networking and Interprocess Communication

The modules described in this chapter provide mechanisms for networking and inter-processes communication.

例えば signal や mmap のように、同じマシン上の 2 つのプロセスでしか使えないモジュールがあります。その他のモジュールは 2 つ以上のプロセスを使ってマシン間で通信できるネットワークプロトコルをサポートします。

この章で解説されるモジュールのリスト:

  • asyncio --- Asynchronous I/O
  • socket --- 低水準ネットワークインターフェイス
  • ssl --- ソケットオブジェクトに対する TLS/SSL ラッパー
  • select --- I/O 処理の完了を待機する
  • selectors --- 高水準の I/O 多重化
  • asyncore --- 非同期ソケットハンドラ
  • asynchat --- 非同期ソケットコマンド/レスポンスハンドラ
  • signal --- 非同期イベントにハンドラを設定する
  • mmap --- メモリマップファイル

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


asyncio --- Asynchronous I/O

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »

asyncio --- Asynchronous I/O

Hello World!

import asyncio

async def main():
    print('Hello ...')
    await asyncio.sleep(1)
    print('... World!')

# Python 3.7+
asyncio.run(main())

asyncio is a library to write concurrent code using the async/await syntax.

asyncio is used as a foundation for multiple Python asynchronous frameworks that provide high-performance network and web-servers, database connection libraries, distributed task queues, etc.

asyncio is often a perfect fit for IO-bound and high-level structured network code.

asyncio provides a set of high-level APIs to:

  • run Python coroutines concurrently and have full control over their execution;
  • perform network IO and IPC;
  • control subprocesses;
  • distribute tasks via queues;
  • synchronize concurrent code;

Additionally, there are low-level APIs for library and framework developers to:

  • create and manage event loops, which provide asynchronous APIs for networking, running subprocesses, handling OS signals, etc;
  • implement efficient protocols using transports;
  • bridge callback-based libraries and code with async/await syntax.

リファレンス

High-level APIs

  • コルーチンと Task
  • Streams
  • Synchronization Primitives
  • Subprocesses
  • キュー
  • 例外

Low-level APIs

  • Event Loop
  • Future
  • Transports and Protocols
  • Policies
  • Platform Support

Guides and Tutorials

  • 高水準の API インデックス
  • Low-level API Index
  • Developing with asyncio

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Networking and Interprocess Communication »


コルーチンと Task

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

コルーチンと Task

この節では、コルーチンと Task を利用する高レベルの asyncio の API の概略を解説します。

  • コルーチン
  • Awaitables
  • Running an asyncio Program
  • Creating Tasks
  • Sleeping
  • Running Tasks Concurrently
  • Shielding From Cancellation
  • Timeouts
  • Waiting Primitives
  • Scheduling From Other Threads
  • Introspection
  • Task Object
  • Generator-based Coroutines

コルーチン

async/await 構文で宣言されたコルーチンは、 asyncio を使ったアプリケーションを書く手法として好ましいです。 例えば、次のコードスニペット (Python 3.7 以降が必要) は "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 では主なもので 3 つの機構が提供されています:

  • 最上位のエントリーポイントである "main()" 関数を実行する asyncio.run() 関数 (上の例を参照してください。)

  • Awaiting on a coroutine. The following snippet of code will print "hello" after waiting for 1 second, and then print "world" after waiting for another 2 seconds:

    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

  • The asyncio.create_task() function to run coroutines concurrently as asyncio Tasks.

    Let's modify the above example and run two say_after coroutines concurrently:

    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')}")

    Note that expected output now shows that the snippet runs 1 second faster than before:

    started at 17:14:32
hello
world
finished at 17:14:34

Awaitables

We say that an object is an awaitable object if it can be used in an await expression. Many asyncio APIs are designed to accept awaitables.

There are three main types of awaitable objects: coroutines, Tasks, and Futures.

コルーチン

Python coroutines are awaitables and therefore can be awaited from other coroutines:

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())

重要

In this documentation the term "coroutine" can be used for two closely related concepts:

  • a coroutine function: an async def function;
  • a coroutine object: an object returned by calling a coroutine function.

asyncio also supports legacy generator-based coroutines.

タスク

Tasks are used to schedule coroutines concurrently.

When a coroutine is wrapped into a Task with functions like asyncio.create_task() the coroutine is automatically scheduled to run soon:

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

A Future is a special low-level awaitable object that represents an eventual result of an asynchronous operation.

When a Future object is awaited it means that the coroutine will wait until the Future is resolved in some other place.

Future objects in asyncio are needed to allow callback-based code to be used with async/await.

Normally there is no need to create Future objects at the application level code.

Future objects, sometimes exposed by libraries and some asyncio APIs, can be awaited:

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()
    )

A good example of a low-level function that returns a Future object is loop.run_in_executor().

Running an asyncio Program

asyncio.run(coro, *, debug=False)

This function runs the passed coroutine, taking care of managing the asyncio event loop and finalizing asynchronous generators.

This function cannot be called when another asyncio event loop is running in the same thread.

If debug is True, the event loop will be run in debug mode.

This function always creates a new event loop and closes it at the end. It should be used as a main entry point for asyncio programs, and should ideally only be called once.

バージョン 3.7 で追加: Important: this function has been added to asyncio in Python 3.7 on a provisional basis.

Creating Tasks

asyncio.create_task(coro)

Wrap the coro coroutine into a Task and schedule its execution. Return the Task object.

The task is executed in the loop returned by get_running_loop(), RuntimeError is raised if there is no running loop in current thread.

This function has been added in Python 3.7. Prior to Python 3.7, the low-level asyncio.ensure_future() function can be used instead:

async def coro():
    ...

# In Python 3.7+
task = asyncio.create_task(coro())
...

# This works in all Python versions but is less readable
task = asyncio.ensure_future(coro())
...

バージョン 3.7 で追加.

Sleeping

coroutine asyncio.sleep(delay, result=None, *, loop=None)

Block for delay seconds.

If result is provided, it is returned to the caller when the coroutine completes.

sleep() always suspends the current task, allowing other tasks to run.

The loop argument is deprecated and scheduled for removal in Python 3.10.

Example of coroutine displaying the current date every second for 5 seconds:

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())

Running Tasks Concurrently

awaitable asyncio.gather(*aws, loop=None, return_exceptions=False)

Run awaitable objects in the aws sequence concurrently.

If any awaitable in aws is a coroutine, it is automatically scheduled as a Task.

If all awaitables are completed successfully, the result is an aggregate list of returned values. The order of result values corresponds to the order of awaitables in aws.

If return_exceptions is False (default), the first raised exception is immediately propagated to the task that awaits on gather(). Other awaitables in the aws sequence won't be cancelled and will continue to run.

If return_exceptions is True, exceptions are treated the same as successful results, and aggregated in the result list.

If gather() is cancelled, all submitted awaitables (that have not completed yet) are also cancelled.

If any Task or Future from the aws sequence is cancelled, it is treated as if it raised CancelledError -- the gather() call is not cancelled in this case. This is to prevent the cancellation of one submitted Task/Future to cause other Tasks/Futures to be cancelled.

以下はプログラム例です:

import asyncio

async def factorial(name, number):
    f = 1
    for i in range(2, number + 1):
        print(f"Task {name}: Compute factorial({i})...")
        await asyncio.sleep(1)
        f *= i
    print(f"Task {name}: factorial({number}) = {f}")

async def main():
    # Schedule three calls *concurrently*:
    await asyncio.gather(
        factorial("A", 2),
        factorial("B", 3),
        factorial("C", 4),
    )

asyncio.run(main())

# Expected output:
#
#     Task A: Compute factorial(2)...
#     Task B: Compute factorial(2)...
#     Task C: Compute factorial(2)...
#     Task A: factorial(2) = 2
#     Task B: Compute factorial(3)...
#     Task C: Compute factorial(3)...
#     Task B: factorial(3) = 6
#     Task C: Compute factorial(4)...
#     Task C: factorial(4) = 24

バージョン 3.7 で変更: If the gather itself is cancelled, the cancellation is propagated regardless of return_exceptions.

Shielding From Cancellation

awaitable asyncio.shield(aw, *, loop=None)

Protect an awaitable object from being cancelled.

If aw is a coroutine it is automatically scheduled as a Task.

命令文:

res = await shield(something())

は、以下と同じです

res = await something()

except that if the coroutine containing it is cancelled, the Task running in something() is not cancelled. From the point of view of something(), the cancellation did not happen. Although its caller is still cancelled, so the "await" expression still raises a CancelledError.

If something() is cancelled by other means (i.e. from within itself) that would also cancel shield().

If it is desired to completely ignore cancellation (not recommended) the shield() function should be combined with a try/except clause, as follows:

try:
    res = await shield(something())
except CancelledError:
    res = None

Timeouts

coroutine asyncio.wait_for(aw, timeout, *, loop=None)

Wait for the aw awaitable to complete with a timeout.

If aw is a coroutine it is automatically scheduled as a Task.

timeout can either be None or a float or int number of seconds to wait for. If timeout is None, block until the future completes.

If a timeout occurs, it cancels the task and raises asyncio.TimeoutError.

To avoid the task cancellation, wrap it in shield().

The function will wait until the future is actually cancelled, so the total wait time may exceed the timeout.

If the wait is cancelled, the future aw is also cancelled.

The loop argument is deprecated and scheduled for removal in Python 3.10.

以下はプログラム例です:

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 asyncio.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 asyncio.TimeoutError immediately.

Waiting Primitives

coroutine asyncio.wait(aws, *, loop=None, timeout=None, return_when=ALL_COMPLETED)

Run awaitable objects in the aws set concurrently and block until the condition specified by return_when.

If any awaitable in aws is a coroutine, it is automatically scheduled as a Task. Passing coroutines objects to wait() directly is deprecated as it leads to confusing behavior.

Returns two sets of Tasks/Futures: (done, pending).

使い方:

done, pending = await asyncio.wait(aws)

The loop argument is deprecated and scheduled for removal in Python 3.10.

timeout (a float or int), if specified, can be used to control the maximum number of seconds to wait before returning.

Note that this function does not raise asyncio.TimeoutError. Futures or Tasks that aren't done when the timeout occurs are simply returned in the second set.

return_when でこの関数がいつ結果を返すか指定します。指定できる値は以下の 定数のどれか一つです:

定数 | 説明
FIRST_COMPLETED | いずれかのフューチャが終了したかキャンセルされたときに返します。
FIRST_EXCEPTION | いずれかのフューチャが例外の送出で終了した場合に返します。例外を送出したフューチャがない場合は、ALL_COMPLETED と等価になります。
ALL_COMPLETED | すべてのフューチャが終了したかキャンセルされたときに返します。

Unlike wait_for(), wait() does not cancel the futures when a timeout occurs.

注釈

wait() schedules coroutines as Tasks automatically and later returns those implicitly created Task objects in (done, pending) sets. Therefore the following code won't work as expected:

async def foo():
    return 42

coro = foo()
done, pending = await asyncio.wait({coro})

if coro in done:
    # This branch will never be run!

Here is how the above snippet can be fixed:

async def foo():
    return 42

task = asyncio.create_task(foo())
done, pending = await asyncio.wait({task})

if task in done:
    # Everything will work as expected now.

Passing coroutine objects to wait() directly is deprecated.

asyncio.as_completed(aws, *, loop=None, timeout=None)

Run awaitable objects in the aws set concurrently. Return an iterator of Future objects. Each Future object returned represents the earliest result from the set of the remaining awaitables.

全フューチャが終了する前にタイムアウトが発生した場合 asyncio.TimeoutError を送出します。

以下はプログラム例です:

for f in as_completed(aws):
    earliest_result = await f
    # ...

Scheduling From Other Threads

asyncio.run_coroutine_threadsafe(coro, loop)

Submit a coroutine to the given event loop. Thread-safe.

Return a concurrent.futures.Future to wait for the result from another OS thread.

This function is meant to be called from a different OS thread than the one where the event loop is running. Example:

# 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

If an exception is raised in the coroutine, the returned Future will be notified. It can also be used to cancel the task in the event loop:

try:
    result = future.result(timeout)
except asyncio.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-multithreading 節を参照してください。

Unlike other asyncio functions this functions requires the loop argument to be passed explicitly.

バージョン 3.5.1 で追加.

Introspection

asyncio.current_task(loop=None)

Return the currently running Task instance, or None if no task is running.

If loop is None get_running_loop() is used to get the current loop.

バージョン 3.7 で追加.

asyncio.all_tasks(loop=None)

Return a set of not yet finished Task objects run by the loop.

If loop is None, get_running_loop() is used for getting current loop.

バージョン 3.7 で追加.

Task Object

class asyncio.Task(coro, *, loop=None)

A Future-like object that runs a Python coroutine. Not thread-safe.

Tasks are used to run coroutines in event loops. If a coroutine awaits on a Future, the Task suspends the execution of the coroutine and waits for the completion of the Future. When the Future is done, the execution of the wrapped coroutine resumes.

Event loops use cooperative scheduling: an event loop runs one Task at a time. While a Task awaits for the completion of a Future, the event loop runs other Tasks, callbacks, or performs IO operations.

Use the high-level asyncio.create_task() function to create Tasks, or the low-level loop.create_task() or ensure_future() functions. Manual instantiation of Tasks is discouraged.

To cancel a running Task use the cancel() method. Calling it will cause the Task to throw a CancelledError exception into the wrapped coroutine. If a coroutine is awaiting on a Future object during cancellation, the Future object will be cancelled.

cancelled() can be used to check if the Task was cancelled. The method returns True if the wrapped coroutine did not suppress the CancelledError exception and was actually cancelled.

asyncio.Task inherits from Future all of its APIs except Future.set_result() and Future.set_exception().

Tasks support the contextvars module. When a Task is created it copies the current context and later runs its coroutine in the copied context.

バージョン 3.7 で変更: Added support for the contextvars module.

cancel()

Request the Task to be cancelled.

This arranges for a CancelledError exception to be thrown into the wrapped coroutine on the next cycle of the event loop.

The coroutine then has a chance to clean up or even deny the request by suppressing the exception with a 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.

The following example illustrates how coroutines can intercept the cancellation request:

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()

Return True if the Task is cancelled.

The Task is cancelled when the cancellation was requested with cancel() and the wrapped coroutine propagated the CancelledError exception thrown into it.

done()

Return True if the Task is done.

A Task is done when the wrapped coroutine either returned a value, raised an exception, or the Task was cancelled.

result()

Return the result of the Task.

If the Task is done, the result of the wrapped coroutine is returned (or if the coroutine raised an exception, that exception is re-raised.)

If the Task has been cancelled, this method raises a CancelledError exception.

If the Task's result isn't yet available, this method raises a InvalidStateError exception.

exception()

Return the exception of the Task.

If the wrapped coroutine raised an exception that exception is returned. If the wrapped coroutine returned normally this method returns None.

If the Task has been cancelled, this method raises a CancelledError exception.

If the Task isn't done yet, this method raises an InvalidStateError exception.

add_done_callback(callback, *, context=None)

Add a callback to be run when the Task is done.

This method should only be used in low-level callback-based code.

See the documentation of Future.add_done_callback() for more details.

remove_done_callback(callback)

Remove callback from the callbacks list.

This method should only be used in low-level callback-based code.

See the documentation of Future.remove_done_callback() for more details.

get_stack(*, limit=None)

Return the list of stack frames for this Task.

If the wrapped coroutine is not done, this returns the stack where it is suspended. If the coroutine has completed successfully or was cancelled, this returns an empty list. If the coroutine was terminated by an exception, this returns the list of traceback frames.

フレームは常に古いものから新しい物へ並んでいます。

Only one stack frame is returned for a suspended coroutine.

The optional limit argument sets the maximum number of frames to return; by default all available frames are returned. The ordering of the returned list differs depending on whether a stack or a traceback is returned: the newest frames of a stack are returned, but the oldest frames of a traceback are returned. (This matches the behavior of the traceback module.)

print_stack(*, limit=None, file=None)

Print the stack or traceback for this Task.

This produces output similar to that of the traceback module for the frames retrieved by get_stack().

The limit argument is passed to get_stack() directly.

The file argument is an I/O stream to which the output is written; by default output is written to sys.stderr.

classmethod all_tasks(loop=None)

イベントループ loop のすべてのタスクの集合を返します。

By default all tasks for the current event loop are returned. If loop is None, the get_event_loop() function is used to get the current loop.

This method is deprecated and will be removed in Python 3.9. Use the asyncio.all_tasks() function instead.

classmethod current_task(loop=None)

Return the currently running task or None.

If loop is None, the get_event_loop() function is used to get the current loop.

This method is deprecated and will be removed in Python 3.9. Use the asyncio.current_task() function instead.

Generator-based Coroutines

注釈

Support for generator-based coroutines is deprecated and is scheduled for removal in Python 3.10.

Generator-based coroutines predate async/await syntax. They are Python generators that use yield from expressions to await on Futures and other coroutines.

Generator-based coroutines should be decorated with @asyncio.coroutine, although this is not enforced.

@asyncio.coroutine

Decorator to mark generator-based coroutines.

This decorator enables legacy generator-based coroutines to be compatible with async/await code:

@asyncio.coroutine
def old_style_coroutine():
    yield from asyncio.sleep(1)

async def main():
    await old_style_coroutine()

This decorator is deprecated and is scheduled for removal in Python 3.10.

This decorator should not be used for async def coroutines.

asyncio.iscoroutine(obj)

obj が コルーチンオブジェクト であれば True を返します。

This method is different from inspect.iscoroutine() because it returns True for generator-based coroutines.

asyncio.iscoroutinefunction(func)

Return True if func is a coroutine function.

This method is different from inspect.iscoroutinefunction() because it returns True for generator-based coroutine functions decorated with @coroutine.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


Streams

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

Streams

Streams are high-level async/await-ready primitives to work with network connections. Streams allow sending and receiving data without using callbacks or low-level protocols and transports.

Here is an example of a TCP echo client written using asyncio streams:

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())

    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!'))

See also the Examples section below.

Stream Functions

The following top-level asyncio functions can be used to create and work with streams:

coroutine asyncio.open_connection(host=None, port=None, *, loop=None, limit=None, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None)

Establish a network connection and return a pair of (reader, writer) objects.

The returned reader and writer objects are instances of StreamReader and StreamWriter classes.

The loop argument is optional and can always be determined automatically when this function is awaited from a coroutine.

limit determines the buffer size limit used by the returned StreamReader instance. By default the limit is set to 64 KiB.

The rest of the arguments are passed directly to loop.create_connection().

バージョン 3.7 で追加: The ssl_handshake_timeout parameter.

coroutine asyncio.start_server(client_connected_cb, host=None, port=None, *, loop=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, start_serving=True)

Start a socket server.

The client_connected_cb callback is called whenever a new client connection is established. It receives a (reader, writer) pair as two arguments, instances of the StreamReader and StreamWriter classes.

client_connected_cb can be a plain callable or a coroutine function; if it is a coroutine function, it will be automatically scheduled as a Task.

The loop argument is optional and can always be determined automatically when this method is awaited from a coroutine.

limit determines the buffer size limit used by the returned StreamReader instance. By default the limit is set to 64 KiB.

The rest of the arguments are passed directly to loop.create_server().

バージョン 3.7 で追加: The ssl_handshake_timeout and start_serving parameters.

Unix Sockets

coroutine asyncio.open_unix_connection(path=None, *, loop=None, limit=None, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)

Establish a Unix socket connection and return a pair of (reader, writer).

Similar to open_connection() but operates on Unix sockets.

See also the documentation of loop.create_unix_connection().

利用可能な環境: Unix。

バージョン 3.7 で追加: The ssl_handshake_timeout parameter.

バージョン 3.7 で変更: The path parameter can now be a path-like object

coroutine asyncio.start_unix_server(client_connected_cb, path=None, *, loop=None, limit=None, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)

Start a Unix socket server.

Similar to start_server() but works with Unix sockets.

See also the documentation of loop.create_unix_server().

利用可能な環境: Unix。

バージョン 3.7 で追加: The ssl_handshake_timeout and start_serving parameters.

バージョン 3.7 で変更: The path parameter can now be a path-like object.

StreamReader

class asyncio.StreamReader

Represents a reader object that provides APIs to read data from the IO stream.

It is not recommended to instantiate StreamReader objects directly; use open_connection() and start_server() instead.

coroutine read(n=-1)

n バイト読み込みます。n が指定されないか -1 が指定されていた場合 EOF になるまで読み込み、全データを返します。

If EOF was received and the internal buffer is empty, return an empty bytes object.

coroutine readline()

1 行読み込みます。 "行" とは、\n で終了するバイト列のシーケンスです。

If EOF is received and \n was not found, the method returns partially read data.

If EOF is received and the internal buffer is empty, return an empty bytes object.

coroutine readexactly(n)

Read exactly n bytes.

Raise an IncompleteReadError if EOF is reached before n can be read. Use the IncompleteReadError.partial attribute to get the partially read data.

coroutine readuntil(separator=b'\n')

Read data from the stream until separator is found.

成功時には、データと区切り文字は内部バッファから削除されます (消費されます)。返されるデータの最後には区切り文字が含まれます。

If the amount of data read exceeds the configured stream limit, a LimitOverrunError exception is raised, and the data is left in the internal buffer and can be read again.

If EOF is reached before the complete separator is found, an IncompleteReadError exception is raised, and the internal buffer is reset. The IncompleteReadError.partial attribute may contain a portion of the separator.

バージョン 3.5.2 で追加.

at_eof()

バッファーが空で feed_eof() が呼ばれていた場合 True を返します。

StreamWriter

class asyncio.StreamWriter

Represents a writer object that provides APIs to write data to the IO stream.

It is not recommended to instantiate StreamWriter objects directly; use open_connection() and start_server() instead.

can_write_eof()

Return True if the underlying transport supports the write_eof() method, False otherwise.

write_eof()

Close the write end of the stream after the buffered write data is flushed.

transport

Return the underlying asyncio transport.

get_extra_info(name, default=None)

Access optional transport information; see BaseTransport.get_extra_info() for details.

write(data)

Write data to the stream.

This method is not subject to flow control. Calls to write() should be followed by drain().

writelines(data)

Write a list (or any iterable) of bytes to the stream.

This method is not subject to flow control. Calls to writelines() should be followed by drain().

coroutine drain()

Wait until it is appropriate to resume writing to the stream. Example:

writer.write(data)
await writer.drain()

This is a flow control method that interacts with the underlying IO write buffer. When the size of the buffer reaches the high watermark, drain() blocks until the size of the buffer is drained down to the low watermark and writing can be resumed. When there is nothing to wait for, the drain() returns immediately.

close()

Close the stream.

is_closing()

Return True if the stream is closed or in the process of being closed.

バージョン 3.7 で追加.

coroutine wait_closed()

Wait until the stream is closed.

Should be called after close() to wait until the underlying connection is closed.

バージョン 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())

    data = await reader.read(100)
    print(f'Received: {data.decode()!r}')

    print('Close the connection')
    writer.close()

asyncio.run(tcp_echo_client('Hello World!'))

参考

The TCP echo client protocol example uses the low-level loop.create_connection() method.

ストリームを使った 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()

async def main():
    server = await asyncio.start_server(
        handle_echo, '127.0.0.1', 8888)

    addr = server.sockets[0].getsockname()
    print(f'Serving on {addr}')

    async with server:
        await server.serve_forever()

asyncio.run(main())

参考

The TCP echo server protocol example uses the loop.create_server() method.

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()

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()

    # Close the second socket
    wsock.close()

asyncio.run(wait_for_data())

参考

The register an open socket to wait for data using a protocol example uses a low-level protocol and the loop.create_connection() method.

The watch a file descriptor for read events example uses the low-level loop.add_reader() method to watch a file descriptor.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


Synchronization Primitives

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

Synchronization Primitives

asyncio synchronization primitives are designed to be similar to those of the threading module with two important caveats:

  • asyncio primitives are not thread-safe, therefore they should not be used for OS thread synchronization (use threading for that);
  • methods of these synchronization primitives do not accept the timeout argument; use the asyncio.wait_for() function to perform operations with timeouts.

asyncio has the following basic sychronization primitives:

  • Lock
  • Event
  • Condition
  • Semaphore
  • BoundedSemaphore

Lock

class asyncio.Lock(*, loop=None)

Implements a mutex lock for asyncio tasks. Not thread-safe.

An asyncio lock can be used to guarantee exclusive access to a shared resource.

The preferred way to use a Lock is an async with statement:

lock = asyncio.Lock()

# ... later
async with lock:
    # access shared state

which is equivalent to:

lock = asyncio.Lock()

# ... later
await lock.acquire()
try:
    # access shared state
finally:
    lock.release()
coroutine acquire()

Acquire the lock.

This method waits until the lock is unlocked, sets it to locked and returns True.

release()

Release the lock.

When the lock is locked, reset it to unlocked and return.

If the lock is unlocked, a RuntimeError is raised.

locked()

Return True if the lock is locked.

Event

class asyncio.Event(*, loop=None)

An event object. Not thread-safe.

An asyncio event can be used to notify multiple asyncio tasks that some event has happened.

An Event object manages an internal flag that can be set to true with the set() method and reset to false with the clear() method. The wait() method blocks until the flag is set to true. The flag is set to false initially.

以下はプログラム例です:

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()

Wait until the event is set.

If the event is set, return True immediately. Otherwise block until another task calls set().

set()

Set the event.

All tasks waiting for event to be set will be immediately awakened.

clear()

Clear (unset) the event.

Tasks awaiting on wait() will now block until the set() method is called again.

is_set()

Return True if the event is set.

Condition

class asyncio.Condition(lock=None, *, loop=None)

A Condition object. Not thread-safe.

An asyncio condition primitive can be used by a task to wait for some event to happen and then get exclusive access to a shared resource.

In essence, a Condition object combines the functionality of an Event and a Lock. It is possible to have multiple Condition objects share one Lock, which allows coordinating exclusive access to a shared resource between different tasks interested in particular states of that shared resource.

The optional lock argument must be a Lock object or None. In the latter case a new Lock object is created automatically.

The preferred way to use a Condition is an async with statement:

cond = asyncio.Condition()

# ... later
async with cond:
    await cond.wait()

which is equivalent to:

cond = asyncio.Condition()

# ... later
await lock.acquire()
try:
    await cond.wait()
finally:
    lock.release()
coroutine acquire()

下層でのロックを獲得します。

This method waits until the underlying lock is unlocked, sets it to locked and returns 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.

The lock must be acquired before this method is called and released shortly after. If called with an unlocked lock a RuntimeError error is raised.

locked()

下層のロックを獲得していれば True を返します。

notify_all()

Wake up all tasks waiting on this condition.

This method acts like notify(), but wakes up all waiting tasks.

The lock must be acquired before this method is called and released shortly after. If called with an unlocked lock a RuntimeError error is raised.

release()

下層のロックを解除します。

アンロック状態のロックに対して呼び出された場合、RuntimeError が送出されます。

coroutine wait()

通知を受けるまで待機します。

If the calling task has not acquired the lock when this method is called, a RuntimeError is raised.

This method releases the underlying lock, and then blocks until it is awakened by a notify() or notify_all() call. Once awakened, the Condition re-acquires its lock and this method returns True.

coroutine wait_for(predicate)

Wait until a predicate becomes true.

The predicate must be a callable which result will be interpreted as a boolean value. The final value is the return value.

Semaphore

class asyncio.Semaphore(value=1, *, loop=None)

A Semaphore object. Not thread-safe.

A semaphore manages an internal counter which is decremented by each acquire() call and incremented by each release() call. The counter can never go below zero; when acquire() finds that it is zero, it blocks, waiting until some task calls release().

The optional value argument gives the initial value for the internal counter (1 by default). If the given value is less than 0 a ValueError is raised.

The preferred way to use a Semaphore is an async with statement:

sem = asyncio.Semaphore(10)

# ... later
async with sem:
    # work with shared resource

which is equivalent to:

sem = asyncio.Semaphore(10)

# ... later
await sem.acquire()
try:
    # work with shared resource
finally:
    sem.release()
coroutine acquire()

セマフォを獲得します。

If the internal counter is greater than zero, decrement it by one and return True immediately. If it is zero, wait until a release() is called and return True.

locked()

セマフォを直ちに獲得できない場合 True を返します。

release()

Release a semaphore, incrementing the internal counter by one. Can wake up a task waiting to acquire the semaphore.

Unlike BoundedSemaphore, Semaphore allows making more release() calls than acquire() calls.

BoundedSemaphore

class asyncio.BoundedSemaphore(value=1, *, loop=None)

A bounded semaphore object. Not thread-safe.

Bounded Semaphore is a version of Semaphore that raises a ValueError in release() if it increases the internal counter above the initial value.

バージョン 3.7 で非推奨: Acquiring a lock using await lock or yield from lock and/or with statement (with await lock, with (yield from lock)) is deprecated. Use async with lock instead.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


Subprocesses

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

Subprocesses

This section describes high-level async/await asyncio APIs to create and manage subprocesses.

Here's an example of how asyncio can run a shell command and obtain its result:

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'))

will print:

['ls /zzz' exited with 1]
[stderr]
ls: /zzz: No such file or directory

Because all asyncio subprocess functions are asynchronous and asyncio provides many tools to work with such functions, it is easy to execute and monitor multiple subprocesses in parallel. It is indeed trivial to modify the above example to run several commands simultaneously:

async def main():
    await asyncio.gather(
        run('ls /zzz'),
        run('sleep 1; echo "hello"'))

asyncio.run(main())

See also the Examples subsection.

Creating Subprocesses

coroutine asyncio.create_subprocess_exec(*args, stdin=None, stdout=None, stderr=None, loop=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 のインスタンスを返します。

See the documentation of loop.subprocess_exec() for other parameters.

coroutine asyncio.create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, **kwds)

Run the cmd shell command.

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 のインスタンスを返します。

See the documentation of loop.subprocess_shell() for other parameters.

重要

It is the application's responsibility to ensure that all whitespace and special characters are quoted appropriately to avoid shell injection vulnerabilities. The shlex.quote() function can be used to properly escape whitespace and special shell characters in strings that are going to be used to construct shell commands.

注釈

The default asyncio event loop implementation on Windows does not support subprocesses. Subprocesses are available for Windows if a ProactorEventLoop is used. See Subprocess Support on Windows for details.

参考

asyncio also has the following low-level APIs to work with subprocesses: loop.subprocess_exec(), loop.subprocess_shell(), loop.connect_read_pipe(), loop.connect_write_pipe(), as well as the Subprocess Transports and Subprocess Protocols.

定数

asyncio.subprocess.PIPE

Can be passed to the stdin, stdout or stderr parameters.

If PIPE is passed to stdin argument, the Process.stdin attribute will point to a StreamWriter instance.

If PIPE is passed to stdout or stderr arguments, the Process.stdout and Process.stderr attributes will point to StreamReader instances.

asyncio.subprocess.STDOUT

Special value that can be used as the stderr argument and indicates that standard error should be redirected into standard output.

asyncio.subprocess.DEVNULL

Special value that can be used as the stdin, stdout or stderr argument to process creation functions. It indicates that the special file os.devnull will be used for the corresponding subprocess stream.

Interacting with Subprocesses

Both create_subprocess_exec() and create_subprocess_shell() functions return instances of the Process class. Process is a high-level wrapper that allows communicating with subprocesses and watching for their completion.

class asyncio.subprocess.Process

An object that wraps OS processes created by the create_subprocess_exec() and create_subprocess_shell() functions.

This class is designed to have a similar API to the subprocess.Popen class, but there are some notable differences:

  • unlike Popen, Process instances do not have an equivalent to the poll() method;
  • the communicate() and
wait() methods don't have a
timeout parameter: use the wait_for() function;
  • the Process.wait() method
is asynchronous, whereas subprocess.Popen.wait() method
is implemented as a blocking busy loop;
  • the universal_newlines parameter is not supported.

このクラスは スレッド安全ではありません。

See also the Subprocess and Threads section.

coroutine wait()

Wait for the child process to terminate.

Set and return the returncode attribute.

注釈

This method can deadlock when using stdout=PIPE or stderr=PIPE and the child process generates so much output that it blocks waiting for the OS pipe buffer to accept more data. Use the communicate() method when using pipes to avoid this condition.

coroutine communicate(input=None)

Interact with process:

  1. send data to stdin (if input is not None);
  2. read data from stdout and stderr, until EOF is reached;
  3. wait for process to terminate.

The optional input argument is the data (bytes object) that will be sent to the child process.

Return a tuple (stdout_data, stderr_data).

If either BrokenPipeError or ConnectionResetError exception is raised when writing input into stdin, the exception is ignored. This condition occurs when the process exits before all data are written into stdin.

If it is desired to send data to the process' stdin, the process needs to be created with stdin=PIPE. Similarly, to get anything other than None in the result tuple, the process has to be created with stdout=PIPE and/or stderr=PIPE arguments.

Note, that the data read is buffered in memory, so do not use this method if the data size is large or unlimited.

send_signal(signal)

子プロセスにシグナル signal を送信します。

注釈

Windows では、SIGTERM は terminate() の別名になります。CTRL_C_EVENT および CTRL_BREAK_EVENT で、creationflags で始まり、CREATE_NEW_PROCESS_GROUP を含むパラメータをプロセスに送信することができます。

terminate()

Stop the child process.

On POSIX systems this method sends signal.SIGTERM to the child process.

On Windows the Win32 API function TerminateProcess() is called to stop the child process.

kill()

Kill the child.

On POSIX systems this method sends SIGKILL to the child process.

On Windows this method is an alias for terminate().

stdin

Standard input stream (StreamWriter) or None if the process was created with stdin=None.

stdout

Standard output stream (StreamReader) or None if the process was created with stdout=None.

stderr

Standard error stream (StreamReader) or None if the process was created with stderr=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

Process identification number (PID).

Note that for processes created by the create_subprocess_shell() function, this attribute is the PID of the spawned shell.

returncode

Return code of the process when it exits.

A None value indicates that the process has not terminated yet.

負の値 -N は子プロセスがシグナル N により中止させられたことを示します (POSIX のみ)。

Subprocess and Threads

Standard asyncio event loop supports running subprocesses from different threads, but there are limitations:

  • An event loop must run in the main thread.
  • The child watcher must be instantiated in the main thread before executing subprocesses from other threads. Call the get_child_watcher() function in the main thread to instantiate the child watcher.

Note that alternative event loop implementations might not share the above limitations; please refer to their documentation.

参考

asyncio-multithreading

使用例

An example using the Process class to control a subprocess and the StreamReader class to read from its standard output.

The subprocess is created by the create_subprocess_exec() function:

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

if sys.platform == "win32":
    asyncio.set_event_loop_policy(
        asyncio.WindowsProactorEventLoopPolicy())

date = asyncio.run(get_date())
print(f"Current date: {date}")

See also the same example written using low-level APIs.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


キュー

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

キュー

asyncio queues are designed to be similar to classes of the queue module. Although asyncio queues are not thread-safe, they are designed to be used specifically in async/await code.

Note that methods of asyncio queues don't have a timeout parameter; use asyncio.wait_for() function to do queue operations with a timeout.

See also the Examples section below.

Queue

class asyncio.Queue(maxsize=0, *, loop=None)

A first in, first out (FIFO) queue.

If maxsize is less than or equal to zero, the queue size is infinite. If it is an integer greater than 0, then await put() blocks when the queue reaches maxsize until an item is removed by get().

Unlike the standard library threading queue, the size of the queue is always known and can be returned by calling the qsize() method.

このクラスは スレッド安全ではありません。

maxsize

キューに追加できるアイテム数です。

empty()

キューが空ならば True を、そうでなければ False を返します。

full()

キューに要素が maxsize 個あれば True を返します。

If the queue was initialized with maxsize=0 (the default), then full() never returns True.

coroutine get()

キューから要素を削除して返します。キューが空の場合項目が利用可能になるまで待機します。

get_nowait()

直ちに利用できるアイテムがあるときはそれを、そうでなければ QueueEmpty を返します。

coroutine join()

Block until all items in the queue have been received and processed.

The count of unfinished tasks goes up whenever an item is added to the queue. The count goes down whenever a consumer thread calls task_done() to indicate that the item was retrieved and all work on it is complete. When the count of unfinished tasks drops to zero, join() unblocks.

coroutine put(item)

Put an item into the queue. If the queue is full, wait until a free slot is available before adding the item.

put_nowait(item)

ブロックせずにアイテムをキューに追加します。

直ちに利用できるスロットがない場合、QueueFull を送出します。

qsize()

Return the number of items in the queue.

task_done()

キューに入っていたタスクが完了したことを示します。

キューコンシューマーによって使用されます。タスクの取得に get() を使用し、その後の task_done() の呼び出しでタスクの処理が完了したことをキューに通知します。

join() が現在ブロック中だった場合、全アイテムが処理されたとき (put() でキューに追加された全アイテムの task_done() の呼び出しを受信したとき) に再開します。

キューに追加されているアイテム数以上の呼び出しが行われたときに ValueError を送出します。

Priority Queue

class asyncio.PriorityQueue

A variant of Queue; retrieves entries in priority order (lowest first).

Entries are typically tuples of the form (priority_number, data).

LIFO Queue

class asyncio.LifoQueue

A variant of Queue that retrieves most recently added entries first (last in, first out).

例外

exception asyncio.QueueEmpty

This exception is raised when the get_nowait() method is called on an empty queue.

exception asyncio.QueueFull

Exception raised when the put_nowait() method is called on a queue that has reached its maxsize.

使用例

Queues can be used to distribute workload between several concurrent tasks:

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())

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


例外

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

例外

exception asyncio.TimeoutError

The operation has exceeded the given deadline.

重要

This exception is different from the builtin TimeoutError exception.

exception asyncio.CancelledError

The operation has been cancelled.

This exception can be caught to perform custom operations when asyncio Tasks are cancelled. In almost all situations the exception must be re-raised.

重要

This exception is a subclass of Exception, so it can be accidentally suppressed by an overly broad try..except block:

try:
    await operation
except Exception:
    # The cancellation is broken because the *except* block
    # suppresses the CancelledError exception.
    log.log('an error has occurred')

Instead, the following pattern should be used:

try:
    await operation
except asyncio.CancelledError:
    raise
except Exception:
    log.log('an error has occurred')
exception asyncio.InvalidStateError

Invalid internal state of Task or Future.

Can be raised in situations like setting a result value for a Future object that already has a result value set.

exception asyncio.SendfileNotAvailableError

The "sendfile" syscall is not available for the given socket or file type.

A subclass of RuntimeError.

exception asyncio.IncompleteReadError

The requested read operation did not complete fully.

Raised by the asyncio stream APIs.

This exception is a subclass of EOFError.

expected

The total number (int) of expected bytes.

partial

A string of bytes read before the end of stream was reached.

exception asyncio.LimitOverrunError

Reached the buffer size limit while looking for a separator.

Raised by the asyncio stream APIs.

consumed

The total number of to be consumed bytes.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


Event Loop

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

Event Loop

Preface

The event loop is the core of every asyncio application. Event loops run asynchronous tasks and callbacks, perform network IO operations, and run subprocesses.

Application developers should typically use the high-level asyncio functions, such as asyncio.run(), and should rarely need to reference the loop object or call its methods. This section is intended mostly for authors of lower-level code, libraries, and frameworks, who need finer control over the event loop behavior.

Obtaining the Event Loop

The following low-level functions can be used to get, set, or create an event loop:

asyncio.get_running_loop()

Return the running event loop in the current OS thread.

If there is no running event loop a RuntimeError is raised. This function can only be called from a coroutine or a callback.

バージョン 3.7 で追加.

asyncio.get_event_loop()

Get the current event loop. If there is no current event loop set in the current OS thread and set_event_loop() has not yet been called, asyncio will create a new event loop and set it as the current one.

Because this function has rather complex behavior (especially when custom event loop policies are in use), using the get_running_loop() function is preferred to get_event_loop() in coroutines and callbacks.

Consider also using the asyncio.run() function instead of using lower level functions to manually create and close an event loop.

asyncio.set_event_loop(loop)

Set loop as a current event loop for the current OS thread.

asyncio.new_event_loop()

Create a new event loop object.

Note that the behaviour of get_event_loop(), set_event_loop(), and new_event_loop() functions can be altered by setting a custom event loop policy.

内容

This documentation page contains the following sections:

  • The Event Loop Methods section is the reference documentation of the event loop APIs;
  • The Callback Handles section documents the Handle and TimerHandle instances which are returned from scheduling methods such as loop.call_soon() and loop.call_later();
  • The Server Objects section documents types returned from event loop methods like loop.create_server();
  • The Event Loop Implementations section documents the SelectorEventLoop and ProactorEventLoop classes;
  • The Examples section showcases how to work with some event loop APIs.

Event Loop Methods

Event loops have low-level APIs for the following:

  • Running and stopping the loop
  • Scheduling callbacks
  • Scheduling delayed callbacks
  • Creating Futures and Tasks
  • Opening network connections
  • Creating network servers
  • Transferring files
  • TLS Upgrade
  • Watching file descriptors
  • Working with socket objects directly
  • DNS
  • Working with pipes
  • Unix signals
  • Executing code in thread or process pools
  • エラーハンドリング API
  • Enabling debug mode
  • Running Subprocesses

Running and stopping the loop

loop.run_until_complete(future)

Run until the future (an instance of Future) has completed.

If the argument is a coroutine object it is implicitly scheduled to run as a asyncio.Task.

Return the Future's result or raise its exception.

loop.run_forever()

Run the event loop until stop() is called.

If stop() is called before run_forever() is called, the loop will poll the I/O selector once with a timeout of zero, run all callbacks scheduled in response to I/O events (and those that were already scheduled), and then exit.

If stop() is called while run_forever() is running, the loop will run the current batch of callbacks and then exit. Note that new callbacks scheduled by callbacks will not run in this case; instead, they will run the next time run_forever() or run_until_complete() is called.

loop.stop()

Stop the event loop.

loop.is_running()

Return True if the event loop is currently running.

loop.is_closed()

Return True if the event loop was closed.

loop.close()

Close the event loop.

The loop must not be running when this function is called. Any pending callbacks will be discarded.

This method clears all queues and shuts down the executor, but does not wait for the executor to finish.

This method is idempotent and irreversible. No other methods should be called after the event loop is closed.

coroutine loop.shutdown_asyncgens()

Schedule all currently open asynchronous generator objects to close with an aclose() call. After calling this method, the event loop will issue a warning if a new asynchronous generator is iterated. This should be used to reliably finalize all scheduled asynchronous generators.

Note that there is no need to call this function when asyncio.run() is used.

以下はプログラム例です:

try:
    loop.run_forever()
finally:
    loop.run_until_complete(loop.shutdown_asyncgens())
    loop.close()

バージョン 3.6 で追加.

Scheduling callbacks

loop.call_soon(callback, *args, context=None)

Schedule a callback to be called with args arguments at the next iteration of the event loop.

Callbacks are called in the order in which they are registered. Each callback will be called exactly once.

An optional keyword-only context argument allows specifying a custom contextvars.Context for the callback to run in. The current context is used when no context is provided.

An instance of asyncio.Handle is returned, which can be used later to cancel the callback.

This method is not thread-safe.

loop.call_soon_threadsafe(callback, *args, context=None)

A thread-safe variant of call_soon(). Must be used to schedule callbacks from another thread.

このドキュメントの asyncio-multithreading 節を参照してください。

バージョン 3.7 で変更: The context keyword-only parameter was added. See PEP 567 for more details.

注釈

Most asyncio scheduling functions don't allow passing keyword arguments. To do that, use functools.partial():

# will schedule "print("Hello", flush=True)"
loop.call_soon(
    functools.partial(print, "Hello", flush=True))

Using partial objects is usually more convenient than using lambdas, as asyncio can render partial objects better in debug and error messages.

Scheduling delayed callbacks

Event loop provides mechanisms to schedule callback functions to be called at some point in the future. Event loop uses monotonic clocks to track time.

loop.call_later(delay, callback, *args, context=None)

Schedule callback to be called after the given delay number of seconds (can be either an int or a float).

An instance of asyncio.TimerHandle is returned which can be used to cancel the callback.

callback will be called exactly once. If two callbacks are scheduled for exactly the same time, the order in which they are called is undefined.

The optional positional args will be passed to the callback when it is called. If you want the callback to be called with keyword arguments use functools.partial().

An optional keyword-only context argument allows specifying a custom contextvars.Context for the callback to run in. The current context is used when no context is provided.

バージョン 3.7 で変更: The context keyword-only parameter was added. See PEP 567 for more details.

バージョン 3.7.1 で変更: In Python 3.7.0 and earlier with the default event loop implementation, the delay could not exceed one day. This has been fixed in Python 3.7.1.

loop.call_at(when, callback, *args, context=None)

Schedule callback to be called at the given absolute timestamp when (an int or a float), using the same time reference as loop.time().

このメソッドの振る舞いは call_later() と同じです。

An instance of asyncio.TimerHandle is returned which can be used to cancel the callback.

バージョン 3.7 で変更: The context keyword-only parameter was added. See PEP 567 for more details.

バージョン 3.7.1 で変更: In Python 3.7.0 and earlier with the default event loop implementation, the difference between when and the current time could not exceed one day. This has been fixed in Python 3.7.1.

loop.time()

Return the current time, as a float value, according to the event loop's internal monotonic clock.

注釈

タイムアウト (相対値 delay または絶対値 when) は 1 日を超えてはいけません。

参考

関数 asyncio.sleep()。

Creating Futures and Tasks

loop.create_future()

Create an asyncio.Future object attached to the event loop.

This is the preferred way to create Futures in asyncio. This lets third-party event loops provide alternative implementations of the Future object (with better performance or instrumentation).

バージョン 3.5.2 で追加.

loop.create_task(coro)

Schedule the execution of a コルーチン. Return a Task object.

サードパーティのイベントループは相互運用のための自身の Task のサブクラスを使用できます。この場合、結果は Task のサブクラスになります。

loop.set_task_factory(factory)

Set a task factory that will be used by 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), 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()

Return a task factory or None if the default one is in use.

Opening network connections

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)

Open a streaming transport connection to a given address specified by host and 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 must be a callable returning an asyncio protocol implementation.

This method will try to establish the connection in the background. When successful, it returns a (transport, protocol) pair.

時系列での下層処理の概要は以下のとおりです:

  1. The connection is established and a transport is created for it.
  2. protocol_factory is called without arguments and is expected to return a protocol instance.
  3. The protocol instance is coupled with the transport by calling its connection_made() method.
  4. A (transport, protocol) tuple is returned on success.

作成されたトランスポートは実装依存の双方向ストリームです。

Other arguments:

  • ssl: if given and not false, a SSL/TLS transport is created (by default a plain TCP transport is created). If ssl is a ssl.SSLContext object, this context is used to create the transport; if ssl is True, a default context returned from ssl.create_default_context() is used.

    参考

    SSL/TLS セキュリティについての考察

  • server_hostname sets or overrides the hostname that the target server's certificate will be matched against. Should only be passed if ssl is not None. By default the value of the host argument is used. If host is empty, there is no default and you must pass a value for server_hostname. If server_hostname is an empty string, hostname matching is disabled (which is a serious security risk, allowing for potential man-in-the-middle attacks).

  • family, proto, flags は任意のアドレスファミリであり、host 解決のための getaddrinfo() 経由で渡されるプロトコルおよびフラグになります。このオプションが与えられた場合、これらはすべて socket モジュール定数に従った整数でなければなりません。

  • sock を与える場合、トランスポートに使用される、既存の、すでに接続済の socket.socket オブジェクトを指定します。sock を指定する場合、host、port、family、proto、flags および local_addr を指定してはなりません。

  • local_addr, if given, is a (local_host, local_port) tuple used to bind the socket to locally. The local_host and local_port are looked up using getaddrinfo(), similarly to host and port.

  • ssl_handshake_timeout is (for a TLS connection) the time in seconds to wait for the TLS handshake to complete before aborting the connection. 60.0 seconds if None (default).

バージョン 3.7 で追加: The ssl_handshake_timeout parameter.

バージョン 3.6 で変更: The socket option TCP_NODELAY is set by default for all TCP connections.

バージョン 3.5 で変更: Added support for SSL/TLS in ProactorEventLoop.

参考

The open_connection() function is a high-level alternative API. It returns a pair of (StreamReader, StreamWriter) that can be used directly in async/await code.

coroutine loop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)

Create a datagram connection.

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 must be a callable returning a protocol implementation.

A tuple of (transport, protocol) is returned on success.

Other arguments:

  • 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_address tells the kernel to reuse a local socket in TIME_WAIT state, without waiting for its natural timeout to expire. If not specified will automatically be set to True on Unix.
  • 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 SO_REUSEPORT constant is not defined then this capability is unsupported.
  • allow_broadcast は、カーネルに、このエンドポイントがブロードキャストアドレスにメッセージを送信することを許可するように指示します。
  • オプションの sock を指定することで、既存の、すでに接続されている socket.socket をトランスポートで使用することができます。このオプションを使用する場合、local_addr と remote_addr は省略してください (None でなければなりません)。

On Windows, with ProactorEventLoop, this method is not supported.

UDP echo クライアントプロトコル および UDP echo サーバープロトコル の例を参照してください。

バージョン 3.4.4 で変更: family, proto, flags, reuse_address, reuse_port, *allow_broadcast, sock パラメータが追加されました。

coroutine loop.create_unix_connection(protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)

Create a Unix connection.

The socket family will be AF_UNIX; socket type will be SOCK_STREAM.

A tuple of (transport, protocol) is returned on success.

path is the name of a Unix domain socket and is required, unless a sock parameter is specified. Abstract Unix sockets, str, bytes, and Path paths are supported.

See the documentation of the loop.create_connection() method for information about arguments to this method.

利用可能な環境: Unix。

バージョン 3.7 で追加: The ssl_handshake_timeout parameter.

バージョン 3.7 で変更: The path parameter can now be a path-like object.

Creating network servers

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, start_serving=True)

Create a TCP server (socket type SOCK_STREAM) listening on port of the host address.

Returns a Server object.

Arguments:

  • protocol_factory must be a callable returning a protocol implementation.
  • The host parameter can be set to several types which determine where the server would be listening:
    • If host is a string, the TCP server is bound to a single network interface specified by host.
    • If host is a sequence of strings, the TCP server is bound to all network interfaces specified by the sequence.
    • host が空の文字列か None の場合、すべてのインターフェースが想定され、複合的なソケットのリスト (通常は一つが IPv4、もう一つが IPv6) が返されます。
  • 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 can optionally be specified in order to use a preexisting socket object. If specified, host and port must not be specified.
  • backlog は listen() に渡される、キューに入るコネクションの最大数になります (デフォルトは 100)。
  • ssl can be set to an SSLContext instance to enable TLS over the accepted connections.
  • reuse_address tells the kernel to reuse a local socket in TIME_WAIT state, without waiting for its natural timeout to expire. If not specified will automatically be set to True on Unix.
  • reuse_port は、同じポートにバインドされた既存の端点すべてがこのフラグを設定して生成されている場合に限り、この端点を既存の端点と同じポートにバインドすることを許可するよう、カーネルに指示します（訳註: ソケットのオプション SO_REUSEPORT を使用します）。このオプションは、Windows ではサポートされていません。
  • ssl_handshake_timeout is (for a TLS server) the time in seconds to wait for the TLS handshake to complete before aborting the connection. 60.0 seconds if None (default).
  • start_serving set to True (the default) causes the created server to start accepting connections immediately. When set to False, the user should await on Server.start_serving() or Server.serve_forever() to make the server to start accepting connections.

バージョン 3.7 で追加: Added ssl_handshake_timeout and start_serving parameters.

バージョン 3.6 で変更: The socket option TCP_NODELAY is set by default for all TCP connections.

バージョン 3.5 で変更: Added support for SSL/TLS in ProactorEventLoop.

バージョン 3.5.1 で変更: The host parameter can be a sequence of strings.

参考

The start_server() function is a higher-level alternative API that returns a pair of StreamReader and StreamWriter that can be used in an async/await code.

coroutine loop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)

Similar to loop.create_server() but works with the AF_UNIX socket family.

path is the name of a Unix domain socket, and is required, unless a sock argument is provided. Abstract Unix sockets, str, bytes, and Path paths are supported.

See the documentation of the loop.create_server() method for information about arguments to this method.

利用可能な環境: Unix。

バージョン 3.7 で追加: The ssl_handshake_timeout and start_serving parameters.

バージョン 3.7 で変更: The path parameter can now be a Path object.

coroutine loop.connect_accepted_socket(protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None)

Wrap an already accepted connection into a transport/protocol pair.

This method can be used by servers that accept connections outside of asyncio but that use asyncio to handle them.

引数:

  • protocol_factory must be a callable returning a protocol implementation.
  • sock is a preexisting socket object returned from socket.accept.
  • ssl には SSLContext を指定できます。指定すると、受け付けたコネクション上での SSL を有効にします。
  • ssl_handshake_timeout is (for an SSL connection) the time in seconds to wait for the SSL handshake to complete before aborting the connection. 60.0 seconds if None (default).

Returns a (transport, protocol) pair.

バージョン 3.7 で追加: The ssl_handshake_timeout parameter.

バージョン 3.5.3 で追加.

Transferring files

coroutine loop.sendfile(transport, file, offset=0, count=None, *, fallback=True)

Send a file over a transport. Return the total number of bytes sent.

The method uses high-performance os.sendfile() if available.

file must be a regular file object opened in binary mode.

offset tells from where to start reading the file. If specified, count is the total number of bytes to transmit as opposed to sending the file until EOF is reached. File position is always updated, even when this method raises an error, and file.tell() can be used to obtain the actual number of bytes sent.

fallback set to True makes asyncio to manually read and send the file when the platform does not support the sendfile system call (e.g. Windows or SSL socket on Unix).

Raise SendfileNotAvailableError if the system does not support the sendfile syscall and fallback is False.

バージョン 3.7 で追加.

TLS Upgrade

coroutine loop.start_tls(transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None)

Upgrade an existing transport-based connection to TLS.

Return a new transport instance, that the protocol must start using immediately after the await. The transport instance passed to the start_tls method should never be used again.

引数:

  • transport and protocol instances that methods like create_server() and create_connection() return.
  • sslcontext: a configured instance of SSLContext.
  • server_side pass True when a server-side connection is being upgraded (like the one created by create_server()).
  • server_hostname: sets or overrides the host name that the target server's certificate will be matched against.
  • ssl_handshake_timeout is (for a TLS connection) the time in seconds to wait for the TLS handshake to complete before aborting the connection. 60.0 seconds if None (default).

バージョン 3.7 で追加.

Watching file descriptors

loop.add_reader(fd, callback, *args)

Start monitoring the fd file descriptor for read availability and invoke callback with the specified arguments once fd is available for reading.

loop.remove_reader(fd)

Stop monitoring the fd file descriptor for read availability.

loop.add_writer(fd, callback, *args)

Start monitoring the fd file descriptor for write availability and invoke callback with the specified arguments once fd is available for writing.

Use functools.partial() to pass keyword arguments to callback.

loop.remove_writer(fd)

Stop monitoring the fd file descriptor for write availability.

See also Platform Support section for some limitations of these methods.

Working with socket objects directly

In general, protocol implementations that use transport-based APIs such as loop.create_connection() and loop.create_server() are faster than implementations that work with sockets directly. However, there are some use cases when performance is not critical, and working with socket objects directly is more convenient.

coroutine loop.sock_recv(sock, nbytes)

Receive up to nbytes from sock. Asynchronous version of socket.recv().

Return the received data as a bytes object.

sock must be a non-blocking socket.

バージョン 3.7 で変更: Even though this method was always documented as a coroutine method, releases before Python 3.7 returned a Future. Since Python 3.7 this is an async def method.

coroutine loop.sock_recv_into(sock, buf)

Receive data from sock into the buf buffer. Modeled after the blocking socket.recv_into() method.

Return the number of bytes written to the buffer.

sock must be a non-blocking socket.

バージョン 3.7 で追加.

coroutine loop.sock_sendall(sock, data)

Send data to the sock socket. Asynchronous version of socket.sendall().

This method continues to send to the socket until either all data in data has been sent or an error occurs. None is returned on success. On error, an exception is raised. Additionally, there is no way to determine how much data, if any, was successfully processed by the receiving end of the connection.

sock must be a non-blocking socket.

バージョン 3.7 で変更: Even though the method was always documented as a coroutine method, before Python 3.7 it returned an Future. Since Python 3.7, this is an async def method.

coroutine loop.sock_connect(sock, address)

Connect sock to a remote socket at address.

Asynchronous version of socket.connect().

sock must be a non-blocking socket.

バージョン 3.5.2 で変更: address no longer needs to be resolved. sock_connect will try to check if the address is already resolved by calling socket.inet_pton(). If not, loop.getaddrinfo() will be used to resolve the address.

参考

loop.create_connection() and asyncio.open_connection().

coroutine loop.sock_accept(sock)

Accept a connection. Modeled after the blocking socket.accept() method.

ソケットはアドレスに束縛済みで、接続を listen 中である必要があります。戻り値は (conn, address) のペアで、conn は接続を通じてデータの送受信を行うための 新しい ソケットオブジェクト、address は接続先の端点でソケットに束縛されているアドレスを示します。

sock must be a non-blocking socket.

バージョン 3.7 で変更: Even though the method was always documented as a coroutine method, before Python 3.7 it returned a Future. Since Python 3.7, this is an async def method.

参考

loop.create_server() and start_server().

coroutine loop.sock_sendfile(sock, file, offset=0, count=None, *, fallback=True)

Send a file using high-performance os.sendfile if possible. Return the total number of bytes sent.

Asynchronous version of socket.sendfile().

sock must be a non-blocking socket.SOCK_STREAM socket.

file must be a regular file object open in binary mode.

offset tells from where to start reading the file. If specified, count is the total number of bytes to transmit as opposed to sending the file until EOF is reached. File position is always updated, even when this method raises an error, and file.tell() can be used to obtain the actual number of bytes sent.

fallback, when set to True, makes asyncio manually read and send the file when the platform does not support the sendfile syscall (e.g. Windows or SSL socket on Unix).

Raise SendfileNotAvailableError if the system does not support sendfile syscall and fallback is False.

sock must be a non-blocking socket.

バージョン 3.7 で追加.

DNS

coroutine loop.getaddrinfo(host, port, *, family=0, type=0, proto=0, flags=0)

Asynchronous version of socket.getaddrinfo().

coroutine loop.getnameinfo(sockaddr, flags=0)

Asynchronous version of socket.getnameinfo().

バージョン 3.7 で変更: Both getaddrinfo and getnameinfo methods were always documented to return a coroutine, but prior to Python 3.7 they were, in fact, returning asyncio.Future objects. Starting with Python 3.7 both methods are coroutines.

Working with pipes

coroutine loop.connect_read_pipe(protocol_factory, pipe)

Register the read end of pipe in the event loop.

protocol_factory must be a callable returning an asyncio protocol implementation.

pipe is a file-like object.

Return pair (transport, protocol), where transport supports the ReadTransport interface and protocol is an object instantiated by the protocol_factory.

SelectorEventLoop イベントループの場合、pipe は非ブロックモードに設定されていなければなりません。

coroutine loop.connect_write_pipe(protocol_factory, pipe)

Register the write end of pipe in the event loop.

protocol_factory must be a callable returning an asyncio protocol implementation.

pipe is file-like object.

Return pair (transport, protocol), where transport supports WriteTransport interface and protocol is an object instantiated by the protocol_factory.

SelectorEventLoop イベントループの場合、pipe は非ブロックモードに設定されていなければなりません。

注釈

SelectorEventLoop does not support the above methods on Windows. Use ProactorEventLoop instead for Windows.

参考

The loop.subprocess_exec() and loop.subprocess_shell() methods.

Unix signals

loop.add_signal_handler(signum, callback, *args)

Set callback as the handler for the signum signal.

シグナルナンバーが誤っているか捕捉不可能な場合 ValueError が送出されます。ハンドラーの設定に問題があった場合 RuntimeError が送出されます。

Use functools.partial() to pass keyword arguments to callback.

loop.remove_signal_handler(sig)

Remove the handler for the sig signal.

Return True if the signal handler was removed, or False if no handler was set for the given signal.

利用可能な環境: Unix。

参考

signal モジュール。

Executing code in thread or process pools

awaitable loop.run_in_executor(executor, func, *args)

Arrange for func to be called in the specified executor.

The executor argument should be an concurrent.futures.Executor instance. The default executor is used if executor is 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)

asyncio.run(main())

This method returns a asyncio.Future object.

Use functools.partial() to pass keyword arguments to func.

バージョン 3.5.3 で変更: loop.run_in_executor() no longer configures the max_workers of the thread pool executor it creates, instead leaving it up to the thread pool executor (ThreadPoolExecutor) to set the default.

loop.set_default_executor(executor)

Set executor as the default executor used by run_in_executor(). executor should be an instance of ThreadPoolExecutor.

バージョン 3.7 で非推奨: Using an executor that is not an instance of ThreadPoolExecutor is deprecated and will trigger an error in Python 3.9.

executor must be an instance of concurrent.futures.ThreadPoolExecutor.

エラーハンドリング API

イベントループ内での例外の扱い方をカスタマイズできます。

loop.set_exception_handler(handler)

handler を新しいイベントループ例外ハンドラーとして設定します。

If handler is None, the default exception handler will be set. Otherwise, handler must be a callable with the signature matching (loop, context), where loop is a reference to the active event loop, and context is a dict object containing the details of the exception (see call_exception_handler() documentation for details about context).

loop.get_exception_handler()

Return the current exception handler, or None if no custom exception handler was set.

バージョン 3.5.2 で追加.

loop.default_exception_handler(context)

デフォルトの例外ハンドラーです。

This is called when an exception occurs and no exception handler is set. This can be called by a custom exception handler that wants to defer to the default handler behavior.

引数 context の意味は call_exception_handler() と同じです。

loop.call_exception_handler(context)

現在のイベントループ例外ハンドラーを呼び出します。

context is a dict object containing the following keys (new keys may be introduced in future Python versions):

  • 'message': エラーメッセージ;
  • 'exception' (任意): 例外オブジェクト;
  • 'future' (任意): asyncio.Future インスタンス;
  • 'handle' (任意): asyncio.Handle インスタンス;
  • 'protocol' (任意): プロトコル インスタンス;
  • 'transport' (任意): トランスポート インスタンス;
  • 'socket' (任意): socket.socket インスタンス;

注釈

This method should not be overloaded in subclassed event loops. For custom exception handling, use the set_exception_handler() method.

Enabling debug mode

loop.get_debug()

イベントループのデバッグモード (bool) を取得します。

環境変数 PYTHONASYNCIODEBUG に空でない文字列が設定されている場合のデフォルト値は True、そうでない場合は False になります。

loop.set_debug(enabled: bool)

イベントループのデバッグモードを設定します。

バージョン 3.7 で変更: The new -X dev command line option can now also be used to enable the debug mode.

参考

asyncio のデバッグモード。

Running Subprocesses

Methods described in this subsections are low-level. In regular async/await code consider using the high-level asyncio.create_subprocess_shell() and asyncio.create_subprocess_exec() convenience functions instead.

注釈

The default asyncio event loop on Windows does not support subprocesses. See Subprocess Support on Windows for details.

coroutine loop.subprocess_exec(protocol_factory, *args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Create a subprocess from one or more string arguments specified by args.

args must be a list of strings represented by:

  • str;
  • or bytes, encoded to the filesystem encoding.

The first string specifies the program executable, and the remaining strings specify the arguments. Together, string arguments form the argv of the program.

This is similar to the standard library subprocess.Popen class called with shell=False and the list of strings passed as the first argument; however, where Popen takes a single argument which is list of strings, subprocess_exec takes multiple string arguments.

The protocol_factory must be a callable returning a subclass of the asyncio.SubprocessProtocol class.

その他の引数:

  • stdin: either a file-like object representing a pipe to be connected to the subprocess's standard input stream using connect_write_pipe(), or the subprocess.PIPE constant (default). By default a new pipe will be created and connected.

  • stdout: either a file-like object representing the pipe to be connected to the subprocess's standard output stream using connect_read_pipe(), or the subprocess.PIPE constant (default). By default a new pipe will be created and connected.

  • stderr: either a file-like object representing the pipe to be connected to the subprocess's standard error stream using connect_read_pipe(), or one of subprocess.PIPE (default) or subprocess.STDOUT constants.

    By default a new pipe will be created and connected. When subprocess.STDOUT is specified, the subprocess' standard error stream will be connected to the same pipe as the standard output stream.

  • その他のキーワード引数は、指定してはならない bufsize、universal_newlines および shell を除き、すべて解釈されずに subprocess.Popen に渡されます。

See the constructor of the subprocess.Popen class for documentation on other arguments.

Returns a pair of (transport, protocol), where transport conforms to the asyncio.SubprocessTransport base class and protocol is an object instantiated by the protocol_factory.

coroutine loop.subprocess_shell(protocol_factory, cmd, *, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Create a subprocess from cmd, which can be a str or a bytes string encoded to the filesystem encoding, using the platform's "shell" syntax.

This is similar to the standard library subprocess.Popen class called with shell=True.

The protocol_factory must be a callable returning a subclass of the SubprocessProtocol class.

See subprocess_exec() for more details about the remaining arguments.

Returns a pair of (transport, protocol), where transport conforms to the SubprocessTransport base class and protocol is an object instantiated by the protocol_factory.

注釈

It is the application's responsibility to ensure that all whitespace and special characters are quoted appropriately to avoid shell injection vulnerabilities. The shlex.quote() function can be used to properly escape whitespace and special characters in strings that are going to be used to construct shell commands.

Callback Handles

class asyncio.Handle

A callback wrapper object returned by loop.call_soon(), loop.call_soon_threadsafe().

cancel()

Cancel the callback. If the callback has already been canceled or executed, this method has no effect.

cancelled()

Return True if the callback was cancelled.

バージョン 3.7 で追加.

class asyncio.TimerHandle

A callback wrapper object returned by loop.call_later(), and loop.call_at().

This class is a subclass of Handle.

when()

Return a scheduled callback time as float seconds.

The time is an absolute timestamp, using the same time reference as loop.time().

バージョン 3.7 で追加.

Serverオブジェクト

Server objects are created by loop.create_server(),
loop.create_unix_server(), start_server(),
and start_unix_server() functions.

Do not instantiate the class directly.

class asyncio.Server

Server objects are asynchronous context managers. When used in an async with statement, it's guaranteed that the Server object is closed and not accepting new connections when the async with statement is completed:

srv = await loop.create_server(...)

async with srv:
    # some code

# At this point, srv is closed and no longer accepts new connections.

バージョン 3.7 で変更: Server object is an asynchronous context manager since Python 3.7.

close()

サーバーを停止します: 待機しているソケットをクローズし sockets 属性に None を設定します。

既存の受信中のクライアントとの接続を表すソケットはオープンのままです。

サーバーは非同期に停止されます。サーバーの停止を待ちたい場合は wait_closed() コルーチンを使用します。

get_loop()

Return the event loop associated with the server object.

バージョン 3.7 で追加.

coroutine start_serving()

Start accepting connections.

This method is idempotent, so it can be called when the server is already being serving.

The start_serving keyword-only parameter to loop.create_server() and asyncio.start_server() allows creating a Server object that is not accepting connections initially. In this case Server.start_serving(), or Server.serve_forever() can be used to make the Server start accepting connections.

バージョン 3.7 で追加.

coroutine serve_forever()

Start accepting connections until the coroutine is cancelled. Cancellation of serve_forever task causes the server to be closed.

This method can be called if the server is already accepting connections. Only one serve_forever task can exist per one Server object.

以下はプログラム例です:

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

バージョン 3.7 で追加.

is_serving()

Return True if the server is accepting new connections.

バージョン 3.7 で追加.

coroutine wait_closed()

close() メソッドが完了するまで待ちます。

sockets

List of socket.socket objects the server is listening on, or None if the server is closed.

バージョン 3.7 で変更: Prior to Python 3.7 Server.sockets used to return an internal list of server sockets directly. In 3.7 a copy of that list is returned.

Event Loop Implementations

asyncio ships with two different event loop implementations: SelectorEventLoop and ProactorEventLoop.

By default asyncio is configured to use SelectorEventLoop on all platforms.

class asyncio.SelectorEventLoop

An event loop based on the selectors module.

Uses the most efficient selector available for the given platform. It is also possible to manually configure the exact selector implementation to be used:

import asyncio
import selectors

selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)

Availability: Unix, Windows.

class asyncio.ProactorEventLoop

An event loop for Windows that uses "I/O Completion Ports" (IOCP).

利用可能な環境: Windows 。

An example how to use ProactorEventLoop on Windows:

import asyncio
import sys

if sys.platform == 'win32':
    loop = asyncio.ProactorEventLoop()
    asyncio.set_event_loop(loop)

参考

MSDN documentation on I/O Completion Ports.

class asyncio.AbstractEventLoop

Abstract base class for asyncio-compliant event loops.

The Event Loop Methods section lists all methods that an alternative implementation of AbstractEventLoop should have defined.

使用例

Note that all examples in this section purposefully show how to use the low-level event loop APIs, such as loop.run_forever() and loop.call_soon(). Modern asyncio applications rarely need to be written this way; consider using the high-level functions like asyncio.run().

call_soon() を使った Hello World

An example using the loop.call_soon() method to schedule a callback. The callback displays "Hello World" and then stops the event loop:

import asyncio

def hello_world(loop):
    """A callback to print 'Hello World' and stop the event loop"""
    print('Hello World')
    loop.stop()

loop = asyncio.get_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()

参考

A similar Hello World example created with a coroutine and the run() function.

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

An example of a callback displaying the current date every second. The callback uses the loop.call_later() method to reschedule itself after 5 seconds, and then stops the event loop:

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.get_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()

参考

A similar current date example created with a coroutine and the run() function.

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

Wait until a file descriptor received some data using the loop.add_reader() method and then close the event loop:

import asyncio
from socket import socketpair

# Create a pair of connected file descriptors
rsock, wsock = socketpair()

loop = asyncio.get_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()

参考

  • A similar example using transports, protocols, and the loop.create_connection() method.
  • Another similar example using the high-level asyncio.open_connection() function and streams.

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

(This signals example only works on 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):
    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))

    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())

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


Future

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

Future

Future objects are used to bridge low-level callback-based code with high-level async/await code.

Future Functions

asyncio.isfuture(obj)

Return True if obj is either of:

  • an instance of asyncio.Future,
  • an instance of asyncio.Task,
  • a Future-like object with a _asyncio_future_blocking attribute.

バージョン 3.5 で追加.

asyncio.ensure_future(obj, *, loop=None)

Return:

  • obj argument as is, if obj is a Future, a Task, or a Future-like object (isfuture() is used for the test.)
  • a Task object wrapping obj, if obj is a coroutine (iscoroutine() is used for the test.)
  • a Task object that would await on obj, if obj is an awaitable (inspect.isawaitable() is used for the test.)

If obj is neither of the above a TypeError is raised.

重要

See also the create_task() function which is the preferred way for creating new Tasks.

バージョン 3.5.1 で変更: The function accepts any awaitable object.

asyncio.wrap_future(future, *, loop=None)

Wrap a concurrent.futures.Future object in a asyncio.Future object.

Future Object

class asyncio.Future(*, loop=None)

A Future represents an eventual result of an asynchronous operation. Not thread-safe.

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.

Typically Futures are used to enable low-level callback-based code (e.g. in protocols implemented using asyncio transports) to interoperate with high-level async/await code.

The rule of thumb is to never expose Future objects in user-facing APIs, and the recommended way to create a Future object is to call loop.create_future(). This way alternative event loop implementations can inject their own optimized implementations of a Future object.

バージョン 3.7 で変更: Added support for the contextvars module.

result()

Return the result of the Future.

If the Future is done and has a result set by the set_result() method, the result value is returned.

If the Future is done and has an exception set by the set_exception() method, this method raises the exception.

If the Future has been cancelled, this method raises a CancelledError exception.

If the Future's result isn't yet available, this method raises a InvalidStateError exception.

set_result(result)

Mark the Future as done and set its result.

Raises a InvalidStateError error if the Future is already done.

set_exception(exception)

Mark the Future as done and set an exception.

Raises a InvalidStateError error if the Future is already done.

done()

Return True if the Future is done.

A Future is done if it was cancelled or if it has a result or an exception set with set_result() or set_exception() calls.

cancelled()

Return True if the Future was cancelled.

The method is usually used to check if a Future is not cancelled before setting a result or an exception for it:

if not fut.cancelled():
    fut.set_result(42)
add_done_callback(callback, *, context=None)

Add a callback to be run when the Future is done.

The callback is called with the Future object as its only argument.

If the Future is already done when this method is called, the callback is scheduled with loop.call_soon().

An optional keyword-only context argument allows specifying a custom contextvars.Context for the callback to run in. The current context is used when no context is provided.

functools.partial() can be used to pass parameters to the callback, e.g.:

# Call 'print("Future:", fut)' when "fut" is done.
fut.add_done_callback(
    functools.partial(print, "Future:"))

バージョン 3.7 で変更: The context keyword-only parameter was added. See PEP 567 for more details.

remove_done_callback(callback)

Remove callback from the callbacks list.

Returns the number of callbacks removed, which is typically 1, unless a callback was added more than once.

cancel()

Cancel the Future and schedule callbacks.

If the Future is already done or cancelled, return False. Otherwise, change the Future's state to cancelled, schedule the callbacks, and return True.

exception()

Return the exception that was set on this Future.

The exception (or None if no exception was set) is returned only if the Future is done.

If the Future has been cancelled, this method raises a CancelledError exception.

If the Future isn't done yet, this method raises an InvalidStateError exception.

get_loop()

Return the event loop the Future object is bound to.

バージョン 3.7 で追加.

This example creates a Future object, creates and schedules an asynchronous Task to set result for the Future, and waits until the Future has a result:

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())

重要

The Future object was designed to mimic concurrent.futures.Future. Key differences include:

  • unlike asyncio Futures, concurrent.futures.Future instances cannot be awaited.
  • asyncio.Future.result() and asyncio.Future.exception() do not accept the timeout argument.
  • asyncio.Future.result() and asyncio.Future.exception() raise an InvalidStateError exception when the Future is not done.
  • Callbacks registered with asyncio.Future.add_done_callback() are not called immediately. They are scheduled with loop.call_soon() instead.
  • asyncio Future is not compatible with the concurrent.futures.wait() and concurrent.futures.as_completed() functions.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


Transports and Protocols

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

Transports and Protocols

Preface

Transports and Protocols are used by the low-level event loop APIs such as loop.create_connection(). They use callback-based programming style and enable high-performance implementations of network or IPC protocols (e.g. HTTP).

Essentially, transports and protocols should only be used in libraries and frameworks and never in high-level asyncio applications.

This documentation page covers both Transports and Protocols.

はじめに

At the highest level, the transport is concerned with how bytes are transmitted, while the protocol determines which bytes to transmit (and to some extent when).

A different way of saying the same thing: a transport is an abstraction for a socket (or similar I/O endpoint) while a protocol is an abstraction for an application, from the transport's point of view.

Yet another view is the transport and protocol interfaces together define an abstract interface for using network I/O and interprocess I/O.

There is always a 1:1 relationship between transport and protocol objects: the protocol calls transport methods to send data, while the transport calls protocol methods to pass it data that has been received.

Most of connection oriented event loop methods (such as loop.create_connection()) usually accept a protocol_factory argument used to create a Protocol object for an accepted connection, represented by a Transport object. Such methods usually return a tuple of (transport, protocol).

内容

This documentation page contains the following sections:

  • The Transports section documents asyncio BaseTransport, ReadTransport, WriteTransport, Transport, DatagramTransport, and SubprocessTransport classes.
  • The Protocols section documents asyncio BaseProtocol, Protocol, BufferedProtocol, DatagramProtocol, and SubprocessProtocol classes.
  • The Examples section showcases how to work with transports, protocols, and low-level event loop APIs.

トランスポート

Transports are classes provided by asyncio in order to abstract various kinds of communication channels.

Transport objects are always instantiated by an ref:asyncio event loop <asyncio-event-loop>.

asyncio implements transports for TCP, UDP, SSL, and subprocess pipes. The methods available on a transport depend on the transport's kind.

トランスポートクラスは スレッド安全ではありません。

Transports Hierarchy

class asyncio.BaseTransport

Base class for all transports. Contains methods that all asyncio transports share.

class asyncio.WriteTransport(BaseTransport)

A base transport for write-only connections.

Instances of the WriteTransport class are returned from the loop.connect_write_pipe() event loop method and are also used by subprocess-related methods like loop.subprocess_exec().

class asyncio.ReadTransport(BaseTransport)

A base transport for read-only connections.

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)

Interface representing a bidirectional transport, such as a TCP connection.

The user does not instantiate a transport directly; they call a utility function, passing it a protocol factory and other information necessary to create the transport and protocol.

Instances of the Transport class are returned from or used by
event loop methods like loop.create_connection(),
loop.create_unix_connection(),
loop.create_server(), loop.sendfile(), etc.

class asyncio.DatagramTransport(BaseTransport)

A transport for datagram (UDP) connections.

Instances of the DatagramTransport class are returned from the loop.create_datagram_endpoint() event loop method.

class asyncio.SubprocessTransport(BaseTransport)

An abstraction to represent a connection between a parent and its child OS process.

Instances of the SubprocessTransport class are returned from event loop methods loop.subprocess_shell() and loop.subprocess_exec().

Base Transport

BaseTransport.close()

Close the transport.

If the transport has a buffer for outgoing data, buffered data will be flushed asynchronously. No more data will be received. After all buffered data is flushed, the protocol's protocol.connection_lost() method will be called with None as its argument.

BaseTransport.is_closing()

トランスポートを閉じている最中か閉じていた場合 True を返します。

BaseTransport.get_extra_info(name, default=None)

Return information about the transport or underlying resources it uses.

name is a string representing the piece of transport-specific information to get.

default is the value to return if the information is not available, or if the transport does not support querying it with the given third-party event loop implementation or on the current platform.

For example, the following code attempts to get the underlying socket object of the transport:

sock = transport.get_extra_info('socket')
if sock is not None:
    print(sock.getsockopt(...))

Categories of information that can be queried on some transports:

  • ソケット:
    • '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)

Set a new protocol.

Switching protocol should only be done when both protocols are documented to support the switch.

BaseTransport.get_protocol()

現在のプロトコルを返します。

Read-only Transports

ReadTransport.is_reading()

Return True if the transport is receiving new data.

バージョン 3.7 で追加.

ReadTransport.pause_reading()

Pause the receiving end of the transport. No data will be passed to the protocol's protocol.data_received() method until resume_reading() is called.

バージョン 3.7 で変更: The method is idempotent, i.e. it can be called when the transport is already paused or closed.

ReadTransport.resume_reading()

Resume the receiving end. The protocol's protocol.data_received() method will be called once again if some data is available for reading.

バージョン 3.7 で変更: The method is idempotent, i.e. it can be called when the transport is already reading.

Write-only Transports

WriteTransport.abort()

Close the transport immediately, without waiting for pending operations to complete. Buffered data will be lost. No more data will be received. The protocol's protocol.connection_lost() method will eventually be called with None as its argument.

WriteTransport.can_write_eof()

Return True if the transport supports write_eof(), False if not.

WriteTransport.get_write_buffer_size()

トランスポートで使用されている出力バッファーの現在のサイズを返します。

WriteTransport.get_write_buffer_limits()

Get the high and low watermarks for write flow control. Return a tuple (low, high) where low and high are positive number of bytes.

水位点の設定は set_write_buffer_limits() で行います。

バージョン 3.4.2 で追加.

WriteTransport.set_write_buffer_limits(high=None, low=None)

Set the high and low watermarks for write flow control.

These two values (measured in number of bytes) control when the protocol's protocol.pause_writing() and protocol.resume_writing() methods are called. If specified, the low watermark must be less than or equal to the high watermark. Neither high nor low can be negative.

pause_writing() is called when the buffer size becomes greater than or equal to the high value. If writing has been paused, resume_writing() is called when the buffer size becomes less than or equal to the low value.

The defaults are implementation-specific. If only the high watermark is given, the low watermark defaults to an implementation-specific value less than or equal to the high watermark. Setting high to zero forces low to zero as well, and causes pause_writing() to be called whenever the buffer becomes non-empty. Setting low to zero causes resume_writing() to be called only once the buffer is empty. Use of zero for either limit is generally sub-optimal as it reduces opportunities for doing I/O and computation concurrently.

Use get_write_buffer_limits() to get the limits.

WriteTransport.write(data)

トランスポートにバイト列 data を書き込みます。

このメソッドはブロックしません; データをバッファーし、非同期に送信する準備を行います。

WriteTransport.writelines(list_of_data)

バイト列のデータのリスト (またはイテラブル) をトランスポートに書き込みます。この振る舞いはイテラブルを yield して各要素で write() を呼び出すことと等価ですが、より効率的な実装となる場合があります。

WriteTransport.write_eof()

Close the write end of the transport after flushing all buffered data. Data may still be received.

This method can raise NotImplementedError if the transport (e.g. SSL) doesn't support half-closed connections.

Datagram Transports

DatagramTransport.sendto(data, addr=None)

リモートピア addr (トランスポート依存の対象アドレス) にバイト列 data を送信します。addr が None の場合、データはトランスポートの作成時に指定された送信先に送られます。

このメソッドはブロックしません; データをバッファーし、非同期に送信する準備を行います。

DatagramTransport.abort()

Close the transport immediately, without waiting for pending operations to complete. Buffered data will be lost. No more data will be received. The protocol's protocol.connection_lost() method will eventually be called with None as its argument.

Subprocess Transports

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()

Return the subprocess return code as an integer or None if it hasn't returned, which is similar to the subprocess.Popen.returncode attribute.

SubprocessTransport.kill()

Kill the subprocess.

POSIX システムでは、この関数はサブプロセスに SIGKILL を送信します。Windows では、このメソッドは terminate() の別名です。

See also subprocess.Popen.kill().

SubprocessTransport.send_signal(signal)

サブプロセスにシグナル signal を送信します。subprocess.Popen.send_signal() と同じです。

SubprocessTransport.terminate()

Stop the subprocess.

POSIX システムでは、このメソッドはサブプロセスに SIGTERM を送信します。Windows では、Windows API 関数 TerminateProcess() が呼び出されます。

See also subprocess.Popen.terminate().

SubprocessTransport.close()

Kill the subprocess by calling the kill() method.

If the subprocess hasn't returned yet, and close transports of stdin, stdout, and stderr pipes.

プロトコル

asyncio provides a set of abstract base classes that should be used to implement network protocols. Those classes are meant to be used together with transports.

Subclasses of abstract base protocol classes may implement some or all methods. All these methods are callbacks: they are called by transports on certain events, for example when some data is received. A base protocol method should be called by the corresponding transport.

Base Protocols

class asyncio.BaseProtocol

Base protocol with methods that all protocols share.

class asyncio.Protocol(BaseProtocol)

The base class for implementing streaming protocols (TCP, Unix sockets, etc).

class asyncio.BufferedProtocol(BaseProtocol)

A base class for implementing streaming protocols with manual control of the receive buffer.

class asyncio.DatagramProtocol(BaseProtocol)

The base class for implementing datagram (UDP) protocols.

class asyncio.SubprocessProtocol(BaseProtocol)

The base class for implementing protocols communicating with child processes (unidirectional pipes).

Base Protocol

All asyncio protocols can implement Base Protocol callbacks.

Connection Callbacks

Connection callbacks are called on all protocols, exactly once per a successful connection. All other protocol callbacks can only be called between those two methods.

BaseProtocol.connection_made(transport)

コネクションが作成されたときに呼び出されます。

The transport argument is the transport representing the connection. The protocol is responsible for storing the reference to its transport.

BaseProtocol.connection_lost(exc)

コネクションが失われた、あるいはクローズされたときに呼び出されます。

引数は例外オブジェクトまたは None になります。None のとき、通常の EOF が受信されたか、あるいはコネクションがこちら側から中止またはクローズされたことを意味します。

Flow Control Callbacks

Flow control callbacks can be called by transports to pause or resume writing performed by the protocol.

See the documentation of the set_write_buffer_limits() method for more details.

BaseProtocol.pause_writing()

Called when the transport's buffer goes over the high watermark.

BaseProtocol.resume_writing()

Called when the transport's buffer drains below the low watermark.

If the buffer size equals the high watermark, pause_writing() is not called: the buffer size must go strictly over.

Conversely, resume_writing() is called when the buffer size is equal or lower than the low watermark. These end conditions are important to ensure that things go as expected when either mark is zero.

Streaming Protocols

Event methods, such as loop.create_server(),
loop.create_unix_server(), loop.create_connection(),
loop.create_unix_connection(), loop.connect_accepted_socket(),
loop.connect_read_pipe(), and loop.connect_write_pipe()
accept factories that return streaming protocols.

Protocol.data_received(data)

データを受信したときに呼び出されます。data は受信したデータを含む空ではないバイト列オブジェクトになります。

Whether the data is buffered, chunked or reassembled depends on the transport. In general, you shouldn't rely on specific semantics and instead make your parsing generic and flexible. However, data is always received in the correct order.

The method can be called an arbitrary number of times while a connection is open.

However, protocol.eof_received() is called at most once. Once eof_received() is called, data_received() is not called anymore.

Protocol.eof_received()

Called when the other end signals it won't send any more data (for example by calling transport.write_eof(), if the other end also uses asyncio).

This method may return a false value (including None), in which case the transport will close itself. Conversely, if this method returns a true value, the protocol used determines whether to close the transport. Since the default implementation returns None, it implicitly closes the connection.

Some transports, including SSL, don't support half-closed connections, in which case returning true from this method will result in the connection being closed.

ステートマシン:

start -> connection_made
    [-> data_received]*
    [-> eof_received]?
-> connection_lost -> end

Buffered Streaming Protocols

バージョン 3.7 で追加: Important: this has been added to asyncio in Python 3.7 on a provisional basis! This is as an experimental API that might be changed or removed completely in Python 3.8.

Buffered Protocols can be used with any event loop method that supports Streaming Protocols.

BufferedProtocol implementations allow explicit manual allocation and control of the receive buffer. Event loops can then use the buffer provided by the protocol to avoid unnecessary data copies. This can result in noticeable performance improvement for protocols that receive big amounts of data. Sophisticated protocol implementations can significantly reduce the number of buffer allocations.

The following callbacks are called on BufferedProtocol instances:

BufferedProtocol.get_buffer(sizehint)

Called to allocate a new receive buffer.

sizehint is the recommended minimum size for the returned buffer. It is acceptable to return smaller or larger buffers than what sizehint suggests. When set to -1, the buffer size can be arbitrary. It is an error to return a buffer with a zero size.

get_buffer() must return an object implementing the buffer protocol.

BufferedProtocol.buffer_updated(nbytes)

Called when the buffer was updated with the received data.

nbytes is the total number of bytes that were written to the buffer.

BufferedProtocol.eof_received()

See the documentation of the protocol.eof_received() method.

get_buffer() can be called an arbitrary number of times during a connection. However, protocol.eof_received() is called at most once and, if called, get_buffer() and buffer_updated() won't be called after it.

ステートマシン:

start -> connection_made
    [-> get_buffer
        [-> buffer_updated]?
    ]*
    [-> eof_received]?
-> connection_lost -> end

Datagram Protocols

Datagram Protocol instances should be constructed by protocol factories passed to the loop.create_datagram_endpoint() method.

DatagramProtocol.datagram_received(data, addr)

データグラムを受信したときに呼び出されます。data は受信データを含むバイトオブジェクトです。addr はデータを送信するピアのアドレスです; 正確な形式はトランスポートに依存します。

DatagramProtocol.error_received(exc)

直前の送信あるいは受信が OSError を送出したときに呼び出されます。exc は OSError のインスタンスになります。

This method is called in rare conditions, when the transport (e.g. UDP) detects that a datagram could not be delivered to its recipient. In many conditions though, undeliverable datagrams will be silently dropped.

注釈

On BSD systems (macOS, FreeBSD, etc.) flow control is not supported for datagram protocols, because there is no reliable way to detect send failures caused by writing too many packets.

The socket always appears 'ready' and excess packets are dropped. An OSError with errno set to errno.ENOBUFS may or may not be raised; if it is raised, it will be reported to DatagramProtocol.error_received() but otherwise ignored.

Subprocess Protocols

Datagram Protocol instances should be constructed by protocol factories passed to the loop.subprocess_exec() and loop.subprocess_shell() methods.

SubprocessProtocol.pipe_data_received(fd, data)

Called when the child process writes data into its stdout or stderr pipe.

fd is the integer file descriptor of the pipe.

data is a non-empty bytes object containing the received data.

SubprocessProtocol.pipe_connection_lost(fd, exc)

Called when one of the pipes communicating with the child process is closed.

fd is the integer file descriptor that was closed.

SubprocessProtocol.process_exited()

子プロセスが終了したときに呼び出されます。

使用例

TCP Echo Server

Create a TCP echo server using the loop.create_server() method, send back received data, and close the connection:

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())

参考

The TCP echo server using streams example uses the high-level asyncio.start_server() function.

TCP Echo Client

A TCP echo client using the loop.create_connection() method, sends data, and waits until the connection is closed:

import asyncio

class EchoClientProtocol(asyncio.Protocol):
    def __init__(self, message, on_con_lost, loop):
        self.message = message
        self.loop = loop
        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, loop),
        '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())

参考

The TCP echo client using streams example uses the high-level asyncio.open_connection() function.

UDP Echo Server

A UDP echo server, using the loop.create_datagram_endpoint() method, sends back received data:

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 Echo Client

A UDP echo client, using the loop.create_datagram_endpoint() method, sends data and closes the transport when it receives the answer:

import asyncio

class EchoClientProtocol:
    def __init__(self, message, loop):
        self.message = message
        self.loop = loop
        self.transport = None
        self.on_con_lost = loop.create_future()

    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()

    message = "Hello World!"
    transport, protocol = await loop.create_datagram_endpoint(
        lambda: EchoClientProtocol(message, loop),
        remote_addr=('127.0.0.1', 9999))

    try:
        await protocol.on_con_lost
    finally:
        transport.close()

asyncio.run(main())

Connecting Existing Sockets

Wait until a socket receives data using the loop.create_connection() method with a protocol:

import asyncio
import socket

class MyProtocol(asyncio.Protocol):

    def __init__(self, loop):
        self.transport = None
        self.on_con_lost = loop.create_future()

    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()

    # 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(loop), 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())

参考

The watch a file descriptor for read events example uses the low-level loop.add_reader() method to register an FD.

The register an open socket to wait for data using streams example uses high-level streams created by the open_connection() function in a coroutine.

loop.subprocess_exec() and SubprocessProtocol

An example of a subprocess protocol used to get the output of a subprocess and to wait for the subprocess exit.

The subprocess is created by th loop.subprocess_exec() method:

import asyncio
import sys

class DateProtocol(asyncio.SubprocessProtocol):
    def __init__(self, exit_future):
        self.exit_future = exit_future
        self.output = bytearray()

    def pipe_data_received(self, fd, data):
        self.output.extend(data)

    def process_exited(self):
        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()

if sys.platform == "win32":
    asyncio.set_event_loop_policy(
        asyncio.WindowsProactorEventLoopPolicy())

date = asyncio.run(get_date())
print(f"Current date: {date}")

See also the same example written using high-level APIs.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


Policies

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

Policies

An event loop policy is a global per-process object that controls the management of the event loop. Each event loop has a default policy, which can be changed and customized using the policy API.

A policy defines the notion of context and manages a separate event loop per context. The default policy defines context to be the current thread.

By using a custom event loop policy, the behavior of get_event_loop(), set_event_loop(), and new_event_loop() functions can be customized.

Policy objects should implement the APIs defined in the AbstractEventLoopPolicy abstract base class.

Getting and Setting the Policy

The following functions can be used to get and set the policy for the current process:

asyncio.get_event_loop_policy()

Return the current process-wide policy.

asyncio.set_event_loop_policy(policy)

Set the current process-wide policy to policy.

If policy is set to None, the default policy is restored.

Policy Objects

The abstract event loop policy base class is defined as follows:

class asyncio.AbstractEventLoopPolicy

An abstract base class for asyncio policies.

get_event_loop()

現在のコンテクストのイベントループを取得します。

Return an event loop object implementing the AbstractEventLoop interface.

This method should never return None.

バージョン 3.6 で変更.

set_event_loop(loop)

現在のコンテキストにイベントループ loop を設定します。

new_event_loop()

Create and return a new event loop object.

This method should never return None.

get_child_watcher()

Get a child process watcher object.

Return a watcher object implementing the AbstractChildWatcher interface.

This function is Unix specific.

set_child_watcher(watcher)

Get the current child process watcher to watcher.

This function is Unix specific.

asyncio ships with the following built-in policies:

class asyncio.DefaultEventLoopPolicy

The default asyncio policy. Uses SelectorEventLoop on both Unix and Windows platforms.

There is no need to install the default policy manually. asyncio is configured to use the default policy automatically.

class asyncio.WindowsProactorEventLoopPolicy

An alternative event loop policy that uses the ProactorEventLoop event loop implementation.

利用可能な環境: Windows 。

Process Watchers

A process watcher allows customization of how an event loop monitors child processes on Unix. Specifically, the event loop needs to know when a child process has exited.

In asyncio, child processes are created with create_subprocess_exec() and loop.subprocess_exec() functions.

asyncio defines the AbstractChildWatcher abstract base class, which child watchers should implement, and has two different implementations: SafeChildWatcher (configured to be used by default) and FastChildWatcher.

See also the Subprocess and Threads section.

The following two functions can be used to customize the child process watcher implementation used by the asyncio event loop:

asyncio.get_child_watcher()

Return the current child watcher for the current policy.

asyncio.set_child_watcher(watcher)

Set the current child watcher to watcher for the current policy. watcher must implement methods defined in the AbstractChildWatcher base class.

注釈

Third-party event loops implementations might not support custom child watchers. For such event loops, using set_child_watcher() might be prohibited or have no effect.

class asyncio.AbstractChildWatcher
add_child_handler(pid, callback, *args)

Register a new child handler.

Arrange for callback(pid, returncode, *args) to be called when a process with PID equal to pid terminates. Specifying another callback for the same process replaces the previous handler.

The callback callable must be thread-safe.

remove_child_handler(pid)

Removes the handler for process with PID equal to pid.

The function returns True if the handler was successfully removed, False if there was nothing to remove.

attach_loop(loop)

Attach the watcher to an event loop.

If the watcher was previously attached to an event loop, then it is first detached before attaching to the new loop.

Note: loop may be None.

close()

Close the watcher.

This method has to be called to ensure that underlying resources are cleaned-up.

class asyncio.SafeChildWatcher

This implementation avoids disrupting other code spawning processes by polling every process explicitly on a SIGCHLD signal.

This is a safe solution but it has a significant overhead when handling a big number of processes (O(n) each time a SIGCHLD is received).

asyncio uses this safe implementation by default.

class asyncio.FastChildWatcher

This implementation reaps every terminated processes by calling os.waitpid(-1) directly, possibly breaking other code spawning processes and waiting for their termination.

There is no noticeable overhead when handling a big number of children (O(1) each time a child terminates).

Custom Policies

To implement a new event loop policy, it is recommended to subclass DefaultEventLoopPolicy and override the methods for which custom behavior is wanted, e.g.:

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())

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


Platform Support

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

Platform Support

The asyncio module is designed to be portable, but some platforms have subtle differences and limitations due to the platforms' underlying architecture and capabilities.

All Platforms

  • loop.add_reader() and loop.add_writer() cannot be used to monitor file I/O.

Windows

All event loops on Windows do not support the following methods:

  • 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() and loop.remove_signal_handler() are not supported.

SelectorEventLoop has the following limitations:

  • SelectSelector is used to wait on socket events: it supports sockets and is limited to 512 sockets.
  • loop.add_reader() and loop.add_writer() only accept socket handles (e.g. pipe file descriptors are not supported).
  • Pipes are not supported, so the loop.connect_read_pipe() and loop.connect_write_pipe() methods are not implemented.
  • Subprocesses are not supported, i.e. loop.subprocess_exec() and loop.subprocess_shell() methods are not implemented.

ProactorEventLoop has the following limitations:

  • The loop.create_datagram_endpoint() method is not supported.
  • The loop.add_reader() and loop.add_writer() methods are not supported.

The resolution of the monotonic clock on Windows is usually around 15.6 msec. The best resolution is 0.5 msec. The resolution depends on the hardware (availability of HPET) and on the Windows configuration.

Subprocess Support on Windows

SelectorEventLoop on Windows does not support subproceses. On Windows, ProactorEventLoop should be used instead:

import asyncio

asyncio.set_event_loop_policy(
    asyncio.WindowsProactorEventLoopPolicy())

asyncio.run(your_code())

The policy.set_child_watcher() function is also not supported, as ProactorEventLoop has a different mechanism to watch child processes.

macOS

Modern macOS versions are fully supported.

macOS <= 10.8

On macOS 10.6, 10.7 and 10.8, the default event loop uses selectors.KqueueSelector, which does not support character devices on these versions. The SelectorEventLoop can be manually configured to use SelectSelector or PollSelector to support character devices on these older versions of macOS. Example:

import asyncio
import selectors

selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


高水準の API インデックス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

高水準の API インデックス

このページには、すべての高水準の 非同期/待機 可能な asyncio API が一覧になっています。

タスク

ユーティリティは asyncio プログラムを実行し、タスクを作成し、タイムアウトのある複数の機能を待っています。

run() | イベントループを作成し、コルーチンを実行し、ループを閉じます。
create_task() | asyncio タスクを開始します。
await sleep() | 数秒間スリープします。
await gather() | 並行してスケジュールして、待ちます。
await wait_for() | タイムアウトで実行します。
await shield() | 取り消しから保護します。
await wait() | 完了かどうかを監視します。
current_task() | 現在のタスクを返します。
all_tasks() | イベントループのすべてのタスクを返します。
Task | Task オブジェクト
run_coroutine_threadsafe() | Schedule a coroutine from another OS thread.
for in as_completed() | Monitor for completion with a for loop.

使用例

  • Using asyncio.gather() to run things in parallel.
  • Using asyncio.wait_for() to enforce a timeout.
  • Cancellation.
  • Using asyncio.sleep().
  • See also the main Tasks documentation page.

キュー

Queues should be used to distribute work amongst multiple asyncio Tasks, implement connection pools, and pub/sub patterns.

Queue | A FIFO queue.
PriorityQueue | A priority queue.
LifoQueue | A LIFO queue.

使用例

  • Using asyncio.Queue to distribute workload between several Tasks.
  • See also the Queues documentation page.

Subprocesses

Utilities to spawn subprocesses and run shell commands.

await create_subprocess_exec() | サブプロセスを作成します。
await create_subprocess_shell() | Run a shell command.

使用例

  • Executing a shell command.
  • See also the subprocess APIs documentation.

Streams

High-level APIs to work with network IO.

await open_connection() | Establish a TCP connection.
await open_unix_connection() | Establish a Unix socket connection.
await start_server() | Start a TCP server.
await start_unix_server() | Start a Unix socket server.
StreamReader | High-level async/await object to receive network data.
StreamWriter | High-level async/await object to send network data.

使用例

  • Example TCP client.
  • See also the streams APIs documentation.

Synchronization

Threading-like synchronization primitives that can be used in Tasks.

Lock | A mutex lock.
Event | An event object.
Condition | A condition object.
Semaphore | A semaphore.
BoundedSemaphore | A bounded semaphore.

使用例

  • Using asyncio.Event.
  • See also the documentation of asyncio synchronization primitives.

例外

asyncio.TimeoutError | Raised on timeout by functions like wait_for(). Keep in mind that asyncio.TimeoutError is unrelated to the built-in TimeoutError exception.
asyncio.CancelledError | Raised when a Task is cancelled. See also Task.cancel().

使用例

  • Handling CancelledError to run code on cancellation request.
  • See also the full list of asyncio-specific exceptions.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


Low-level API Index

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

Low-level API Index

This page lists all low-level asyncio APIs.

Obtaining the Event Loop

asyncio.get_running_loop() | The preferred function to get the running event loop.
asyncio.get_event_loop() | Get an event loop instance (current or via the policy).
asyncio.set_event_loop() | Set the event loop as current via the current policy.
asyncio.new_event_loop() | Create a new event loop.

使用例

  • Using asyncio.get_running_loop().

Event Loop Methods

See also the main documentation section about the event loop methods.

Lifecycle

loop.run_until_complete() | Run a Future/Task/awaitable until complete.
loop.run_forever() | Run the event loop forever.
loop.stop() | Stop the event loop.
loop.close() | Close the event loop.
loop.is_running() | Return True if the event loop is running.
loop.is_closed() | Return True if the event loop is closed.
await loop.shutdown_asyncgens() | Close asynchronous generators.

デバッグ

loop.set_debug() | Enable or disable the debug mode.
loop.get_debug() | Get the current debug mode.

Scheduling Callbacks

loop.call_soon() | Invoke a callback soon.
loop.call_soon_threadsafe() | A thread-safe variant of loop.call_soon().
loop.call_later() | Invoke a callback after the given time.
loop.call_at() | Invoke a callback at the given time.

Thread/Process Pool

await loop.run_in_executor() | Run a CPU-bound or other blocking function in a concurrent.futures executor.
loop.set_default_executor() | Set the default executor for loop.run_in_executor().

Tasks and Futures

loop.create_future() | Create a Future object.
loop.create_task() | Schedule coroutine as a Task.
loop.set_task_factory() | Set a factory used by loop.create_task() to create Tasks.
loop.get_task_factory() | Get the factory loop.create_task() uses to create Tasks.

DNS

await loop.getaddrinfo() | Asynchronous version of socket.getaddrinfo().
await loop.getnameinfo() | Asynchronous version of socket.getnameinfo().

Networking and IPC

await loop.create_connection() | Open a TCP connection.
await loop.create_server() | Create a TCP server.
await loop.create_unix_connection() | Open a Unix socket connection.
await loop.create_unix_server() | Create a Unix socket server.
await loop.connect_accepted_socket() | Wrap a socket into a (transport, protocol) pair.
await loop.create_datagram_endpoint() | Open a datagram (UDP) connection.
await loop.sendfile() | Send a file over a transport.
await loop.start_tls() | Upgrade an existing connection to TLS.
await loop.connect_read_pipe() | Wrap a read end of a pipe into a (transport, protocol) pair.
await loop.connect_write_pipe() | Wrap a write end of a pipe into a (transport, protocol) pair.

ソケット

await loop.sock_recv() | Receive data from the socket.
await loop.sock_recv_into() | Receive data from the socket into a buffer.
await loop.sock_sendall() | Send data to the socket.
await loop.sock_connect() | Connect the socket.
await loop.sock_accept() | Accept a socket connection.
await loop.sock_sendfile() | Send a file over the socket.
loop.add_reader() | Start watching a file descriptor for read availability.
loop.remove_reader() | Stop watching a file descriptor for read availability.
loop.add_writer() | Start watching a file descriptor for write availability.
loop.remove_writer() | Stop watching a file descriptor for write availability.

Unix Signals

loop.add_signal_handler() | Add a handler for a signal.
loop.remove_signal_handler() | Remove a handler for a signal.

Subprocesses

loop.subprocess_exec() | Spawn a subprocess.
loop.subprocess_shell() | Spawn a subprocess from a shell command.

エラー処理

loop.call_exception_handler() | Call the exception handler.
loop.set_exception_handler() | Set a new exception handler.
loop.get_exception_handler() | Get the current exception handler.
loop.default_exception_handler() | The default exception handler implementation.

使用例

  • Using asyncio.get_event_loop() and loop.run_forever().
  • Using loop.call_later().
  • Using loop.create_connection() to implement an echo-client.
  • Using loop.create_connection() to connect a socket.
  • Using add_reader() to watch an FD for read events.
  • Using loop.add_signal_handler().
  • Using loop.subprocess_exec().

トランスポート

All transports implement the following methods:

transport.close() | Close the transport.
transport.is_closing() | トランスポートを閉じている最中か閉じていた場合 True を返します。
transport.get_extra_info() | Request for information about the transport.
transport.set_protocol() | Set a new protocol.
transport.get_protocol() | 現在のプロトコルを返します。

Transports that can receive data (TCP and Unix connections, pipes, etc). Returned from methods like loop.create_connection(), loop.create_unix_connection(), loop.connect_read_pipe(), etc:

Read Transports

transport.is_reading() | Return True if the transport is receiving.
transport.pause_reading() | Pause receiving.
transport.resume_reading() | Resume receiving.

Transports that can Send data (TCP and Unix connections, pipes, etc). Returned from methods like loop.create_connection(), loop.create_unix_connection(), loop.connect_write_pipe(), etc:

Write Transports

transport.write() | Write data to the transport.
transport.writelines() | Write buffers to the transport.
transport.can_write_eof() | Return True if the transport supports sending EOF.
transport.write_eof() | Close and send EOF after flushing buffered data.
transport.abort() | Close the transport immediately.
transport.get_write_buffer_size() | Return high and low water marks for write flow control.
transport.set_write_buffer_limits() | Set new high and low water marks for write flow control.

Transports returned by loop.create_datagram_endpoint():

Datagram Transports

transport.sendto() | Send data to the remote peer.
transport.abort() | Close the transport immediately.

Low-level transport abstraction over subprocesses. Returned by loop.subprocess_exec() and loop.subprocess_shell():

Subprocess Transports

transport.get_pid() | Return the subprocess process id.
transport.get_pipe_transport() | Return the transport for the requested communication pipe (stdin, stdout, or stderr).
transport.get_returncode() | Return the subprocess return code.
transport.kill() | Kill the subprocess.
transport.send_signal() | Send a signal to the subprocess.
transport.terminate() | Stop the subprocess.
transport.close() | Kill the subprocess and close all pipes.

プロトコル

Protocol classes can implement the following callback methods:

callback connection_made() | コネクションが作成されたときに呼び出されます。
callback connection_lost() | コネクションが失われた、あるいはクローズされたときに呼び出されます。
callback pause_writing() | Called when the transport's buffer goes over the high water mark.
callback resume_writing() | Called when the transport's buffer drains below the low water mark.

Streaming Protocols (TCP, Unix Sockets, Pipes)

callback data_received() | Called when some data is received.
callback eof_received() | Called when an EOF is received.

Buffered Streaming Protocols

callback get_buffer() | Called to allocate a new receive buffer.
callback buffer_updated() | Called when the buffer was updated with the received data.
callback eof_received() | Called when an EOF is received.

Datagram Protocols

callback datagram_received() | Called when a datagram is received.
callback error_received() | Called when a previous send or receive operation raises an OSError.

Subprocess Protocols

callback pipe_data_received() | Called when the child process writes data into its stdout or stderr pipe.
callback pipe_connection_lost() | Called when one of the pipes communicating with the child process is closed.
callback process_exited() | 子プロセスが終了したときに呼び出されます。

Event Loop Policies

Policies is a low-level mechanism to alter the behavior of functions like asyncio.get_event_loop(). See also the main policies section for more details.

Accessing Policies

asyncio.get_event_loop_policy() | Return the current process-wide policy.
asyncio.set_event_loop_policy() | Set a new process-wide policy.
AbstractEventLoopPolicy | Base class for policy objects.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


Developing with asyncio

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »

Developing with asyncio

Asynchronous programming is different from classic "sequential" programming.

This page lists common mistakes and traps and explains how to avoid them.

Debug Mode

By default asyncio runs in production mode. In order to ease the development asyncio has a debug mode.

There are several ways to enable asyncio debug mode:

  • Setting the PYTHONASYNCIODEBUG environment variable to 1.
  • Using the -X dev Python command line option.
  • Passing debug=True to asyncio.run().
  • Calling loop.set_debug().

In addition to enabling the debug mode, consider also:

  • 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)

  • configuring the warnings module to display ResourceWarning warnings. One way of doing that is by using the -W default command line option.

When the debug mode is enabled:

  • asyncio checks for coroutines that were not awaited and logs them; this mitigates the "forgotten await" pitfall.
  • Many non-threadsafe asyncio APIs (such as loop.call_soon() and loop.call_at() methods) raise an exception if they are called from a wrong thread.
  • The execution time of the I/O selector is logged if it takes too long to perform an I/O operation.
  • Callbacks taking longer than 100ms are logged. The loop.slow_callback_duration attribute can be used to set the minimum execution duration in seconds that is considered "slow".

Concurrency and Multithreading

An event loop runs in a thread (typically the main thread) and executes all callbacks and Tasks in its thread. While a Task is running in the event loop, no other Tasks can run in the same thread. When a Task executes an await expression, the running Task gets suspended, and the event loop executes the next Task.

To schedule a callback from a different OS thread, the loop.call_soon_threadsafe() method should be used. Example:

loop.call_soon_threadsafe(callback, *args)

Almost all asyncio objects are not thread safe, which is typically not a problem unless there is code that works with them from outside of a Task or a callback. If there's a need for such code to call a low-level asyncio API, the loop.call_soon_threadsafe() method should be used, e.g.:

loop.call_soon_threadsafe(fut.cancel)

To schedule a coroutine object from a different OS thread, the run_coroutine_threadsafe() function should be used. It returns a concurrent.futures.Future to access the result:

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()

シグナルの処理やサブプロセスの実行を行うには、イベントループはメインスレッド内で実行しなければなりません。

The loop.run_in_executor() method can be used with a concurrent.futures.ThreadPoolExecutor to execute blocking code in a different OS thread without blocking the OS thread that the event loop runs in.

Running Blocking Code

Blocking (CPU-bound) code should not be called directly. For example, if a function performs a CPU-intensive calculation for 1 second, all concurrent asyncio Tasks and IO operations would be delayed by 1 second.

An executor can be used to run a task in a different thread or even in a different process to avoid blocking block the OS thread with the event loop. See the loop.run_in_executor() method for more details.

ログ記録

asyncio uses the logging module and all logging is performed via the "asyncio" logger.

The default log level is logging.INFO, which can be easily adjusted:

logging.getLogger("asyncio").setLevel(logging.WARNING)

Detect never-awaited coroutines

When a coroutine function is called, but not awaited (e.g. coro() instead of await coro()) or the coroutine is not scheduled with asyncio.create_task(), asyncio will emit a 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()

The usual fix is to either await the coroutine or call the asyncio.create_task() function:

async def main():
    await test()

Detect never-retrieved exceptions

If a Future.set_exception() is called but the Future object is never awaited on, the exception would never be propagated to the user code. In this case, asyncio would emit a log message when the Future object is garbage collected.

Example of an unhandled exception:

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

Enable the debug mode to get the traceback where the task was created:

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »
  • asyncio --- Asynchronous I/O »


socket --- 低水準ネットワークインターフェイス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »

socket --- 低水準ネットワークインターフェイス

ソースコード: Lib/socket.py

このモジュールはBSDの ソケット(socket) インターフェイスへのアクセスを提供します。これは、近代的なUnixシステム、Windows、MacOS、その他多くのプラットフォームで動作します。

注釈

いくつかの挙動はプラットフォームに依存します。オペレーティングシステムのソケットAPIを呼び出しているためです。

Pythonインターフェースは、Unixのソケット用システムコールとライブラリインターフェースを、そのままPythonのオブジェクト指向スタイルに変換したものです。各種ソケット関連のシステムコールは、 socket() 関数で生成される socket オブジェクト のメソッドとして実装されています。 メソッドの引数は C のインターフェイスよりも多少高水準で、例えばファイルに対する read() や write() メソッドと同様に、 受信時のバッファ確保は自動的に処理され、送信時のバッファ長は暗黙的に決まります。

参考

Module socketserver
ネットワークサーバの開発を省力化するためのクラス群。
Module ssl
ソケットオブジェクトに対する TLS/SSL ラッパー.

ソケットファミリー

どのシステムで実行するかとビルドオプションに依存しますが、このモジュールによって多様なソケットファミリーをサポートします。

特定のソケットオブジェクトによって必要とされるアドレスフォーマットは、ソケットオブジェクトが生成されたときに指定されたアドレスファミリーを元に自動的に選択されます。ソケットアドレスは次の通りです。

  • ファイルシステム上のノードに束縛された AF_UNIX ソケットのアドレスは、ファイルシステムエンコーディングと 'surrogateescape' エラーハンドラ ( PEP 383 を参照) を使って文字列として表現されます。 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 は整数です。

    • For IPv4 addresses, two special forms are accepted instead of a host address: '' represents INADDR_ANY, which is used to bind to all interfaces, and the string '<broadcast>' represents INADDR_BROADCAST. This behavior is not compatible with IPv6, therefore, you may want to avoid these if you intend to support IPv6 with your Python programs.

  • AF_INET6 アドレスファミリーでは、 (host, port, flowinfo, scopeid) の4 要素のタプルが利用されます。 flowinfo と scopeid はそれぞれC言語の struct sockaddr_in6 の sin6_flowinfo と sin6_scope_id メンバーを表します。 socket モジュールのメソッドでは、後方互換性のために flowinfo と scopeid の省略を許しています。しかし、 scopeid を省略すると scope された IPv6 アドレスを操作するときに問題が起こる場合があることに注意してください。

    バージョン 3.7 で変更: For multicast addresses (with scopeid meaningful) address may not contain %scope (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).

  • 文字列またはタプル (id, unit) は PF_SYSTEM ファミリーの SYSPROTO_CONTROL プロトコルのために使用されます。この文字列は、動的に割り当てられたIDによるカーネルコントロールの名前です。このタプルは、カーネルコントロールのIDとユニット番号が既知の場合、または登録済みIDが使用中の場合に使用することができます。

    バージョン 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 ビットの整数です。

    Availability: Linux 2.6.38, some algorithm types require more recent Kernels.

    バージョン 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.

    Availability: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5.

    バージョン 3.7 で追加.

  • AF_PACKET is a low-level interface directly to network devices. The packets are represented by the tuple (ifname, proto[, pkttype[, hatype[, addr]]]) where:

    • ifname - String specifying the device name.
    • proto - An in network-byte-order integer specifying the Ethernet protocol number.
    • pkttype - Optional integer specifying the packet type:
      • PACKET_HOST (the default) - Packet addressed to the local host.
      • PACKET_BROADCAST - Physical-layer broadcast packet.
      • PACKET_MULTIHOST - 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.

IPv4/v6ソケットの host 部にホスト名を指定すると、処理結果が一定ではない場合があります。これはPythonはDNSから取得したアドレスのうち最初のアドレスを使用するので、 DNSの処理やホストの設定によって異なるIPv4/6アドレスを取得する場合があるためです。常に同じ結果が必要であれば、 host に数値のアドレスを指定してください。

全てのエラーは例外を発生させます。引数型のエラーやメモリ不足の場合には通常の例外が発生し、ソケットやアドレス関連のエラーは Python 3.3 からは OSError かそのサブクラスを発生させます (Python 3.3 以前は socket.error を発生させていました)。

setblocking() メソッドで、非ブロッキングモードを使用することができます。また、より汎用的に settimeout() メソッドでタイムアウトを指定する事ができます。

モジュールの内容

socket モジュールは以下の要素を公開しています。

例外

exception socket.error

OSError の非推奨のエイリアスです。

バージョン 3.3 で変更: 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

OSError のサブクラスです。この例外は getaddrinfo() と getnameinfo() でアドレス関連のエラーが発生した場合に送出されます。例外の値は (error, string) のペアで、ライブラリの呼び出し結果を返します。 string はC関数 gai_strerror() で取得した、 error の意味を示す文字列です。 error の値は、このモジュールで定義される EAI_* 定数のどれかとなります。

バージョン 3.3 で変更: このクラスは OSError のサブクラスになりました。

exception socket.timeout

OSError のサブクラスです。この例外は、あらかじめ settimeout() を呼び出して (あるいは setdefaulttimeout() を利用して暗黙に) タイムアウトを有効にしてあるソケットでタイムアウトが生じた際に送出されます。 例外に付属する値は文字列で、その内容は現状では常に "timed out" となります。

バージョン 3.3 で変更: このクラスは OSError のサブクラスになりました。

定数

AF_* 定数と SOCK_* 定数は、 AddressFamily と SocketKind IntEnum collection になりました。

バージョン 3.4 で追加.

socket.AF_UNIX
socket.AF_INET
socket.AF_INET6

アドレス (およびプロトコル) ファミリーを示す定数で、 socket() の 最初の引数に指定することができます。 AF_UNIX ファミリーをサポート しないプラットフォームでは、 AF_UNIX は未定義となります。システムによってはこれら以外の定数が定義されているかもしれません。

socket.SOCK_STREAM
socket.SOCK_DGRAM
socket.SOCK_RAW
socket.SOCK_RDM
socket.SOCK_SEQPACKET

ソケットタイプを示す定数で、 socket() の2番目の引数に指定することができます。システムによってはこれら以外の定数が定義されているかもしれません。 (ほとんどの場合、 SOCK_STREAM と SOCK_DGRAM 以外は必要ありません。)

socket.SOCK_CLOEXEC
socket.SOCK_NONBLOCK

この2つの定数が定義されていた場合、ソケットタイプと組み合わせていくつかの flags をアトミックに設定することができます (別の呼び出しを不要にして競合状態を避ける事ができます)。

参考

より完全な説明は Secure File Descriptor Handling を参照してください。

Availability: Linux >= 2.6.27.

バージョン 3.2 で追加.

SO_*
socket.SOMAXCONN
MSG_*
SOL_*
SCM_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*

Unixのソケット・IPプロトコルのドキュメントで定義されている各種定数。ソケットオブジェクトの setsockopt() や getsockopt() で使用します。ほとんどのシンボルはUnixのヘッダファイルに従っています。一部のシンボルには、デフォルト値を定義してあります。

バージョン 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 was added.

On Windows, TCP_KEEPIDLE, TCP_KEEPINTVL appear if run-time Windows supports.

socket.AF_CAN
socket.PF_CAN
SOL_CAN_*
CAN_*

Linux ドキュメントにあるこの形式の定数は socket モジュールでも定義されています。

Availability: Linux >= 2.6.25.

バージョン 3.3 で追加.

socket.CAN_BCM
CAN_BCM_*

CANプロトコルファミリーのCAN_BCMは、ブロードキャストマネージャー(BCM)プロトコルです。Linuxドキュメントにあるこの形式の定数は、socketモジュールでも定義されています。

Availability: Linux >= 2.6.25.

バージョン 3.4 で追加.

socket.CAN_RAW_FD_FRAMES

CAN_RAW ソケットで CAN FD をサポートします。これはデフォルトで無効になっています。これにより、アプリケーションが CAN フレームと CAN FD フレームを送信できるようになります。ただし、ソケットからの読み出し時に、CAN と CAN FD の両方のフレームを受け入れなければなりません。

この定数は、 Linux のドキュメンテーションで説明されています。

Availability: Linux >= 3.6.

バージョン 3.5 で追加.

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.

Availability: Linux >= 2.6.25.

バージョン 3.7 で追加.

socket.AF_PACKET
socket.PF_PACKET
PACKET_*

Linux ドキュメントにあるこの形式の定数は socket モジュールでも定義されています。

Availability: Linux >= 2.2.

socket.AF_RDS
socket.PF_RDS
socket.SOL_RDS
RDS_*

Linux ドキュメントにあるこの形式の定数は socket モジュールでも定義されています。

Availability: Linux >= 2.6.30.

バージョン 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 カーネル暗号用の定数です。

Availability: Linux >= 2.6.38.

バージョン 3.6 で追加.

socket.AF_VSOCK
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID
VMADDR*
SO_VM*

Constants for Linux host/guest communication.

Availability: Linux >= 4.8.

バージョン 3.7 で追加.

socket.AF_LINK

Availability: BSD, OSX.

バージョン 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 object を生成します。

socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)

Create a new socket using the given address family, socket type and protocol number. The address family should be AF_INET (the default), AF_INET6, AF_UNIX, AF_CAN, AF_PACKET, or AF_RDS. The socket type should be SOCK_STREAM (the default), SOCK_DGRAM, SOCK_RAW or perhaps one of the other SOCK_ constants. The protocol number is usually zero and may be omitted or in the case where the address family is AF_CAN the protocol should be one of CAN_RAW, CAN_BCM or CAN_ISOTP.

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

新たに作成されたソケットは 継承不可 です。

バージョン 3.3 で変更: AF_CAN, AF_RDS ファミリーが追加されました。

バージョン 3.4 で変更: CAN_BCMプロトコルが追加されました。

バージョン 3.4 で変更: 返されるソケットは継承不可になりました。

バージョン 3.7 で変更: The CAN_ISOTP protocol was added.

バージョン 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.

socket.socketpair([family[, type[, proto]]])

指定されたアドレスファミリー、ソケットタイプ、プロトコル番号から、接続されたソケットオブジェクトのペアを作成します。アドレスファミリー、ソケットタイプ、プロトコル番号は socket() 関数と同様に指定します。デフォルトのアドレスファミリは、プラットフォームで定義されている場合 AF_UNIX 、そうでなければ AF_INET が使われます。

新たに作成されたソケットは 継承不可 です。

バージョン 3.2 で変更: 返されるソケットオブジェクトが、サブセットではなく完全なソケットAPIを提供するようになりました。

バージョン 3.4 で変更: 返されるソケットの組は、どちらも継承不可になりました。

バージョン 3.5 で変更: Windows のサポートが追加されました。

socket.create_connection(address[, timeout[, source_address]])

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のデフォルトの動作になります。

バージョン 3.2 で変更: source_address が追加されました。

socket.fromfd(fd, family, type, proto=0)

ファイル記述子 (ファイルオブジェクトの fileno() メソッドが返す整数) fd を複製して、ソケットオブジェクトを構築します。アドレスファミリとプロトコル番号は socket() と同様に指定します。ファイル記述子 はソケットを指していなければなりませんが、実際にソケットであるかどうかのチェックは行っていません。このため、ソケット以外のファイル記述子 を指定するとその後の処理が失敗する場合があります。この関数が必要な事はあまりありませんが、 (Unixのinetデーモンに起動されるプログラムのように) ソケットを標準入力や標準出力として使用するプログラムでソケットオプションの取得や設定を行うために使われます。この関数で使用するソケットは、ブロッキングモードと想定しています。

新たに作成されたソケットは 継承不可 です。

バージョン 3.4 で変更: 返されるソケットは継承不可になりました。

socket.fromshare(data)

socket.share() メソッドから取得した data からソケットオブジェクトを生成します。ソケットはブロッキングモードだと仮定されます。

利用可能な環境: Windows 。

バージョン 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.

バージョン 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)

このタプルにある family, type, proto は、 socket() 関数を呼び出す際に指定する値と同じ整数です。 AI_CANONNAME を含んだ flags を指定した場合、 canonname は host の canonical name を示す文字列です。そうでない場合は canonname は空文字列です。 sockaddr は、ソケットアドレスを family に依存した形式で表すタプルで、 (AF_INET の場合は 2 要素のタプル (address, port) 、 AF_INET6 の場合は 4 要素のタプル (address, port, flow info, scope id)) socket.connect() メソッドに渡すためのものです。

次の例では example.org の 80 番ポートポートへの TCP 接続を得るためのアドレス情報を取得しようとしています。 (結果は IPv6 をサポートしているかどうかで変わります):

>>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
[(<AddressFamily.AF_INET6: 10>, <SocketType.SOCK_STREAM: 1>,
 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
 (<AddressFamily.AF_INET: 2>, <SocketType.SOCK_STREAM: 1>,
 6, '', ('93.184.216.34', 80))]

バージョン 3.2 で変更: パラメータをキーワード引数で渡すことができるようになりました。

バージョン 3.7 で変更: for IPv6 multicast addresses, string representing an address will not contain %scope part.

socket.getfqdn([name])

name の完全修飾ドメイン名を返します。 name が空または省略された場合、ローカルホストを指定したとみなします。完全修飾ドメイン名の取得にはまず gethostbyaddr() でチェックし、次に可能であればエイリアスを調べ、名前にピリオドを含む最初の名前を値として返します。完全修飾ドメイン名を取得できない場合、 gethostname() で返されるホスト名を返します。

socket.gethostbyname(hostname)

ホスト名を '100.50.200.5' のようなIPv4形式のアドレスに変換します。ホスト名としてIPv4アドレスを指定した場合、その値は変換せずにそのまま返ります。 gethostbyname() APIへのより完全なインターフェイスが必要であれば、 gethostbyname_ex() を参照してください。 gethostbyname() は、IPv6名前解決をサポートしていません。IPv4/ v6のデュアルスタックをサポートする場合は getaddrinfo() を使用します。

socket.gethostbyname_ex(hostname)

ホスト名から、IPv4形式の各種アドレス情報を取得します。戻り値は (hostname, aliaslist, ipaddrlist) のタプルで、 hostname は ip_address で指定したホストの正式名、 aliaslist は同じアドレスの別名のリスト(空の場合もある)、 ipaddrlist は同じホスト上の同一インターフェイスのIPv4アドレスのリスト(ほとんどの場合は単一のアドレスのみ) を示します。 gethostbyname_ex() は、IPv6名前解決をサポートしていません。IPv4/v6のデュアルスタックをサポートする場合は getaddrinfo() を使用します。

socket.gethostname()

Pythonインタープリタを現在実行しているマシンのホスト名を含む文字列を返します。

注意: gethostname() は完全修飾ドメイン名を返すとは限りません。完全修飾ドメイン名が必要であれば、getfqdn() を使用してください。

socket.gethostbyaddr(ip_address)

(hostname, aliaslist, ipaddrlist) のタプルを返し、 hostname は ip_address で指定したホストの正式名、 aliaslist は同じアドレスの別名のリスト(空の場合もある)、 ipaddrlist は同じホスト上の同一インターフェイスのIPv4アドレスのリスト(ほとんどの場合は単一のアドレスのみ)を示します。完全修飾ドメイン名が必要であれば、 getfqdn() を使用してください。 gethostbyaddr() は、IPv4/IPv6の両方をサポートしています。

socket.getnameinfo(sockaddr, flags)

ソケットアドレス sockaddr から、 (host, port) のタプルを取得します。 flags の設定に従い、 host は完全修飾ドメイン名または数値形式アドレスとなります。同様に、 port は文字列のポート名または数値のポート番号となります。

For IPv6 addresses, %scope is appended to the host part if sockaddr contains meaningful scopeid. Usually this happens for multicast addresses.

socket.getprotobyname(protocolname)

('icmp' のような) インターネットプロトコル名を、 socket() の 第三引数として指定する事ができる定数に変換します。これは主にソケットを "raw" モード(SOCK_RAW)でオープンする場合には必要ですが、通常の ソケットモードでは第三引数に0を指定するか省略すれば正しいプロトコルが自動的に選択されます。

socket.getservbyname(servicename[, protocolname])

インターネットサービス名とプロトコルから、そのサービスのポート番号を取得します。省略可能なプロトコル名として、 'tcp' か 'udp' のどちらかを指定することができます。指定がなければどちらのプロトコルにもマッチします。

socket.getservbyport(port[, protocolname])

インターネットポート番号とプロトコル名から、サービス名を取得します。省略可能なプロトコル名として、 'tcp' か 'udp' のどちらかを指定することができます。指定がなければどちらのプロトコルにもマッチします。

socket.ntohl(x)

32ビットの正の整数のバイトオーダを、ネットワークバイトオーダからホストバイトオーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致するマシンでは、この関数は何もしません。それ以外の場合は4バイトのスワップを行います。

socket.ntohs(x)

16ビットの正の整数のバイトオーダを、ネットワークバイトオーダからホストバイトオーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致するマシンでは、この関数は何もしません。それ以外の場合は2バイトのスワップを行います。

バージョン 3.7 で非推奨: In case x does not fit in 16-bit unsigned integer, but does fit in a positive C int, it is silently truncated to 16-bit unsigned integer. This silent truncation feature is deprecated, and will raise an exception in future versions of Python.

socket.htonl(x)

32ビットの正の整数のバイトオーダを、ホストバイトオーダからネットワークバイトオーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致するマシンでは、この関数は何もしません。それ以外の場合は4バイトのスワップを行います。

socket.htons(x)

16ビットの正の整数のバイトオーダを、ホストバイトオーダからネットワークバイトオーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致するマシンでは、この関数は何もしません。それ以外の場合は2バイトのスワップを行います。

バージョン 3.7 で非推奨: In case x does not fit in 16-bit unsigned integer, but does fit in a positive C int, it is silently truncated to 16-bit unsigned integer. This silent truncation feature is deprecated, and will raise an exception in future versions of Python.

socket.inet_aton(ip_string)

ドット記法によるIPv4アドレス('123.45.67.89' など)を32ビットにパックしたバイナリ形式に変換し、長さ4のバイト列オブジェクトとして返します。この関数が返す値は、標準Cライブラリの struct in_addr 型を使用する関数に渡す事ができます。

inet_aton() はドットが 3 個以下の文字列も受け取ります; 詳細については Unix のマニュアル 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 ライブラリのプログラムとやりとりする場合に便利です。struct 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() は、 struct in_addr 型 (inet_aton() と同様)や struct in6_addr を使用するライブラリやネットワークプロトコルを呼び出す際に使用することができます。

現在サポートされている address_family は、 AF_INET と AF_INET6 です。 ip_string に不正なIPアドレス文字列を指定すると、 OSError が発生します。有効な ip_string は、 address_family と inet_pton() の実装によって異なります。

Availability: Unix (maybe not all platforms), 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() と同様に)、 struct in_addr 型や struct in6_addr 型のオブジェクトを返すライブラリやネットワークプロトコル等で使用することができます。

現在サポートされている address_family の値は、 AF_INET と AF_INET6 です。バイトオブジェクトの packed_ip の長さが、指定したアドレスファミリで適切な長さでない場合、 ValueError が発生します。 inet_ntop() の呼び出しでエラーが起こると、 OSError が発生します。

Availability: Unix (maybe not all platforms), Windows.

バージョン 3.4 で変更: Windowsで利用可能になりました

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

socket.CMSG_LEN(length)

指定された length にある制御メッセージ（CMSG）から、末尾のパディングを除いた全体の長さを返します。この値は多くの場合、 recvmsg() が制御メッセージの一連の要素を受信するためのバッファサイズとして使用できますが、バッファの末尾が要素である場合であってもパディングは含まれるので、バッファサイズを取得するには RFC 3542 で求められているように、 CMSG_SPACE() を使用した移植可能なアプリケーションが必要です。通常 length は定数であり、許容範囲外の値が指定された場合は OverflowError 例外が送出されます。

Availability: most Unix platforms, possibly others.

バージョン 3.3 で追加.

socket.CMSG_SPACE(length)

指定された length の制御メッセージ（CMSG）の要素を recvmsg() が受信するために必要な、パディングを含めたバッファサイズを返します。複数の項目を受信するために必要なバッファスペースは、 CMSG_SPACE() が返すそれぞれの要素の長さの合計です。通常 length は定数であり、許容範囲外の値が指定された場合は OverflowError 例外が送出されます。

一部のシステムではこの関数を提供せずに制御メッセージをサポートする可能性があることに注意してください。また、この関数の返り値を使用して設定するバッファサイズは、受信する制御メッセージの量を正確に規定しないことがあり、その後に受信するデータがパディング領域に合う場合があることに注意してください。

Availability: most Unix platforms, possibly others.

バージョン 3.3 で追加.

socket.getdefaulttimeout()

新規に生成されたソケットオブジェクトの、デフォルトのタイムアウト値を浮動小数点形式の秒数で返します。タイムアウトを使用しない場合には None を返します。最初に socket モジュールがインポートされた時の初期値は None です。

socket.setdefaulttimeout(timeout)

新規に生成されるソケットオブジェクトの、デフォルトのタイムアウト値を秒数 (float 型) で設定します。最初に socket モジュールがインポートされた時の初期値は None です。指定可能な値とその意味については settimeout() メソッドを参照してください。

socket.sethostname(name)

マシンのホスト名を name に設定します。必要な権限がない場合は OSError を送出します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

socket.if_nameindex()

ネットワークインターフェイス情報 (index int, name string)のタプルを返します。システムコールが失敗した場合、 OSError 例外を送出します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

socket.if_nametoindex(if_name)

インターフェイス名 if_name に対応するネットワークインターフェイスのインデックス番号を返します。対応するインターフェースが存在しない場合は OSError 例外を送出します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

socket.if_indextoname(if_index)

インターフェイスインデックス番号 if_index に対応するネットワークインターフェイス名を返します。対応するインターフェイスが存在しない場合は OSError 例外を送出します。

利用可能な環境: Unix。

バージョン 3.3 で追加.

socket オブジェクト

ソケットオブジェクトは以下のメソッドを持ちます。 makefile() 以外のメソッドは、Unixのソケット用システムコールに対応しています。

バージョン 3.2 で変更: context manager プロトコルのサポートが追加されました。コンテキストマネージャを終了することは、 close() を呼ぶことと同一です。

socket.accept()

接続を受け付けます。ソケットはアドレスにbind済みで、listen中である必要があります。戻り値は (conn, address) のペアで、 conn は接続を通じてデータの送受信を行うための 新しい ソケットオブジェクト、 address は接続先でソケットにbindしているアドレスを示します。

新たに作成されたソケットは 継承不可 です。

バージョン 3.4 で変更: ソケットが 継承不可 になりました。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

socket.bind(address)

ソケットを address にbindします。bind済みのソケットを再バインドする事はできません。(address のフォーマットはアドレスファミリによって異なります -- 前述。)

socket.close()

ソケットを閉じられたものとしてマークします。 makefile() が返したファイルオブジェクトを閉じる時、対応する下層のシステムリソース（例：ファイル記述子）もすべて閉じます。一度この操作をすると、その後、このソケットオブジェクトに対するすべての操作が失敗します。キューに溜まったデータがフラッシュされた後は、リモート側の端点ではそれ以上のデータを受信しません。

ソケットはガベージコレクション時に自動的にクローズされます。しかし、明示的に close() するか、 with 文の中でソケットを使うことを推奨します。

バージョン 3.6 で変更: 下層の close() が呼び出される時、OSError が送出されるようになりました。

注釈

close() は接続に関連付けられたリソースを解放しますが、接続をすぐに切断するとは限りません。接続を即座に切断したい場合は、 close() の前に shutdown() を呼び出してください。

socket.connect(address)

address で示されるリモートソケットに接続します。(address のフォーマットはアドレスファミリによって異なります --- 前述。)

接続が信号によって中断された場合、このメソッドは接続が完了するまで待機するか、タイムアウト時に socket.timeout を送出します。タイムアウトは、信号ハンドラが例外を送出せず、ソケットがブロックするかタイムアウトが設定されている場合に起こります。非ブロックソケットでは、接続が信号によって中断された場合 (あるいは信号ハンドラにより例外が送出された場合)、このメソッドは InterruptedError 例外を送出します。

バージョン 3.5 で変更: このメソッドは、接続が信号によって中断され、信号ハンドラが例外を送出せず、ソケットがブロックであるかタイムアウトが設定されている場合、InterruptedError 例外を送出する代わりに、接続を完了するまで待機するようになりました (論拠については PEP 475 を参照してください)。

socket.connect_ex(address)

connect(address) と同様ですが、C言語の connect() 関数の呼び出しでエラーが発生した場合には例外を送出せずにエラーを戻り値として返します。(これ以外の、"host not found,"等のエラーの場合には例外が発生します。)処理が正常に終了した場合には 0 を返し、エラー時には errno の値を返します。この関数は、非同期接続をサポートする場合などに使用することができます。

socket.detach()

実際にファイル記述子を閉じることなく、ソケットオブジェクトを閉じた状態にします。ファイル記述子は返却され、他の目的に再利用することができます。

バージョン 3.2 で追加.

socket.dup()

ソケットを複製します。

新たに作成されたソケットは 継承不可 です。

バージョン 3.4 で変更: ソケットが 継承不可 になりました。

socket.fileno()

ソケットのファイル記述子を短い整数型で返します。失敗時には、-1 を返します。ファイル記述子は、 select.select() などで使用します。

Windowsではこのメソッドで返された小整数をファイル記述子を扱う箇所 (os.fdopen() など) で利用できません。 Unix にはこの制限はありません。

socket.get_inheritable()

ソケットのファイル記述子またはソケットのハンドルの 継承可能フラグ を取得します。ソケットが子プロセスへ継承可能なら True 、継承不可なら False を返します。

バージョン 3.4 で追加.

socket.getpeername()

ソケットが接続しているリモートアドレスを返します。この関数は、リモート IPv4/v6ソケットのポート番号を調べる場合などに使用します。 address のフォーマットはアドレスファミリによって異なります(前述)。この関数をサポートしていないシステムも存在します。

socket.getsockname()

ソケット自身のアドレスを返します。この関数は、IPv4/v6ソケットのポート番号を調べる場合などに使用します。(address のフォーマットはアドレスファミリによって異なります --- 前述。)

socket.getsockopt(level, optname[, buflen])

ソケットに指定されたオプションを返します(Unixのマニュアルページ getsockopt(2) を参照)。 SO_* 等のシンボルは、このモジュールで定義しています。 buflen を省略した場合、取得するオブションは整数とみなし、整数型の値を戻り値とします。 buflen を指定した場合、長さ buflen のバッファでオプションを受け取り、このバッファをバイト列オブジェクトとして返します。このバッファは、呼び出し元プログラムで struct モジュール等を利用して内容を読み取ることができます。

socket.getblocking()

Return True if socket is in blocking mode, False if in non-blocking.

This is equivalent to checking socket.gettimeout() == 0.

バージョン 3.7 で追加.

socket.gettimeout()

ソケットに指定されたタイムアウト値を取得します。タイムアウト値が設定されている場合には浮動小数点型で秒数が、設定されていなければ None が返ります。この値は、最後に呼び出された setblocking() または settimeout() によって設定されます。

socket.ioctl(control, option)
プラットフォーム: Windows

ioctl() メソッドは WSAIoctl システムインタフェースへの制限されたインタフェースです。詳しい情報については、 Win32 documentation を参照してください。

他のプラットフォームでは一般的な 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 に設定されます)。システムが新しい接続を拒否するまでに許可する未受付の接続の数を指定します。指定しない場合、デフォルトの妥当な値が選択されます。

バージョン 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])

ソケットからデータを受信し、結果を bytes オブジェクトで返します。一度に受信するデータは、最大でも bufsize で指定した量です。オプション引数 flags に指定するフラグの意味については、 Unix のマニュアルページ recv(2) を参照してください。 flags のデフォルトは 0 です。

注釈

ハードウェアおよびネットワークの現実に最大限マッチするように、 bufsize の値は比較的小さい2の累乗、たとえば 4096、にすべきです。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

socket.recvfrom(bufsize[, flags])

ソケットからデータを受信し、結果をタプル (bytes, address) として返します。 bytes は受信データの bytes オブジェクトで、 address は送信元のアドレスを示します。オプション引数 flags については、 Unix のマニュアルページ recv(2) を参照してください。デフォルトは0です。 (address のフォーマットはアドレスファミリによって異なります(前述))

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

バージョン 3.7 で変更: For multicast IPv6 address, first item of address does not contain %scope 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 型のバイナリ配列として表します。システムコールが返った後 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.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

Availability: most Unix platforms, possibly others.

バージョン 3.3 で追加.

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

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---')]

Availability: most Unix platforms, possibly others.

バージョン 3.3 で追加.

socket.recvfrom_into(buffer[, nbytes[, flags]])

ソケットからデータを受信し、そのデータを新しいバイト文字列として返す代わりに buffer に書きます。戻り値は (nbytes, address) のペアで、 nbytes は受信したデータのバイト数を、 address はデータを送信したソケットのアドレスです。オプション引数 flags (デフォルト:0) の意味については、 Unix マニュアルページ recv(2) を参照してください。(address のフォーマットは前述のとおりアドレスファミリーに依存します。)

socket.recv_into(buffer[, nbytes[, flags]])

nbytes バイトまでのデータをソケットから受信して、そのデータを新しいバイト文字列にするのではなく buffer に保存します。 nbytes が指定されない(あるいは0が指定された)場合、 buffer の利用可能なサイズまで受信します。受信したバイト数を返り値として返します。オプション引数 flags (デフォルト:0) の意味については、 Unix マニュアルページ recv(2) を参照してください。

socket.send(bytes[, flags])

ソケットにデータを送信します。ソケットはリモートソケットに接続済みでなければなりません。オプション引数 flags の意味は、上記 recv() と同じです。戻り値として、送信したバイト数を返します。アプリケーションでは、必ず戻り値をチェックし、全てのデータが送られた事を確認する必要があります。データの一部だけが送信された場合、アプリケーションで残りのデータを再送信してください。 ソケットプログラミング HOWTO に、さらに詳しい情報があります。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

socket.sendall(bytes[, flags])

ソケットにデータを送信します。ソケットはリモートソケットに接続済みでなければなりません。オプション引数 flags の意味は、上記 recv() と同じです。 send() と異なり、このメソッドは bytes の全データを送信するか、エラーが発生するまで処理を継続します。正常終了の場合は None を返し、エラー発生時には例外が発生します。エラー発生時、送信されたバイト数を調べる事はできません。

バージョン 3.5 で変更: ソケットのタイムアウトは、データが正常に送信される度にリセットされなくなりました。ソケットのタイムアウトは、すべてのデータを送る最大の合計時間となります。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

socket.sendto(bytes, address)
socket.sendto(bytes, flags, address)

ソケットにデータを送信します。このメソッドでは接続先を address で指定するので、接続済みではいけません。オプション引数 flags の意味は、上記 recv() と同じです。戻り値として、送信したバイト数を返します。(address のフォーマットはアドレスファミリによって異なります --- 前述。)

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

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: most Unix platforms, possibly others.

バージョン 3.3 で追加.

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

socket.sendmsg_afalg([msg, ]*, op[, iv[, assoclen[, flags]]])

sendmsg() の AF_ALG ソケット用に特化したバージョンです。AF_ALG ソケットの、モード、IV、AEAD に関連づけられたデータ長、フラグを設定します。

Availability: Linux >= 2.6.38.

バージョン 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 タイプでなければなりません。非ブロックソケットはサポートされていません。

バージョン 3.5 で追加.

socket.set_inheritable(inheritable)

ソケットのファイル記述子、またはソケットのハンドルの、 継承可能フラグ を立てます。

バージョン 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)

指定されたソケットオプションの値を設定します (Unix のマニュアルページ setsockopt(2) を参照)。必要なシンボリック定数は、socket モジュール (SO_* など) で定義されています。この値は、整数、None、またはバッファを表す bytes-like object のいずれかです。バイトライクオブジェクトの場合、バイト文字列に適切なビットが含まれていることを確認するのは呼び出し元の仕事です (C 構造をバイト文字列としてエンコードする方法については、オプションの組み込みモジュール struct を参照)。値が None に設定されている場合、optlen 引数が必須です。これは、optval=NULL と optlen=optlen で setsockopt C 関数を呼び出すのと同一です。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

バージョン 3.6 で変更: setsockopt(level, optname, None, optlen: int) の形式が追加されました。

socket.shutdown(how)

接続の片方向、または両方向を切断します。 how が SHUT_RD の場合、以降は受信を行えません。 how が SHUT_WR の場合、以降は送信を行えません。 how が SHUT_RDWR の場合、以降は送受信を行えません。

socket.share(process_id)

ソケットを複製し、対象のプロセスと共有するための bytes オブジェクトを返します。対象のプロセスを process_id で指定しなければなりません。戻り値の bytes オブジェクトは、何らかのプロセス間通信を使って対象のプロセスに伝えます。対象のプロセス側では、 fromshare() を使って複製されたソケットをとらえます。オペレーティング・システムは対象のプロセスに対してソケットを複製するため、このメソッドを呼び出した後であれば、元のソケットをクローズしても、対象のプロセスに渡ったソケットには影響がありません。

利用可能な環境: Windows 。

バージョン 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() が返すソケットは、オペレーティングシステムによってブロッキングモードまたは非ブロッキングモードになります。クロスプラットフォームの動作を確保したい場合、この設定を手動でオーバーライドすることをお勧めします。

使用例

以下は TCP/IP プロトコルの簡単なサンプルとして、受信したデータをクライアントにそのまま返送するサーバ (接続可能なクライアントは一件のみ) と、サーバに接続するクライアントの例を示します。サーバでは、 socket() ・ bind() ・ listen() ・ accept() を実行し (複数のクライアントからの接続を受け付ける場合、 accept() を複数回呼び出します)、クライアントでは socket() と connect() だけを呼び出しています。サーバでは sendall() / recv() メソッドは listen 中のソケットで実行するのではなく、 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))

次のサンプルは上記のサンプルとほとんど同じですが、IPv4 と IPv6 の両方をサポートしています。サーバでは、IPv4/v6 の両方ではなく、利用可能な最初のアドレスファミリだけを listen しています。ほとんどの IPv6 対応システムでは IPv6 が先に現れるため、サーバは IPv4 には応答しません。クライアントでは名前解決の結果として取得したアドレスに順次接続を試み、最初に接続に成功したソケットにデータを送信しています。

# 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 packages
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# receive a package
print(s.recvfrom(65565))

# disabled promiscuous mode
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

The next example shows how to use the socket interface to communicate to a CAN network using the raw socket protocol. To use CAN with the broadcast manager protocol instead, open a socket with:

socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)

ソケットの束縛 (CAN_RAW) または (CAN_BCM) 接続を行ったあと、ソケットオブジェクトで socket.send() と socket.recv() 操作 (とそのカウンターパート) を通常通りに使用することができます。

This last example might require special privileges:

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 状態のままにし、すぐには再利用できないことで起こります。

これを防ぐのに、 socket フラグの 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 "Basic Socket Interface Extensions for IPv6" を参照してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Networking and Interprocess Communication »


ssl --- ソケットオブジェクトに対する TLS/SSL ラッパー

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »

ssl --- ソケットオブジェクトに対する TLS/SSL ラッパー

Source code: Lib/ssl.py

このモジュールは Transport Layer Security ( "Secure Sockets Layer" という名前でよく知られています) 暗号化と、クライアントサイド、サーバサイド両方のネットワークソケットのためのピア認証の仕組みを提供しています。このモジュールは OpenSSL ライブラリを利用しています。 OpenSSL は、すべてのモダンな Unix システム、 Windows 、 Mac OS X 、その他幾つかの OpenSSL がインストールされているプラットフォームで利用できます。

注釈

OSのソケットAPIに対して実装されているので、幾つかの挙動はプラットフォーム依存になるかもしれません。インストールされているOpenSSLのバージョンの違いも挙動の違いの原因になるかもしれません。例えば、TLSv1.1, TLSv1.2 は openssl version 1.0.1 以降でのみ利用できます。

警告

セキュリティで考慮すべき点 を読まずにこのモジュールを使用しないでください。SSL のデフォルト設定はアプリケーションに十分ではないので、読まない場合はセキュリティに誤った意識を持ってしまうかもしれません。

このセクションでは、 ssl モジュールのオブジェクトと関数を解説します。 TLS, SSL, 証明書に関するより一般的な情報は、末尾にある "See Also" のセクションを参照してください。

このモジュールは ssl.SSLSocket クラスを提供します。このクラスは socket.socket クラスを継承していて、ソケットで通信されるデータをSSLで暗号化・復号するソケットに似たラッパーになります。また、このクラスは、接続の相手側からの証明書を取得する getpeercert() メソッドや、セキュア接続で使うための暗号方式を取得する cipher() メソッドのような追加のメソッドをサポートしています。

より洗練されたアプリケーションのために、 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 を必要とするようになります。

関数、定数、例外

ソケットの作成

Since Python 3.2 and 2.7.9, it is recommended to use the SSLContext.wrap_socket() of an SSLContext instance to wrap sockets as SSLSocket objects. The helper functions create_default_context() returns a new context with secure default settings. The old wrap_socket() function is deprecated since it is both inefficient and has no support for server name indication (SNI) and hostname matching.

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 証明書を信用して選択することができます。

設定は、 PROTOCOL_TLS, OP_NO_SSLv2, RC4 と非認証暗号化スイート以外の、高度暗号化スイートを利用した OP_NO_SSLv3 です。SERVER_AUTH を purpose として渡すと、verify_mode を CERT_REQUIRED に設定し、 CA 証明書をロードする (cafile, capath, cadata の少なくとも1つが与えられている場合) か、SSLContext.load_default_certs() を使用してデフォルトの CA 証明書をロードします。

注釈

プロトコル、オプション、暗号方式その他の設定は、事前に非推奨の状態にすることなく、もっと制限の強い値に変更される場合があります。これらの値は、互換性と安全性との妥当なバランスをとって決められます。

もしもあなたのアプリケーションが特定の設定を必要とする場合、 SSLContext を作って自分自身で設定を適用すべきです。

注釈

ある種の古いクライアントやサーバが接続しようと試みてきた場合に、この関数で作られた SSLContext が "Protocol or cipher suite mismatch" で始まるエラーを起こすのを目撃したらそれは、この関数が OP_NO_SSLv3 を使って除外している SSL 3.0 しかサポートしていないのでしょう。SSL 3.0 は 完璧にぶっ壊れている ことが広く知られています。それでもまだこの関数を使って、ただし SSL 3.0 接続を許可したいと望むならば、これをこのように再有効化できます:

ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3

バージョン 3.4 で追加.

バージョン 3.4.4 で変更: デフォルトの暗号設定から RC4 が除かれました。

バージョン 3.6 で変更: デフォルトの暗号化文字列に ChaCha20/Poly1305 が追加されました。

デフォルトの暗号化文字列から 3DES が除かれました。

例外

exception ssl.SSLError

(現在のところ OpenSSL ライブラリによって提供されている)下層の SSL 実装からのエラーを伝えるための例外です。このエラーは、低レベルなネットワークの上に載っている、高レベルな暗号化と認証レイヤーでの問題を通知します。このエラーは OSError のサブタイプです。 SSLError インスタンスのエラーコードとメッセージは OpenSSL ライブラリによるものです。

バージョン 3.3 で変更: SSLError は以前は socket.error のサブタイプでした。

library

エラーが起こった OpenSSL サブモジュールを示すニーモニック文字列で、 SSL, PEM, X509 などです。取り得る値は OpenSSL のバージョンに依存します。

バージョン 3.3 で追加.

reason

エラーが起こった原因を示すニーモニック文字列で、 CERTIFICATE_VERIFY_FAILED などです。取り得る値は OpenSSL のバージョンに依存します。

バージョン 3.3 で追加.

exception ssl.SSLZeroReturnError

読み出しあるいは書き込みを試みようとした際に SSL コネクションが行儀よく閉じられてしまった場合に送出される SSLError サブクラス例外です。これは下層の転送(read TCP)が閉じたことは意味しないことに注意してください。

バージョン 3.3 で追加.

exception ssl.SSLWantReadError

読み出しあるいは書き込みを試みようとした際に、リクエストが遂行される前に下層の TCP 転送で受け取る必要があるデータが不足した場合に non-blocking SSL socket によって送出される SSLError サブクラス例外です。

バージョン 3.3 で追加.

exception ssl.SSLWantWriteError

読み出しあるいは書き込みを試みようとした際に、リクエストが遂行される前に下層の TCP 転送が送信する必要があるデータが不足した場合に non-blocking SSL socket によって送出される SSLError サブクラス例外です。

バージョン 3.3 で追加.

exception ssl.SSLSyscallError

SSL ソケット上で操作を遂行しようとしていてシステムエラーが起こった場合に送出される SSLError サブクラス例外です。残念ながら元となった errno 番号を調べる簡単な方法はありません。

バージョン 3.3 で追加.

exception ssl.SSLEOFError

SSL コネクションが唐突に打ち切られた際に送出される SSLError サブクラス例外です。一般的に、このエラーが起こったら下層の転送を再利用しようと試みるべきではありません。

バージョン 3.3 で追加.

exception ssl.SSLCertVerificationError

A subclass of SSLError raised when certificate validation has failed.

バージョン 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

An alias for SSLCertVerificationError.

バージョン 3.7 で変更: The exception is now an alias for SSLCertVerificationError.

乱数生成

ssl.RAND_bytes(num)

暗号学的に強固な擬似乱数の num バイトを返します。擬似乱数生成器に十分なデータでシードが与えられていない場合や、現在の RANDOM メソッドに操作がサポートされていない場合は SSLError を送出します。 RAND_status() を使って擬似乱数生成器の状態をチェックできます。 RAND_add() を使って擬似乱数生成器にシードを与えることができます。

ほとんどすべてのアプリケーションでは os.urandom() が望ましいです。

暗号論的擬似乱数生成器に要求されることについては Wikipedia の記事 Cryptographically secure pseudorandom number generator (CSPRNG) (日本語版: 暗号論的擬似乱数生成器) を参照してください。

バージョン 3.3 で追加.

ssl.RAND_pseudo_bytes(num)

(bytes, is_cryptographic) タプルを返却: bytes は長さ num の擬似乱数バイト列、 is_cryptographic は、生成されたバイト列が暗号として強ければ True 。 操作が現在使われている RAND メソッドでサポートされていなければ、 SSLError が送出されます。

生成される擬似乱数バイトシーケンスは十分な長さであれば一意にはなるでしょうが、必ずしも予測不可能とは言えません。これは非暗号目的、あるいは暗号化プロトコルでの若干の用途に使われますが、普通は鍵生成などには使いません。

ほとんどすべてのアプリケーションでは os.urandom() が望ましいです。

バージョン 3.3 で追加.

バージョン 3.6 で非推奨: OpenSSL は ssl.RAND_pseudo_bytes() を廃止しました。代わりに ssl.RAND_bytes() を使用してください。

ssl.RAND_status()

SSL 擬似乱数生成器が十分なランダム性(randomness)を受け取っている時に True を、それ以外の場合は False を返します。 ssl.RAND_egd() と ssl.RAND_add() を使って擬似乱数生成機にランダム性を加えることができます。

ssl.RAND_egd(path)

もしエントロピー収集デーモン(EGD=entropy-gathering daemon)が動いていて、 path がEGDへのソケットのパスだった場合、この関数はそのソケットから 256バイトのランダム性を読み込み、SSL擬似乱数生成器にそれを渡すことで、生成される暗号鍵のセキュリティを向上させることができます。これは、より良いランダム性のソースが無いシステムでのみ必要です。

エントロピー収集デーモンについては、 http://egd.sourceforge.net/ や http://prngd.sourceforge.net/ を参照してください。

Availability: not available with LibreSSL and OpenSSL > 1.1.0.

ssl.RAND_add(bytes, entropy)

与えられた bytes をSSL擬似乱数生成器に混ぜます。 entropy 引数(float値)は、その文字列に含まれるエントロピーの下限(lower bound)です。 (なので、いつでも 0.0 を使うことができます。) エントロピーのソースについてのより詳しい情報は、 RFC 1750 を参照してください。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

証明書の取り扱い

ssl.match_hostname(cert, hostname)

Verify that cert (in decoded format as returned by SSLSocket.getpeercert()) matches the given hostname. The rules applied are those for checking the identity of HTTPS servers as outlined in RFC 2818, RFC 5280 and RFC 6125. In addition to HTTPS, this function should be suitable for checking the identity of servers in various SSL-based protocols such as FTPS, IMAPS, POPS and others.

失敗すれば CertificateError が送出されます。成功すれば、この関数は何も返しません:

>>> cert = {'subject': ((('commonName', 'example.com'),),)}
>>> ssl.match_hostname(cert, "example.com")
>>> ssl.match_hostname(cert, "example.org")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'

バージョン 3.2 で追加.

バージョン 3.3.3 で変更: この関数は RFC 6125 の section 6.4.3 に従うようになりましたので、マルチプルワイルドカード(例. *.*.com や *a*.example.org) にも国際化ドメイン名 (IDN=internationalized domain name)フラグメント内部に含まれるワイルドカードのどちらにも合致しません。 www*.xn--pthon-kva.org のような IDN A-labels はまだサポートしますが、 x*.python.org はもはや xn--tda.python.org には合致しません。

バージョン 3.5 で変更: 認定書の subjectAltName フィールドで提示されている場合、IP アドレスの一致がサポートされるようになりました。

バージョン 3.7 で変更: The function is no longer used to TLS connections. Hostname matching is now performed by OpenSSL.

Allow wildcard when it is the leftmost and the only character in that segment. Partial wildcards like www*.example.com are no longer supported.

バージョン 3.7 で非推奨.

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)。

バージョン 3.5 で変更: 入力文字列に指定された 'GMT' タイムゾーンを UTC として解釈するようになりました。以前はローカルタイムで解釈していました。また、整数を返すようになりました(入力に含まれる秒の端数を含まない)。

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_TLS, ca_certs=None)

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 same parameter in SSLContext.wrap_socket(). The call will attempt to validate the server certificate against that set of root certificates, and will fail if the validation attempt fails.

バージョン 3.3 で変更: この関数はIPv6互換になりました。

バージョン 3.5 で変更: ssl_version のデフォルトが、最近のサーバへの最大限の互換性のために PROTOCOL_SSLv3 から PROTOCOL_TLS に変更されました。

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 のパス

Availability: LibreSSL ignores the environment vars openssl_cafile_env and openssl_capath_env.

バージョン 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 。

バージョン 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 。

バージョン 3.4 で追加.

ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version=PROTOCOL_TLS, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True, ciphers=None)

socket.socket のインスタンス sock を受け取り、 socket.socket のサブタイプである ssl.SSLSocket のインスタンスを返します。 ssl.SSLSocket は低レイヤのソケットをSSLコンテキストでラップします。 sock は SOCK_STREAM ソケットでなければなりません; ほかのタイプのソケットはサポートされていません。

Internally, function creates a SSLContext with protocol ssl_version and SSLContext.options set to cert_reqs. If parameters keyfile, certfile, ca_certs or ciphers are set, then the values are passed to SSLContext.load_cert_chain(), SSLContext.load_verify_locations(), and SSLContext.set_ciphers().

The arguments server_side, do_handshake_on_connect, and suppress_ragged_eofs have the same meaning as SSLContext.wrap_socket().

バージョン 3.7 で非推奨: Since Python 3.2 and 2.7.9, it is recommended to use the SSLContext.wrap_socket() instead of wrap_socket(). The top-level function is limited and creates an insecure client socket without server name indication or hostname matching.

定数

すべての定数が enum.IntEnum コレクションまたは enum.IntFlag コレクションになりました。

バージョン 3.6 で追加.

ssl.CERT_NONE

Possible value for SSLContext.verify_mode, or the cert_reqs parameter to wrap_socket(). 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, or the cert_reqs parameter to wrap_socket(). 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.

この設定では、正当なCA証明書のセットを SSLContext.load_verify_locations() または wrap_socket() の ca_certs パラメータのどちらかに渡す必要があります。

ssl.CERT_REQUIRED

Possible value for SSLContext.verify_mode, or the cert_reqs parameter to wrap_socket(). 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.

この設定では、正当なCA証明書のセットを SSLContext.load_verify_locations() または wrap_socket() の ca_certs パラメータのどちらかに渡す必要があります。

class ssl.VerifyMode

CERT_* 定数の enum.IntEnum コレクションです。

バージョン 3.6 で追加.

ssl.VERIFY_DEFAULT

SSLContext.verify_flags に渡せる値です。このモードでは、証明書失効リスト(CRLs)はチェックされません。デフォルトでは OpenSSL は CRLs を必要ともしませんし検証にも使いません。

バージョン 3.4 で追加.

ssl.VERIFY_CRL_CHECK_LEAF

SSLContext.verify_flags に渡せる値です。このモードでは、接続先の証明書のチェックのみで仲介の CA 証明書はチェックしません。接続先証明書の発行者(その CA の直接の祖先)によって署名された妥当な CRL が必要です。 SSLContext.load_verify_locations が相応しいものをロードしていなければ、検証は失敗するでしょう。

バージョン 3.4 で追加.

ssl.VERIFY_CRL_CHECK_CHAIN

SSLContext.verify_flags に渡せる値です。このモードでは、接続先の証明書チェイン内のすべての証明書についての CRLs がチェックされます。

バージョン 3.4 で追加.

ssl.VERIFY_X509_STRICT

SSLContext.verify_flags に渡せる値で、壊れた X.509 証明書に対するワークアラウンドを無効にします。

バージョン 3.4 で追加.

ssl.VERIFY_X509_TRUSTED_FIRST

SSLContext.verify_flags に渡せる値です。OpenSSL に対し、証明書検証のために信頼チェインを構築する際、信頼できる証明書を選ぶように指示します。これはデフォルトで有効にされています。

バージョン 3.4.4 で追加.

class ssl.VerifyFlags

VERIFY_* 定数の enum.IntFlag コレクションです。

バージョン 3.6 で追加.

ssl.PROTOCOL_TLS

Selects the highest protocol version that both the client and server support. Despite the name, this option can select both "SSL" and "TLS" protocols.

バージョン 3.6 で追加.

ssl.PROTOCOL_TLS_CLIENT

Auto-negotiate the highest protocol version like PROTOCOL_TLS, but only support client-side SSLSocket connections. The protocol enables CERT_REQUIRED and check_hostname by default.

バージョン 3.6 で追加.

ssl.PROTOCOL_TLS_SERVER

Auto-negotiate the highest protocol version like PROTOCOL_TLS, but only support server-side SSLSocket connections.

バージョン 3.6 で追加.

ssl.PROTOCOL_SSLv23

data:PROTOCOL_TLS のエイリアスです。

バージョン 3.6 で非推奨: 代わりに PROTOCOL_TLS を使用してください。

ssl.PROTOCOL_SSLv2

チャンネル暗号化プロトコルとして SSL バージョン2を選択します。

このプロトコルは、 OpenSSL が OPENSSL_NO_SSL2 フラグが有効な状態でコンパイルされている場合には利用できません。

警告

SSL version 2 は非セキュアです。このプロトコルは強く非推奨です。

バージョン 3.6 で非推奨: OpenSSL は SSLv2 へのサポートを打切りました。

ssl.PROTOCOL_SSLv3

チャンネル暗号化プロトコルとしてSSLバージョン3を選択します。

このプロトコルは、 OpenSSL が OPENSSL_NO_SSLv3 フラグが有効な状態でコンパイルされている場合には利用できません。

警告

SSL version 3 は非セキュアです。このプロトコルは強く非推奨です。

バージョン 3.6 で非推奨: OpenSSL は全てのバージョン固有のプロトコルを廃止しました。デフォルトプロトコルの PROTOCOL_TLS に OP_NO_SSLv3 などのフラグをつけて使用してください。

ssl.PROTOCOL_TLSv1

チャンネル暗号化プロトコルとしてTLSバージョン1.0を選択します。

バージョン 3.6 で非推奨: OpenSSL は全てのバージョン固有のプロトコルを廃止しました。デフォルトプロトコルの PROTOCOL_TLS に OP_NO_SSLv3 などのフラグをつけて使用してください。

ssl.PROTOCOL_TLSv1_1

チャンネル暗号化プロトコルとしてTLSバージョン1.1を選択します。 openssl version 1.0.1+ のみで利用可能です。

バージョン 3.4 で追加.

バージョン 3.6 で非推奨: OpenSSL は全てのバージョン固有のプロトコルを廃止しました。デフォルトプロトコルの PROTOCOL_TLS に OP_NO_SSLv3 などのフラグをつけて使用してください。

ssl.PROTOCOL_TLSv1_2

チャンネル暗号化プロトコルとしてTLSバージョン1.2を選択します。これは最も現代的で、接続の両サイドが利用できる場合は、たぶん最も安全な選択肢です。 openssl version 1.0.1+ のみで利用可能です。

バージョン 3.4 で追加.

バージョン 3.6 で非推奨: OpenSSL は全てのバージョン固有のプロトコルを廃止しました。デフォルトプロトコルの PROTOCOL_TLS に OP_NO_SSLv3 などのフラグをつけて使用してください。

ssl.OP_ALL

相手にする SSL 実装のさまざまなバグを回避するためのワークアラウンドを有効にします。このオプションはデフォルトで有効です。これを有効にする場合 OpenSSL 用の同じ意味のフラグ SSL_OP_ALL をセットする必要はありません。

バージョン 3.2 で追加.

ssl.OP_NO_SSLv2

SSLv2 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして SSLv2 を選択しないようにします。

バージョン 3.2 で追加.

バージョン 3.6 で非推奨: SSLv2 は非推奨です

ssl.OP_NO_SSLv3

SSLv3 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして SSLv3 を選択しないようにします。

バージョン 3.2 で追加.

バージョン 3.6 で非推奨: SSLv3 は非推奨です

ssl.OP_NO_TLSv1

TLSv1 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして TLSv1 を選択しないようにします。

バージョン 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 以降でのみ利用できます。

バージョン 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 以降でのみ利用できます。

バージョン 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.

バージョン 3.7 で追加.

バージョン 3.7 で非推奨: The option is deprecated since OpenSSL 1.1.0. It was added to 2.7.15, 3.6.3 and 3.7.0 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.

This option is only available with OpenSSL 1.1.0h and later.

バージョン 3.7 で追加.

ssl.OP_CIPHER_SERVER_PREFERENCE

暗号の優先順位として、クライアントのものではなくサーバのものを使います。このオプションはクライアントソケットと SSLv2 のサーバソケットでは効果はありません。

バージョン 3.3 で追加.

ssl.OP_SINGLE_DH_USE

SSL セッションを区別するのに同じ DH 鍵を再利用しないようにします。これはセキュリティを向上させますが、より多くの計算機リソースを必要とします。このオプションはサーバソケットに適用されます。

バージョン 3.3 で追加.

ssl.OP_SINGLE_ECDH_USE

SSL セッションを区別するのに同じ ECDH 鍵を再利用しないようにします。これはセキュリティを向上させますが、より多くの計算機リソースを必要とします。このオプションはサーバソケットに適用されます。

バージョン 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.

This option is only available with OpenSSL 1.1.1 and later.

バージョン 3.8 で追加.

ssl.OP_NO_COMPRESSION

SSL チャネルでの圧縮を無効にします。これはアプリケーションのプロトコルが自身の圧縮方法をサポートする場合に有用です。

このオプションは OpenSSL 1.0.0以降のみで使用できます。

バージョン 3.3 で追加.

class ssl.Options

OP_* 定数の enum.IntFlag コレクションです。

ssl.OP_NO_TICKET

クライアントサイドがセッションチケットをリクエストしないようにします。

バージョン 3.6 で追加.

ssl.HAS_ALPN

OpenSSL ライブラリが、組み込みで RFC 7301 で記述されている Application-Layer Protocol Negotiation TLS 拡張をサポートしているかどうか。

バージョン 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.

バージョン 3.7 で追加.

ssl.HAS_ECDH

Whether the OpenSSL library has built-in support for the Elliptic Curve-based Diffie-Hellman key exchange. This should be true unless the feature was explicitly disabled by the distributor.

バージョン 3.3 で追加.

ssl.HAS_SNI

Whether the OpenSSL library has built-in support for the Server Name Indication extension (as defined in RFC 6066).

バージョン 3.2 で追加.

ssl.HAS_NPN

Whether the OpenSSL library has built-in support for the Next Protocol Negotiation as described in the Application Layer Protocol Negotiation. When true, you can use the SSLContext.set_npn_protocols() method to advertise which protocols you want to support.

バージョン 3.3 で追加.

ssl.HAS_SSLv2

Whether the OpenSSL library has built-in support for the SSL 2.0 protocol.

バージョン 3.7 で追加.

ssl.HAS_SSLv3

Whether the OpenSSL library has built-in support for the SSL 3.0 protocol.

バージョン 3.7 で追加.

ssl.HAS_TLSv1

Whether the OpenSSL library has built-in support for the TLS 1.0 protocol.

バージョン 3.7 で追加.

ssl.HAS_TLSv1_1

Whether the OpenSSL library has built-in support for the TLS 1.1 protocol.

バージョン 3.7 で追加.

ssl.HAS_TLSv1_2

Whether the OpenSSL library has built-in support for the TLS 1.2 protocol.

バージョン 3.7 で追加.

ssl.HAS_TLSv1_3

Whether the OpenSSL library has built-in support for the TLS 1.3 protocol.

バージョン 3.7 で追加.

ssl.CHANNEL_BINDING_TYPES

サポートされている TLS のチャネルバインディングのタイプのリスト。リスト内の文字列は SSLSocket.get_channel_binding() の引数に渡せます。

バージョン 3.3 で追加.

ssl.OPENSSL_VERSION

インタプリタによってロードされた OpenSSL ライブラリのバージョン文字列:

>>> ssl.OPENSSL_VERSION
'OpenSSL 1.0.2k  26 Jan 2017'

バージョン 3.2 で追加.

ssl.OPENSSL_VERSION_INFO

OpenSSL ライブラリのバージョン情報を表す5つの整数のタプル:

>>> ssl.OPENSSL_VERSION_INFO
(1, 0, 2, 11, 15)

バージョン 3.2 で追加.

ssl.OPENSSL_VERSION_NUMBER

1つの整数の形式の、 OpenSSL ライブラリの生のバージョン番号:

>>> ssl.OPENSSL_VERSION_NUMBER
268443839
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x100020bf'

バージョン 3.2 で追加.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE
ssl.ALERT_DESCRIPTION_INTERNAL_ERROR
ALERT_DESCRIPTION_*

RFC 5246 その他からのアラートの種類です。 IANA TLS Alert Registry にはこのリストとその意味が定義された RFC へのリファレンスが含まれています。

SSLContext.set_servername_callback() でのコールバック関数の戻り値として使われます。

バージョン 3.4 で追加.

class ssl.AlertDescription

ALERT_DESCRIPTION_* 定数の enum.IntEnum コレクションです。

バージョン 3.6 で追加.

Purpose.SERVER_AUTH

create_default_context() と SSLContext.load_default_certs() に渡すオプションです。この値はコンテキストが Web サーバの認証に使われることを示します (ですので、クライアントサイドのソケットを作るのに使うことになるでしょう)。

バージョン 3.4 で追加.

Purpose.CLIENT_AUTH

create_default_context() と SSLContext.load_default_certs() に渡すオプションです。この値はコンテキストが Web クライアントの認証に使われることを示します (ですので、サーバサイドのソケットを作るのに使うことになるでしょう)。

バージョン 3.4 で追加.

class ssl.SSLErrorNumber

SSL_ERROR_* 定数の enum.IntEnum コレクションです。

バージョン 3.6 で追加.

class ssl.TLSVersion

enum.IntEnum collection of SSL and TLS versions for SSLContext.maximum_version and SSLContext.minimum_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.

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レベルのソケットの仕様から逸脱することがあります。特に ノンブロッキングソケットについての注釈 を参照してください。

Instances of SSLSocket must be created using the SSLContext.wrap_socket() method.

バージョン 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.

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 send to the peer.

SSLSocket.getpeercert(binary_form=False)

接続先に証明書が無い場合、 None を返します。SSL ハンドシェイクがまだ行われていない場合は、 ValueError が送出されます。

binary_form が False で接続先から証明書を取得した場合、このメソッドは dict のインスタンスを返します。証明書が認証されていない場合、辞書は空です。証明書が認証されていた場合いくつかのキーを持った辞書を返し、 subject (証明書が発行された principal), issuer (証明書を発行した principal) を含みます。証明書が Subject Alternative Name 拡張( RFC 3280 を参照)のインスタンスを格納していた場合、 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}

注釈

特定のサービスのために証明書の検証がしたければ、 match_hostname() 関数を使うことができます。

binary_form 引数が True だった場合、証明書が渡されていればこのメソッドはDERエンコードされた証明書全体をバイト列として返し、接続先が証明書を提示しなかった場合は None を返します。接続先が証明書を提供するかどうかは SSL ソケットの役割に依存します:

  • クライアント SSL ソケットでは、認証が要求されているかどうかに関わらず、サーバは常に証明書を提供します。
  • サーバ SSL ソケットでは、クライアントはサーバによって認証が要求されている場合にのみ証明書を提供します。したがって、 (CERT_OPTIONAL や CERT_REQUIRED ではなく) CERT_NONE を使用した場合 getpeercert() は None を返します。

バージョン 3.2 で変更: 返される辞書に issuer, notBefore のような追加アイテムを含むようになりました。

バージョン 3.4 で変更: ハンドシェイクが済んでいなければ ValueError を投げるようになりました。返される辞書に crlDistributionPoints, caIssuers, OCSP URI のような X509v3 拡張アイテムを含むようになりました。

SSLSocket.cipher()

利用されている暗号の名前、その暗号の利用を定義しているSSLプロトコルのバージョン、利用されている鍵のbit長の3つの値を含むタプルを返します。もし接続が確立されていない場合、 None を返します。

SSLSocket.shared_ciphers()

ハンドシェイク中にクライアントにより共有される暗号方式のリストを返します。返されるリストの各要素は 3つの値を含むタプルで、その値はそれぞれ、暗号方式の名前、その暗号の利用を定義している SSL プロトコルのバージョン、暗号で使用される秘密鍵のビット長です。接続が確立されていないか、ソケットがクライアントソケットである場合、meth:~SSLSocket.shared_ciphers は None を返します。

バージョン 3.5 で追加.

SSLSocket.compression()

使われている圧縮アルゴリズムを文字列で返します。接続が圧縮されていなければ None を返します。

上位レベルのプロトコルが自身で圧縮メカニズムをサポートする場合、SSL レベルでの圧縮を OP_NO_COMPRESSION を使って無効にできます。

バージョン 3.3 で追加.

SSLSocket.get_channel_binding(cb_type="tls-unique")

現在の接続におけるチャネルバインディングのデータを取得します。未接続あるいはハンドシェイクが完了していなければ None を返します。

cb_type パラメータにより、望みのチャネルバインディングのタイプを選択できます。チャネルバインディングのタイプの妥当なものは CHANNEL_BINDING_TYPES でリストされています。現在のところは RFC 5929 で定義されている 'tls-unique' のみがサポートされています。未サポートのチャネルバインディングのタイプが要求された場合、 ValueError を送出します。

バージョン 3.3 で追加.

SSLSocket.selected_alpn_protocol()

TLS ハンドシェイクで選択されたプロトコルを返します。 SSLContext.set_alpn_protocols() が呼ばれていない場合、相手側が ALPN をサポートしていない場合、クライアントが提案したプロトコルのどれもソケットがサポートしない場合、あるいはハンドシェイクがまだ行われていない場合には、 None が返されます。

バージョン 3.5 で追加.

SSLSocket.selected_npn_protocol()

TLS/SSL ハンドシェイクで選択された上位レベルのプロトコルを返します。 SSLContext.set_npn_protocols() が呼ばれていない場合、相手側が NPN をサポートしていない場合、あるいはハンドシェイクがまだ行われていない場合には、 None が返されます。

バージョン 3.3 で追加.

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.

バージョン 3.7.1 で追加.

注釈

Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3 support, the method raises NotImplementedError.

SSLSocket.version()

コネクションによって実際にネゴシエイトされた SSL プロトコルバージョンを文字列で、または、セキュアなコネクションが確立していなければ None を返します。これを書いている時点では、 "SSLv2", "SSLv3", "TLSv1", "TLSv1.1", "TLSv1.2" などが返ります。最新の OpenSSL はもっと色々な値を定義しているかもしれません。

バージョン 3.5 で追加.

SSLSocket.pending()

接続において既に復号済みで読み出し可能で保留になっているバイト列の数を返します。

SSLSocket.context

The SSLContext object this SSL socket is tied to. If the SSL socket was created using the deprecated wrap_socket() function (rather than SSLContext.wrap_socket()), this is a custom context object created for this SSL socket.

バージョン 3.2 で追加.

SSLSocket.server_side

サーバサイドのソケットに対して True 、クライアントサイドのソケットに対して False となる真偽値です。

バージョン 3.2 で追加.

SSLSocket.server_hostname

サーバのホスト名: str 型、またはサーバサイドのソケットの場合とコンストラクタで hostname が指定されなかった場合は None

バージョン 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() が呼ばれる前に設定して、セッションを再利用できます。

バージョン 3.6 で追加.

SSLSocket.session_reused

バージョン 3.6 で追加.

SSL コンテキスト

バージョン 3.2 で追加.

SSL コンテキストは、SSL 構成オプション、証明書(群)や秘密鍵(群)などのような、一回の SSL 接続よりも長生きするさまざまなデータを保持します。これはサーバサイドソケットの SSL セッションのキャッシュも管理し、同じクライアントからの繰り返しの接続時の速度向上に一役買います。

class ssl.SSLContext(protocol=PROTOCOL_TLS)

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 で変更: このコンテキストは、安全性の高いデフォルト値で作成されます。デフォルト設定されるオプションは、 OP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE, OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE, OP_NO_SSLv2 (PROTOCOL_SSLv2 以外), OP_NO_SSLv3 (PROTOCOL_SSLv3 以外) です。初期の暗号方式スイートリストには HIGH 暗号のみが含まれており、 NULL 暗号および MD5 暗号は含まれません (PROTOCOL_SSLv2 以外)。

SSLContext オブジェクトは以下のメソッドと属性を持っています:

SSLContext.cert_store_stats()

ロードされた X.509 証明書の数、CA 証明書で活性の X.509 証明書の数、証明書失効リストの数、についての統計情報を辞書として取得します。

一つの CA と他の一つの証明書を持ったコンテキストでの例です:

>>> context.cert_store_stats()
{'crl': 0, 'x509_ca': 1, 'x509': 2}

バージョン 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 証明書をロードするかもしれません。

purpose フラグでどの種類の CA 証明書をロードするかを指定します。デフォルトの Purpose.SERVER_AUTH は TLS web サーバの認証のために活性かつ信頼された証明書をロードします(クライアントサイドのソケット)。 Purpose.CLIENT_AUTH はクライアント証明書の正当性検証をサーバサイドで行うための CA 証明書をロードします。

バージョン 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 証明書が結合されたファイルへのパスを指定してください。このファイル内で証明書をどのように編成すれば良いのかについての詳しい情報については、 証明書 の議論を参照してください。

The capath string, if present, is the path to a directory containing several CA certificates in PEM format, following an OpenSSL specific layout.

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 ディレクトリ内の証明書は一度でも使われない限りはロードされません。

バージョン 3.4 で追加.

SSLContext.get_ciphers()

有効な暗号化のリストを取得します。リストは暗号化優先度順に並びます。SSLContext.set_ciphers() を参照してください。

以下はプログラム例です:

>>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
>>> ctx.get_ciphers()  # OpenSSL 1.0.x
[{'alg_bits': 256,
  'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(256) Mac=AEAD',
  'id': 50380848,
  'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  'protocol': 'TLSv1/SSLv3',
  'strength_bits': 256},
 {'alg_bits': 128,
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'id': 50380847,
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1/SSLv3',
  'strength_bits': 128}]

OpenSSL 1.1 以降では、暗号化辞書に以下のフィールドが追加されました。

>>> ctx.get_ciphers()  # OpenSSL 1.1+
[{'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'}]

Availability: OpenSSL 1.0.2+.

バージョン 3.6 で追加.

SSLContext.set_default_verify_paths()

デフォルトの "認証局" (CA=certification authority) 証明書を、OpenSSL ライブラリがビルドされた際に定義されたファイルシステム上のパスからロードします。残念ながらこのメソッドが成功したかどうかを知るための簡単な方法はありません: 証明書が見つからなくてもエラーは返りません。OpenSSL ライブラリがオペレーティングシステムの一部として提供されている際にはどうやら適切に構成できるようですが。

SSLContext.set_ciphers(ciphers)

Set the available ciphers for sockets created with this context. It should be a string in the OpenSSL cipher list format. If no cipher can be selected (because compile-time options or other configuration forbids use of all the specified ciphers), an SSLError will be raised.

注釈

接続時に SSL ソケットの SSLSocket.cipher() メソッドが、現在選択されているその暗号を使います。

OpenSSL 1.1.1 has TLS 1.3 cipher suites enabled by default. The suites cannot be disabled with set_ciphers().

SSLContext.set_alpn_protocols(protocols)

SSL/TLS ハンドシェイク時にソケットが提示すべきプロトコルを指定します。 ['http/1.1', 'spdy/2'] のような推奨順に並べた ASCII 文字列のリストでなければなりません。プロトコルの選択は RFC 7301 に従いハンドシェイク中に行われます。ハンドシェイクが正常に終了した後、 SSLSocket.selected_alpn_protocol() メソッドは合意されたプロトコルを返します。

このメソッドは HAS_ALPN が偽の場合 NotImplementedError を送出します。

OpenSSL 1.1.0 to 1.1.0e will abort the handshake and raise SSLError when both sides support ALPN but cannot agree on a protocol. 1.1.0f+ behaves like 1.0.2, SSLSocket.selected_alpn_protocol() returns None.

バージョン 3.5 で追加.

SSLContext.set_npn_protocols(protocols)

Specify which protocols the socket should advertise during the SSL/TLS handshake. It should be a list of strings, like ['http/1.1', 'spdy/2'], ordered by preference. The selection of a protocol will happen during the handshake, and will play out according to the Application Layer Protocol Negotiation. After a successful handshake, the SSLSocket.selected_npn_protocol() method will return the agreed-upon protocol.

このメソッドは HAS_NPN が偽の場合 NotImplementedError を送出します。

バージョン 3.3 で追加.

SSLContext.sni_callback

TLS クライアントがサーバ名表示を指定した際の、SSL/TLS サーバによって TLS Client Hello ハンドシェイクメッセージが受け取られたあとで呼び出されるコールバック関数を登録します。サーバ名表示メカニズムは RFC 6066 セクション 3 - Server Name Indication で述べられています。

Only one callback can be set per SSLContext. If sni_callback is set to None then the callback is disabled. Calling this function a subsequent time will disable the previously registered callback.

The callback function will be called with three arguments; the first being the 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 オブジェクトに変更することです。

TLS 接続の初期ネゴシエーションのフェーズなので、 SSLSocket.selected_alpn_protocol(), SSLSocket.context のような限られたメソッドと属性のみ使えます。 SSLSocket.getpeercert(), SSLSocket.getpeercert(), SSLSocket.cipher(), SSLSocket.compress() メソッドは TLS 接続が TLS Client Hello よりも先に進行していることを必要としますから、これらは意味のある値を返しませんし、安全に呼び出すこともできません。

The sni_callback function must return None to allow the TLS negotiation to continue. If a TLS failure is required, a constant ALERT_DESCRIPTION_* can be returned. Other return values will result in a TLS fatal error with ALERT_DESCRIPTION_INTERNAL_ERROR.

If an exception is raised from the sni_callback function the TLS connection will terminate with a fatal TLS alert message ALERT_DESCRIPTION_HANDSHAKE_FAILURE.

このメソッドは OpenSSL ライブラリが OPENSSL_NO_TLSEXT を定義してビルドされている場合、 NotImplementedError を送出します。

バージョン 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").

If there is an decoding error on the server name, the TLS connection will terminate with an ALERT_DESCRIPTION_INTERNAL_ERROR fatal TLS alert message to the client.

バージョン 3.4 で追加.

SSLContext.load_dh_params(dhfile)

Load the key generation parameters for Diffie-Hellman (DH) key exchange. Using DH key exchange improves forward secrecy at the expense of computational resources (both on the server and on the client). The dhfile parameter should be the path to a file containing DH parameters in PEM format.

この設定はクライアントソケットには適用されません。さらにセキュリティを改善するのに OP_SINGLE_DH_USE オプションも利用できます。

バージョン 3.3 で追加.

SSLContext.set_ecdh_curve(curve_name)

楕円曲線ディフィー・ヘルマン(ECDH)鍵交換の曲線名を指定します。ECDH はもとの DH に較べて、ほぼ間違いなく同程度に安全である一方で、顕著に高速です。 curve_name パラメータは既知の楕円曲線を表す文字列でなければなりません。例えば prime256v1 が広くサポートされている曲線です。

この設定はクライアントソケットには適用されません。さらにセキュリティを改善するのに OP_SINGLE_ECDH_USE オプションも利用できます。

このメソッドは HAS_ECDH が False の場合は利用できません。

バージョン 3.3 で追加.

参考

SSL/TLS & 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 引数は真偽値で、このソケットがサーバサイドとクライアントサイドのどちらの動作をするのかを指定します。

For client-side sockets, the context construction is lazy; if the underlying socket isn't connected yet, the context construction will be performed after connect() is called on the socket. For server-side sockets, if the socket has no remote peer, it is assumed to be a listening socket, and the server-side SSL wrapping is automatically performed on client connections accepted via the accept() method. The method may raise 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 を参照してください。

バージョン 3.5 で変更: OpenSSL が SNI をサポートしなくても server_hostname を許容するようになりました。

バージョン 3.6 で変更: session 引数が追加されました。

バージョン 3.7 で変更: The method returns on instance of SSLContext.sslsocket_class instead of hard-coded SSLSocket.

SSLContext.sslsocket_class

The return type of SSLContext.wrap_sockets(), defaults to SSLSocket. The attribute can be overridden on instance of class in order to return a custom subclass of SSLSocket.

バージョン 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 attr: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 on 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.

バージョン 3.7 で追加.

SSLContext.session_stats()

Get statistics about the SSL sessions created or managed by this context. A dictionary is returned which maps the names of each piece of information to their numeric values. For example, here is the total number of hits and misses in the session cache since the context was created:

>>> stats = context.session_stats()
>>> stats['hits'], stats['misses']
(0, 0)
SSLContext.check_hostname

Whether to match the peer cert's hostname with match_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.

以下はプログラム例です:

import socket, ssl

context = ssl.SSLContext()
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))

バージョン 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.

注釈

この機能にはOpenSSL0.9.8f以降が必要です。

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.

注釈

This attribute is not available unless the ssl module is compiled with OpenSSL 1.1.0g or newer.

SSLContext.minimum_version

Like SSLContext.maximum_version except it is the lowest supported version or TLSVersion.MINIMUM_SUPPORTED.

注釈

This attribute is not available unless the ssl module is compiled with OpenSSL 1.1.0g or newer.

SSLContext.options

このコンテキストで有効になっている SSL オプションを表す整数。デフォルトの値は OP_ALL ですが、 OP_NO_SSLv2 のような他の値をビット OR 演算で指定できます。

注釈

With versions of OpenSSL older than 0.9.8m, it is only possible to set options, not to clear them. Attempting to clear an option (by resetting the corresponding bits) will raise a ValueError.

バージョン 3.6 で変更: SSLContext.options は次のように Options のフラグを返します。

>>> ssl.create_default_context().options  # doctest: +SKIP
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>
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.

バージョン 3.7.1 で追加.

注釈

Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3 support, the property value is None and can't be modified

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

バージョン 3.7 で追加.

注釈

Only writeable with OpenSSL 1.1.0 or higher.

SSLContext.verify_flags

証明書の検証操作のためのフラグです。 VERIFY_CRL_CHECK_LEAF などのフラグをビット OR 演算でセットできます。デフォルトでは OpenSSL は証明書失効リスト (CRLs) を必要としませんし検証にも使いません。openssl version 0.9.8+ でのみ利用可能です。

バージョン 3.4 で追加.

バージョン 3.6 で変更: SSLContext.verify_flags は次のように VerifyFlags のフラグを返します。

>>> ssl.create_default_context().verify_flags  # doctest: +SKIP
<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つの鍵は関連しており、片方の鍵で暗号化したメッセージは、もう片方の鍵 のみ で復号できます。

A certificate contains information about two principals. It contains the name of a subject, and the subject's public key. It also contains a statement by a second principal, the issuer, that the subject is who they claim to be, and that this is indeed the subject's public key. The issuer's statement is signed with the issuer's private key, which only the issuer knows. However, anyone can verify the issuer's statement by finding the issuer's public key, decrypting the statement with it, and comparing it to the other information in the certificate. The certificate also contains information about the time period over which it is valid. This is expressed as two fields, called "notBefore" and "notAfter".

Python において証明書を利用する場合、クライアントもサーバーも自分を証明するために証明書を利用することができます。ネットワーク接続の相手側に証明書の提示を要求する事ができ、そのクライアントやサーバーが認証を必要とするならその証明書を認証することができます。認証が失敗した場合、接続は例外を発生させます。認証は下位層のOpenSSLフレームワークが自動的に行います。アプリケーションは認証機構について意識する必要はありません。しかし、アプリケーションは認証プロセスのために幾つかの証明書を提供する必要があるかもしれません。

Python は証明書を格納したファイルを利用します。そのファイルは "PEM" ( RFC 1422 参照) フォーマットという、ヘッダー行とフッター行の間に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() によって自動的に行われます。

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

多くの場合、証明書と同じファイルに秘密鍵も格納されています。この場合、 SSLContext.load_cert_chain(), wrap_socket() には certfile 引数だけが必要とされます。秘密鍵が証明書ファイルに格納されている場合、秘密鍵は証明書チェインの最初の証明書よりも先にないといけません。

-----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()
>>> context.verify_mode = ssl.CERT_REQUIRED
>>> context.check_hostname = True
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

(このスニペットはすべての CA 証明書が /etc/ssl/certs/ca-bundle.crt にバンドルされていることを仮定しています; もし違っていればエラーになりますので、適宜修正してください)

サーバへの接続にこのコンテキストを使うと、 CERT_REQUIRED でサーバの証明書の検証が行われます: サーバの証明書が CA 証明書のいずれかに署名されていて、その署名が正しいことを保障します。

>>> 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.mydomain.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 サポート

バージョン 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」オブジェクトを通じて実行する必要があります。

This class has no public constructor. An SSLObject instance must be created using the wrap_bio() method. This method will create the SSLObject instance and bind it to a pair of BIOs. The incoming BIO is used to pass data from Python to the SSL protocol instance, while the outgoing BIO is used to pass data the other way around.

次のメソッドがサポートされています:

  • context
  • server_side
  • server_hostname
  • session
  • session_reused
  • read()
  • write()
  • getpeercert()
  • selected_npn_protocol()
  • cipher()
  • shared_ciphers()
  • compression()
  • pending()
  • do_handshake()
  • unwrap()
  • get_channel_binding()

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 を送出します。
  • wrap_socket() に対して存在するような、モジュールレベルの wrap_bio() 呼び出しは存在しません。SSLObject は、常に SSLContext を経由して作成されます。

バージョン 3.7 で変更: SSLObject instances must to 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 セッション

バージョン 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 コンテキストを作ると、デフォルトでは証明書検証もホスト名チェックも有効になりません。自分で設定を行う場合は、十分なセキュリティレベルを達成するために、以下のパラグラフをお読みください。

手動での設定

証明書の検証

SSLContext のコンストラクタを直接呼び出した場合、 CERT_NONE がデフォルトとして使われます。これは接続先の身元特定をしないので安全ではありませんし、特にクライアントモードでは大抵相手となるサーバの信憑性を保障したいでしょう。ですから、クライアントモードでは CERT_REQUIRED を強くお勧めします。ですが、それだけでは不十分です; SSLSocket.getpeercert() を呼び出してサーバ証明書が望んだサービスと合致するかのチェックもしなければなりません。多くのプロトコルとアプリケーションにとって、サービスはホスト名で特定されます; この場合、 match_hostname() が使えます。これらの共通的なチェックは SSLContext.check_hostname が有効な場合、自動的に行われます。

バージョン 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.options |= ssl.OP_NO_TLSv1
>>> client_context.options |= ssl.OP_NO_TLSv1_1

上記で作成した SSL コンテキストは、TLSv1.2 以降 (システムでサポートされている場合) でのサーバへの接続のみを許可します。PROTOCOL_TLS_CLIENT は、デフォルトで証明書の検証とホスト名のチェックを意味します。コンテキスト中に証明書をロードする必要があります。

暗号の選択

If you have advanced security requirements, fine-tuning of the ciphers enabled when negotiating a SSL session is possible through the SSLContext.set_ciphers() method. Starting from Python 3.2.3, the ssl module disables certain weak ciphers by default, but you may want to further restrict the cipher choice. Be sure to read OpenSSL's documentation about the cipher list format. If you want to check which ciphers are enabled by a given cipher list, use SSLContext.get_ciphers() or the openssl ciphers command on your system.

マルチプロセス化

(例えば multiprocessing や concurrent.futures を使って、)マルチプロセスアプリケーションの一部としてこのモジュールを使う場合、OpenSSL の内部の乱数発生器は fork したプロセスを適切に処理しないことに気を付けて下さい。SSL の機能を os.fork() とともに使う場合、アプリケーションは親プロセスの PRNG 状態を変更しなければなりません。 RAND_add(), RAND_bytes(), RAND_pseudo_bytes() のいずれかの呼び出し成功があれば十分です。

TLS 1.3

バージョン 3.7 で追加.

Python has provisional and experimental support for TLS 1.3 with OpenSSL 1.1.1. The new 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.

LibreSSL support

LibreSSL is a fork of OpenSSL 1.0.1. The ssl module has limited support for LibreSSL. Some features are not available when the ssl module is compiled with LibreSSL.

  • LibreSSL >= 2.6.1 no longer supports NPN. The methods SSLContext.set_npn_protocols() and SSLSocket.selected_npn_protocol() are not available.
  • SSLContext.set_default_verify_paths() ignores the env vars SSL_CERT_FILE and SSL_CERT_PATH although get_default_verify_paths() still reports them.

参考

socket.socket クラス
下位レイヤーの socket クラスのドキュメント
SSL/TLS Strong Encryption: An Introduction
Intro from the Apache HTTP Server documentation
RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management
Steve Kent
RFC 4086: Randomness Requirements for Security
Donald E., Jeffrey I. Schiller
RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
D. Cooper
RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2
T. Dierks et. al.
RFC 6066: Transport Layer Security (TLS) Extensions
D. Eastlake
IANA TLS: Transport Layer Security (TLS) Parameters
IANA
RFC 7525: Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)
IETF
Mozilla's Server Side TLS recommendations
Mozilla

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Networking and Interprocess Communication »


select --- I/O 処理の完了を待機する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »

select --- I/O 処理の完了を待機する

このモジュールでは、ほとんどのオペレーティングシステムで利用可能な select() および poll() 関数、Solaris やその派生で利用可能な devpoll() 、Linux 2.5+ で利用可能な epoll() 、多くのBSDで利用可能な kqueue() 関数に対するアクセスを提供しています。 Windows 上ではソケットに対してしか動作しないので注意してください; その他のオペレーティングシステムでは、他のファイル形式でも (特に Unixではパイプにも) 動作します。通常のファイルに対して適用し、最後にファイルを読み出した時から内容が増えているかを決定するために使うことはできません。

注釈

selectors モジュールにより、select モジュールプリミティブに基づく高水準かつ効率的な I/O の多重化が行うことが出来ます。 OS レベルプリミティブを使用した正確な制御を求めない限り、このモジュールの使用が推奨されます。

このモジュールは以下を定義します:

exception select.error

OSError の非推奨のエイリアスです。

バージョン 3.3 で変更: PEP 3151 に基づき、このクラスは OSError のエイリアスになりました。

select.devpoll()

(Solaris およびその派生でのみサポートされています) /dev/poll ポーリングオブジェクトを返します。 ポーリングオブジェクトが提供しているメソッドについては ポーリングオブジェクト 節を参照してください。

devpoll() オブジェクトはインスタンス化時に許されるファイル記述子の数にリンクされます。
プログラムがこの値を減らす場合 devpoll() は失敗します。
プログラムがこの値を増やす場合 devpoll() は有効なファイル記述子の不完全なリストを返すことがあります。

新しいファイル記述子は 継承不可 です。

バージョン 3.3 で追加.

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

select.epoll(sizehint=-1, flags=0)

(Only supported on Linux 2.5.44 and newer.) Return an edge polling object, which can be used as Edge or Level Triggered interface for I/O events.

sizehint informs epoll about the expected number of events to be registered. It must be positive, or -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])

Unix の select() システムコールに対する直接的なインタフェースです。最初の 3 つの引数は '待機可能オブジェクト' からなるシーケンスです: 待機可能オブジェクトとは、ファイル記述子を表す整数値か、そのような整数を返す引数なしメソッド fileno() を持つオブジェクトです。

  • 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() メソッドを持つ必要があります。

注釈

select() は Windows のファイルオブジェクトを受理しませんが、ソケットは受理します。 Windows では、背後の select() 関数は WinSock ライブラリで提供されており、 WinSock によって生成されたものではないファイル記述子を扱うことができないのです。

バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 InterruptedError を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。

select.PIPE_BUF

select(), poll() またはこのモジュールの別のインタフェースによってパイプが書き込む準備ができていると報告された時に、ブロックせずにパイプに書き込むことのできる最小のバイト数。これはソケットなどの他の種類の file-like オブジェクトには適用されません。

This value is guaranteed by POSIX to be at least 512.

Availability: Unix

バージョン 3.2 で追加.

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

Solaris とその派生は、/dev/poll を持っています。 select() が O(最大のファイル記述子) 、 poll() が O(ファイル記述子の数) である一方、 /dev/poll は O(アクティブなファイル記述子) です。

/dev/poll の挙動は標準的な poll() オブジェクトに非常に近いです。

devpoll.close()

ポーリングオブジェクトのファイル記述子を閉じます。

バージョン 3.4 で追加.

devpoll.closed

ポーリングオブジェクトが閉じている場合 True です。

バージョン 3.4 で追加.

devpoll.fileno()

ポーリングオブジェクトのファイル記述子番号を返します。

バージョン 3.4 で追加.

devpoll.register(fd[, eventmask])

ファイル記述子をポーリングオブジェクトに登録します。これ以降の poll() メソッド呼び出しでは、そのファイル記述子に処理待ち中の I/O イベントがあるかどうかを監視します。 fd は整数か、整数値を返す fileno() メソッドを持つオブジェクトを取ります。ファイルオブジェクトも fileno() を実装しているので、引数として使うことができます。

eventmask はオプションのビットマスクで、どの種類の I/O イベントを監視したいかを記述します。 poll() オブジェクトと同じ定数が使われます。デフォルト値は定数 POLLIN 、 POLLPRI 、および POLLOUT の組み合わせです。

警告

登録済みのファイル記述子を登録してもエラーにはなりませんが、結果は未定義です。適切なアクションは、最初に unregister するか modify することです。これは 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 を見てください)。

エッジおよびレベルトリガポーリング (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 | 無視される。
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 を削除します。

epoll.poll(timeout=-1, maxevents=-1)

イベントを待機します。timeout はタイムアウト時間で、単位は秒 (float型) です。

バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 InterruptedError を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。

ポーリングオブジェクト

poll() システムコールはほとんどの Unix システムでサポートされており、非常に多数のクライアントに同時にサービスを提供するようなネットワークサーバが高いスケーラビリティを持てるようにしています。 poll() は対象のファイル記述子を列挙するだけでよいため、良くスケールします。一方、 select() はビット対応表を構築し、対象ファイルの記述子に対応するビットを立て、その後全ての対応表の全てのビットを線形探索します。 select() は O(最大のファイル記述子番号) なのに対し、 poll() は O(対象とするファイル記述子の数) で済みます。

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 を見てください)。

kqueue オブジェクト

kqueue.close()

kqueue オブジェクトの制御用ファイル記述子を閉じる。

kqueue.closed

kqueue オブジェクトが閉じている場合 True です。

kqueue.fileno()

制御用ファイル記述子の番号を返します。

kqueue.fromfd(fd)

与えられたファイル記述子から、kqueue オブジェクトを作成する。

kqueue.control(changelist, max_events[, timeout=None]) → eventlist

kevent に対する低水準のインタフェース

  • changelist は kevent オブジェクトのイテラブルまたは None
  • max_events は 0 または正の整数
  • timeout はタイムアウト秒数 (float を利用可能)

バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 InterruptedError を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。

kevent オブジェクト

https://www.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 | ネットワークデバイス上のイベントを監視する (Mac OS X では利用不可)
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 フィルタフラグ (Mac OS X では利用不可):

定数 | 意味
KQ_NOTE_LINKUP | リンクアップしている
KQ_NOTE_LINKDOWN | リンクダウンしている
KQ_NOTE_LINKINV | リンク状態が不正
kevent.data

フィルタ固有のデータ。

kevent.udata

ユーザー定義値。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Networking and Interprocess Communication »


selectors --- 高水準の I/O 多重化

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »

selectors --- 高水準の I/O 多重化

バージョン 3.4 で追加.

ソースコード: Lib/selectors.py

はじめに

このモジュールにより、select モジュールプリミティブに基づく高水準かつ効率的な I/O の多重化が行えます。OS 水準のプリミティブを使用した正確な制御を求めない限り、このモジュールの使用が推奨されます。

このモジュールは BaseSelector 抽象基底クラスと、いくつかの具象実装 (KqueueSelector, EpollSelector...) を定義しており、これらは複数のファイルオブジェクトの I/O の準備状況の通知の待機に使用できます。以下では、 "ファイルオブジェクト" は、fileno() メソッドを持つあらゆるオブジェクトか、あるいは Raw ファイル記述子を意味します。ファイルオブジェクト を参照してください。

DefaultSelector は、現在のプラットフォームで利用できる、もっとも効率的な実装の別名になります: これはほとんどのユーザーにとってのデフォルトの選択になるはずです。

注釈

プラットフォームごとにサポートされているファイルオブジェクトのタイプは異なります: Windows ではソケットはサポートされますが、パイプはされません。Unix では両方がサポートされます (その他の fifo やスペシャルファイルデバイスなどのタイプもサポートされます)。

参考

select
低水準の I/O 多重化モジュールです。

クラス

クラス階層:

BaseSelector
+-- SelectSelector
+-- PollSelector
+-- EpollSelector
+-- DevpollSelector
+-- KqueueSelector

以下では、events は与えられたファイルオブジェクトを待機すべき I/O イベントを示すビット単位のマスクになります。これには以下のモジュール定数の組み合わせを設定できます:

定数 | 意味
EVENT_READ | 読み込み可能
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 を参照してください)。

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() オブジェクトが使用しているファイル記述子を返します。

バージョン 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)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Networking and Interprocess Communication »


asyncore --- 非同期ソケットハンドラ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »

asyncore --- 非同期ソケットハンドラ

ソースコード: Lib/asyncore.py

バージョン 3.6 で非推奨: 代わりに asyncio を使ってください。

注釈

このモジュールは後方互換性のためだけに存在します。新しいコードでは asyncio を利用することを推奨します。

このモジュールは、非同期ソケットサービスのクライアント・サーバを開発するための基盤として使われます。

CPUが一つしかない場合、プログラムが"二つのことを同時に"実行する方法は二つしかありません。もっとも簡単で一般的なのはマルチスレッドを利用する方法ですが、これとはまったく異なるテクニックで、一つのスレッドだけでマルチスレッドと同じような効果を得られるテクニックがあります。このテクニックはI/O処理が中心である場合にのみ有効で、CPU負荷の高いプログラムでは効果が無く、この場合にはプリエンプティブなスケジューリングが可能なスレッドが有効でしょう。しかし、多くの場合、ネットワークサーバではCPU負荷よりはIO負荷が問題となります。

もしOSのI/Oライブラリがシステムコール select() をサポートしている場合（ほとんどの場合はサポートされている）、I/O処理は"バックグラウンド"で実行し、その間に他の処理を実行すれば、複数の通信チャネルを同時にこなすことができます。一見、この戦略は奇妙で複雑に思えるかもしれませんが、いろいろな面でマルチスレッドよりも理解しやすく、制御も容易です。 asyncore は多くの複雑な問題を解決済みなので、洗練され、パフォーマンスにも優れたネットワークサーバとクライアントを簡単に開発することができます。とくに、 asynchat のような、対話型のアプリケーションやプロトコルには非常に有効でしょう。

基本的には、この二つのモジュールを使う場合は一つ以上のネットワーク チャネル を asyncore.dispatcher クラス、または asynchat.async_chat のインスタンスとして作成します。作成されたチャネルはグローバルマップに登録され、 loop() 関数で参照されます。 loop() には、専用の マップ を渡す事も可能です。

チャネルを生成後、 loop() を呼び出すとチャネル処理が開始し、最後のチャネル（非同期処理中にマップに追加されたチャネルを含む）が閉じるまで継続します。

asyncore.loop([timeout[, use_poll[, map[, count]]]])

ポーリングループを開始し、count 回が過ぎるか、全てのオープン済みチャネルがクローズされた場合のみ終了します。全ての引数はオプションです。引数 count のデフォルト値は None で、ループは全てのチャネルがクローズされた場合のみ終了します。引数 timeout は select() または poll() の引数 timeout として渡され、秒単位で指定します。デフォルト値は 30 秒です。引数 use_poll が真の場合、 select() ではなく poll() が使われます (デフォルト値は False です)。

引数 map には、監視するチャネルをアイテムとして格納した辞書を指定します。チャネルがクローズされた時に map からそのチャネルが削除されます。 map が省略された場合、グローバルなマップが使用されます。チャネル (asyncore.dispatcher, asynchat.async_chat とそのサブクラス) は自由に混ぜて map に入れることができます。

class asyncore.dispatcher

dispatcher クラスは、低レベルソケットオブジェクトの薄いラッパーです。便宜上、非同期ループから呼び出されるイベント処理メソッドを追加していますが、これ以外の点では、non-blockingなソケットと同様です。

非同期ループ内で低レベルイベントが発生した場合、発生のタイミングやコネクションの状態から特定の高レベルイベントへと置き換えることができます。例えばソケットを他のホストに接続する場合、最初の書き込み可能イベントが発生すれば接続が完了した事が分かります(この時点で、ソケットへの書き込みは成功すると考えられる)。このように判定できる高レベルイベントを以下に示します:

Event | 説明
handle_connect() | 最初にreadもしくはwriteイベントが発生した時
handle_close() | 読み込み可能なデータなしでreadイベントが発生した時
handle_accepted() | listen中のソケットでreadイベントが発生した時

非同期処理中、マップに登録されたチャネルの readable() メソッドと writable() メソッドが呼び出され、 select() か poll() でread/writeイベントを検出するリストに登録するか否かを判定します。

このようにして、チャネルでは低レベルなソケットイベントの種類より多くの種類のイベントを検出する事ができます。以下にあげるイベントは、サブクラスでオーバライドすることが可能です:

handle_read()

非同期ループで、チャネルのソケットの read() メソッドの呼び出しが成功した時に呼び出されます。

handle_write()

非同期ループで、書き込み可能ソケットが実際に書き込み可能になった時に呼び出されます。このメソッドでは、しばしばパフォーマンスの向上のために必要なバッファリングを実装します。例:

def handle_write(self):
    sent = self.send(self.buffer)
    self.buffer = self.buffer[sent:]
handle_expt()

out of band (OOB)データが検出された時に呼び出されます。OOBはあまりサポートされておらず、また滅多に使われないので、handle_expt() が呼び出されることはほとんどありません。

handle_connect()

ソケットの接続が確立した時に呼び出されます。"welcome"バナーの送信、プロトコルネゴシエーションの初期化などを行います。

handle_close()

ソケットが閉じた時に呼び出されます。

handle_error()

捕捉されない例外が発生した時に呼び出されます。デフォルトでは、短縮したトレースバック情報が出力されます。

handle_accept()

listen 中のチャネル (受動的にオープンしたもの) がリモートホストからの connect() で接続され、接続が確立した時に呼び出されます。 バージョン 3.2 で非推奨になりました; 代わりに handle_accepted() を使ってください。

バージョン 3.2 で非推奨.

handle_accepted(sock, addr)

listen 中のチャネル (受動的にオープンしたもの) がリモートホストからの connect() で接続され、接続が確立した時に呼び出されます。 sock はその接続でデータを送受信するのに使える 新しい ソケットオブジェクトで、 addr は接続の対向のソケットに bind されているアドレスです。

バージョン 3.2 で追加.

readable()

非同期ループ中に呼び出され、readイベントの監視リストに加えるか否かを決定します。デフォルトのメソッドでは True を返し、readイベントの発生を監視します。

writable()

非同期ループ中に呼び出され、writeイベントの監視リストに加えるか否かを決定します。デフォルトのメソッドでは True を返し、writeイベントの発生を監視します。

さらに、チャネルにはソケットのメソッドとほぼ同じメソッドがあり、チャネルはソケットのメソッドの多くを委譲・拡張しており、ソケットとほぼ同じメソッドを持っています。

create_socket(family=socket.AF_INET, type=socket.SOCK_STREAM)

引数も含め、通常のソケット生成と同一です。ソケットの生成については、 socket モジュールのドキュメントを参照してください。

バージョン 3.3 で変更: family 引数と type 引数が省略可能になりました。

connect(address)

通常のソケットオブジェクトと同様、address には一番目の値が接続先ホスト、2番目の値がポート番号であるタプルを指定します。

send(data)

リモート側の端点に data を送出します。

recv(buffer_size)

リモート側の端点より、最大 buffer_size バイトのデータを読み込みます。長さ0のバイト列オブジェクトが返ってきた場合、チャネルはリモートから切断された事を示します。

select.select() や select.poll() がソケットが読み込みできる状態にあると報告したとしても、 recv() が BlockingIOError を送出する場合があります。

listen(backlog)

ソケットへの接続を待ちます。引数 backlog は、キューに追加できるコネクションの最大数 (1 以上) を指定します。最大値はシステムに依存します（通常は5)。

bind(address)

ソケットを address にバインドします。ソケットはバインド済みであってはなりません。 (address の形式は、アドレスファミリに依存します。 socket モジュールを参照のこと。) ソケットを再利用可能にする (SO_REUSEADDR オプションを設定する) には、 dispatcher オブジェクトの set_reuse_addr() メソッドを呼び出してください。

accept()

接続を受け入れます。ソケットはアドレスにバインド済みであり、listen() で接続待ち状態でなければなりません。戻り値は None か (conn, address) のペアで、conn はデータの送受信を行う 新しい ソケットオブジェクト、address は接続先ソケットがバインドされているアドレスです。None が返された場合、接続が起こらなかったことを意味します。その場合、サーバーはこのイベントを無視して後続の接続を待ち続けるべきです。

close()

ソケットをクローズします。以降の全ての操作は失敗します。リモート端点では、キューに溜まったデータ以外、これ以降のデータ受信は行えません。ソケットはガベージコレクト時に自動的にクローズされます。

class asyncore.dispatcher_with_send

dispatcher のサブクラスで、シンプルなバッファされた出力機能を持ちます。シンプルなクライアントプログラムに適しています。もっと高レベルな場合には asynchat.async_chat を利用してください。

class asyncore.file_dispatcher

A file_dispatcher takes a file descriptor or file object along with an optional map argument and wraps it for use with the poll() or loop() functions. If provided a file object or anything with a fileno() method, that method will be called and passed to the file_wrapper constructor.

利用可能な環境: Unix。

class asyncore.file_wrapper

A file_wrapper takes an integer file descriptor and calls os.dup() to duplicate the handle so that the original handle may be closed independently of the file_wrapper. This class implements sufficient methods to emulate a socket for use by the file_dispatcher class.

利用可能な環境: Unix。

asyncoreの例: 簡単なHTTPクライアント

基本的なサンプルとして、以下に非常に単純なHTTPクライアントを示します。このHTTPクライアントは dispatcher クラスでソケットを利用しています:

import asyncore

class HTTPClient(asyncore.dispatcher):

    def __init__(self, host, path):
        asyncore.dispatcher.__init__(self)
        self.create_socket()
        self.connect( (host, 80) )
        self.buffer = bytes('GET %s HTTP/1.0\r\nHost: %s\r\n\r\n' %
                            (path, host), 'ascii')

    def handle_connect(self):
        pass

    def handle_close(self):
        self.close()

    def handle_read(self):
        print(self.recv(8192))

    def writable(self):
        return (len(self.buffer) > 0)

    def handle_write(self):
        sent = self.send(self.buffer)
        self.buffer = self.buffer[sent:]

client = HTTPClient('www.python.org', '/')
asyncore.loop()

基本的な echo サーバーの例

この例の基本的な echoサーバーは、 dispatcher を利用して接続を受けつけ、接続をハンドラーにディスパッチします:

import asyncore

class EchoHandler(asyncore.dispatcher_with_send):

    def handle_read(self):
        data = self.recv(8192)
        if data:
            self.send(data)

class EchoServer(asyncore.dispatcher):

    def __init__(self, host, port):
        asyncore.dispatcher.__init__(self)
        self.create_socket()
        self.set_reuse_addr()
        self.bind((host, port))
        self.listen(5)

    def handle_accepted(self, sock, addr):
        print('Incoming connection from %s' % repr(addr))
        handler = EchoHandler(sock)

server = EchoServer('localhost', 8080)
asyncore.loop()

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Networking and Interprocess Communication »


asynchat --- 非同期ソケットコマンド/レスポンスハンドラ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »

asynchat --- 非同期ソケットコマンド/レスポンスハンドラ

ソースコード: Lib/asynchat.py

バージョン 3.6 で非推奨: 代わりに asyncio を使ってください。

注釈

このモジュールは後方互換性のためだけに存在します。新しいコードでは asyncio を利用することを推奨します。

asynchat を使うと、 asyncore を基盤とした非同期なサーバ・クライアントをより簡単に開発する事ができます。 asynchat では、プロトコルの要素が任意の文字列で終了するか、または可変長の文字列であるようなプロトコルを容易に制御できるようになっています。 asynchat は、抽象クラス async_chat を定義しており、 async_chat を継承して collect_incoming_data() メソッドと found_terminator() メソッドを実装すれば使うことができます。 async_chat と asyncore は同じ非同期ループを使用しており、 asyncore.dispatcher も asynchat.async_chat も同じチャネルマップに登録する事ができます。通常、 asyncore.dispatcher はサーバチャネルとして使用し、リクエストの受け付け時に asynchat.async_chat オブジェクトを生成します。

class asynchat.async_chat

このクラスは、 asyncore.dispatcher から継承した抽象クラスです。使用する際には async_chat のサブクラスを作成し、 collect_incoming_data() と found_terminator() を定義しなければなりません。 asyncore.dispatcher のメソッドを使用する事もできますが、メッセージ/レスポンス処理を中心に行う場合には使えないメソッドもあります。

asyncore.dispatcher と同様に、 async_chat も select() 呼出し後のソケットの状態からイベントを生成します。ポーリングループ開始後、イベント処理フレームワークが自動的に async_chat のメソッドを呼び出しますので、プログラマが処理を記述する必要はありません。

パフォーマンスの向上やメモリの節約のために、2つのクラス属性を調整することができます。

ac_in_buffer_size

非同期入力バッファサイズ (デフォルト値: 4096)。

ac_out_buffer_size

非同期出力バッファサイズ (デフォルト値: 4096)。

Unlike asyncore.dispatcher, async_chat allows you to define a FIFO queue of producers. A producer need have only one method, more(), which should return data to be transmitted on the channel. The producer indicates exhaustion (i.e. that it contains no more data) by having its more() method return the empty bytes object. At this point the async_chat object removes the producer from the queue and starts using the next producer, if any. When the producer queue is empty the handle_write() method does nothing. You use the channel object's set_terminator() method to describe how to recognize the end of, or an important breakpoint in, an incoming transmission from the remote endpoint.

async_chat のサブクラスでは、入力メソッド collect_incoming_data() と found_terminator() を定義し、チャネルが非同期に受信するデータを処理します。これらのメソッドについては後ろで解説します。

async_chat.close_when_done()

Pushes a None on to the producer queue. When this producer is popped off the queue it causes the channel to be closed.

async_chat.collect_incoming_data(data)

チャネルが受信した不定長のデータを data に指定して呼び出されます。このメソッドは必ずオーバライドする必要があり、デフォルトの実装では、 NotImplementedError 例外を送出します。

async_chat.discard_buffers()

In emergencies this method will discard any data held in the input and/or output buffers and the producer queue.

async_chat.found_terminator()

入力データストリームが、 set_terminator() で指定した終了条件と一致した場合に呼び出されます。このメソッドは必ずオーバライドする必要があり、デフォルトの実装では、 NotImplementedError 例外を送出します。入力データを参照する必要がある場合でも引数としては与えられないため、入力バッファをインスタンス属性として参照しなければなりません。

async_chat.get_terminator()

現在のチャネルの終了条件を返します。

async_chat.push(data)

Pushes data on to the channel's queue to ensure its transmission. This is all you need to do to have the channel write the data out to the network, although it is possible to use your own producers in more complex schemes to implement encryption and chunking, for example.

async_chat.push_with_producer(producer)

Takes a producer object and adds it to the producer queue associated with the channel. When all currently-pushed producers have been exhausted the channel will consume this producer's data by calling its more() method and send the data to the remote endpoint.

async_chat.set_terminator(term)

チャネルで検出する終了条件を設定します。term は入力プロトコルデータの処理方式によって以下の3つの型の何れかを指定します。

term | 説明
string | 入力ストリーム中でstringが検出された時、 found_terminator() を呼び出します
integer | 指定された文字数が読み込まれた時、 found_terminator() を呼び出します
None | 永久にデータを読み込みます

終了条件が成立しても、その後に続くデータは、 found_terminator() の呼出し後に再びチャネルを読み込めば取得する事ができます。

asynchat 使用例

以下のサンプルは、 async_chat でHTTPリクエストを読み込む処理の一部です。Webサーバは、クライアントからの接続毎に http_request_handler オブジェクトを作成します。最初はチャネルの終了条件に空行を指定してHTTPヘッダの末尾までを検出し、その後ヘッダ読み込み済みを示すフラグを立てています。

ヘッダ読み込んだ後、リクエストの種類がPOSTであればデータが入力ストリームに流れるため、Content-Length: ヘッダの値を数値として終了条件に指定し、適切な長さのデータをチャネルから読み込みます。

必要な入力データを全て入手したら、チャネルの終了条件に None を指定して残りのデータを無視するようにしています。この後、 handle_request() が呼び出されます。

import asynchat

class http_request_handler(asynchat.async_chat):

    def __init__(self, sock, addr, sessions, log):
        asynchat.async_chat.__init__(self, sock=sock)
        self.addr = addr
        self.sessions = sessions
        self.ibuffer = []
        self.obuffer = b""
        self.set_terminator(b"\r\n\r\n")
        self.reading_headers = True
        self.handling = False
        self.cgi_data = None
        self.log = log

    def collect_incoming_data(self, data):
        """Buffer the data"""
        self.ibuffer.append(data)

    def found_terminator(self):
        if self.reading_headers:
            self.reading_headers = False
            self.parse_headers(b"".join(self.ibuffer))
            self.ibuffer = []
            if self.op.upper() == b"POST":
                clen = self.headers.getheader("content-length")
                self.set_terminator(int(clen))
            else:
                self.handling = True
                self.set_terminator(None)
                self.handle_request()
        elif not self.handling:
            self.set_terminator(None)  # browsers sometimes over-send
            self.cgi_data = parse(self.headers, b"".join(self.ibuffer))
            self.handling = True
            self.ibuffer = []
            self.handle_request()

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Networking and Interprocess Communication »


signal --- 非同期イベントにハンドラを設定する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »

signal --- 非同期イベントにハンドラを設定する

このモジュールでは Python でシグナルハンドラを使うための機構を提供します。

一般的なルール

signal.signal() 関数を使って、シグナルを受信した時に実行されるハンドラを定義することができます。 Python は標準でごく少数のシグナルハンドラをインストールしています: SIGPIPE は無視され (したがって、 pipe や socket に対する書き込みで生じたエラーは通常の Python 例外として報告されます)、 SIGINT は KeyboardInterrupt 例外に変換されます。これらはどれも上書きすることができます。

特定のシグナルに対するハンドラが一度設定されると、明示的にリセットしないかぎり設定されたままになります (Python は背後の実装系に関係なく BSD 形式のインタフェースをエミュレートします)。例外は SIGCHLD のハンドラで、この場合は背後の実装系の仕様に従います。

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 のシグナルハンドラはその計算が終了してから呼び出されます。

シグナルとスレッド

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. getsignal(), pthread_sigmask(), sigpending() and sigwait() functions return human-readable enums.

以下に signal モジュールで定義されている変数を示します:

signal.SIG_DFL

二つある標準シグナル処理オプションのうちの一つです; 単純にシグナルに対する標準の関数を実行します。例えば、ほとんどのシステムでは、 SIGQUIT に対する標準の動作はコアダンプと終了で、 SIGCHLD に対する標準の動作は単にシグナルの無視です。

signal.SIG_IGN

もう一つの標準シグナル処理オプションで、受け取ったシグナルを単に無視します。

SIG*

全てのシグナル番号はシンボル定義されています。例えば、ハングアップシグナルは signal.SIGHUP で定義されています; 変数名は C 言語のプログラムで使われているのと同じ名前で、 <signal.h> にあります。 'signal()' に関する Unix マニュアルページでは、システムで定義されているシグナルを列挙しています (あるシステムではリストは signal(2) に、別のシステムでは signal(7) に列挙されています)。全てのシステムで同じシグナル名のセットを定義しているわけではないので注意してください; このモジュールでは、システムで定義されているシグナル名だけを定義しています。

signal.CTRL_C_EVENT

CTRL+C キーストロークに該当するシグナル。このシグナルは os.kill() でだけ利用できます。

利用可能な環境: Windows 。

バージョン 3.2 で追加.

signal.CTRL_BREAK_EVENT

CTRL+BREAK キーストロークに該当するシグナル。このシグナルは os.kill() でだけ利用できます。

利用可能な環境: Windows 。

バージョン 3.2 で追加.

signal.NSIG

最も大きいシグナル番号に 1 を足した値です。

signal.ITIMER_REAL

実時間でデクリメントするインターバルタイマーです。タイマーが発火したときに SIGALRM を送ります。

signal.ITIMER_VIRTUAL

プロセスの実行時間だけデクリメントするインターバルタイマーです。タイマーが発火したときに SIGVTALRM を送ります。

signal.ITIMER_PROF

プロセスの実行中と、システムがそのプロセスのために実行している時間だけデクリメントするインターバルタイマーです。ITIMER_VIRTUAL と組み合わせて、このタイマーはよくアプリケーションがユーザー空間とカーネル空間で消費した時間のプロファイリングに利用されます。タイマーが発火したときに SIGPROF を送ります。

signal.SIG_BLOCK

pthread_sigmask() の how 引数に渡せる値で、シグナルがブロックされることを意味します。

バージョン 3.3 で追加.

signal.SIG_UNBLOCK

pthread_sigmask() の how 引数に渡せる値で、シグナルがブロック解除されることを意味します。

バージョン 3.3 で追加.

signal.SIG_SETMASK

pthread_sigmask() の how 引数に渡せる値で、シグナルが置換されることを意味します。

バージョン 3.3 で追加.

signal モジュールは1つの例外を定義しています:

exception signal.ItimerError

背後の setitimer() または getitimer() 実装からエラーを通知するために送出されます。無効なインタバルタイマーや負の時間が setitimer() に渡された場合、このエラーを予期してください。このエラーは OSError を継承しています。

バージョン 3.3 で追加: このエラーは以前は IOError のサブタイプでしたが、 OSError のエイリアスになりました。

signal モジュールでは以下の関数を定義しています:

signal.alarm(time)

If time is non-zero, this function requests that a SIGALRM signal be sent to the process in time seconds. Any previously scheduled alarm is canceled (only one alarm can be scheduled at any time). The returned value is then the number of seconds before any previously set alarm was to have been delivered. If time is zero, no alarm is scheduled, and any scheduled alarm is canceled. If the return value is zero, no alarm is currently scheduled. (See the Unix man page alarm(2).)

利用可能な環境: Unix。

signal.getsignal(signalnum)

シグナル signalnum に対する現在のシグナルハンドラを返します。戻り値は呼び出し可能な Python オブジェクトか、 signal.SIG_IGN、 signal.SIG_DFL、および None といった特殊な値のいずれかです。ここで signal.SIG_IGN は以前そのシグナルが無視されていたことを示し、 signal.SIG_DFL は以前そのシグナルの標準の処理方法が使われていたことを示し、 None はシグナルハンドラがまだ Python によってインストールされていないことを示します。

signal.pause()

シグナルを受け取るまでプロセスを一時停止します; その後、適切なハンドラが呼び出されます。戻り値はありません。Windows では利用できません。(Unix マニュアルページ signal(2) を参照してください。)

sigwait(), sigwaitinfo(), sigtimedwait() sigpending() も参照してください。

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

Availability: Unix (see the man page pthread_kill(3) for further information).

os.kill() を参照してください。

バージョン 3.3 で追加.

signal.pthread_sigmask(how, mask)

これを呼び出すスレッドにセットされているシグナルマスクを取り出したり変更したりします。シグナルマスクは、呼び出し側のために現在どのシグナルの配送がブロックされているかを示す集合 (set) です。呼び出し前のもとのシグナルマスクを集合として返却します。

この関数の振る舞いは how に依存して以下のようになります。

  • SIG_BLOCK: mask で指定されるシグナルが現時点のシグナルマスクに追加されます。
  • SIG_UNBLOCK: mask で指定されるシグナルが現時点のシグナルマスクから取り除かれます。もともとブロックされていないシグナルをブロック解除しようとしても問題ありません。
  • SIG_SETMASK: シグナルマスク全体を mask としてセットします。

mask はシグナル番号の集合です (例えば {signal.SIGINT, signal.SIGTERM})。全てのシグナルを含む全集合として range(1, signal.NSIG) を使うことが出来ます。

呼び出しスレッドにセットされたシグナルマスクを問い合わせるには例えば signal.pthread_sigmask(signal.SIG_BLOCK, []) とします。

Availability: Unix. See the man page sigprocmask(3) and pthread_sigmask(3) for further information.

pause(), sigpending(), sigwait() も参照して下さい。

バージョン 3.3 で追加.

signal.setitimer(which, seconds, interval=0.0)

Sets given interval timer (one of signal.ITIMER_REAL, signal.ITIMER_VIRTUAL or signal.ITIMER_PROF) specified by which to fire after seconds (float is accepted, different from alarm()) and after that every interval seconds (if interval is non-zero). The interval timer specified by which can be cleared by setting seconds to zero.

インターバルタイマーが起動したとき、シグナルがプロセスに送られます。送られるシグナルは利用されたタイマーの種類に依存します。 signal.ITIMER_REAL の場合は SIGALRM が、 signal.ITIMER_VIRTUAL の場合は SIGVTALRM が、 signal.ITIMER_PROF の場合は SIGPROF が送られます。

以前の値が (delay, interval) のタプルとして返されます。

Attempting to pass an invalid interval timer will cause an ItimerError.

利用可能な環境: Unix。

signal.getitimer(which)

Returns current value of a given interval timer specified by 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.

スレッドが有効な場合、この関数はメインスレッドからしか実行できません。それ以外のスレッドからこの関数を実行しようとすると 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 で変更: Added warn_on_full_buffer parameter.

signal.siginterrupt(signalnum, flag)

Change system call restart behaviour: if flag is False, system calls will be restarted when interrupted by signal signalnum, otherwise system calls will be interrupted. Returns nothing.

Availability: Unix (see the man page siginterrupt(3) for further information).

signal() を使ってシグナルハンドラを設定したときに、暗黙のうちに flag に true を指定して siginterrupt() が実行されるため、中断に対するリスタートの動作がリセットされることに注意してください。

signal.signal(signalnum, handler)

シグナル signalnum に対するハンドラを関数 handler にします。 handler は二つの引数 (下記参照) を取る呼び出し可能な Python オブジェクトか、 signal.SIG_IGN あるいは signal.SIG_DFL といった特殊な値にすることができます。以前に使われていたシグナルハンドラが返されます (上記の getsignal() の記述を参照してください)。 (Unix マニュアルページ signal(2) を参照してください。)

スレッドが有効な場合、この関数はメインスレッドからしか実行できません。それ以外のスレッドからこの関数を実行しようとすると 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()

呼び出しスレッドで配送が保留されているシグナル (つまり配送がブロックされている間に発生したシグナル) の集合を調べます。保留中のシグナルの集合を返します。

Availability: Unix (see the man page sigpending(2) for further information).

pause(), pthread_sigmask(), sigwait() も参照して下さい。

バージョン 3.3 で追加.

signal.sigwait(sigset)

sigset 集合で指定されたシグナルのうちどれか一つが届くまで呼び出しスレッドを一時停止します。この関数はそのシグナルを受け取ると (それを保留シグナルリストから取り除いて) そのシグナル番号を返します。

Availability: Unix (see the man page sigwait(3) for further information).

pause(), pthread_sigmask(), sigpending(), sigwaitinfo(), sigtimedwait() も参照して下さい。

バージョン 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.

Availability: Unix (see the man page sigwaitinfo(2) for further information).

pause(), sigwait(), sigtimedwait() も参照して下さい。

バージョン 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 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.

Availability: Unix (see the man page sigtimedwait(2) for further information).

pause(), sigwait(), sigwaitinfo() も参照して下さい。

バージョン 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 for the rationale).

使用例

以下は最小限のプログラム例です。この例では alarm() を使ってファイルを開く処理を待つのに費やす時間を制限します; 例えば、電源の入っていないシリアルデバイスを開こうとすると、通常 os.open() は未定義の期間ハングアップしてしまいますが、この方法はそうした場合に便利です。ここではファイルを開くまで 5 秒間のアラームを設定することで解決しています; ファイルを開く処理が長くかかりすぎると、アラームシグナルが送信され、ハンドラが例外を送出するようになっています。

import signal, os

def handler(signum, frame):
    print('Signal handler called with signal', 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) 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 also whenever any socket connection is interrupted while your program is still writing to it.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Networking and Interprocess Communication »


mmap --- メモリマップファイル

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Networking and Interprocess Communication »

mmap --- メモリマップファイル

メモリにマップされたファイルオブジェクトは、 bytearray と ファイルオブジェクト の両方のように振舞います。しかし通常の文字列オブジェクトとは異なり、これらは可変です。 bytearray が期待されるほとんどの場所で mmap オブジェクトを利用できます。例えば、メモリマップファイルを探索するために re モジュールを使うことができます。それらは可変なので、 obj[index] = 97 のように文字を変換できますし、スライスを使うことで obj[i1:i2] = b'...' のように部分文字列を変換することができます。現在のファイル位置をデータの始めとする読込みや書込み、ファイルの異なる位置へ seek() することもできます。

メモリマップドファイルは Unix と Windows で異なる mmap コンストラクタで生成されます。どちらの場合も、更新用に開かれたファイルディスクリプタを渡さなければなりません。既存の Python ファイルオブジェクトをマップしたければ、 fileno() メソッドを使って fileno パラメータの正しい値を取得してください。そうでなければ、 os.open() 関数を使ってファイルを開けます。この関数はファイルディスクリプタを直接返します(処理が終わったら、やはりファイルを閉じる必要があります)。

注釈

書き込み可能でバッファされたファイルへのメモリマップファイルを作りたいのであれば、まず最初にファイルの flush() を呼び出すべきです。これはバッファへのローカルな修正がマッピングで実際に利用可能になることを保障するために必要です。

For both the Unix and Windows versions of the constructor, access may be specified as an optional keyword parameter. access accepts one of four values: ACCESS_READ, ACCESS_WRITE, or ACCESS_COPY to specify read-only, write-through or copy-on-write memory respectively, or ACCESS_DEFAULT to defer to prot. access can be used on both Unix and Windows. If access is not specified, Windows mmap returns a write-through mapping. The initial memory values for all three access types are taken from the specified file. Assignment to an ACCESS_READ memory map raises a TypeError exception. Assignment to an ACCESS_WRITE memory map affects both memory and the underlying file. Assignment to an ACCESS_COPY memory map affects memory but does not update the underlying file.

バージョン 3.7 で変更: Added ACCESS_DEFAULT constant.

無名メモリ(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 は、 None 以外で指定された場合、マップのタグ名を与える文字列となります。 Windows は同じファイルに対する様々なマップを持つことを可能にします。既存のタグの名前を指定すればそのタグがオープンされ、そうでなければこの名前の新しいタグが作成されます。もしこのパラメータを省略したり None を与えたりしたならば、マップは名前なしで作成されます。タグ・パラメータの使用の回避は、あなたのコードを Unix と Windows の間で移植可能にしておくのを助けてくれるでしょう。

offset may be specified as a non-negative integer offset. mmap references will be relative to the offset from the beginning of the file. offset defaults to 0. offset must be a multiple of the ALLOCATIONGRANULARITY.

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 はマップの種類を指定します。 MAP_PRIVATE はプライベートな copy-on-write(書込み時コピー)のマップを作成します。従って、mmap オブジェクトの内容への変更はこのプロセス内にのみ有効です。 MAP_SHARED はファイルの同じ領域をマップする他のすべてのプロセスと共有されたマップを作成します。デフォルトは MAP_SHARED です。

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.

Mac OS X と OpenVMS において、作成された memory mapping の正当性を確実にするために fileno で指定されたファイルディスクリプタは内部で自動的に物理的なストレージ (physical backing store) と同期されます。

この例は 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 can also be used as a context manager in a with statement:

import mmap

with mmap.mmap(-1, 13) as mm:
    mm.write(b"Hello world!")

バージョン 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()

メモリマップファイルオブジェクトは以下のメソッドをサポートしています:

close()

メモリマップファイルを閉じます。この呼出しの後にオブジェクトの他のメソッドの呼出すことは、 ValueError 例外の送出を引き起こします。このメソッドは開いたファイルのクローズはしません。

closed

ファイルが閉じている場合 True となります。

バージョン 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.

(Windows バージョン) ゼロ以外の値が返されたら成功を、ゼロは失敗を意味します。

(Unix バージョン) ゼロの値が返されたら成功を意味します。呼び出しが失敗すると例外が送出されます。

move(dest, src, count)

オフセット src から始まる count バイトをインデックス dest の位置へコピーします。もし mmap が ACCESS_READ で作成されていた場合、 TypeError 例外を発生させます。

read([n])

現在のファイル位置からの最大 n バイトを含む bytes を返します。引数が省略されるか、 None もしくは負の値が指定された場合、現在のファイル位置からマップ終端までの全てのバイト列を返します。ファイル位置は返されたバイト列の直後を指すように更新されます。

バージョン 3.3 で変更: 引数が省略可能になり、 None も受け付けるようになりました。

read_byte()

現在のファイル位置のバイトを整数値として返し、ファイル位置を 1 進めます。

readline()

現在のファイル位置から次の改行までの、1行を返します。

resize(newsize)

マップと元ファイル(がもしあれば)のサイズを変更します。もし mmap が ACCESS_READ または ACCESS_COPY で作成されたならば、マップサイズの変更は TypeError 例外を発生させます。

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が:const:ACCESS_READ とともに作成されていた場合は、書き込みは TypeError 例外を送出するでしょう。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

バージョン 3.6 で変更: 書きこまれたバイト数を返すようになりました。

write_byte(byte)

メモリ内のファイル・ポインタの現在位置に整数 byte を書き込みます。ファイル位置は 1 だけ進みます。もし mmap が ACCESS_READ で作成されていた場合、書き込み時に TypeError 例外を発生させるでしょう。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Networking and Interprocess Communication »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

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

この章ではインターネット上で一般的に利用されているデータ形式の操作をサポートするモジュール群について記述します。

  • email --- 電子メールと MIME 処理のためのパッケージ
    • email.message: 電子メールメッセージの表現
    • email.parser: 電子メールメッセージのパース
      • FeedParser API
      • Parser API
      • 追記事項
    • email.generator: MIME 文書の生成
    • email.policy: ポリシーオブジェクト
    • email.errors: 例外及び欠陥クラス
    • email.headerregistry: カスタムヘッダーオブジェクト
    • email.contentmanager: MIME 内容の管理
      • Content Manager Instances
    • email: 使用例
    • email.message.Message: Representing an email message using the compat32 API
    • email.mime: メールと MIME オブジェクトを一から作成
    • email.header: 国際化されたヘッダ
    • email.charset: 文字集合の表現
    • email.encoders: エンコーダ
    • email.utils: 多方面のユーティリティ
    • email.iterators: イテレータ
  • json --- JSON エンコーダおよびデコーダ
    • 基本的な使い方
    • エンコーダとデコーダ
    • 例外
    • 標準への準拠と互換性
      • 文字エンコーディング
      • 無限および NaN の数値
      • オブジェクト中に重複した名前の扱い
      • トップレベルの非オブジェクト、非配列の値の扱い
      • 実装の制限
    • コマンドラインインターフェイス
      • コマンドラインオプション
  • mailcap --- mailcap ファイルの操作
  • mailbox --- 様々な形式のメールボックス操作
    • Mailbox オブジェクト
      • Maildir
      • mbox
      • MH
      • Babyl
      • MMDF
    • Message objects
      • MaildirMessage
      • mboxMessage
      • MHMessage
      • BabylMessage
      • MMDFMessage
    • 例外
    • 使用例
  • mimetypes --- ファイル名を MIME 型へマップする
    • Mime 型オブジェクト
  • base64 --- Base16, Base32, Base64, Base85 データの符号化
  • binhex --- binhex4 形式ファイルのエンコードおよびデコード
    • 注釈
  • binascii --- バイナリデータと ASCII データとの間での変換
  • quopri --- MIME quoted-printable 形式データのエンコードおよびデコード
  • uu --- uuencode形式のエンコードとデコード

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


email --- 電子メールと MIME 処理のためのパッケージ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »

email --- 電子メールと MIME 処理のためのパッケージ

ソースコード: Lib/email/__init__.py

email パッケージは、電子メールメッセージを管理するライブラリです。 特に、SMTP（:rfc:`2821）、NNTP、またはその他のサーバーに電子メールメッセージを送信するようには設計されていません。これらは、:mod:`smtplib` や、 nntplib などのモジュールの関数群です。 email パッケージは、可能な限りRFCに準拠するよう試みています。 :rfc:`5233`や :rfc:`6532` のほか、 RFC 2045、 RFC 2046、 RFC 2047、 RFC 2183、 RFC 2231 などのMIME関連のRFCに対応しています。

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: 電子メールメッセージの表現
  • email.parser: 電子メールメッセージのパース
    • FeedParser API
    • Parser API
    • 追記事項
  • email.generator: MIME 文書の生成
  • email.policy: ポリシーオブジェクト
  • email.errors: 例外及び欠陥クラス
  • email.headerregistry: カスタムヘッダーオブジェクト
  • email.contentmanager: MIME 内容の管理
    • Content Manager Instances
  • email: 使用例

レガシーAPI:

  • email.message.Message: Representing an email message using the compat32 API
  • email.mime: メールと MIME オブジェクトを一から作成
  • email.header: 国際化されたヘッダ
  • email.charset: 文字集合の表現
  • email.encoders: エンコーダ
  • email.utils: 多方面のユーティリティ
  • email.iterators: イテレータ

参考

smtplib モジュール
SMTP (Simple Mail Transport Protocol) client
Module poplib
POP (Post Office Protocol) client
モジュール imaplib
IMAP (Internet Message Access Protocol) client
nntplib モジュール
NNTP (Net News Transport Protocol) client
mailbox モジュール
Tools for creating, reading, and managing collections of messages on disk using a variety standard formats.
Module smtpd
SMTP server framework (primarily useful for testing)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネット上のデータの操作 »


email.message: 電子メールメッセージの表現

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.message: 電子メールメッセージの表現

ソースコード: Lib/email/message.py

バージョン 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 or RFC 6532 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 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. Unlike a real dict, there is an ordering to the keys, and there can be duplicate keys. 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.

Flattening the message may trigger changes to the EmailMessage if defaults need to be filled in to complete the transformation to a string (for example, MIME boundaries may be generated or modified).

Note that this method is provided as a convenience and may not be the most useful way to serialize messages in your application, especially if you are dealing with multiple messages. See 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-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.

Flattening the message may trigger changes to the EmailMessage if defaults need to be filled in to complete the transformation to a string (for example, MIME boundaries may be generated or modified).

Note that this method is provided as a convenience and may not be the most useful way to serialize messages in your application, especially if you are dealing with multiple messages. See 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)

Add a header to the message with field name name and value val. The field is appended to the end of the message's existing headers.

注意: このメソッドでは、すでに同一の名前で存在するフィールドは上書き されません。もしメッセージが名前 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 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 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, messages always have a default type, get_content_type() will always return a value. RFC 2045 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 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 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)

Remove the given parameter completely from the Content-Type header. The header will be re-written in place without the parameter or its value. Optional header specifies an alternative to 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 のリストを返します。

Each item in the list will be a string which is the value of the charset parameter in the Content-Type header for the represented subpart. If the subpart has no Content-Type header, no charset parameter, or is not of the text main MIME type, then that item in the returned list will be 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.

バージョン 3.5 で追加.

The following methods relate to interrogating and manipulating the content (payload) of the message.

walk()

walk() メソッドは多目的のジェネレータで、これはあるメッセージオブジェクトツリー中のすべての part および subpart をわたり歩くのに使えます。順序は深さ優先です。おそらく典型的な用法は、 walk() を for ループ中でのイテレータとして使うことでしょう。ループを一回まわるごとに、次の subpart が返されるのです。

Here's an example that prints the MIME type of every part of a multipart message structure:

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

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 objects have the following instance attributes:

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: Representing an email message using the compat32 API.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.parser: 電子メールメッセージのパース

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.parser: 電子メールメッセージのパース

ソースコード: 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.

The BytesFeedParser's API is simple; you create an instance, feed it a bunch of bytes until there's no more to feed it, then close the parser to retrieve the root message object. The BytesFeedParser is extremely accurate when parsing standards-compliant messages, and it does a very good job of parsing non-compliant messages, providing information about how a message was deemed broken. It will populate a message object's defects attribute with a list of any problems it found in a message. See the email.errors module for the list of defects that it can find.

Here is the API for the BytesFeedParser:

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.

バージョン 3.2 で追加.

バージョン 3.3 で変更: キーワード引数 policy が追加されました。

バージョン 3.6 で変更: _factory defaults to the policy message_factory.

feed(data)

Feed the parser some more data. data should be a bytes-like object containing one or more lines. The lines can be partial and the parser will stitch such partial lines together properly. The lines can have any of the three common line endings: carriage return, newline, or carriage return and newline (they can even be mixed).

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 (or, if utf8 is True, RFC 6532) 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() メソッドと同じです。

バージョン 3.2 で追加.

class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)

Exactly like BytesParser, except that headersonly defaults to True.

バージョン 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)

Read all the data from the text-mode file-like object fp, parse the resulting text, and return the root message object. fp must support both the readline() and the read() methods on file-like objects.

Other than the text mode requirement, this method operates like BytesParser.parse().

parsestr(text, headersonly=False)

Similar to the parse() method, except it takes a string object instead of a file-like object. Calling this method on a string is equivalent to wrapping text in a StringIO instance first and calling 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)

Return a message object structure from a bytes-like object. This is equivalent to BytesParser().parsebytes(s). Optional _class and policy are interpreted as with the BytesParser class constructor.

バージョン 3.2 で追加.

バージョン 3.3 で変更: strict 引数の削除。キーワード引数 policy の追加。

email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)

Return a message object structure tree from an open binary file object. This is equivalent to BytesParser().parse(fp). _class and policy are interpreted as with the BytesParser class constructor.

バージョン 3.2 で追加.

バージョン 3.3 で変更: strict 引数の削除。キーワード引数 policy の追加。

email.message_from_string(s, _class=None, *, policy=policy.compat32)

Return a message object structure from a string. This is equivalent to Parser().parsestr(s). _class and policy are interpreted as with the Parser class constructor.

バージョン 3.3 で変更: strict 引数の削除。キーワード引数 policy の追加。

email.message_from_file(fp, _class=None, *, policy=policy.compat32)

Return a message object structure tree from an open file object. This is equivalent to Parser().parse(fp). _class and policy are interpreted as with the Parser class constructor.

バージョン 3.3 で変更: strict 引数の削除。キーワード引数 policy の追加。

バージョン 3.6 で変更: _class defaults to the policy message_factory.

Here's an example of how you might use message_from_bytes() at an interactive Python prompt:

>>> 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.
  • Some non-standards-compliant messages may not be internally consistent about their multipart-edness. Such messages may have a Content-Type header of type multipart, but their is_multipart() method may return False. If such messages were parsed with the FeedParser, they will have an instance of the MultipartInvariantViolationDefect class in their defects attribute list. See email.errors for details.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.generator: MIME 文書の生成

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.generator: MIME 文書の生成

ソースコード: 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".

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

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

Print the textual representation of the message object structure rooted at msg to the output file specified when the BytesGenerator instance was created.

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

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)

Print the textual representation of the message object structure rooted at msg to the output file specified when the Generator instance was created.

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.policy: ポリシーオブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.policy: ポリシーオブジェクト

バージョン 3.3 で追加.

ソースコード: 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 に従い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.

バージョン 3.5 で追加: mangle_from_ 引数。

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.

バージョン 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 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, RFC 2047, 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 and RFC 5322.

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:

バージョン 3.6 で追加: [1]

utf8

If False, follow RFC 5322, supporting non-ASCII characters in headers by encoding them as "encoded words". If True, follow RFC 6532 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).

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

バージョン 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.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.errors: 例外及び欠陥クラス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.errors: 例外及び欠陥クラス

ソースコード: 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 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) に対して呼んだ場合にも送出されることがあります。

Here is the list of the defects that the FeedParser can find while parsing messages. Note that the defects are added to the message where the problem was found, so for example, if a message nested inside a multipart/alternative had a malformed header, that nested message object would have a defect, but the containing messages would not.

All defect classes are subclassed from email.errors.MessageDefect.

  • NoBoundaryInMultipartDefect -- メッセージが multipart だと宣言されているのに、 boundary パラメータがありません。

  • StartBoundaryNotFoundDefect -- Content-Type ヘッダで宣言された開始境界がありません。

  • CloseBoundaryNotFoundDefect -- 開始境界はあるが対応する終了境界がありません。

    バージョン 3.3 で追加.

  • FirstHeaderLineIsContinuationDefect -- メッセージの最初のヘッダ行が継続行です。

  • MisplacedEnvelopeHeaderDefect -- ヘッダブロックの途中に "Unix From" ヘッダがあります。

  • MissingHeaderBodySeparatorDefect - 先頭に空白はないが ':' がないヘッダの解析中に行が見付かりました。その行を本体の最初の行とみなして解析を続けます。

    バージョン 3.3 で追加.

  • MalformedHeaderDefect -- ヘッダにコロンがありません、あるいはそれ以外の不正な形式です。

    バージョン 3.3 で非推奨: この欠陥が使われていないPythonバージョンがいくつかあります。

  • MultipartInvariantViolationDefect -- メッセージが multipart だと宣言されているのに、サブパートが存在しません。 メッセージがこの欠陥を持つ場合、内容の型が multipart と宣言されていても is_multipart() メソッドは偽を返すことがあるので注意してください。

  • InvalidBase64PaddingDefect -- When decoding a block of base64 encoded bytes, the padding was not correct. Enough padding is added to perform the decode, but the resulting decoded bytes may be invalid.

  • InvalidBase64CharactersDefect -- When decoding a block of base64 encoded bytes, characters outside the base64 alphabet were encountered. The characters are ignored, but the resulting decoded bytes may be invalid.

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.headerregistry: カスタムヘッダーオブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.headerregistry: カスタムヘッダーオブジェクト

ソースコード: Lib/email/headerregistry.py

バージョン 3.6 で追加: [1]

Headers are represented by customized subclasses of str. The particular class used to represent a given header is determined by the header_factory of the policy in effect when the headers are created. This section documents the particular header_factory implemented by the email package for handling RFC 5322 compliant email messages, which not only provides customized header objects for various header types, but also provides an extension mechanism for applications to add their own custom header types.

When using any of the policy objects derived from EmailPolicy, all headers are produced by HeaderRegistry and have BaseHeader as their last base class. Each header class has an additional base class that is determined by the type of the header. For example, many headers have the class UnstructuredHeader as their other base class. The specialized second class for a header is determined by the name of the header, using a lookup table stored in the HeaderRegistry. All of this is managed transparently for the typical application program, but interfaces are provided for modifying the default behavior for use by more complex applications.

The sections below first document the header base classes and their attributes, followed by the API for modifying the behavior of HeaderRegistry, and finally the support classes used to represent the data parsed from structured headers.

class email.headerregistry.BaseHeader(name, value)

name and value are passed to BaseHeader from the header_factory call. The string value of any header object is the value fully decoded to unicode.

基底クラスは以下の読み出し専用属性を定義しています:

name

The name of the header (the portion of the field before the ':'). This is exactly the value passed in the header_factory call for name; that is, case is preserved.

defects

A tuple of HeaderDefect instances reporting any RFC compliance problems found during parsing. The email package tries to be complete about detecting compliance issues. See the errors module for a discussion of the types of defects that may be reported.

max_count

The maximum number of headers of this type that can have the same name. A value of None means unlimited. The BaseHeader value for this attribute is None; it is expected that specialized header classes will override this value as needed.

BaseHeader also provides the following method, which is called by the email library code and should not in general be called by application programs:

fold(*, policy)

Return a string containing linesep characters as required to correctly fold the header according to policy. A cte_type of 8bit will be treated as if it were 7bit, since headers may not contain arbitrary binary data. If utf8 is False, non-ASCII data will be RFC 2047 encoded.

BaseHeader by itself cannot be used to create a header object. It defines a protocol that each specialized header cooperates with in order to produce the header object. Specifically, BaseHeader requires that the specialized class provide a classmethod() named parse. This method is called as follows:

parse(string, kwds)

kwds is a dictionary containing one pre-initialized key, defects. defects is an empty list. The parse method should append any detected defects to this list. On return, the kwds dictionary must contain values for at least the keys decoded and defects. decoded should be the string value for the header (that is, the header value fully decoded to unicode). The parse method should assume that string may contain content-transfer-encoded parts, but should correctly handle all valid unicode characters as well so that it can parse un-encoded header values.

BaseHeader's __new__ then creates the header instance, and calls its init method. The specialized class only needs to provide an init method if it wishes to set additional attributes beyond those provided by BaseHeader itself. Such an init method should look like this:

def init(self, *args, **kw):
    self._myattr = kw.pop('myattr')
    super().init(*args, **kw)

That is, anything extra that the specialized class puts in to the kwds dictionary should be removed and handled, and the remaining contents of kw (and args) passed to the BaseHeader init method.

class email.headerregistry.UnstructuredHeader

An "unstructured" header is the default type of header in RFC 5322. Any header that does not have a specified syntax is treated as unstructured. The classic example of an unstructured header is the Subject header.

In RFC 5322, an unstructured header is a run of arbitrary text in the ASCII character set. RFC 2047, however, has an RFC 5322 compatible mechanism for encoding non-ASCII text as ASCII characters within a header value. When a value containing encoded words is passed to the constructor, the UnstructuredHeader parser converts such encoded words into unicode, following the RFC 2047 rules for unstructured text. The parser uses heuristics to attempt to decode certain non-compliant encoded words. Defects are registered in such cases, as well as defects for issues such as invalid characters within the encoded words or the non-encoded text.

このヘッダ型には追加の属性はありません。

class email.headerregistry.DateHeader

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

The decoded value of the header is determined by formatting the datetime according to the RFC 5322 rules; that is, it is set to:

email.utils.format_datetime(self.datetime)

When creating a DateHeader, value may be datetime instance. This means, for example, that the following code is valid and does what one would expect:

msg['Date'] = datetime(2011, 7, 15, 21)

Because this is a naive datetime it will be interpreted as a UTC timestamp, and the resulting value will have a timezone of -0000. Much more useful is to use the localtime() function from the utils module:

msg['Date'] = utils.localtime()

This example sets the date header to the current time and date using the current timezone offset.

class email.headerregistry.AddressHeader

Address headers are one of the most complex structured header types. The AddressHeader class provides a generic interface to any address header.

このヘッダ型は以下の属性も提供しています:

groups

A tuple of Group objects encoding the addresses and groups found in the header value. Addresses that are not part of a group are represented in this list as single-address Groups whose display_name is None.

addresses

A tuple of Address objects encoding all of the individual addresses from the header value. If the header value contains any groups, the individual addresses from the group are included in the list at the point where the group occurs in the value (that is, the list of addresses is "flattened" into a one dimensional list).

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, 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 を参照してください。

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
from: UniqueAddressHeader
resent-from: AddressHeader
reply-to: UniqueAddressHeader

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.

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 rules, but with no Content Transfer Encoding of any non-ASCII characters.

To support SMTP ( RFC 5321), 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, 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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.contentmanager: MIME 内容の管理

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.contentmanager: MIME 内容の管理

ソースコード: Lib/email/contentmanager.py

バージョン 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, 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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email: 使用例

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

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'] = 'The contents of %s' % 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 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, 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

# And imghdr to find the types of our images
import imghdr

# 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 = 'Our family reunion'

# Open the files in binary mode.  Use imghdr to figure out the
# MIME subtype for each specific image.
for file in pngfiles:
    with open(file, 'rb') as fp:
        img_data = fp.read()
    msg.add_attachment(img_data, maintype='image',
                                 subtype=imghdr.what(None, img_data))

# 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'] = 'Contents of directory %s' % 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 = 'part-%03d%s' % (counter, 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

# An imaginary module that would make this work and be safe.
from imaginary import magic_html_parser

# 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:
    # The magic_html_parser has to rewrite the href="cid:...." attributes to
    # point to the filenames in partfiles.  It also has to do a safety-sanitize
    # of the html.  It could be written using html.parser.
    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 のおかげです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.message.Message: Representing an email message using the compat32 API

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.message.Message: Representing an email message using the 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 5233 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.

Flattening the message may trigger changes to the Message if defaults need to be filled in to complete the transformation to a string (for example, MIME boundaries may be generated or modified).

Note that this method is provided as a convenience and may not always format the message the way you want. For example, by default it does not do the mangling of lines that begin with 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.

Flattening the message may trigger changes to the Message if defaults need to be filled in to complete the transformation to a string (for example, MIME boundaries may be generated or modified).

Note that this method is provided as a convenience and may not always format the message the way you want. For example, by default it does not do the mangling of lines that begin with 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()

バージョン 3.4 で追加.

__bytes__()

as_bytes() と等価です。これにより bytes(msg) は書式化されたメッセージの bytes オブジェクトを作ります。

バージョン 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 ヘッダにアクセスするためのマップ (辞書) 形式のインタフェイスを実装したものです。これらのメソッドと、通常のマップ (辞書) 型はまったく同じ意味をもつわけではないことに注意してください。たとえば辞書型では、同じキーが複数あることは許されていませんが、ここでは同じメッセージヘッダが複数ある場合があります。また、辞書型では 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)

指定された名前をもつフィールドの値を返します。これは指定された名前がないときにオプション引数の failobj (デフォルトでは None) を返すことをのぞけば、 __getitem__() と同じです。

さらに、役に立つメソッドをいくつか紹介します:

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 を参照してください)、 VALUE は非 ASCII コードポイントを含む文字列値です。この 3 タプルではなく非 ASCII 文字を含む値が渡された場合は、 CHARSET に utf-8 、 LANGUAGE に None を使って RFC 2231 形式に自動的にエンコードされます。

以下はこの使用例です:

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 によればメッセージはつねにデフォルトの content-type をもっているので、 get_content_type() はつねになんらかの値を返すはずです。

RFC 2045 はメッセージのデフォルト content-type を、それが multipart/digest コンテナに現れているとき以外は text/plain に規定しています。あるメッセージが multipart/digest コンテナ中にある場合、その content-type は message/rfc822 になります。もし Content-Type ヘッダが適切でない content-type 書式だった場合、 RFC 2045 はそれのデフォルトを 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 エンコードされている場合です。3 要素タプルの場合、各要素の値は (CHARSET, LANGUAGE, VALUE) の形式になっています。 CHARSET と LAGUAGE は None になることがあり、その場合 VALUE は us-ascii 文字セットでエンコードされているとみなさなければならないので注意してください。普段は LANGUAGE を無視できます。

この関数を使うアプリケーションが、パラメータが RFC 2231 形式でエンコードされているかどうかを気にしないのであれば、 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 にしたがいこの値には text/plain が設定され、新しいパラメータ値が末尾に追加されます。

オプション引数 header が与えられた場合、 Content-Type のかわりにそのヘッダが使用されます。オプション引数 requote が False でない限り、この値は quote されます (デフォルトは True)。

オプション引数 charset が与えられると、そのパラメータは RFC 2231 に従ってエンコードされます。オプション引数 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.

バージョン 3.5 で追加.

walk()

walk() メソッドは多目的のジェネレータで、これはあるメッセージオブジェクトツリー中のすべての part および subpart をわたり歩くのに使えます。順序は深さ優先です。おそらく典型的な用法は、 walk() を for ループ中でのイテレータとして使うことでしょう。ループを一回まわるごとに、次の subpart が返されるのです。

Here's an example that prints the MIME type of every part of a multipart message structure:

>>> 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 を参照してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.mime: メールと MIME オブジェクトを一から作成

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.mime: メールと MIME オブジェクトを一から作成

ソースコード: 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 で変更: Added policy keyword-only parameter.

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 で変更: Added policy keyword-only parameter.

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

モジュール: email.mime.application

MIMENonMultipart のサブクラスである MIMEApplication クラスは MIME メッセージオブジェクトのメジャータイプ application を表します。 _data は生のバイト列が入った文字列です。オプション引数 _subtype は MIME のサブタイプを設定します。サブタイプのデフォルトは octet-stream です。

オプション引数の _encoder は呼び出し可能なオブジェクト (関数など) で、データの転送に使う実際のエンコード処理を行います。この呼び出し可能なオブジェクトは引数を 1 つ取り、それは MIMEApplication のインスタンスです。ペイロードをエンコードされた形式に変更するために get_payload() と set_payload() を使い、必要に応じて Content-Transfer-Encoding やその他のヘッダをメッセージオブジェクトに追加するべきです。デフォルトのエンコードは base64 です。組み込みのエンコーダの一覧は email.encoders モジュールを見てください。

Optional policy argument defaults to compat32.

_params は基底クラスのコンストラクタにそのまま渡されます。

バージョン 3.6 で変更: Added policy keyword-only parameter.

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

モジュール: email.mime.audio

MIMEAudio クラスは MIMENonMultipart のサブクラスで、主形式 (maintype) が audio の MIME オブジェクトを作成するのに使われます。 _audiodata は実際の音声データを格納した文字列です。もしこのデータが標準の Python モジュール sndhdr によって認識できるものであれば、 Content-Type ヘッダの副形式 (subtype) は自動的に決定されます。そうでない場合はその画像の形式 (subtype) を _subtype で明示的に指定する必要があります。副形式が自動的に決定できず、 _subtype の指定もない場合は、 TypeError が発生します。

オプション引数の _encoder は呼び出し可能なオブジェクト (関数など) で、オーディオデータの転送に使う実際のエンコード処理を行います。この呼び出し可能なオブジェクトは引数を 1 つ取り、それは MIMEAudio のインスタンスです。ペイロードをエンコードされた形式に変更するために get_payload() と set_payload() を使い、必要に応じて Content-Transfer-Encoding やその他のヘッダをメッセージオブジェクトに追加するべきです。デフォルトのエンコードは base64 です。組み込みのエンコーダの一覧は email.encoders モジュールを見てください。

Optional policy argument defaults to compat32.

_params は基底クラスのコンストラクタにそのまま渡されます。

バージョン 3.6 で変更: Added policy keyword-only parameter.

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

モジュール: email.mime.image

MIMEImage クラスは MIMENonMultipart のサブクラスで、主形式 (maintype) が image の MIME オブジェクトを作成するのに使われます。 _imagedata は実際の画像データを格納した文字列です。もしこのデータが標準の Python モジュール imghdr によって認識できるものであれば、 Content-Type ヘッダの副形式 (subtype) は自動的に決定されます。そうでない場合はその画像の形式 (subtype) を _subtype で明示的に指定する必要があります。副形式が自動的に決定できず、 _subtype の指定もない場合は、 TypeError が発生します。

オプション引数の _encoder は呼び出し可能なオブジェクト (関数など) で、画像データの転送に使う実際のエンコード処理を行います。この呼び出し可能なオブジェクトは引数を 1 つ取り、それは MIMEImage のインスタンスです。ペイロードをエンコードされた形式に変更するために get_payload() と set_payload() を使い、必要に応じて Content-Transfer-Encoding やその他のヘッダをメッセージオブジェクトに追加するべきです。デフォルトのエンコードは base64 です。組み込みのエンコーダの一覧は email.encoders モジュールを見てください。

Optional policy argument defaults to compat32.

_params は MIMEBase コンストラクタに直接渡されます。

バージョン 3.6 で変更: Added policy keyword-only parameter.

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 で変更: Added policy keyword-only parameter.

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 インスタンスの両方を受け付けます。

Unless the _charset argument is explicitly set to None, the MIMEText object created will have both a Content-Type header with a charset parameter, and a Content-Transfer-Encoding header. This means that a subsequent set_payload call will not result in an encoded payload, even if a charset is passed in the set_payload command. You can "reset" this behavior by deleting the Content-Transfer-Encoding header, after which a set_payload call will automatically encode the new payload (and add a new Content-Transfer-Encoding header).

Optional policy argument defaults to compat32.

バージョン 3.5 で変更: _charset は Charset インスタンスも受け取ります。

バージョン 3.6 で変更: Added policy keyword-only parameter.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.header: 国際化されたヘッダ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.header: 国際化されたヘッダ

ソースコード: Lib/email/header.py

このモジュールはレガシー(Compat32)な電子メールAPIの一部です。現在のAPIではヘッダのエンコードとデコードは EmailMessage クラスの辞書的なAPIによって透過的に処理されます。レガシーコードでの使用に加えて、このモジュールは、ヘッダーをエンコードする際に使用される文字セットを完全に制御する必要があるアプリケーションで役立ちます

The remaining text in this section is the original documentation of the module.

RFC 2822 は電子メールメッセージの形式を規定する基本規格です。これはほとんどの電子メールが ASCII 文字のみで構成されていたころ普及した RFC 822 標準から発展したものです。 RFC 2822 は電子メールがすべて 7-bit ASCII 文字のみから構成されていると仮定して作られた仕様です。

もちろん、電子メールが世界的に普及するにつれ、この仕様は国際化されてきました。今では電子メールに言語依存の文字集合を使うことができます。基本規格では、まだ電子メールメッセージを 7-bit ASCII 文字のみを使って転送するよう要求していますので、多くの RFC でどうやって非ASCII の電子メールを RFC 2822 準拠な形式にエンコードするかが記述されています。これらの RFC は以下のものを含みます: RFC 2045 、 RFC 2046 、 RFC 2047 、および RFC 2231 。 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 準拠の適切な形式にエンコードされます。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 準拠の折り返し用余白文字で、ふつうこれは空白か、ハードタブ文字 (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 準拠のヘッダを RFC 2047 の規則を用いて生成する際、文字列は指定された文字セットの出力コーデックを用いてエンコードされます。出力コーデックを用いて文字列がエンコードできないときは UnicodeError が発生します。

Optional errors is passed as the errors argument to the decode call if s is a byte string.

encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

メッセージヘッダを RFC に沿ったやり方でエンコードします。おそらく長い行は折り返され、非 ASCII 部分は base64 または quoted-printable エンコーディングで包含されるでしょう。

オプション引数 splitchars は、通常のヘッダーの折り返し処理の間に分割アルゴリズムによって特別な重みが与えられるべき文字を含む文字列です。これは、 RFC 2822 の 'higher level syntactic breaks' の非常に荒いサポートです: splitchar の後の分割点は、行分割において優先されます。 分割文字は文字列中での出現順に優先されます。スペースとタブは、分割しようとする行に他の分割文字が出現しない時に、分割点として他の文字と比べてどのような優先順位が与えられるべきかを示すために、文字列に含めることができます。 Splitchars は RFC 2047 エンコードされた行には影響しません。

与えられた場合、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 コンストラクタに与えるものと同じです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.charset: 文字集合の表現

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.charset: 文字集合の表現

ソースコード: Lib/email/charset.py

This module is part of the legacy (Compat32) email API. In the new API only the aliases table is used.

The remaining text in this section is the original documentation of the module.

このモジュールは文字集合の表現および電子メールメッセージの文字集合の変換を行う 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 コーデックの名前です。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.encoders: エンコーダ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.encoders: エンコーダ

ソースコード: Lib/email/encoders.py

This module is part of the legacy (Compat32) email API. In the new API the functionality is provided by the cte parameter of the set_content() method.

The remaining text in this section is the original documentation of the module.

何もないところから Message を作成するときしばしば必要になるのが、ペイロードをメールサーバに通すためにエンコードすることです。これはとくにバイナリデータを含んだ image/* や text/* タイプのメッセージで必要です。

email パッケージでは、 encoders モジュールにおいていくかの便宜的なエンコーディングをサポートしています。実際にはこれらのエンコーダは MIMEAudio および MIMEImage クラスのコンストラクタでデフォルトエンコーダとして使われています。すべてのエンコーディング関数は、エンコードするメッセージオブジェクトひとつだけを引数にとります。これらはふつうペイロードを取りだし、それをエンコードして、ペイロードをエンコードされたものにセットしなおします。これらはまた Content-Transfer-Encoding ヘッダを適切な値に設定します。

マルチパートメッセージにこれら関数を使うことは全く無意味です。それらは各々のサブパートごとに適用されるべきものです。メッセージがマルチパートのものを渡すと 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() を使ってエンコードすると、データ中のタブ文字や空白文字もエンコードされます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.utils: 多方面のユーティリティ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.utils: 多方面のユーティリティ

ソースコード: Lib/email/utils.py

There are a couple of useful utilities provided in the email.utils module:

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. In this case, a positive or zero value for isdst causes localtime to presume initially that summer time (for example, Daylight Saving Time) is or is not (respectively) in effect for the specified time. A negative value for isdst causes the localtime to attempt to divine whether summer time is in effect for the specified time.

バージョン 3.3 で追加.

email.utils.make_msgid(idstring=None, domain=None)

Returns a string suitable for an RFC 2822-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 エンコーディングに使われる文字集合です。str か Charset のインスタンスで、デフォルトは utf-8 です。

バージョン 3.3 で変更: charset オプションが追加されました。

email.utils.getaddresses(fieldvalues)

このメソッドは parseaddr() が返す形式の 2 要素タプルのリストを返します。 fieldvalues は Message.get_all が返すような一連のヘッダフィールドです。 以下はメッセージの全ての受信者を得る簡単な例です:

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 の規則に基づいて日付の解析を試みます。 しかしながらメイラーによっては指定された形式に従っていないものがあるので、その場合 parsedate() は正しく推測しようとします。 date は "Mon, 20 Nov 1995 19:12:08 -0500" のような RFC 2822 形式の日付を含む文字列です。 日付の解析に成功した場合、 parsedate() は関数 time.mktime() に直接渡せる形式の 9 要素からなるタプルを返します。 失敗した場合は None を返します。 返されるタプルの 6、7、8番目の添字は使用不可なので注意してください。

email.utils.parsedate_tz(date)

parsedate() と同様に機能しますが、 None か 10 要素のタプルを返します。 最初の 9 要素は time.mktime() に直接渡すことの出来るタプルを成し、10 番目はその日付のタイムゾーンの UTC (グリニッジ標準時の公式用語) からの差です [1] 。 入力文字列にタイムゾーンがない場合、返されるタプルの最後の要素は None です。 返されるタプルの 6、7、8番目の添字は使用不可なので注意してください。

email.utils.parsedate_to_datetime(date)

format_datetime() の逆です。 parsedate() と同様に機能しますが、成功時に datetime を返します。 入力文字列がタイムゾーン -0000 を持つ場合、datetime はナイーブな datetime です。 日付が RFC に従っている場合、datetime は UTC での時間を表しますが、日付の元になったメッセージの実際のタイムゾーンについての情報を持ちません。 入力データにその他の有効なタイムゾーンの差がある場合、 datetime は対応する timezone tzinfo のあるそつのない datetime です。

バージョン 3.3 で追加.

email.utils.mktime_tz(tuple)

parsedate_tz() が返す 10 要素のタプルを UTC のタイムスタンプ (エポックからの秒数) に変換します。与えられた時間帯が None である場合、時間帯として現地時間 (localtime) が仮定されます。

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)

日付を RFC 2822 形式の文字列で返します。例:

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.

バージョン 3.3 で追加.

email.utils.decode_rfc2231(s)

RFC 2231 に従って文字列 s をデコードします。

email.utils.encode_rfc2231(s, charset=None, language=None)

RFC 2231 に従って s をエンコードします。オプション引数 charset および language が与えられた場合、これらは文字セット名と言語名として使われます。もしこれらのどちらも与えられていない場合、 s はそのまま返されます。 charset は与えられているが language が与えられていない場合、文字列 s は language の空文字列を使ってエンコードされます。

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')

ヘッダのパラメータが RFC 2231 形式でエンコードされている場合、 Message.get_param は 3 要素からなるタプルを返すことがあります。ここには、そのパラメータの文字セット、言語、および値の順に格納されています。 collapse_rfc2231_value() はこのパラメータをひとつの Unicode 文字列にまとめます。オプション引数 errors は str の encode() メソッドの引数 errors に渡されます。このデフォルト値は 'replace' となっています。オプション引数 fallback_charset は、もし RFC 2231 ヘッダの使用している文字セットが Python の知っているものではなかった場合の非常用文字セットとして使われます。デフォルトでは、この値は 'us-ascii' です。

便宜上、 collapse_rfc2231_value() に渡された引数 value がタプルでない場合には、これは文字列でなければなりません。その場合にはクォートを除いた文字列を返します。

email.utils.decode_params(params)

RFC 2231 に従って引数のリストをデコードします。 params は (content-type, string-value) のような形式の 2 要素タプルです。

脚注

[1] 注意: この時間帯のオフセット値は time.timezone の値と符号が逆です。これは time.timezone が POSIX 標準に準拠しているのに対して、こちらは RFC 2822 に準拠しているからです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


email.iterators: イテレータ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »

email.iterators: イテレータ

ソースコード: 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)

Prints an indented representation of the content types of the message object structure. For example:

>>> msg = email.message_from_file(somefile)
>>> _structure(msg)
multipart/mixed
    text/plain
    text/plain
    multipart/digest
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
    text/plain

Optional fp is a file-like object to print the output to. It must be suitable for Python's print() function. level is used internally. include_default, if true, prints the default type as well.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »
  • email --- 電子メールと MIME 処理のためのパッケージ »


json --- JSON エンコーダおよびデコーダ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »

json --- JSON エンコーダおよびデコーダ

ソースコード: Lib/json/__init__.py

JSON (JavaScript Object Notation) は、 RFC 7159 ( RFC 4627 を obsolete) と ECMA-404 によって定義された軽量のデータ交換用のフォーマットです。 JavaScript のオブジェクトリテラル記法に由来しています (JavaScript の厳密なサブセットではありませんが [1])。

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 json.JSONEncoder.default(self, 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 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) ならば、コンテナ型の循環参照チェックが省かれ、循環参照があれば OverflowError (またはもっと悪い結果) に終わります。

allow_nan が偽 (デフォルトは True) の場合、許容範囲外の float 値 (nan, inf, -inf) を JSON 仕様を厳格に守って 直列化すると、ValueError になります。 allow_non が真の場合は、 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)

Deserialize fp (a .read()-supporting text file or binary file containing a JSON document) to a Python object using this conversion table.

object_hook はオプションの関数で、任意のオブジェクトリテラルがデコードされた結果 (dict) に対し呼び出されます。 object_hook の返り値は dict の代わりに使われます。この機能は独自のデコーダ (例えば JSON-RPC クラスヒンティング) を実装するのに使えます。

object_pairs_hook is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.

バージョン 3.1 で変更: object_pairs_hook のサポートが追加されました。

parse_float は、もし指定されれば、全てのデコードされる JSON の浮動小数点数文字列に対して呼ばれます。デフォルトでは、 float(num_str) と等価です。これは JSON 浮動小数点数に対して他のデータ型やパーサ (たとえば decimal.Decimal) を使うのに使えます。

parse_int は、もし指定されれば、全てのデコードされる JSON の整数文字列に対して呼ばれます。デフォルトでは、 int(num_str) と等価です。これは JSON 整数に対して他のデータ型やパーサ (たとえば float) を使うのに使えます。

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 can now be a binary file. The input encoding should be UTF-8, UTF-16 or UTF-32.

json.loads(s, *, encoding=None, 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 オブジェクトへ脱直列化します。

無視される非推奨の引数 encoding を除いて、その他の引数は load() のものと同じ意味です。

脱直列化しようとしているデータが不正な JSON ドキュメントだった場合、 JSONDecodeError が送出されます。

バージョン 3.6 で変更: s には bytes 型と bytearray 型も使えるようになりました。 入力エンコーディングは UTF-8, UTF-16, UTF-32 のいずれかでなければなりません。

エンコーダとデコーダ

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 クラスヒンティングをサポートするような) を提供するのに使えます。

object_pairs_hook, if specified will be called with the result of every JSON object decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.

バージョン 3.1 で変更: object_pairs_hook のサポートが追加されました。

parse_float は、もし指定されれば、全てのデコードされる JSON の浮動小数点数文字列に対して呼ばれます。デフォルトでは、 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 (デフォルト) ならば、リスト、辞書および自作でエンコードしたオブジェクトは循環参照がないかエンコード中にチェックされ、無限再帰 (これは OverflowError を引き起こします) を防止します。 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 を送出するために) 呼び出すかします。

たとえば、任意のイテレータをサポートするために、次のように実装します:

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 json.JSONEncoder.default(self, 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 に対応する列です。

バージョン 3.5 で追加.

標準への準拠と互換性

JSON 形式の仕様は RFC 7159 と 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 によって規定された古いバージョンの JSON では、JSON テキストのトップレベルの値は JSON オブジェクトか配列(Python での dict か list)であることを要求していて、JSON の null, boolean, number, string であることは許されていませんでしたが、この制限は RFC 7159 により取り払われました。このモジュールはこの制限を持っていませんし、シリアライザでもデシリアライズでも、一度としてこの制限で実装されたことはありません。

それにも関わらず、相互運用可能性を最大化したいならば、あなた自身の手で自発的にその制約に忠実に従いたいと思うでしょう。

実装の制限

いくつかの JSON デシリアライザの実装は、以下の制限を設定することがあります。

  • 受け入れられる JSON テキストのサイズ
  • JSON オブジェクトと配列のネストの最大の深さ
  • JSON 数値の範囲と精度
  • JSON 文字列の内容と最大の長さ

このモジュールは関連する Python データ型や Python インタプリタ自身の制約の世界を超えたそのような制約を強要はしません。

JSON にシリアライズする際には、あなたの JSON を消費する側のアプリケーションが持つ当該制約に思いを馳せてください。とりわけJSON 数値を IEEE 754 倍精度浮動小数にデシリアライズする際の問題はありがちで、すなわちその有効桁数と精度の制限の影響を受けます。これは、極端に大きな値を持った Python int をシリアライズするとき、あるいは decimal.Decimal のような "風変わりな" 数値型をシリアライズするとき、に特に関係があります。

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

ソースコード: 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

辞書の出力を、キーのアルファベット順にソートします。

バージョン 3.5 で追加.

-h, --help

ヘルプメッセージを出力します

脚注

[1] RFC 7159 正誤表 で述べられている通り、JSON は (ECMAScript Edition 5.1 の) JavaScript とは逆に、 U+2028 (LINE SEPARATOR) と U+2029 (PARAGRAPH SEPARATOR) が文字列内に含まれることを許容しています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネット上のデータの操作 »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »

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

ソースコード: Lib/mailcap.py

mailcap ファイルは、メールリーダや Web ブラウザのような MIME 対応のアプリケーションが、異なる MIME タイプのファイルにどのように反応するかを設定するために使われます ("mailcap" の名前は "mail capability" から取られました)。例えば、ある mailcap ファイルに video/mpeg; xmpeg %s のような行が入っていたとします。ユーザが email メッセージや Web ドキュメント上でその MIME タイプ video/mpeg に遭遇すると、 %s はファイル名 (通常テンポラリファイルに属するものになります) に置き換えられ、ファイルを閲覧するためにxmpeg プログラムが自動的に起動されます。

mailcap の形式は RFC 1524, "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 を参照してください。

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() はこれらの条件を自動的にチェックし、チェックが失敗したエントリを読み飛ばします。

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'})

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネット上のデータの操作 »


mailbox --- 様々な形式のメールボックス操作

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »

mailbox --- 様々な形式のメールボックス操作

ソースコード: Lib/mailbox.py

このモジュールでは二つのクラス Mailbox および Message をディスク上のメールボックスとそこに収められたメッセージへのアクセスと操作のために定義しています。 Mailbox は辞書のようなキーからメッセージへの対応付けを提供しています。 Message は email.message モジュールの Message を拡張して形式ごとの状態と振る舞いを追加しています。サポートされるメールボックスの形式は Maildir, mbox, MH, Babyl, MMDF です。

参考

email モジュール
メッセージの表現と操作。

Mailbox オブジェクト

class mailbox.Mailbox

メールボックス。内容を確認したり変更したりできます。

Mailbox 自体はインタフェースを定義し形式ごとのサブクラスに継承されるように意図されたもので、インスタンス化されることは想定されていません。インスタンス化したいならばサブクラスを代わりに使うべきです。

Mailbox のインタフェースは辞書風で、小さなキーがメッセージに対応します。キーは対象となる Mailbox インスタンスが発行するもので、そのインスタンスに対してのみ意味を持ちます。一つのキーは一つのメッセージにひも付けられ、その対応はメッセージが他のメッセージで置き換えられるような更新をされたあとも続きます。

メッセージを Mailbox インスタンスに追加するには集合風のメソッド add() を使います。また削除は del 文または集合風の remove() や discard() を使って行ないます。

Mailbox インタフェースのセマンティクスと辞書のそれとは注意すべき違いがあります。メッセージは、要求されるたびに新しい表現(典型的には Message インスタンス)が現在のメールボックスの状態に基づいて生成されます。同様に、メッセージが Mailbox インスタンスに追加される時も、渡されたメッセージ表現の内容がコピーされます。どちらの場合も Mailbox インスタンスにメッセージ表現への参照は保たれません。

デフォルトの Mailbox イテレータはメッセージ表現ごとに繰り返すもので、辞書のイテレータのようにキーごとの繰り返しではありません。さらに、繰り返し中のメールボックスを変更することは安全であり整合的に定義されています。イテレータが作られた後にメールボックスに追加されたメッセージはそのイテレータからは見えません。そのイテレータが yield するまえにメールボックスから削除されたメッセージは黙ってスキップされますが、イテレータからのキーを使ったときにはそのキーに対応するメッセージが削除されているならば KeyError を受け取ることになります。

警告

十分な注意を、何か他のプロセスによっても同時に変更される可能性のあるメールボックスを更新する時は、払わなければなりません。そのようなタスクをこなすのに最も安全なメールボックス形式は Maildir で、 mbox のような単一ファイルの形式を並行した書き込みに利用するのは避けるように努力しましょう。メールボックスを更新する場面では、 必ず lock() と unlock() メソッドを、ファイル内のメッセージを読んだり書き込んだり削除したりといった操作をする 前 に、呼び出してロックします。メールボックスをロックし損なうと、メッセージを失ったりメールボックス全体をぐちゃぐちゃにしたりする羽目に陥ります。

Mailbox インスタンスには次のメソッドがあります:

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()
keys()

iterkeys() として呼び出されると全てのキーについてのイテレータを返しますが、 keys() として呼び出されるとキーのリストを返します。

itervalues()
__iter__()
values()

itervalues() または __iter__() として呼び出されると全てのメッセージの表現についてのイテレータを返しますが、 values() として呼び出されるとその表現のリストを返します。メッセージは適切な形式ごとの Message サブクラスのインスタンスとして表現されるのが普通ですが、 Mailbox インスタンスが初期化されるときに指定すればお好みのメッセージファクトリを使うこともできます。

注釈

__iter__() は辞書のそれのようにキーについてのイテレータではありません。

iteritems()
items()

(key, message) ペア、ただし key はキーで message はメッセージ表現、のイテレータ(iteritems() として呼び出された場合)、またはリスト(items() として呼び出された場合)を返します。メッセージは適切な形式ごとの Message サブクラスのインスタンスとして表現されるのが普通ですが、 Mailbox インスタンスが初期化されるときに指定すればお好みのメッセージファクトリを使うこともできます。

get(key, default=None)
__getitem__(key)

key に対応するメッセージの表現を返します。対応するメッセージが存在しない場合、 get() として呼び出されたなら default を返しますが、 __getitem__() として呼び出されたなら KeyError 例外が送出されます。メッセージは適切な形式ごとの Message サブクラスのインスタンスとして表現されるのが普通ですが、 Mailbox スタンスが初期化されるときに指定すればお好みのメッセージファクトリを使うこともできます。

get_message(key)

key に対応するメッセージの表現を形式ごとの Message サブクラスのインスタンスとして返します。もし対応するメッセージが存在しなければ KeyError 例外が送出されます。

get_bytes(key)

key に対応するメッセージのバイト列を返すか、そのようなメッセージが存在しない場合は KeyError 例外を送出します。

バージョン 3.2 で追加.

get_string(key)

key に対応するメッセージの文字列表現を返すか、そのようなメッセージが存在しない場合は KeyError 例外を送出します。このメッセージは email.message.Message を通して処理されて7ビットクリーンな表現へ変換されます。

get_file(key)

key に対応するメッセージの表現をファイル風表現として返します。もし対応するメッセージが存在しなければ KeyError 例外が送出されます。ファイル風オブジェクトはバイナリモードで開かれているように振る舞います。このファイルは必要がなくなったら閉じなければなりません。

バージョン 3.2 で変更: ファイルオブジェクトは実際はバイナリファイルです; 以前は誤ってテキストモードで返されていました。 また、現在ファイル風オブジェクトはコンテキストマネージャプロトコルをサポートしています: with 文を用いることで自動的にファイルを閉じることができます。

注釈

他の表現方法とは違い、ファイル風オブジェクトはそれを作り出した Mailbox インスタンスやそれが基づいているメールボックスと独立である必要がありません。より詳細な説明は各サブクラスごとにあります。

__contains__(key)

key がメッセージに対応していれば True を、そうでなければ False を返します。

__len__()

メールボックス中のメッセージ数を返します。

clear()

メールボックスから全てのメッセージを削除します。

pop(key, default=None)

key に対応するメッセージの表現を返します。メッセージは適切な形式ごとの Message サブクラスのインスタンスとして表現されるのが普通ですが、 Mailbox インスタンスが初期化されるときに指定すればお好みのメッセージファクトリを使うこともできます。

popitem()

任意に選んだ (key, message) ペアを返します。ただしここで key はキーで message はメッセージ表現です。もしメールボックスが空ならば、 KeyError 例外を送出します。メッセージは適切な形式ごとの Message サブクラスのインスタンスとして表現されるのが普通ですが、 Mailbox インスタンスが初期化されるときに指定すればお好みのメッセージファクトリを使うこともできます。

update(arg)

引数 arg は key から message へのマッピングまたは (key, message) ペアのイテレート可能オブジェクトでなければなりません。メールボックスは、各 key と message のペアについて __setitem__() を使ったかのように key に対応するメッセージが message になるように更新されます。 __setitem__() と同様に、 key は既存のメールボックス中のメッセージに対応しているものでなければならず、そうでなければ KeyError が送出されます。ですから、一般的には arg に Mailbox インスタンスを渡すのは間違いです。

注釈

辞書と違い、キーワード引数はサポートされていません。

flush()

保留されている変更をファイルシステムに書き込みます。 Mailbox のサブクラスによっては変更はいつも直ちにファイルに書き込まれ flush() は何もしないということもありますが、それでもこのメソッドを呼ぶように習慣付けておきましょう。

lock()

メールボックスの排他的アドバイザリロックを取得し、他のプロセスが変更しないようにします。ロックが取得できない場合 ExternalClashError が送出されます。ロック機構はメールボックス形式によって変わります。メールボックスの内容に変更を加えるときは いつも ロックを掛けるべきです。

unlock()

メールボックスのロックが存在する場合は解放します。

close()

メールボックスをフラッシュし、必要ならばアンロックし、開いているファイルを閉じます。 Mailbox サブクラスによっては何もしないこともあります。

Maildir

class mailbox.Maildir(dirname, factory=None, create=True)

Maildir 形式のメールボックスのための Mailbox のサブクラス。パラメータ factory は呼び出し可能オブジェクトで (バイナリモードで開かれているかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表現を返すものです。 factory が None ならば、 MaildirMessage がデフォルトのメッセージ表現として使われます。 create が True ならばメールボックスが存在しないときには作成します。

path ではなく dirname と命名される歴史的な理由のためです。

Maildir はディレクトリ型のメールボックス形式でメール転送エージェント qmail 用に発明され、現在では多くの他のプログラムでもサポートされているものです。Maildir メールボックス中のメッセージは共通のディレクトリ構造の下で個別のファイルに保存されます。このデザインにより、Maildir メールボックスは複数の無関係のプログラムからデータを失うことなくアクセスしたり変更したりできます。そのためロックは不要です。

Maildir メールボックスには三つのサブディレクトリ tmp, new, cur があります。メッセージはまず tmp サブディレクトリに瞬間的に作られた後、 new サブディレクトリに移動されて配送を完了します。メールユーザエージェントが引き続いて cur サブディレクトリにメッセージを移動しメッセージの状態についての情報をファイル名に追加される特別な "info" セクションに保存することができます。

Courier メール転送エージェントによって導入されたスタイルのフォルダもサポートされます。主たるメールボックスのサブディレクトリは '.' がファイル名の先頭であればフォルダと見なされます。フォルダ名は Maildir によって先頭の '.' を除いて表現されます。各フォルダはまた Maildir メールボックスですがさらにフォルダを含むことはできません。その代わり、論理的包含関係は例えば "Archived.2005.07" のような '.' を使ったレベル分けで表わされます。

注釈

本来の Maildir 仕様ではある種のメッセージのファイル名にコロン (':') を使う必要があります。しかしながら、オペレーティングシステムによってはこの文字をファイル名に含めることができないことがあります。そういった環境で Maildir のような形式を使いたい場合、代わりに使われる文字を指定する必要があります。感嘆符 ('!') を使うのが一般的な選択です。以下の例を見てください:

import mailbox
mailbox.Maildir.colon = '!'

colon 属性はインスタンスごとにセットしても構いません。

Maildir インスタンスには Mailbox の全てのメソッドに加え以下のメソッドもあります:

list_folders()

全てのフォルダ名のリストを返します。

get_folder(folder)

名前が folder であるフォルダを表わす Maildir インスタンスを返します。そのようなフォルダが存在しなければ NoSuchMailboxError 例外が送出されます。

add_folder(folder)

名前が folder であるフォルダを作り、それを表わす Maildir インスタンスを返します。

remove_folder(folder)

名前が folder であるフォルダを削除します。もしフォルダに一つでもメッセージが含まれていれば NotEmptyError 例外が送出されフォルダは削除されません。

clean()

過去36時間以内にアクセスされなかったメールボックス内の一時ファイルを削除します。Maildir 仕様はメールを読むプログラムはときどきこの作業をすべきだとしています。

Maildir で実装された Mailbox のいくつかのメソッドには特別な注意が必要です:

add(message)
__setitem__(key, message)
update(arg)

警告

これらのメソッドは一意的なファイル名をプロセスIDに基づいて生成します。複数のスレッドを使う場合は、同じメールボックスを同時に操作しないようにスレッド間で調整しておかないと検知されない名前の衝突が起こりメールボックスを壊すかもしれません。

flush()

Maildir メールボックスへの変更は即時に適用されるので、このメソッドは何もしません。

lock()
unlock()

Maildir メールボックスはロックをサポート(または要求)しないので、このメソッドは何もしません。

close()

Maildir インスタンスは開いたファイルを保持しませんしメールボックスはロックをサポートしませんので、このメソッドは何もしません。

get_file(key)

ホストのプラットフォームによっては、返されたファイルが開いている間、元になったメッセージを変更したり削除したりできない場合があります。

参考

qmail の maildir マニュアルページ
Maildir 形式のオリジナルの仕様。
Using maildir format
Maildir 形式の発明者による注意書き。更新された名前生成規則と "info" の解釈についても含まれます。
Courier の maildir マニュアルページ
Maildir 形式のもう一つの仕様。フォルダをサポートする一般的な拡張について記述されています。

mbox

class mailbox.mbox(path, factory=None, create=True)

mbox 形式のメールボックスのための Mailbox のサブクラス。パラメータ factory は呼び出し可能オブジェクトで (バイナリモードで開かれているかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表現を返すものです。 factory が None ならば、 mboxMessage がデフォルトのメッセージ表現として使われます。 create が True ならばメールボックスが存在しないときには作成します。

mbox 形式は Unixシステム上でメールを保存する古くからある形式です。mbox メールボックスでは全てのメッセージが一つのファイルに保存されておりそれぞれのメッセージは "From " という5文字で始まる行を先頭に付けられています。

mbox 形式には幾つかのバリエーションがあり、それぞれオリジナルの形式にあった欠点を克服すると主張しています。互換性のために、 mbox はオリジナルの(時に mboxo と呼ばれる) 形式を実装しています。すなわち、 Content-Length ヘッダはもしあっても無視され、メッセージのボディにある行頭の "From " はメッセージを保存する際に ">From " に変換されますが、この ">From " は読み出し時にも "From " に変換されません。

mbox で実装された Mailbox のいくつかのメソッドには特別な注意が必要です:

get_file(key)

mbox インスタンスに対し flush() や close() を呼び出した後でファイルを使用すると予期しない結果を引き起こしたり例外が送出されたりすることがあります。

lock()
unlock()

3種類のロック機構が使われます --- ドットロッキングと、もし使用可能ならば flock() と lockf() システムコールです。

参考

qmail の mbox マニュアルページ
mbox 形式の仕様および種々のバリエーション。
tin の mbox マニュアルページ
もう一つの mbox 形式の仕様でロックについての詳細を含む。
Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad
バリエーションの一つではなくオリジナルの mbox を使う理由。
"mbox" は相互に互換性を持たないいくつかのメールボックスフォーマットの集まりです
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 というファイルで定義されます。

MH クラスは MH メールボックスを操作しますが、 mh の動作の全てを模倣しようとはしていません。特に、 mh が状態と設定を保存する context や .mh_profile といったファイルは書き換えませんし影響も受けません。

MH インスタンスには Mailbox の全てのメソッドの他に次のメソッドがあります:

list_folders()

全てのフォルダ名のリストを返します。

get_folder(folder)

folder という名前のフォルダを表わす MH インスタンスを返します。もしフォルダが存在しなければ NoSuchMailboxError 例外が送出されます。

add_folder(folder)

folder という名前のフォルダを作成し、それを表わす MH インスタンスを返します。

remove_folder(folder)

名前が folder であるフォルダを削除します。もしフォルダに一つでもメッセージが含まれていれば NotEmptyError 例外が送出されフォルダは削除されません。

get_sequences()

folder という名前のフォルダを削除します。フォルダにメッセージが一つでも残っていれば、NotEmptyError 例外が送出されフォルダは削除されません。

set_sequences(sequences)

シーケンス名をキーのリストに対応付ける辞書を返します。シーケンスが一つもなければ空の辞書を返します。

pack()

メールボックス中のシーケンスを get_sequences() で返されるような名前とキーのリストを対応付ける辞書 sequences に基づいて再定義します。

注釈

番号付けの間隔を詰める必要に応じてメールボックス中のメッセージの名前を付け替えます。シーケンスのリストのエントリもそれに応じて更新されます。

既に発行されたキーはこの操作によって無効になるのでそれ以降使ってはなりません:

remove(key)
__delitem__(key)
discard(key)

これらのメソッドはメッセージを直ちに削除します。名前の前にコンマを付加してメッセージに削除の印を付けるという MH の規約は使いません。

lock()
unlock()

3種類のロック機構が使われます --- ドットロッキングと、もし使用可能ならば flock() と lockf() システムコールです。 MH メールボックスに対するロックとは .mh_sequences のロックと、それが影響を与える操作中だけの個々のメッセージファイルに対するロックを意味します。

get_file(key)

ホストプラットフォームにより、ファイルが開かれたままの場合はメッセージを削除することができない場合があります。

flush()

MH メールボックスへの変更は即時に適用されますのでこのメソッドは何もしません。

close()

MH インスタンスは開いたファイルを保持しませんのでこのメソッドは unlock() と同じです。

参考

nmh - Message Handling System
mh の改良版である nmh のホームページ。
MH & nmh: Email for Users & Programmers
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 インスタンスには Mailbox の全てのメソッドの他に次のメソッドがあります:

get_labels()

メールボックスで使われているユーザが定義した全てのラベルのリストを返します。

注釈

メールボックスにどのようなラベルが存在するかを決めるのに、Babyl オプションセクションのリストを参考にせず、実際のメッセージを捜索しますが、Babyl セクションもメールボックスが変更されたときにはいつでも更新されます。

Babyl で実装された Mailbox のいくつかのメソッドには特別な注意が必要です:

get_file(key)

Babyl メールボックスにおいて、メッセージのヘッダはボディと繋がって格納されていません。ファイル風の表現を生成するために、ヘッダとボディがファイルと同じ API を持つ io.BytesIO インスタンスに一緒にコピーされます。その結果、ファイル風オブジェクトは元にしているメールボックスとは真に独立していますが、文字列表現と比べてメモリーを節約することにはなりません。

lock()
unlock()

3種類のロック機構が使われます --- ドットロッキングと、もし使用可能ならば flock() と lockf() システムコールです。

参考

Format of Version 5 Babyl Files
Babyl 形式の仕様。
Reading Mail with Rmail
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 " には変えられません。それは追加されたメッセージ区切りによって新たなメッセージの開始と見間違うことが避けられるからです。

MMDF で実装された Mailbox のいくつかのメソッドには特別な注意が必要です:

get_file(key)

MMDF インスタンスに対し flush() や close() を呼び出した後でファイルを使用すると予期しない結果を引き起こしたり例外が送出されたりすることがあります。

lock()
unlock()

3種類のロック機構が使われます --- ドットロッキングと、もし使用可能ならば flock() と lockf() システムコールです。

参考

mmdf man page from tin
ニュースリーダ tin のドキュメント中の MMDF 形式仕様。
MMDF
Multichannel Memorandum Distribution Facility についてのウィキペディアの記事。

Message objects

class mailbox.Message(message=None)

email.message モジュールの Message のサブクラス。 mailbox.Message のサブクラスはメールボックス形式ごとの状態と動作を追加します。

message が省略された場合、新しいインスタンスはデフォルトの空の状態で生成されます。 message が email.message.Message インスタンスならばその内容がコピーされます。さらに、 message が Message インスタンスならば、形式固有の情報も可能な限り変換されます。 message が文字列かバイト列またはファイルならば、読まれ解析されるべき RFC 2822 準拠のメッセージを含んでいなければなりません。ファイルはバイナリモードで開かれているべきですが、後方互換性のためテキストモードファイルも受け付けます。

サブクラスにより提供される形式ごとの状態と動作は様々ですが、一般に或るメールボックスに固有のものでないプロパティだけがサポートされます(おそらくプロパティのセットはメールボックス形式ごとに固有でしょうが)。例えば、単一ファイルメールボックス形式におけるファイルオフセットやディレクトリ式メールボックス形式におけるファイル名は保持されません、というのもそれらは元々のメールボックスにしか適用できないからです。しかし、メッセージがユーザに読まれたかどうかあるいは重要だとマークされたかどうかという状態は保持されます、というのはそれらはメッセージ自体に適用されるからです。

Mailbox インスタンスを使って取得したメッセージを表現するのに Message インスタンスが使われなければいけないとは要求していません。ある種の状況では Message による表現を生成するのに必要な時間やメモリーが受け入れられないこともあります。そういった状況では Mailbox インスタンスは文字列やファイル風オブジェクトの表現も提供できますし、 Mailbox インスタンスを初期化する際にメッセージファクトリーを指定することもできます。

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 インスタンスは以下のメソッドを提供します:

get_subdir()

"new" (メッセージが new サブディレクトリに保存されるべき場合) または "cur" (メッセージが cur サブディレクトリに保存されるべき場合)のどちらかを返します。

注釈

メッセージは通常メールボックスがアクセスされた後、メッセージが読まれたかどうかに関わらず new から cur に移動されます。メッセージ msg は "S" in msg.get_flags() が 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 をセットします。

MaildirMessage インスタンスが mboxMessage や MMDFMessage のインスタンスに基づいて生成されるとき、 Status および X-Status ヘッダは省かれ以下の変換が行われます:

結果の状態 | mboxMessage または MMDFMessage の状態
"cur" サブディレクトリ | O フラグ
F フラグ | F フラグ
R フラグ | A フラグ
S フラグ | R フラグ
T フラグ | D フラグ

MaildirMessage インスタンスが MHMessage インスタンスに基づいて生成されるとき、以下の変換が行われます:

結果の状態 | MHMessage の状態
"cur" サブディレクトリ | "unseen" シーケンス
"cur" サブディレクトリおよび S フラグ | "unseen" シーケンス無し
F フラグ | "flagged" シーケンス
R フラグ | "replied" シーケンス

MaildirMessage インスタンスが BabylMessage インスタンスに基づいて生成されるとき、以下の変換が行われます:

結果の状態 | 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 インスタンスは以下のメソッドを提供します:

get_from()

mbox メールボックスのメッセージの開始を示す "From " 行を表わす文字列を返します。先頭の "From " および末尾の改行は含まれません。

set_from(from_, time_=None)

"From " 行を from_ にセットします。 from_ は先頭の "From " や末尾の改行を含まない形で指定しなければなりません。利便性のために、 time_ を指定して適切に整形して from_ に追加させることができます。 time_ を指定する場合、それは time.struct_time インスタンス、 time.strftime() に渡すのに適したタプル、または True (この場合 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文字以上の文字列を指定すればできます。

mboxMessage インスタンスが MaildirMessage インスタンスに基づいて生成されるとき、 MaildirMessage インスタンスの配送日時に基づいて "From " 行が作り出され、次の変換が行われます:

結果の状態 | MaildirMessage の状態
R フラグ | S フラグ
O フラグ | "cur" サブディレクトリ
D フラグ | T フラグ
F フラグ | F フラグ
A フラグ | R フラグ

mboxMessage インスタンスが MHMessage インスタンスに基づいて生成されるとき、以下の変換が行われます:

結果の状態 | MHMessage の状態
R フラグおよび O フラグ | "unseen" シーケンス無し
O フラグ | "unseen" シーケンス
F フラグ | "flagged" シーケンス
A フラグ | "replied" シーケンス

mboxMessage インスタンスが BabylMessage インスタンスに基づいて生成されるとき、以下の変換が行われます:

結果の状態 | BabylMessage の状態
R フラグおよび O フラグ | "unseen" ラベル無し
O フラグ | "unseen" ラベル
D フラグ | "deleted" ラベル
A フラグ | "answered" ラベル

mboxMessage インスタンスが MMDFMessage インスタンスに基づいて生成されるとき、"From " 行はコピーされ全てのフラグは直接対応します:

結果の状態 | 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 インスタンスは以下のメソッドを提供します:

get_sequences()

このメッセージを含むシーケンスの名前のリストを返す。

set_sequences(sequences)

このメッセージを含むシーケンスのリストをセットする。

add_sequence(sequence)

sequence をこのメッセージを含むシーケンスのリストに追加する。

remove_sequence(sequence)

sequence をこのメッセージを含むシーケンスのリストから除く。

MHMessage インスタンスが MaildirMessage インスタンスに基づいて生成されるとき、以下の変換が行われます:

結果の状態 | MaildirMessage の状態
"unseen" シーケンス | S フラグ無し
"replied" シーケンス | R フラグ
"flagged" シーケンス | F フラグ

MHMessage インスタンスが mboxMessage や MMDFMessage のインスタンスに基づいて生成されるとき、 Status および X-Status ヘッダは省かれ以下の変換が行われます:

結果の状態 | mboxMessage または MMDFMessage の状態
"unseen" シーケンス | R フラグ無し
"replied" シーケンス | A フラグ
"flagged" シーケンス | F フラグ

MHMessage インスタンスが BabylMessage インスタンスに基づいて生成されるとき、以下の変換が行われます:

結果の状態 | BabylMessage の状態
"unseen" シーケンス | "unseen" ラベル
"replied" シーケンス | "answered" ラベル

BabylMessage

class mailbox.BabylMessage(message=None)

Babyl 固有の動作をするメッセージ。引数 message は Message のコンストラクタと同じ意味を持ちます。

ある種のメッセージラベルは アトリビュート と呼ばれ、規約により特別な意味が与えられています。アトリビュートは以下の通りです:

ラベル | 説明
unseen | 読んではいないが既にMUAに見つけられている
deleted | 削除予定とされたもの
filed | 他のファイルまたはメールボックスにコピーされた
answered | 返答されたもの
forwarded | 転送された
edited | ユーザによって変更された
resent | 再送された

デフォルトでは Rmail は可視ヘッダのみ表示します。 BabylMessage クラスはしかし、オリジナルヘッダをより完全だという理由で使います。可視ヘッダは望むならそのように指示してアクセスすることができます。

BabylMessage インスタンスは以下のメソッドを提供します:

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()

BabylMessage インスタンスのオリジナルヘッダが変更されたとき、可視ヘッダは自動的に対応して変更されるわけではありません。このメソッドは可視ヘッダを以下のように更新します。対応するオリジナルヘッダのある可視ヘッダはオリジナルヘッダの値がセットされます。対応するオリジナルヘッダの無い可視ヘッダは除去されます。そして、オリジナルヘッダにあって可視ヘッダに無い Date 、 From 、 Reply-To 、 To 、 CC 、 Subject は可視ヘッダに追加されます。

BabylMessage インスタンスが MaildirMessage インスタンスに基づいて生成されるとき、以下の変換が行われます:

結果の状態 | MaildirMessage の状態
"unseen" ラベル | S フラグ無し
"deleted" ラベル | T フラグ
"answered" ラベル | R フラグ
"forwarded" ラベル | P フラグ

BabylMessage インスタンスが mboxMessage や MMDFMessage のインスタンスに基づいて生成されるとき、 Status および X-Status ヘッダは省かれ以下の変換が行われます:

結果の状態 | mboxMessage または MMDFMessage の状態
"unseen" ラベル | R フラグ無し
"deleted" ラベル | D フラグ
"answered" ラベル | A フラグ

BabylMessage インスタンスが MHMessage インスタンスに基づいて生成されるとき、以下の変換が行われます:

結果の状態 | 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 インスタンスは mboxMessage インスタンスと同一の以下のメソッドを提供します:

get_from()

mbox メールボックスのメッセージの開始を示す "From " 行を表わす文字列を返します。先頭の "From " および末尾の改行は含まれません。

set_from(from_, time_=None)

"From " 行を from_ にセットします。 from_ は先頭の "From " や末尾の改行を含まない形で指定しなければなりません。利便性のために、 time_ を指定して適切に整形して from_ に追加させることができます。 time_ を指定する場合、それは time.struct_time インスタンス、 time.strftime() に渡すのに適したタプル、または True (この場合 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文字以上の文字列を指定すればできます。

MMDFMessage インスタンスが MaildirMessage インスタンスに基づいて生成されるとき、"From"行が MaildirMessage インスタンスの配信日をもとに生成され、以下の変換が行われます:

結果の状態 | MaildirMessage の状態
R フラグ | S フラグ
O フラグ | "cur" サブディレクトリ
D フラグ | T フラグ
F フラグ | F フラグ
A フラグ | R フラグ

MMDFMessage インスタンスが MHMessage インスタンスに基づいて生成されるとき、以下の変換が行われます:

結果の状態 | MHMessage の状態
R フラグおよび O フラグ | "unseen" シーケンス無し
O フラグ | "unseen" シーケンス
F フラグ | "flagged" シーケンス
A フラグ | "replied" シーケンス

MMDFMessage インスタンスが BabylMessage インスタンスに基づいて生成されるとき、以下の変換が行われます:

結果の状態 | BabylMessage の状態
R フラグおよび O フラグ | "unseen" ラベル無し
O フラグ | "unseen" ラベル
D フラグ | "deleted" ラベル
A フラグ | "answered" ラベル

MMDFMessage インスタンスが mboxMessage インスタンスに基づいて生成されるとき、"From"行がコピーされ、全てのフラグが直接対応します:

結果の状態 | mboxMessage の状態
R フラグ | R フラグ
O フラグ | O フラグ
D フラグ | D フラグ
F フラグ | F フラグ
A フラグ | A フラグ

例外

mailbox モジュールでは以下の例外クラスが定義されています:

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 --- ファイル名を MIME 型へマップする

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »

mimetypes --- ファイル名を MIME 型へマップする

ソースコード: Lib/mimetypes.py

mimetypes モジュールは、ファイル名あるいは URL と、ファイル名拡張子に関連付けられた MIME 型とを変換します。ファイル名から MIME 型へと、 MIME 型からファイル名拡張子への変換が提供されます; 後者の変換では符号化方式はサポートされていません。

このモジュールは、一つのクラスと多くの便利な関数を提供します。これらの関数がこのモジュールへの標準のインターフェースですが、アプリケーションによっては、そのクラスにも関係するかもしれません。

以下で説明されている関数は、このモジュールへの主要なインターフェースを提供します。たとえモジュールが初期化されていなくても、もしこれらの関数が、 init() がセットアップする情報に依存していれば、これらの関数は、 init() を呼びます。

mimetypes.guess_type(url, strict=True)

url で与えられるファイル名あるいは URL に基づいて、ファイルの型を推定します。戻り値は、タプル (type, encoding) です、ここで type は、もし型が(拡張子がないあるいは未定義のため)推定できない場合は、 None を、あるいは、 MIME content-type ヘッダ に利用できる、 'type/subtype' の形の文字列です。

encoding は、符合化方式がない場合は None を、あるいは、符号化に使われるプログラムの名前 (たとえば、 compress あるいは gzip)です。符号化方式は Content-Encoding ヘッダとして使うのに適しており、 Content-Transfer-Encoding ヘッダには適して いません 。マッピングはテーブル駆動です。符号化方式のサフィックスは大/小文字を区別します; データ型サフィックスは、最初大/小文字を区別して試し、それから大/小文字を区別せずに試します。

省略可能な strict 引数は、既知の MIME 型のリストとして認識されるものが、IANAに登録された 正式な型のみに限定されるかどうかを指定するフラグです。strict が True (デフォルト)の時は、IANA 型のみがサポートされます; strict が False のときは、いくつかの追加の、非標準ではあるが、一般的に使用される MIME 型も認識されます。

mimetypes.guess_all_extensions(type, strict=True)

type で与えられる MIME 型に基づいてファイルの拡張子を推定します。戻り値は、先頭のドット ('.')を含む、可能なファイル拡張子すべてを与える文字列のリストです。拡張子と特別なデータストリームとの関連付けは保証されませんが、 guess_type() によって MIME 型 type とマップされます。

省略可能な strict 引数は guess_type() 関数のものと同じ意味を持ちます。

mimetypes.guess_extension(type, strict=True)

type で与えられる MIME 型に基づいてファイルの拡張子を推定します。戻り値は、先頭のドット ('.')を含む、ファイル拡張子を与える文字列のリストです。拡張子と特別なデータストリームとの関連付けは保証されませんが、 guess_type() によって MIME 型 type とマップされます。もし type に対して拡張子が推定できない場合は、 None が返されます。

省略可能な strict 引数は guess_type() 関数のものと同じ意味を持ちます。

モジュールの動作を制御するために、いくつかの追加の関数とデータ項目が利用できます。

mimetypes.init(files=None)

内部のデータ構造を初期化します。もし files が与えられていれば、これはデフォルトの type map を増やすために使われる、一連のファイル名でなければなりません。もし省略されていれば、使われるファイル名は knownfiles から取られます。 Windows であれば、現在のレジストリの設定が読み込まれます。 files あるいは knownfiles 内の各ファイル名は、それ以前に現れる名前より優先されます。繰り返し init() を呼び出すことは許されています。

files に空リストを与えることで、システムのデフォルトが適用されるのを避けることが出来ます; 組み込みのリストから well-known な値だけが取り込まれます。

バージョン 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)

Load MIME type information from the Windows registry.

利用可能な環境: Windows 。

strict が True の時 (デフォルト) は、そのマッピングは標準 MIME 型のリストに、そうでなければ、非標準 MIME 型のリストに追加されます。

バージョン 3.2 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネット上のデータの操作 »


base64 --- Base16, Base32, Base64, Base85 データの符号化

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »

base64 --- Base16, Base32, Base64, Base85 データの符号化

ソースコード: Lib/base64.py

このモジュールはバイナリデータを印字可能な ASCII にエンコード関数、およびそのようなエンコードデータをバイナリにデコードする関数を提供します。それらは、 RFC 3548 が定義する Base16, Base32, Base64 のエンコーディング、デファクトスタンダードになっている Ascii85, Base85 のエンコーディングについてのエンコード、デコード関数です。

RFC 3548 エンコーディングは、email で安全に送信したり、 URL の一部として使ったり、あるいは HTTP POST リクエストの一部に含めるために用いるのに適しています。このエンコーディングで使われているアルゴリズムは uuencode プログラムで用いられているものとは同じではありません。

There are two interfaces provided by this module. The modern interface supports encoding bytes-like objects to ASCII bytes, and decoding bytes-like objects or strings containing ASCII to bytes. Both base-64 alphabets defined in RFC 3548 (normal, and URL- and filesystem-safe) are supported.

The legacy interface does not support decoding from strings, but it does provide functions for encoding and decoding to and from file objects. It only supports the Base64 standard alphabet, and it adds newlines every 76 characters as per RFC 2045. Note that if you are looking for RFC 2045 support you probably want to be looking at the email package instead.

バージョン 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 アルファベット集合が使われることを意味します。

base64.b64decode(s, altchars=None, validate=False)

Base64 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた bytes を返します。

オプション引数の altchars は最低でも 2 の長さをもつ bytes-like object または ASCII 文字列で (これ以降の文字は無視されます)、これは + と / の代わりに使われる代替アルファベットを指定します。

s が正しくパディングされていない場合は binascii.Error 例外を発生させます。

If validate is False (the default), characters that are neither in the normal base-64 alphabet nor the alternative alphabet are discarded prior to the padding check. If validate is True, these non-alphabet characters in the input result in a binascii.Error.

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)

Encode bytes-like object s using the URL- and filesystem-safe alphabet, which substitutes - instead of + and _ instead of / in the standard Base64 alphabet, and return the encoded bytes. The result can still contain =.

base64.urlsafe_b64decode(s)

Decode bytes-like object or ASCII string s using the URL- and filesystem-safe alphabet, which substitutes - instead of + and _ instead of / in the standard Base64 alphabet, and return the decoded bytes.

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 3548 は付加的なマッピングとして、数字の 0 (零) をアルファベットの O (オー) に、数字の 1 (壱) をアルファベットの I (アイ) または L (エル) に対応させることを許しています。オプション引数は map01 は、 None でないときは、数字の 1 をどの文字に対応づけるかを指定します (map01 が None でないとき、数字の 0 はつねにアルファベットの O (オー) に対応づけられます)。セキュリティ上の理由により、これはデフォルトでは None になっているため、 0 および 1 は入力として許可されていません。

s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、 binascii.Error 例外を発生させます。

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)

Encode the bytes-like object b using Ascii85 and return the encoded bytes.

foldspaces を使うと、4 つの連続した空白文字(ASCII 0x20)を 'btoa' によってサポートされている短い特殊文字 'y' に置き換えます。この機能は "標準" Ascii85 ではサポートされていません。

wrapcol は何文字ごとに改行文字 (b'\n') を挿入するかを制御します。ゼロでない場合、出力の各行はこの与えられた文字数を超えません。

pad を指定すると、エンコード前に入力が 4 の倍数になるようにパディングされます。なお、 btoa の実装は常にパディングします。

adobe を指定すると、エンコードしたバイトシーケンスを <~ と ~> で囲みます。これは Adobe の実装で使われています。

バージョン 3.4 で追加.

base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\v')

Decode the Ascii85 encoded bytes-like object or ASCII string b and return the decoded bytes.

foldspaces は、短い特殊文字 'y' を受け取って 4 つの連続した空白文字(ASCII 0x20)と解釈するかどうかを制御します。この機能は "標準" Ascii85 ではサポートされていません。

adobe で、入力シーケンスが Adobe Ascii85 (つまり <~ と ~> で囲まれている)かどうかを伝えます。

ignorechars には、入力に含まれていれば無視する文字で構成された bytes-like object または ASCII 文字列を指定してください。これは空白文字だけで構成されているべきです。デフォルトは ASCII における空白文字全てです。

バージョン 3.4 で追加.

base64.b85encode(b, pad=False)

Encode the bytes-like object b using base85 (as used in e.g. git-style binary diffs) and return the encoded bytes.

pad が真ならば、エンコードに先立って、バイト数が 4 の倍数となるように入力が b'\0' でパディングされます。

バージョン 3.4 で追加.

base64.b85decode(b)

base85でエンコードされた bytes-like object または ASCII 文字列の b をデコードし、デコードされた bytes を返します。パディングは、もしあれば、暗黙に削除されます。

バージョン 3.4 で追加.

レガシーなインターフェイスは以下のものを提供します:

base64.decode(input, output)

input ファイルの中身をデコードし、結果のバイナリデータを output ファイルに出力します。 input 、 output ともに file objects でなければなりません。 input は input.readline() が空バイト列を返すまで読まれます。

base64.decodebytes(s)

Decode the bytes-like object s, which must contain one or more lines of base64 encoded data, and return the decoded bytes.

バージョン 3.1 で追加.

base64.decodestring(s)

Deprecated alias of decodebytes().

バージョン 3.1 で非推奨.

base64.encode(input, output)

Encode the contents of the binary input file and write the resulting base64 encoded data to the output file. input and output must be file objects. input will be read until input.read() returns an empty bytes object. encode() inserts a newline character (b'\n') after every 76 bytes of the output, as well as ensuring that the output always ends with a newline, as per RFC 2045 (MIME).

base64.encodebytes(s)

Encode the bytes-like object s, which can contain arbitrary binary data, and return bytes containing the base64-encoded data, with newlines (b'\n') inserted after every 76 bytes of output, and ensuring that there is a trailing newline, as per RFC 2045 (MIME).

バージョン 3.1 で追加.

base64.encodestring(s)

Deprecated alias of encodebytes().

バージョン 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'

参考

モジュール binascii
ASCII からバイナリへ、バイナリから ASCII への変換をサポートするモジュール。
RFC 1521 - 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.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネット上のデータの操作 »


binhex --- binhex4 形式ファイルのエンコードおよびデコード

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »

binhex --- binhex4 形式ファイルのエンコードおよびデコード

ソースコード: Lib/binhex.py

このモジュールは binhex4 形式のファイルに対するエンコードやデコードを行います。binhex4 は Macintosh のファイルを ASCII で表現できるようにしたものです。データフォークだけが処理されます。

binhex モジュールでは以下の関数を定義しています:

binhex.binhex(input, output)

ファイル名 input のバイナリファイルをファイル名 output の binhex 形式ファイルに変換します。 output パラメタはファイル名でも (write() および close() メソッドをサポートするような) ファイル様オブジェクトでもかまいません。

binhex.hexbin(input, output)

binhex 形式のファイル input をデコードします。 input はファイル名でも、 read() および close() メソッドをサポートするようなファイル様オブジェクトでもかまいません。変換結果のファイルはファイル名 output になります。この引数が None なら、出力ファイルは binhex ファイルの中から復元されます。

以下の例外も定義されています:

exception binhex.Error

binhex 形式を使ってエンコードできなかった場合 (例えば、ファイル名が filename フィールドに収まらないくらい長かった場合など) や、入力が正しくエンコードされた binhex 形式のデータでなかった場合に送出される例外です。

参考

モジュール binascii
ASCII からバイナリへ、バイナリから ASCII への変換をサポートするモジュール。

注釈

別のより強力なエンコーダおよびデコーダへのインタフェースが存在します。詳しくはソースを参照してください。

非 Macintosh プラットフォームでテキストファイルをエンコードしたりデコードしたりする場合でも、古い Macintosh の改行文字変換 (行末をキャリッジリターンとする) が行われます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネット上のデータの操作 »


binascii --- バイナリデータと ASCII データとの間での変換

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »

binascii --- バイナリデータと ASCII データとの間での変換

binascii モジュールにはバイナリと ASCII コード化されたバイナリ表現との間の変換を行うための多数のメソッドが含まれています。通常、これらの関数を直接使う必要はなく、 uu 、 base64 や binhex といった、ラッパ (wrapper) モジュールを使うことになるでしょう。 binascii モジュールは C で書かれた高速な低水準関数を提供していて、それらは上記の高水準なモジュールで利用されます。

注釈

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 で変更: Added the backtick parameter.

binascii.a2b_base64(string)

base64 でエンコードされたデータのブロックをバイナリに変換し、変換後のバイナリデータを返します。一度に 1 行以上のデータを与えてもかまいません。

binascii.b2a_base64(data, *, newline=True)

バイナリデータを base64 でエンコードされた 1 行の ASCII 文字列に変換します。戻り値は変換後の 1 行の文字列で、newline が真の場合改行文字を含みます。この関数の出力は RFC 3548 を遵守します。

バージョン 3.6 で変更: パラメータに newline を追加しました。

binascii.a2b_qp(data, header=False)

quoted-printable 形式のデータをバイナリに変換し、バイナリデータを返します。一度に 1 行以上のデータを渡すことができます。オプション引数 header が与えられており、かつその値が真であれば、アンダースコアは空白文字にデコードされます。

binascii.b2a_qp(data, quotetabs=False, istext=True, header=False)

Convert binary data to a line(s) of ASCII characters in quoted-printable encoding. The return value is the converted line(s). If the optional argument quotetabs is present and true, all tabs and spaces will be encoded. If the optional argument istext is present and true, newlines are not encoded but trailing whitespace will be encoded. If the optional argument header is present and true, spaces will be encoded as underscores per RFC 1522. If the optional argument header is present and false, newline characters will be encoded as well; otherwise linefeed conversion might corrupt the binary data stream.

binascii.a2b_hqx(string)

binhex4 形式の ASCII 文字列データを RLE 展開を行わないでバイナリに変換します。文字列はバイナリのバイトデータを完全に含むような長さか、または (binhex4 データの最後の部分の場合) 余白のビットがゼロになっていなければなりません。

binascii.rledecode_hqx(data)

data に対し、 binhex4 標準に従って RLE 展開を行います。このアルゴリズムでは、あるバイトの後ろに 0x90 がきた場合、そのバイトの反復を指示しており、さらにその後ろに反復カウントが続きます。カウントが 0 の場合 0x90 自体を示します。このルーチンは入力データの末端における反復指定が不完全でないかぎり解凍されたデータを返しますが、不完全な場合、例外 Incomplete が送出されます。

バージョン 3.2 で変更: 入力として bytestring または bytearray オブジェクトのみを受け取ります。

binascii.rlecode_hqx(data)

binhex4 方式の RLE 圧縮を data に対して行い、その結果を返します。

binascii.b2a_hqx(data)

バイナリを hexbin4 エンコードして ASCII 文字列に変換し、変換後の文字列を返します。引数の data はすでに RLE エンコードされていなければならず、その長さは (最後のフラグメントを除いて) 3 で割り切れなければなりません。

binascii.crc_hqx(data, value)

value を CRC の初期値として data の 16 ビット CRC 値を計算し、その結果を返します。 この関数は、よく 0x1021 と表現される CRC-CCITT 多項式 x16 + x12 + x5 + 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 で変更: 結果は常に unsigned です。すべてのバージョンとプラットフォームの Python に渡って同一の数値を生成するには、crc32(data) & 0xffffffff を使用します。

binascii.b2a_hex(data)
binascii.hexlify(data)

バイナリ data の16進表現を返します。data の各バイトは、対応する2桁の16進表現に変換されます。したがって、返されるバイトオブジェクトは data の2倍の長さになります。

binascii.a2b_hex(hexstr)
binascii.unhexlify(hexstr)

16進数表記の文字列 hexstr の表すバイナリデータを返します。この関数は b2a_hex() の逆です。 hexstr は 16進数字 (大文字でも小文字でも構いません) を偶数個含んでいなければなりません。そうでない場合、例外 Error が送出されます。

exception binascii.Error

エラーが発生した際に送出される例外です。通常はプログラムのエラーです。

exception binascii.Incomplete

変換するデータが不完全な場合に送出される例外です。通常はプログラムのエラーではなく、多少追加読み込みを行って再度変換を試みることで対処できます。

参考

base64 モジュール
RFC 準拠の base64 形式の、底が 16、32、64、85 のエンコーディング。
binhex モジュール
Macintosh で使われる binhex フォーマットのサポート。
uu モジュール
Unix で使われる UU エンコードのサポート。
quopri モジュール
MIME 電子メールメッセージで使われる quoted-printable エンコードのサポート。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネット上のデータの操作 »


quopri --- MIME quoted-printable 形式データのエンコードおよびデコード

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »

quopri --- MIME quoted-printable 形式データのエンコードおよびデコード

ソースコード: Lib/quopri.py

このモジュールは RFC 1521: "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: "MIME (Multipurpose Internet Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text" で記述されているところの "Q"-エンコードされたヘッダをデコードするのに使われます。

quopri.encode(input, output, quotetabs, header=False)

Encode the contents of the input file and write the resulting quoted-printable data to the output file. input and output must be binary file objects. quotetabs, a non-optional flag which controls whether to encode embedded spaces and tabs; when true it encodes such embedded whitespace, and when false it leaves them unencoded. Note that spaces and tabs appearing at the end of lines are always encoded, as per RFC 1521. header is a flag which controls if spaces are encoded as underscores as per RFC 1522.

quopri.decodestring(s, header=False)

decode() に似ていますが、ソース bytes を受け取り、対応するデコードされた bytes を返します。

quopri.encodestring(s, quotetabs=False, header=False)

Like encode(), except that it accepts a source bytes and returns the corresponding encoded bytes. By default, it sends a False value to quotetabs parameter of the encode() function.

参考

base64 モジュール
MIME base64 形式データのエンコードおよびデコード

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネット上のデータの操作 »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネット上のデータの操作 »

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

ソースコード: Lib/uu.py

このモジュールではファイルを uuencode 形式(任意のバイナリデータを ASCII 文字列に変換したもの)にエンコード、デコードする機能を提供します。引数としてファイルが仮定されている所では、ファイルのようなオブジェクトが利用できます。後方互換性のために、パス名を含む文字列も利用できるようにしていて、対応するファイルを開いて読み書きします。しかし、このインタフェースは利用しないでください。呼び出し側でファイルを開いて(Windows では 'rb' か 'wb' のモードで)利用する方法が推奨されます。

このコードは Lance Ellinghouse によって提供され、Jack Jansen によって更新されました。

uu モジュールでは以下の関数を定義しています:

uu.encode(in_file, out_file, name=None, mode=None, *, backtick=False)

Uuencode file in_file into file out_file. The uuencoded file will have the header specifying name and mode as the defaults for the results of decoding the file. The default defaults are taken from in_file, or '-' and 0o666 respectively. If backtick is true, zeros are represented by '`' instead of spaces.

バージョン 3.7 で変更: Added the backtick parameter.

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 への変換をサポートするモジュール。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネット上のデータの操作 »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

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

Python は様々な構造化データマークアップ形式を扱うための、様々なモジュールをサポートしています。これらは標準化一般マークアップ言語 (SGML) およびハイパーテキストマークアップ言語 (HTML)、そして可拡張性マークアップ言語 (XML) を扱うためのいくつかのインタフェースからなります。

  • html --- HyperText Markup Language のサポート
  • html.parser--- HTML および XHTML のシンプルなパーサー
    • HTML パーサーアプリケーションの例
    • HTMLParser メソッド
    • 使用例
  • html.entities --- HTML 一般実体の定義
  • XMLを扱うモジュール群
    • XML の脆弱性
    • defusedxml および defusedexpat パッケージ
  • xml.etree.ElementTree --- ElementTree XML API
    • チュートリアル
      • XML 木構造と要素
      • XML の解析
      • 非ブロックパースのためのプル API
      • 関心ある要素の検索
      • XML ファイルの編集
      • XML 文書の構築
      • 名前空間のある XML の解析
      • その他の情報
    • XPath サポート
      • 使用例
      • サポートされている XPath 構文
    • リファレンス
      • 関数
      • Element オブジェクト
      • ElementTree オブジェクト
      • QName オブジェクト
      • TreeBuilder オブジェクト
      • XMLParser オブジェクト
      • XMLPullParser オブジェクト
      • 例外
  • xml.dom --- 文書オブジェクトモデル (DOM) API
    • モジュールコンテンツ
    • DOM 内のオブジェクト
      • DOMImplementation オブジェクト
      • Node オブジェクト
      • NodeList オブジェクト
      • DocumentType オブジェクト
      • Document オブジェクト
      • Element オブジェクト
      • Attr オブジェクト
      • NamedNodeMap Objects
      • Comment オブジェクト
      • Text オブジェクトおよび CDATASection オブジェクト
      • ProcessingInstruction オブジェクト
      • 例外
    • 適合性
      • 型の対応付け
      • アクセサメソッド
  • xml.dom.minidom --- 最小限の DOM の実装
    • DOM オブジェクト
    • DOM の例
    • minidom と DOM 標準
  • xml.dom.pulldom --- 部分的な DOM ツリー構築のサポート
    • DOMEventStream オブジェクト
  • xml.sax --- SAX2 パーサのサポート
    • SAXException オブジェクト
  • xml.sax.handler --- SAX ハンドラの基底クラス
    • ContentHandler オブジェクト
    • DTDHandler オブジェクト
    • EntityResolver オブジェクト
    • ErrorHandler オブジェクト
  • xml.sax.saxutils --- SAX ユーティリティ
  • xml.sax.xmlreader --- XML パーサのインタフェース
    • XMLReader オブジェクト
    • IncrementalParser オブジェクト
    • Locator オブジェクト
    • InputSource オブジェクト
    • Attributes インタフェース
    • AttributesNS インタフェース
  • xml.parsers.expat --- Expat を使った高速な XML 解析
    • XMLParser オブジェクト
    • ExpatError 例外
    • 使用例
    • 内容モデルの記述
    • Expat エラー定数

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


html --- HyperText Markup Language のサポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

html --- HyperText Markup Language のサポート

ソースコード: Lib/html/__init__.py

このモジュールは HTML を操作するユーティリティを定義しています。

html.escape(s, quote=True)

文字列 s 内の &、<、および > を HTML セーフなシーケンスに変換します。これらの文字を含む HTML を表示する必要がある場合に使用します。オプションフラグ quote が真の場合、文字 (") および (') も変換します。これは例えば <a href="..."> など、引用符で括られている HTML 属性値を包含する時に役立ちます。

バージョン 3.2 で追加.

html.unescape(s)

Convert all named and numeric character references (e.g. &gt;, &#62;, &#x3e;) in the string s to the corresponding Unicode characters. This function uses the rules defined by the HTML 5 standard for both valid and invalid character references, and the list of HTML 5 named character references.

バージョン 3.4 で追加.

html パッケージのサブモジュールは以下のとおりです:

  • html.parser -- 許容性のあるモードを持つ HTML/XHTML パーサー
  • html.entities -- HTML 実体の定義

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 構造化マークアップツール »


html.parser--- HTML および XHTML のシンプルなパーサー

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

html.parser--- HTML および XHTML のシンプルなパーサー

ソースコード: 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)

このメソッドは &#NNN; あるいは &#xNNN; 形式の 10進および 16 進数値文字参照を処理するために呼び出されます。例えば、&gt; と等価な 10 進数は &#62; で、16進数は &#x3E; になります。この場合、メソッドは '62' あるいは 'x3E' を受け取ります。このメソッドは convert_charrefs が 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 --- HTML 一般実体の定義

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

html.entities --- HTML 一般実体の定義

ソースコード: Lib/html/entities.py

このモジュールは 4 つの辞書、html5、name2codepoint、codepoint2name、および entitydefs を定義しています。

html.entities.html5

HTML5 名前付き文字参照 [1] と Unicode 文字とを対応付ける辞書です (例: html5['gt;'] == '>')。末尾のセミコロンは名前に含まれますが (例: 'gt;')、一部の名前はセミコロンなしでも標準で受け付けます。この場合、';' ありの名前と ';' なしの名前が両方存在します。 html.unescape() も参照してください。

バージョン 3.3 で追加.

html.entities.entitydefs

各 XHTML 1.0 実体定義と ISO Latin-1 における置換テキストとを対応付ける辞書です。

html.entities.name2codepoint

HTML 実体名と Unicode コードポイントとを対応付ける辞書です。

html.entities.codepoint2name

Unicode コードポイントと HTML 実体名とを対応付ける辞書です。

脚注

[1] https://www.w3.org/TR/html5/syntax.html#named-character-references を参照してください

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 構造化マークアップツール »


XMLを扱うモジュール群

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

XMLを扱うモジュール群

ソースコード: Lib/xml/

PythonのXMLを扱うインタフェースは xml パッケージにまとめられています。

警告

XML モジュール群は不正なデータや悪意を持って作成されたデータに対して安全ではありません。信頼できないデータをパースする必要がある場合は XML の脆弱性 と defusedxml および defusedexpat パッケージ を参照してください。

注意すべき重要な点として、 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 | 脆弱 | 脆弱 | 脆弱 | 脆弱 | 脆弱
quadratic blowup | 脆弱 | 脆弱 | 脆弱 | 脆弱 | 脆弱
external entity expansion | Safe (4) | 安全 (1) | 安全 (2) | Safe (4) | 安全 (3)
DTD retrieval | Safe (4) | 安全 | 安全 | Safe (4) | 安全
decompression bomb | 安全 | 安全 | 安全 | 安全 | 脆弱
  1. xml.etree.ElementTree は外部エンティティを展開せず、エンティティが現れた場合は ParserError を送出します。
  2. xml.dom.minidom は外部エンティティを展開せず、展開前のエンティティをそのまま返します。
  3. xmlrpclib は外部エンティティを展開せず、除外します。
  4. Since Python 3.7.1, external general entities are no longer processed by default.
billion laughs / exponential entity expansion
Billion Laughs 攻撃 -- または指数関数的エンティティ展開 (exponential entity expansion) -- は複数階層の入れ子になったエンティティを使用します。 各エンティティは別のエンティティを複数回参照し、最終的なエンティティの定義は短い文字列です。 指数関数的に展開されることで数 GB のテキストができ、多くのメモリと CPU 時間を消費します。
quadratic blowup entity expansion
二次爆発攻撃 (quadratic blowup attack) はエンティティ展開を悪用する点で Billion Laughs 攻撃に似ています。 入れ子になったエンティティの代わりに、この攻撃は数千字の大きなエンティティを何度も繰り返します。 この攻撃は指数関数的なものほど効率的ではありませんが、パーザの深い入れ子になったエンティティを禁止する対抗手段をすり抜けます。
external entity expansion
(外部エンティティ展開) エンティティの定義はただのテキスト置換以上のことが出来ます。 外部のリソースやローカルファイルを参照することも出来ます。 XML パーザはリソースにアクセスしてその内容を XML 文書に埋め込みます。
DTD retrieval
Python の xml.dom.pulldom のような XML ライブラリは DTD をリモートやローカルの場所から読み込みます。 この機能には外部エンティティ展開の問題と同じことが予想されます。
decompression bomb
解凍爆弾 (あるいは ZIP 爆弾) は、gzip 圧縮 HTTP ストリームや LZMA 圧縮ファイルなどの圧縮された XML ストリームをパースできる全ての XML ライブラリに対し行われます。 攻撃者は送信データ量を1/3以下に減らすことができます。

PyPI 上の defusedxml のドキュメントには既知の攻撃手法の詳細が例と文献付きであります。

defusedxml および defusedexpat パッケージ

defusedxml は潜在的に悪意のある操作を防ぐ、修正された stdlib XML parsers のサブクラスが付属している純 Python パッケージです。信頼出来ない XML データをパースするサーバーコードではこのパッケージの使用が推奨されます。パッケージには悪用の例に加え、XPath injection 等のさらなる XML の悪用の例があります。

defusedexpat はエンティティ展開を使った DoS 攻撃の対策をしている、修正された libexpat とパッチを当てた pyexpat モジュールを提供しています。 それでも、defusedexpat モジュールは常識的で設定可能な量のエンティティ展開を許可しています。 この修正は Python の将来のリリースに取り込まれるかもしれませんが、後方互換性を破壊するため Python のバグ修正リリースには取り込まれません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 構造化マークアップツール »


xml.etree.ElementTree --- ElementTree XML API

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

xml.etree.ElementTree --- ElementTree XML API

Source code: Lib/xml/etree/ElementTree.py

xml.etree.ElementTree モジュールは、XML データを解析および作成するシンプルかつ効率的な API を実装しています。

バージョン 3.3 で変更: このモジュールは利用出来る場合は常に高速な実装を使用します。xml.etree.cElementTree は非推奨です。

警告

xml.etree.ElementTree モジュールは悪意を持って作成されたデータに対して安全ではありません。信頼できないデータや認証されていないデータををパースする必要がある場合は XML の脆弱性 を参照してください。

チュートリアル

これは xml.etree.ElementTree (略して ET) を使用するための短いチュートリアルで、ブロックの構築およびモジュールの基本コンセプトを紹介することを目的としています。

XML 木構造と要素

XML は本質的に階層データ形式で、木構造で表すのが最も自然な方法です。ET はこの目的のために 2 つのクラス - XML 文書全体を木で表す ElementTree および木構造内の単一ノードを表す Element - を持っています。文書全体とのやりとり (ファイルの読み書き) は通常 ElementTree レベルで行います。単一 XML 要素およびその子要素とのやりとりは Element レベルで行います。

XML の解析

このセクションでは例として以下の XML 文書を使います:

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

これの分かりやすい用途は、XML データをソケットから受信したり、ストレージデバイスからインクリメンタルに読み出したりするような、非ブロック式に動作するアプリケーションです。このような場合、ブロッキング読み出しは使用できません。

XMLPullParser は柔軟性が非常に高いため、単純に使用したいユーザーにとっては不便かもしれません。アプリケーションにおいて、XML データの読み取り時にブロックすることに支障がないが、インクリメンタルにパースする能力が欲しい場合、iterparse() を参照してください。大きな XML ドキュメントを読んでいて、全てメモリ上にあるという状態にしたくない場合に有用です。

関心ある要素の検索

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'):
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> 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>
</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 入力が 名前空間 を持っている場合、 prefix:sometag の形式で修飾されたタグと属性が、その prefix が完全な URI で置換された {uri}sometag の形に展開されます。さらに、 デフォルトの XML 名前空間 があると、修飾されていない全てのタグにその完全 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

その他の情報

http://effbot.org/zone/element-index.htm にはチュートリアルと他のドキュメントへのリンクがあります。

XPath サポート

このモジュールは木構造内の要素の位置決めのための 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]")

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

操作 | 意味
tag | 与えられたタグを持つ全ての子要素を選択します。 例えば、spam は spam という名前の子要素すべてを選択し、spam/egg は spam という名前の全ての子要素の下にある egg という名前の孫要素を全て選択します。
* | すべての子要素を選択します。例えば、*/egg は egg という名前の孫要素をすべて選択します。
. | 現在のノードを選択します。これはパスの先頭に置くことで相対パスであることを示すのに役立ちます。
// | 現在の要素の下にある全てのレベルの全ての子要素を選択します。例えば、.//egg は木全体から egg 要素を選択します。
.. | 親ノードを選択します。パスが開始要素 (find が呼ばれた要素) の上の要素に進もうとした場合 None を返します。
[@attrib] | 与えられた属性を持つ全ての要素を選択します。
[@attrib='value'] | 与えられた属性が与えられた値を持つ全ての要素を選択します。 値に引用符は含められません。
[tag] | tag という名前の子要素を持つ全ての要素を選択します。 直下の子要素のみサポートしています。
[.='text'] | Selects all elements whose complete text content, including descendants, equals the given text. バージョン 3.7 で追加.
[tag='text'] | Selects all elements that have a child named tag whose complete text content, including descendants, equals the given text.
[position] | 与えられた位置にあるすべての要素を選択します。位置は整数 (先頭は 1)、式 last() (末尾)、あるいは末尾からの相対位置 (例えば last()-1) のいずれかで指定できます。

述語 (角括弧内の式) の前にはタグ名、アスタリスク、あるいはその他の述語がなければなりません。 position 述語の前にはタグ名がなければなりません。

リファレンス

関数

xml.etree.ElementTree.Comment(text=None)

コメント要素のファクトリです。このファクトリ関数は、標準のシリアライザでは XML コメントにシリアライズされる特別な要素を作ります。コメント文字列はバイト文字列でも Unicode 文字列でも構いません。text はそのコメント文字列を含んだ文字列です。コメントを表わす要素のインスタンスを返します。

XMLParser は、入力に含まれるコメントを読み飛ばし、コメントオブジェクトは作成しません。ElementTree は、Element メソッドの 1 つを使用して木内に挿入されたコメントノードのみを含みます。

xml.etree.ElementTree.dump(elem)

要素の木もしくは要素の構造を sys.stdout に出力します。この関数はデバッグ目的のみに使用してください。

出力される形式の正確なところは実装依存です。このバージョンでは、通常の XML ファイルとして出力されます。

elem は要素の木もしくは個別の要素です。

xml.etree.ElementTree.fromstring(text)

文字列定数で与えられた XML 断片を解析します。 XML() 関数と同じです。 text は XML データの文字列です。 Element インスタンスを返します。

xml.etree.ElementTree.fromstringlist(sequence, parser=None)

文字列フラグメントのシーケンスから XML ドキュメントを解析します。 sequence は XML データのフラグメントを格納した、リストかその他のシーケンスです。 parser はオプションのパーザインスタンスです。パーザが指定されない場合、標準の XMLParser パーザが使用されます。 Element インスタンスを返します。

バージョン 3.2 で追加.

xml.etree.ElementTree.iselement(element)

オブジェクトが正当な要素オブジェクトであるかをチェックします。 element は要素インスタンスです。引数が要素オブジェクトならば真値を返します。

xml.etree.ElementTree.iterparse(source, events=None, parser=None)

XML セクションを構文解析して要素の木を漸増的に作っていき、その間進行状況をユーザーに報告します。 source は XML データを含むファイル名またはファイル風オブジェクト (file object) です。 events は報告すべきイベントのシーケンスです。サポートされているイベントは、文字列の "start", "end", "start-ns", "end-ns" です ("ns" イベントは、名前空間についての詳細情報を取得するために使用)。events が省略された場合は "end" イベントだけが報告されます。 parser はオプションの引数で、パーサーのインスタンスです。指定されなかった場合は標準の XMLParser が利用されます。parser は XMLParser のサブクラスでなくてはならず、ターゲットとして既定の TreeBuilder のみしか使用できません。(event, elem) ペアを提供するイテレータ (iterator) を返します。

iterparse() は木をインクリメンタルに構築しますが、source (または指定のファイル) でのブロッキング読みを起こします。したがって、ブロッキング読みが許可されないアプリケーションには適しません。完全に非ブロックのパースのためには、XMLPullParser を参照してください。

注釈

iterparse() は "start" イベントを発行した時に開始タグの文字 ">" が現れたことだけを保証します。そのため、属性は定義されますが、その時点ではテキストの内容も tail 属性も定義されていません。同じことは子要素にも言えて、その時点ではあるともないとも言えません。

全部揃った要素が必要ならば、"end" イベントを探してください。

バージョン 3.4 で非推奨: parser 引数。

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 を表わす要素インスタンスを返します。

XMLParser は、入力に含まれる処理命令を読み飛ばし、コメントオブジェクトは作成しません。ElementTree は、Element メソッドの 1 つを使用して木内に挿入された処理命令ノードのみを含みます。

xml.etree.ElementTree.register_namespace(prefix, uri)

名前空間の接頭辞を登録します。レジストリはグローバルで、与えられた接頭辞か名前空間 URI のどちらかの既存のマッピングはすべて削除されます。prefix には名前空間の接頭辞を指定します。uri には名前空間の URI を指定します。この名前空間のタグや属性は、可能な限り与えられた接頭辞をつけてシリアライズされます。

バージョン 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", *, short_empty_elements=True)

XML 要素を全ての子要素を含めて表現する文字列を生成します。 element は Element のインスタンスです。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。Unicode 文字列を生成するには、encoding="unicode" を使用してください。 method は "xml", "html", "text" のいずれか(デフォルトは "xml") です。short_empty_elements は、 ElementTree.write() での意味と同じ意味を持ちます。 XML データを含んだ (オプションで) エンコードされた文字列を返します。

バージョン 3.4 で追加: short_empty_elements 引数。

xml.etree.ElementTree.tostringlist(element, encoding="us-ascii", method="xml", *, short_empty_elements=True)

XML 要素を全ての子要素を含めて表現する文字列を生成します。 element は Element のインスタンスです。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。Unicode 文字列を生成するには、encoding="unicode" を使用してください。 method は "xml", "html", "text" のいずれか(デフォルトは "xml") です。short_empty_elements は、 ElementTree.write() での意味と同じ意味を持ちます。 XML データを含んだ (オプションで) エンコードされた文字列のリストを返します。b"".join(tostringlist(element)) == tostring(element) となること以外、特定の順序になる保証はありません。

バージョン 3.2 で追加.

バージョン 3.4 で追加: short_empty_elements 引数。

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 のインスタンスと辞書のタプルを返します。

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 を送出します。

バージョン 3.2 で追加.

find(match, namespaces=None)

match にマッチする最初の子要素を検索します。match はタグ名または パス を指定できます。要素インスタンスか None を返します。namespaces はオプションで、名前空間接頭辞から完全名を対応付けるマップオブジェクトを指定します。

findall(match, namespaces=None)

タグ名または パス にマッチするすべての子要素を検索します。マッチしたすべての子要素が文書内の順序で含まれたリストを返します。namespaces はオプションで、名前空間接頭辞から完全名を対応付けるマップオブジェクトを指定します。

findtext(match, default=None, namespaces=None)

match にマッチする最初の子要素のテキストを検索します。match にはタグ名または パス を指定できます。最初にマッチした要素の内容のテキストを返します。マッチする要素が無い場合 default を返します。マッチした要素の内容にテキストがなかった場合空の文字列が返ります。namespaces はオプションで、名前空間接頭辞から完全名を対応付けるマップオブジェクトを指定します。

getchildren()

バージョン 3.2 で非推奨: list(elem) かイテレーションを使用してください。

getiterator(tag=None)

バージョン 3.2 で非推奨: 代わりに Element.iter() メソッドを使用してください。

insert(index, subelement)

要素内の指定された位置に subelement を挿入します。subelement が Element でない場合、TypeError を送出します。

iter(tag=None)

現在の要素を根とする木の イテレータ を作成します。イテレータは現在の要素とそれ以下のすべての要素を、文書内での出現順 (深さ優先順) でイテレートします。 tag が None または '*' でない場合、与えられたタグに等しいものについてのみイテレータから返されます。イテレート中に木構造が変更された場合の結果は未定義です。

バージョン 3.2 で追加.

iterfind(match, namespaces=None)

タグ名または パス にマッチするすべての子要素を検索します。マッチしたすべての要素を文書内での出現順で yield するイテレータを返します。namespaces はオプションで、名前空間接頭辞と完全名を対応付けるマップオブジェクトを指定します。

バージョン 3.2 で追加.

itertext()

テキストのイテレータを作成します。イテレータは、この要素とすべての子要素を文書上の順序で巡回し、すべての内部のテキストを返します。

バージョン 3.2 で追加.

makeelement(tag, attrib)

現在の要素と同じ型の新しい要素オブジェクトを作成します。このメソッドは呼び出さずに、 SubElement() ファクトリ関数を使って下さい。

remove(subelement)

要素から subelement を削除します。find* メソッド群と異なり、このメソッドは要素をインスタンスの同一性で比較します。タグや内容では比較しません。

Element オブジェクトは以下のシーケンス型のメソッドを、サブ要素を操作するためにサポートします: __delitem__(), __getitem__(), __setitem__(), __len__().

注意: 子要素を持たない要素の真偽値は False になります。この挙動は将来のバージョンで変更されるかもしれません。直接真偽値をテストするのでなく、 len(elem) か elem is None を利用してください。

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")

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() と同じで、木の根要素を起点とします。

getiterator(tag=None)

バージョン 3.2 で非推奨: 代わりに ElementTree.iter() メソッドを使用してください。

getroot()

この木のルート要素を返します。

iter(tag=None)

根要素に対する、木を巡回するイテレータを返します。イテレータは木のすべての要素に渡ってセクション順にループします。tag は探したいタグです (デフォルトではすべての要素を返します)。

iterfind(match, namespaces=None)

Element.iterfind() と同じで、木の根要素を起点とします。

バージョン 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 は、書き込み用に開かれたファイル名またはファイル風オブジェクト (file object) です。 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 で追加: short_empty_elements 引数。

以下はこれから操作する 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)

汎用の要素構造ビルダです。これは start、data、および end メソッドのシーケンスを適格な要素構造に変換します。このクラスを使うと、カスタム XML パーザ、あるいは他の XML に似た形式のパーザを使用して要素構造を構築できます。element_factory を指定する場合、タグと属性の辞書の 2 個の位置引数へのアクセスによって呼び出し可能でなければなりません。これは新しい要素インスタンスを返すはずです。

close()

ビルダのバッファをフラッシュし、最上位の文書要素を返します。戻り値は Element インスタンスになります。

data(data)

現在の要素にテキストを追加します。 data は文字列です。バイト文字列もしくは Unicode 文字列でなければなりません。

end(tag)

現在の要素を閉じます。 tag は要素の名前です。閉じられた要素を返します。

start(tag, attrs)

新しい要素を開きます。 tag は要素の名前です。 attrs は要素の属性を保持した辞書です。開かれた要素を返します。

加えて、カスタムの TreeBuilder オブジェクトは以下のメソッドを提供できます:

doctype(name, pubid, system)

doctype 宣言を処理します。 name は doctype 名です。 pubid は公式の識別子です。 system はシステム識別子です。このメソッドはデフォルトの TreeBuilder クラスには存在しません。

バージョン 3.2 で追加.

XMLParser オブジェクト

class xml.etree.ElementTree.XMLParser(html=0, target=None, encoding=None)

このクラスは、このモジュールの構成要素のうち、低水準のものです。効率的でイベントベースのXMLパースのため、xml.parsers.expat を使用します。feed() メソッドで XML データをインクリメンタルに受け取り、target オブジェクトのコールバックを呼び出すことで、パースイベントをプッシュ API に変換します。target が省略された場合、標準の TreeBuilder が使用されます。html 引数は、後方互換性のため使われてきましたが、廃止されました。encoding [1] が指定された場合、このあたいは XML ファイル内で指定されたエンコーディングを上書きします。

バージョン 3.4 で非推奨: html 引数。残りの引数は、キーワード引数として渡し、 html 引数の削除に向けて備えるべきです。

close()

パーザへのデータの提供を完了します。構築中に渡される target の close() メソッドを呼び出す結果を返します。既定では、これがトップレベルのドキュメント要素になります。

doctype(name, pubid, system)

バージョン 3.2 で非推奨: カスタムの TreeBuilder target で TreeBuilder.doctype() メソッドを定義してください。

feed(data)

パーザへデータを入力します。 data はエンコードされたデータです。

XMLParser.feed() は target の start(tag, attrs_dict) メソッドをそれぞれの開始タグに対して呼び、また end(tag) メソッドを終了タグに対して呼び、そしてデータを data(data) メソッドで処理します。 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", "start-ns", "end-ns" ("ns" イベントは、名前空間の詳細情報の取得に使用) です。events が省略された場合、 "end" イベントのみが報告されます。

feed(data)

指定したバイトデータをパーザに与えます。

close()

パーザに、データストリームが終了したことを伝えます。XMLParser.close() とは異なり、このメソッドは常に None を返します。パーザがクローズした時にまだ帰って来ていないイベントは、まだ read_events() で読むことができます。

read_events()

パーザに与えられたデータ中で見つかったイベントのイテレータを返します。このイテレータは、(event, elem) ペアを順に返します。ここで、 event はイベントの種類を表す文字列 (例: "end")、elem は見つかった Element オブジェクトです。

read_events() の前の呼び出しで提供されたイベントは、再度 yield されることはありません。イベントは、イテレータから取得された場合にのみ内部キューから消費されるため、read_events() から取得されたイテレータに対して複数の読み出しを並行して反復的に行うと、予期せぬ結果が引き起こされます。

注釈

XMLPullParser は "start" イベントを発行した時に開始タグの文字 ">" が現れたことだけを保証します。そのため、属性は定義されますが、その時点ではテキストの内容も tail 属性も定義されていません。子要素にもそれが存在する、しないにかかわらず同じ物が適用されます。

全部揃った要素が必要ならば、"end" イベントを探してください。

バージョン 3.4 で追加.

例外

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.minidom --- 最小限の DOM の実装

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

xml.dom.minidom --- 最小限の DOM の実装

ソースコード: 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"

DOM ツリーを使い終えたとき、 unlink() メソッドを呼び出して不要になったオブジェクトが早く片付けられるように働きかけることができます。 unlink() は、 DOM API に対する xml.dom.minidom 特有の拡張です。ノードに対して unlink() を呼び出した後は、ノードとその下位ノードは本質的には無意味なものとなります。このメソッドを呼び出さなくても、 Python のガベージコレクタがいつかはツリーのオブジェクトを後片付けします。

参考

Document Object Model (DOM) Level 1 Specification
xml.dom.minidom でサポートされている W3C の DOM に関する勧告。

DOM オブジェクト

Python の DOM API 定義は xml.dom モジュールドキュメントの一部として与えられています。この節では、 xml.dom の API と xml.dom.minidom との違いについて列挙します。

Node.unlink()

DOM との内部的な参照を破壊して、循環参照ガベージコレクションを持たないバージョンの Python でもガベージコレクションされるようにします。循環参照ガベージコレクションが利用できる場合でも、このメソッドを使えば大量のメモリをすぐに使えるようにできるため、不要になったらすぐに DOM オブジェクトに対してこのメソッドを呼ぶのが良い習慣です。このメソッドは Document オブジェクトに対して呼び出すだけでよいのですが、あるノードの子ノードを破棄するために子ノードに対して呼び出してもかまいません。

You can avoid calling this method explicitly by using the with statement. The following code will automatically unlink dom when the with block is exited:

with xml.dom.minidom.parse(datasource) as dom:
    ... # Work with dom.
Node.writexml(writer, indent="", addindent="", newl="")

XML を writer オブジェクトに書き込みます。 writer は、ファイルオブジェクトインタフェースの write() に該当するメソッドを持たなければなりません。 indent 引数には現在のノードのインデントを指定します。 addindent 引数には現在のノードの下にサブノードを追加する際のインデント増分を指定します。 newl には、改行時に行末を終端する文字列を指定します。

Document ノードでは、追加のキーワード引数 encoding を使って XML ヘッダの encoding フィールドを指定することができます。

Node.toxml(encoding=None)

DOM ノードによって表わされる XML を含んだ文字列またはバイト文字列を返します。

明示的に encoding [1] 引数を渡すと、結果は指定されたエンコードのバイト文字列になります。encoding 引数なしだと、結果は unicode 文字列です。また、結果として生じる文字列の中の XML 宣言はエンコーディングを指定しません。XML のデフォルトエンコーディングは UTF-8 なので、この文字列を UTF-8 以外でエンコードすることはおそらく正しくありません。

Node.toprettyxml(indent="\t", newl="\n", encoding=None)

文書の整形されたバージョンを返します。 indent はインデントを行うための文字で、デフォルトはタブです; newl には行末で出力される文字列を指定し、デフォルトは \n です。

encoding 引数は toxml() の対応する引数と同様に振る舞います。

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("<title>%s</title>" % getText(title.childNodes))

def handleSlideTitle(title):
    print("<h2>%s</h2>" % getText(title.childNodes))

def handlePoints(points):
    print("<ul>")
    for point in points:
        handlePoint(point)
    print("</ul>")

def handlePoint(point):
    print("<li>%s</li>" % getText(point.childNodes))

def handleToc(slides):
    for slide in slides:
        title = slide.getElementsByTagName("title")[0]
        print("<p>%s</p>" % getText(title.childNodes))

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
  • DocumentType
  • DOMImplementation
  • CharacterData
  • CDATASection
  • Notation
  • Entity
  • EntityReference
  • DocumentFragment

これらの大部分は、ほとんどの 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 --- 部分的な DOM ツリー構築のサポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

xml.dom.pulldom --- 部分的な DOM ツリー構築のサポート

Source code: Lib/xml/dom/pulldom.py

xml.dom.pulldom モジュールは "プルパーザ" を提供します。 プルパーザは必要に応じて文書の DOM アクセス可能な断片を生成することができます。 基本概念は、入力 XML のストリームから "イベント" を取り出し (pull し) て処理することです。 SAX とは、コールバックつきのイベント駆動処理モデルを採用しているという点で同様ですが、SAX とは対照的に、プルパーザの使用者には処理が完了するかエラー状態が発生するまで、明示的にストリームからイベントを取り出し、イベントに対しループを回す責任があります。

警告

xml.dom.pulldom モジュールは悪意を持って作成されたデータに対して安全ではありません。信頼できないデータや認証されていないデータをパースする必要がある場合は XML の脆弱性 を参照してください。

バージョン 3.7.1 で変更: The SAX parser no longer processes general external entities by default to increase security by default. To enable processing of external entities, pass a custom parser instance in:

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)
getEvent()

Return a tuple containing event and the current node as xml.dom.minidom.Document if event equals START_DOCUMENT, xml.dom.minidom.Element if event equals START_ELEMENT or END_ELEMENT or xml.dom.minidom.Text if event equals CHARACTERS. The current node does not contain information about its children, unless expandNode() is called.

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 --- SAX2 パーサのサポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

xml.sax --- SAX2 パーサのサポート

ソースコード: Lib/xml/sax/__init__.py

xml.sax パッケージは Python 用の Simple API for XML (SAX) インターフェースを実装した数多くのモジュールを提供しています。またパッケージには SAX 例外と SAX API 利用者が頻繁に利用するであろう有用な関数群も含まれています。

警告

xml.sax モジュールは悪意を持って作成されたデータに対して安全ではありません。信頼できないデータや認証されていないデータをパースする必要がある場合は XML の脆弱性 を参照してください。

バージョン 3.7.1 で変更: The SAX parser no longer processes general external entities by default to increase security. Before, the parser created network connections to fetch remote files or loaded local files from the file system for DTD and entities. The feature can be enabled again with method setFeature() on the parser object and argument feature_external_ges.

その関数群は以下の通りです:

xml.sax.make_parser(parser_list=[])

Create and return a SAX XMLReader object. The first parser found will be used. If parser_list is provided, it must be a list of strings which name modules that have a function named create_parser(). Modules listed in parser_list will be used before modules in the default list of parsers.

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
SAX API 定義に関し中心となっているサイトです。Java による実装とオンライン・ドキュメントが提供されています。実装と SAX API の歴史に関する情報のリンクも掲載されています。
xml.sax.handler モジュール
アプリケーションが提供するオブジェクトのインターフェース定義。
xml.sax.saxutils モジュール
SAX アプリケーション向けの有用な関数群。
xml.sax.xmlreader モジュール
パーサが提供するオブジェクトのインターフェース定義。

SAXException オブジェクト

SAXException 例外クラスは以下のメソッドをサポートしています:

SAXException.getMessage()

エラー状態を示す可読メッセージを返します。

SAXException.getException()

カプセル化した例外オブジェクトまたは None を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 構造化マークアップツール »


xml.sax.saxutils --- SAX ユーティリティ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

xml.sax.saxutils --- SAX ユーティリティ

ソースコード: Lib/xml/sax/saxutils.py

モジュール xml.sax.saxutils には SAX アプリケーションの作成に役立つ多くの関数やクラスも含まれており、直接利用したり、基底クラスとして使うことができます。

xml.sax.saxutils.escape(data, entities={})

文字列データ内の '&', '<', '>' をエスケープします。

オプションの entities 引数に辞書を渡すことで、そのほかの文字列データをエスケープすることも可能です。辞書のキーと値はすべて文字列で、キーは対応する値に置換されます。entities が与えられている場合でも、 '&', '<', '>' は常にエスケープされます。

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 で追加: short_empty_elements 引数。

class xml.sax.saxutils.XMLFilterBase(base)

このクラスは XMLReader とクライアント・アプリケーションのイベント・ハンドラとの間に位置するものとして設計されています。デフォルトでは何もせず、ただリクエストをリーダに、イベントをハンドラに、それぞれ加工せず渡すだけです。しかし、サブクラスでメソッドをオーバーライドすると、イベント・ストリームやリクエストを加工してから渡すように変更可能です。

xml.sax.saxutils.prepare_input_source(source, base='')

この関数は引数に入力ソース、オプションとして URL を取り、読み取り可能な解決済み InputSource オブジェクトを返します。入力ソースは文字列、ファイル風オブジェクト、 InputSource のいずれでも良く、この関数を使うことで、パーサは様々な source パラメータを parse() に渡すことが可能になります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 構造化マークアップツール »


xml.sax.xmlreader --- XML パーサのインタフェース

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

xml.sax.xmlreader --- XML パーサのインタフェース

ソースコード: 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)、ファイル様オブジェクト、あるいは InputSource オブジェクトです。 parse() が return したとき、入力データの処理は完了し、パーサ・オブジェクトは破棄ないしリセットされます。

バージョン 3.5 で変更: 文字ストリームがサポートされました。

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 --- Expat を使った高速な XML 解析

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 構造化マークアップツール »

xml.parsers.expat --- Expat を使った高速な XML 解析

警告

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
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 オブジェクトは次のような属性を持ちます:

xmlparser.buffer_size

buffer_text が真の時に使われるバッファのサイズです。この属性に新しい整数値を代入することで違うバッファサイズにできます。サイズが変えられるときにバッファはフラッシュされます。

xmlparser.buffer_text

この値を真にすると、 xmlparser オブジェクトが Expatから返されたもとの内容をバッファに保持するようになります。これにより可能なときに何度も CharacterDataHandler() を呼び出してしまうようなことを避けることができます。Expatは通常、文字列のデータを行末ごと大量に破棄するため、かなりパフォーマンスを改善できるはずです。この属性はデフォルトでは偽で、いつでも変更可能です。

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)

文字データを処理するときに呼びだされます。このハンドラは通常の文字データ、 CDATAセクション、無視できる空白文字列のために呼び出されます。これらを識別しなければならないアプリケーションは、要求された情報を収集するために StartCdataSectionHandler, EndCdataSectionHandler, and ElementDeclHandler コールバックメソッドを使用できます。

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

数値的なエラーコードを文字列の記述に対応させる辞書です。

バージョン 3.2 で追加.

xml.parsers.expat.errors.messages

文字列の記述をエラーコードに対応させる辞書です。

バージョン 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

脚注

[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 »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

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

この章で記述されるモジュールは、インターネットプロトコルを実装し、関連技術をサポートします。それらは全てPythonで実装されています。これらのモジュールの大部分は、システム依存のモジュール socket が存在することが必要ですが、これは現在ではほとんどの一般的なプラットフォーム上でサポートされています。ここに概観を示します:

  • webbrowser --- 便利なウェブブラウザコントローラー
    • ブラウザコントローラーオブジェクト
  • cgi --- CGI (ゲートウェイインタフェース規格) のサポート
    • はじめに
    • cgi モジュールを使う
    • 高水準インタフェース
    • 関数
    • セキュリティへの配慮
    • CGI スクリプトを Unix システムにインストールする
    • CGI スクリプトをテストする
    • CGI スクリプトをデバッグする
    • よくある問題と解決法
  • cgitb --- CGI スクリプトのトレースバック管理機構
  • wsgiref --- WSGI ユーティリティとリファレンス実装
    • wsgiref.util -- WSGI 環境のユーティリティ
    • wsgiref.headers -- WSGI レスポンスヘッダツール群
    • wsgiref.simple_server -- シンプルな WSGI HTTP サーバ
    • wsgiref.validate --- WSGI 準拠チェッカー
    • wsgiref.handlers -- サーバ／ゲートウェイのベースクラス
    • 使用例
  • urllib --- URL を扱うモジュール群
  • urllib.request --- URL を開くための拡張可能なライブラリ
    • 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 --- URL を解析して構成要素にする
    • URL の解析
    • ASCII エンコードバイト列の解析
    • 構造化された解析結果
    • URL のクオート
  • urllib.error --- urllib.request が投げる例外
  • urllib.robotparser --- robots.txt のためのパーザ
  • http --- HTTP モジュール群
    • HTTP ステータスコード
  • http.client --- HTTP プロトコルクライアント
    • HTTPConnection オブジェクト
    • HTTPResponse オブジェクト
    • 使用例
    • HTTPMessage オブジェクト
  • ftplib --- FTPプロトコルクライアント
    • FTP オブジェクト
    • FTP_TLS オブジェクト
  • poplib --- POP3 プロトコルクライアント
    • POP3 オブジェクト
    • POP3 の例
  • imaplib --- IMAP4 プロトコルクライアント
    • IMAP4 オブジェクト
    • IMAP4 の使用例
  • nntplib --- NNTP プロトコルクライアント
    • NNTP オブジェクト
      • 属性
      • メソッド
    • ユーティリティー関数
  • smtplib --- SMTP プロトコルクライアント
    • SMTP オブジェクト
    • SMTP 使用例
  • smtpd --- SMTP サーバー
    • SMTPServer オブジェクト
    • DebuggingServer オブジェクト
    • PureProxy オブジェクト
    • MailmanProxy Objects
    • SMTPChannel オブジェクト
  • telnetlib --- Telnet クライアント
    • Telnet オブジェクト
    • Telnet Example
  • uuid --- UUID objects according to RFC 4122
    • 使用例
  • socketserver --- ネットワークサーバのフレームワーク
    • サーバ生成に関するノート
    • Serverオブジェクト
    • Request Handler Objects
    • 使用例
      • socketserver.TCPServer の例
      • socketserver.UDPServer の例
      • 非同期処理の Mix-in
  • http.server --- HTTP サーバ
  • http.cookies --- HTTPの状態管理
    • Cookieオブジェクト
    • Morselオブジェクト
    • 使用例
  • http.cookiejar --- HTTP クライアント用の Cookie 処理
    • CookieJar および FileCookieJar オブジェクト
    • FileCookieJar のサブクラスと web ブラウザとの連携
    • CookiePolicy オブジェクト
    • DefaultCookiePolicy オブジェクト
    • Cookieオブジェクト
    • 使用例
  • xmlrpc --- XMLRPC サーバーとクライアントモジュール
  • xmlrpc.client --- XML-RPC クライアントアクセス
    • ServerProxy オブジェクト
    • DateTime オブジェクト
    • Binary オブジェクト
    • Fault オブジェクト
    • ProtocolError オブジェクト
    • MultiCall オブジェクト
    • 補助関数
    • クライアントのサンプル
    • クライアントとサーバーの利用例
  • xmlrpc.server --- 基本的なXML-RPCサーバー
    • SimpleXMLRPCServer オブジェクト
      • SimpleXMLRPCServer の例
    • CGIXMLRPCRequestHandler
    • XMLRPC サーバの文書化
    • DocXMLRPCServer オブジェクト
    • DocCGIXMLRPCRequestHandler
  • ipaddress --- IPv4/IPv6 操作ライブラリ
    • 便利なファクトリ関数
    • IP アドレス
      • Address オブジェクト
      • 文字列と整数への変換
      • 演算子
        • 比較演算子
        • 算術演算
    • IP ネットワーク定義
      • プリフィックス, ネットマスク、ホストマスク
      • Network オブジェクト
      • 演算子
        • 論理演算子
        • イテレーション
        • Networks as containers of addresses
    • インターフェイスオブジェクト
      • 演算子
        • 論理演算子
    • その他のモジュールレベル関数
    • Custom Exceptions

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


webbrowser --- 便利なウェブブラウザコントローラー

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

webbrowser --- 便利なウェブブラウザコントローラー

ソースコード: Lib/webbrowser.py

webbrowser モジュールにはウェブベースのドキュメントを表示するための、とてもハイレベルなインターフェースが定義されています。たいていの環境では、このモジュールの open() を呼び出すだけで正しく動作します。

Unixでは、X11上でグラフィカルなブラウザが選択されますが、グラフィカルなブラウザが利用できなかったり、X11が利用できない場合はテキストモードのブラウザが使われます。もしテキストモードのブラウザが使われたら、ユーザがブラウザから抜け出すまでプロセスの呼び出しはブロックされます。

環境変数 BROWSER が存在する場合、これは os.pathsep で区切られたブラウザのリストとして解釈され、プラットフォームのデフォルトのブラウザリストに先立って順に試みられます。リストの中の値に %s が含まれていれば、 %s を URL に置換したコマンドライン文字列と解釈されます；もし %s が含まれなければ、起動するブラウザの名前として単純に解釈されます。 [1]

非UnixプラットフォームあるいはUnix上でリモートブラウザが利用可能な場合、制御プロセスはユーザがブラウザを終了するのを待ちませんが、ディスプレイにブラウザのウィンドウを表示させたままにします。Unix上でリモートブラウザが利用可能でない場合、制御プロセスは新しいブラウザを立ち上げ、待ちます。

webbrowser スクリプトをこのモジュールのコマンドライン・インタフェースとして使うことができます。スクリプトは引数に 1 つの URL を受け付けます。また次のオプション引数を受け付けます。 -n により可能ならば新しいブラウザウィンドウで指定された URL を開きます。一方、 -t では新しいブラウザのページ (「タブ」) で開きます。 当然ながらこれらのオプションは排他的です。使用例は次の通りです:

python -m webbrowser -t "http://www.python.org"

以下の例外が定義されています:

exception webbrowser.Error

ブラウザのコントロールエラーが起こると発生する例外。

以下の関数が定義されています:

webbrowser.open(url, new=0, autoraise=True)

デフォルトのブラウザで url を表示します。new が 0 なら、url はブラウザの今までと同じウィンドウで開きます。new が 1 なら、可能であればブラウザの新しいウィンドウが開きます。new が 2 なら、可能であればブラウザの新しいタブが開きます。autoraise が True なら、可能であればウィンドウが前面に表示されます（多くのウィンドウマネージャではこの変数の設定に関わらず、前面に表示されます）。

幾つかのプラットフォームにおいて、ファイル名をこの関数で開こうとすると、OSによって関連付けられたプログラムが起動されます。しかし、この動作はポータブルではありませんし、サポートされていません。

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 でかまいません。

Setting preferred to True makes this browser a preferred result for a get() call with no argument. Otherwise, this entry point is only useful if you plan to either set the BROWSER variable or call get() with a nonempty argument matching the name of a handler you declare.

バージョン 3.7 で変更: preferred keyword-only parameter was added.

いくつかの種類のブラウザがあらかじめ定義されています。このモジュールで定義されている、関数 get() に与えるブラウザの名前と、それぞれのコントローラークラスのインスタンスを以下の表に示します。

Type Name | Class Name | 注釈
'mozilla' | Mozilla('mozilla') |
'firefox' | Mozilla('mozilla') |
'netscape' | Mozilla('netscape') |
'galeon' | Galeon('galeon') |
'epiphany' | Galeon('epiphany') |
'skipstone' | BackgroundBrowser('skipstone') |
'kfmclient' | Konqueror() | (1)
'konqueror' | Konqueror() | (1)
'kfm' | Konqueror() | (1)
'mosaic' | BackgroundBrowser('mosaic') |
'opera' | Opera() |
'grail' | Grail() |
'links' | GenericBrowser('links') |
'elinks' | Elinks('elinks') |
'lynx' | GenericBrowser('lynx') |
'w3m' | GenericBrowser('w3m') |
'windows-default' | WindowsDefault | (2)
'macosx' | MacOSX('default') | (3)
'safari' | MacOSX('safari') | (3)
'google-chrome' | Chrome('google-chrome') |
'chrome' | Chrome('chrome') |
'chromium' | Chromium('chromium') |
'chromium-browser' | Chromium('chromium-browser') |

注釈:

  1. "Konqueror"はUnixのKDEデスクトップ環境のファイルマネージャで、KDEが動作している時にだけ意味を持ちます。何か信頼できる方法でKDEを検出するのがいいでしょう; 変数 KDEDIR では十分ではありません。また、KDE 2で konqueror コマンドを使うときにも、"kfm"が使われます --- Konquerorを動作させるのに最も良い方法が実装によって選択されます。
  2. Windowsプラットフォームのみ。
  3. Mac OS X プラットフォームのみ。

バージョン 3.3 で追加: Chrome/Chromium のサポートが追加されました。

簡単な例を示します:

url = 'http://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 つの関数に相当します:

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 環境変数で与えられたディレクトリから探し出されます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

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

ソースコード: Lib/cgitb.py

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)

This function handles the exception described by info (a 3-tuple containing the result of sys.exc_info()), formatting its traceback as text and returning the result as a string. The optional argument context is the number of lines of context to display around the current line of source code in the traceback; this defaults to 5.

cgitb.html(info, context=5)

This function handles the exception described by info (a 3-tuple containing the result of sys.exc_info()), formatting its traceback as HTML and returning the result as a string. The optional argument context is the number of lines of context to display around the current line of source code in the traceback; this defaults to 5.

cgitb.handler(info=None)

この関数は標準の設定 (ブラウザに報告を表示しますがファイルにはログを書き込みません) を使って例外を処理します。この関数は、例外を捕捉した際に cgitb を使って報告したい場合に使うことができます。オプションの info 引数は、例外の型、例外の値、トレースバックオブジェクトからなる 3 要素のタプルでなければなりません。これは sys.exc_info() によって返される値と全く同じです。 info 引数が与えられていない場合、現在の例外は sys.exc_info() から取得されます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


wsgiref --- WSGI ユーティリティとリファレンス実装

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

wsgiref --- WSGI ユーティリティとリファレンス実装

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) 準拠のバリデーションツールを提供します。

See wsgi.readthedocs.io for more information about WSGI, and links to tutorials and other resources.

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

このモジュールは WSGI 環境で使う様々なユーティリティ関数を提供します。 WSGI 環境は PEP 3333 で記述されているような HTTP リクエスト変数を含む辞書です。すべての environ パラメータを取る関数は WSGI 準拠の辞書を与えられることを期待しています; 細かい仕様については PEP 3333 を参照してください。

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 の "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 で定義されている 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 で定義されている HTTP/1.1 の "Hop-by-Hop" ヘッダの場合に true を返します。

class wsgiref.util.FileWrapper(filelike, blksize=8192)

ファイル風オブジェクトをイテレータ(iterator)に変換するラッパです。結果のオブジェクトは __getitem__() と __iter__() 両方をサポートしますが、これは Python 2.1 と Jython の互換性のためです。オブジェクトがイテレートされる間、オプションの blksize パラメータがくり返し filelike オブジェクトの read() メソッドに渡されて受け渡すバイト文字列を取得します。 read() が空バイト文字列を返した場合、イテレーションは終了して再開されることはありません。

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)

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

このモジュールは単一のクラス、 Headers を提供し、WSGI レスポンスヘッダの操作をマップに似たインターフェースで便利にします。

class wsgiref.headers.Headers([headers])

headers をラップするマップ風オブジェクトを生成します。これは PEP 3333 に定義されるようなヘッダの名前／値のタプルのリストです。 headers のデフォルト値は空のリストです。

Headers オブジェクトは典型的なマッピング操作をサポートし、これには __getitem__() 、 get() 、 __setitem__() 、 setdefault() 、 __delitem__() 、 __contains__() を含みます。これらメソッドのそれぞれにおいて、キーはヘッダ名で（大文字小文字は区別しません）、値はそのヘッダ名に関連づけられた最初の値です。ヘッダを設定すると既存のヘッダ値は削除され、ラップされたヘッダのリストの末尾に新しい値が加えられます。既存のヘッダの順番は一般に維持され、ラップされたリストの最後に新しいヘッダが追加されます。

辞書とは違って、 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 で定義されるところの 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()

現在設定されている呼び出し可能 (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()

リクエストに対する WSGI 環境を含む辞書を返します。デフォルト実装では WSGIServer オブジェクトの base_environ 辞書属性のコンテンツをコピーし、それから HTTP リクエスト由来の様々なヘッダを追加しています。このメソッド呼び出し毎に、 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 準拠を保証するものでないことは注意してください; このモジュールでエラーが出ないことは必ずしもエラーが存在しないことを意味しません。しかしこのモジュールがエラーを出したならば、ほぼ確実にサーバかアプリケーションのどちらかが 100% 準拠ではありません。

このモジュールは lan Bicking の "Python Paste" ライブラリの paste.lint モジュールをベースにしています。

wsgiref.validate.validator(application)

Wrap application and return a new WSGI application object. The returned application will forward all requests to the original application, and will check that both the application and the server invoking it are conforming to the WSGI specification and to RFC 2616.

何らかの非準拠が検出されると、 AssertionError 例外が送出されます; しかし、このエラーがどう扱われるかはサーバ依存であることに注意してください。例えば、 wsgiref.simple_server とその他 wsgiref.handlers ベースのサーバ（エラー処理メソッドが他のことをするようにオーバライドしていないもの）は単純にエラーが発生したというメッセージとトレースバックのダンプを sys.stderr やその他のエラーストリームに出力します。

このラッパは、疑わしいものの実際には 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.

バージョン 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 ではなくこのクラスをサブクラス化するとよいでしょう。

このクラスは BaseHandler のサブクラスです。これは __init__() 、 get_stdin() 、 get_stderr() 、 add_cgi_vars() 、 _write() 、 _flush() をオーバーライドして、コンストラクタから明示的に環境とストリームを設定するようにしています。与えられた環境とストリームは stdin 、 stdout 、 stderr それに environ 属性に保存されています。

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()

現在処理中のリクエストの wsgi.input としての利用に適当な入力ストリームオブジェクトを返します。

get_stderr()

現在処理中のリクエストの wsgi.errors としての利用に適当な出力ストリームオブジェクトを返します。

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.exc_info() を使って現在のエラー情報にアクセスでき、その情報はこれを呼ぶときに start_response に渡すべきです ( PEP 3333 の "Error Handling" セクションに記述があります)。

デフォルト実装は単に error_status 、 error_headers 、 error_body 属性を出力ページの生成に使います。サブクラスではこれをオーバーライドしてもっと動的なエラー出力をすることができます。

しかし、セキュリティの観点からは診断をあらゆるユーザに吐き出すことは推奨されないことに気をつけてください; 理想的には、診断的な出力を有効にするには何らかの特別なことをする必要があるようにすべきで、これがデフォルト実装では何も含まれていない理由です。

error_status

エラーレスポンスで使われる HTTP ステータスです。これは PEP 3333 で定義されているステータス文字列です; デフォルトは 500 コードとメッセージです。

error_headers

エラーレスポンスで使われる HTTP ヘッダです。これは PEP 3333 で述べられているような、 WSGI レスポンスヘッダ ((name, value) タプル) のリストであるべきです。デフォルトのリストはコンテントタイプを text/plain にセットしているだけです。

error_body

エラーレスポンスボディ。これは HTTP レスポンスのボディバイト文字列であるべきです。これはデフォルトではプレーンテキストで "A server error occurred. Please contact the administrator." です。

PEP 3333 の "オプションのプラットフォーム固有のファイルハンドリング" 機能のためのメソッドと属性:

wsgi_file_wrapper

wsgi.file_wrapper ファクトリ、または None です。この属性のデフォルト値は wsgiref.util.FileWrapper クラスです。

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

バージョン 3.2 で追加.

使用例

これは動作する "Hello World" WSGIアプリケーションです:

from wsgiref.simple_server import make_server

# 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 (see PEP 333).
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()

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


urllib --- URL を扱うモジュール群

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

urllib --- URL を扱うモジュール群

ソースコード: Lib/urllib/

urllib は URL を扱う幾つかのモジュールを集めたパッケージです:

  • urllib.request は URL を開いて読むためのモジュールです
  • urllib.error は urllib.request が発生させる例外を持っています
  • urllib.parse は URL をパースするためのモジュールです
  • urllib.robotparser は robots.txt ファイルをパースするためのモジュールです

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


urllib.request --- URL を開くための拡張可能なライブラリ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

urllib.request --- URL を開くための拡張可能なライブラリ

ソースコード: Lib/urllib/request.py

urllib.request モジュールは基本的な認証、暗号化認証、リダイレクション、Cookie、その他の介在する複雑なアクセス環境において (大抵は HTTP で) URL を開くための関数とクラスを定義します。

参考

より高水準の HTTP クライアントインターフェイスとしては Requests パッケージ がお奨めです。

urllib.request モジュールでは以下の関数を定義しています:

urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)

URL url を開きます。 url は文字列でも Request オブジェクトでもかまいません。

data must be an object specifying additional data to be sent to the server, or None if no such data is needed. See Request for details.

urllib.request モジュールは HTTP/1.1 を使用し、その HTTP リクエストに Connection:close ヘッダーを含みます。

任意引数 timeout には接続開始などのブロックする操作におけるタイムアウト時間を秒数で指定します (指定されなかった場合、グローバルのデフォルトタイムアウト時間が利用されます)。この引数は、 HTTP, HTTPS, FTP 接続でのみ有効です。

context を指定する場合は、様々な SSL オプションを記述する ssl.SSLContext インスタンスでなければなりません。 詳細は HTTPSConnection を参照してください。

任意引数 cafile および capath には HTTPS リクエストのための CA 証明書のセットを指定します。cafile には CA 証明書のリストを含む 1 個のファイルを指定し、capath にはハッシュ化された証明書ファイルが格納されたディレクトリを指定しなければなりません。より詳しい情報は ssl.SSLContext.load_verify_locations() を参照してください。

cadefault 引数は無視されます。

この関数は常に コンテクストマネージャ として機能するオブジェクトを返します。このオブジェクトには以下のメソッドがあります。

  • geturl() --- 取得されたリソースの URL を返します。 主に、リダイレクトが発生したかどうかを確認するために利用します
  • info() --- return the meta-information of the page, such as headers, in the form of an email.message_from_string() instance (see Quick Reference to HTTP Headers)
  • getcode() -- レスポンスの HTTP ステータスコードです。

HTTP および HTTPS URL の場合、この関数は、わずかに修正された http.client.HTTPResponse オブジェクトを返します。上記の3つの新しいメソッドに加えて、 msg 属性が HTTPResponse のドキュメンテーションで指定されているレスポンスヘッダーの代わりに reason 属性 --- サーバーから返された reason フレーズ --- と同じ情報を含んでいます。

FTP 、ファイルおよびデータ URL 、レガシーな URLopener や FancyURLopener によって明示的に扱われるリクエストの場合、この関数は urllib.response.addinfourl オブジェクトを返します。

プロトコルエラー発生時は URLError を送出します。

どのハンドラもリクエストを処理しなかった場合には None を返すことがあるので注意してください (デフォルトでインストールされる グローバルハンドラの OpenerDirector は、 UnknownHandler を使って上記の問題が起きないようにしています)。

さらに、プロキシ設定が検出された場合(例えば http_proxy のような *_proxy 環境変数がセットされているなど)には ProxyHandler がデフォルトでインストールされ、これがプロキシを通してリクエストを処理するようにしています。

Python 2.6 以前のレガシーな urllib.urlopen 関数は廃止されました。urllib.request.urlopen() が過去の urllib2.urlopen に相当します。urllib.urlopen において辞書型オブジェクトで渡していたプロキシの扱いは、ProxyHandler オブジェクトを使用して取得できます。

バージョン 3.2 で変更: cafile および capath が追加されました。

バージョン 3.2 で変更: HTTPS バーチャルホストがサポートされました (ssl.HAS_SNI が真の場合のみ)。

バージョン 3.2 で追加: data にイテラブルなオブジェクトを指定できるようになりました。

バージョン 3.3 で変更: cadefault が追加されました。

バージョン 3.4.3 で変更: context が追加されました。

バージョン 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 という名前の環境変数を大文字小文字を区別せずにスキャンします。そこで見つからなかった場合、 Max OS X の場合は Mac OSX システム環境設定を、 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 は有効な 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. 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, Section 3.3.1 will be used to send files and other iterables.

For an HTTP POST request method, data should be a buffer in the standard application/x-www-form-urlencoded format. The urllib.parse.urlencode() function takes a mapping or sequence of 2-tuples and returns an ASCII string in this format. It should be encoded to bytes before being used as the data parameter.

headers は辞書でなければなりません。この辞書は 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の場合) と設定します。

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.

最後の二つの引数は、サードパーティの HTTP クッキーを正しく扱いたい場合にのみ関係してきます:

origin_req_host は、 RFC 2965 で定義されている元のトランザクションにおけるリクエストホスト (request-host of the origin transaction) です。デフォルトの値は http.cookiejar.request_host(self) です。この値は、ユーザーによって開始された元々のリクエストにおけるホスト名や IP アドレスです。例えば、もしリクエストがある HTML ドキュメント内の画像を指していれば、この値は画像を含んでいるページへのリクエストにおけるリクエストホストになるはずです。

unverifiable should indicate whether the request is unverifiable, as defined by RFC 2965. It defaults to False. An unverifiable request is one whose URL the user did not have the option to approve. For example, if the request is for an image in an HTML document, and the user had no option to approve the automatic fetching of the image, this should be true.

method should be a string that indicates the HTTP request method that will be used (e.g. 'HEAD'). If provided, its value is stored in the method attribute and is used by get_method(). The default is 'GET' if data is None or 'POST' otherwise. Subclasses may indicate a different default method by setting the method attribute in the class itself.

注釈

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)

Cause requests to go through a proxy. If proxies is given, it must be a dictionary mapping protocol names to URLs of proxies. The default is to read the list of proxies from the environment variables <protocol>_proxy. If no proxy environment variables are set, then in a Windows environment proxy settings are obtained from the registry's Internet Settings section, and in a Mac OS X environment proxy information is retrieved from the OS X 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 ハンドラによって使われます。

バージョン 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 が呼ばれます。

バージョン 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 を開きます。

バージョン 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

boolean, indicates whether the request is unverifiable as defined by RFC 2965.

Request.method

HTTP リクエストで使うメソッドです。 デフォルト値は None で、このときは使うメソッドを get_method() が通常の方法で決定するということになります。 この値を設定する (従って get_method() のデフォルトの決定を上書きする) 方法は、 Request サブクラスでのクラスレベルの設定処理でデフォルト値を提供するか、 Request のコンストラクタの method 引数へ値を渡すかです。

バージョン 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)

リクエストインスタンス (の通常のヘッダーと非リダイレクトヘッダーの両方) から名前つきヘッダーを削除します。

バージョン 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 は BaseHandler のインスタンスでなければなりません。以下のメソッドを使った検索が行われ、URL を取り扱うことが可能なハンドラの連鎖が追加されます (HTTP エラーは特別扱いされているので注意してください)。

  • protocol_open() --- ハンドラーが protocol の URL を開く方法を知っているかどうかを調べます。
  • http_error_type() --- ハンドラーが HTTP エラーコード type の処理方法を知っていることを示すシグナルです。
  • protocol_error() --- ハンドラーが (http でない) protocol のエラーを処理する方法を知っていることを示すシグナルです。
  • protocol_request() --- ハンドラーが protocol リクエストのプリプロセス方法を知っていることを示すシグナルです。
  • protocol_response() --- ハンドラーが protocol リクエストのポストプロセス方法を知っていることを示すシグナルです。
OpenerDirector.open(url, data=None[, timeout])

与えられた url (リクエストオブジェクトでも文字列でもかまいません) を開きます。オプションとして data を与えることができます。 引数、戻り値、および送出される例外は urlopen() と同じです (urlopen() の場合、標準でインストールされている グローバルな OpenerDirector の open() メソッドを呼び出します) 。 オプションの timeout 引数は、接続開始のようなブロックする処理におけるタイムアウト時間を 秒数で指定します。(指定しなかった場合は、グローバルのデフォルト設定が利用されます) タイムアウト機能は、 HTTP, HTTPS, FTP 接続でのみ有効です。

OpenerDirector.error(proto, *args)

与えられたプロトコルにおけるエラーを処理します。このメソッドは与えられたプロトコルにおける登録済みのエラーハンドラを (プロトコル固有の) 引数で呼び出します。 HTTP プロトコルは特殊なケースで、特定のエラーハンドラを選び出すのに HTTP レスポンスコードを使います; ハンドラクラスの http_error_*() メソッドを参照してください。

戻り値および送出される例外は urlopen() と同じものです。

OpenerDirector オブジェクトは、以下の 3 つのステージに分けて URL を開きます:

各ステージで OpenerDirector オブジェクトのメソッドがどのような順で呼び出されるかは、ハンドラインスタンスの並び方で決まります。

  1. protocol_request() 形式のメソッドを持つすべてのハンドラーに対してそのメソッドを呼び出し、リクエストのプリプロセスを行います。

  2. protocol_open() のようなメソッドでハンドラーが呼び出され、リクエストを処理します。このステージではハンドラーが非-None 値 (例: レスポンス) か例外 (通常は URLError) を返した時点で終了します。例外は伝搬できます。

    実際には、上のアルゴリズムではまず default_open() という名前のメソッドを呼び出します。このメソッドがすべて None を返す場合、同じアルゴリズムを繰り返して、今度は protocol_open() 形式のメソッドを試します。メソッドがすべて None を返すと、さらに同じアルゴリズムを繰り返して unknown_open() を呼び出します。

    これらのメソッドの実装には、親となる OpenerDirector インスタンスの open() や error() といったメソッド呼び出しが入る場合があるので注意してください。

  3. protocol_response() 形式のメソッドを持つすべてのハンドラーに対してそのメソッドを呼び出し、リクエストのポストプロセスを行います。

BaseHandler オブジェクト

BaseHandler オブジェクトは直接的に役に立つ 2 つのメソッドと、その他として派生クラスで使われることを想定したメソッドを 提供します。以下は直接的に使うためのメソッドです:

BaseHandler.add_parent(director)

親オブジェクトとして、 director を追加します。

BaseHandler.close()

全ての親オブジェクトを削除します。

以下の属性およびメソッドは BaseHandler から派生したクラスでのみ使われます。

注釈

慣習的に、 protocol_request() や protocol_response() といったメソッドを定義している サブクラスは *Processor と名づけ、その他は * Handler と名づけることになっています

BaseHandler.parent

有効な OpenerDirector です。この値は違うプロトコルを使って URL を開く場合やエラーを処理する際に使われます。

BaseHandler.default_open(req)

このメソッドは BaseHandler では定義されて いません 。しかし、全ての URL をキャッチさせたいなら、サブクラスで定義する 必要があります。

このメソッドが実装されていれば、OpenerDirector の親クラスによって呼び出されます。これは OpenerDirector の open() の戻り値で表されるファイルライクオブジェクトか、または None を返さなければならず、真に想定外の事態が発生した場合を除き、URLError を送出しなければなりません (例えば、MemoryError は URLError にマップしてはなりません)。

このメソッドはプロトコル固有のオープンメソッドが呼び出される前に呼び出されます。

BaseHandler.protocol_open(req)

このメソッドは BaseHandler では定義されて いません 。しかしプロトコルの URL をキャッチしたいなら、サブクラスで定義する必要があります。

このメソッドが定義されていた場合、 OpenerDirector から呼び出されます。戻り値は default_open() と同じでなければなりません。

BaseHandler.unknown_open(req)

このメソッドは BaseHandler では定義されて いません 。しかし URL を開くための特定のハンドラが登録されていないような URL をキャッチしたいなら、サブクラスで定義する必要があります。

このメソッドが定義されていた場合、 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 エラーに対する処理を行うためには、このメソッドをサブクラスでオーバライドする必要があります。

引数、返される値、および送出される例外は 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 を参照してください。

セキュリティ上の配慮として、HTTPRedirectHandler に HTTP、HTTPS、あるいは FTP の URL ではないリダイレクトされた URL が存在した場合、HTTPError 例外が送出されます。

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)

リダイレクトへのレスポンスの Request または None を返します。これはサーバーからリダイレクションを受信した時に http_error_30*() メソッドのデフォルトの実装によって呼び出されます。リダイレクションを行わなければならない場合、newurl へのリダイレクトを実行するための http_error_30*() を許可する新しい Request を返します。その他の場合、この URL を扱うその他のハンドラーがない場合は HTTPError を、他のハンドラーでできそうな場合は None を返します。

注釈

このメソッドのデフォルトの実装は、 RFC 2616 に厳密に従ったものではありません。 RFC 2616 では、 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)

http_error_301() と同じですが、'temporary redirect' レスポンスに対して呼び出されます。

HTTPCookieProcessor オブジェクト

HTTPCookieProcessor インスタンスは属性をひとつだけ持ちます:

HTTPCookieProcessor.cookiejar

Cookie の入っている http.cookiejar.CookieJar オブジェクトです。

ProxyHandler オブジェクト

ProxyHandler.protocol_open(request)

ProxyHandler は、コンストラクターで与えた辞書 proxies にプロキシが設定されているような protocol すべてについて、メソッド protocol_open() を持つことになります。このメソッドは request.set_proxy() を呼び出して、リクエストがプロキシを通過できるように修正します。その後連鎖するハンドラーの中から次のハンドラーを呼び出して実際にプロトコルを実行します。

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 は無視されます。

HTTPPasswordMgr.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. 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 の場合、レスポンスオブジェクトを即座に返します。

200 以外のエラーコードの場合、これは単に protocol_error_code() ハンドラーメソッドに OpenerDirector.error() 経由で処理を渡します。他にそのエラーを処理するハンドラーがない場合、HTTPDefaultErrorHandler は最後に HTTPError を送出します。

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() はデフォルトで沢山のハンドラを提供しており、その中に ProxyHandler があります。デフォルトでは、 ProxyHandler は <scheme>_proxy という環境変数を使います。 ここで <scheme> は URL スキームです。例えば、 HTTP プロキシの URL を得るには、環境変数 http_proxy を読み出します。

この例では、デフォルトの 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)

URL で表されるネットワークオブジェクトをローカルファイルにコピーします。 URL がローカルファイルを示している場合は、ファイル名が与えられない限りオブジェクトはコピーされません。戻り値はタプル (filename, headers) になり、 filename はオブジェクトが保存されたローカルファイル名、 headers は (リモートオブジェクトに対しては) urlopen() が返したオブジェクトの info() メソッドが返すものすべてになります。例外は 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() は、予想 (これは Content-Length ヘッダーにより通知されるサイズです) よりも取得できるデータ量が少ないことを検知した場合、 ContentTooShortError を発生します。これは、例えば、ダウンロードが中断された場合などに発生します。

Content-Length はデータ量の下限です: 読み込むデータ量がこれを超えている場合 urlretrieve はそれらも読み込みますが、利用できるデータがこれを下回った場合、例外が送出されます。

このような場合にもダウンロードされたデータを取得することは可能で、これは exception インスタンスの content 属性に保存されています。

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 と同じ意味を持っています。

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 です。

その他のレスポンスコードについては、 http_error_default() が呼ばれます。これはサブクラスでエラーを適切に処理するようにオーバーライドすることができます。

注釈

RFC 2616 によると、 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() を含む 最小限のファイルライクインターフェースを定義する関数およびクラスを定義しています。代表的なレスポンスオブジェクトは addinfourl インスタンスで、レスポンスヘッダーを返す info() メソッドおよび URL を返す geturl() メソッドを定義しています。このモジュールで定義された関数は、urllib.request モジュール内で使用されます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


urllib.parse --- URL を解析して構成要素にする

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

urllib.parse --- URL を解析して構成要素にする

ソースコード: Lib/urllib/parse.py

このモジュールでは URL (Uniform Resource Locator) 文字列をその構成要素 (アドレススキーム、ネットワーク上の位置、パスその他) に分解したり、構成要素を URL に組みなおしたり、 "相対 URL (relative URL)" を指定した "基底 URL (base URL)" に基づいて絶対 URL に変換するための標準的なインタフェースを定義しています。

このモジュールは Relative Uniform Resource Locators (相対 URL) に関するインターネット RFC に適合するよう設計されており、次の URL スキームをサポートしています: file, ftp, gopher, hdl, http, https, imap, mailto, mms, news, nntp, prospero, rsync, rtsp, rtspu, sftp, shttp, sip, sips, snews, svn, svn+ssh, telnet, wais, ws, wss

urllib.parse モジュールは、大きく分けると URL の解析を行う関数と URL のクオートを行う関数を定義しています。以下にこれらの詳細を説明します。

URL の解析

URL 解析関数は、URL 文字列を各構成要素に分割するか、あるいは URL の構成要素を組み合わせて URL 文字列を生成します。

urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)

URL を解析して 6 つの構成要素にし、6 要素のタプルを返します。このタプルは URL の一般的な構造: scheme://netloc/path;parameters?query#fragment に対応しています。各タプル要素は文字列で、空の場合もあります。構成要素がさらに小さい要素に分解されることはありません (例えばネットワーク上の位置は単一の文字列になります)。また % によるエスケープは展開されません。上で示された区切り文字がタプルの各要素の一部分として含まれることはありませんが、path 要素の先頭のスラッシュがある場合には例外です。たとえば以下のようになります:

>>> from urllib.parse import urlparse
>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
>>> o   # doctest: +NORMALIZE_WHITESPACE
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> o.scheme
'http'
>>> o.port
80
>>> o.geturl()
'http://www.cwi.nl:80/%7Eguido/Python.html'

RFC 1808 にある文法仕様に基づき、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 は空文字に設定されます。

戻り値は実際には tuple のサブクラスのインスタンスです。このクラスには以下の読み出し専用の便利な属性が追加されています:

属性 | インデックス | 値 | 指定されなかった場合の値
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 を送出します。

バージョン 3.2 で変更: IPv6 URL の解析も行えるようになりました。

バージョン 3.3 で変更: RFC 3986 に従い、fragment はすべての URL スキームに対して解析されるようになりました (allow_fragment が偽の場合は除く)。

バージョン 3.6 で変更: 範囲外のポート番号を指定すると、 None を返す代わりに、ValueError を送出するようになりました。

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None)

文字列引数として渡されたクエリ文字列 (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.

このような辞書をクエリ文字列に変換するには urllib.parse.urlencode() 関数を (doseq パラメータに True を指定して) 使用します。

バージョン 3.2 で変更: encoding および errors パラメータが追加されました。

バージョン 3.7.2 で変更: Added max_num_fields parameter.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None)

文字列引数として渡されたクエリ文字列 (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.

ペアのリストからクエリ文字列を生成する場合には urllib.parse.urlencode() 関数を使用します。

バージョン 3.2 で変更: encoding および errors パラメータが追加されました。

バージョン 3.7.2 で変更: Added max_num_fields parameter.

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 参照) が必要な場合に、 urlparse() の代わりに使われます。パスセグメントとパラメータを分割するためには分割用の関数が必要です。この関数は 5 要素のタプル: (アドレススキーム、ネットワーク上の位置、パス、クエリ、フラグメント識別子) を返します。

戻り値は実際には tuple のサブクラスのインスタンスです。このクラスには以下の読み出し専用の便利な属性が追加されています:

属性 | インデックス | 値 | 指定されなかった場合の値
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 を送出します。

バージョン 3.6 で変更: 範囲外のポート番号を指定すると、 None を返す代わりに、ValueError を送出するようになりました。

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 で定義された意味論とマッチするように挙動がアップデートされました。

urllib.parse.urldefrag(url)

url がフラグメント識別子を含む場合、フラグメント識別子を持たないバージョンに修正された url と、別の文字列に分割されたフラグメント識別子を返します。url 中にフラグメント識別子がない場合、そのままの url と空文字列を返します。

戻り値は実際には tuple のサブクラスのインスタンスです。このクラスには以下の読み出し専用の便利な属性が追加されています:

属性 | インデックス | 値 | 指定されなかった場合の値
url | 0 | フラグメントのない URL | 空文字列
fragment | 1 | フラグメント識別子 | 空文字列

結果オブジェクトのより詳しい情報は 構造化された解析結果 節を参照してください。

バージョン 3.2 で変更: 結果はシンプルな 2 要素のタプルから構造化オブジェクトに変更されました。

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 インスタンスを返します。

バージョン 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 インスタンスを返します。

バージョン 3.2 で追加.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)

urlparse() の具象クラスの結果には bytes が含まれます。decode() メソッドは ParseResult インスタンスを返します。

バージョン 3.2 で追加.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)

urlsplit() の具象クラスの結果には bytes データが含まれます。decode() メソッドは SplitResult インスタンスを返します。

バージョン 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 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 to RFC 3986 for quoting URL strings. "~" is now included in the set of reserved 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)

quote() と似ていますが、クエリ文字列を URL に挿入する時のために HTML フォームの値の空白をプラス記号「+」に置き換えます。オリジナルの文字列に「+」が存在した場合は safe に指定されている場合を除きエスケープされます。safe にデフォルト値は設定されていません。

例: 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')

エスケープされた %xx をそれに対応した単一文字に置き換えます。オプション引数の encoding と errors は bytes.decode() メソッドで受け付けられるパーセントエンコードされたシーケンスから Unicode 文字へのデコード法を指定します。

string は str でなければなりません。

encoding のデフォルトは 'utf-8'、errors のデフォルトは 'replace' で、不正なシーケンスはプレースホルダー文字に置き換えられます。

例: unquote('/El%20Ni%C3%B1o/') は '/El Niño/' を返します。

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)

スケープされた %xx をそれに対応した 1 オクテットに置き換え、bytes オブジェクトを返します。

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 クエリ文字列を生成するために、urlencode メソッドをどのように使えばよいかを見るには、urllib の使用例 を参照してください。

バージョン 3.2 で変更: クエリ文字列にバイト列と文字列オブジェクトをサポートしました。

バージョン 3.5 で追加: quote_via 引数。

参考

RFC 3986 - Uniform Resource Identifiers
これが現在の標準規格 (STD66) です。urllib.parse モジュールに対するすべての変更はこの規格に準拠していなければなりませんが、若干の逸脱はありえます。これは主には後方互換性のため、また主要なブラウザで一般的に見られる、URL を解析する上でのいくつかの事実上の要件を満たすためです。
RFC 2732 - Format for Literal IPv6 Addresses in URL's.
この規格は IPv6 の URL を解析するときの要求事項を記述しています。
RFC 2396 - Uniform Resource Identifiers (URI): Generic Syntax
この RFC では Uniform Resource Name (URN) と Uniform Resource Locator (URL) の両方に対する一般的な文法的要求事項を記述しています。
RFC 2368 - The mailto URL scheme.
mailto URL スキームに対する文法的要求事項です。
RFC 1808 - Relative Uniform Resource Locators
この RFC には絶対 URL と相対 URL を結合するための規則がボーダケースの取扱い方を決定する "異常な例" つきで収められています。
RFC 1738 - Uniform Resource Locators (URL)
この RFC では絶対 URL の形式的な文法と意味付けを仕様化しています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


urllib.error --- urllib.request が投げる例外

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

urllib.error --- urllib.request が投げる例外

ソースコード: Lib/urllib/error.py

urllib.error は urllib.request によって投げられる例外を定義しています。基底クラスは URLError です。

urllib.error は必要に応じて以下の例外が送出します:

exception urllib.error.URLError

ハンドラが何らかの問題に遭遇した場合、この例外 (またはこの例外から派生した例外)を送出します。この例外は OSError のサブクラスです。

reason

このエラーの理由。メッセージ文字列あるいは他の例外インスタンスです。

バージョン 3.3 で変更: URLError は IOError の代わりに OSError のサブクラスになりました。

exception urllib.error.HTTPError

HTTPError は例外 (URLError のサブクラス) ですが、同時に例外ではない file-like な戻り値を返す関数でもあります (urlopen() の戻り値と同じです)。これは、例えばサーバからの認証リクエストのように、変わった HTTP エラーを処理するのに役立ちます。

code

An HTTP status code as defined in RFC 2616. This numeric value corresponds to a value found in the dictionary of codes as found in http.server.BaseHTTPRequestHandler.responses.

reason

これは通常、このエラーの原因を説明する文字列です。

headers

HTTPError の原因となった HTTP リクエストの HTTP レスポンスヘッダ。

バージョン 3.4 で追加.

exception urllib.error.ContentTooShortError(msg, content)

この例外は urlretrieve() 関数が、ダウンロードされたデータの量が予期した量 (Content-Length ヘッダで与えられる) よりも少ないことを検知した際に発生します。 content 属性には (恐らく途中までの) ダウンロードされたデータが格納されています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


urllib.robotparser --- robots.txt のためのパーザ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

urllib.robotparser --- robots.txt のためのパーザ

ソースコード: 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.

バージョン 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.

バージョン 3.6 で追加.

The following example demonstrates basic use of the RobotFileParser class:

>>> 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 モジュール群

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

http --- HTTP モジュール群

ソースコード: Lib/http/__init__.py

http パッケージはハイパーテキスト転送プロトコルを扱うための幾つかのモジュールを集めたものです:

  • http.client は低水準のHTTPプロトコルのクライアントです。高水準の URL を開く操作には urllib.request を使ってください
  • http.server は socketserver をベースにした基礎的な HTTP サーバーを実装しています
  • http.cookies は cookie の状態管理を実装するためのユーティリティーを提供しています
  • http.cookiejar は cookie の永続化機能を提供しています

http は http.HTTPStatus 列挙子で 多くの HTTP ステータスコードと関連するメッセージを定義しているモジュールでもあります。

class http.HTTPStatus

バージョン 3.5 で追加.

一連の HTTP ステータスコード、理由の表現、英語で書かれた長い記述を定義した enum.IntEnum のサブクラスです。

使い方:

>>> from http import HTTPStatus
>>> HTTPStatus.OK
<HTTPStatus.OK: 200>
>>> HTTPStatus.OK == 200
True
>>> http.HTTPStatus.OK.value
200
>>> HTTPStatus.OK.phrase
'OK'
>>> HTTPStatus.OK.description
'Request fulfilled, document follows'
>>> list(HTTPStatus)
[<HTTPStatus.CONTINUE: 100>, <HTTPStatus.SWITCHING_PROTOCOLS: 101>, ...]

HTTP ステータスコード

サポートされている IANA に登録された http.HTTPStatus で利用可能なステータスコード:

コード | 列挙名 | 詳細
100 | CONTINUE | HTTP/1.1 RFC 7231, Section 6.2.1
101 | SWITCHING_PROTOCOLS | HTTP/1.1 RFC 7231, Section 6.2.2
102 | PROCESSING | WebDAV RFC 2518, Section 10.1
200 | OK | HTTP/1.1 RFC 7231, Section 6.3.1
201 | CREATED | HTTP/1.1 RFC 7231, Section 6.3.2
202 | ACCEPTED | HTTP/1.1 RFC 7231, Section 6.3.3
203 | NON_AUTHORITATIVE_INFORMATION | HTTP/1.1 RFC 7231, Section 6.3.4
204 | NO_CONTENT | HTTP/1.1 RFC 7231, Section 6.3.5
205 | RESET_CONTENT | HTTP/1.1 RFC 7231, Section 6.3.6
206 | PARTIAL_CONTENT | HTTP/1.1 RFC 7233, Section 4.1
207 | MULTI_STATUS | WebDAV RFC 4918, Section 11.1
208 | ALREADY_REPORTED | WebDAV Binding Extensions RFC 5842, Section 7.1 (Experimental)
226 | IM_USED | Delta Encoding in HTTP RFC 3229, Section 10.4.1
300 | MULTIPLE_CHOICES | HTTP/1.1 RFC 7231, Section 6.4.1
301 | MOVED_PERMANENTLY | HTTP/1.1 RFC 7231, Section 6.4.2
302 | FOUND | HTTP/1.1 RFC 7231, Section 6.4.3
303 | SEE_OTHER | HTTP/1.1 RFC 7231, Section 6.4.4
304 | NOT_MODIFIED | HTTP/1.1 RFC 7232, Section 4.1
305 | USE_PROXY | HTTP/1.1 RFC 7231, Section 6.4.5
307 | TEMPORARY_REDIRECT | HTTP/1.1 RFC 7231, Section 6.4.7
308 | PERMANENT_REDIRECT | Permanent Redirect RFC 7238, Section 3 (Experimental)
400 | BAD_REQUEST | HTTP/1.1 RFC 7231, Section 6.5.1
401 | UNAUTHORIZED | HTTP/1.1 Authentication RFC 7235, Section 3.1
402 | PAYMENT_REQUIRED | HTTP/1.1 RFC 7231, Section 6.5.2
403 | FORBIDDEN | HTTP/1.1 RFC 7231, Section 6.5.3
404 | NOT_FOUND | HTTP/1.1 RFC 7231, Section 6.5.4
405 | METHOD_NOT_ALLOWED | HTTP/1.1 RFC 7231, Section 6.5.5
406 | NOT_ACCEPTABLE | HTTP/1.1 RFC 7231, Section 6.5.6
407 | PROXY_AUTHENTICATION_REQUIRED | HTTP/1.1 Authentication RFC 7235, Section 3.2
408 | REQUEST_TIMEOUT | HTTP/1.1 RFC 7231, Section 6.5.7
409 | CONFLICT | HTTP/1.1 RFC 7231, Section 6.5.8
410 | GONE | HTTP/1.1 RFC 7231, Section 6.5.9
411 | LENGTH_REQUIRED | HTTP/1.1 RFC 7231, Section 6.5.10
412 | PRECONDITION_FAILED | HTTP/1.1 RFC 7232, Section 4.2
413 | REQUEST_ENTITY_TOO_LARGE | HTTP/1.1 RFC 7231, Section 6.5.11
414 | REQUEST_URI_TOO_LONG | HTTP/1.1 RFC 7231, Section 6.5.12
415 | UNSUPPORTED_MEDIA_TYPE | HTTP/1.1 RFC 7231, Section 6.5.13
416 | REQUEST_RANGE_NOT_SATISFIABLE | HTTP/1.1 Range Requests RFC 7233, Section 4.4
417 | EXPECTATION_FAILED | HTTP/1.1 RFC 7231, Section 6.5.14
421 | MISDIRECTED_REQUEST | HTTP/2 RFC 7540, Section 9.1.2
422 | UNPROCESSABLE_ENTITY | WebDAV RFC 4918, Section 11.2
423 | LOCKED | WebDAV RFC 4918, Section 11.3
424 | FAILED_DEPENDENCY | WebDAV RFC 4918, Section 11.4
426 | UPGRADE_REQUIRED | HTTP/1.1 RFC 7231, Section 6.5.15
428 | PRECONDITION_REQUIRED | Additional HTTP Status Codes RFC 6585
429 | TOO_MANY_REQUESTS | Additional HTTP Status Codes RFC 6585
431 | REQUEST_HEADER_FIELDS_TOO_LARGE | Additional HTTP Status Codes RFC 6585
500 | INTERNAL_SERVER_ERROR | HTTP/1.1 RFC 7231, Section 6.6.1
501 | NOT_IMPLEMENTED | HTTP/1.1 RFC 7231, Section 6.6.2
502 | BAD_GATEWAY | HTTP/1.1 RFC 7231, Section 6.6.3
503 | SERVICE_UNAVAILABLE | HTTP/1.1 RFC 7231, Section 6.6.4
504 | GATEWAY_TIMEOUT | HTTP/1.1 RFC 7231, Section 6.6.5
505 | HTTP_VERSION_NOT_SUPPORTED | HTTP/1.1 RFC 7231, Section 6.6.6
506 | VARIANT_ALSO_NEGOTIATES | Transparent Content Negotiation in HTTP RFC 2295, Section 8.1 (Experimental)
507 | INSUFFICIENT_STORAGE | WebDAV RFC 4918, Section 11.5
508 | LOOP_DETECTED | WebDAV Binding Extensions RFC 5842, Section 7.2 (Experimental)
510 | NOT_EXTENDED | An HTTP Extension Framework RFC 2774, Section 7 (Experimental)
511 | NETWORK_AUTHENTICATION_REQUIRED | Additional HTTP Status Codes RFC 6585, Section 6

後方互換性を保つために列挙値は http.client にも定数という形で存在します。 列挙名は定数名と同じです (すなわち http.HTTPStatus.OK は http.client.OK としても利用可能です)。

バージョン 3.7 で変更: Added 421 MISDIRECTED_REQUEST status code.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


http.client --- HTTP プロトコルクライアント

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

http.client --- HTTP プロトコルクライアント

ソースコード: Lib/http/client.py

このモジュールでは HTTP および HTTPS プロトコルのクライアントサイドを実装しているクラスを定義しています。通常、このモジュールは直接使いません --- urllib.request モジュールが HTTP や HTTPS を使った URL を扱う上でこのモジュールを使います。

参考

より高水準の HTTP クライアントインターフェイスとしては Requests パッケージ がお奨めです。

注釈

HTTPS のサポートは、Python が SSL サポート付きでコンパイルされている場合にのみ利用できます (ssl モジュールによって)。

このモジュールでは以下のクラスを提供しています:

class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None, blocksize=8192)

An HTTPConnection instance represents one transaction with an HTTP server. It should be instantiated passing it a host and optional port number. If no port number is passed, the port is extracted from the host string if it has the form host:port, else the default HTTP port (80) is used. If the optional timeout parameter is given, blocking operations (like connection attempts) will timeout after that many seconds (if it is not given, the global default timeout setting is used). The optional source_address parameter may be a tuple of a (host, port) to use as the source address the HTTP connection is made from. The optional blocksize parameter sets the buffer size in bytes for sending a file-like message body.

例えば、以下の呼び出しは全て同じサーバの同じポートに接続するインスタンスを生成します:

>>> 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 parameter was added.

class http.client.HTTPSConnection(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=None, blocksize=8192)

HTTPConnection のサブクラスはセキュア・サーバとやりとりする為の SSL を使う場合に用います。デフォルトのポート番号は 443 です。context が指定されれば、それは様々な SSL オプションを記述する ssl.SSLContext インスタンスでなければなりません。

ベストプラクティスに関するより良い情報が セキュリティで考慮すべき点 にありますのでお読みください。

バージョン 3.2 で変更: source_address、context そして check_hostname が追加されました。

バージョン 3.2 で変更: このクラスは現在、可能であれば(つまり ssl.HAS_SNI が真の場合) HTTPS のバーチャルホストをサポートしています。

バージョン 3.4 で変更: strict パラメータは廃止されました。HTTP 0.9 の "シンプルなレスポンス" のような形式はもはやサポートされません。

バージョン 3.4.3 で変更: このクラスは今や全ての必要な証明書とホスト名の検証をデフォルトで行うようになりました。昔の、検証を行わない振る舞いに戻したければ、 context に ssl._create_unverified_context() を渡すことで出来ます。

バージョン 3.6 で非推奨: key_file and cert_file 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.

The check_hostname parameter is also deprecated; the ssl.SSLContext.check_hostname attribute of context should be used instead.

class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)

コネクションに成功したときに、このクラスのインスタンスが返されます。ユーザーから直接利用されることはありません。

バージョン 3.4 で変更: strict パラメータは廃止されました。HTTP 0.9 の "シンプルなレスポンス" のような形式はもはやサポートされません。

状況に応じて、以下の例外が送出されます:

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.

バージョン 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)

このメソッドは、HTTP 要求メソッド method およびセレクタ url を使って、要求をサーバに送ります。

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.

headers 引数は要求と同時に送信される拡張 HTTP ヘッダの内容からなるマップ型でなくてはなりません。

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.

注釈

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.

バージョン 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).

ヘッダのパラメータは CONNECT リクエストで送信するために他の HTTP ヘッダにマッピングされます。

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")

バージョン 3.2 で追加.

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.

HTTPConnection.close()

サーバへの接続を閉じます。

HTTPConnection.blocksize

Buffer size in bytes for sending a file-like message body.

バージョン 3.7 で追加.

上で説明した request() メソッドを使うかわりに、以下の4つの関数を使用して要求をステップバイステップで送信することもできます。

HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)

This should be the first call after the connection to the server has been made. It sends a line to the server consisting of the method string, the url string, and the HTTP version (HTTP/1.1). To disable automatic sending of Host: or Accept-Encoding: headers (for example to accept additional content encodings), specify skip_host or skip_accept_encoding with non-False values.

HTTPConnection.putheader(header, argument[, ...])

RFC 822 形式のヘッダをサーバに送ります。この処理では、 header 、コロンとスペース、そして最初の引数からなる 1 行をサーバに送ります。追加の引数を指定した場合、継続して各行にタブ一つと引数の入った引数行が送信されます。

HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)

Send a blank line to the server, signalling the end of the headers. The optional message_body argument can be used to pass a message body associated with the request.

If encode_chunked is True, the result of each iteration of message_body will be chunk-encoded as specified in RFC 7230, 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 で追加: Chunked encoding support. The encode_chunked parameter was added.

HTTPConnection.send(data)

サーバにデータを送ります。このメソッドは endheaders() が呼び出された直後で、かつ getresponse() が呼び出される前に使わなければなりません。

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) バイト読み込みます。何バイト読んだかを返します。

バージョン 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.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 となります。

使用例

以下は 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 not r1.closed:
...     print(r1.read(200))  # 200 bytes
b'<!doctype html>\n<!--[if"...
...
>>> # Example of an invalid request
>>> 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

以下は POST リクエストの送信方法を示した例です:

>>> 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="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
>>> conn.close()

Client side HTTP PUT requests are very similar to POST requests. The difference lies only the server side where HTTP server will allow resources to be created via PUT request. It should be noted that custom HTTP methods +are also handled in urllib.request.Request by sending the appropriate +method attribute.Here is an example session that shows how to do PUT request using http.client:

>>> # This creates an HTTP message
>>> # 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 オブジェクト

http.client.HTTPMessage のインスタンスは HTTP レスポンスヘッダを格納します。 email.message.Message クラスを利用して実装されています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


ftplib --- FTPプロトコルクライアント

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

ftplib --- FTPプロトコルクライアント

ソースコード: Lib/ftplib.py

This module defines the class FTP and a few related items. The FTP class implements the client side of the FTP protocol. You can use this to write Python programs that perform a variety of automated FTP jobs, such as mirroring other FTP servers. It is also used by the module urllib.request to handle URLs that use FTP. For more information on FTP (File Transfer Protocol), see Internet RFC 959.

ftplib モジュールを使ったサンプルを以下に示します:

>>> from ftplib import FTP
>>> ftp = FTP('ftp.debian.org')     # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
>>> 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.'
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
'226 Transfer complete.'
>>> ftp.quit()

このモジュールは以下の項目を定義しています:

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None)

Return a new instance of the FTP class. When host is given, the method call connect(host) is made. When user is given, additionally the method call login(user, passwd, acct) is made (where passwd and acct default to the empty string when not given). The optional timeout parameter specifies a timeout in seconds for blocking operations like the connection attempt (if is not specified, the global default timeout setting will be used). source_address is a 2-tuple (host, port) for the socket to bind to as its source address before connecting.

FTP クラスは with 文をサポートしています。例えば:

>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
...     ftp.login()
...     ftp.dir()
... # doctest: +SKIP
'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 引数が追加されました。

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None)

RFC 4217 に記述されている TLS サポートを FTP に加えた FTP のサブクラスです。認証の前に FTP コントロール接続を暗黙にセキュアにし、通常通りに port 21 に接続します。データ接続をセキュアにするには、ユーザが prot_p() メソッドを呼び出してそれを明示的に要求しなければなりません。 context は SSL 設定オプション、証明書、秘密鍵を一つの(潜在的に長生きの)構造にまとめた ssl.SSLContext オブジェクトです。ベストプラクティスについての セキュリティで考慮すべき点 をお読みください。

keyfile と certfile は context のレガシー版です -- これらは、SSL 接続のための、 PEM フォーマットの秘密鍵と証明書チェーンファイル名(前者が keyfile 、後者が certfile )を含むことができます。

バージョン 3.2 で追加.

バージョン 3.3 で変更: source_address 引数が追加されました。

バージョン 3.4 で変更: このクラスは ssl.SSLContext.check_hostname と Server Name Indication でホスト名のチェックをサポートしました。(ssl.HAS_SNI を参照してください)。

バージョン 3.6 で非推奨: keyfile and certfile 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.

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']
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 も含まれます。

参考

netrc モジュール
.netrc ファイルフォーマットのパーザ。 .netrc ファイルは、 FTPクライアントがユーザにプロンプトを出す前に、ユーザ認証情報をロードするのによく使われます。

FTP オブジェクト

いくつかのコマンドは２つのタイプについて実行します：１つはテキストファイルで、もう１つはバイナリファイルを扱います。これらのメソッドのテキストバージョンでは lines 、バイナリバージョンでは binary の語がメソッド名の終わりについています。

FTP インスタンスには以下のメソッドがあります:

FTP.set_debuglevel(level)

インスタンスのデバッグレベルを設定します。この設定によってデバッグ時に出力される量を調節します。デフォルトは 0 で、何も出力されません。 1 なら、一般的に１つのコマンドあたり１行の適当な量のデバッグ出力を行います。 2 以上なら、コントロール接続で受信した各行を出力して、最大のデバッグ出力をします。

FTP.connect(host='', port=0, timeout=None, source_address=None)

Connect to the given host and port. The default port number is 21, as specified by the FTP protocol specification. It is rarely needed to specify a different port number. This function should be called only once for each instance; it should not be called at all if a host was given when the instance was created. All other methods can only be used after a connection has been made. The optional timeout parameter specifies a timeout in seconds for the connection attempt. If no timeout is passed, the global default timeout setting will be used. source_address is a 2-tuple (host, port) for the socket to bind to as its source address before connecting.

バージョン 3.3 で変更: source_address 引数が追加されました。

FTP.getwelcome()

サーバに最初に接続した際に送信される応答中のウェルカムメッセージを返します。(このメッセージには時に、ユーザにとって重要な免責事項や ヘルプ情報が入っています。)

FTP.login(user='anonymous', passwd='', acct='')

与えられた user でログインします。 passwd と acct のパラメータは省略可能で、デフォルトでは空文字列です。もし user が指定されないなら、デフォルトで 'anonymous' になります。もし user が 'anonymous' なら、デフォルトの passwd は 'anonymous@' になります。この関数は各インスタンスについて一度だけ、接続が確立した後に呼び出さなければなりません。インスタンスが作られた時にホスト名とユーザ名が与えられていたら、このメソッドを実行すべきではありません。ほとんどのFTPコマンドはクライアントがログインした後に実行可能になります。 acct 引数は "accounting information" を提供します。ほとんどのシステムはこれを実装していません。

FTP.abort()

実行中のファイル転送を中止します。これはいつも機能するわけではありませんが、やってみる価値はあります。

FTP.sendcmd(cmd)

シンプルなコマンド文字列をサーバに送信して、受信した文字列を返します。

FTP.voidcmd(cmd)

シンプルなコマンド文字列をサーバに送信して、その応答を扱います。応答コードが成功に関係するもの(200--299の範囲にあるコード)なら何も返しません。それ以外は error_reply を発生します。

FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)

Retrieve a file in binary transfer mode. cmd should be an appropriate RETR command: 'RETR filename'. The callback function is called for each block of data received, with a single bytes argument giving the data block. The optional blocksize argument specifies the maximum chunk size to read on the low-level socket object created to do the actual transfer (which will also be the largest size of the data blocks passed to callback). A reasonable default is chosen. rest means the same thing as in the transfercmd() method.

FTP.retrlines(cmd, callback=None)

Retrieve a file or directory listing in ASCII transfer mode. 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.

FTP.set_pasv(val)

Enable "passive" mode if val is true, otherwise disable passive mode. Passive mode is on by default.

FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

Store a file in binary transfer mode. cmd should be an appropriate STOR command: "STOR filename". fp is 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. The blocksize argument defaults to 8192. callback is an optional single parameter callable that is called on each block of data after it is sent. rest means the same thing as in the transfercmd() method.

バージョン 3.2 で変更: rest パラメタが追加されました。

FTP.storlines(cmd, fp, callback=None)

Store a file in ASCII transfer 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.

FTP.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 RFC 959 requires only that rest be a string containing characters in the printable range from ASCII code 33 to ASCII code 126. The transfercmd() method, therefore, converts rest to a string, 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.

FTP.ntransfercmd(cmd, rest=None)

transfercmd() と同様ですが、データと予想されるサイズとのタプルを返します。もしサイズが計算できないなら、サイズの代わりに None が返されます。 cmd と rest は transfercmd() のものと同じです。

FTP.mlsd(path="", facts=[])

List a directory in a standardized format by using MLSD command ( RFC 3659). 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.

バージョン 3.3 で追加.

FTP.nlst(argument[, ...])

NLST コマンドで返されるファイル名のリストを返します。省略可能な argument は、リストアップするディレクトリです（デフォルトではサーバのカレントディレクトリです）。 NLST コマンドに非標準である複数の引数を渡すことができます。

注釈

If your server supports the command, mlsd() offers a better API.

FTP.dir(argument[, ...])

LIST コマンドで返されるディレクトリ内のリストを作り、標準出力へ出力します。省略可能な argument は、リストアップするディレクトリです（デフォルトではサーバのカレントディレクトリです）。 LIST コマンドに非標準である複数の引数を渡すことができます。もし最後の引数が関数なら、 retrlines() のように callback として使われます; デフォルトでは sys.stdout に印字します。このメソッドは None を返します。

注釈

If your server supports the command, mlsd() offers a better API.

FTP.rename(fromname, toname)

サーバ上のファイルのファイル名 fromname を toname へ変更します。

FTP.delete(filename)

サーバからファイル filename を削除します。成功したら応答のテキストを返し、そうでないならパーミッションエラーでは error_perm を、他のエラーでは error_reply を返します。

FTP.cwd(pathname)

サーバのカレントディレクトリを設定します。

FTP.mkd(pathname)

サーバ上に新たにディレクトリを作ります。

FTP.pwd()

サーバ上のカレントディレクトリのパスを返します。

FTP.rmd(dirname)

サーバ上のディレクトリ dirname を削除します。

FTP.size(filename)

サーバ上のファイル filename のサイズを尋ねます。成功したらファイルサイズが整数で返され、そうでないなら None が返されます。 SIZE コマンドは標準化されていませんが、多くの普通のサーバで実装されていることに注意して下さい。

FTP.quit()

サーバに QUIT コマンドを送信し、接続を閉じます。これは接続を閉じるのに"礼儀正しい"方法ですが、 QUIT コマンドに反応してサーバの例外が発生するかもしれません。この例外は、 close() メソッドによって FTP インスタンスに対するその後のコマンド使用が不可になっていることを示しています（下記参照）。

FTP.close()

接続を一方的に閉じます。既に閉じた接続に対して実行すべきではありません（例えば quit() を呼び出して成功した後など）。この実行の後、 FTP インスタンスはもう使用すべきではありません（ close() あるいは quit() を呼び出した後で、 login() メソッドをもう一度実行して再び接続を開くことはできません）。

FTP_TLS オブジェクト

FTP_TLS クラスは FTP を継承し、さらにオブジェクトを定義します:

FTP_TLS.ssl_version

使用する SSL のバージョン (デフォルトは ssl.PROTOCOL_SSLv23) です。

FTP_TLS.auth()

Set up a secure control connection by using TLS or SSL, depending on what is specified in the ssl_version attribute.

バージョン 3.4 で変更: このメソッドは ssl.SSLContext.check_hostname と Server Name Indication でホスト名のチェックをサポートしました。(ssl.HAS_SNI を参照してください)。

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

バージョン 3.3 で追加.

FTP_TLS.prot_p()

セキュアデータ接続をセットアップします。

FTP_TLS.prot_c()

平文データ接続をセットアップします。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


poplib --- POP3 プロトコルクライアント

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

poplib --- POP3 プロトコルクライアント

ソースコード: Lib/poplib.py

このモジュールはクラス POP3 を定義しています。 POP3 はPOP3 サーバへの接続をカプセル化し、 RFC 1939 で定義されているプロトコルを実装しています。 POP3 クラスは RFC 1939 の最小限のコマンドセットとオプションのコマンドセットをサポートしています。 既に確立されている接続で暗号化された通信を行うために、 RFC 2595 で導入された STLS コマンドもサポートされています。

加えて、このモジュールはクラス POP3_SSL を提供しています。 POP3_SSL は SSL を下層のプロトコルレイヤーとして使う POP3 サーバへの接続をサポートしています。

POP3についての注意事項は、それが広くサポートされているにもかかわらず、既に時代遅れだということです。幾つも実装されているPOP3サーバーの品質は、貧弱なものが多数を占めています。もし、お使いのメールサーバーがIMAPをサポートしているなら、 imaplib.IMAP4 クラスが使えます。 IMAPサーバーは、より良く実装されている傾向があります。

poplib モジュールは二つのクラスを提供します:

class poplib.POP3(host, port=POP3_PORT[, timeout])

このクラスが、実際にPOP3プロトコルを実装します。インスタンスが初期化されるときに、コネクションが作成されます。 port が省略されると、POP3標準のポート(110)が使われます。オプションの timeout 引数は、接続時のタイムアウト時間を秒数で指定します (指定されなかった場合は、グローバルのデフォルトタイムアウト設定が利用されます)。

class poplib.POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)

POP3 クラスのサブクラスで、SSL でカプセル化されたソケットによる POP サーバへの接続を提供します。 port が指定されていない場合、 POP3-over-SSL 標準の 995 番ポートが使われます。timeout については POP3 クラスのコンストラクタの引数と同じです。 context は SSL の設定、証明書、秘密鍵を一つの (POP3_SSL オブジェクトよりも長く存在し続けうる) 構造にまとめた ssl.SSLContext オブジェクトで、省略可能です。ベストプラクティスについては セキュリティで考慮すべき点 を参照してください。

keyfile と certfile は context のレガシー版です - これらは、SSL 接続のための、 PEM フォーマットの秘密鍵と証明書チェーンファイル名(前者が keyfile 、後者が certfile )を含むことができます。

バージョン 3.2 で変更: context 引数が追加されました。

バージョン 3.4 で変更: このクラスは ssl.SSLContext.check_hostname と Server Name Indication でホスト名のチェックをサポートしました。(ssl.HAS_SNI を参照してください)。

バージョン 3.6 で非推奨: keyfile and certfile 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.

1つの例外が、 poplib モジュールのアトリビュートとして定義されています:

exception poplib.error_proto

このモジュール内で起こったあらゆるエラーで送出される例外です (socket モジュールからのエラーは捕捉されません)。例外の理由は文字列としてコンストラクタに渡されます。

参考

モジュール imaplib
標準 Python IMAP モジュールです。
Frequently Asked Questions About Fetchmail
POP/IMAPクライアント fetchmail のFAQ。POPプロトコルをベースにしたアプリケーションを書くときに有用な、POP3サーバの種類や RFCへの適合度といった情報を収集しています。

POP3 オブジェクト

POP3コマンドはすべて、それと同じ名前のメソッドとしてlower-caseで表現されます。そしてそのほとんどは、サーバからのレスポンスとなるテキストを返します。

POP3 クラスのインスタンスは以下のメソッドを持ちます:

POP3.set_debuglevel(level)

インスタンスのデバッグレベルを設定します。この設定によってデバッグ時に出力される量を調節します。デフォルトは 0 で、何も出力されません。 1 なら、一般的に１つのコマンドあたり１行の適当な量のデバッグ出力を行います。 2 以上なら、コントロール接続で受信した各行を出力して、最大のデバッグ出力をします。

POP3.getwelcome()

POP3サーバーから送られるグリーティングメッセージを返します。

POP3.capa()

RFC 2449 で規定されている機能についてサーバに問い合わせます。{'name': ['param'...]} という形の辞書を返します。

バージョン 3.4 で追加.

POP3.user(username)

userコマンドを送出します。応答はパスワード要求を表示します。

POP3.pass_(password)

パスワードを送出します。応答は、メッセージ数とメールボックスのサイズを含みます。注意：サーバー上のメールボックスは quit() が呼ばれるまでロックされます。

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 で規定されています。

バージョン 3.5 で追加.

POP3.stls(context=None)

アクティブな接続にて RFC 2595 で定められた方法で TLS セッションを開始します。TLS セッションはユーザ認証を行う前に開始する必要があります。

context は SSL の設定、証明書、秘密鍵を一つの (POP3 オブジェクトよりも長く存在し続けうる) 構造にまとめた ssl.SSLContext オブジェクトです。ベストプラクティスについては セキュリティで考慮すべき点 を参照してください。

このメソッドは ssl.SSLContext.check_hostname と Server Name Indication でホスト名のチェックをサポートしました。(ssl.HAS_SNI を参照してください)。

バージョン 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 プロトコルクライアント

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

imaplib --- IMAP4 プロトコルクライアント

ソースコード: Lib/imaplib.py

このモジュールでは三つのクラス、 IMAP4, IMAP4_SSL と IMAP4_stream を定義します。これらのクラスは IMAP4 サーバへの接続をカプセル化し、 RFC 2060 に定義されている IMAP4rev1 クライアントプロトコルの大規模なサブセットを実装しています。このクラスは IMAP4 ( RFC 1730) 準拠のサーバと後方互換性がありますが、 STATUS コマンドは IMAP4 ではサポートされていないので注意してください。

imaplib モジュール内では三つのクラスを提供しており、 IMAP4 は基底クラスとなります:

class imaplib.IMAP4(host='', port=IMAP4_PORT)

このクラスは実際の IMAP4 プロトコルを実装しています。インスタンスが初期化された際に接続が生成され、プロトコルバージョン (IMAP4 または IMAP4rev1) が決定されます。host が指定されていない場合、'' (ローカルホスト) が用いられます。port が省略された場合、標準の IMAP4 ポート番号 (143) が用いられます。

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 構文のサポートが追加されました。

例外は 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, keyfile=None, certfile=None, ssl_context=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.

keyfile and certfile are a legacy alternative to ssl_context - they can point to PEM-formatted private key and certificate chain files for the SSL connection. Note that the keyfile/certfile parameters are mutually exclusive with ssl_context, a ValueError is raised if keyfile/certfile is provided along with ssl_context.

バージョン 3.3 で変更: ssl_context parameter added.

バージョン 3.4 で変更: このクラスは ssl.SSLContext.check_hostname と Server Name Indication でホスト名のチェックをサポートしました。(ssl.HAS_SNI を参照してください)。

バージョン 3.6 で非推奨: keyfile and certfile are deprecated in favor of ssl_context. Please use ssl.SSLContext.load_cert_chain() instead, or let ssl.create_default_context() select the system's trusted CA certificates for you.

さらにもう一つのサブクラスは、子プロセスで確立した接続を使用する場合に使用します:

class imaplib.IMAP4_stream(command)

IMAP4 から派生したサブクラスで、 command を subprocess.Popen() に渡して作成される stdin/stdout ディスクリプタと接続します。

以下のユーティリティ関数が定義されています:

imaplib.Internaldate2tuple(datestr)

Parse an IMAP4 INTERNALDATE string and return corresponding local time. The return value is a time.struct_time tuple or None if the string has wrong format.

imaplib.Int2AP(num)

整数を [A .. P] からなる文字集合を用いて表現した文字列に変換します。

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 を利用するよう強く勧めます。

モジュールの末尾に、より拡張的な使用例が収められたテストセクションがあります。

参考

プロトコルに関する記述、およびプロトコルを実装したサーバのソースとバイナリは、全てワシントン大学の IMAP Information Center (https://www.washington.edu/imap/) にあります。

IMAP4 オブジェクト

全ての IMAP4rev1 命令は、同じ名前のメソッドで表されており、大文字のものも小文字のものもあります。

命令に対する引数は全て文字列に変換されます。例外は AUTHENTICATE の引数と APPEND の最後の引数で、これは IMAP4 リテラルとして渡されます。必要に応じて (IMAP4 プロトコルが感知対象としている文字が文字列に入っており、かつ丸括弧か二重引用符で囲われていなかった場合) 文字列はクオートされます。しかし、LOGIN 命令の password 引数は常にクオートされます。文字列がクオートされないようにしたい (例えば STORE 命令の flags 引数) 場合、文字列を丸括弧で囲んでください (例: r'(\Deleted)')。

各命令はタプル: (type, [data, ...]) を返し、type は通常 'OK' または 'NO' です。data は命令に対する応答をテキストにしたものか、命令に対する実行結果です。各 data は文字列かタプルとなります。タプルの場合、最初の要素はレスポンスのヘッダで、次の要素にはデータが格納されます (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). Most capabilities do not need to be enabled. Currently only the UTF8=ACCEPT capability is supported (see RFC 6855).

バージョン 3.5 で追加: The enable() method itself, and RFC 6855 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 で定義されている IMAP4 QUOTA 拡張の一部です。

IMAP4.getquotaroot(mailbox)

mailbox に対して quota root を実行した結果のリストを取得します。このメソッドは RFC 2087 で定義されている 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 応答を返します。

IMAP4.lsub(directory='""', pattern='*')

購読しているメールボックス名のうち、ディレクトリ内でパターンにマッチするものを列挙します。directory の標準の設定値は最上レベルのメールフォルダで、pattern は標準の設定では全てにマッチします。返されるデータには返されるデータはメッセージパートエンベロープ情報とデータからなるタプルです。

IMAP4.myrights(mailbox)

mailboxにおける自分のACLを返します (すなわち自分がmailboxで持っている権限を返します)。

IMAP4.namespace()

Returns IMAP namespaces as defined in RFC 2342.

IMAP4.noop()

サーバに NOOP を送信します。

IMAP4.open(host, port)

host 上の port に対するソケットを開きます。このメソッドは IMAP4 のコンストラクタから暗黙的に呼び出されます。このメソッドで確立された接続オブジェクトは IMAP4.read(), IMAP4.readline(), IMAP4.send(), IMAP4.shutdown() メソッドで使われます。このメソッドはオーバライドすることができます。

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 を送信します。このメソッドはオーバライドすることができます。

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 で定義されている 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.

バージョン 3.2 で追加.

バージョン 3.4 で変更: このメソッドは ssl.SSLContext.check_hostname と Server Name Indication でホスト名のチェックをサポートしました。(ssl.HAS_SNI を参照してください)。

IMAP4.status(mailbox, names)

mailbox の指定ステータス名の状態情報を要求します。

IMAP4.store(message_set, command, flag_list)

メールボックス内のメッセージ群のフラグ設定を変更します。 command は RFC 2060 のセクション 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 (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 コマンドは search_criterion 引数の前に2つの引数を持っています。threading_algorithm と charset です。search コマンドとは違い、charset は必須です。search に対する uid search と同様に、thread にも uid thread があります。thread コマンドはまずメールボックス中のメッセージを、charsetを用いた検索条件で検索します。その後マッチしたメッセージを指定されたスレッドアルゴリズムでスレッド化して返します.

IMAP4rev1 拡張命令です。

IMAP4.uid(command, arg[, ...])

command args を、メッセージ番号ではなく UID で指定されたメッセージ群に対して実行します。命令内容に応じた応答を返します。少なくとも一つの引数を与えなくてはなりません; 何も与えない場合、サーバはエラーを返し、例外が送出されます。

IMAP4.unsubscribe(mailbox)

古いメールボックスの購読を解除 (unsubscribe) します。

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.

バージョン 3.5 で追加.

IMAP4 の使用例

以下にメールボックスを開き、全てのメッセージを取得して印刷する最小の (エラーチェックをしない) 使用例を示します:

import getpass, imaplib

M = imaplib.IMAP4()
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()

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

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

ソースコード: Lib/nntplib.py

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 as well as the older RFC 977 and RFC 2980.

以下にこのモジュールの使い方の小さな例を二つ示します。ニュースグループに関する統計情報を列挙し、最新 10 件の記事を出力するには以下のようにします:

>>> s = nntplib.NNTP('news.gmane.org')
>>> 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.org')
>>> 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.org') as n:
...     n.group('gmane.comp.python.committers')
... # doctest: +SKIP
('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
>>>

バージョン 3.2 で変更: usenetrc がデフォルトで False になりました。

バージョン 3.3 で変更: with 構文のサポートが追加されました。

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, in favor of STARTTLS as described below. However, some servers only support the former.

バージョン 3.2 で追加.

バージョン 3.4 で変更: このクラスは ssl.SSLContext.check_hostname と Server Name Indication でホスト名のチェックをサポートしました。(ssl.HAS_SNI を参照してください)。

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 準拠を通知しているサーバでは 2 で、他の場合は 1 のはずです。

バージョン 3.2 で追加.

NNTP.nntp_implementation

NNTP サーバのソフトウェア名とバージョンを記述する文字列です。 サーバが通知していない場合は None です。

バージョン 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 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.org')
>>> 'POST' in s.getcapabilities()
True

バージョン 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.

バージョン 3.2 で追加.

NNTP.starttls(ssl_context=None)

Send a STARTTLS command. This will enable encryption on the NNTP connection. The ssl_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.

バージョン 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) # doctest: +SKIP
85
>>> groups[0] # doctest: +SKIP
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 (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) # doctest: +SKIP
295
>>> descs.popitem() # doctest: +SKIP
('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>'

バージョン 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. Some of them have been superseded by newer commands in RFC 3977.

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.

NNTP.xpath(id)

Return a pair (resp, path), where path is the directory path to the article with message ID id. Most of the time, this extension is not enabled by NNTP server administrators.

バージョン 3.3 で非推奨: XPATH 拡張は積極的に使われません。

ユーティリティー関数

このモジュールは以下のユーティリティ関数も定義しています:

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'

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


smtplib --- SMTP プロトコルクライアント

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

smtplib --- SMTP プロトコルクライアント

ソースコード: Lib/smtplib.py

smtplib モジュールは、SMTPまたはESMTPのリスナーデーモンを備えた任意のインターネット上のホストにメールを送るために使用することができる SMTPクライアント・セッション・オブジェクトを定義します。 SMTPおよびESMTPオペレーションの詳細は、 RFC 821 (Simple Mail Transfer Protocol) や RFC 1869 (SMTP Service Extensions)を調べてください。

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 パラメータは、接続試行のようなブロッキング操作のタイムアウトを秒単位で指定します（指定されていない場合、グローバルなデフォルトのタイムアウト設定が使用されます）。タイムアウトが切れると、 socket.timeout が送出されます。オプションのsource_addressパラメータを使用すると、複数のネットワークインターフェイスを持つマシンの特定の送信元アドレス、かつ（または）特定の送信元TCPポートにバインドできます。接続する前にソケットを送信元アドレスとしてバインドするためにタプル(host, port)が必要です。省略された場合（あるいは、hostまたはportがそれぞれ '' かつ/または0の場合）、OSのデフォルト動作が使用されます。

For normal use, you should only require the initialization/connect, sendmail(), and SMTP.quit() methods. An example is included below.

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')
>>>

バージョン 3.3 で変更: with 構文のサポートが追加されました。

バージョン 3.3 で変更: source_address 引数が追加されました。

バージョン 3.5 で追加: SMTPUTF8 拡張 ( RFC 6531) がサポートされました。

class smtplib.SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, certfile=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 を含むことができ、安全な接続のさまざまな側面を設定することができます。ベストプラクティスについては セキュリティで考慮すべき点 を読んでください。

keyfile and certfile are a legacy alternative to context, and can point to a PEM formatted private key and certificate chain file for the SSL connection.

バージョン 3.3 で変更: context が追加されました。

バージョン 3.3 で変更: source_address 引数が追加されました。

バージョン 3.4 で変更: このクラスは ssl.SSLContext.check_hostname と Server Name Indication でホスト名のチェックをサポートしました。(ssl.HAS_SNI を参照してください)。

バージョン 3.6 で非推奨: keyfile and certfile 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.

class smtplib.LMTP(host='', port=LMTP_PORT, local_hostname=None, source_address=None)

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は通常認証をサポートしたり要求したりはしません。しかし、あなたが必要であれば、利用することができます。

このモジュールの例外には次のものがあります:

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

試行したコマンドやオプションはサーバにサポートされていません。

バージョン 3.5 で追加.

exception smtplib.SMTPAuthenticationError

SMTP 認証が失敗しました。最もあり得るのは、サーバーがユーザ名/パスワードのペアを受け付なかった事です。

参考

RFC 821 - Simple Mail Transfer Protocol
SMTP のプロトコル定義です。このドキュメントでは SMTP のモデル、操作手順、プロトコルの詳細についてカバーしています。
RFC 1869 - 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要素タプルです。

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()

This method calls ehlo() and/or helo() if there has been no previous EHLO or HELO command this session. It tries ESMTP EHLO first.

SMTPHeloError
サーバーが HELO に正しく返答しませんでした。
SMTP.has_extn(name)

name が拡張SMTPサービスセットに含まれている場合には True を返し、そうでなければ False を返します。大小文字は区別されません。

SMTP.verify(address)

VRFY を利用してSMTPサーバにアドレスの妥当性をチェックします。妥当である場合はコード250と完全な RFC 822 アドレス (人名を含む) のタプルを返します。それ以外の場合は、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 で指定された"初期応答"を送信できるかどうかを指定します。

バージョン 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 "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.

バージョン 3.5 で追加.

SMTP.starttls(keyfile=None, certfile=None, 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.6 で非推奨: keyfile and certfile 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.

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 のfromアドレス文字列、 RFC 822 の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エラーコードと付随するエラーメッセージのタプルを持ちます。

If SMTPUTF8 is included in mail_options, and the server supports it, from_addr and to_addrs may contain non-ASCII characters.

このメソッドは次の例外を送出することがあります:

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

バージョン 3.2 で追加.

バージョン 3.5 で追加: 国際化アドレスのサポート (SMTPUTF8)。

SMTP.quit()

SMTPセッションを終了し、接続を閉じます。SMTP QUIT コマンドの結果を返します。

下位レベルのメソッドは標準SMTP/ESMTPコマンド HELP 、 RSET 、 NOOP 、 MAIL 、 RCPT 、 DATA に対応しています。通常これらは直接呼ぶ必要はなく、また、ドキュメントもありません。詳細はモジュールのコードを調べてください。

SMTP 使用例

次の例は最低限必要なメールアドレス('To' と 'From')を含んだメッセージを送信するものです。この例では RFC 822 ヘッダの加工もしていません。メッセージに含まれるヘッダは、メッセージに含まれる必要があり、特に、明確な '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: 使用例 を参照してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


smtpd --- SMTP サーバー

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

smtpd --- SMTP サーバー

ソースコード: Lib/smtpd.py

このモジュールは SMTP (email) サーバを実装するためのいくつかのクラスを提供しています。

参考

The aiosmtpd package is a recommended replacement for this module. It is based on asyncio and provides a more straightforward API. smtpd should be considered deprecated.

サーバの実装がいくつかあります。一つはジェネリックで何もしない実装で、オーバーライドすることが出来ます。他の二つは特定のメール送信方策を提供しています。

また、SMTPChannel を拡張して SMTP クライアントとの特定の相互作用挙動を実装することができます。

コードは RFC 5321 に加え、 RFC 1870 SIZE と RFC 6531 SMTPUTF8 拡張をサポートしています。

SMTPServer オブジェクト

class smtpd.SMTPServer(localaddr, remoteaddr, data_size_limit=33554432, map=None, enable_SMTPUTF8=False, decode_data=False)

新たな SMTPServer オブジェクトを作成し、それをローカルのアドレス localaddr に関連づけ (bind) ます。 このオブジェクトは remoteaddr を上流の SMTP リレー先とします。 localaddr と remoteaddr のどちらも (host, port) タプルである必要があります。 このクラスは asyncore.dispatcher を継承しており、インスタンス化時に自身を asyncore のイベントループに登録します。

data_size_limit には DATA コマンドが受け取る最大のバイト数を指定します。 None や 0 の場合上限はありません。

map is the socket map to use for connections (an initially empty dictionary is a suitable value). If not specified the asyncore global socket map is used.

enable_SMTPUTF8 determines whether the SMTPUTF8 extension (as defined in RFC 6531) should be enabled. The default is False. When True, SMTPUTF8 is accepted as a parameter to the MAIL command and when present is passed to process_message() in the kwargs['mail_options'] list. decode_data and enable_SMTPUTF8 cannot be set to True at the same time.

decode_data specifies whether the data portion of the SMTP transaction should be decoded using UTF-8. When decode_data is False (the default), the server advertises the 8BITMIME extension ( RFC 6152), accepts the BODY=8BITMIME parameter to the MAIL command, and when present passes it to process_message() in the kwargs['mail_options'] list. decode_data and enable_SMTPUTF8 cannot be set to True at the same time.

process_message(peer, mailfrom, rcpttos, data, **kwargs)

Raise a NotImplementedError exception. Override this in subclasses to do something useful with this message. Whatever was passed in the constructor as remoteaddr will be available as the _remoteaddr attribute. peer is the remote host's address, mailfrom is the envelope originator, rcpttos are the envelope recipients and data is a string containing the contents of the e-mail (which should be in RFC 5321 format).

decode_data コンストラクタ引数が True の場合、 data 引数はユニコード文字列です。False の場合は bytes オブジェクトです。

kwargs is a dictionary containing additional information. It is empty if decode_data=True was given as an init argument, otherwise it contains the following keys:

mail_options:
MAIL コマンドが受け取る全ての引数のリストです (要素は大文字の文字列です; 例えば ['BODY=8BITMIME', 'SMTPUTF8'])。
rcpt_options:
RCPT コマンドのものである点以外は mail_options と同じです。今のところ RCPT TO オプションはサポートされていないため、これは常に空のリストです。

将来の仕様改善によって kwargs 辞書にキーが追加される可能性があるため、 process_message の実装で追加のキーワード引数を受け取るには **kwargs シグニチャを使うべきです。

通常の 250 Ok 応答には None を返します。そうでない場合求められる応答を RFC 5321 形式の文字列で返します。

channel_class

これを派生クラスでオーバーライドすることで、SMTP クライアントを管理するのにカスタムの SMTPChannel を使います。

バージョン 3.4 で追加: map コンストラクタ引数。

バージョン 3.5 で変更: localaddr および remoteaddr は IPv6 アドレスを持てるようになりました。

バージョン 3.5 で追加: The decode_data and enable_SMTPUTF8 constructor parameters, and the kwargs parameter to process_message() when decode_data is False.

バージョン 3.6 で変更: decode_data is now False by default.

DebuggingServer オブジェクト

class smtpd.DebuggingServer(localaddr, remoteaddr)

新たなデバッグ用サーバを生成します。引数は SMTPServer と同じです。メッセージが届いても無視し、標準出力に出力します。

PureProxy オブジェクト

class smtpd.PureProxy(localaddr, remoteaddr)

新たな単純プロキシ (pure proxy) サーバを生成します。引数は SMTPServer と同じです。全てのメッセージを remoteaddr にリレーします。このオブジェクトを動作させるとオープンリレーを作成してしまう可能性が多分にあります。注意してください。

MailmanProxy Objects

class smtpd.MailmanProxy(localaddr, remoteaddr)

新たな単純プロキシサーバを生成します。引数は SMTPServer と同じです。全てのメッセージを remoteaddr にリレーしますが、 ローカルの mailman の設定に remoteaddr がある場合には mailman を使って処理します。このオブジェクトを動作させるとオープンリレーを 作成してしまう可能性が多分にあります。注意してください。

SMTPChannel オブジェクト

class smtpd.SMTPChannel(server, conn, addr, data_size_limit=33554432, map=None, enable_SMTPUTF8=False, decode_data=False)

サーバと一つの SMTP クライアント間の通信を管理する SMTPChannel オブジェクトを新たに生成します。

conn and addr are as per the instance variables described below.

data_size_limit には DATA コマンドが受け取る最大のバイト数を指定します。 None や 0 の場合上限はありません。

enable_SMTPUTF8 determines whether the SMTPUTF8 extension (as defined in RFC 6531) should be enabled. The default is False. decode_data and enable_SMTPUTF8 cannot be set to True at the same time.

A dictionary can be specified in map to avoid using a global socket map.

decode_data specifies whether the data portion of the SMTP transaction should be decoded using UTF-8. The default is False. decode_data and enable_SMTPUTF8 cannot be set to True at the same time.

To use a custom SMTPChannel implementation you need to override the SMTPServer.channel_class of your SMTPServer.

バージョン 3.5 で変更: The decode_data and enable_SMTPUTF8 parameters were added.

バージョン 3.6 で変更: decode_data is now False by default.

SMTPChannel は以下のインスタンス変数を持っています:

smtp_server

このチャンネルを生成した SMTPServer を保持します。

conn

クライアントに接続しているソケットオブジェクトを保持します。

addr

Holds the address of the client, the second value returned by socket.accept

received_lines

Holds a list of the line strings (decoded using UTF-8) received from the client. The lines have their "\r\n" line ending translated to "\n".

smtp_state

Holds the current state of the channel. This will be either COMMAND initially and then DATA after the client sends a "DATA" line.

seen_greeting

Holds a string containing the greeting sent by the client in its "HELO".

mailfrom

Holds a string containing the address identified in the "MAIL FROM:" line from the client.

rcpttos

Holds a list of strings containing the addresses identified in the "RCPT TO:" lines from the client.

received_data

Holds a string containing all of the data sent by the client during the DATA state, up to but not including the terminating "\r\n.\r\n".

fqdn

Holds the fully-qualified domain name of the server as returned by socket.getfqdn().

peer

Holds the name of the client peer as returned by conn.getpeername() where conn is conn.

The SMTPChannel operates by invoking methods named smtp_<command> upon reception of a command line from the client. Built into the base SMTPChannel class are methods for handling the following commands (and responding to them appropriately):

コマンド | 行う動作
HELO | クライアントのグリーティングを受け取り seen_greeting に格納します。サーバを基本コマンドモードに設定します。
EHLO | クライアントのグリーティングを受け取り seen_greeting に格納します。サーバを拡張コマンドモードに設定します。
NOOP | 何もしません。
QUIT | 接続をきれいに閉じます。
MAIL | "MAIL FROM:" シンタックスを受け取り提供されたアドレスを mailfrom として保存します。拡張コマンドモードでは RFC 1870 SIZE 属性を受け取り data_size_limit の値に基づき適切に応答します。
RCPT | "RCPT TO:" シンタックスを受け取り提供されたアドレスを rcpttos リストに格納します。
RSET | mailfrom, rcpttos, received_data をリセットしますが、グリーティングはリセットしません。
DATA | 内部状態を DATA に設定し、クライアントからの残りの行を終端子 "\r\n.\r\n" を受け取るまで received_data に格納します。
HELP | 最小の情報をコマンドシンタックスで返します。
VRFY | コード 252 (サーバはアドレスが有効か分かりません) を返します。
EXPN | コマンドが実装されていないことを報告します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


telnetlib --- Telnet クライアント

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

telnetlib --- Telnet クライアント

ソースコード: Lib/telnetlib.py

telnetlib モジュールでは、Telnet プロトコルを実装している Telnet クラスを提供します。Telnet プロトコルについての詳細は RFC 854 を参照してください。加えて、このモジュールでは 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 (サブネゴシエーション開始) です。

class telnetlib.Telnet(host=None, port=0[, timeout])

Telnet は Telnet サーバへの接続を表現します。デフォルトでは、 Telnet クラスのインスタンスは最初はサーバに接続していません。接続を確立するには open() を使わなければなりません。別の方法として、コンストラクタにホスト名とオプションのポート番号を渡すこともできます。この場合はコンストラクタの呼び出しが返る以前にサーバへの接続が確立されます。オプション引数の timeout が渡された場合、コネクション接続時のタイムアウト時間を秒数で指定します (指定されなかった場合は、グローバルのデフォルトタイムアウト設定が利用されます)。

すでに接続の開かれているンスタンスを再度開いてはいけません。

このクラスは多くの read_*() メソッドを持っています。これらのメソッドのいくつかは、接続の終端を示す文字を読み込んだ場合に EOFError を送出するので注意してください。例外を送出するのは、これらの関数が終端に到達しなくても空の文字列を返す可能性があるからです。詳しくは下記の個々の説明を参照してください。

A Telnet object is a context manager and can be used in a with statement. When the with block ends, the close() method is called:

>>> from telnetlib import Telnet
>>> with Telnet('localhost', 23) as tn:
...     tn.interact()
...

バージョン 3.6 で変更: Context manager support added

参考

RFC 854 - 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 が渡された場合、コネクション接続時などのブロックする操作のタイムアウト時間を秒数で指定します (指定されなかった場合は、グローバルのデフォルトタイムアウト設定が利用されます)。

すでに接続しているインスタンスで再接続を試みてはいけません。

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 が送出されるかもしれません。

バージョン 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'))

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


uuid --- UUID objects according to RFC 4122

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

uuid --- UUID objects according to RFC 4122

ソースコード: Lib/uuid.py

このモジュールでは immutable (変更不能) な UUID オブジェクト (UUID クラス) と RFC 4122 の定めるバージョン 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

バージョン 3.7 で追加.

safe

The UUID was generated by the platform in a multiprocessing-safe way.

unsafe

The UUID was not generated in a multiprocessing-safe way.

unknown

The platform does not provide information on whether the UUID was generated safely or not.

class uuid.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)

Create a UUID from either a string of 32 hexadecimal digits, a string of 16 bytes in big-endian order as the bytes argument, a string of 16 bytes in little-endian order as the bytes_le argument, a tuple of six integers (32-bit time_low, 16-bit time_mid, 16-bit time_hi_version, 8-bit clock_seq_hi_variant, 8-bit clock_seq_low, 48-bit node) as the fields argument, or a single 128-bit integer as the int argument. When a string of hex digits is given, curly braces, hyphens, and a URN prefix are all optional. For example, these expressions all yield the same UUID:

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)

Exactly one of hex, bytes, bytes_le, fields, or int must be given. The version argument is optional; if given, the resulting UUID will have its variant and version number set according to RFC 4122, overriding bits in the given hex, bytes, 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 つの派生した属性としても取得可能です:

フィールド | 意味
time_low | UUID の最初の 32 ビット
time_mid | UUID の次の 16 ビット
time_hi_version | UUID の次の 16 ビット
clock_seq_hi_variant | UUID の次の 8 ビット
clock_seq_low | UUID の次の 8 ビット
node | UUID の最後の 48 ビット
time | 60 ビットのタイムスタンプ
clock_seq | 14 ビットのシーケンス番号
UUID.hex

32 文字の 16 進数文字列での UUID。

UUID.int

128 ビット整数での UUID。

UUID.urn

The UUID as a URN as specified in RFC 4122.

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

An enumeration of SafeUUID which indicates whether the platform generated the UUID in a multiprocessing-safe way.

バージョン 3.7 で追加.

The uuid モジュールには以下の関数があります:

uuid.getnode()

Get the hardware address as a 48-bit positive integer. The first time this runs, it may launch a separate program, which could be quite slow. If all attempts to obtain the hardware address fail, we choose a random 48-bit number with the multicast bit (least significant bit of the first octet) set to 1 as recommended in RFC 4122. "Hardware address" means the MAC address of a network interface. On a machine with multiple network interfaces, universally administered MAC addresses (i.e. where the second least significant bit of the first octet is unset) will be preferred over locally administered MAC addresses, but with no other ordering guarantees.

バージョン 3.7 で変更: Universally administered MAC addresses are preferred over locally administered MAC addresses, since the former are guaranteed to be globally unique, while the latter are not.

uuid.uuid1(node=None, clock_seq=None)

UUID をホスト ID、シーケンス番号、現在時刻から生成します。 node が与えられなければ、 getnode() がハードウェアアドレス取得のために使われます。 clock_seq が与えられると、これはシーケンス番号として使われます; さもなくば 14 ビットのランダムなシーケンス番号が選ばれます。

uuid.uuid3(namespace, name)

UUID を名前空間識別子 (UUID) と名前 (文字列) の MD5 ハッシュから生成します。

uuid.uuid4()

ランダムな UUID を生成します。

uuid.uuid5(namespace, name)

名前空間識別子(これは UUID です)と名前(文字列です)の SHA-1 ハッシュからUUIDを生成します。

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 モジュールは以下の定数を variant 属性が取りうる値として定義しています:

uuid.RESERVED_NCS

NCS 互換性のために予約されています。

uuid.RFC_4122

RFC 4122 で与えられた UUID レイアウトを指定します。

uuid.RESERVED_MICROSOFT

Microsoft の互換性のために予約されています。

uuid.RESERVED_FUTURE

将来のために予約されています。

参考

RFC 4122 - Universally Unique IDentifier (UUID) の URN 名前空間
この仕様は UUID のための Uniform Resource Name 名前空間、UUID の内部フォーマットと UUID の生成方法を定義しています。

使用例

典型的な 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')

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


socketserver --- ネットワークサーバのフレームワーク

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

socketserver --- ネットワークサーバのフレームワーク

ソースコード: Lib/socketserver.py

socketserver モジュールはネットワークサーバを実装するタスクを単純化します。

基本的な具象サーバクラスが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) を使えば、非同期的な動作をサポートできます。

Creating a server requires several steps. First, you must create a request handler class by subclassing the BaseRequestHandler class and overriding its handle() method; this method will process incoming requests. Second, you must instantiate one of the server classes, passing it the server's address and the request handler class. It is recommended to use the server in a with statement. Then call the handle_request() or serve_forever() method of the server object to process one or many requests. Finally, call server_close() to close the socket (unless you used a with statement).

ThreadingMixIn から継承してスレッドを利用した接続を行う場合、突発的な通信切断時の処理を明示的に指定する必要があります。 ThreadingMixIn クラスには daemon_threads 属性があり、サーバがスレッドの終了を待ち合わせるかどうかを指定する事ができます。スレッドが独自の処理を行う場合は、このフラグを明示的に指定します。デフォルトは False で、Pythonは ThreadingMixIn クラスが起動した全てのスレッドが終了するまで実行し続けます。

サーバクラス群は使用するネットワークプロトコルに関わらず、同じ外部メソッドおよび属性を持ちます。

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

継承図にある五つのクラスのうち四つは四種類の同期サーバを表わしています:

+------------+
| BaseServer |
+------------+
      |
      v
+-----------+        +------------------+
| TCPServer |------->| UnixStreamServer |
+-----------+        +------------------+
      |
      v
+-----------+        +--------------------+
| UDPServer |------->| UnixDatagramServer |
+-----------+        +--------------------+

UnixDatagramServer は UDPServer から派生していて、 UnixStreamServer からではないことに注意してください --- IP と Unix ストリームサーバの唯一の違いはアドレスファミリーでそれは両方の Unix サーバクラスで単純に繰り返されています。

class socketserver.ForkingMixIn
class socketserver.ThreadingMixIn

Forking and threading versions of each type of server can be created using these mix-in classes. For instance, ThreadingUDPServer is created as follows:

class ThreadingUDPServer(ThreadingMixIn, UDPServer):
    pass

The mix-in class comes first, since it overrides a method defined in UDPServer. Setting the various attributes also changes the behavior of the underlying server mechanism.

ForkingMixIn and the Forking classes mentioned below are only available on POSIX platforms that support fork().

socketserver.ForkingMixIn.server_close() waits until all child processes complete, except if socketserver.ForkingMixIn.block_on_close attribute is false.

socketserver.ThreadingMixIn.server_close() waits until all non-daemon threads complete, except if socketserver.ThreadingMixIn.block_on_close attribute is false. Use daemonic threads by setting ThreadingMixIn.daemon_threads to True to not wait until threads complete.

バージョン 3.7 で変更: socketserver.ForkingMixIn.server_close() and socketserver.ThreadingMixIn.server_close() now waits until all child processes and non-daemonic threads complete. Add a new socketserver.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

These classes are pre-defined using the mix-in classes.

To implement a service, you must derive a class from BaseRequestHandler and redefine its handle() method. You can then run various versions of the service by combining one of the server classes with your request handler class. The request handler class must be different for datagram or stream services. This can be hidden by using the handler subclasses StreamRequestHandler or DatagramRequestHandler.

もちろん、まだ頭を使わなければなりません! たとえば、サービスがリクエストによっては書き換えられるようなメモリ上の状態を使うならば、フォークするサーバを使うのは馬鹿げています。というのも子プロセスでの書き換えは親プロセスで保存されている初期状態にも親プロセスから分配される各子プロセスの状態にも届かないからです。この場合、スレッド実行するサーバを使うことはできますが、共有データの一貫性を保つためにロックを使わなければならなくなるでしょう。

一方、全てのデータが外部に(たとえばファイルシステムに)保存される HTTP サーバを作っているのだとすると、同期クラスではどうしても一つの要求が処理されている間サービスが「耳の聞こえない」状態を呈することになります --- この状態はもしクライアントが要求した全てのデータをゆっくり受け取るととても長い時間続きかねません。こういう場合にはサーバをスレッド実行したりフォークすることが適切です。

In some cases, it may be appropriate to process part of a request synchronously, but to finish processing in a forked child depending on the request data. This can be implemented by using a synchronous server and doing an explicit fork in the request handler class handle() method.

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). See asyncore for another way to manage this.

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()

Return an integer file descriptor for the socket on which the server is listening. This function is most commonly passed to selectors, to allow monitoring multiple servers in the same process.

handle_request()

Process a single request. This function calls the following methods in order: get_request(), verify_request(), and process_request(). If the user-provided handle() method of the handler class raises an exception, the server's handle_error() method will be called. If no request is received within timeout seconds, handle_timeout() will be called and handle_request() will return.

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.

バージョン 3.3 で追加.

shutdown()

serve_forever() ループに停止するように指示し、停止されるまで待ちます。

server_close()

サーバをクリーンアップします。上書き出来ます。

address_family

サーバのソケットが属しているプロトコルファミリです。一般的な値は socket.AF_INET および socket.AF_UNIX です。

RequestHandlerClass

ユーザが提供する要求処理クラスです; 要求ごとにこのクラスのインスタンスが生成されます。

server_address

The address on which the server is listening. The format of addresses varies depending on the protocol family; see the documentation for the socket module for details. For Internet protocols, this is a tuple containing a string giving the address, and an integer port number: ('127.0.0.1', 80), for example.

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)

Actually processes the request by instantiating RequestHandlerClass and calling its handle() method.

get_request()

ソケットから要求を受理して、クライアントとの通信に使われる 新しい ソケットオブジェクト、およびクライアントのアドレスからなる、2 要素のタプルを返します。

handle_error(request, client_address)

This function is called if the handle() method of a RequestHandlerClass instance raises an exception. The default action is to print the traceback to standard error and continue handling further requests.

バージョン 3.6 で変更: Now only called for exceptions derived from the 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 で変更: Support for the context manager protocol was added. Exiting the context manager is equivalent to calling 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()

この関数では、クライアントからの要求を実現するために必要な全ての作業を行わなければなりません。デフォルト実装では何もしません。この作業の上で、いくつかのインスタンス属性を利用することができます; クライアントからの要求は self.request です; クライアントのアドレスは self.client_address です; そしてサーバごとの情報にアクセスする場合には、サーバインスタンスを self.server で取得できます。

The type of self.request is different for datagram or stream services. For stream services, self.request is a socket object; for datagram services, self.request is a pair of string and socket.

finish()

handle() メソッドより後に呼び出され、何らかの必要なクリーンアップ処理を行います。標準の実装では何も行いません。 setup() メソッドが例外を送出した場合、このメソッドは呼び出されません。

class socketserver.StreamRequestHandler
class socketserver.DatagramRequestHandler

These BaseRequestHandler subclasses override the setup() and finish() methods, and provide self.rfile and self.wfile attributes. The self.rfile and self.wfile attributes can be read or written, respectively, to get the request data or return data to the client.

The rfile attributes of both classes support the io.BufferedIOBase readable interface, and DatagramRequestHandler.wfile supports the io.BufferedIOBase writable interface.

バージョン 3.6 で変更: StreamRequestHandler.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("{} wrote:".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())

先ほどとの違いは、readline() の呼び出しが、改行を受け取るまで recv() を複数回呼び出すことです。1回の recv() の呼び出しは、クライアントから1回の sendall() 呼び出しで送信された分しか受け取りません。

クライアントサイドの例:

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

この例の出力は次のようになります:

Server:

$ python TCPServer.py
127.0.0.1 wrote:
b'hello world with TCP'
127.0.0.1 wrote:
b'python is nice'

Client:

$ 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

The ForkingMixIn class is used in the same way, except that the server will spawn a new process for each request. Available only on POSIX platforms that support fork().

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


http.server --- HTTP サーバ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

http.server --- HTTP サーバ

ソースコード: Lib/http/server.py

このモジュールは HTTP (web) サーバを実装するためのクラスを提供しています。

警告

http.server is not recommended for production. It only implements basic security checks.

クラス 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.

バージョン 3.7 で追加.

The HTTPServer and ThreadingHTTPServer must be given a RequestHandlerClass on instantiation, of which this module provides three different variants:

class http.server.BaseHTTPRequestHandler(request, client_address, server)

このクラスはサーバに到着したリクエストを処理します。 このメソッド自体では、実際のリクエストに応答することはできません; (GET や POST のような) 各リクエストメソッドを処理するためにはサブクラス化しなければなりません。 BaseHTTPRequestHandler では、サブクラスで使うためのクラスやインスタンス変数、メソッド群を数多く提供しています。

このハンドラはリクエストを解釈し、次いでリクエスト形式ごとに固有のメソッドを呼び出します。メソッド名はリクエストの名称から構成されます。例えば、リクエストメソッド SPAM に対しては、 do_SPAM() メソッドが引数なしで呼び出されます。リクエストに関連する情報は全て、ハンドラのインスタンス変数に記憶されています。サブクラスでは __init__() メソッドを上書きしたり拡張したりする必要はありません。

BaseHTTPRequestHandler は以下のインスタンス変数を持っています:

client_address

HTTP クライアントのアドレスを参照している、(host, port) の形式をとるタプルが入っています。

server

server インスタンスが入っています。

close_connection

handle_one_request() が返る前に設定すべき真偽値で、別のリクエストが期待されているかどうか、もしくはコネクションを切断すべきかどうかを指し示しています。

requestline

HTTP リクエスト行の文字列表現を保持しています。 末尾の CRLF は除去されています。 この属性は handle_one_request() によって設定されるべきです。 妥当なリクエスト行が1行も処理されなかった場合は、空文字列に設定されるべきです。

command

HTTP 命令 (リクエスト形式) が入っています。例えば 'GET' です。

path

リクエストされたパスが入っています。

request_version

リクエストのバージョン文字列が入っています。例えば 'HTTP/1.0' です。

headers

MessageClass クラス変数で指定されたクラスのインスタンスを保持しています。 このインスタンスは HTTP リクエストのヘッダを解釈し、管理しています。 http.client の parse_headers() 関数がヘッダを解釈するために使われ、 HTTP リクエストが妥当な RFC 2822 スタイルのヘッダを提供することを要求します。

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

この値には応答に使われる HTTP プロトコルのバージョンを指定します。 'HTTP/1.1' に設定されると、サーバは持続的 HTTP 接続を許可します; しかしその場合、サーバは全てのクライアントに対する応答に、正確な値を持つ Content-Length ヘッダを (send_header() を使って) 含め なければなりません 。以前のバージョンとの互換性を保つため、標準の設定値は '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()

handle_one_request() を一度だけ (持続的接続が有効になっている場合には複数回) 呼び出して、HTTPリクエストを処理します。このメソッドを上書きする必要はまったくありません; そうする代わりに適切な do_*() を実装してください。

handle_one_request()

このメソッドはリクエストを解釈し、適切な do_*() メソッドに転送します。このメソッドを上書きする必要はまったくありません。

handle_expect_100()

HTTP/1.1 準拠のサーバが Expect: 100-continue リクエストヘッダを受け取ったとき、 100 Continue を返し、その後に 200 OK がきます。 このメソッドは、サーバがクライアントに継続を要求しない場合、エラーを送出するようにオーバーライドできます。 例えば、サーバはレスポンスヘッダとして 417 Expectation Failed を送る選択をし、 return False とできます。

バージョン 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.

バージョン 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()

最終的にヘッダを出力ストリームに送り、内部ヘッダバッファをフラッシュします。

バージョン 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)

Returns the date and time given by timestamp (which must be None or in the format returned by time.time()), formatted for a message header. If timestamp is omitted, it uses the current date and time.

出力は '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)

このクラスは、現在のディレクトリ以下にあるファイルを、HTTP リクエストにおけるディレクトリ構造に直接対応付けて提供します。

A lot of the work, such as parsing the request, is done by the base class BaseHTTPRequestHandler. This class implements the do_GET() and do_HEAD() functions.

SimpleHTTPRequestHandler では以下のメンバ変数を定義しています:

server_version

この値は "SimpleHTTP/" + __version__ になります。__version__ はこのモジュールで定義されている値です。

extensions_map

拡張子を MIME 型指定子に対応付ける辞書です。標準の型指定は空文字列で表され、この値は application/octet-stream と見なされます。対応付けは大小文字の区別をするので、小文字のキーのみを入れるべきです。

directory

If not specified, the directory to serve is the current working directory.

SimpleHTTPRequestHandler では以下のメソッドを定義しています:

do_HEAD()

このメソッドは 'HEAD' 型のリクエスト処理を実行します: すなわち、 GET リクエストの時に送信されるものと同じヘッダを送信します。送信される可能性のあるヘッダについての完全な説明は do_GET() メソッドを参照してください。

do_GET()

リクエストを現在の作業ディレクトリからの相対的なパスとして解釈することで、リクエストをローカルシステム上のファイルと対応付けます。

If the request was mapped to a directory, the directory is checked for a file named index.html or index.htm (in that order). If found, the file's contents are returned; otherwise a directory listing is generated by calling the list_directory() method. This method uses os.listdir() to scan the directory, and returns a 404 error response if the listdir() fails.

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 invocation in the http.server module.

バージョン 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()

http.server can also be invoked directly using the -m switch of the interpreter with a port number argument. Similar to the previous example, this serves files relative to the current directory:

python -m http.server 8000

By default, server binds itself to all interfaces. The option -b/--bind specifies a specific address to which it should bind. For example, the following command causes the server to bind to localhost only:

python -m http.server 8000 --bind 127.0.0.1

バージョン 3.4 で追加: --bind 引数が導入されました。

By default, 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 で追加: --directory specify alternate directory

class http.server.CGIHTTPRequestHandler(request, client_address, server)

This class is used to serve either files or output of CGI scripts from the current directory and below. Note that mapping HTTP hierarchic structure to local directory structure is exactly as in SimpleHTTPRequestHandler.

注釈

CGIHTTPRequestHandler クラスで実行される CGI スクリプトは HTTP コード 200 (スクリプトの出力が後に続く) を実行に先立って出力される (これがステータスコードになります) ため、リダイレクト(コード302) を行なうことができません。

The class will however, run the CGI script, instead of serving it as a file, if it guesses it to be a CGI script. Only directory-based CGI are used --- the other common server configuration is to treat special extensions as denoting CGI scripts.

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" になります。

Note that CGI scripts will be run with UID of user nobody, for security reasons. Problems with the CGI script will be translated to error 403.

CGIHTTPRequestHandler can be enabled in the command line by passing the --cgi option:

python -m http.server --cgi 8000

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


http.cookies --- HTTPの状態管理

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

http.cookies --- HTTPの状態管理

ソースコード: Lib/http/cookies.py

http.cookies モジュールはHTTPの状態管理機能であるcookieの概念を抽象化、定義しているクラスです。単純な文字列のみで構成されるcookieのほか、シリアル化可能なあらゆるデータ型でクッキーの値を保持するための機能も備えています。

このモジュールは元々 RFC 2109 と RFC 2068 に定義されている構文解析の規則を厳密に守っていました。しかし、MSIE 3.0x がこれらの RFC で定義された文字の規則に従っていないことが判明し、また、現代の多くのブラウザとサーバも Cookie の処理に緩い解析をしており、結局、やや厳密さを欠く構文解析規則にせざるを得ませんでした。

文字集合 string.ascii_letters 、 string.digits 、 !#$%&'*+-.^_`|~: を、このモジュールは Cookie 名 (key) として有効と認めています。

バージョン 3.3 で変更: ':' が有効な Cookie 名の文字として認められました。

注釈

不正な cookie に遭遇した場合、 CookieError 例外を送出します。そのため、ブラウザから持ってきた cookie データをパースするときには常に不正なデータに備え CookieError 例外を捕捉してください。

exception http.cookies.CookieError

属性や Set-Cookie ヘッダが正しくないなど、 RFC 2109 に合致していないときに発生する例外です。

class http.cookies.BaseCookie([input])

このクラスはキーが文字列、値が Morsel インスタンスで構成される辞書風オブジェクトです。値に対するキーを設定するときは、値がキーと値を含む Morsel に変換されることに注意してください。

input が与えられたときは、そのまま load() メソッドへ渡されます。

class http.cookies.SimpleCookie([input])

このクラスは BaseCookie の派生クラスで、 value_decode() は与えられた値の正当性を確認するように、 value_encode() は str() で文字列化するようにそれぞれオーバライドします。

参考

モジュール http.cookiejar
Web クライアント 向けの HTTP クッキー処理です。 http.cookiejar と http.cookies は互いに独立しています。
RFC 2109 - HTTP State Management Mechanism
このモジュールが実装しているHTTPの状態管理に関する規格です。

Cookieオブジェクト

BaseCookie.value_decode(val)

文字列表現を値にデコードして返します。戻り値の型はどのようなものでも許されます。このメソッドは BaseCookie において何も実行せず、オーバーライドされるためにだけ存在します。

BaseCookie.value_encode(val)

エンコードした値を返します。元の値はどのような型でもかまいませんが、戻り値は必ず文字列となります。このメソッドは BaseCookie において何も実行せず、オーバーライドされるためにだけ存在します。

通常 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 の属性をキーと値で保持するabstractクラスです。

Morselは辞書風のオブジェクトで、キーは次のような RFC 2109 準拠の定数となっています。

  • expires
  • path
  • comment
  • domain
  • max-age
  • secure
  • version
  • httponly

httponly 属性は、 cookie が HTTP リクエストでのみ送信されて、 JavaScript からのはアクセスできない事を示します。これはいくつかのクロスサイトスクリプティングの脅威を和らげることを意図しています。

キーの大小文字は区別されません。そのデフォルト値は '' です。

バージョン 3.5 で変更: __eq__() は key 及び value を考慮するようになりました。

バージョン 3.7 で変更: Attributes key, value and coded_value are read-only. Use set() for setting them.

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 属性でない場合エラーを送出します。

バージョン 3.5 で変更: 不正なキーではエラーが送出されます。

Morsel.copy(value)

Morsel オブジェクトの浅いコピーを返します。

バージョン 3.5 で変更: 辞書ではなく Morsel オブジェクトを返します。

Morsel.setdefault(key, value=None)

キーが有効な RFC 2109 属性でない場合エラーを送出します。そうでない場合は 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 --- HTTP クライアント用の Cookie 処理

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

http.cookiejar --- HTTP クライアント用の Cookie 処理

ソースコード: Lib/http/cookiejar.py

http.cookiejar モジュールは HTTP クッキーの自動処理をおこなうクラスを定義します。これは小さなデータの断片 -- クッキー -- を要求する web サイトにアクセスする際に有用です。クッキーとは web サーバの HTTP レスポンスによってクライアントのマシンに設定され、のちの HTTP リクエストをおこなうさいにサーバに返されるものです。

標準的な Netscape クッキープロトコルおよび RFC 2965 で定義されているプロトコルの両方を処理できます。RFC 2965 の処理はデフォルトではオフになっています。 RFC 2109 のクッキーは 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 was made a subclass of OSError instead of IOError.

以下のクラスが提供されています:

class http.cookiejar.CookieJar(policy=None)

policy は CookiePolicy インターフェイスを実装するオブジェクトです。

CookieJar クラスには HTTP クッキーを保管します。これは HTTP リクエストに応じてクッキーを取り出し、それを HTTP レスポンスの中で返します。必要に応じて、 CookieJar インスタンスは保管されているクッキーを自動的に破棄します。このサブクラスは、クッキーをファイルやデータベースに格納したり取り出したりする操作をおこなう役割を負っています。

class http.cookiejar.FileCookieJar(filename, delayload=None, policy=None)

policy は CookiePolicy インターフェイスを実装するオブジェクトです。これ以外の引数については、該当する属性の説明を参照してください。

FileCookieJar はディスク上のファイルからのクッキーの読み込み、もしくは書き込みをサポートします。実際には、 load() または revert() のどちらかのメソッドが呼ばれるまでクッキーは指定されたファイルからはロード されません 。このクラスのサブクラスは FileCookieJar のサブクラスと web ブラウザとの連携 節で説明します。

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)

コンストラクタはキーワード引数しか取りません。 blocked_domains はドメイン名からなるシーケンスで、ここからは決してクッキーを受けとらないし、このドメインにクッキーを返すこともありません。 allowed_domains が None でない場合、これはこのドメインのみからクッキーを受けとり、返すという指定になります。これ以外の引数については CookiePolicy および DefaultCookiePolicy オブジェクトの説明をごらんください。

DefaultCookiePolicy implements the standard accept / reject rules for Netscape and RFC 2965 cookies. By default, RFC 2109 cookies (ie. cookies received in a Set-Cookie header with a version cookie-attribute of 1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling is turned off or rfc2109_as_netscape is True, RFC 2109 cookies are 'downgraded' by the CookieJar instance to Netscape cookies, by setting the version attribute of the Cookie instance to 0. DefaultCookiePolicy also provides some parameters to allow some fine-tuning of policy.

class http.cookiejar.Cookie

This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not expected that users of http.cookiejar construct their own Cookie instances. Instead, if necessary, call make_cookies() on a CookieJar instance.

参考

urllib.request モジュール
クッキーの自動処理をおこない URL を開くモジュールです。
http.cookies モジュール
HTTP のクッキークラスで、基本的にはサーバサイドのコードで有用です。 http.cookiejar および http.cookies モジュールは互いに依存してはいません。
https://curl.haxx.se/rfc/cookie_spec.html
元祖 Netscape のクッキープロトコルの仕様です。今でもこれが主流のプロトコルですが、現在のメジャーなブラウザ (と http.cookiejar) が実装している「Netscape クッキープロトコル」は cookie_spec.html で述べられているものとおおまかにしか似ていません。
RFC 2109 - HTTP State Management Mechanism
Obsoleted by RFC 2965. Uses Set-Cookie with version=1.
RFC 2965 - HTTP State Management Mechanism
Netscape プロトコルのバグを修正したものです。 Set-Cookie のかわりに Set-Cookie2 を使いますが、普及してはいません。
http://kristol.org/cookie/errata.html
Unfinished errata to RFC 2965.

RFC 2964 - Use of HTTP State Management

CookieJar および FileCookieJar オブジェクト

CookieJar オブジェクトは保管されている Cookie オブジェクトをひとつずつ取り出すための、イテレータ(iterator)・プロトコルをサポートしています。

CookieJar は以下のようなメソッドを持っています:

CookieJar.add_cookie_header(request)

request に正しい Cookie ヘッダを追加します。

ポリシーが許すようであれば (CookieJar の CookiePolicy インスタンスにある属性のうち、 rfc2965 および hide_cookie2 がそれぞれ真と偽であるような場合)、必要に応じて Cookie2 ヘッダも追加されます。

The request object (usually a urllib.request..Request instance) must support the methods get_full_url(), get_host(), get_type(), unverifiable(), has_header(), get_header(), header_items(), add_unredirected_header() and origin_req_host attribute as documented by urllib.request.

バージョン 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() メソッドの承認におうじて) クッキーを保管します。

The response object (usually the result of a call to urllib.request.urlopen(), or similar) should support an info() method, which returns an email.message.Message instance.

The request object (usually a urllib.request.Request instance) must support the methods get_full_url(), get_host(), unverifiable(), and origin_req_host attribute, as documented by urllib.request. The request is used to set default values for cookie-attributes as well as for checking that the cookie is allowed to be set.

バージョン 3.3 で変更: request object needs 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() と同じです。

The named file must be in the format understood by the class, or LoadError will be raised. Also, OSError may be raised, for example if the file does not exist.

バージョン 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, delayload=None, policy=None)

Mozilla の cookies.txt ファイル形式 (この形式はまた Lynx と Netscape ブラウザによっても使われています) でディスクにクッキーを読み書きするための FileCookieJar です。

注釈

This loses information about RFC 2965 cookies, and also about newer or non-standard cookie-attributes such as port.

警告

もしクッキーの損失や欠損が望ましくない場合は、クッキーを保存する前にバックアップを取っておくようにしてください (ファイルへの読み込み / 保存をくり返すと微妙な変化が生じる場合があります)。

また、Mozilla の起動中にクッキーを保存すると、Mozilla によって内容が破壊されてしまうことにも注意してください。

class http.cookiejar.LWPCookieJar(filename, delayload=None, policy=None)

libwww-perl のライブラリである Set-Cookie3 ファイル形式でディスクにクッキーを読み書きするための FileCookieJar です。これはクッキーを人間に可読な形式で保存するのに向いています。

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

Implement RFC 2965 protocol.

CookiePolicy.hide_cookie2

Don't add Cookie2 header to requests (the presence of this header indicates to the server that we understand RFC 2965 cookies).

もっとも有用な方法は、 DefaultCookiePolicy をサブクラス化した CookiePolicy クラスを定義して、いくつか (あるいはすべて) のメソッドをオーバーライドすることでしょう。 CookiePolicy 自体はどのようなクッキーも受け入れて設定を許可する「ポリシー無し」ポリシーとして使うこともできます (これが役に立つことはあまりありませんが)。

DefaultCookiePolicy オブジェクト

クッキーを受けつけ、またそれを返す際の標準的なルールを実装します。

Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is switched off by default.

自分のポリシーを提供するいちばん簡単な方法は、このクラスを継承して、自分用の追加チェックの前にオーバーライドした元のメソッドを呼び出すことです:

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 がクッキーを授受しないブラックリストに載っているかどうかを返します。

DefaultCookiePolicy.allowed_domains()

None あるいは明示的に許可されているドメインを (タプルとして) 返します。

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

許可するドメイン、あるいは None を設定します。

DefaultCookiePolicy.is_not_allowed(domain)

domain がクッキーを授受するホワイトリストに載っているかどうかを返します。

DefaultCookiePolicy インスタンスは以下の属性をもっています。これらはすべてコンストラクタから同じ名前の引数をつかって初期化することができ、代入してもかまいません。

DefaultCookiePolicy.rfc2109_as_netscape

If true, request that the CookieJar instance downgrade RFC 2109 cookies (ie. cookies received in a Set-Cookie header with a version cookie-attribute of 1) to Netscape cookies by setting the version attribute of the Cookie instance to 0. The default value is None, in which case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned off. Therefore, RFC 2109 cookies are downgraded by default.

一般的な厳密性のスイッチ:

DefaultCookiePolicy.strict_domain

サイトに、国別コードとトップレベルドメインだけからなるドメイン名 (.co.uk, .gov.uk, .co.nz など) を設定させないようにします。これは完璧からはほど遠い実装であり、いつもうまくいくとは限りません!

RFC 2965 protocol strictness switches:

DefaultCookiePolicy.strict_rfc2965_unverifiable

Follow RFC 2965 rules on unverifiable transactions (usually, an unverifiable transaction is one resulting from a redirect or a request for an image hosted on another site). If this is false, cookies are never blocked on the basis of verifiability

Netscape プロトコルの厳密性に関するスイッチ:

DefaultCookiePolicy.strict_ns_unverifiable

Apply RFC 2965 rules on unverifiable transactions even to Netscape cookies.

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

When setting cookies, require a full RFC 2965 domain-match.

以下の属性は上記のフラグのうちもっともよく使われる組み合わせで、便宜をはかるために提供されています:

DefaultCookiePolicy.DomainLiberal

0 と同じです (つまり、上述の Netscape のドメイン厳密性フラグがすべてオフにされます)。

DefaultCookiePolicy.DomainStrict

DomainStrictNoDots|DomainStrictNonDomain と同じです。

Cookieオブジェクト

Cookie instances have Python attributes roughly corresponding to the standard cookie-attributes specified in the various cookie standards. The correspondence is not one-to-one, because there are complicated rules for assigning default values, because the max-age and expires cookie-attributes contain equivalent information, and because RFC 2109 cookies may be 'downgraded' by http.cookiejar from version 1 to version 0 (Netscape) cookies.

CookiePolicy メソッド内でのごくわずかな例外を除けば、これらの属性に代入する必要はないはずです。このクラスは内部の一貫性を保つようにはしていないため、代入するのは自分のやっていることを理解している場合のみにしてください。

Cookie.version

Integer or None. Netscape cookies have version 0. RFC 2965 and RFC 2109 cookies have a version cookie-attribute of 1. However, note that http.cookiejar may 'downgrade' RFC 2109 cookies to Netscape cookies, in which case version is 0.

Cookie.name

クッキーの名前 (文字列)。

Cookie.value

クッキーの値 (文字列)、あるいは None 。

Cookie.port

ポートあるいはポートの集合をあらわす文字列 (例: '80' または '80,8080')、あるいは None 。

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

True if this cookie was received as an RFC 2109 cookie (ie. the cookie arrived in a Set-Cookie header, and the value of the Version cookie-attribute in that header was 1). This attribute is provided because http.cookiejar may 'downgrade' RFC 2109 cookies to Netscape cookies, in which case version is 0.

Cookie.port_specified

サーバがポート、あるいはポートの集合を (Set-Cookie / Set-Cookie2 ヘッダ内で) 明示的に指定していれば True を返します。

Cookie.domain_specified

サーバにより明示的にドメインが指定されていれば True を返します。

Cookie.domain_initial_dot

サーバが明示的に指定したドメインがドット ('.') で始まっていれば True を返します。

クッキーは、オプションとして標準的でないクッキー属性を持つこともできます。これらは以下のメソッドでアクセスできます:

Cookie.has_nonstandard_attr(name)

そのクッキーが指定された名前のクッキー属性をもっている場合には真を返します。

Cookie.get_nonstandard_attr(name, default=None)

クッキーが指定された名前のクッキー属性をもっていれば、その値を返します。そうでない場合は default を返します。

Cookie.set_nonstandard_attr(name, value)

指定された名前のクッキー属性を設定します。

Cookie クラスは以下のメソッドも定義しています:

Cookie.is_expired(now=None)

サーバが要求するクッキーの有効期限を過ぎていれば True を返します。 now が (エポックからの経過秒で) 指定されているときは、特定の時刻で期限切れかどうかを判定します。

使用例

The first example shows the most common usage of 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/")

The next example illustrates the use of DefaultCookiePolicy. Turn on RFC 2965 cookies, be more strict about domains when setting and returning Netscape cookies, and block some domains from setting cookies or having them returned:

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 サーバーとクライアントモジュール

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

xmlrpc --- XMLRPC サーバーとクライアントモジュール

XML-RPC は HTTP 経由の XML を使って遠隔手続き呼び出し (Remote Procedure Call) を実現する方法です。XML-RPC を使うと、クライアントはリモートサーバー (サーバーは URI で名前付けられます) 上のメソッドを引数付きで呼び出して、構造化されたデータを受け取る事ができます。

xmlrpc パッケージは XML-RPC のサーバーとクライアントを実装したモジュールを持っています。モジュール一覧:

  • xmlrpc.client
  • xmlrpc.server

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


xmlrpc.client --- XML-RPC クライアントアクセス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

xmlrpc.client --- XML-RPC クライアントアクセス

ソースコード: Lib/xmlrpc/client.py

XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP(S) as a transport. With it, a client can call methods with parameters on a remote server (the server is named by a URI) and get back structured data. This module supports writing XML-RPC client code; it handles all the details of translating between conformable Python objects and XML on the wire.

警告

xmlrpc.client モジュールは悪意を持って構築されたデータに対して安全ではありません。信頼できないデータや認証されていないデータを解析する必要がある場合は、XML の脆弱性 を参照してください。

バージョン 3.5 で変更: HTTPS URI の場合、 xmlrpc.client は必要な証明書検証とホスト名チェックを全てデフォルトで行います。

class xmlrpc.client.ServerProxy(uri, transport=None, encoding=None, verbose=False, allow_none=False, use_datetime=False, use_builtin_types=False, *, context=None)

バージョン 3.3 で変更: use_builtin_types フラグが追加されました。

A ServerProxy instance is an object that manages communication with a remote XML-RPC server. The required first argument is a URI (Uniform Resource Indicator), and will normally be the URL of the server. The optional second argument is a transport factory instance; by default it is an internal SafeTransport instance for https: URLs and an internal HTTP Transport instance otherwise. The optional third argument is an encoding, by default UTF-8. The optional fourth argument is a debugging flag.

The following parameters govern the use of the returned proxy instance. If allow_none is true, the Python constant 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 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 obsolete use_datetime flag is similar to use_builtin_types but it applies only to date/time values.

Both the HTTP and HTTPS transports support the URL syntax extension for HTTP Basic Authentication: http://user:pass@host:port/path. The user:pass portion will be base64-encoded as an HTTP 'Authorization' header, and sent to the remote server as part of the connection process when invoking an XML-RPC method. You only need to use this if the remote server requires a Basic Authentication user and password. If an HTTPS URL is provided, context may be ssl.SSLContext and configures the SSL settings of the underlying HTTPS connection.

生成されるインスタンスはリモートサーバへのプロクシオブジェクトで、RPC呼び出しを行う為のメソッドを持ちます。リモートサーバがイントロスペクション APIをサポートしている場合は、リモートサーバのサポートするメソッドを検索 (サービス検索)やサーバのメタデータの取得なども行えます。

Types that are conformable (e.g. that can be marshalled through XML), include the following (and except where noted, they are unmarshalled as the same Python type):

XML-RPC の型 | Python の型
boolean | bool
int, i1, i2, i4, i8 or biginteger | int in range from -2147483648 to 2147483647. Values get the <int> tag.
double or float | float. Values get the <double> tag.
string | str
array | 適合する要素を持つ list または tuple。array は list として返します。
struct | dict. Keys must be strings, values may be any conformable type. Objects of user-defined classes can be passed in; only their __dict__ attribute is transmitted.
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では組み込み型のサブクラスのインスタンスをマーシャルすることはできません。

When passing strings, characters special to XML such as <, >, and & will be automatically escaped. However, it's the caller's responsibility to ensure that the string is free of characters that aren't allowed in XML, such as the control characters with ASCII values between 0 and 31 (except, of course, tab, newline and carriage return); failing to do this will result in an XML-RPC request that isn't well-formed XML. If you have to pass arbitrary bytes via XML-RPC, use bytes or bytearray classes or the Binary wrapper class described below.

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 http://ws.apache.org/xmlrpc/types.html for a description.

参考

XML-RPC HOWTO
数種類のプログラミング言語で記述された XML-RPCの操作とクライアントソフトウェアの素晴らしい説明が掲載されています。 XML- RPCクライアントの開発者が知っておくべきことがほとんど全て記載されています。
XML-RPC Introspection
インストロペクションをサポートする、 XML-RPC プロトコルの拡張を解説しています。
XML-RPC Specification
公式の仕様
XML-RPC 非公式正誤表
Fredrik Lundh による "unofficial errata, intended to clarify certain details in the XML-RPC specification, as well as hint at 'best practices' to use when designing your own XML-RPC implementations."

ServerProxy オブジェクト

ServerProxy インスタンスの各メソッドはそれぞれXML-RPCサーバの遠隔手続き呼び出しに対応しており、メソッドが呼び出されると名前と引数をシグネチャとしてRPCを実行します(同じ名前のメソッドでも、異なる引数シグネチャによってオーバロードされます)。RPC実行後、変換された値を返すか、または Fault オブジェクトもしくは ProtocolError オブジェクトでエラーを通知します。

Servers that support the XML introspection API support some common methods grouped under the reserved system attribute:

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 値を出力します。

また、比較と __repr__() で定義される演算子を使用することができます。

以下は、動作する例です。サーバ側のコード:

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)

Write the XML-RPC base 64 encoding of this binary item to the out stream object.

The encoded data will have newlines every 76 characters as per RFC 2045 section 6.8, which was the de facto standard base64 specification when the XML-RPC spec was written.

また、 __eq__() および __ne__() メソッドで定義される演算子を使用することができます。

バイナリオブジェクトの使用例です。 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 オブジェクト

遠隔のサーバに対する複数の呼び出しをひとつのリクエストにカプセル化する方法は、http://www.xmlrpc.com/discuss/msgReader%241208 で示されています。

class xmlrpc.client.MultiCall(server)

巨大な (boxcar) メソッド呼び出しに使えるオブジェクトを作成します。 server には最終的に呼び出しを行う対象を指定します。作成した MultiCall オブジェクトを使って呼び出しを行うと、即座に None を返し、呼び出したい手続き名とパラメタを MultiCall オブジェクトに保存するだけに留まります。オブジェクト自体を呼び出すと、それまでに保存しておいたすべての呼び出しを単一の system.multicall リクエストの形で伝送します。呼び出し結果はジェネレータ(generator)になります。このジェネレータにわたってイテレーションを行うと、個々の呼び出し結果を返します。

以下は、このクラスの使用例です。サーバ側のコード:

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)

To access an XML-RPC server through a HTTP proxy, you need to define a custom transport. The following example shows how:

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] This approach has been first presented in a discussion on xmlrpc.com.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


xmlrpc.server --- 基本的なXML-RPCサーバー

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

xmlrpc.server --- 基本的なXML-RPCサーバー

ソースコード: Lib/xmlrpc/server.py

xmlrpc.server モジュールはPythonで記述された基本的なXML-RPC サーバーフレームワークを提供します。サーバーはスタンドアロンであるか、 SimpleXMLRPCServer を使うか、 CGIXMLRPCRequestHandler を使って CGI 環境に組み込まれるかの、いずれかです。

警告

xmlrpc.server モジュールは悪意を持って構築されたデータに対して安全ではありません。信頼できないデータや認証されていないデータを解析する必要がある場合は、 XML の脆弱性 を参照してください。

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

The CGIXMLRPCRequestHandler class can be used to handle XML-RPC requests sent to Python CGI scripts.

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 操作ライブラリ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • インターネットプロトコルとサポート »

ipaddress --- IPv4/IPv6 操作ライブラリ

ソースコード: Lib/ipaddress.py

ipaddress は IPv4 と IPv6 アドレスとネットワークの生成・変更・操作を提供しています。

このモジュールの関数やクラスを使うと、IPアドレスに関する様々なタスク、例えば2つのホストが同じサブネットに属しているかどうかをチェックしたり、特定のサブネット内の全てのホストをイテレートしたり、文字列が正しい IP アドレスかネットワークを定義しているかどうかをチェックするなどを簡単に実現することができます。

これはモジュールの完全な API リファレンスです。概要や紹介は ipaddressモジュールの紹介 を参照してください。

バージョン 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 オブジェクト

The IPv4Address and IPv6Address objects share a lot of common attributes. Some attributes that are only meaningful for IPv6 addresses are also implemented by IPv4Address objects, in order to make it easier to write code that handles both IP versions correctly. Address objects are hashable, so they can be used as keys in dictionaries.

class ipaddress.IPv4Address(address)

IPv4 アドレスを構築する。 address が正しい IPv4 アドレスでない場合、 AddressValueError を発生させます。

以下のものが正しい IPv4 アドレスを構築します:

  1. 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 tolerated only for values less than 8 (as there is no ambiguity between the decimal and octal interpretations of such strings).
  2. 32bit に収まる整数。
  3. 大きさ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')
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.

バージョン 3.5 で追加.

is_multicast

アドレスがマルチキャスト用に予約されている場合は True 。 RFC 3171 (IPv4) か RFC 2373 (IPv6) を参照。

is_private

アドレスがプライベートネットワークに割り当てられている場合に True. iana-ipv4-special-registry (for IPv4) か iana-ipv6-special-registry (for IPv6) を参照。

is_global

アドレスがパブリックネットワークに割り当てられている場合に True. iana-ipv4-special-registry (for IPv4) か iana-ipv6-special-registry (for IPv6) を参照。

バージョン 3.4 で追加.

is_unspecified

アドレスが未定義の時に True. RFC 5735 (IPv4) か RFC 2373 (IPv6) を参照。

is_reserved

IETF で予約されているアドレスの場合に True。

is_loopback

ループバックアドレスである場合に True. RFC 3330 (IPv4) か RFC 2373 (IPv6) を参照。

is_link_local

アドレスがリンクローカル用に予約されいている場合に True. RFC 3927 を参照。

class ipaddress.IPv6Address(address)

IPv6 アドレスを構築する。 address が正しい IPv6 アドレスでない場合、 AddressValueError を発生させます。

以下のものが正しい IPv6 アドレスを構築します:

  1. 4桁の16進数からなるグループ8個で構成された文字列。各グループは16bitを表現している。グループはコロンで区切られる。これは exploded (長い) 記法を表す。文字列は compressed (省略) 記法でも良い。詳細は RFC 4291 を参照。例えば、 "0000:0000:0000:0000:0000:0abc:0007:0def" は "::abc:7:def" と省略できる。
  2. 128bit に収まる整数。
  3. ビッグエンディアンで 16 バイトの長さの bytes オブジェクトにパックされた整数。
>>> ipaddress.IPv6Address('2001:db8::1000')
IPv6Address('2001:db8::1000')
compressed

アドレス表現の短い形式で、グループ内の先頭の 0 を省略し、連続する完全に0のグループの一番長いシーケンスを1つの空グループに折りたたんだもの。

これは IPv6 アドレスに対して str(addr) が返す値と同じです。

exploded

アドレス表現の長い形式。全てのグループの先頭の0は省略されず、完全に0のグループも省略されない。

For the following attributes, see the corresponding documentation of the IPv4Address class:

packed
reverse_pointer
version
max_prefixlen
is_multicast
is_private
is_global
is_unspecified
is_reserved
is_loopback
is_link_local

バージョン 3.4 で追加: is_global

is_site_local

アドレスがサイトローカルな目的のために予約されいている場合に True. サイトローカルアドレスは RFC 3879 によって廃止されている事に注意してください。アドレスが RFC 4193 で定義されているユニークローカルアドレスの範囲に含まれているかどうかをテストするには、 is_private を利用してください。

ipv4_mapped

IPv4 にマップされた(::FFFF/96 で始まる)アドレスの場合、このプロパティは埋め込まれた IPv4 Address を返します。それ以外のアドレスに対しては、このプロパティは None になります。

sixtofour

RFC 3056 で定義された 6to4 (2002::/16 で始まる)アドレスの場合、このプロパティは埋め込まれた IPv4 Address を返します。それ以外のアドレスに対しては、このプロパティは None になります。

teredo

RFC 4380 で定義された Teredo (2001::/32 で始まる)アドレスの場合、このプロパティは埋め込まれた (server, client) IP アドレスペアを返します。それ以外のアドレスに対しては、このプロパティは None になります。

文字列と整数への変換

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

演算子

Address オブジェクトはいくつかの演算子をサポートします。明記されない限り、演算子は互換性のあるオブジェクト間 (つまり IPv4 同士や IPv6 同士) でのみ利用できます。

比較演算子

Address オブジェクトは通常の比較演算子を使って比較することができます。いくつかの例:

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

算術演算

アドレスオブジェクトから整数を加減算できます。いくつかの例:

>>> 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 オブジェクト

All attributes implemented by address objects are implemented by network objects as well. In addition, network objects implement additional attributes. All of these are common between IPv4Network and IPv6Network, so to avoid duplication they are only documented for IPv4Network. Network objects are hashable, so they can be used as keys in dictionaries.

class ipaddress.IPv4Network(address, strict=True)

IPv4 ネットワーク定義を構築します。address は以下の1つです:

  1. A string consisting of an IP address and an optional mask, separated by a slash (/). The IP address is the network address, and the mask can be either a single number, which means it's a prefix, or a string representation of an IPv4 address. If it's the latter, the mask is interpreted as a net mask if it starts with a non-zero field, or as a host mask if it starts with a zero field, with the single exception of an all-zero mask which is treated as a net mask. If no mask is provided, it's considered to be /32.

    例えば、次の address 指定は全て等しくなります: 192.168.1.0/24, 192.168.1.0/255.255.255.0 192.168.1.0/0.0.0.255.

  2. 32bit に収まる整数。これは1つのアドレスのネットワークと等しく、ネットワークアドレスが address に、マスクが /32 になります。

  3. 4byte の bytes オブジェクトにビッグエンディアンでパックされた整数。これは整数の address と同じように解釈されます。

  4. アドレス記述とネットマスクの2要素のタプル。アドレス記述は、文字列、32ビットの整数、4バイトのパックされた整数、 既存の IPv4Address オブジェクトのいずれかです。ネットマスクは、プレフィックス長を表す整数（例えば `` 24``）またはプレフィックスマスクを表す文字列（例えば `` 255.255.255.0``）です。

address が有効な IPv4 アドレスでない場合に AddressValueError 例外を発生させます。マスクが IPv4 アドレスに対して有効でない場合に NetmaskValueError 例外を発生させます。

strict が True の場合、与えられたアドレスのホストビットが立っていたら ValueError を発生させます。そうでない場合、ホストビットをマスクして正しいネットワークアドレスを計算します。

Unless stated otherwise, all network methods accepting other network/address objects will raise TypeError if the argument's IP version is incompatible to self.

バージョン 3.5 で変更: address コンストラクタ引数に2要素のタプル形式を追加しました

version
max_prefixlen

Refer to the corresponding attribute documentation in 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

The host mask, as an IPv4Address object.

netmask

The net mask, as an IPv4Address object.

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

The total number of addresses in the network.

prefixlen

Length of the network prefix, in bits.

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.

>>> list(ip_network('192.0.2.0/29').hosts())  #doctest: +NORMALIZE_WHITESPACE
[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')]
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))  #doctest: +NORMALIZE_WHITESPACE
[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))  #doctest: +NORMALIZE_WHITESPACE
[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))  #doctest: +NORMALIZE_WHITESPACE
[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)

Returns True if this network is a subnet of other.

>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> b.subnet_of(a)
True

バージョン 3.7 で追加.

supernet_of(other)

Returns True if this network is a supernet of other.

>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> a.supernet_of(b)
True

バージョン 3.7 で追加.

compare_networks(other)

Compare this network to other. In this comparison only the network addresses are considered; host bits aren't. Returns either -1, 0 or 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)

Construct an IPv6 network definition. address can be one of the following:

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

  2. An integer that fits into 128 bits. This is equivalent to a single-address network, with the network address being address and the mask being /128.

  3. An integer packed into a bytes object of length 16, big-endian. The interpretation is similar to an integer address.

  4. アドレス記述とネットマスクの2要素のタプル。アドレス記述は、文字列、128ビットの整数、16バイトのパックされた整数、 既存の IPv6Address オブジェクトのいずれかです。ネットマスクは、プレフィックス長を表す整数です。

An AddressValueError is raised if address is not a valid IPv6 address. A NetmaskValueError is raised if the mask is not valid for an IPv6 address.

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.

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)

Refer to the corresponding attribute documentation in 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 objects support some operators. Unless stated otherwise, operators can only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with 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')

Networks as containers of addresses

Network objects can act as containers of addresses. Some examples:

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

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

Interface objects are hashable, so they can be used as keys in dictionaries.

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

Refer to the corresponding attribute documentation in IPv4Interface.

演算子

Interface objects support some operators. Unless stated otherwise, operators can only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with 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')

doesn't make sense. There are some times however, where you may wish to have ipaddress sort these anyway. If you need to do this, you can use this function as the key argument to sorted().

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.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • インターネットプロトコルとサポート »


マルチメディアサービス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

マルチメディアサービス

この章で記述されているモジュールは、主にマルチメディアアプリケーションに役立つさまざまなアルゴリズムまたはインターフェイスを実装しています。これらのモジュールはインストール時の自由裁量に応じて利用できます:

  • audioop --- 生の音声データを操作する
  • aifc --- AIFFおよびAIFCファイルの読み書き
  • sunau --- Sun AUファイルの読み書き
    • AU_read オブジェクト
    • AU_write オブジェクト
  • wave --- WAVファイルの読み書き
    • Wave_read オブジェクト
    • Wave_write オブジェクト
  • chunk --- IFFチャンクデータの読み込み
  • colorsys --- 色体系間の変換
  • imghdr --- 画像の形式を決定する
  • sndhdr --- サウンドファイルの識別
  • ossaudiodev --- OSS互換オーディオデバイスへのアクセス
    • オーディオデバイスオブジェクト
    • ミキサデバイスオブジェクト

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • マルチメディアサービス »

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 を返します。ビッグエンディアンのサンプルをリトルエンディアンに、またはその逆に変換します。

バージョン 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)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • マルチメディアサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • マルチメディアサービス »

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

ソースコード: Lib/aifc.py

このモジュールは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)

Open an AIFF or AIFF-C file and return an object instance with methods that are described below. The argument file is either a string naming a file or a file object. mode must be 'r' or 'rb' when the file must be opened for reading, or 'w' or 'wb' when the file must be opened for writing. If omitted, file.mode is used if it exists, otherwise 'rb' is used. When used for writing, the file object should be seekable, unless you know ahead of time how many samples you are going to write in total and use writeframesraw() and setnframes(). The open() function may be used in a with statement. When the with block completes, the close() method is called.

バージョン 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ファイルを閉じます。ファイルのヘッダ情報は、オーディオデータの実際のサイズを反映して更新されます。このメソッドを呼び出したあとでは、オブジェクトはもう使用できません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • マルチメディアサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • マルチメディアサービス »

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

ソースコード: Lib/sunau.py

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.openfp(file, mode)

open() と同義。後方互換性のために残されています。

Deprecated since version 3.7, will be removed in version 3.9.

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() メソッドを呼び出したあとで、どんなパラメータを設定しようとしても不正となることに注意して下さい。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • マルチメディアサービス »


wave --- WAVファイルの読み書き

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • マルチメディアサービス »

wave --- WAVファイルの読み書き

ソースコード: Lib/wave.py

wave モジュールは、WAVサウンドフォーマットへの便利なインターフェイスを提供するモジュールです。このモジュールは圧縮／展開をサポートしていませんが、モノラル／ステレオには対応しています。

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 のデフォルト値として使われます。

file like オブジェクトを渡した場合、 wave オブジェクトの close() メソッドを呼び出してもその file like オブジェクトを close しません。 file like オブジェクトの close は呼び出し側の責任になります。

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 で変更: シーク不能なファイルのサポートが追加されました。

wave.openfp(file, mode)

open() と同義。後方互換性のために残されています。

Deprecated since version 3.7, will be removed in version 3.9.

exception wave.Error

WAVの仕様を犯したり、実装の欠陥に遭遇して何か実行不可能となった時に発生するエラー。

Wave_read オブジェクト

open() によって返される Wave_read オブジェクトには、以下のメソッドがあります:

Wave_read.close()

wave によって開かれていた場合はストリームを閉じ、このオブジェクトのインスタンスを使用できなくします。これはオブジェクトのガベージコレクション時に自動的に呼び出されます。

Wave_read.getnchannels()

オーディオチャンネル数（モノラルなら 1 、ステレオなら 2 ）を返します。

Wave_read.getsampwidth()

サンプルサイズをバイト数で返します。

Wave_read.getframerate()

サンプリングレートを返します。

Wave_read.getnframes()

オーディオフレーム数を返します。

Wave_read.getcomptype()

圧縮形式を返します（ 'NONE' だけがサポートされている形式です）。

Wave_read.getcompname()

getcomptype() を人に判読可能な形にしたものです。通常、 'NONE' に対して 'not compressed' が返されます。

Wave_read.getparams()

get*() メソッドが返すのと同じ (nchannels, sampwidth, framerate, nframes, comptype, compname) の namedtuple() を返します。

Wave_read.readframes(n)

最大 n 個のオーディオフレームを読み込んで、 bytes オブジェクトとして返します。

Wave_read.rewind()

ファイルのポインタをオーディオストリームの先頭に戻します。

以下の2つのメソッドは aifc モジュールとの互換性のために定義されており、何も面白いことはしません。

Wave_read.getmarkers()

None を返します。

Wave_read.getmark(id)

エラーを発生します。

以下の2つのメソッドは共通の"位置"を定義しています。"位置"は他の関数とは独立して実装されています。

Wave_read.setpos(pos)

ファイルのポインタを指定した位置に設定します。

Wave_read.tell()

ファイルの現在のポインタ位置を返します。

Wave_write オブジェクト

seek 可能な出力ストリームでは、実際に書き込まれたフレーム数を反映するように wave ヘッダーは自動的にアップデートされます。 seek 不能なストリームでは、最初のフレームデータが書き込まれる時には nframes の値は正確でなければなりません。 nframes の正確な値は、 close() が呼ばれる前に書き込まれるフレーム数とともに setnframes() または setparams() を呼んで、その後 writeframesraw() を利用してフレームデータを書くか、もしくはすべての書き込むべきフレームデータとともに writeframes() を呼び出すことによって達成できます。後者のケースでは、 writeframes() はフレームデータを書く前に、データ中のフレームの数を計算して、それに応じて nframes を設定します。

open() によって返される Wave_write オブジェクトには、以下のメソッドがあります:

バージョン 3.4 で変更: シーク不能なファイルのサポートが追加されました。

Wave_write.close()

nframes が正しいか確認して、ファイルが wave によって開かれていた場合は閉じます。このメソッドはオブジェクトがガベージコレクションされるときに呼び出されます。もし出力ストリームがシーク不能で、 nframes が実際に書き込まれたフレームの数と一致しなければ、例外が起きます。

Wave_write.setnchannels(n)

チャンネル数を設定します。

Wave_write.setsampwidth(n)

サンプルサイズを n バイトに設定します。

Wave_write.setframerate(n)

サンプリングレートを n に設定します。

バージョン 3.2 で変更: 整数ではない値がこのメソッドに入力された場合は、直近の整数に丸められます。

Wave_write.setnframes(n)

フレーム数を n に設定します。もし実際に書き込まれたフレームの数と異なるなら、これは後で変更されます (出力ストリームがシーク不能なら、更新しようとした時にエラーが起きます)。

Wave_write.setcomptype(type, name)

圧縮形式とその記述を設定します。現在のところ、非圧縮を示す圧縮形式 NONE だけがサポートされています。

Wave_write.setparams(tuple)

この tuple は (nchannels, sampwidth, framerate, nframes, comptype, compname) でなければならず、その値はそれぞれの set*() メソッドで有効でなければなりません。すべてのパラメータを設定します。

Wave_write.tell()

ファイルの中の現在位置を返します。 Wave_read.tell() と Wave_read.setpos() メソッドでお断りしたことがこのメソッドにも当てはまります。

Wave_write.writeframesraw(data)

nframes の修正なしにオーディオフレームを書き込みます。

バージョン 3.4 で変更: どのような bytes-like object も使用できるようになりました。

Wave_write.writeframes(data)

出力ストリームが seek 不可能で、 data が書き込まれた後でそれ以前に nframes に設定された値と書き込まれた全フレーム数が一致しなければ、エラーを送出します。

バージョン 3.4 で変更: どのような bytes-like object も使用できるようになりました。

writeframes() や writeframesraw() メソッドを呼び出したあとで、どんなパラメータを設定しようとしても不正となることに注意して下さい。そうすると wave.Error を発生します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • マルチメディアサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • マルチメディアサービス »

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

ソースコード: Lib/chunk.py

このモジュールは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.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • マルチメディアサービス »


colorsys --- 色体系間の変換

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • マルチメディアサービス »

colorsys --- 色体系間の変換

ソースコード: 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 の値をとります。

参考

More information about color spaces can be found at http://poynton.ca/ColorFAQ.html and 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)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • マルチメディアサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • マルチメディアサービス »

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

ソースコード: Lib/imghdr.py

imghdr モジュールはファイルやバイトストリームに含まれる画像の形式を決定します。

imghdr モジュールは次の関数を定義しています:

imghdr.what(filename, h=None)

filename という名前のファイル内の画像データをテストし、画像形式を表す文字列を返します。オプションの h が与えられた場合は、filename は無視され、テストするバイトストリームを含んでいると h は仮定されます。

バージョン 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

バージョン 3.5 で追加: フォーマット*exr*と*webp*が追加されました.

この変数に追加することで、あなたは imghdr が認識できるファイル形式のリストを拡張できます:

imghdr.tests

個別のテストを行う関数のリスト。それぞれの関数は二つの引数をとります: バイトストリームとオープンされたファイルのようにふるまうオブジェクト。 what() がバイトストリームとともに呼び出されたときは、ファイルのようにふるまうオブジェクトは None でしょう。

テストが成功した場合は、テスト関数は画像形式を表す文字列を返すべきです。あるいは、失敗した場合は None を返すべきです。

以下はプログラム例です:

>>> import imghdr
>>> imghdr.what('bass.gif')
'gif'

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • マルチメディアサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • マルチメディアサービス »

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

ソースコード: Lib/sndhdr.py

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 に変更されました。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • マルチメディアサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • マルチメディアサービス »

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

このモジュールを使うとOSS (Open Sound System) オーディオインターフェースにアクセスできます。OSSはオープンソースあるいは商用のUnixで広く利用でき、Linux (カーネル 2.4まで) とFreeBSDで標準のオーディオインターフェースです。

バージョン 3.3 で変更: このモジュールの操作で以前は IOError が送出されていたところで OSError が送出されるようになりました。

参考

Open Sound System Programmer's Guide
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 つのメソッドを正しい順序で呼び出さねばなりません:

  1. setfmt() で出力形式を設定し
  2. channels() でチャンネル数を設定し
  3. 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)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • マルチメディアサービス »


国際化

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

国際化

この章で解説されるモジュールは、プログラムのメッセージで使用される言語を選択したり、または出力を地域の習慣に従って変更するメカニズムを提供して、言語や地域に依存しないソフトの開発を手助けします。

この章で解説されるモジュールのリスト:

  • gettext --- 多言語対応に関する国際化サービス
    • GNU gettext API
    • クラス形式の API
      • NullTranslations クラス
      • GNUTranslations クラス
      • Solaris メッセージカタログ機構のサポート
      • Catalog コンストラクタ
    • プログラムやモジュールを国際化する
      • モジュールを地域化する
      • アプリケーションを地域化する
      • 動作中 (on the fly) に言語を切り替える
      • 翻訳処理の遅延解決
    • 謝辞
  • locale --- 国際化サービス
    • ロケールの背景、詳細、ヒント、助言および補足説明
    • Python 拡張の作者と、Python を埋め込むようなプログラムに関して
    • メッセージカタログへのアクセス

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


gettext --- 多言語対応に関する国際化サービス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 国際化 »

gettext --- 多言語対応に関する国際化サービス

ソースコード: 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.bind_textdomain_codeset(domain, codeset=None)

domain を codeset に対応付け、 lgettext(), ldgettext(), lngettext(), ldngettext() 関数が返すバイト文字列のエンコード方式を変更します。 codeset が省略された場合は、現在 domain に対応付けられているコードセットを返します。

gettext.textdomain(domain=None)

現在のグローバルドメインを変更したり調べたりします。 domain が None の場合、現在のグローバルドメインが返されます。それ以外の場合には、グローバルドメインに domain を設定し、その設定されたグローバルドメインを返します。

gettext.gettext(message)

現在のグローバルドメイン、言語、およびロケールディレクトリに基づいて、 message の地域化された訳文を返します。 通常、この関数はローカルな名前空間にある _() という別名を持ちます (下の例を参照してください)。

gettext.dgettext(domain, message)

gettext() と同様ですが、指定された domain からメッセージを探します。

gettext.ngettext(singular, plural, n)

gettext() と同様ですが、複数形を考慮しています。 翻訳が見つかった場合、複数形の選択公式を n に適用し、その結果得られたメッセージを返します (言語によっては二つ以上の複数形があります)。 翻訳が見つからなかった場合、 n が 1 なら singular を返します; そうでない場合 plural を返します。

複数形の選択公式はカタログのヘッダから取得されます。 選択公式は自由変数 n を持つ C または Python の式です; その式の評価結果はカタログにある複数形のインデックスになります。 .po ファイルで用いられる詳細な文法と、様々な言語における選択公式については GNU gettext ドキュメント を参照してください。

gettext.dngettext(domain, singular, plural, n)

ngettext() と同様ですが、指定された domain からメッセージを探します。

gettext.lgettext(message)
gettext.ldgettext(domain, message)
gettext.lngettext(singular, plural, n)
gettext.ldngettext(domain, singular, plural, n)

それぞれに対応する先頭の l が無い関数 (gettext(), dgettext(), ngettext(), dngettext()) と同じですが、エンコーディングが bind_textdomain_codeset() を使って明示的に設定されていない場合、翻訳結果は優先システムエンコーディングでエンコードされたバイト文字列として返されます。

警告

これらの関数はエンコードされたバイト列を返すため Python 3 で使うのは避けるべきです。 ほとんどの Python アプリケーションでは、人間が読むテキストをバイト列ではなく文字列として扱いたいので、 Unicode 文字列を返す代わりの関数を使う方が良いです。 さらに言うと、翻訳文字列にエンコーディング上の問題があった場合、 Unicode 関連の予期しない例外を受け取るかもしれません。 このように l*() 関数は問題や制約を抱えているので、将来の Python バージョンで非推奨となる可能性があります。

GNU gettext では dcgettext() も定義していますが、このメソッドはあまり有用ではないと思われるので、現在のところ実装されていません。

以下にこの API の典型的な使用法を示します:

import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print(_('This is a translatable string.'))

クラス形式の API

gettext モジュールのクラス形式の API は、 GNU gettext API よりも高い柔軟性と利便性を持っています。 Python のアプリケーションやモジュールを地域化するにはこちらを使うことをお勧めします。 gettext には、GNU .mo 形式のファイルを構文解析する処理の実装と、文字列を返すメソッドを持つ "翻訳" クラスが定義されています。 この "翻訳" クラスのインスタンスも、自分自身を組み込み名前空間に関数 _() として配置できます。

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, codeset=None)

domain 、 localedir 、 languages に基づいて Translations インスタンスを返します。 domain 、 localedir 、 languages はまず find() に渡され、関連付けられている .mo ファイルパスのリストを取得します。 同一の .mo ファイル名を持つインスタンスはキャッシュされます。 実際にインスタンス化されるクラスは、 class_ が与えられていた場合はそのクラスで、そうでない場合には GNUTranslations です。 クラスのコンストラクタは単一の引数として file object を取らなければなりません。 codeset が与えられた場合、 lgettext() メソッドおよび lngettext() メソッドで翻訳文字列のエンコードに使う文字集合を変更します。

複数の .mo ファイルがあった場合、後ろのファイルは前のファイルのフォールバックとして利用されます。 フォールバックの設定のために、 copy.copy() を使いキャッシュから翻訳オブジェクトを複製します; こうすることで、実際のインスタンスデータはキャッシュのものと共有されたままになります。

.mo ファイルが見つからなかった場合、 fallback が偽 (デフォルト値) ならこの関数は OSError を送出し、 fallback が真なら NullTranslations インスタンスが返されます。

バージョン 3.3 で変更: 以前は OSError ではなく IOError が送出されていました。

gettext.install(domain, localedir=None, codeset=None, names=None)

translation() に domain 、 localedir 、および codeset を渡してできる関数 _() を Python の組み込み名前空間に組み込みます。

names パラメータについては、翻訳オブジェクトの install() メソッドの説明を参照ください。

以下に示すように、通常はアプリケーション中の文字列を関数 _() の呼び出しで包み込んで翻訳対象候補であることを示します:

print(_('This string will be translated.'))

利便性を高めるためには、 _() 関数を Python の組み込み名前空間に組み入れる必要があります。こうすることで、アプリケーション内の全てのモジュールからアクセスできるようになります。

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 を返します。 派生クラスで上書きするメソッドです。

lgettext(message)
lngettext(singular, plural, n)

gettext() および ngettext() と同じですが、エンコーディングが set_output_charset() で明示的に設定されていない場合、翻訳結果は優先システムエンコーディングでエンコードされたバイト文字列として返されます。 派生クラスで上書きするメソッドです。

警告

これらのメソッドは Python 3 で使うのは避けるべきです。 lgettext() 関数に対する警告を参照してください。

info()

"protected" の _info 変数を返します。

charset()

メッセージカタログファイルのエンコーディングを返します。

output_charset()

lgettext() と lngettext() の返り値となる翻訳メッセージで使われているエンコーディングを返します。

set_output_charset(charset)

返り値の翻訳メッセージで使われるエンコーディングを変更します。

install(names=None)

このメソッドは gettext() を組み込み名前空間にインストールし、変数 _ に束縛します。

names パラメータを与える場合には、 _() 以外では組み込み名前空間に配置したい関数名を列挙したシーケンスでなければなりません。 サポートされている名前は 'gettext' 、 'ngettext' 、 'lgettext' 、 'lngettext' です。

この方法はアプリケーションで _() 関数を利用できるようにするための最も便利な方法ですが、唯一の手段でもあるので注意してください。この関数はアプリケーション全体、とりわけ組み込み名前空間に影響するので、地域化されたモジュールで _() を組み入れることができないのです。その代わりに、以下のコードを使って _() を使えるようにしなければなりません。:

import gettext
t = gettext.translation('mymodule', ...)
_ = t.gettext

この操作は _() をモジュール内だけのグローバル名前空間に組み入れるので、モジュール内の _() の呼び出しだけに影響します。

GNUTranslations クラス

gettext モジュールでは NullTranslations から派生したもう一つのクラス: GNUTranslations を提供しています。このクラスはビッグエンディアン、およびリトルエンディアン両方のバイナリ形式の GNU gettext .mo ファイルを読み出せるように _parse() を上書きしています。

GNUTranslations はまた、翻訳カタログ以外に、オプションのメタデータを読み込んで解釈します。GNU gettext では、空の文字列に対する変換先としてメタデータを取り込むことが慣習になっています。このメタデータは RFC 822 形式の key: value のペアになっており、 Project-Id-Version キーを含んでいなければなりません。キー Content-Type があった場合、 charset の特性値 (property) は "保護された" _charset インスタンス変数を初期化するために用いられます。値がない場合には、デフォルトとして None が使われます。エンコードに用いられる文字セットが指定されている場合、カタログから読み出された全てのメッセージ id とメッセージ文字列は、指定されたエンコードを用いて Unicode に変換され、そうでなければ ASCII エンコーディングとみなされます。

メッセージ id もユニコード文字列として解釈されるので、すべての *gettext() メソッドはメッセージ id をバイト文字列ではなくユニコード文字列と仮定するでしょう。

key/value ペアの集合全体は辞書型データ中に配置され、"保護された" _info インスタンス変数に設定されます。

.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}
lgettext(message)
lngettext(singular, plural, n)

gettext() および ngettext() と同じですが、エンコーディングが set_output_charset() で明示的に設定されていない場合、翻訳結果は優先システムエンコーディングでエンコードされたバイト文字列として返されます。

警告

これらのメソッドは Python 3 で使うのは避けるべきです。 lgettext() 関数に対する警告を参照してください。

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

Solaris オペレーティングシステムでは、独自の .mo バイナリファイル形式を定義していますが、この形式に関するドキュメントが手に入らないため、現時点ではサポートされていません。

Catalog コンストラクタ

GNOME では、James Henstridge によるあるバージョンの gettext モジュールを使っていますが、このバージョンは少し異なった API を持っています。ドキュメントに書かれている利用法は:

import gettext
cat = gettext.Catalog(domain, localedir)
_ = cat.gettext
print(_('hello world'))

となっています。過去のモジュールとの互換性のために、 Catalog() は前述の translation() 関数の別名になっています。

このモジュールと Henstridge のバージョンとの間には一つ相違点があります: 彼のカタログオブジェクトはマップ型の API を介したアクセスがサポートされていましたが、この API は使われていないらしく、現在はサポートされていません。

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

国際化 (I18N, I-nternationalizatio-N) とは、プログラムを複数の言語に対応させる操作を指します。地域化 (L10N, L-ocalizatio-N) とは、すでに国際化されているプログラムを特定地域の言語や文化的な事情に対応させることを指します。Python プログラムに多言語メッセージ機能を追加するには、以下の手順を踏む必要があります:

  1. プログラムやモジュールで翻訳対象とする文字列に特殊なマークをつけて準備します
  2. マークづけをしたファイルに一連のツールを走らせ、生のメッセージカタログを生成します
  3. 特定の言語へのメッセージカタログの翻訳を作成します
  4. メッセージ文字列を適切に変換するために gettext モジュールを使います

ソースコードを I18N 化する準備として、ファイル内の全ての文字列を探す必要があります。翻訳を行う必要のある文字列はどれも _('...') --- すなわち関数 _() の呼び出しで包むことでマーク付けしなくてはなりません。例えば以下のようにします:

filename = 'mylog.txt'
message = _('writing a log message')
fp = open(filename, 'w')
fp.write(message)
fp.close()

この例では、文字列 'writing a log message' が翻訳対象候補としてマーク付けされており、文字列 'mylog.txt' および 'w' はされていません。

飜訳対象の文字列を抽出するツールもあります。 オリジナルの GNU gettext は C と C++ のソースコードしかサポートしませんが、拡張版の xgettext は Python を含めた多くの言語で書かれたコードを読み取り、飜訳できる文字列を発見します。 Babel は Python の国際化ライブラリで、飜訳文字列の抽出とメッセージカタログのコンパイルを行う file:pybabel スクリプトがあります。 François Pinard が開発した xpot と呼ばれるプログラムは同じような処理を行え、彼の po-utils package の一部として利用可能です。

(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

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

アプリケーションを地域化するのなら、関数 _() をグローバルな組み込み名前空間に組み入れなければならず、これは通常アプリケーションの主ドライバ (main driver) ファイルで行います。この操作によって、アプリケーション独自のファイルは明示的に各ファイルで _() の組み入れを行わなくても単に _('...') を使うだけで済むようになります。

単純な場合では、単に以下の短いコードをアプリケーションの主ドライバファイルに追加するだけです:

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

ダミーの _() 定義が単に文字列をそのまま返すようになっているので、上のコードはうまく動作します。かつ、このダミーの定義は、組み込み名前空間に置かれた _() の定義で (del 命令を実行するまで) 一時的に上書きすることができます。もしそれまでに _() をローカルな名前空間に持っていたら注意してください。

二つ目の例における _() の使い方では、パラメータが文字列リテラルではないので、 gettext プログラムが翻訳可能だとは判定されないことに注意してください。

もう一つの処理法は、以下の例のようなやり方です:

def N_(message): return message

animals = [N_('mollusk'),
           N_('albatross'),
           N_('rat'),
           N_('penguin'),
           N_('python'), ]

# ...
for a in animals:
    print(_(a))

この例では、飜訳可能な文字列に N_() でマークを付けているために、 _() の定義と衝突しません。 しかし、これではメッセージを抽出するプログラムに対して N_() でマークされている飜訳可能な文字列を見付けるように教える必要が出てきます。 xgettext, pygettext, pybabel extract, xpot は全て、コマンドラインスイッチ -k を使ってその機能をサポートしています。 この例の N_() という名前は好きに選べます; 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] 標準でロケールが収められているディレクトリはシステム依存です; 例えば、RedHat Linux では /usr/share/locale ですが、 Solaris では /usr/lib/locale です。 gettext モジュールはこうしたシステム依存の標準設定をサポートしません; その代わりに sys.prefix/share/locale を標準の設定とします。この理由から、常にアプリケーションの開始時に絶対パスで明示的に指定して bindtextdomain() を呼び出すのが最良のやり方ということになります。
[2] 上の bindtextdomain() に関する脚注を参照してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 国際化 »


locale --- 国際化サービス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 国際化 »

locale --- 国際化サービス

ソースコード: Lib/locale.py

locale モジュールは POSIX ロケールデータベースおよびロケール関連機能へのアクセスを提供します。 POSIX ロケール機構を使うことで、プログラマはソフトウェアが実行される各国における詳細を知らなくても、アプリケーション上で特定の地域文化に関係する部分を扱うことができます。

locale モジュールは、 _locale を被うように実装されており、ANSI C ロケール実装を使っている _locale が利用可能なら、こちらを先に使うようになっています。

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() の書式文字列として用いることのできる文字列を取得します。

DAY_1 ... DAY_7

1 週間中の n 番目の曜日名を取得します。

注釈

ロケール US における、 DAY_1 を日曜日とする慣行に従っています。国際的な (ISO 8601) 月曜日を週の初めとする慣行ではありません。

ABDAY_1 ... ABDAY_7

1 週間中の n 番目の曜日名を略式表記で取得します。

MON_1 ... MON_12

n 番目の月の名前を取得します。

ABMON_1 ... ABMON_12

n 番目の月の名前を略式表記で取得します。

locale.RADIXCHAR

基数点 (小数点ドット、あるいは小数点コンマ、等) を取得します。

locale.THOUSEP

1000 単位桁区切り (3 桁ごとのグループ化) の区切り文字を取得します。

locale.YESEXPR

肯定／否定で答える質問に対する肯定回答を正規表現関数で認識するために利用できる正規表現を取得します。

注釈

表現は C ライブラリの regex() 関数に合ったものでなければならず、これは re で使われている構文とは異なるかもしれません。

locale.NOEXPR

肯定／否定で答える質問に対する否定回答を正規表現関数で認識するために利用できる正規表現を取得します。

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 に対応します。 language code および encoding が決定できなかった場合、 None になるかもしれません。

locale.getlocale(category=LC_CTYPE)

与えられたロケールカテゴリに対する現在の設定を、 language code 、 encoding を含むシーケンスで返します。 category として LC_ALL 以外の LC_* の値の一つを指定できます。標準の設定は LC_CTYPE です。

'C' の場合を除き、言語コードは RFC 1766 に対応します。 language code および encoding が決定できなかった場合、 None になるかもしれません。

locale.getpreferredencoding(do_setlocale=True)

テキストデータをエンコードする方法を、ユーザの設定に基づいて返します。ユーザの設定は異なるシステム間では異なった方法で表現され、システムによってはプログラミング的に得ることができないこともあるので、この関数が返すのはただの推測です。

システムによっては、ユーザの設定を取得するために setlocale() を呼び出す必要があるため、この関数はスレッド安全ではありません。 setlocale() を呼び出す必要がない、または呼び出したくない場合、 do_setlocale を False に設定する必要があります。

Android 上あるいは UTF-8 モード (-X utf8 オプション) では、常に 'UTF-8' が返され、ロケールや do_setlocale 引数は無視されます。

バージョン 3.7 で変更: この関数は、 Android 上あるいは UTF-8 モードが有効になっている場合、常に UTF-8 を返すようになりました。

locale.normalize(localename)

与えたロケール名を規格化したロケールコードを返します。返されるロケールコードは setlocale() で使うために書式化されています。規格化が失敗した場合、もとの名前がそのまま返されます。

与えたエンコードがシステムにとって未知の場合、標準の設定では、この関数は setlocale() と同様に、エンコーディングをロケールコードにおける標準のエンコーディングに設定します。

locale.resetlocale(category=LC_ALL)

category のロケールを標準設定にします。

標準設定は getdefaultlocale() を呼ぶことで決定されます。 category は標準で LC_ALL になっています。

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 が真なら、ロケールに配慮した桁数の区切りが行われます。

monetary が真なら、桁区切り記号やグループ化文字列を用いて変換を行います。

format % val 形式のフォーマット指定子を、現在のロケール設定を考慮したうえで処理します。

バージョン 3.7 で変更: monetary パラメータが追加されました。

locale.format(format, val, grouping=False, monetary=False)

この関数は format_string() に似た動作をしますが、1つの %char 指示子しかない場合のみ動作します。 例えば、'%f' や '%.0f' はどちらも有効な指示子ですが、 '%f KiB' は有効ではありません。

文字列全体をフォーマットするには、 format_string() を使ってください。

バージョン 3.7 で非推奨: 代わりに format_string() を使ってください。

locale.currency(val, symbol=True, grouping=False, international=False)

数値 val を、現在の LC_MONETARY の設定にあわせてフォーマットします。

symbol が真の場合は、返される文字列に通貨記号が含まれるようになります。これはデフォルトの設定です。grouping が真の場合(これはデフォルトではありません)は、値をグループ化します。international が真の場合(これはデフォルトではありません)は、国際的な通貨記号を使用します。

この関数は'C'ロケールでは動作しないことに注意しましょう。まず最初に setlocale() でロケールを設定する必要があります。

locale.str(float)

浮動小数点数を str(float) と同じように書式化しますが、ロケールに配慮した小数点が使われます。

locale.delocalize(string)

文字列を LC_NUMERIC で設定された慣行に従って正規化された数値文字列に変換します。

バージョン 3.5 で追加.

locale.atof(string)

文字列を LC_NUMERIC で設定された慣行に従って浮動小数点に変換します。

locale.atoi(string)

文字列を LC_NUMERIC で設定された慣行に従って整数に変換します。

locale.LC_CTYPE

文字タイプ関連の関数のためのロケールカテゴリです。このカテゴリの設定に従って、モジュール string における関数の振る舞いが変わります。

locale.LC_COLLATE

文字列を並べ替えるためのロケールカテゴリです。 locale モジュールの関数 strcoll() および strxfrm() が影響を受けます。

locale.LC_TIME

時刻を書式化するためのロケールカテゴリです。 time.strftime() はこのカテゴリに設定されている慣行に従います。

locale.LC_MONETARY

金額に関係する値を書式化するためのロケールカテゴリです。設定可能なオプションは関数 localeconv() で得ることができます。

locale.LC_MESSAGES

メッセージ表示のためのロケールカテゴリです。現在 Python はアプリケーション毎にロケールに対応したメッセージを出力する機能はサポートしていません。 os.strerror() が返すような、オペレーティングシステムによって表示されるメッセージはこのカテゴリによって影響を受けます。

locale.LC_NUMERIC

数字を書式化するためのロケールカテゴリです。関数 format() 、 atoi() 、 atof() および locale モジュールの str() が影響を受けます。他の数値書式化操作は影響を受けません。

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 ロケール以外の設定には互換性がないとドキュメントに書くことです。

ロケールに従って数値操作を行うための唯一の方法はこのモジュールで特別に定義されている関数: atof() 、 atoi() 、 format() 、 str() を使うことです。

ロケールに従ってケース変換や文字分類を行う方法はありません。 (ユニコード) テキスト文字列については、これらは文字の値のみによって行われます。その一方、バイト文字列はバイトの ASCII 値に従って変換と分類が行われます。そして、上位ビットが立っているバイト (すなわち、non-ASCII バイト) は、決して変換されず、英字や空白などの文字クラスの一部とみなされることもありません。

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

拡張モジュールは、現在のロケールを調べる以外は、決して setlocale() を呼び出してはなりません。しかし、返される値もロケールの復帰のために使えるだけなので、さほど便利とはいえません (例外はおそらくロケールが C かどうか調べることでしょう)。

ロケールを変更するために Python コードで locale モジュールを使った場合、Python を埋め込んでいるアプリケーションにも影響を及ぼします。Python を埋め込んでいるアプリケーションに影響が及ぶことを望まない場合、 config.c ファイル内の組み込みモジュールのテーブルから _locale 拡張モジュール (ここで全てを行っています) を削除し、共有ライブラリから _locale モジュールにアクセスできないようにしてください。

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

locale.gettext(msg)
locale.dgettext(domain, msg)
locale.dcgettext(domain, msg, category)
locale.textdomain(domain)
locale.bindtextdomain(domain, dir)

C ライブラリの gettext インタフェースが提供されているシステムでは、 locake モジュールでそのインタフェースを公開しています。このインタフェースは関数 gettext() 、 dgettext() 、 dcgettext() 、 textdomain() 、 bindtextdomain() 、 bind_textdomain_codeset() からなります。これらは gettext モジュールの同名の関数に似ていますが、メッセージカタログとして C ライブラリのバイナリフォーマットを使い、メッセージカタログを探すために C ライブラリの検索アルゴリズムを使います。

Python アプリケーションでは、通常これらの関数を呼び出す必要はないはずで、代わりに gettext を呼ぶべきです。例外として知られているのは、内部で gettext() または dcgettext() を呼び出すような C ライブラリにリンクするアプリケーションです。こうしたアプリケーションでは、ライブラリが正しいメッセージカタログを探せるようにテキストドメイン名を指定する必要があります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 国際化 »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

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

この章で解説されるモジュールはあなたのプログラムの大枠を規定するフレームワークです。現状では、ここで解説されるモジュールは全てコマンドラインインタフェースを書くためのものです。

この章で解説されるモジュールの完全な一覧は:

  • turtle --- タートルグラフィックス
    • はじめに
    • Turtle および Screen のメソッドの概観
      • Turtle のメソッド
      • TurtleScreen/Screen のメソッド
    • RawTurtle/Turtle のメソッドと対応する関数
      • Turtle の動き
      • Turtle の状態を知る
      • 設定と計測
      • Pen の制御
        • 描画状態
        • 色の制御
        • 塗りつぶし
        • さらなる描画の制御
      • タートルの状態
        • 可視性
        • 見た目
      • イベントを利用する
      • 特別な Turtle のメソッド
      • Compound shapes
    • TurtleScreen/Screen のメソッドと対応する関数
      • ウィンドウの制御
      • アニメーションの制御
      • スクリーンイベントを利用する
      • Input methods
      • 設定と特殊なメソッド
      • Screen 独自のメソッド、TurtleScreen から継承したもの以外
    • Public classes
    • ヘルプと設定
      • ヘルプの使い方
      • ドキュメント文字列の翻訳
      • Screen および Turtle の設定方法
    • turtledemo --- デモスクリプト
    • python 2.6からの変更点
    • python 3.0からの変更点
  • cmd --- 行指向のコマンドインタープリタのサポート
    • Cmdオブジェクト
    • Cmd の例
  • shlex --- 単純な字句解析
    • shlex オブジェクト
    • 解析規則
    • Improved Compatibility with Shells

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • プログラムのフレームワーク »

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

ソースコード: Lib/turtle.py

はじめに

タートルグラフィックスは子供にプログラミングを紹介するのによく使われます。タートルグラフィックスは Wally Feurzig と Seymore Papert が 1966 年に開発した Logo プログラミング言語の一部でした。

x-y 平面の (0, 0) から動き出すロボット亀を想像してみて下さい。 turtle.forward(15) という命令を出すと、その亀が (スクリーン上で!) 15 ピクセル分顔を向けている方向に動き、動きに沿って線を引きます。 turtle.left(25) という命令を出すと、今度はその場で25度反時計回りに回ります。

Turtle star

Turtle can draw intricate shapes using programs that repeat simple moves.

from turtle import *
color('red', 'yellow')
begin_fill()
while True:
    forward(200)
    left(170)
    if abs(pos()) < 1:
        break
end_fill()
done()

これらの命令と他の同様な命令を組み合わせることで、複雑な形や絵が簡単に描けます。

turtle モジュールは同じ名前を持った Python 2.5 までのモジュールの拡張された再実装です。

再実装に際しては古い turtle モジュールのメリットをそのままに、 (ほぼ) 100% 互換性を保つようにしました。すなわち、まず第一に、学習中のプログラマがモジュールを -n スイッチを付けて走らせている IDLE の中から全てのコマンド、クラス、メソッドを対話的に使えるようにしました。

turtle モジュールはオブジェクト指向と手続き指向の両方の方法でタートルグラフィックス・プリミティブを提供します。グラフィックスの基礎として tkinter を使っているために、Tk をサポートした Python のバージョンが必要です。

オブジェクト指向インターフェイスでは、本質的に 2+2 のクラスを使います:

  1. TurtleScreen クラスはタートルが絵を描きながら走り回る画面を定義します。そのコンストラクタには tkinter.Canvas または ScrolledCanvas を渡す必要があります。 turtle をアプリケーションの一部として用いたい場合にはこれを使うべきです。

    Screen() 関数は TurtleScreen のサブクラスのシングルトンオブジェクトを返します。 turtle をグラフィクスを使う一つの独立したツールとして使う場合には、この関数を呼び出すべきです。シングルトンなので、そのクラスからの継承はできません。

    TurtleScreen/Screen の全てのメソッドは関数としても、すなわち、手続き指向インターフェイスの一部としても存在しています。

  2. RawTurtle (別名: RawPen) は TurtleScreen 上に絵を描く Turtle オブジェクトを定義します。コンストラクタには Canvas, ScrolledCanvas, TurtleScreen のいずれかを引数として渡して RawTurtle オブジェクトがどこに絵を描くかを教えます。

    RawTurtle の派生はサブクラス Turtle (別名: Pen) で、 (既に与えられているのでなければ自動的に作られた) "唯一の" Screen インスタンスに絵を描きます。

    RawTurtle/Turtle の全てのメソッドは関数としても、すなわち、手続き指向インターフェイスの一部としても存在しています。

手続き型インターフェイスでは Screen および Turtle クラスのメソッドを元にした関数を提供しています。その名前は対応するメソッドと一緒です。 Screen のメソッドを元にした関数が呼び出されるといつでも screen オブジェクトが自動的に作られます。 Turtle のメソッドを元にした関数が呼び出されるといつでも(名無しの) turtle オブジェクトが自動的に作られます。

複数のタートルを一つのスクリーン上で使いたい場合、オブジェクト指向インターフェイスを使わなければなりません。

注釈

以下の文書では関数に対する引数リストが与えられています。メソッドでは、勿論、ここでは省略されている self が第一引数になります。

Turtle および Screen のメソッドの概観

Turtle のメソッド

Turtle の動き
移動および描画
forward() | fd()
backward() | bk() | back()
right() | rt()
left() | lt()
goto() | setpos() | setposition()
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()
clear() | clearscreen()
reset() | 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()
Input methods
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.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")
>>> turtle.stamp()
11
>>> 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):
...     turtle.stamp(); turtle.fd(30)
13
14
15
16
17
18
19
20
>>> 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()

Fill the shape drawn after the last call to begin_fill().

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

タートルの形(turtleshape)を現在の傾斜角に関わらず、指定された角度(angle)の向きに回転します。タートルの進む方向は 変わりません 。

>>> 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, 22. 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 を直接使わなければなりません:

  1. タイプ "compound" の空の Shape オブジェクトを作ります。

  2. 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")

  3. こうして作った 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()
turtle.clearscreen()

全ての図形と全てのタートルを TurtleScreen から削除します。そして空になった TurtleScreen をリセットして初期状態に戻します: 白い背景、背景画像もイベント束縛もなく、トレーシングはオンです。

注釈

この TurtleScreen メソッドはグローバル関数としては clearscreen という名前でだけ使えます。グローバル関数 clear は Turtle メソッドの clear から派生した別ものです。

turtle.reset()
turtle.resetscreen()

スクリーン上の全てのタートルをリセットしその初期状態に戻します。

注釈

この TurtleScreen メソッドはグローバル関数としては resetscreen という名前でだけ使えます。グローバル関数 reset は Turtle メソッドの reset から派生した別ものです。

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 -- 非負整数

Turn turtle animation on/off and set delay for update drawings. If n is given, only each n-th regular screen update is really performed. (Can be used to accelerate the drawing of complex graphics.) When called without arguments, returns the currently stored value of n. Second argument sets delay value (see 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()

Input methods

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)

この関数を呼び出す三つの異なる方法があります:

  1. name が gif ファイルの名前で shape が None: 対応する画像の形を取り込みます。

    >>> screen.register_shape("turtle.gif")

    注釈

    画像の形はタートルが向きを変えても 回転しません ので、タートルがどちらを向いているか見ても判りません!

  2. name が任意の文字列で shape が座標ペアのタプル: 対応する多角形を取り込みます。

    >>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))

  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

上で説明した setbg() のようなスクリーン向けのメソッドを提供します。

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) 回転

ヘルプと設定

ヘルプの使い方

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) をお試し下さい。
  • 塗りつぶしの色(fillcolor)を使いたくない(つまりタートルを透明にしたい)場合、 fillcolor = "" と書かなければなりません (しかし全ての空でない文字列は cfg ファイル中で引用符を付けてはいけません)。
  • タートルにその状態を反映させるためには resizemode = auto とします。
  • たとえば language = italian とするとドキュメント文字列辞書(docstringdict) として turtle_docstringdict_italian.py がインポート時に読み込まれます (もしそれがインポートパス、たとえば turtle と同じディレクトリにあれば)。
  • exampleturtle および examplescreen はこれらのオブジェクトのドキュメント文字列内での呼び名を決めます。メソッドのドキュメント文字列から関数のドキュメント文字列に変換する際に、これらの名前は取り除かれます。
  • using_IDLE: IDLE とその -n スイッチ(サブプロセスなし)を常用するならば、この値を True に設定して下さい。これにより exitonclick() がメインループ(mainloop)に入るのを阻止します。

turtle.cfg ファイルは turtle の保存されているディレクトリと現在の作業ディレクトリに追加的に存在し得ます。後者が前者の設定をオーバーライドします。

The Lib/turtledemo directory contains a turtle.cfg file. You can study it as an example and see its effects when running the demos (preferably not from within the demo-viewer).

turtledemo --- デモスクリプト

`turtledemo`パッケージには一連のデモスクリプトが含まれています。これらのスクリプトは以下のように、付属のデモビューアを使用して実行および表示できます:

python -m turtledemo

あるいは、個別にデモスクリプトを実行できます。たとえば 、:

python -m turtledemo.bytedesign

`turtledemo`パッケージのディレクトリには次のものが含まれます:

  • A demo viewer __main__.py which can be used to view the sourcecode of the scripts and run them at the same time.
  • 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
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
wikipedia | タートルグラフィックスについての wikipedia の記事の例 | clone(), undo()
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 methods Turtle.shearfactor(), Turtle.shapetransform() and Turtle.get_shapepoly() have been added. Thus the full range of regular linear transforms is now available for transforming turtle shapes. Turtle.tiltangle() has been enhanced in functionality: it now can be used to get or set the tiltangle. Turtle.settiltangle() has been deprecated.
  • The method Screen.onkeypress() has been added as a complement to Screen.onkey() which in fact binds actions to the keyrelease event. Accordingly the latter has got an alias: Screen.onkeyrelease().
  • The method Screen.mainloop() has been added. So when working only with Screen and Turtle objects one must not additionally import mainloop() anymore.
  • Two input methods has been added Screen.textinput() and Screen.numinput(). These popup 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 --- 行指向のコマンドインタープリタのサポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • プログラムのフレームワーク »

cmd --- 行指向のコマンドインタープリタのサポート

ソースコード: 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' として渡されます。

メソッド do_foo() を持っている場合に限って、インタープリタのインスタンスはコマンド名 foo を認識します。特別な場合として、文字 '?' で始まる行はメソッド do_help() へディスパッチします。他の特別な場合として、文字 '!' で始まる行はメソッド do_shell() へディスパッチします(このようなメソッドが定義されている場合)。

このメソッドは postcmd() メソッドが真を返したときに return します。 postcmd() に対する stop 引数は、このコマンドが対応する do_*() メソッドからの返り値です。

補完が有効になっているなら、コマンドの補完が自動的に行われます。また、コマンド引数の補完は、引数 text, line, begidx, および endidx と共に complete_foo() を呼び出すことによって行われます。 text は、マッチしようとしている文字列の先頭の語です。返されるマッチは全てそれで始まっていなければなりません。 line は始めの空白を除いた現在の入力行です。 begidx と endidx は先頭のテキストの始まりと終わりのインデックスで、引数の位置に依存した異なる補完を提供するのに使えます。

Cmd のすべてのサブクラスは、定義済みの do_help() を継承します。このメソッドは、(引数 'bar' と共に呼ばれたとすると)対応するメソッド help_bar() を呼び出します。そのメソッドが存在しない場合、 do_bar() の docstring があればそれを表示します。引数がなければ、 do_help() は、すべての利用可能なヘルプ見出し(すなわち、対応する help_*() メソッドを持つすべてのコマンドまたは docstring を持つコマンド)をリストアップします。また、文書化されていないコマンドでも、すべてリストアップします。

Cmd.onecmd(str)

プロンプトに答えてタイプしたかのように引数を解釈実行します。これをオーバーライドすることがあるかもしれませんが、通常は必要ないでしょう。便利な実行フックについては、 precmd() と postcmd() メソッドを参照してください。戻り値は、インタープリタによるコマンドの解釈実行をやめるかどうかを示すフラグです。コマンド str に対応する do_*() メソッドがある場合、そのメソッドの返り値が返されます。そうでない場合は default() メソッドからの返り値が返されます。

Cmd.emptyline()

プロンプトに空行が入力されたときに呼び出されるメソッド。このメソッドがオーバーライドされていないなら、最後に入力された空行でないコマンドが繰り返されます。

Cmd.default(line)

コマンドの先頭の語が認識されないときに、入力行に対して呼び出されます。このメソッドがオーバーライドされていないなら、エラーメッセージを表示して戻ります。

Cmd.completedefault(text, line, begidx, endidx)

利用可能なコマンド固有の complete_*() が存在しないときに、入力行を補完するために呼び出されるメソッド。デフォルトでは、空行を返します。

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

ヘルプの出力にその他のヘルプ見出しがある(すなわち、 do_*() メソッドに対応していない help_*() メソッドが存在する)場合に表示するヘッダ。

Cmd.undoc_header

ヘルプ出力に文書化されていないコマンドのセクションがある(すなわち、対応する help_*() メソッドを持たない do_*() メソッドが存在する)場合に表示するヘッダ。

Cmd.ruler

ヘルプメッセージのヘッダの下に、区切り行を表示するために使われる文字。空のときは、ルーラ行が表示されません。デフォルトでは、'=' です。

Cmd.use_rawinput

フラグで、デフォルトでは真です。真ならば、 cmdloop() はプロンプトを表示して次のコマンド読み込むために input() を使います。偽ならば、 sys.stdout.write() と sys.stdin.readline() が使われます。 (これが意味するのは、 readline を import することによって、それをサポートするシステム上では、インタープリタが自動的に Emacs 形式の行編集とコマンド履歴のキーストロークをサポートするということです。)

Cmd の例

cmd モジュールは、ユーザーがプログラムと対話的に連携できるカスタムシェルを構築するのに主に役立ちます。

この節では、turtle モジュールのいくつかのコマンドを持ったシェルの作成方法の簡単な例を示します。

forward() のような基本的な turtle コマンドは Cmd のサブクラスに do_forward() と名付けられたメソッドで追加されます。 引数は数値に変換され、 turtle モジュールに振り分けられます。ドキュメント文字列はシェルによって提供されるヘルプユーティリティで使用されます。

この例には、基本的な記録機能と再実行機能が含まれていて、入力を小文字に変換しコマンドをファイルに書き込む責務を持たせた precmd() メソッドに実装されています。 do_playback() メソッドはファイルを読み込み、そこに記録されているコマンドをすぐに再実行するために cmdqueue に追加します:

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 --- 単純な字句解析

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • プログラムのフレームワーク »

shlex --- 単純な字句解析

ソースコード: Lib/shlex.py

shlex クラスは Unix シェルに似た、単純な構文に対する字句解析器を簡単に書けるようにします。このクラスはしばしば、 Python アプリケーションのための実行制御ファイルのような小規模言語を書く上で便利です。

shlex モジュールは以下の関数を定義しています:

shlex.split(s, comments=False, posix=True)

シェルに似た文法を使って、文字列 s を分割します。 comments が False (デフォルト値) の場合、受理した文字列内のコメントを解析しません (shlex インスタンスの commenters メンバの値を空文字列にします)。この関数はデフォルトでは POSIX モードで動作し、 posix 引数が偽の場合は非 POSIX モードで動作します。

注釈

split() 関数は shlex クラスのインスタンスを利用するので、 s に None を渡すと標準入力から分割する文字列を読み込みます。

shlex.quote(s)

文字列 s をシェルエスケープして返します。戻り値は、リストを使えないようなケースで、シェルコマンドライン内で一つのトークンとして安全に利用出来る文字列です。

This idiom would be unsafe:

>>> filename = 'somefile; rm -rf ~'
>>> command = 'ls -l {}'.format(filename)
>>> print(command)  # executed by a shell: boom!
ls -l somefile; rm -rf ~

quote() lets you plug the security hole:

>>> 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 ~']

バージョン 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.

バージョン 3.6 で変更: The punctuation_chars parameter was added.

参考

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.

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. If this attribute is True, punctuation_chars will have no effect, and splitting will happen only on whitespaces. When using punctuation_chars, which is intended to provide parsing closer to that implemented by shells, it is advisable to leave whitespace_split as False (the default value).

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

Characters that will be considered punctuation. Runs of punctuation characters will be returned as a single token. However, note that no semantic validity checking will be performed: for example, '>>>' could be returned as a token, even though it may not be recognised as such by shells.

バージョン 3.6 で追加.

解析規則

非 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

バージョン 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\")"
 >>> list(shlex.shlex(text))
 ['a', '&', '&', 'b', ';', 'c', '&', '&', 'd', '|', '|', 'e', ';', 'f', '>',
 "'abc'", ';', '(', 'def', '"ghi"', ')']
 >>> list(shlex.shlex(text, punctuation_chars=True))
 ['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?']

For best effect, punctuation_chars should be set in conjunction with posix=True. (Note that posix=False is the default for shlex.)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • プログラムのフレームワーク »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

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

Tk/Tcl は長きにわたり Python の不可欠な一部でありつづけています。Tk/Tcl は頑健でプラットホームに依存しないウィンドウ構築ツールキットであり、Python プログラマは tkinter パッケージやその拡張の tkinter.tix および tkinter.ttk モジュールを使って利用できます。

tkinter パッケージは Tcl/Tk 上に作られた軽量なオブジェクト指向のレイヤです。 tkinter を使うために Tcl コードを書く必要はありませんが、Tk のドキュメントや、場合によっては Tcl のドキュメントを調べる必要があるでしょう。tkinter は Tk のウィジェットを Python のクラスとして実装しているラッパをまとめたものです。加えて、内部モジュール _tkinter は、Python と Tcl とがやり取りできるスレッドセーフなメカニズムを提供しています。

tkinter の一番素晴らしい点は、速く、そしてほとんどの Python に付属していることです。標準ドキュメントが頼りないものだとしても、代わりとなる、リファレンス、チュートリアル、書籍その他が入手可能です。tkinter は古臭いルックアンドフィールでも有名ですが、その点は Tk 8.5 で大きく改善されました。とはいえ、他にも興味を引きそうな GUI ライブラリは多数あります。それらについてのより詳しい情報は 他のグラフィカルユーザインタフェースパッケージ 節を参照してください。

  • tkinter --- Tcl/Tk の Python インタフェース
    • Tkinter モジュール
    • Tkinter お助け手帳
      • この節の使い方
      • 簡単な Hello World プログラム
    • Tcl/Tk を (本当に少しだけ) 見渡してみる
    • 基本的な Tk プログラムと Tkinter との対応関係
    • Tk と Tkinter はどのように関わっているのか
    • 簡単なリファレンス
      • オプションの設定
      • Packer
      • Packer のオプション
      • ウィジェット変数を関連付ける
      • ウィンドウマネージャ
      • Tk オプションデータ型
      • バインドとイベント
      • index パラメータ
      • 画像
    • ファイルハンドラ
  • tkinter.ttk --- Tk のテーマ付きウィジェット
    • Ttk を使う
    • Ttk ウィジェット
    • ウィジェット
      • 標準オプション
      • スクロール可能ウィジェットのオプション
      • ラベルオプション
      • 互換性オプション
      • ウィジェットの状態
      • ttk.Widget
    • コンボボックス
      • オプション
      • 仮想イベント
      • ttk.Combobox
    • Spinbox
      • オプション
      • 仮想イベント
      • ttk.Spinbox
    • ノートブック
      • オプション
      • タブオプション
      • タブ識別子
      • 仮想イベント
      • ttk.Notebook
    • プログレスバー
      • オプション
      • ttk.Progressbar
    • セパレータ
      • オプション
    • サイズグリップ
      • プラットフォーム固有のメモ
      • バグ
    • ツリービュー
      • オプション
      • 要素オプション
      • タグオプション
      • カラム識別子
      • 仮想イベント
      • ttk.Treeview
    • Ttk スタイル
      • レイアウト
  • tkinter.tix --- Tkの拡張ウィジェット
    • Tixを使う
    • Tixウィジェット
      • 基本ウィジェット
      • ファイルセレクタ
      • 階層的リストボックス
      • 表的リストボックス
      • 管理ウィジェット
      • 画像タイプ
      • その他のウィジェット
      • ジオメトリマネジャを作る
    • Tixコマンド
  • tkinter.scrolledtext --- スクロールするテキストウィジェット
  • 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 ウィンドウ)
      • コンテキストメニュー
    • 編集とナビゲーション
      • Editor windows
      • Key bindings
      • 自動的な字下げ
      • 補完 (Completions)
      • 呼び出しヒント (Calltips)
      • Python Shell ウィンドウ
      • テキストの色
    • スタートアップとコードの実行
      • コマンドラインの使い方
      • Startup failure
      • Running user code
      • User output in Shell
      • Developing tkinter applications
      • サブプロセスを起こさずに起動する
    • ヘルプとお好み設定
      • Help sources
      • Setting preferences [お好み設定]
      • IDLE on macOS
      • Extensions [拡張]
  • 他のグラフィカルユーザインタフェースパッケージ

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Tk を用いたグラフィカルユーザインターフェイス »

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

ソースコード: Lib/tkinter/tix.py

バージョン 3.6 で非推奨: この Tk 拡張は保守されておらず、新しいコードでは使うべきではありません。 その代わりに tkinter.ttk を使ってください。

tkinter.tix (Tk Interface Extension) モジュールは豊富な追加ウィジェットを提供します。標準 Tk ライブラリには多くの有用なウィジェットがありますが、決して完全ではありません。 tkinter.tix ライブラリは、HList 、 ComboBox 、 Control (別名SpinBox) および各種のスクロール可能なウィジェットなど、標準 Tk にはないが、一般的に必要とされるウィジェットの大部分を提供します。 tkinter.tix には、class:NoteBook 、 FileEntry 、 PanedWindow など、一般的に幅広い用途に役に立つたくさんのウィジェットも含まれています。それらは40以上あります。

これら多くの新しいウィジェットと使うと、より便利でより直感的なユーザインタフェースを作成し、新しい相互作用テクニックをアプリケーションに導入することができます。アプリケーションとユーザに特有の要求に合うように、最も適切なアプリケーションウィジェットを選んでアプリケーションを設計できます。

参考

Tix Homepage
Tix のホームページ。ここには追加ドキュメントとダウンロードへのリンクがあります。
Tix Man Pages
manページと参考資料のオンライン版。
Tix Programming Guide
プログラマ用参考資料のオンライン版。
Tix Development Applications
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')

If this fails, you have a Tk installation problem which must be resolved before proceeding. Use the environment variable TIX_LIBRARY to point to the installed Tix library directory, and make sure you have the dynamic object library (tix8183.dll or libtix8183.so) in the same directory that contains your Tk dynamic object library (tk8183.dll or libtk8183.so). The directory with the dynamic object library should also have a file called pkgIndex.tcl (case sensitive), which contains the line:

package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]

Tixウィジェット

Tix は40個以上のウィジェットクラスを tkinter のレパートリーに導入します。

基本ウィジェット

class tkinter.tix.Balloon

ヘルプを提示するためにウィジェット上にポップアップする Balloon。ユーザがカーソルをBalloonウィジェットが束縛されているウィジェット内部へ移動させたとき、説明のメッセージが付いた小さなポップアップウィンドウがスクリーン上に表示されます。

class tkinter.tix.ButtonBox

ButtonBox ウィジェットは、Ok Cancel のためだけに普通は使われるようなボタンボックスを作成します。

class tkinter.tix.ComboBox

ComboBox ウィジェットはMS Windowsのコンボボックスコントロールに似ています。ユーザはエントリ・サブウィジェットでタイプするか、リストボックス・サブウィジェットから選択するかのどちらかで選択肢を選びます。

class tkinter.tix.Control

Control ウィジェットは SpinBox ウィジェットとしても知られています。ユーザは二つの矢印ボタンを押すか、またはエントリに直接値を入力して値を調整します。新しい値をユーザが定義した上限と下限に対してチェックします。

class tkinter.tix.LabelEntry

LabelEntry ウィジェットはエントリウィジェットとラベルを一つのメガウィジェットにまとめたものです。"記入形式"型のインタフェースの作成を簡単に行うために使うことができます。

class tkinter.tix.LabelFrame

LabelFrame ウィジェットはフレームウィジェットとラベルを一つのメガウィジェットにまとめたものです。LabelFrameウィジェット内部にウィジェットを作成するためには、 frame サブウィジェットに対して新しいウィジェットを作成し、それらを frame サブウィジェット内部で取り扱います。

class tkinter.tix.Meter

Meter ウィジェットは実行に時間のかかるバックグラウンド・ジョブの進み具合を表示するために使用できます。

class tkinter.tix.OptionMenu

OptionMenu はオプションのメニューボタンを作成します。

class tkinter.tix.PopupMenu

PopupMenu ウィジェットは tk_popup コマンドの代替品として使用できます。 Tix PopupMenu ウィジェットの利点は、操作に必要なアプリケーション・コードが少ないことです。

class tkinter.tix.Select

Select ウィジェットはボタン・サブウィジェットのコンテナです。ユーザに対する選択オプションのラジオボックスまたはチェックボックス形式を提供するために利用することができます。

class tkinter.tix.StdButtonBox

StdButtonBox ウィジェットは、Motif に似たダイアログボックスのための標準的なボタンのグループです。

ファイルセレクタ

class tkinter.tix.DirList

DirList ウィジェットは、ディレクトリのリストビュー (上の階層のディレクトリとサブディレクトリ) を表示します。ユーザはリスト内に表示されたディレクトリの一つを選択したり、他のディレクトリへ変更したりできます。

class tkinter.tix.DirTree

DirTree ウィジェットはディレクトリのツリービュー (上の階層のディレクトリとそのサブディレクトリ) を表示します。ユーザはリスト内に表示されたディレクトリの一つを選択したり、他のディレクトリへ変更したりできます。

class tkinter.tix.DirSelectDialog

DirSelectDialog ウィジェットは、ダイアログウィンドウにファイルシステム内のディレクトリを提示します。ユーザはこのダイアログウィンドウを使用して、ファイルシステム内を移動して目的のディレクトリを選択することができます。

class tkinter.tix.DirSelectBox

DirSelectBox は標準 Motif(TM) ディレクトリ選択ボックスに似ています。ユーザがディレクトリを選択するために一般的に使われます。DirSelectBox は主に最近 ComboBox ウィジェットに選択されたディレクトリを保存し、すばやく再選択できるようにします。

class tkinter.tix.ExFileSelectBox

ExFileSelectBox ウィジェットは、たいてい tixExFileSelectDialog ウィジェット内に組み込まれます。ユーザがファイルを選択するのに便利なメソッドを提供します。 ExFileSelectBox ウィジェットのスタイルは、MS Windows 3.1 の標準ファイルダイアログにとてもよく似ています。

class tkinter.tix.FileSelectBox

FileSelectBox は標準的な Motif(TM) ファイル選択ボックスに似ています。通常、ユーザがファイルを選択するために使われます。FileSelectBox は、直近に ComboBox ウィジェットに選択されたファイルを保存し、素早く再選択できるようにします。

class tkinter.tix.FileEntry

FileEntry ウィジェットは、ファイル名を入力するために使うことができます。ユーザはファイル名を手入力できます。その代わりに、エントリの横に並んでいるボタンウィジェットを押すと表示されるファイル選択ダイアログを使用することもできます。

階層的リストボックス

class tkinter.tix.HList

HList ウィジェットは階層構造をもつどんなデータ(例えば、ファイルシステムディレクトリツリー)でも表示するために使用できます。リストエントリは字下げされ、階層のそれぞれの場所に応じて分岐線で接続されます。

class tkinter.tix.CheckList

CheckList ウィジェットは、ユーザが選ぶ項目のリストを表示します。CheckList は Tk のチェックリストやラジオボタンより多くの項目を扱うことができることを除いて、チェックボタンあるいはラジオボタンウィジェットと同じように動作します。

class tkinter.tix.Tree

Tree ウィジェットは階層的なデータをツリー形式で表示するために使うことができます。ユーザはツリーの一部を開いたり閉じたりすることによって、ツリーの見えを調整できます。

表的リストボックス

class tkinter.tix.TList

TList ウィジェットは、表形式でデータを表示するために使うことができます。 TList ウィジェットのリスト・エントリは、Tkのリストボックス・ウィジェットのエントリに似ています。主な差は、(1) TList ウィジェットはリスト・エントリを二次元形式で表示でき、(2) リスト・エントリに対して複数の色やフォントだけでなく画像も使うことができるということです。

管理ウィジェット

class tkinter.tix.PanedWindow

PanedWindow ウィジェットは、ユーザがいくつかのペインのサイズを対話的に操作できるようにします。ペインは垂直または水平のどちらかに配置されます。ユーザは二つのペインの間でリサイズ・ハンドルをドラッグしてペインの大きさを変更します。

class tkinter.tix.ListNoteBook

ListNoteBook ウィジェットは、 TixNoteBook ウィジェットにとてもよく似ています。ノートのメタファを使って限られた空間をに多くのウィンドウを表示するために使われます。ノートはたくさんのページ(ウィンドウ)に分けられています。ある時には、これらのページの一つしか表示できません。ユーザは hlist サブウィジェットの中の望みのページの名前を選択することによって、これらのページを切り替えることができます。

class tkinter.tix.NoteBook

NoteBook ウィジェットは、ノートのメタファを多くのウィンドウを表示することができます。ノートはたくさんのページに分けられています。ある時には、これらのページの一つしか表示できません。ユーザは NoteBook ウィジェットの一番上にある目に見える"タブ"を選択することで、これらのページを切り替えることができます。

画像タイプ

tkinter.tix モジュールは次のものを追加します:

  • 全ての tkinter.tix と tkinter ウィジェットに対して XPM ファイルからカラー画像を作成する pixmap 機能。
  • Compound 画像タイプは複数の水平方向の線から構成される画像を作成するために使うことができます。それぞれの線は左から右に並べられた一連のアイテム(テキスト、ビットマップ、画像あるいは空白)から作られます。例えば、Tk のButton ウィジェットの中にビットマップとテキスト文字列を同時に表示するためにcompound画像は使うことができます。

その他のウィジェット

class tkinter.tix.InputOnly

InputOnly ウィジェットは、ユーザから入力を受け付けます。それは、bind コマンドを使って行われます(Unixのみ)。

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

加えて、 tkinter.tix は次のものを提供することで tkinter を補強します:

class tkinter.tix.Form

すべての Tk ウィジェットに対する接続ルールに基づいた Form ジオメトリマネジャ。

Tixコマンド

class tkinter.tix.tixCommand

tixコマンド は 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() メソッドを代わりに使わなければならないのです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Tk を用いたグラフィカルユーザインターフェイス »


tkinter.scrolledtext --- スクロールするテキストウィジェット

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Tk を用いたグラフィカルユーザインターフェイス »

tkinter.scrolledtext --- スクロールするテキストウィジェット

ソースコード: Lib/tkinter/scrolledtext.py

tkinter.scrolledtext モジュールは"正しい動作"をするように設定された垂直スクロールバーをもつ基本的なテキストウィジェットを実装する同じ名前のクラスを提供します。 ScrolledText クラスを使うことは、テキストウィジェットとスクロールバーを直接設定するより簡単です。コンストラクタは tkinter.Text クラスのものを同じです。

テキストウィジェットとスクロールバーは Frame の中に一緒にpackされ、 Grid と Pack ジオメトリマネジャのメソッドはFrame オブジェクトから得られます。これによって、もっとも標準的なジオメトリマネジャの振る舞いにするために、直接 ScrolledText ウィジェットを使えるようになります。

特定の制御が必要ならば、以下の属性が利用できます:

ScrolledText.frame

テキストとスクロールバーウィジェットを取り囲むフレーム。

ScrolledText.vbar

スクロールバーウィジェット。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Tk を用いたグラフィカルユーザインターフェイス »


他のグラフィカルユーザインタフェースパッケージ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Tk を用いたグラフィカルユーザインターフェイス »

他のグラフィカルユーザインタフェースパッケージ

主要なクロスプラットフォーム (Windows, Mac OS X, Unix 系) GUI ツールキットで Python でも使えるものは:

参考

PyGObject
PyGObject provides introspection bindings for C libraries using GObject. One of these libraries is the GTK+ 3 widget set. GTK+ comes with many more widgets than Tkinter provides. An online Python GTK+ 3 Tutorial is available.
PyGTK
PyGTK はより古いバージョンであるライブラリ GTK+ 2 に対するバインディングを提供しています。 それは C での実装よりはやや高級なオブジェクト指向インターフェイスを提供しています。 GNOME へのバインディングもあります。 オンラインで利用できる チュートリアル があります。
PyQt
PyQtは sip でラップされた Qt ツールキットへのバインディングです。 Qt は Unix、Windows および Mac OS X で利用できる大規模な C++ GUI ツールキットです。 sip は C++ ライブラリに対するバインディングを Python クラスとして生成するためのツールで、Python 用に特化して設計されています。
PySide
PySide は Qt ツールキットへのより新しいバインディングで、 Nokia によって提供されています。 PyQt と比較して、非オープンソースのアプリケーションでより扱いやすいライセンス形態になっています。
wxPython
wxPython はクロスプラットフォームの Python 用 GUI ツールキットで、人気のある wxWidgets (旧名 wxWindows) C++ ツールキットに基づいて作られています。 このツールキットは Windows, Mac OS X および Unix システムのアプリケーションに、それぞれのプラットフォームのネイティブなウィジェットを可能ならば利用して (Unix 系のシステムでは GTK+)、ネイティブなルック＆フィールを提供します。 多彩なウィジェットの他に、オンラインドキュメントや場面に応じたヘルプ、印刷、HTML 表示、低級デバイスコンテキスト描画、ドラッグ＆ドロップ、システムクリップボードへのアクセス、XML に基づいたリソースフォーマット、さらにユーザ寄贈のモジュールからなる成長し続けているライブラリ等々を wxPython は提供しています。

PyGTK、PyQt および wxPython は全て現代的なルック＆フィールをそなえ、 Tkinter より豊富なウィジェットを持ちます。これらに加えて、他にも Python 用 GUI ツールキットが、クロスプラットフォームのもの、プラットフォーム固有のものを含め、沢山あります。Python Wiki の GUI Programming ページも参照してください。もっとずっと完全なリストや、GUI ツールキット同士の比較をしたドキュメントへのリンクがあります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Tk を用いたグラフィカルユーザインターフェイス »


開発ツール

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

開発ツール

この章で紹介されるモジュールはソフトウェアを書くことを支援します。たとえば、 pydoc モジュールはモジュールの内容からドキュメントを生成します。 doctest と unittest モジュールでは、自動的に実行して予想通りの出力が生成されるか確認するユニットテストを書くことができます。 2to3 は Python2.x 用のソースコードを正当な Python 3.x コードに翻訳できます。

この章で解説されるモジュールのリスト:

  • typing --- 型ヒントのサポート
    • 型エイリアス
    • NewType
    • 呼び出し可能オブジェクト
    • ジェネリクス
    • ユーザー定義のジェネリック型
    • Any 型
    • クラス、関数、およびデコレータ
  • pydoc --- ドキュメント生成とオンラインヘルプシステム
  • doctest --- 対話的な実行例をテストする
    • 簡単な利用法: docstring 中の実行例をチェックする
    • 簡単な利用法: テキストファイル中の実行例をチェックする
    • doctest のからくり
      • どの docstring が検証されるのか?
      • docstring 内の実行例をどのように認識するのか?
      • 実行コンテキストとは何か?
      • 例外はどう扱えばよいか?
      • オプションフラグ
      • ディレクティブ (Directives)
      • 警告
    • 基本 API
    • 単体テスト API
    • 拡張 API
      • DocTest オブジェクト
      • Example オブジェクト
      • DocTestFinder オブジェクト
      • DocTestParser オブジェクト
      • DocTestRunner オブジェクト
      • OutputChecker オブジェクト
    • デバッグ
    • アドバイス
  • unittest --- ユニットテストフレームワーク
    • 基本的な例
    • コマンドラインインターフェイス
      • コマンドラインオプション
    • テストディスカバリ
    • テストコードの構成
    • 既存テストコードの再利用
    • テストのスキップと予期された失敗
    • サブテストを利用して繰り返しテストの区別を付ける
    • クラスと関数
      • テストクラス
        • 非推奨のエイリアス
      • テストのグループ化
      • テストのロードと起動
        • load_tests プロトコル
    • クラスとモジュールのフィクスチャ
      • setUpClass と tearDownClass
      • setUpModule と tearDownModule
    • シグナルハンドリング
  • unittest.mock --- モックオブジェクトライブラリ
    • クイックガイド
    • Mock クラス
      • 呼び出し
      • 属性の削除
      • Mock の名前と name 属性
      • 属性として設定されるモック
    • patcher
      • patch
      • patch.object
      • patch.dict
      • patch.multiple
      • patch のメソッド: start と stop
      • ビルトインをパッチする
      • TEST_PREFIX
      • patch デコレータをネストする
      • どこにパッチするか
      • デスクリプタやプロキシオブジェクトにパッチする
    • MagicMock と magic method のサポート
      • magick method をモックする
      • Magic Mock
    • ヘルパー
      • sentinel
      • DEFAULT
      • call
      • create_autospec
      • ANY
      • FILTER_DIR
      • mock_open
      • autospec を使う
      • Sealing mocks
  • unittest.mock --- 入門
    • Mock を使う
      • Mock のパッチ用メソッド
      • オブジェクトのメソッド呼び出しに対するモック
      • クラスをモックする
      • モックに名前をつける
      • 全ての呼び出しのトラッキング
      • 戻り値や属性を設定する
      • モックから例外を発生させる
      • side_effect の関数と iterable
      • 既存のオブジェクトから Mock を作る
    • patch デコレータ
    • さらなる例
      • chained call をモックする
      • 部分的なモック
      • ジェネレータ method をモックする
      • 同じパッチを全てのメソッドに適用する
      • Mocking Unbound Methods
      • モックで複数回の呼び出しをチェックする
      • ミュータブルな引数に対処する
      • 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 --- Python 用回帰テストパッケージ
    • test パッケージのためのユニットテストを書く
    • コマンドラインインタフェースを利用してテストを実行する
  • test.support --- テストのためのユーティリティ関数
  • test.support.script_helper --- Utilities for the Python execution tests

See also the Python development mode: the -X dev option and PYTHONDEVMODE environment variable.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 開発ツール »

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

バージョン 3.5 で追加.

ソースコード: Lib/typing.py

注釈

typing モジュールは 暫定的に 標準ライブラリに追加されました。マイナーリリースの間でもコアデベロッパーが必要だと判断した場合は、新機能の追加や API の変更がなされることがあります。

このモジュールは PEP 484 と PEP 526 によって規定された型ヒントをサポートします。最も基本的なサポートとして Any、 Union、 Tuple、 Callable、 TypeVar および Generic 型を含みます。完全な仕様は PEP 484 を参照してください。型ヒントの簡単な導入は PEP 483 を参照してください。

以下の関数は文字列を受け取って文字列を返す関数で、次のようにアノテーションがつけられます:

def greeting(name: str) -> str:
    return 'Hello ' + name

関数 greeting で、実引数 name の型は str であり、返り値の型は str であることが期待されます。サブタイプも実引数として許容されます。

型エイリアス

型エイリアスは型をエイリアスに代入することで定義されます。この例では Vector と List[float] は交換可能な同義語として扱われます。

from typing import List
Vector = List[float]

def scale(scalar: float, vector: Vector) -> Vector:
    return [scalar * num for num in vector]

# typechecks; a list of floats qualifies as a Vector.
new_vector = scale(2.0, [1.0, -4.2, 5.4])

型エイリアスは複雑な型シグネチャを単純化するのに有用です。例えば:

from typing import Dict, Tuple, List

ConnectionOptions = Dict[str, str]
Address = Tuple[str, int]
Server = Tuple[Address, ConnectionOptions]

def broadcast_message(message: str, servers: List[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: List[Tuple[Tuple[str, int], Dict[str, str]]]) -> None:
    ...

型ヒントとしての None は特別なケースであり、 type(None) によって置き換えられます。

NewType

異なる型を作るためには NewType() ヘルパー関数を使います:

from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)

静的型検査器は新しい型を元々の型のサブクラスのように扱います。この振る舞いは論理的な誤りを見つける手助けとして役に立ちます。

def get_user_name(user_id: UserId) -> str:
    ...

# typechecks
user_a = get_user_name(UserId(42351))

# does not typecheck; 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 関数を作ります。つまり Derived(some_value) という式は新しいクラスを作ることはなく、通常の関数呼び出し以上のオーバーヘッドがないということを意味します。

より正確に言うと、式 some_value is Derived(some_value) は実行時に常に真を返します。

これは Derived のサブタイプを作ることが出来ないということも意味しています。 Derived は実行時には恒等関数になっていて、実際の型ではないからです:

from typing import NewType

UserId = NewType('UserId', int)

# Fails at runtime and does not typecheck
class AdminUserId(UserId): pass

しかし、 'derived' である NewType をもとにした NewType() は作ることが出来ます:

from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

そして ProUserId に対する型検査は期待通りに動作します。

より詳しくは PEP 484 を参照をしてください。

注釈

型エイリアスの使用は二つの型が互いに 等価 だと宣言している、ということを思い出してください。 Alias = Original とすると、静的型検査器は Alias をすべての場合において Original と 完全に等価 なものとして扱います。これは複雑な型シグネチャを単純化したい時に有用です。

これに対し、 NewType はある型をもう一方の型の サブタイプ として宣言します。 Derived = NewType('Derived', Original) とすると静的型検査器は Derived を Original の サブクラス として扱います。つまり Original 型の値は Derived 型の値が期待される場所で使うことが出来ないということです。これは論理的な誤りを最小の実行時のコストで防ぎたい時に有用です。

バージョン 3.5.2 で追加.

呼び出し可能オブジェクト

特定のシグネチャを持つコールバック関数を要求されるフレームワークでは、 Callable[[Arg1Type, Arg2Type], ReturnType] を使って型ヒントを付けます。

例えば:

from typing import Callable

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

型ヒントの実引数の型を ellipsis で置き換えることで呼び出しシグニチャを指定せずに callable の戻り値の型を宣言することができます: Callable[..., ReturnType]。

ジェネリクス

コンテナ内のオブジェクトについての型情報は一般的な方法では静的に推論できないため、抽象基底クラスを継承したクラスが実装され、期待されるコンテナの要素の型を示すために添字表記をサポートするようになりました。

from typing import Mapping, Sequence

def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...

ジェネリクスは、 typing にある TypeVar と呼ばれる新しいファクトリを使ってパラメータ化することができます。

from typing import Sequence, TypeVar

T = TypeVar('T')      # Declare type variable

def first(l: Sequence[T]) -> T:   # Generic function
    return l[0]

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

ユーザー定義のクラスを、ジェネリッククラスとして定義できます。

from typing import TypeVar, Generic
from logging import Logger

T = TypeVar('T')

class LoggedVar(Generic[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)

Generic[T] を基底クラスにすることで、 LoggedVar クラスが 1 つの型引数 T をとる、と定義できます。 この定義により、クラスの本体の中でも T が型として有効になります。

基底クラス Generic は LoggedVar[t] が型として有効になるように __getitem__() を定義したメタクラスを使います。

from typing import Iterable

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
    for var in vars:
        var.set(0)

ジェネリック型は任意の数の型変数をとれます、また型変数に制約をつけられます:

from typing import TypeVar, Generic
...

T = TypeVar('T')
S = TypeVar('S', int, str)

class StrangePair(Generic[T, S]):
    ...

Generic の引数のそれぞれの型変数は別のものでなければなりません。このため次のクラス定義は無効です:

from typing import TypeVar, Generic
...

T = TypeVar('T')

class Pair(Generic[T, T]):   # INVALID
    ...

Generic を用いて多重継承が可能です:

from typing import TypeVar, Generic, Sized

T = TypeVar('T')

class LinkedList(Sized, Generic[T]):
    ...

ジェネリッククラスを継承するとき、いくつかの型変数を固定することが出来ます:

from typing import TypeVar, Mapping

T = TypeVar('T')

class MyDict(Mapping[str, T]):
    ...

この場合では MyDict は仮引数 T を 1 つとります。

型引数を指定せずにジェネリッククラスを使う場合、それぞれの型引数に Any を与えられたものとして扱います。 次の例では、MyIterable はジェネリックではありませんが Iterable[Any] を暗黙的に継承しています:

from typing import Iterable

class MyIterable(Iterable): # Same as Iterable[Any]

ユーザ定義のジェネリック型エイリアスもサポートされています。例:

from typing import TypeVar, Iterable, Tuple, Union
S = TypeVar('S')
Response = Union[Iterable[S], int]

# Return type here is same as Union[Iterable[str], int]
def response(query: str) -> Response[str]:
    ...

T = TypeVar('T', int, float, complex)
Vec = Iterable[Tuple[T, T]]

def inproduct(v: Vec[T]) -> T: # Same as Iterable[Tuple[T, T]]
    return sum(x*y for x, y in v)

Generic に用いられているメタクラスは abc.ABCMeta のサブクラスです。 ジェネリッククラスは抽象メソッドや抽象プロパティを持つことで抽象基底クラスになれ、ジェネリッククラスはメタクラスの衝突を起こすことなく基底クラスに抽象基底クラスをとれます。 ジェネリックメタクラスはサポートされていません。 パラメータ化を行うジェネリクスの結果はキャッシュされていて、 typing モジュールのほとんどの型はハッシュ化でき、等価比較できます。

Any 型

Any は特別な種類の型です。静的型検査器はすべての型を Any と互換として扱い、 Any をすべての型と互換として扱います。

つまり、 Any 型の値に対し任意の演算やメソッド呼び出しができ、任意の変数に代入できるということです。

from typing import Any

a = None    # type: Any
a = []      # OK
a = 2       # OK

s = ''      # type: str
s = a       # OK

def foo(item: Any) -> int:
    # Typechecks; '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; an object does not have a 'magic' method.
    item.magic()
    ...

def hash_b(item: Any) -> int:
    # Typechecks
    item.magic()
    ...

# Typechecks, since ints and strs are subclasses of object
hash_a(42)
hash_a("foo")

# Typechecks, since Any is compatible with all types
hash_b(42)
hash_b("foo")

object は、ある値が型安全な方法で任意の型として使えることを示すために使用します。 Any はある値が動的に型付けられることを示すために使用します。

クラス、関数、およびデコレータ

このモジュールでは以下のクラス、関数とデコレータを定義します:

class typing.TypeVar

型変数です。

使い方:

T = TypeVar('T')  # Can be anything
A = TypeVar('A', str, bytes)  # Must be str or bytes

型変数は主として静的型検査器のために存在します。型変数はジェネリック型やジェネリック関数の定義の引数として役に立ちます。ジェネリック型についての詳細は Generic クラスを参照してください。ジェネリック関数は以下のように動作します:

def repeat(x: T, n: int) -> Sequence[T]:
    """Return a list containing n references to x."""
    return [x]*n

def longest(x: A, y: A) -> A:
    """Return the longest of two strings."""
    return x if len(x) >= len(y) else y

後者の例のシグネチャは本質的に (str, str) -> str と (bytes, bytes) -> bytes のオーバーロードです。もし引数が str のサブクラスのインスタンスの場合、返り値は普通の str であることに注意して下さい。

実行時に、isinstance(x, T) は TypeError を送出するでしょう。一般的に、isinstance() と issubclass() は型に対して使用するべきではありません。

型変数は covariant=True または contravariant=True を渡すことによって共変または反変であることを示せます。詳細は PEP 484 を参照して下さい。デフォルトの型変数は不変です。あるいは、型変数は bound=<type> を使うことで上界を指定することが出来ます。これは、型変数に (明示的または非明示的に) 代入された実際の型が境界の型のサブクラスでなければならないということを意味します、 PEP 484 も参照。

class typing.Generic

ジェネリック型のための抽象基底クラスです。

ジェネリック型は典型的にはこのクラスを1つ以上の型変数によってインスタンス化したものを継承することによって宣言されます。例えば、ジェネリックマップ型は次のように定義することが出来ます:

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.

このクラスは次のように使用することが出来ます:

X = TypeVar('X')
Y = TypeVar('Y')

def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:
    try:
        return mapping[key]
    except KeyError:
        return default
class typing.Type(Generic[CT_co])

C と注釈が付けされた変数は C 型の値を受理します。一方で Type[C] と注釈が付けられた変数は、そのクラス自身を受理します -- 具体的には、それは C の クラスオブジェクト を受理します。例:

a = 3         # Has type 'int'
b = int       # Has type 'Type[int]'
c = type(a)   # Also has type 'Type[int]'

Type[C] は共変であることに注意してください:

class User: ...
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...

# Accepts User, BasicUser, ProUser, TeamUser, ...
def make_new_user(user_class: Type[User]) -> User:
    # ...
    return user_class()

Type[C] が共変だということは、 C の全てのサブクラスは、 C と同じシグネチャのコンストラクタとクラスメソッドを実装すべきだということになります。 型チェッカーはこの規則への違反に印を付けるべきですが、サブクラスでのコンストラクタ呼び出しで、指定された基底クラスのコンストラクタ呼び出しに適合するものは許可すべきです。 この特別な場合を型チェッカーがどう扱うべきかについては、 PEP 484 の将来のバージョンで変更されるかもしれません。

Type で許されているパラメータは、クラス、 Any 、 型変数 あるいは、それらの直和型だけです。 例えば次のようになります:

def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...

Type[Any] は Type と等価で、同様に Type は type と等価です。type は Python のメタクラス階層のルートです。

バージョン 3.5.2 で追加.

class typing.Iterable(Generic[T_co])

collections.abc.Iterable のジェネリック版です。

class typing.Iterator(Iterable[T_co])

collections.abc.Iterator のジェネリック版です。

class typing.Reversible(Iterable[T_co])

collections.abc.Reversible のジェネリック版です。

class typing.SupportsInt

抽象メソッド __int__ を備えた ABC です。

class typing.SupportsFloat

抽象メソッド __float__ を備えた ABC です。

class typing.SupportsComplex

抽象メソッド __complex__ を備えた ABC です。

class typing.SupportsBytes

抽象メソッド __bytes__ を備えた ABC です。

class typing.SupportsAbs

返り値の型と共変な抽象メソッド __abs__ を備えた ABC です。

class typing.SupportsRound

返り値の型と共変な抽象メソッド __round__ を備えた ABC です。

class typing.Container(Generic[T_co])

collections.abc.Container のジェネリック版です。

class typing.Hashable

collections.abc.Hashable へのエイリアス

class typing.Sized

collections.abc.Sized へのエイリアス

class typing.Collection(Sized, Iterable[T_co], Container[T_co])

collections.abc.Collection のジェネリック版です。

バージョン 3.6 で追加.

class typing.AbstractSet(Sized, Collection[T_co])

collections.abc.Set のジェネリック版です。

class typing.MutableSet(AbstractSet[T])

collections.abc.MutableSet のジェネリック版です。

class typing.Mapping(Sized, Collection[KT], Generic[VT_co])

A generic version of collections.abc.Mapping.

class typing.MutableMapping(Mapping[KT, VT])

collections.abc.MutableMapping のジェネリック版です。

class typing.Sequence(Reversible[T_co], Collection[T_co])

collections.abc.Sequence のジェネリック版です。

class typing.MutableSequence(Sequence[T])

collections.abc.MutableSequence のジェネリック版です。

class typing.ByteString(Sequence[int])

collections.abc.ByteString のジェネリック版です。

この型は bytes と bytearray 、 memoryview を表します。

この型の省略形として、 bytes を上に挙げた任意の型の引数にアノテーションをつけることに使えます。

class typing.Deque(deque, MutableSequence[T])

collections.deque のジェネリック版です。

バージョン 3.6.1 で追加.

class typing.List(list, MutableSequence[T])

Generic version of list. Useful for annotating return types. To annotate arguments it is preferred to use abstract collection types such as Mapping, Sequence, or AbstractSet.

この型は次のように使えます:

T = TypeVar('T', int, float)

def vec2(x: T, y: T) -> List[T]:
    return [x, y]

def keep_positives(vector: Sequence[T]) -> List[T]:
    return [item for item in vector if item > 0]
class typing.Set(set, MutableSet[T])

A generic version of builtins.set.

class typing.FrozenSet(frozenset, AbstractSet[T_co])

builtins.frozenset のジェネリック版です。

class typing.MappingView(Sized, Iterable[T_co])

collections.abc.MappingView のジェネリック版です。

class typing.KeysView(MappingView[KT_co], AbstractSet[KT_co])

collections.abc.KeysView のジェネリック版です。

class typing.ItemsView(MappingView, Generic[KT_co, VT_co])

collections.abc.ItemsView のジェネリック版です。

class typing.ValuesView(MappingView[VT_co])

collections.abc.ValuesView のジェネリック版です。

class typing.Awaitable(Generic[T_co])

collections.abc.Awaitable のジェネリック版です。

class typing.Coroutine(Awaitable[V_co], Generic[T_co T_contra, V_co])

collections.abc.Coroutine のジェネリック版です。 変性と型変数の順序は Generator のものと対応しています。例えば次のようになります:

from typing import List, Coroutine
c = None # type: Coroutine[List[str], str, int]
...
x = c.send('hi') # type: List[str]
async def bar() -> None:
    x = await c # type: int
class typing.AsyncIterable(Generic[T_co])

collections.abc.AsyncIterable のジェネリック版です。

class typing.AsyncIterator(AsyncIterable[T_co])

collections.abc.AsyncIterator のジェネリック版です。

class typing.ContextManager(Generic[T_co])

contextlib.AbstractContextManager のジェネリック版です。

バージョン 3.6 で追加.

class typing.AsyncContextManager(Generic[T_co])

contextlib.AbstractAsyncContextManager のジェネリック版です。

バージョン 3.6 で追加.

class typing.Dict(dict, MutableMapping[KT, VT])

A generic version of dict. The usage of this type is as follows:

def get_position_in_index(word_list: Dict[str, int], word: str) -> int:
    return word_list[word]
class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])

collections.defaultdict のジェネリック版です。

バージョン 3.5.2 で追加.

class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])

collections.OrderedDict のジェネリック版です。

バージョン 3.7.2 で追加.

class typing.Counter(collections.Counter, Dict[T, int])

collections.Counter のジェネリック版です。

バージョン 3.6.1 で追加.

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])

collections.ChainMap のジェネリック版です。

バージョン 3.6.1 で追加.

class typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])

ジェネレータはジェネリック型 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 は共変や不変ではなく、反変として扱われることに注意してください。

もしジェネレータが値を返すだけの場合は、 SendType と ReturnType に 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
class typing.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])

非同期ジェネレータはジェネリック型 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 は反変的に振る舞います。

ジェネレータが値を yield するだけなら、SendType を 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)

バージョン 3.5.4 で追加.

class typing.Text

Text は str のエイリアスです。これは Python 2 のコードの前方互換性を提供するために設けられています: Python 2 では Text は unicode のエイリアスです。

Text は Python 2 と Python 3 の両方と互換性のある方法で値が unicode 文字列を含んでいなければならない場合に使用してください。

def add_unicode_checkmark(text: Text) -> Text:
    return text + u' \u2713'

バージョン 3.5.2 で追加.

class typing.IO
class typing.TextIO
class typing.BinaryIO

ジェネリック型 IO[AnyStr] とそのサブクラスの TextIO(IO[str]) および BinaryIO(IO[bytes]) は、 open() 関数が返すような I/O ストリームの型を表します。

class typing.Pattern
class typing.Match

これらの型エイリアスは re.compile() と re.match() の返り値の型に対応します。 これらの型 (と対応する関数) は AnyStr についてジェネリックで、Pattern[str] 、 Pattern[bytes] 、 Match[str] 、 Match[bytes] と書くことで具体型にできます。

class typing.NamedTuple

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

デフォルト値のあるフィールドはデフォルト値のないフィールドの後でなければなりません。

結果としてできるクラスは二つの追加の属性を持ちます。一つは _field_types で、フィールド名を型に結びつける辞書です。 もう一つは _field_defaults で、フィールド名をデフォルト値に結びつける辞書です。 (フィールド名は namedtuple API の一つである _fields 属性にあります。)

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}>'

後方互換な使用法:

Employee = NamedTuple('Employee', [('name', str), ('id', int)])

バージョン 3.6 で変更: PEP 526 変数アノテーションのシンタックスが追加されました。

バージョン 3.6.1 で変更: デフォルト値、メソッド、ドキュメンテーション文字列への対応が追加されました。

typing.NewType(typ)

異なる型であることを型チェッカーに教えるためのヘルパー関数です。 NewType を参照してください。 実行時には、その引数を返す関数を返します。 使い方は次のようになります:

UserId = NewType('UserId', int)
first_user = UserId(1)

バージョン 3.5.2 で追加.

typing.cast(typ, val)

値をある型にキャストします。

この関数は値を変更せずに返します。 型検査器に対して、返り値が指定された型を持っていることを通知しますが、実行時には意図的に何も検査しません。 (その理由は、処理をできる限り速くしたかったためです。)

typing.get_type_hints(obj[, globals[, locals]])

関数、メソッド、モジュールまたはクラスのオブジェクトの型ヒントを含む辞書を返します。

この辞書はたいてい obj.__annotations__ と同じものです。 それに加えて、文字列リテラルにエンコードされた順方向参照は globals 名前空間および locals 名前空間で評価されます。 必要であれば、 None と等価なデフォルト値が設定されている場合に、関数とメソッドのアノテーションに Optional[t] が追加されます。 クラス C については、 C.__mro__ の逆順に沿って全ての __annotations__ を合併して構築された辞書を返します。

@typing.overload

@overload デコレータを使うと、引数の型の複数の組み合わせをサポートする関数やメソッドを書けるようになります。 @overload 付きの定義を並べた後ろに、(同じ関数やメソッドの) @overload 無しの定義が来なければなりません。 @overload 付きの定義は型チェッカーのためでしかありません。 というのも、 @overload 付きの定義は @overload 無しの定義で上書きされるからです。 後者は実行時に使われますが、型チェッカーからは無視されるべきなのです。 実行時には、 @overload 付きの関数を直接呼び出すと NotImplementedError を送出します。 次のコードはオーバーロードを使うことで直和型や型変数を使うよりもより正確な型が表現できる例です:

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

詳細と他の型付け意味論との比較は PEP 484 を参照してください。

@typing.no_type_check

アノテーションが型ヒントでないことを示すデコレータです。

これはクラス decorator または関数 decorator として動作します。クラス decorator として動作する場合は、そのクラス内に定義されたすべてのメソッドに対して再帰的に適用されます。（ただしスーパークラスやサブクラス内に定義されたメソッドには適用されません。）

これは関数を適切に変更します。

@typing.no_type_check_decorator

別のデコレータに no_type_check() の効果を与えるデコレータです。

これは何かの関数をラップするデコレータを no_type_check() でラップします。

typing.Any

制約のない型であることを示す特別な型です。

  • 任意の型は Any と互換です。
  • Any は任意の型と互換です。
typing.NoReturn

関数が返り値を持たないことを示す特別な型です。例えば次のように使います:

from typing import NoReturn

def stop() -> NoReturn:
    raise RuntimeError('no way')

バージョン 3.6.5 で追加.

typing.Union

ユニオン型; Union[X, Y] は X または Y を表します。

ユニオン型を定義します、例えば Union[int, str] のように使います。詳細:

  • 引数は型でなければならず、少なくとも一つ必要です。

  • ユニオン型のユニオン型は平滑化されます。例えば:

    Union[Union[int, str], float] == Union[int, str, float]

  • 引数が一つのユニオン型は消えます。例えば:

    Union[int] == int  # The constructor actually returns int

  • 冗長な実引数は飛ばされます。例えば:

    Union[int, str, int] == Union[int, str]

  • ユニオン型を比較するとき引数の順序は無視されます。例えば:

    Union[int, str] == Union[str, int]

  • ユニオン型のサブクラスを作成したり、インスタンスを作成することは出来ません。

  • Union[X][Y] と書くことは出来ません。

  • Optional[X] を Union[X, None] の略記として利用することが出来ます。

バージョン 3.7 で変更: 明示的に書かれているサブクラスを、実行時に直和型から取り除かなくなりました。

typing.Optional

オプショナル型。

Optional[X] は Union[X, None] と同値です。

これがデフォルト値を持つオプション引数とは同じ概念ではないということに注意してください。 デフォルト値を持つオプション引数はオプション引数であるために、型アノテーションに Optional 修飾子は必要ありません。 例えば次のようになります:

def foo(arg: int = 0) -> None:
    ...

それとは逆に、 None という値が許されていることが明示されている場合は、引数がオプションであろうとなかろうと、 Optional を使うのが好ましいです。 例えば次のようになります:

def foo(arg: Optional[int] = None) -> None:
    ...
typing.Tuple

タプル型; Tuple[X, Y] は、最初の要素の型が X で、2つ目の要素の型が Y であるような、2つの要素を持つタプルの型です。

例: Tuple[T1, T2] は型変数 T1 と T2 に対応する2つの要素を持つタプルです。Tuple[int, float, str] は int と float、 string のタプルです。

同じ型の任意の長さのタプルを指定するには ellipsis リテラルを用います。例: Tuple[int, ...]。ただの Tuple は Tuple[Any, ...] と等価で、さらに tuple と等価です。.

typing.Callable

呼び出し可能型; Callable[[int], str] は (int) -> str の関数です。

添字表記は常に2つの値とともに使われなければなりません: 実引数のリストと返り値の型です。 実引数のリストは型のリストか ellipsis でなければなりません; 返り値の型は単一の型でなければなりません。

オプショナル引数やキーワード引数を表すための文法はありません; そのような関数型はコールバックの型として滅多に使われません。 Callable[..., ReturnType] (リテラルの Ellipsis) は任意の個数の引数をとり ReturnType を返す型ヒントを与えるために使えます。 普通の Callable は Callable[..., Any] と同等で、 collections.abc.Callable でも同様です。

typing.ClassVar

クラス変数であることを示す特別な型構築子です。

PEP 526 で導入された通り、 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

バージョン 3.5.3 で追加.

typing.AnyStr

AnyStr は AnyStr = TypeVar('AnyStr', str, bytes) として定義される型変数です。

他の種類の文字列を混ぜることなく、任意の種類の文字列を許す関数によって使われることを意図しています。

def concat(a: AnyStr, b: AnyStr) -> AnyStr:
    return a + b

concat(u"foo", u"bar")  # Ok, output has type 'unicode'
concat(b"foo", b"bar")  # Ok, output has type 'bytes'
concat(u"foo", b"bar")  # Error, cannot mix unicode and bytes
typing.TYPE_CHECKING

サードパーティーの静的型検査器が True と仮定する特別な定数です。 実行時には False になります。使用例:

if TYPE_CHECKING:
    import expensive_mod

def fun(arg: 'expensive_mod.SomeType') -> None:
    local_var: expensive_mod.AnotherType = other_fun()

1つ目の型アノテーションは引用符で囲って "前方参照 (forward reference)" にし、インタプリタのランタイムから expensive_mod への参照を隠さなければなりません。 ローカル変数への型アノテーションは評価されないので、2つ目のアノテーションは引用符で囲う必要はありません。

バージョン 3.5.2 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 開発ツール »


unittest --- ユニットテストフレームワーク

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 開発ツール »

unittest --- ユニットテストフレームワーク

ソースコード: 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
Kent Beck のテスティングフレームワークに関する原論文で、ここに記載されたパターンを unittest が使用しています。
Nose and pytest
サードパーティのユニットテストフレームワークでより軽量な構文でテストを書くことができます。例えば、assert func(10) == 42 のように書きます。
The Python Testing Tools Taxonomy
多くの Python のテストツールが一覧で紹介されています。ファンクショナルテストのフレームワークやモックライブラリも掲載されています。
Testing in Python メーリングリスト
Python でテストやテストツールについての議論に特化したグループです。

Python のソースコード配布物にあるスクリプト Tools/unittestgui/unittestgui.py はテストディスカバリとテスト実行のための GUI ツールです。 主な目的は単体テストの初心者が簡単に使えるようにすることです。 実際の生産環境では、 Buildbot 、 Jenkins 、 Hudson のような継続的インテグレーションシステムでテストを実行することを推奨します。

基本的な例

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) ... ok
test_split (__main__.TestStringMethods) ... ok
test_upper (__main__.TestStringMethods) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK

上の例が unittest モジュールで最もよく使われる機能で、ほとんどのテストではこれで十分です。以下では全ての機能を一から解説しています。

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

ユニットテストモジュールはコマンドラインから使って、モジュール、クラス、あるいは個別のテストメソッドで定義されたテストを実行することが出来ます:

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

Only run test methods and classes that match the pattern or substring. This option may be used multiple times, in which case all test cases that match of the given patterns are included.

Patterns that contain a wildcard character (*) are matched against the test name using fnmatch.fnmatchcase(); otherwise simple case-sensitive substring matching is used.

Patterns are matched against the fully qualified test method name as imported by the test loader.

For example, -k foo matches foo_tests.SomeTest.test_something, bar_tests.SomeTest.test_foo, but not bar_tests.FooTest.test_something.

--locals

トレースバック内の局所変数を表示します。

バージョン 3.2 で追加: コマンドラインオプションの -b、-c、-f が追加されました。

バージョン 3.5 で追加: コマンドラインオプション --locals。

バージョン 3.7 で追加: The command-line option -k.

コマンドラインによってテストディスカバリ、すなわちプロジェクトの全テストを実行したりサブセットのみを実行したりすることも出来ます。

テストディスカバリ

バージョン 3.2 で追加.

unittest はシンプルなテストディスカバリをサポートします。 テストディスカバリに対応するには、全テストファイルはプロジェクトの最上位のディスカバリからインポート可能な モジュール か (名前空間パッケージ を含む) パッケージ でなければなりません (つまりそれらのファイル名は有効な 識別子 でなければなりません)。

テストディスカバリは 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 で変更: ディスカバリが 名前空間パッケージ をサポートしました。

テストコードの構成

ユニットテストの基本的な構成要素は、 テストケース --- 設定され正しさのためにチェックされるべき単独のシナリオ --- です。 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))

何らかのテストを行うには、 TestCase ベースクラスが提供する assert*() メソッドのうちの一つを使用してください。 テストが失敗した場合は、例外が説明のメッセージとともに送出され、 unittest はテスト結果を failure とします。 その他の例外は error として扱われます。

テストは多くなり、それらの設定は繰り返しになるかもしれません。 幸いにも、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() が実行されます。

Such a working environment for the testing code is called a test fixture. A new TestCase instance is created as a unique test fixture used to execute each individual test method. Thus setUp(), tearDown(), and __init__() will be called once per test.

テストケースの実装では、テストする機能に従ってテストをまとめるのをお勧めします。 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 のインスタンスを作成します。

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

バージョン 3.1 で追加.

unittest は特定のテストメソッドやテストクラス全体をスキップする仕組みを備えています。さらに、この機能はテスト結果を「予期された失敗 (expected failure)」とすることができ、テストが失敗しても TestResult の失敗数にはカウントされなくなります。

テストをスキップするには、単に skip() デコレータ かその条件的な変種の一つを使用します。

基本的なスキップは以下のようになります:

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

このサンプルを冗長モードで実行すると以下のように出力されます:

test_format (__main__.MyTestCase) ... skipped 'not supported in this library version'
test_nothing (__main__.MyTestCase) ... skipped 'demonstrating skipping'
test_windows_support (__main__.MyTestCase) ... skipped 'requires Windows'

----------------------------------------------------------------------
Ran 3 tests in 0.005s

OK (skipped=3)

テストクラスは以下のようにメソッドをスキップすることができます:

@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

Mark the test as an expected failure. If the test fails it will be considered a success. If the test passes, it will be considered a failure.

exception unittest.SkipTest(reason)

この例外はテストをスキップするために送出されます。

ふつうはこれを直接送出する代わりに TestCase.skipTest() やスキッピングデコレータの一つを使用出来ます。

スキップしたテストの前後では、 setUp() および tearDown() は実行されません。同様に、スキップしたクラスの前後では、 setUpClass() および tearDownClass() は実行されません。スキップしたモジュールの前後では、 setUpModule() および tearDownModule() は実行されません。

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

バージョン 3.4 で追加.

When there are very small differences among your tests, for instance some parameters, unittest allows you to distinguish them inside the body of a test method using the subTest() context manager.

例えば以下のテストは:

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) (i=1)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest) (i=3)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest) (i=5)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

サブテスト無しの場合、最初の失敗で実行は停止し、i の値が表示されないためエラーの原因を突き止めるのは困難になります:

======================================================================
FAIL: test_even (__main__.NumbersTest)
----------------------------------------------------------------------
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()

A class method called before tests in an individual class are run. setUpClass is called with the class as the only argument and must be decorated as a classmethod():

@classmethod
def setUpClass(cls):
    ...

詳しくは クラスとモジュールのフィクスチャ を参照してください。

バージョン 3.2 で追加.

tearDownClass()

個別のクラス内のテストが実行された後に呼び出されるクラスメソッドです。 tearDownClass はクラスを唯一の引数として取り、 classmethod() でデコレーされていなければなりません:

@classmethod
def tearDownClass(cls):
    ...

詳しくは クラスとモジュールのフィクスチャ を参照してください。

バージョン 3.2 で追加.

run(result=None)

テストを実行し、テスト結果を result に指定された TestResult オブジェクトにまとめます。 result が省略されるか None が渡された場合、 (defaultTestResult() メソッドを呼んで) 一時的な結果オブジェクトを生成し、使用します。 結果オブジェクトは run() の呼び出し元に返されます。

このメソッドは、単に TestCase インスタンスを呼び出した場合と同様に振る舞います。

バージョン 3.3 で変更: 以前のバージョンの run は結果オブジェクトを返しませんでした。また TestCase インスタンスを呼び出した場合も同様でした。

skipTest(reason)

テストメソッドや setUp() が現在のテストをスキップする間に呼ばれます。詳細については、 テストのスキップと予期された失敗 を参照してください。

バージョン 3.1 で追加.

subTest(msg=None, **params)

このメソッドを囲っているブロックをサブテストとして実行するコンテキストマネージャを返します。 msg と params はサブテストが失敗したときに表示されるオプションの任意の値で、どんな値が使われたかを明確にするものです。

テストケースには subtest 宣言を幾らでも含めることができ、任意にネストすることができます。

詳細は サブテストを利用して繰り返しテストの区別を付ける を参照してください。

バージョン 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 が同じオブジェクトであること (そうでないこと) をテストします。

バージョン 3.1 で追加.

assertIsNone(expr, msg=None)
assertIsNotNone(expr, msg=None)

expr が None であること (および、そうでないこと) をテストします。

バージョン 3.1 で追加.

assertIn(first, second, msg=None)
assertNotIn(first, second, msg=None)

first が second に含まれること (そうでないこと) をテストします。

バージョン 3.1 で追加.

assertIsInstance(obj, cls, msg=None)
assertNotIsInstance(obj, cls, msg=None)

obj が cls のインスタンスであること (あるいはそうでないこと) をテストします (この cls は、 isinstance() が扱うことのできる、クラスもしくはクラスのタプルである必要があります)。正確な型をチェックするためには、 assertIs(type(obj), cls) を使用してください。

バージョン 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
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')

バージョン 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)

このメソッドは呼び出されたときに警告フィルタを無視して動作します。

バージョン 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')

バージョン 3.2 で追加.

バージョン 3.3 で変更: コンテキストマネージャとして使用したときに msg キーワード引数が追加されました。

assertLogs(logger=None, level=None)

logger かその子ロガーのうちの1つに、少なくとも1つのログメッセージが少なくとも与えられた level で出力されることをテストするコンテキストマネージャです。

logger が与えられた場合、 logging.Logger オブジェクトもしくはロガーの名前である str であるべきです。 デフォルトはルートロガーで、これは全てのメッセージを掴まえます。

level が与えられた場合、ログレベルを表す数値もしくはそれに相当する文字列 (例えば "ERROR" もしくは logging.ERROR) であるべきです。 デフォルトは 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'])

バージョン 3.4 で追加.

より具体的な確認を行うために以下のメソッドが用意されています:

メソッド | 確認事項 | 初出
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 以下 (以上) であることをテストします。

Supplying both delta and places raises a 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"

バージョン 3.1 で追加.

assertRegex(text, regex, msg=None)
assertNotRegex(text, regex, msg=None)

regex の検索が text とマッチする (またはマッチしない) ことをテストします。テスト失敗時には、エラーメッセージにパターンと text が表示されます（もしくは、パターンと意図しないかたちでマッチした text の一部が表示されます）。 regex は正規表現オブジェクトか、 re.search() が扱える正規表現が書かれた文字列である必要があります。

バージョン 3.1 で追加: assertRegexpMatches という名前で追加されました。

バージョン 3.2 で変更: メソッド assertRegexpMatches() は assertRegex() にリネームされました。

バージョン 3.2 で追加: assertNotRegex()。

バージョン 3.5 で追加: assertNotRegexpMatches は assertNotRegex() のエイリアスであることから非推奨となります。

assertCountEqual(first, second, msg=None)

シーケンス first が second と同じ要素を含んでいることをテストします。要素の順序はテスト結果に影響しません。要素が含まれていない場合には、シーケンスの差分がエラーメッセージとして表示されます。

first と second の比較では、重複した要素は無視 されません。両者に同じ数の要素が含まれていることを検証します。このメソッドは assertEqual(Counter(list(first)), Counter(list(second))) と同等に振る舞うことに加えて、ハッシュ化できないオブジェクトのシーケンスでも動作します。

バージョン 3.2 で追加.

assertEqual() メソッドは、同じ型のオブジェクトの等価性確認のために、型ごとに特有のメソッドにディスパッチします。これらのメソッドは、ほとんどの組み込み型用のメソッドは既に実装されています。さらに、 addTypeEqualityFunc() を使う事で新たなメソッドを登録することができます:

addTypeEqualityFunc(typeobj, function)

assertEqual() で呼び出される型特有のメソッドを登録します。登録するメソッドは、比較する2つのオブジェクトの型が厳密に typeobj と同じ (サブクラスでもいけません) の場合に等価性を確認します。 function は assertEqual() と同様に、2つの位置引数と、3番目に msg=None のキーワード引数を取れる必要があります。このメソッドは、始めの2つに指定したパラメータ間の差分を検出した時に self.failureException(msg) の例外を投げる必要があります。この例外を投げる際は、出来る限り、エラーの内容が分かる有用な情報と差分の詳細をエラーメッセージに含めてください。

バージョン 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 を比較するときに自動的に使用します。

バージョン 3.1 で追加.

assertSequenceEqual(first, second, msg=None, seq_type=None)

2つのシーケンスが等しいことをテストします。seq_type が指定された場合、first と second が seq_type のインスタンスで無い場合にはテストが失敗します。シーケンスどうしが異なる場合には、両者の差分がエラーメッセージに表示されます。

このメソッドは直接 assertEqual() からは呼ばれませんが、 assertListEqual() と assertTupleEqual() の実装で使われています。

バージョン 3.1 で追加.

assertListEqual(first, second, msg=None)
assertTupleEqual(first, second, msg=None)

2つのリストまたはタプルが等しいかどうかをテストします。等しくない場合には、両者の差分を表示します。2つのパラメータの型が異なる場合にはテストがエラーになります。このメソッドは、デフォルトで、 assertEqual() が list または tuple を比較するときに自動的に使用します。

バージョン 3.1 で追加.

assertSetEqual(first, second, msg=None)

2つのセットが等しいかどうかをテストします。等しくない場合には、両者の差分を表示します。このメソッドは、デフォルトで、 assertEqual() が set もしくは frozenset を比較するときに自動的に使用します。

first or second のいずれかに set.difference() が無い場合にはテストは失敗します。

バージョン 3.1 で追加.

assertDictEqual(first, second, msg=None)

2つの辞書が等しいかどうかをテストします。等しくない場合には、両者の差分を表示します。このメソッドは、デフォルトで、 assertEqual() が dict を比較するときに自動的に使用します。

バージョン 3.1 で追加.

最後に、 TestCase の残りのメソッドと属性を紹介します:

fail(msg=None)

無条件にテストを失敗させます。エラーメッセージの表示に、msg または None が使われます。

failureException

test() メソッドが送出する例外を指定するクラス属性です。例えばテストフレームワークで追加情報を付した特殊な例外が必要になる場合、この例外のサブクラスとして作成します。この属性の初期値は AssertionError です。

longMessage

このクラス属性は、失敗した assertXYY の呼び出しで独自の失敗時のメッセージが msg 引数として渡されていたときにどうするかを決定します。 True がデフォルト値です。 この場合、標準の失敗時のメッセージの後に独自のメッセージが追記されます。 False に設定したときは、標準のメッセージを独自のメッセージで置き換えます。

アサートメソッドを呼び出す前に、個別のテストメソッドの中でインスタンス属性 self.longMessage を True または False に設定して、この設定を上書きできます。

このクラスの設定はそれぞれのテストを呼び出す前にリセットされます。

バージョン 3.1 で追加.

maxDiff

この属性は、アサーションメソッドが失敗をレポートする時に表示する差分の長さをコントロールします。デフォルトは 80*8 文字です。この属性が影響するメソッドは、 assertSequenceEqual() (およびこのメソッドに委譲するシーケンス比較メソッド)、 assertDictEqual() と assertMultiLineEqual() です。

maxDiff を None に設定すると差分表示の上限がなくなります。

バージョン 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() が呼ばれなかった場合でも、追加されたクリーンアップ関数は呼び出されます。

バージョン 3.1 で追加.

doCleanups()

このメソッドは、 tearDown() の後、もしくは、 setUp() が例外を投げた場合は setUp() の後に、無条件で呼ばれます。

このメソッドは、 addCleanup() で追加された関数を呼び出す責務を担います。もし、クリーンアップ関数を tearDown() より前に呼び出す必要がある場合には、 doCleanups() を明示的に呼び出してください。

doCleanups() は、どこで呼び出されても、クリーンアップ関数をスタックから削除して実行します。

バージョン 3.1 で追加.

class unittest.FunctionTestCase(testFunc, setUp=None, tearDown=None, description=None)

このクラスでは TestCase インターフェースの内、テストランナーがテストを実行するためのインターフェースだけを実装しており、テスト結果のチェックやレポートに関するメソッドは実装していません。既存のテストコードを unittest によるテストフレームワークに組み込むために使用します。

非推奨のエイリアス

歴史的な経緯で、 TestCase のいくつかのエイリアスは非推奨となりました。以下の表に、非推奨のエイリアスをまとめます:

メソッド名 | 非推奨のエイリアス | 非推奨のエイリアス
assertEqual() | failUnlessEqual | assertEquals
assertNotEqual() | failIfEqual | assertNotEquals
assertTrue() | failUnless | assert_
assertFalse() | failIf
assertRaises() | failUnlessRaises
assertAlmostEqual() | failUnlessAlmostEqual | assertAlmostEquals
assertNotAlmostEqual() | failIfAlmostEqual | assertNotAlmostEquals
assertRegex() | assertRegexpMatches
assertNotRegex() | assertNotRegexpMatches
assertRaisesRegex() | assertRaisesRegexp

バージョン 3.1 で非推奨: 2列目に記載されている fail* エイリアス。

バージョン 3.2 で非推奨: 3列目に記載されている assert* エイリアス。

バージョン 3.2 で非推奨: assertRegexpMatches は assertRegex() に、 assertRaisesRegexp は assertRaisesRegex() にメソッド名が変更されました

バージョン 3.5 で非推奨: assertNotRegexpMatces は assertNotRegex() にメソッド名が変更になりました。

テストのグループ化

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__()

TestSuite でグループ化されたテストは反復アクセスできます。 サブクラスは __iter__() をオーバーライドすることで、遅延処理でテストを提供できます。 1つのスイート内でこのメソッドは何度も呼ばれる可能性があることに注意してください (例えば、テスト数のカウントや等価性の比較)。 そのため、 TestSuite.run() を実行する前に反復アクセスを何度繰り返しても同じテスト群を返すようにしなければなりません。 呼び出し側が TestSuite._removeTestAtIndex() をオーバーライドしたサブクラスを使いテストへの参照を保存していない限り、 TestSuite.run() を実行した後はこのメソッドが返すテスト群を信頼すべきではありません。

バージョン 3.2 で変更: 以前のバージョンでは TestSuite はイテレータではなく、直接テストにアクセスしていました。そのため、 __iter__() をオーバーラードしてもテストにアクセスできませんでした。

バージョン 3.4 で変更: 以前のバージョンでは、 TestSuite.run() の実行後は TestSuite が各 TestCase への参照を保持していました。 サブクラスで TestSuite._removeTestAtIndex() をオーバーライドすることでこの振る舞いを復元できます。

通常、 TestSuite の run() メソッドは TestRunner が起動するため、ユーザが直接実行する必要はありません。

テストのロードと起動

class unittest.TestLoader

TestLoader クラスはクラスとモジュールからテストスイートを生成します。通常、このクラスのインスタンスを明示的に生成する必要はありません。 unittest モジュールの unittest.defaultTestLoader を共用インスタンスとして使用することができます。 しかし、このクラスのサブクラスやインスタンスで、属性をカスタマイズすることができます。

TestLoader オブジェクトには以下の属性があります:

errors

テストの読み込み中に起きた致命的でないエラーのリストです。 どの時点でもローダーからリセットされることはありません。 致命的なエラーは適切なメソッドが例外を送出して、呼び出し元に通知します。 致命的でないエラーも、実行したときのエラーを総合テストが通知してくれます。

バージョン 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 で変更: ドキュメントにない、非公式の use_load_tests デフォルト引数は非推奨で、後方互換性のために残されていますが無視されます。 また、このメソッドはキーワード専用引数 pattern を受け取るようになりました。これは load_tests の第三引数に渡されます。

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 の識別子として有効であるということです) がロードされます。

すべてのテストモジュールはプロジェクトのトップレベルからインポート可能である必要があります。開始ディレクトリがトップレベルディレクトリでない場合は、トップレベルディレクトリを個別に指定しなければなりません。

シンタックスエラーなどでモジュールのインポートに失敗した場合、エラーが記録され、ディスカバリ自体は続けられます。 import の失敗が SkipTest 例外が発生したためだった場合は、そのモジュールはエラーではなく skip として記録されます。

パッケージ (__init__.py という名前のファイルがあるディレクトリ) が見付かった場合、そのパッケージに load_tests 関数があるかをチェックします。 関数があった場合、次に package.load_tests(loader, tests, pattern) が呼ばれます。 テストの検索の実行では、たとえ load_tests 関数自身が loader.discover を呼んだとしても、パッケージのチェックは1回のみとなることが保証されています。

load_tests が存在して、ディスカバリがパッケージ内を再帰的な検索を続けている途中で ない 場合、load_tests はそのパッケージ内の全てのテストをロードする責務を担います。

意図的にパターンはローダの属性として保持されないようになっています。それにより、パッケージが自分自身のディスカバリを続ける事ができます。top_level_dir は保持されるため、load_tests はこの引数を loader.discover() に渡す必要はありません。

start_dir はドット付のモジュール名でもディレクトリでも構いません。

バージョン 3.2 で追加.

バージョン 3.4 で変更: インポート時に SkipTest を送出するモジュールはエラーではなくスキップとして記録されます。 名前空間パッケージ も検索対象になります。 ファイルシステムの順序がファイル名に従わないとしても実行順序が一定になるように、パスはインポートする前にソートされます。

バージョン 3.5 で変更: パッケージ名がデフォルトのパターンに適合するのは不可能なので、パスが pattern に適合するかどうかに関係無く、見付けたパッケージに load_tests があるかをチェックするようになりました。

以下の属性は、サブクラス化またはインスタンスの属性値を変更して TestLoader をカスタマイズする場合に使用します:

testMethodPrefix

テストメソッドの名前と判断されるメソッド名の接頭語を示す文字列。デフォルト値は 'test' です。

この値は getTestCaseNames() と全ての loadTestsFrom*() メソッドに影響を与えます。

sortTestMethodsUsing

getTestCaseNames() および全ての loadTestsFrom*() メソッドでメソッド名をソートする際に使用する比較関数。

suiteClass

テストのリストからテストスイートを構築する呼び出し可能オブジェクト。メソッドを持つ必要はありません。デフォルト値は TestSuite です。

この値は全ての loadTestsFrom*() メソッドに影響を与えます。

testNamePatterns

List of Unix shell-style wildcard test name patterns that test methods have to match to be included in test suites (see -v option).

If this attribute is not None (the default), all test methods to be included in test suites must match one of the patterns in this list. Note that matches are always performed using fnmatch.fnmatchcase(), so unlike patterns passed to the -v option, simple substring patterns will have to be converted using * wildcards.

この値は全ての loadTestsFrom*() メソッドに影響を与えます。

バージョン 3.7 で追加.

class unittest.TestResult

このクラスはどのテストが成功しどのテストが失敗したかという情報を収集するのに使います。

TestResult は、複数のテスト結果を記録します。 TestCase クラスと TestSuite クラスのテスト結果を正しく記録しますので、テスト開発者が独自にテスト結果を管理する処理を開発する必要はありません。

unittest を利用したテストフレームワークでは、 TestRunner.run() が返す TestResult インスタンスを参照し、テスト結果をレポートします。

TestResult インスタンスの以下の属性は、テストの実行結果を検査する際に使用することができます:

errors

TestCase と例外のトレースバック情報をフォーマットした文字列の 2 要素タプルからなるリスト。それぞれのタプルは予想外の例外を送出したテストに対応します。

failures

TestCase と例外のトレースバック情報をフォーマットした文字列の 2 要素タプルからなるリスト。それぞれのタプルは TestCase.assert*() メソッドを使って見つけ出した失敗に対応します。

skipped

TestCase インスタンスとテストをスキップした理由を保持する文字列の2要素タプルからなるリストです。

バージョン 3.1 で追加.

expectedFailures

TestCase と例外のトレースバック情報をフォーマット済の文字列の 2 要素タプルからなるリストです。それぞれのタプルは予期された失敗に対応します。

unexpectedSuccesses

予期された失敗とされていながら成功してしまった TestCase のインスタンスのリスト。

shouldStop

True が設定されると stop() によりテストの実行が停止します。

testsRun

これまでに実行したテストの総数です。

buffer

True が設定されると、 sys.stdout と sys.stderr は、 startTest() から stopTest() が呼ばれるまでの間バッファリングされます。実際に、結果が sys.stdout と sys.stderr に出力されるのは、テストが失敗するかエラーが発生した時になります。表示の際には、全ての失敗 / エラーメッセージが表示されます。

バージョン 3.2 で追加.

failfast

真の場合 stop() が始めの失敗もしくはエラーの時に呼び出され、テストの実行が終了します。

バージョン 3.2 で追加.

tb_locals

真の場合、局所変数がトレースバックに表示されます。

バージョン 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()

全てのテストが実行される前に一度だけ実行されます。

バージョン 3.1 で追加.

stopTestRun()

全てのテストが実行された後に一度だけ実行されます。

バージョン 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 を持つ例外を伴います。

結果が成功の場合デフォルトの実装では何もせず、サブテストの失敗を通常の失敗として報告します。

バージョン 3.4 で追加.

class unittest.TextTestResult(stream, descriptions, verbosity)

TextTestRunner に使用される TestResult の具象実装です。

バージョン 3.2 で追加: このクラスは以前 _TextTestResult という名前でした。以前の名前はエイリアスとして残っていますが非推奨です。

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)

結果をストリームに出力する、基本的なテストランナーの実装です。 stream が None の場合、デフォルトで sys.stderr が出力ストリームとして使われます。 このクラスはいくつかの設定項目があるだけで、基本的に非常に単純です。 グラフィカルなテスト実行アプリケーションでは、独自のテストランナーを実装してください。 テストランナーの実装は、 unittest に新しい機能が追加されランナーを構築するインターフェースが変更されたときに備えて **kwargs を受け取れるようにするべきです。

デフォルトで無視 に設定されているとしても、このランナーのデフォルトでは DeprecationWarning, PendingDeprecationWarning, ResourceWarning, ImportWarning を表示します。 unittest の非推奨メソッド で起きた非推奨警告も特別な場合として扱われ、警告フィルタが 'default' もしくは 'always' だったとき、対象の警告メッセージが出ないようにモジュールごとに1回だけ表示されます。 Python の -Wd オプションや -Wa オプション (警告の制御 を参照してください) を使ったり、 warnings を None にしたりしておくと、この動作を上書きできます。

バージョン 3.2 で変更: warnings 引数が追加されました。

バージョン 3.2 で変更: インポート時でなくインスタンス化時にデフォルトのストリームが sys.stderr に設定されます。

バージョン 3.5 で変更: tb_locals 引数が追加されました。

_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 が使われます。

引数、 testRunner は、test runner class、あるいは、そのインスタンスのどちらでも構いません。でフォルトでは main はテストが成功したか失敗したかに対応した終了コードと共に sys.exit() を呼び出します。

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 プロトコル

バージョン 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 例外であれば、そのモジュールはエラーではなくスキップされたものとして報告されます。

シグナルハンドリング

バージョン 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 --- モックオブジェクトライブラリ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 開発ツール »

unittest.mock --- モックオブジェクトライブラリ

バージョン 3.3 で追加.

ソースコード: Lib/unittest/mock.py

unittest.mock はPython におけるソフトウェアテストのためのライブラリです。テスト中のシステムの一部をモックオブジェクトで置き換え、それらがどのように使われるかをアサートすることができます。

unittest.mock はコア Mock クラスを提供しており、それによってテストスイート内でたくさんのスタブを作成しなくてすみます 。アクションの実行後、メソッドや属性の使用や実引数についてアサートできます。また通常の方法で戻り値を明記したり、必要な属性を設定することもできます。

加えて、 mock はテストのスコープ内にあるモジュールやクラスの属性を変更する patch() デコレータを提供します。さらに、ユニークなオブジェクトの作成には sentinel が利用できます。 Mock や MagicMock 、 patch() の利用例は quick guide を参照してください。

Mock はとても使いやすく、 unittest で利用するために設計されています。Mock は多くのモックフレームワークで使われる 'record -> replay' パターンの代わりに、 'action -> assertion' パターンに基づいています。

以前の Python バージョン向けにバックポートされた unittest.mock があり、 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 によって、モック呼び出し時の例外発生などの副作用を実行できます:

>>> 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()

注釈

When you nest patch decorators the mocks are passed in to the decorated function in the same order they applied (the normal Python order that decorators are applied). This means from the bottom up, so in the example above the mock for module.ClassName1 is passed in first.

patch() では探索される名前空間内のオブジェクトにパッチをあてることが重要です。通常は単純ですが、クイックガイドには where-to-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: デフォルトでは、何らかの属性が assert または assret で始まると AttributeError が上がります。 unsafe=True を渡すと、これらの属性へのアクセスが許可されます。

    バージョン 3.5 で追加.

  • wraps: ラップするモックオブジェクトを指定します。 もし wraps に None 以外を指定した場合には、モックの呼び出し時に指定したオブジェクトを呼び出します (戻り値は実際の結果を返します)。 属性へのアクセスは、ラップされたオブジェクトと対応するモックを返します (すなわち、存在しない属性にアクセスしようとした場合は AttributeError が発生します)。

    return_value が設定されている場合には、ラップ対象は呼び出されず、 return_value が返されます。

  • name: もし、モックが name を持つ場合には、モックの repr として使われます。デバッグの際に役立つでしょう。この値は、子のモックにも伝播します。

モックは、任意のキーワード引数を与えることができます。これらはモックの生成後、属性の設定に使われます。詳細は configure_mock() を参照してください。

assert_called(*args, **kwargs)

モックが少なくとも一度は呼び出されたことをアサートします。

>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called()

バージョン 3.6 で追加.

assert_called_once(*args, **kwargs)

モックが一度だけ呼び出されたことをアサートします。

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

バージョン 3.6 で追加.

assert_called_with(*args, **kwargs)

このメソッドは呼び出しが特定の方法で行われたことをアサートするのに便利な方法です:

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

Assert that the mock was called exactly once and that that call was with the specified arguments.

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

バージョン 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, and side_effect are keyword only argument.

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

(もし呼び出されたことがなければ) None、それ以外であれば最後に呼び出された時の引数を返します。引数はタプルの形式で表されます: 最初の要素はモックが呼び出された際の順序付きの引数 (もしくは空のタプル) 、二つ目の要素はキーワード引数 (もしくは空の辞書) です。

>>> 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(3, 4, 5, key='fish', next='w00t!')
>>> mock.call_args
call(3, 4, 5, key='fish', next='w00t!')

call_args は、 call_args_list や method_calls 、 mock_calls と同様、 call オブジェクトです。これらはタプルとしてアンパックすることで個別に取り出すことができます。そして、より複雑なアサーションを行うことができます。 calls as tuples を参照してください。

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)

プロパティもしくはディスクリプタとして使われるためのモックです。 PropertyMock は、 __get__() と __set__() メソッドを提供し、戻り値を指定することができます。

オブジェクトから 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()

呼び出し

モックオブジェクトは呼び出し可能です。呼び出しの戻り値は 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() を使うのは簡単です。重要なのは正しい名前空間に対して 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 文が終了すると、パッチは元に戻されます。

new が省略された場合、 target は MagicMock に置き換えられます。 patch() がデコレータとして利用され、 new が省略された場合、生成された mock はデコレータの対象となる関数の追加の引数として渡されます。 patch() がコンテキストマネージャーとして利用された場合、コンテキストマネージャーが生成した mock を返します。

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 を使って、 new オブジェクトを生成するために呼び出されるクラスや callable オブジェクトを指定することができます。デフォルトでは MagicMock が使われます。

より強力な 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 afterwards. 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() は任意のキーワード引数を受け取り、それを Mock (あるいは new_callable) の生成時に渡します。

異なるユースケースのために、 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

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() はまた、任意のキーワード引数を受け取って辞書に設定します。

patch.dict() はコンテキストマネージャー、デコレータ、クラスデコレータとして利用できます。クラスデコレータとして利用する場合、 patch.dict() は patch.TEST_PREFIX にしたがってラップするメソッドを選択します。

patch.dict() を使うと、辞書にメンバーを追加するか、または単にテストが辞書を変更して、その後テストが終了した時にその辞書が確実に復元されるようにすることができます。

>>> foo = {}
>>> with patch.dict(foo, {'newkey': 'newvalue'}):
...     assert foo == {'newkey': 'newvalue'}
...
>>> assert 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() は辞書ではなくても辞書ライクなオブジェクトに対して使うことができます。対象となるオブジェクトは最低限、 get, set, del そしてイテレーションかメンバーのテストのどちらかをサポートする必要があります。これはマジックメソッドの __getitem__(), __setitem__(), __delitem__() そして __iter__() か __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() はデコレータ、クラスデコレータ、コンテキストマネージャーとして使えます。引数の spec, spec_set, create, autospec, new_callable は patch() の引数と同じ意味を持ちます。これらの引数は patch.multiple() によって適用される すべての パッチに対して適用されます。

クラスデコレータとして利用する場合、 patch.multiple() は patch.TEST_PREFIX にしたがってラップするメソッドを選択します。

patch.multiple() に mock を生成させたい場合、キーワード引数の値に DEFAULT を指定します。この場合生成されたモックはデコレート対象の関数にキーワード引数として渡されます。

>>> 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(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(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 への参照を持っていて、パッチの影響を受けないからです。

The key is to patch out SomeClass where it is used (or where it is looked up). In this case some_function will actually look up SomeClass in module b, where we have imported it. The patching should look like:

@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 オブジェクト に対しても機能します。

MagicMock と magic method のサポート

magick method をモックする

Mock は、 "magic method" とも呼ばれる、Python のプロトコルメソッドに対する mock もサポートしています。これによりコンテナやその他 Python のプロトコルを実装しているオブジェクトを mock することが可能になります。

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__
  • __floor__, __trunc__, __ceil__
  • 比較: __lt__, __gt__, __le__, __ge__, __eq__, __ne__
  • コンテナメソッド: __getitem__, __setitem__, __delitem__, __contains__, __len__, __iter__, __reversed__, __missing__
  • コンテキストマネージャー: __enter__, __exit__
  • 単項算術メソッド: __neg__, __pos__, __invert__
  • 算術メソッド (右辺や in-place のものも含む): __add__, __sub__, __mul__, __matmul__, __div__, __truediv__, __floordiv__, __mod__, __divmod__, __lshift__, __rshift__, __and__, __xor__, __or__, __pow__
  • 算術変換メソッド: __complex__, __int__, __float__, __index__
  • デスクリプタメソッド: __get__, __set__, __delete__
  • pickle: __reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__, __setstate__

以下のメソッドは存在しますが、mock が利用している、動的に設定不可能、その他の問題が発生する可能性があるなどの理由で サポートされていません:

  • __getattr__, __setattr__, __init__, __new__
  • __prepare__, __instancecheck__, __subclasscheck__, __del__

Magic Mock

MagicMock 系のクラスは2種類あります: MagicMock と NonCallableMagicMock です。

class unittest.mock.MagicMock(*args, **kw)

MagicMock は Mock のサブクラスで、ほとんどの magic method のデフォルト実装を提供しています。自分で magic method を構成しなくても MagicMock を使うことができます。

コンストラクタの引数は 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
  • __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

2つの比較メソッド __eq__() と __ne__() は特別です。それらは、もし戻り値として何か別のものを返すように変更していなければ、 side_effect 属性を使用して、同一性に基づくデフォルトの同値比較を行います:

>>> MagicMock() == 3
False
>>> MagicMock() != 3
True
>>> mock = MagicMock()
>>> mock.__eq__.return_value = True
>>> mock == 3
True

MagickMock.__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__, __setformat__
[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
>>> sentinel.some_object
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
>>> args, kwargs = kall
>>> args
(1, 2, 3)
>>> kwargs
{'arg2': 'two', 'arg': 'one'}
>>> args is kall[0]
True
>>> 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
{'arg2': 'three', 'arg': 'two'}
>>> 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 を使う を参照してください。

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

FILTER_DIR

unittest.mock.FILTER_DIR

FILTER_DIR は mock オブジェクトが dir() に何を返すかを制御するためのモジュールレベル変数です。 (Python 2.6 以上でのみ有効) デフォルトは True で、以下に示すフィルタリングを行い、有用なメンバーだけを表示します。このフィルタリングが嫌な場合や、何かの診断のためにフィルタリングを切りたい場合は、 mock.FILTER_DIR = False と設定してください。

フィルタリングが有効な場合、 dir(some_mock) は有用な属性だけを表示し、また通常は表示されない動的に生成される属性も表示します。 mock が spec を使って(もちろん autospec でも)生成された場合、元のオブジェクトのすべての属性が、まだアクセスされていなかったとしても、表示されます。

>>> dir(Mock())
['assert_any_call',
 'assert_called_once_with',
 'assert_called_with',
 'assert_has_calls',
 '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__',
 ...

mock.FILTER_DIR によるフィルタリングをバイパスしたい場合、 var(my_mock) (インスタンスメンバー)、 dir(type(my_mock)) (型メンバー) を代わりに使うことができます。

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 にあるインメモリファイルシステムパッケージのうちのどれかを使えば、テストのための本物のファイルシステムが得られるでしょう。

バージョン 3.4 で変更: readline() および readlines() のサポートが追加されました。 read() のモックは、個々の呼び出しで read_data を返すのではなく、それを消費するように変わりました。

バージョン 3.5 で変更: read_data は mock を呼び出す度に毎回リセットされるようになりました。

バージョン 3.7.1 で変更: 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')

問題は、 open() をモックアウトしたところで、コンテキストマネージャーが使われる (__enter__() と __exit__() が呼ばれる) のはその 戻り値 だということです。

コンテキストマネージャーを 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)

typo のために、テストは不正確に、かつ暗黙に成功してしまいます。

2つ目の問題はもっと一般的なものです。なにかのコードをリファクタし、メンバの名前を変更したとします。古いAPI を利用したコードに対するテストが、mock を利用しているとするとテストは通り続けます。このため、コードが壊れていてもテストがすべて通ってしまう可能性があります。

各ユニットが互いにどのように接続されるかをテストしない場合、依然としてテストで見つけることができるバグの余地が多く残っています。

mock はこの問題に対処するために spec と呼ばれる機能を提供しています。何かクラスかインスタンスを spec として mock に渡すと、実際のクラスに存在する属性にしか、 mock に対してもアクセスできなくなります:

>>> from urllib import request
>>> mock = Mock(spec=request.Request)
>>> mock.assret_called_with
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()

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
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]。

より重大な問題は、インスタンス属性が __init__() で生成され、クラスには全く存在しない場合です。 autospec は動的に生成される属性については知ることができず、 API を検出できる属性だけに制限してしまいます。

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

この問題を解決するベストな方法は、 __init__() で初期化されるインスタンスメンバに対する初期値をクラス属性として追加することかもしれません。 __init__() メソッドの中でデフォルトの属性を代入しているだけなら、それをクラス属性にする (この属性はもちろんインスタンス間で共有されます) 方が速くなるのもメリットです。例:

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.

バージョン 3.7 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 開発ツール »


unittest.mock --- 入門

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 開発ツール »

unittest.mock --- 入門

バージョン 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

既存のオブジェクトから 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'

Using a specification also enables a smarter matching of calls made to the mock, regardless of whether some parameters were passed as positional or named arguments:

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

If you want this smarter matching to also work with method calls on the mock, you can use auto-speccing.

任意の属性の参照だけでなく代入も禁止するより強い定義を利用したい場合は、spec の代わりに spec_set を使います。

patch デコレータ

注釈

patch() では探索される名前空間内のオブジェクトにパッチをあてることが重要です。通常は単純ですが、クイックガイドには where-to-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()

When you nest patch decorators the mocks are passed in to the decorated function in the same order they applied (the normal Python order that decorators are applied). This means from the bottom up, so in the example above the mock for test_module.ClassName2 is passed in first.

また、 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

部分的なモック

テストによっては、 datetime.date.today() の呼び出しを既知の date を返すようにモックしたいと思うことがありました。しかし、テスト対象のコードが新しい date オブジェクトを生成するのを妨げたくはありません。不運にも、 datetime.date は C で書かれています。したがって、静的な date.today() メソッドを単にモンキーパッチすることはできませんでした。

私はこれを行う単純な方法を見つけました。それは、date クラスをモックで事実上ラップして、しかしコンストラクタの呼び出しを実際のクラスへと素通りさせる (そして、実際のインスタンスを返す) というものです。

ここで、テスト対象のモジュール中の date クラスをモックするために patch decorator が使用されています。そして、モックの date クラスの side_effect 属性は、本物の date を返すラムダ関数にセットされます。モックの date クラスが呼ばれる時、 side_effect によって本物の date が構築されて返されます。

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

Note that we don't patch datetime.date globally, we patch date in the module that uses it. See where to patch.

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.

Calls to the date constructor are recorded in the mock_date attributes (call_count and friends) which may also be useful for your tests.

An alternative way of dealing with mocking dates, or other builtin classes, is discussed in this blog entry.

ジェネレータ method をモックする

A Python generator is a function or method that uses the yield statement to return a series of values when iterated over [1].

A generator method / function is called to return the generator object. It is the generator object that is then iterated over. The protocol method for iteration is __iter__(), so we can mock this using a MagicMock.

Here's an example class with an "iter" method implemented as a generator:

>>> class Foo:
...     def iter(self):
...         for i in [1, 2, 3]:
...             yield i
...
>>> foo = Foo()
>>> list(foo.iter())
[1, 2, 3]

How would we mock this class, and in particular its "iter" method?

To configure the values returned from the iteration (implicit in the call to list), we need to configure the object returned by the call to foo.iter().

>>> mock_foo = MagicMock()
>>> mock_foo.iter.return_value = iter([1, 2, 3])
>>> list(mock_foo.iter())
[1, 2, 3]
[1] There are also generator expressions and more advanced uses of generators, but we aren't concerned about them here. A very good introduction to generators and how powerful they are is: Generator Tricks for Systems Programmers.

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

If you want several patches in place for multiple test methods the obvious way is to apply the patch decorators to every method. This can feel like unnecessary repetition. For Python 2.6 or more recent you can use patch() (in all its various forms) as a class decorator. This applies the patches to all test methods on the class. A test method is identified by methods whose names start with test:

>>> @patch('mymodule.SomeClass')
... class MyTest(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'

An alternative way of managing patches is to use the patch のメソッド: start と stop. These allow you to move the patching into your setUp and tearDown methods.

>>> class MyTest(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()

If you use this technique you must ensure that the patching is "undone" by calling stop. This can be fiddlier than you might think, because if an exception is raised in the setUp then tearDown is not called. unittest.TestCase.addCleanup() makes this easier:

>>> class MyTest(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()

Mocking Unbound Methods

Whilst writing tests today I needed to patch an unbound method (patching the method on the class rather than on the instance). I needed self to be passed in as the first argument because I want to make asserts about which objects were calling this particular method. The issue is that you can't patch with a mock for this, because if you replace an unbound method with a mock it doesn't become a bound method when fetched from the instance, and so it doesn't get self passed in. The workaround is to patch the unbound method with a real function instead. The 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)

If we don't use autospec=True then the unbound method is patched out with a Mock instance instead, and isn't called with self.

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

mock has a nice API for making assertions about how your mock objects are used.

>>> 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()]

The call helper makes it easy to make assertions about these calls. You can build up a list of expected calls and compare it to call_args_list. This looks remarkably similar to the repr of the call_args_list:

>>> expected = [call(1, 2, 3), call(4, 5, 6), call()]
>>> mock.call_args_list == expected
True

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

Another situation is rare, but can bite you, is when your mock is called with mutable arguments. call_args and call_args_list store references to the arguments. If the arguments are mutated by the code under test then you can no longer make assertions about what the values were when the mock was called.

Here's some example code that shows the problem. Imagine the following functions defined in 'mymodule':

def frob(val):
    pass

def grob(val):
    "First frob and then clear val"
    frob(val)
    val.clear()

When we try to test that grob calls frob with the correct argument look what happens:

>>> 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(),), {})

One possibility would be for mock to copy the arguments you pass in. This could then cause problems if you do assertions that rely on object identity for equality.

Here's one solution that uses the 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 is called with the mock that will be called. It returns a new mock that we do the assertion on. The side_effect function makes a copy of the args and calls our new_mock with the copy.

注釈

If your mock is only going to be used once there is an easier way of checking arguments at the point they are called. You can simply do the checking inside a side_effect function.

>>> def side_effect(arg):
...     assert arg == {6}
...
>>> mock = Mock(side_effect=side_effect)
>>> mock({6})
>>> mock(set())
Traceback (most recent call last):
    ...
AssertionError

An alternative approach is to create a subclass of Mock or MagicMock that copies (using copy.deepcopy()) the arguments. Here's an example implementation:

>>> from copy import deepcopy
>>> class CopyingMock(MagicMock):
...     def __call__(self, *args, **kwargs):
...         args = deepcopy(args)
...         kwargs = deepcopy(kwargs)
...         return super(CopyingMock, self).__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(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(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, 'c': 3, 'b': 'fish', '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 is subclassing mock to created a Twisted adaptor. 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.

>>> 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 provides similar functionality, that may be useful here, in the form of its equality matcher (hamcrest.library.integration.match_equality).

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 開発ツール »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 開発ツール »

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

2to3 は、 Python 2.x のソースコードを読み込み、一連の 変換プログラム を適用して Python 3.x のコードに変換するプログラムです。標準ライブラリはほとんど全てのコードを取り扱うのに十分な変換プログラムを含んでいます。ただし 2to3 を構成している lib2to3 は柔軟かつ一般的なライブラリなので、 2to3 のために自分で変換プログラムを書くこともできます。 lib2to3 は、 Python コードを自動編集する必要がある場合にも適用することができます。

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)

It can be converted to Python 3.x code via 2to3 on the command line:

$ 2to3 example.py

A diff against the original source file is printed. 2to3 can also write the needed modifications right back to the source file. (A backup of the original file is made unless -n is also given.) Writing the changes back is enabled with the -w flag:

$ 2to3 -w example.py

変換後、 example.py は以下のようになります:

def greet(name):
    print("Hello, {0}!".format(name))
print("What's your name?")
name = input()
greet(name)

変換処理を通じて、コメントと、インデントは保存されます。

By default, 2to3 runs a set of predefined fixers. The -l flag lists all available fixers. An explicit set of fixers to run can be given with -f. Likewise the -x explicitly disables a fixer. The following example runs only the imports and has_key fixers:

$ 2to3 -f imports -f has_key example.py

This command runs every fixer except the apply fixer:

$ 2to3 -x apply example.py

Some fixers are explicit, meaning they aren't run by default and must be listed on the command line to be run. Here, in addition to the default fixers, the idioms fixer is run:

$ 2to3 -f all -f idioms example.py

ここで、 all を指定することで、全てのデフォルトの変換プログラムを有効化できることに注意して下さい。

2to3 がソースコードに修正すべき点を見つけても、自動的には修正できない場合もあります。この場合、 2to3 はファイルの変更点の下に警告を表示します。 3.x に準拠したコードにするために、あなたはこの警告に対処しなくてはなりません。

2to3 can also refactor doctests. To enable this mode, use the -d flag. Note that only doctests will be refactored. This also doesn't require the module to be valid Python. For example, doctest like examples in a reST document could also be refactored with this option.

The -v option enables output of more information on the translation process.

Since some print statements can be parsed as function calls or statements, 2to3 cannot always read files containing the print function. When 2to3 detects the presence of the from __future__ import print_function compiler directive, it modifies its internal grammar to interpret print() as a function. This change can also be enabled manually with the -p flag. Use -p to run fixers on code that already has had its print statements converted.

The -o or --output-dir option allows specification of an alternate directory for processed output files to be written to. The -n flag is required when using this as backup files do not make sense when not overwriting the input files.

バージョン 3.2.3 で追加: The -o option was added.

The -W or --write-unchanged-files flag tells 2to3 to always write output files even if no changes were required to the file. This is most useful with -o so that an entire Python source tree is copied with translation from one directory to another. This option implies the -w flag as it would not make sense otherwise.

バージョン 3.2.3 で追加: The -W flag was added.

The --add-suffix option specifies a string to append to all output filenames. The -n flag is required when specifying this as backups are not necessary when writing to different filenames. Example:

$ 2to3 -n -W --add-suffix=3 example.py

とすれば変換後ファイルは example.py3 として書き出されます。

バージョン 3.2.3 で追加: The --add-suffix option was added.

To translate an entire project from one directory tree to another use:

$ 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

Fixes duplicate types in the second argument of isinstance(). For example, isinstance(x, (int, int)) is converted to isinstance(x, int) and isinstance(x, (int, float, int)) is converted to 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

Converts calls to various functions in the operator module to other, but equivalent, function calls. When needed, the appropriate import statements are added, e.g. import collections.abc. The following mapping are made:

対象 | 変換先
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

Converts reload() to 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/

注釈

lib2to3 API は安定しておらず、将来、劇的に変更されるかも知れないと考えるべきです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 開発ツール »


test --- Python 用回帰テストパッケージ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 開発ツール »

test --- 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)

    このパターンを使うときには、 unittest.TestCase を継承した全てのクラスがテストとして実行されることを忘れないでください。 上の例の Mixin クラスはテストデータを持っておらず、それ自身は実行できないので、 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 を実行してください。

Some other ways to execute the regression tests depend on what platform the tests are being executed on. On Unix, you can run make test at the top-level directory where Python was built. On Windows, executing rt.bat from your PCbuild directory will run all regression tests.

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

True if the system is Android.

test.support.unix_shell

Path for shell if not on Windows; otherwise None.

test.support.FS_NONASCII

A non-ASCII character encodable by os.fsencode().

test.support.TESTFN

テンポラリファイルの名前として安全に利用できる名前に設定されます。作成した一時ファイルは全て閉じ、unlink (削除) しなければなりません。

test.support.TESTFN_UNICODE

Set to a non-ASCII name for a temporary file.

test.support.TESTFN_ENCODING

Set to sys.getfilesystemencoding().

test.support.TESTFN_UNENCODABLE

Set to a filename (str type) that should not be able to be encoded by file system encoding in strict mode. It may be None if it's not possible to generate such a filename.

test.support.TESTFN_UNDECODABLE

Set to a filename (bytes type) that should not be able to be decoded by file system encoding in strict mode. It may be None if it's not possible to generate such a filename.

test.support.TESTFN_NONASCII

Set to a filename containing the FS_NONASCII character.

test.support.IPV6_ENABLED

Set to True if IPV6 is enabled on this host, False otherwise.

test.support.SAVEDCWD

Set to os.getcwd().

test.support.PGO

Set when tests can be skipped when they are not useful for PGO.

test.support.PIPE_MAX_SIZE

A constant that is likely larger than the underlying OS pipe buffer size, to make writes blocking.

test.support.SOCK_MAX_SIZE

A constant that is likely larger than the underlying OS socket buffer size, to make writes blocking.

test.support.TEST_SUPPORT_DIR

Set to the top level directory that contains test.support.

test.support.TEST_HOME_DIR

Set to the top level directory for the test package.

test.support.TEST_DATA_DIR

Set to the data directory within the test package.

test.support.MAX_Py_ssize_t

Set to sys.maxsize for big memory tests.

test.support.max_memuse

Set by set_memlimit() as the memory limit for big memory tests. Limited by MAX_Py_ssize_t.

test.support.real_max_memuse

Set by set_memlimit() as the memory limit for big memory tests. Not limited by MAX_Py_ssize_t.

test.support.MISSING_C_DOCSTRINGS

Return True if running on CPython, not on Windows, and configuration not set with WITH_DOC_STRINGS.

test.support.HAVE_DOCSTRINGS

Check for presence of docstrings.

test.support モジュールでは、以下の関数を定義しています:

test.support.forget(module_name)

モジュール名 module_name を sys.modules から取り除き、モジュールのバイトコンパイル済みファイルを全て削除します。

test.support.unload(name)

Delete name from sys.modules.

test.support.unlink(filename)

Call os.unlink() on filename. On Windows platforms, this is wrapped with a wait loop that checks for the existence fo the file.

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

test.support.rmtree(path)

Call shutil.rmtree() on path or call os.lstat() and os.rmdir() to remove a path and its contents. On Windows platforms, this is wrapped with a wait loop that checks for the existence of the files.

test.support.make_legacy_pyc(source)

Move a PEP 3147/488 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.

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.system_must_validate_cert(f)

Raise unittest.SkipTest on TLS certification validation failures.

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.create_empty_file(filename)

Create an empty file with filename. If it already exists, truncate it.

test.support.fd_count()

Count the number of open file descriptors.

test.support.match_test(test)

Match test to patterns set in set_match_tests().

test.support.set_match_tests(patterns)

Define match test with regular expression patterns.

test.support.run_unittest(*classes)

渡された unittest.TestCase サブクラスを実行します。この関数は名前が test_ で始まるメソッドを探して、テストを個別に実行します。

引数に文字列を渡すことも許可されています。その場合、文字列は sys.module のキーでなければなりません。指定された各モジュールは、 unittest.TestLoader.loadTestsFromModule() でスキャンされます。この関数は、よく次のような test_main() 関数の形で利用されます。

def test_main():
    support.run_unittest(__name__)

この関数は、名前で指定されたモジュールの中の全ての定義されたテストを実行します。

test.support.run_doctest(module, verbosity=None, optionflags=0)

与えられた module の doctest.testmod() を実行します。(failure_count, test_count) を返します。

If verbosity is None, doctest.testmod() is run with verbosity set to verbose. Otherwise, it is run with verbosity set to None. optionflags is passed as optionflags to doctest.testmod().

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:

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

test.support.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.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.strip_python_strerr(stderr)

Strip the stderr of a Python process from potential debug output emitted by the interpreter. This will typically be run on the result of subprocess.Popen.communicate().

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.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.change_cwd(path, quiet=False)

カレントディレクトリを一時的に path に変更し与えるコンテキストマネージャです。

quiet が False の場合、コンテキストマネージャはエラーが起きると例外を送出します。 それ以外の場合には、警告を出すだけでカレントディレクトリは同じままにしておきます。

test.support.temp_cwd(name='tempcwd', quiet=False)

一時的に新しいディレクトリを作成し、カレントディレクトリ (current working directory, CWD) を変更するコンテキストマネージャです。

The context manager creates a temporary directory in the current directory with name name before temporarily changing the current working directory. If name is None, the temporary directory is created using tempfile.mkdtemp().

quiet が False でカレントディレクトリの作成や変更ができない場合、例外を送出します。 それ以外の場合には、警告を出すだけで元のカレントディレクトリが使われます。

test.support.temp_umask(umask)

一時的にプロセスの umask を設定するコンテキストマネージャ。

test.support.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.disable_faulthandler()

A context manager that replaces sys.stderr with sys.__stderr__.

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 upon entry and reenables it upon exit.

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.wait_threads_exit(timeout=60.0)

Context manager to wait until all threads created in the with statement exit.

test.support.start_threads(threads, unlock=None)

Context manager to start threads. It attempts to join the threads upon exit.

test.support.calcobjsize(fmt)

Return struct.calcsize() for nP{fmt}0n or, if gettotalrefcount exists, 2PnP{fmt}0P.

test.support.calcvobjsize(fmt)

Return struct.calcsize() for nPn{fmt}0n or, if gettotalrefcount exists, 2PnPn{fmt}0P.

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.can_symlink()

OS がシンボリックリンクをサポートする場合 True を返し、その他の場合は False を返します。

test.support.can_xattr()

Return True if the OS supports xattr, False otherwise.

@test.support.skip_unless_symlink

シンボリックリンクのサポートが必要なテストを実行することを表すデコレータ。

@test.support.skip_unless_xattr

A decorator for running tests that require support for xattr.

@test.support.skip_unless_bind_unix_socket

A decorator for running tests that require a functional bind() for Unix sockets.

@test.support.anticipate_failure(condition)

ある条件で unittest.expectedFailure() の印をテストに付けるデコレータ。 このデコレータを使うときはいつも、関連する問題を指し示すコメントを付けておくべきです。

@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, raise unittest.SkipTest.

@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, raise unittest.SkipTest.

@test.support.requires_mac_version(*min_version)

Decorator for the minimum version when running test on Mac OS X. If the MAC OS X version is less than the minimum, raise unittest.SkipTest.

@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.cpython_only(test)

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(func)

Decorator to temporarily turn off tracing for the duration of the test.

@test.support.refcount_test(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.reap_threads(func)

Decorator to ensure the threads are cleaned up even if the test fails.

@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(f)

Decorator for tests that fill the address space. f is the function to wrap.

test.support.make_bad_fd()

一時ファイルを開いた後に閉じ、そのファイル記述子を返すことで無効な記述子を作成します。

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 text of the error raised by SyntaxError. If lineno is not None, compares to the line of the SyntaxError. If offset is not None, compares to the offset of the SyntaxError.

test.support.open_urlresource(url, *args, **kw)

Open url. If open fails, raises TestFailed.

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

バージョン 3.1 で追加.

test.support.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'])

バージョン 3.1 で追加.

test.support.modules_setup()

Return a copy of sys.modules.

test.support.modules_cleanup(oldmodules)

Remove modules except for oldmodules and encodings in order to preserve internal cache.

test.support.threading_setup()

Return current thread count and copy of dangling threads.

test.support.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.join_thread(thread, timeout=30.0)

Join a thread within timeout. Raise an AssertionError if thread is still alive after timeout seconds.

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.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.bind_unix_socket(sock, addr)

Bind a unix socket, raising unittest.SkipTest if PermissionError is raised.

test.support.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.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.fs_is_case_insensitive(directory)

Return True if the file system for directory is case-insensitive.

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

バージョン 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 that iter is 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=(), blacklist=())

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 blacklist 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'}
        blacklist = {'baz'}  # Undocumented name.
        # bar imports part of its API from _bar.
        support.check__all__(self, bar, ('bar', '_bar'),
                             extra=extra, blacklist=blacklist)

バージョン 3.6 で追加.

test.support モジュールでは、以下のクラスを定義しています:

class test.support.TransientResource(exc, **kwargs)

このクラスのインスタンスはコンテキストマネージャーで、指定された型の例外が発生した場合に ResourceDenied 例外を発生させます。キーワード引数は全て、 with 文の中で発生した全ての例外の属性名/属性値と比較されます。全てのキーワード引数が例外の属性に一致した場合に、 ResourceDenied 例外が発生します。

class test.support.EnvironmentVarGuard

一時的に環境変数をセット・アンセットするためのクラスです。このクラスのインスタンスはコンテキストマネージャーとして利用されます。また、 os.environ に対する参照・更新を行う完全な辞書のインタフェースを持ちます。コンテキストマネージャーが終了した時、このインスタンス経由で環境変数へ行った全ての変更はロールバックされます。

バージョン 3.1 で変更: 辞書のインタフェースを追加しました。

EnvironmentVarGuard.set(envvar, value)

一時的に、 envvar を value にセットします。

EnvironmentVarGuard.unset(envvar)

一時的に envvar をアンセットします。

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.

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

class test.support.SaveSignals

Class to save and restore signal handlers registered by the Python signal 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).

class test.support.WarningsRecorder

ユニットテスト時に warning を記録するためのクラスです。上の、 check_warnings() のドキュメントを参照してください。

class test.support.BasicTestRunner
run(test)

Run test and return the result.

class test.support.TestHandler(logging.handlers.BufferingHandler)

Class for logging support.

class test.support.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__().

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.

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 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 is set to False.

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.

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.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 開発ツール »


デバッグとプロファイル

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

デバッグとプロファイル

ここに含まれるライブラリは Python での開発を手助けするものです。デバッガはコードのステップ実行や、スタックフレームの解析、ブレークポイントの設定などを可能にします。プロファイラはコードを実行して実行時間の詳細を晒すことでプログラムのボトルネックを見つけることを可能にします。

  • bdb --- デバッガーフレームワーク
  • faulthandler --- Python tracebackのダンプ
    • tracebackのダンプ
    • フォールトハンドラの状態
    • タイムアウト後にtracebackをダンプする
    • ユーザシグナルに対してtracebackをダンプする
    • ファイル記述子の問題
    • 使用例
  • pdb --- Python デバッガ
    • デバッガコマンド
  • Python プロファイラ
    • プロファイラとは
    • かんたんユーザマニュアル
    • リファレンスマニュアル -- profile と cProfile
    • Stats クラス
    • 決定論的プロファイリングとは
    • 制限事項
    • キャリブレーション (補正)
    • カスタムな時刻取得用関数を使う
  • timeit --- 小さなコード断片の実行時間計測
    • 基本的な例
    • Python インターフェイス
    • コマンドラインインターフェイス
    • 使用例
  • trace --- Python 文実行のトレースと追跡
    • コマンドラインからの使用
      • 主要なオプション
      • 修飾的オプション
      • フィルターオプション
    • プログラミングインターフェース
  • tracemalloc --- メモリ割り当ての追跡
    • 使用例
      • 上位10を表示する
      • 差を計算する
      • メモリブロックのトレースバックを取得する
      • top を整形化する
    • API
      • 関数
      • DomainFilter
      • Filter
      • Frame
      • Snapshot
      • Statistic
      • StatisticDiff
      • Trace
      • Traceback

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


bdb --- デバッガーフレームワーク

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • デバッグとプロファイル »

bdb --- デバッガーフレームワーク

ソースコード: Lib/bdb.py

bdb モジュールは、ブレークポイントを設定したり、デバッガー経由で実行を管理するような、基本的なデバッガー機能を提供します。

以下の例外が定義されています:

exception bdb.BdbQuit

Bdb クラスが、デバッガーを終了させるために投げる例外。

bdb モジュールは2つのクラスを定義しています:

class bdb.Breakpoint(self, file, line, temporary=0, cond=None, funcname=None)

このクラスはテンポラリブレークポイント、無視するカウント、無効化と再有効化、条件付きブレークポイントを実装しています。

ブレークポイントは bpbynumber という名前のリストで番号によりインデックスされ、 bplist により (file, line) の形でインデックスされます。 bpbynumber は Breakpoint クラスのインスタンスを指しています。一方 bplist は、同じ行に複数のブレークポイントが設定される場合があるので、インスタンスのリストを指しています。

ブレークポイントを作るとき、設定されるファイル名は正規化されていなければなりません。funcname が設定されたとき、ブレークポイントはその関数の最初の行が実行されたときにヒットカウントにカウントされます。条件付ブレークポイントは毎回カウントされます。

Breakpoint インスタンスは以下のメソッドを持ちます:

deleteMe()

このブレークポイントをファイル/行に関連付けられたリストから削除します。このブレークポイントがその行に設定された最後のブレークポイントだった場合、そのファイル/行に対するエントリ自体を削除します。

enable()

このブレークポイントを有効にします。

disable()

このブレークポイントを無効にします。

bpformat()

ブレークポイントに関する情報を持つ文字列をフォーマットして返します:

  • ブレークポイント番号。
  • テンポラリブレークポイントかどうか。
  • ファイル/行の位置。
  • ブレークする条件。
  • 次のN回無視されるか。
  • ヒットカウント。

バージョン 3.2 で追加.

bpprint(out=None)

ファイル out に、またはそれが None の場合は標準出力に、 bpformat() の出力を表示する。

class bdb.Bdb(skip=None)

Bdb クラスは一般的なPythonデバッガーの基本クラスとして振舞います。

このクラスはトレース機能の詳細を扱います。ユーザーとのインタラクションは、派生クラスが実装するべきです。標準ライブラリのデバッガクラス (pdb.Pdb) がその利用例です。

skip 引数は、もし与えられたならグロブ形式のモジュール名パターンの iterable でなければなりません。デバッガはこれらのパターンのどれかにマッチするモジュールで発生したフレームにステップインしなくなります。フレームが特定のモジュールで発生したかどうかは、フレームのグローバル変数の __name__ によって決定されます。

バージョン 3.1 で追加: skip 引数が追加されました。

以下の Bdb のメソッドは、通常オーバーライドする必要はありません。

canonic(filename)

標準化されたファイル名を取得するための補助関数。標準化されたファイル名とは、(大文字小文字を区別しないファイルシステムにおいて)大文字小文字を正規化し、絶対パスにしたものです。ファイル名が "<" と ">" で囲まれていた場合はそれを取り除いたものです。

reset()

botframe, stopframe, returnframe, quitting 属性を、デバッグを始められる状態に設定します。

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)

デバッガーが現在の行で止まるべきであれば、 user_line() メソッド (サブクラスでオーバーライドされる)を呼び出します。 Bdb.quitting フラグ(user_line() から設定できます)が設定されていた場合、 BdbQuit 例外を発生させます。このスコープのこれからのトレースのために、 trace_dispatch() メソッドの参照を返します。

dispatch_call(frame, arg)

デバッガーがこの関数呼び出しで止まるべきであれば、 user_call() メソッド (サブクラスでオーバーライドされる)を呼び出します。 Bdb.quitting フラグ(user_call() から設定できます)が設定されていた場合、 BdbQuit 例外を発生させます。このスコープのこれからのトレースのために、 trace_dispatch() メソッドの参照を返します。

dispatch_return(frame, arg)

デバッガーがこの関数からのリターンで止まるべきであれば、 user_return() メソッド (サブクラスでオーバーライドされる)を呼び出します。 Bdb.quitting フラグ(user_return() から設定できます)が設定されていた場合、 BdbQuit 例外を発生させます。このスコープのこれからのトレースのために、 trace_dispatch() メソッドの参照を返します。

dispatch_exception(frame, arg)

デバッガーがこの例外発生で止まるべきであれば、 user_exception() メソッド (サブクラスでオーバーライドされる)を呼び出します。 Bdb.quitting フラグ(user_exception() から設定できます)が設定されていた場合、 BdbQuit 例外を発生させます。このスコープのこれからのトレースのために、 trace_dispatch() メソッドの参照を返します。

通常、継承クラスは以下のメソッド群をオーバーライドしません。しかし、停止やブレークポイント機能を再定義したい場合には、オーバーライドすることもあります。

stop_here(frame)

このメソッドは frame がコールスタック中で botframe よりも下にあるかチェックします。 botframe はデバッグを開始したフレームです。

break_here(frame)

このメソッドは、frame に属するファイル名と行に、あるいは、少なくとも現在の関数にブレークポイントがあるかどうかをチェックします。ブレークポイントがテンポラリブレークポイントだった場合、このメソッドはそのブレークポイントを削除します。

break_anywhere(frame)

このメソッドは、現在のフレームのファイル名の中にブレークポイントが存在するかどうかをチェックします。

継承クラスはデバッガー操作をするために以下のメソッド群をオーバーライドするべきです。

user_call(frame, argument_list)

このメソッドは、呼ばれた関数の中でブレークする必要がある可能性がある場合に、 dispatch_call() から呼び出されます。

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)

現在の行番号よりも大きい行番号に到達したとき、あるいは、現在のフレームから戻るときにストップします。

set_trace([frame])

frame からデバッグを開始します。frame が指定されなかった場合、デバッグは呼び出し元のフレームから開始します。

set_continue()

ブレークポイントに到達するか終了したときにストップします。もしブレークポイントが1つも無い場合、システムのトレース関数を None に設定します。

set_quit()

quitting 属性を True に設定します。これにより、次回の dispatch_*() メソッドのどれかの呼び出しで、 BdbQuit 例外を発生させます。

継承クラスとクライアントは以下のメソッドをブレークポイント操作に利用できます。これらのメソッドは、何か悪いことがあればエラーメッセージを含む文字列を返し、すべてが順調であれば None を返します。

set_break(filename, lineno, temporary=0, cond, funcname)

新しいブレークポイントを設定します。引数の 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 が上げられます。

バージョン 3.2 で追加.

get_break(filename, lineno)

filename の lineno にブレークポイントが存在するかどうかをチェックします。

get_breaks(filename, lineno)

filename の lineno にあるすべてのブレークポイントを返します。ブレークポイントが存在しない場合は空のリストを返します。

get_file_breaks(filename)

filename の中のすべてのブレークポイントを返します。ブレークポイントが存在しない場合は空のリストを返します。

get_all_breaks()

セットされているすべてのブレークポイントを返します。

継承クラスとクライアントは以下のメソッドを呼んでスタックトレースを表現するデータ構造を取得することができます。

get_stack(f, t)

与えられたフレームおよび上位(呼び出し側)と下位のすべてのフレームに対するレコードのリストと、上位フレームのサイズを得ます。

format_stack_entry(frame_lineno, lprefix=': ')

(frame, lineno) で指定されたスタックエントリに関する次のような情報を持つ文字列を返します:

  • そのフレームを含むファイル名の標準形。
  • 関数名、もしくは "<lambda>"。
  • 入力された引数。
  • 戻り値。
  • (あれば)その行のコード。

以下の2つのメソッドは、文字列として渡された文(statement)をデバッグするもので、クライアントから利用されます。

run(cmd, globals=None, locals=None)

exec() 関数を利用して文を実行しデバッグします。 globals はデフォルトでは __main__.__dict__ で、 locals はデフォルトでは 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)

この場所でブレークする必要があるかどうかを、ブレークポイント b が設定された方法に依存する方法でチェックします。

ブレークポイントが行番号で設定されていた場合、この関数は b.line が、同じく引数として与えられた frame の中の行に一致するかどうかをチェックします。ブレークポイントが関数名で設定されていた場合、この関数は frame が指定された関数のものであるかどうかと、その関数の最初の行であるかどうかをチェックします。

bdb.effective(file, line, frame)

指定されたソースコード中の行に(有効な)ブレークポイントがあるかどうかを判断します。ブレークポイントと、テンポラリブレークポイントを削除して良いかどうかを示すフラグからなるタプルを返します。マッチするブレークポイントが存在しない場合は (None, None) を返します。

bdb.set_trace()

Bdb クラスのインスタンスを使って、呼び出し元のフレームからデバッグを開始します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • デバッグとプロファイル »


faulthandler --- Python tracebackのダンプ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • デバッグとプロファイル »

faulthandler --- Python tracebackのダンプ

バージョン 3.3 で追加.

このモジュールは、例外発生時、タイムアウト時、ユーザシグナルの発生時などのタイミングでpython tracebackを明示的にダンプするための関数を含んでいます。これらのシグナル、SIGSEGV、SIGFPE、SIGABRT、SIGBUS、SIGILL に対するフォールトハンドラをインストールするには faulthandler.enable() を実行してください。python起動時に有効にするには環境変数 PYTHONFAULTHANDLER を設定するか、コマンドライン引数に -X faulthandler を指定してください。

Pythonのフォールトハンドラは、apportやWindowsのフォールトハンドラのようなシステムフォールトハンドラと互換性があります。このモジュールは sigaltstack() 関数が使用可能であればシグナルハンドラ用に代替スタックを利用します。これによってスタックオーバーフロー時にもスタックトレースを出力することができます。

フォールトハンドラは絶望的なケースで呼び出されます。そのためシグナルセーフな関数しか使うことができません (例: ヒープメモリ上にメモリ確保はできません)。この制限により、tracebackのダンプ機能は通常のPythonのtracebackと比べてごく僅かなものです:

  • ASCIIのみサポートされます。エンコード時には backslashreplace エラーハンドラを使用します。
  • すべての文字列は500文字以内に制限されています。
  • ファイル名、関数名、行数のみ表示します。(ソースコードの表示はありません)
  • 100フレーム、100スレッドに制限されています。
  • 順番は保持されます: 最新の呼び出しが最初に表示されます。

デフォルトでは、Pythonのtracebackは sys.stderr に書き出されます。tracebackを見るには、対象アプリケーションはターミナル上で実行しなければなりません。 faulthandler.enable() に渡す引数によってログファイルを指定することができます。

モジュールはC言語で実装されているので、アプリのクラッシュ時でもPythonがデッドロックした場合でもダンプができます。

tracebackのダンプ

faulthandler.dump_traceback(file=sys.stderr, all_threads=True)

全スレッドのtracebackを file へダンプします。もし all_threads が False であれば、現在のスレッドのみダンプします。

バージョン 3.5 で変更: Added support for passing file descriptor to this function.

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

faulthandler.enable(file=sys.stderr, all_threads=True)

フォールトハンドラを有効にします。 SIGSEGV、 SIGFPE、 SIGABRT、 SIGBUS、SIGILL シグナルに対して Pythonのtracebackをダンプするハンドラをインストールします。もし all_threads が True であれば、すべての実行中のスレッドについてtracebackをダンプします。そうでなければ現在のスレッドのみダンプします。

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.

faulthandler.disable()

フォールトハンドラを無効にします: enable() によってインストールされたシグナルハンドラをアンインストールします。

faulthandler.is_enabled()

フォールトハンドラが有効かどうかチェックします。

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

faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)

timeout 秒経過後か、repeat が True の場合は timeout 秒おきに全スレッドの traceback をダンプします。もし exit が True であればtracebackをダンプした後、status=1で _exit() を呼び出します。(注: _exit() を呼び出すとプロセスを即座に終了します。つまりファイルバッファのクリアといった終了処理を行いません。)関数が2回呼ばれた場合、最新の呼び出しが前回の呼び出しパラメータを引き継いでタイムアウト時間をリセットします。タイマーの分解能は1秒未満です。

The file must be kept open until the traceback is dumped or cancel_dump_traceback_later() is called: see issue with file descriptors.

この関数は番犬(watchdog)スレッドを使って実装されているため、Pythonがスレッド無効でコンパイルされている場合は利用できません。

バージョン 3.5 で変更: Added support for passing file descriptor to this function.

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 の結果は別のファイルへ書き込まれます。ファイルが置き換えられた場合は、毎回これらの関数を呼び出しなおしてください。

使用例

Example of a segmentation fault on Linux with and without enabling the fault handler:

$ python3 -c "import ctypes; ctypes.string_at(0)"
Segmentation fault

$ python3 -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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • デバッグとプロファイル »


Python プロファイラ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • デバッグとプロファイル »

Python プロファイラ

ソースコード: Lib/profile.py と Lib/pstats.py

プロファイラとは

cProfile と profile は 決定論的プロファイリング (deterministic profiling) を行います。 プロファイル (profile) とは、プログラムの各部分がどれだけ頻繁に呼ばれたか、そして実行にどれだけ時間がかかったかという統計情報です。 pstats モジュールを使ってこの統計情報をフォーマットし表示することができます。

Python 標準ライブラリは同じインターフェイスを提供するプロファイラの実装を2つ提供しています:

  1. cProfile はほとんどのユーザーに推奨されるモジュールです。 C言語で書かれた拡張モジュールで、オーバーヘッドが少ないため長時間実行されるプログラムのプロファイルに適しています。 Brett Rosen と Ted Czotter によって提供された lsprof に基づいています。
  2. 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() を実行して、プロファイル結果を次のように表示します:

      197 function calls (192 primitive calls) in 0.002 seconds

Ordered by: standard name

ncalls  tottime  percall  cumtime  percall filename:lineno(function)
     1    0.000    0.000    0.001    0.001 <string>:1(<module>)
     1    0.000    0.000    0.001    0.001 re.py:212(compile)
     1    0.000    0.000    0.001    0.001 re.py:268(_compile)
     1    0.000    0.000    0.000    0.000 sre_compile.py:172(_compile_charset)
     1    0.000    0.000    0.000    0.000 sre_compile.py:201(_optimize_charset)
     4    0.000    0.000    0.000    0.000 sre_compile.py:25(_identityfunction)
   3/1    0.000    0.000    0.000    0.000 sre_compile.py:33(_compile)

最初の行は 197 回の呼び出しを測定したことを示しています。その中で 192 回は プリミティブ です。すなわち呼び出しが再帰によってなされてはいません。次の行は Ordered by: standard name は一番右の列の文字列が出力のソートに用いられたことを示します。列の見出しは以下を含みます:

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 は他のスクリプトをプロファイルするためのスクリプトとして起動することも出来ます。例えば:

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.

バージョン 3.7 で追加: Added the -m option.

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())
enable()

プロファイリングデータの収集を開始します。

disable()

プロファイリングデータの収集を停止します。

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 で指定したストリームに出力されます。

The file selected by the above constructor must have been created by the corresponding version of profile or cProfile. To be specific, there is no file compatibility guaranteed with future versions of this profiler, and there is no compatibility with files produced by other profilers, or the same profiler run on a different operating system. If several files are provided, all the statistics for identical functions will be coalesced, so that an overall view of several processes can be considered in a single report. If additional files need to be combined with data in an existing Stats object, the add() method can be used.

プロファイルデータをファイルから読み込む代わりに、 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.

When more than one key is provided, then additional keys are used as secondary criteria when there is equality in all keys selected before them. For example, sort_stats(SortKey.NAME, SortKey.FILE) will sort all the entries according to their function name, and resolve all ties (identical function names) by sorting by file name.

For the string argument, abbreviations can be used for any key names, as long as the abbreviation is unambiguous.

The following are the valid string and SortKey:

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 | 内部時間

Note that all sorts on statistics are in descending order (placing most time consuming items first), where as name, file, and line number searches are in ascending order (alphabetical). The subtle distinction between SortKey.NFL and SortKey.STDNAME is that the standard name is a sort of the name as printed, which means that the embedded line numbers get compared in an odd way. For example, lines 3, 20, and 40 would (if the file names were the same) appear in the string order 20, 3 and 40. In contrast, SortKey.NFL does a numeric compare of the line numbers. In fact, sort_stats(SortKey.NFL) is the same as sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE).

後方互換性のため、数値を引数に使った -1, 0, 1, 2 の形式もサポートしています。それぞれ 'stdname', 'calls', 'time', 'cumulative' として処理されます。引数をこの旧スタイルで指定した場合、最初のキー (数値キー) だけが使われ、複数のキーを指定しても2番目以降は無視されます。

バージョン 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() と同じです。

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

決定論的プロファイリング とは、すべての 関数呼び出し, 関数からのリターン, 例外発生 をモニターし、正確なタイミングを記録することで、イベント間の時間、つまりどの時間にユーザコードが実行されているのかを計測するやり方です。もう一方の 統計的プロファイリング (このモジュールでこの方法は採用していません) とは、有効なインストラクションポインタからランダムにサンプリングを行い、プログラムのどこで時間が使われているかを推定する方法です。後者の方法は、オーバヘッドが少ないものの、プログラムのどこで多くの時間が使われているか、その相対的な示唆に留まります。

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

The method executes the number of Python calls given by the argument, directly and again under the profiler, measuring the time for both. It then computes the hidden overhead per profiler event, and returns that as a float. For example, on a 1.8Ghz Intel Core i5 running Mac OS X, and using Python's time.process_time() as the timer, the magical number is about 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 --- 小さなコード断片の実行時間計測

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • デバッグとプロファイル »

timeit --- 小さなコード断片の実行時間計測

ソースコード: Lib/timeit.py

このモジュールは小さい Python コードをの時間を計測するシンプルな手段を提供しています。コマンドラインインターフェイス の他 呼び出しも可能 です。このモジュールは実行時間を計測するときに共通するいくつかの罠を回避します。O'Reilly 出版の Python Cookbook にある、Tim Peter による "Algorithms" 章も参照してください。

基本的な例

次の例は コマンドラインインターフェイス を使って 3 つの異なる式の時間を測定する方法を示しています。

$ python3 -m timeit '"-".join(str(n) for n in range(100))'
10000 loops, best of 5: 30.2 usec per loop
$ python3 -m timeit '"-".join([str(n) for n in range(100)])'
10000 loops, best of 5: 27.5 usec per loop
$ python3 -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

ただし、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()

デフォルトのタイマーです。常に time.perf_counter() です。

バージョン 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() と:meth:autorange`メソッドは :meth:.timeit` を複数回呼び出したい時に使用します。

setup の実行時間は全実行時間から除外されています。

stmt および setup パラメータは、引数なしの呼び出し可能オブジェクトをとることもできます。呼び出し可能オブジェクトを指定すると、そのオブジェクトの呼び出しがタイマー関数に埋め込まれ、その関数が timeit() メソッドによって実行されます。この場合、関数呼び出しが増えるためにタイミングのオーバーヘッドが少し増える点に注意してください。

バージョン 3.5 で変更: 任意の globals 引数が追加されました。

timeit(number=1000000)

メイン文を number 回実行した時間を計測します。このメソッドはセットアップ文を1回だけ実行し、メイン文を指定回数実行するのにかかった秒数を浮動小数で返します。引数はループを何回実行するかの指定で、デフォルト値は 100万回です。メイン文、セットアップ文、タイマー関数はコンストラクターで指定されたものを使用します。

注釈

デフォルトでは、timeit() は計測中、一時的に ガベージコレクション を停止します。 この手法の利点は個々の計測結果がより比較しやすくなることです。 欠点は、ガベージコレクションが計測される関数の性能の重要な要素である場合があることです。 その場合、setup 文字列の最初の文でガベージコレクションを有効にできます。 以下に例を示します:

timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
autorange(callback=None)

timeit() を呼び出す回数を自動的に決定します。

これは総時間が0.2秒以上になるように timeit() を繰り返し呼び出す便利な関数で、最終的な結果（ループ回数、ループ回数に要した時間）を返します。 要した時間が少なくとも0.2秒になるまで、シーケンス1, 2, 5, 10, 20, 50, ... から増加する回数で timeit() を呼び出します。

callback が与えられ、Noneでない場合は、 callback(number, time_taken) という2つの引数を指定して試行された後に呼び出されます。

バージョン 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] [-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() を利用して、実時間ではなくプロセス時間を計測します

バージョン 3.3 で追加.

-u, --unit=U
timer 出力の時間の単位を指定します。 nsec、usec、msec、secを選択できます。

バージョン 3.5 で追加.

-v, --verbose

時間計測の結果をそのまま詳細な数値でくり返し表示する

-h, --help

簡単な使い方を表示して終了する

文は複数行指定することもできます。その場合、各行は独立した文として引数に指定されたものとして処理します。クォートと行頭のスペースを使って、インデントした文を使うことも可能です。この複数行のオプションは -s においても同じ形式で指定可能です。

オプション -n でループの回数が指定されていない場合、10 回から始めて、所要時間が 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

>>> 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.40193588800002544, 0.3960157959998014, 0.39594301399984033]

以下の例は、複数行を含んだ式を計測する方法を示しています。ここでは、オブジェクトの存在する属性と存在しない属性に対してテストするために 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 --- Python 文実行のトレースと追跡

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • デバッグとプロファイル »

trace --- Python 文実行のトレースと追跡

ソースコード: Lib/trace.py

trace モジュールにより、プログラム実行のトレース、 注釈された文のカバレッジの一覧の作成、呼び出し元/呼び出し先の関係の出力、プログラム実行中に実行された関数の表の作成を行うことができます。 これは別のプログラム中やコマンドラインから利用することができます。

参考

Coverage.py
A popular third-party coverage tool that provides HTML output along with advanced features such as branch coverage.

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

trace モジュールはコマンドラインから起動することができます。これは次のように簡単です

python -m trace --count -C . somefile.py ...

これで、 somefile.py の実行中に import された Python モジュールの注釈付きリストがカレントディレクトリに生成されます。

--help

使い方を表示して終了します。

--version

モジュールのバージョンを表示して終了します。

主要なオプション

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 環境下で、コマンドを実行して、現在のトレースパラメータに基づいてその実行から統計情報を集めます。cmd は、exec() に渡せるような文字列か code オブジェクトです。定義しない場合、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 --- メモリ割り当ての追跡

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • デバッグとプロファイル »

tracemalloc --- メモリ割り当ての追跡

バージョン 3.4 で追加.

ソースコード: 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

We can see that Python loaded 4855 KiB data (bytecode and constants) from modules and that the collections module allocated 244 KiB to build namedtuple types.

オプションの詳細については 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

We can see that Python has loaded 8173 KiB of module data (bytecode and constants), and that this is 4428 KiB more than had been loaded before the tests, when the previous snapshot was taken. Similarly, the linecache module has cached 940 KiB of Python source code to format tracebacks, all of it since the previous snapshot.

システムに空きメモリがほとんどない場合、スナップショットをオフラインで解析するための 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]
        # replace "/path/to/module/file.py" with "module/file.py"
        filename = os.sep.join(frame.filename.split(os.sep)[-2:])
        print("#%s: %s:%s: %.1f KiB"
              % (index, 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() を参照してください。

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.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 以上でなければなりません。

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

バージョン 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 で変更: Added the domain attribute.

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

Filename pattern of the filter (str). Read-only property.

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)

Compute the differences with an old snapshot. Get statistics as a sorted list of StatisticDiff instances grouped by key_type.

See the Snapshot.statistics() method for key_type and cumulative parameters.

結果は降順でソートされます: キーは 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)

Get statistics as a sorted list of Statistic instances grouped by key_type:

key_type | description
'filename' | ファイル名
'lineno' | ファイル名と行番号
'traceback' | traceback

If cumulative is True, cumulate size and count of memory blocks of all frames of the traceback of a trace, not only the most recent frame. The cumulative mode can only be used with key_type equals to 'filename' and '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 で変更: Added the domain attribute.

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 Trace.traceback attribute is an instance of Traceback instance.

バージョン 3.7 で変更: Frames are now sorted from the oldest to the most recent, instead of most recent to oldest.

format(limit=None, most_recent_first=False)

Format the traceback as a list of lines with newlines. 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 »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

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

以下のライブラリは Python で書かれたソフトウェアを配布、インストールするためのものです。 これらは Python Package Index に対して動作するように設計されていますが、ローカルのインデックスサーバーや、インデックスサーバーなしに使うこともできます。

  • distutils --- Python モジュールの構築とインストール
  • ensurepip --- pip インストーラのブートストラップ
    • コマンドラインインターフェイス
    • モジュール API
  • venv --- 仮想環境の作成
    • 仮想環境の作成
    • API
    • EnvBuilder を拡張する例
  • zipapp --- Manage executable Python zip archives
    • 基本的な例
    • コマンドラインインターフェイス
    • Python API
    • 使用例
    • インタープリタの指定
    • Creating Standalone Applications with zipapp
      • Making a Windows executable
      • Caveats
    • The Python Zip Application Archive Format

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


distutils --- Python モジュールの構築とインストール

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ソフトウェア・パッケージと配布 »

distutils --- Python モジュールの構築とインストール

distutils パッケージは、現在インストールされている Python に追加するためのモジュール構築、および実際のインストールを支援します。新規のモジュールは 100%-pure Python でも、C で書かれた拡張モジュールでも、あるいは Python と C 両方のコードが入っているモジュールからなる Python パッケージでもかまいません。

Python ユーザの大半はこのパッケージを直接使い たくはない でしょうが、代わりに Python Packaging Authority が保守しているクロスバージョンツールを使うでしょう。特に、setuptools は distutils の改良された代替品で、以下を提供しています:

  • プロジェクトの依存性の宣言のサポート
  • ソースのリリースの際どのファイルを含めるか指定する追加の機構 (バージョン管理システムとの統合のためのプラグインも含む)
  • プロジェクトの "エントリーポイント" を宣言する機能、アプリケーションプラグインシステムとして使うことができます
  • インストール時に事前にビルドすることなく、Windows コマンドライン実行ファイルを自動的に生成する機能
  • サポートしている Python の全バージョンで一貫性のある挙動

たとえスクリプト自身が distutils のみをインポートしていても、推奨される pip インストーラは setuptools で全 setup.py スクリプトを実行します。詳細は Python Packaging User Guide を参照してください。

現在のパッケージと配布システムへの理解を深めようとしている著者やユーザのために、レガシーな distutils に基づくユーザドキュメントと API のリファレンスは利用可能なままになっています。

  • Python モジュールのインストール (旧版)
  • Python モジュールの配布 (レガシーバージョン)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ソフトウェア・パッケージと配布 »


venv --- 仮想環境の作成

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ソフトウェア・パッケージと配布 »

venv --- 仮想環境の作成

バージョン 3.3 で追加.

ソースコード: Lib/venv/

venv モジュールは、軽量な "仮想環境" の作成のサポートを提供します。仮想環境には、仮想環境ごとの site ディレクトリがあり、これはシステムの site ディレクトリから分離させることができます。それぞれの仮想環境には、それ自身に (この仮想環境を作成するのに使ったバイナリのバージョンに合った) Python バイナリがあり、仮想環境ごとの site ディレクトリに独立した Python パッケージ群をインストールできます。

Python仮想環境に関してより詳しくは PEP 405 を参照してください。

参考

Python Packaging User Guide: Creating and using virtual environments

注釈

pyvenv スクリプトは Python 3.6 で非推奨となり、代わりに python3 -m venv を使い、仮想環境を動かす Python インタープリタを取り違える可能性を防ぎやすくします。

仮想環境の作成

仮想環境 を作成するには venv コマンドを実行します:

python3 -m venv /path/to/new/virtual/environment

Running this command creates the target directory (creating any parent directories that don't exist already) and places a pyvenv.cfg file in it with a home key pointing to the Python installation from which the command was run. It also creates a bin (or Scripts on Windows) subdirectory containing a copy of the python binary (or binaries, in the case of Windows). It also creates an (initially empty) lib/pythonX.Y/site-packages subdirectory (on Windows, this is Lib\site-packages). If an existing directory is specified, it will be re-used.

バージョン 3.6 で非推奨: Python 3.3 と 3.4 では、仮想環境の作成に推奨していたツールは pyvenv でしたが、Python 3.6では非推奨です。

バージョン 3.5 で変更: 仮想環境の作成には、 venv の使用をお勧めします。

Windows では、 venv コマンドは次のように実行します:

c:\>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]
            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)

Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.

バージョン 3.4 で変更: デフォルトで pip をインストールします。--without-pip と --copies オプションを追加しました。

バージョン 3.4 で変更: 以前のバージョンでは、対象となるディレクトリが既に存在していた場合は、 --clear オプションや --upgrade オプションを付けない限りはエラーを送出していました。

作成された pyvenv.cfg ファイルには、include-system-site-packages キーも含まれます。これは venv が --system-site-packages オプションをつけて実行されたなら true で、そうでなければ false です。

--without-pip オプションが与えられない限り、pip を仮想環境でブートするために ensurepip が呼ばれます。

venv には複数のパスを渡すことができ、その場合はそれぞれのパスに同一の仮想環境が作成されます。

仮想環境の作成が完了すれば、その仮想環境のバイナリディレクトリにあるスクリプトで "有効化" できます。 スクリプトの呼び出し方はプラットフォーム固有です (<venv> の部分は、仮想環境があるディレクトリのパスに置き換える必要があります):

プラットフォーム | シェル | 仮想環境を有効化するためのコマンド
Posix | bash/zsh | $ source <venv>/bin/activate
 | fish | $ . <venv>/bin/activate.fish
 | csh/tcsh | $ source <venv>/bin/activate.csh
Windows | cmd.exe | C:\> <venv>\Scripts\activate.bat
 | PowerShell | PS C:\> <venv>\Scripts\Activate.ps1

環境を有効化するのに特別な指定は 必要 ありません; 有効化は仮想環境のバイナリディレクトリをパスの最初に加えて、 "python" で仮想環境の Python インタプリタが呼び出されるようにし、フルパスを入力せずにインストールされたスクリプトを実行できるようにするだけです。 しかし、インストールされたすべてのスクリプトは有効化しなくても実行可能で、仮想環境の Python で自動的に実行されなければなりません。

シェルで "deactivate" と入力することで仮想環境を無効化できます。 厳密な仕組みはプラットフォーム固有です。 例えば、Bash の有効化スクリプトは "deactivate" 関数を定義している一方、 Windows では、仮想環境が作成されるときにインストールされる deactivate.bat と Deactivate.ps1 という個別のスクリプトがあります。

バージョン 3.4 で追加: fish および csh 有効化スクリプト。

注釈

仮想環境とは、その中にインストールされた Python インタープリタ、ライブラリ、そしてスクリプトが、他の仮想環境にインストールされたものから隔離されている Python 環境です。そして (デフォルトでは) 仮想環境は "システム" の Python、すなわち OS の一部としてインストールされた Python にインストールされている全てのライブラリからも隔離されています。

仮想環境は、 Python 実行ファイルと、それが仮想環境であることを示す幾つかのファイルを含んだディレクトリツリーです。

Setuptools や pip などの一般的なインストールツールは期待通りに仮想環境と連係します。 言い換えると、仮想環境が有効なときには、 Python パッケージを仮想環境へインストールするのに、インストールツールへの明示的な指示は必要ありません。

仮想環境が有効な場合 (すなわち、仮想環境の Python インタープリタを実行しているとき)、 sys.prefix と sys.exec_prefix は仮想環境のベースディレクトリを示します。 代わりに sys.base_prefix と sys.base_exec_prefix が仮想環境を作るときに使った、仮想環境ではない環境の Python がインストールされている場所を示します。 仮想環境が無効の時は、 sys.prefix は sys.base_prefix と、 sys.exec_prefix は sys.base_exec_prefix と同じになります (全て仮想環境ではない環境の Python のインストール場所を示します)。

仮想環境が有効なときに、不注意で仮想環境の外にプロジェクトがインストールされることを避けるために、インストールパスを変更するあらゆるオプションは distutils の全ての設定ファイルによって無視されます。

コマンドシェルで作業をしているとき、仮想環境の実行可能ファイルディレクトリにある activate スクリプト (正確なファイル名はシェル依存です) を実行して、仮想環境を有効化できます。 このスクリプトは仮想環境の実行可能ファイルのディレクトリを、実行中のシェルの PATH 環境変数の先頭に差し込みます。 それ以外の状況では、仮想環境を有効化するための作業は必要無いはずです—仮想環境にインストールされたスクリプトには、仮想環境の Python インタプリタを指す "shebang" 行があります。 これはつまり、スクリプトは PATH の値に関係無く、仮想環境のインタプリタで実行されるということです。 Windows では、 Windows 用の Python ランチャがインストールされている場合は "shebang" 行の処理がサポートされています (この機能はバージョン 3.3 で Python に追加されました - 詳細は PEP 397 を参照してください)。 従って、インストールされたスクリプトを Windows のエクスプローラのウィンドウからダブルクリックすると、 PATH にその仮想環境への参照を持たせる必要無く、そのスクリプトが正しいインタープリタで実行されるはずです。

API

上述の高水準のメソッドは、サードパーティの仮想環境の作成者が環境の作成を必要に応じてカスタマイズするための機構を提供する簡素な API を利用します。それが EnvBuilder クラスです。

class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None)

EnvBuilder クラスを実体化するときに、以下のキーワード引数を受け取ります:

  • system_site_packages -- 真偽値で、システムの Python の site-packages を仮想環境から利用できるかどうかを示します (デフォルト: False)。
  • clear -- 真偽値で、真の場合環境を作成する前に既存の対象ディレクトリの中身を削除します。
  • symlinks -- a Boolean value indicating whether to attempt to symlink the Python binary (and any necessary DLLs or other binaries, e.g. pythonw.exe), rather than copying.
  • upgrade -- 真偽値で、真の場合実行中の Python で既存の環境をアップグレードします。その Python がインプレースでアップグレードされたときに用います。デフォルトは False です。
  • with_pip -- 真偽値で、真の場合仮想環境に pip がインストールされていることを保証します。--default-pip オプションで ensurepip を使用します。
  • prompt -- 仮想環境が有効になっているときに使われる文字列 (デフォルトは None で、その環境のディレクトリ名が使われることになります)。

バージョン 3.4 で変更: with_pip 引数が追加されました。

バージョン 3.6 で追加: prompt 引数が追加されました。

サードパーティーの仮想環境ツールの作成者は、EnvBuilder を継承して使うことができます。

返される env-builder オブジェクトには create というメソッドがあります:

create(env_dir)

このメソッドは path (絶対パスあるいは現在のディレクトリからの相対パス) を必要な1つの引数と受け取ります。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)

仮想環境のディレクトリと全ての必要なディレクトリを作成し、コンテキストオブジェクトを返します。 これは (パスなどの) 属性を保持しているだけのオブジェクトで、他のメソッドから使うためのものです。 既存の仮想環境ディレクトリ上での操作を許可するために clear や upgrade が指定されている場合に限り、作成されるディレクトリは既に存在していても構いません。

create_configuration(context)

仮想環境に pyvenv.cfg 設定ファイルを作成します。

setup_python(context)

Creates a copy of the Python executable in the environment on POSIX systems. If a specific executable python3.x was used, symlinks to python and python3 will be created pointing to that executable, unless files with those names already exist.

setup_scripts(context)

Installs activation scripts appropriate to the platform into the virtual environment. On Windows, also installs the python[w].exe scripts.

post_setup(context)

サードパーティーライブラリがオーバーライドするための空のメソッドです。このメソッドをオーバーライドして、仮想環境構築後にパッケージのプリインストールなどのステップを実装できます。

バージョン 3.7.2 で変更: Windows now uses redirector scripts for python[w].exe instead of copying the actual binaries, and so setup_python() does nothing unless running from a build in the source tree.

これらに加えて、 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)

EnvBuilder を指定されたキーワード引数を使って作成し、その create() メソッドに env_dir 引数を渡して実行します。

バージョン 3.4 で変更: with_pip 引数が追加されました。

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://bitbucket.org/pypa/setuptools/downloads/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://raw.github.com/pypa/pip/master/contrib/get-pip.py'
        self.install_script(context, 'pip', url)

def main(args=None):
    compatible = True
    if sys.version_info < (3, 3):
        compatible = False
    elif not hasattr(sys, 'base_prefix'):
        compatible = False
    if not compatible:
        raise ValueError('This script is only for use with '
                         'Python 3.3 or later')
    else:
        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)

このスクリプトは オンライン よりダウンロードすることも可能です。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • ソフトウェア・パッケージと配布 »


zipapp --- Manage executable Python zip archives

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • ソフトウェア・パッケージと配布 »

zipapp --- Manage executable Python zip archives

バージョン 3.5 で追加.

ソースコード: 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 has no effect when copying an archive.

バージョン 3.7 で追加.

--info

診断するために書庫に埋め込まれたインタープリタを表示します。 この場合、他の全てのオプションは無視され、SOURCE はディレクトリではなく書庫でなければなりません。

-h, --help

簡単な使用法を表示して終了します。

Python API

このモジュールは 2 つの簡便関数を定義しています:

zipapp.create_archive(source, target=None, interpreter=None, main=None, filter=None, compressed=False)

source からアプリケーション書庫を作成します。 ソースは以下のいずれかです:

  • The name of a directory, or a path-like object referring to a directory, in which case a new application archive will be created from the content of that directory.
  • The name of an existing application archive file, or a path-like object referring to such a file, in which case the file is copied to the target (modifying it to reflect the value given for the interpreter argument). The file name should include the .pyz extension, if required.
  • バイトモードの読込みで開くファイルオブジェクト。 ファイルの内容がアプリケーションアーカイブとなり、 ファイルオブジェクトがアーカイブの起点となります。

target 引数は作成される書庫が書き込まれる場所を決めます:

  • If it is the name of a file, or a path-like object, the archive will be written to that file.
  • 開いているファイルオブジェクトを指定した場合、 アーカイブはそのファイルオブジェクトへ書込みを行ないます。 ファイルオブジェクトは必ずバイトモードの書込みで開いてください。
  • 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 arguments.

zipapp.get_interpreter(archive)

アーカイブの最初の行の #! に指定されたインタープリタを返します。 #! が無い場合は None を返します。 archive 引数は、ファイル名またはバイトモードの読込みで開いた ファイルに準じるオブジェクトを指定することができ、アーカイブの起点で決定されます。

使用例

ディレクトリを書庫に圧縮し、実行します。

$ python -m zipapp myapp
$ python myapp.pyz
<output from myapp>

The same can be done using the create_archive() function:

>>> import zipapp
>>> zipapp.create_archive('myapp.pyz', 'myapp')

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:

  1. Create your application in a directory as normal, so you have a myapp directory containing a __main__.py file, and any supporting application code.

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

  3. Optionally, delete the .dist-info directories created by pip in the myapp directory. These hold metadata for pip to manage the packages, and as you won't be making any further use of pip they aren't required - although it won't do any harm if you leave them.

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

Making a Windows executable

On Windows, registration of the .pyz extension is optional, and furthermore, there are certain places that don't recognise registered extensions "transparently" (the simplest example is that subprocess.run(['myapp']) won't find your application - you need to explicitly specify the extension).

On Windows, therefore, it is often preferable to create an executable from the zipapp. This is relatively easy, although it does require a C compiler. The basic approach relies on the fact that zipfiles can have arbitrary data prepended, and Windows exe files can have arbitrary data appended. So by creating a suitable launcher and tacking the .pyz file onto the end of it, you end up with a single-file executable that runs your application.

A suitable launcher can be as simple as the following:

#define Py_LIMITED_API 1
#include "Python.h"

#define WIN32_LEAN_AND_MEAN
#include <windows.h>

#ifdef WINDOWS
int WINAPI wWinMain(
    HINSTANCE hInstance,      /* handle to current instance */
    HINSTANCE hPrevInstance,  /* handle to previous instance */
    LPWSTR lpCmdLine,         /* pointer to command line */
    int nCmdShow              /* show state of window */
)
#else
int wmain()
#endif
{
    wchar_t **myargv = _alloca((__argc + 1) * sizeof(wchar_t*));
    myargv[0] = __wargv[0];
    memcpy(myargv + 1, __wargv, __argc * sizeof(wchar_t *));
    return Py_Main(__argc+1, myargv);
}

If you define the WINDOWS preprocessor symbol, this will generate a GUI executable, and without it, a console executable.

To compile the executable, you can either just use the standard MSVC command line tools, or you can take advantage of the fact that distutils knows how to compile Python source:

>>> from distutils.ccompiler import new_compiler
>>> import distutils.sysconfig
>>> import sys
>>> import os
>>> from pathlib import Path

>>> def compile(src):
>>>     src = Path(src)
>>>     cc = new_compiler()
>>>     exe = src.stem
>>>     cc.add_include_dir(distutils.sysconfig.get_python_inc())
>>>     cc.add_library_dir(os.path.join(sys.base_exec_prefix, 'libs'))
>>>     # First the CLI executable
>>>     objs = cc.compile([str(src)])
>>>     cc.link_executable(objs, exe)
>>>     # Now the GUI executable
>>>     cc.define_macro('WINDOWS')
>>>     objs = cc.compile([str(src)])
>>>     cc.link_executable(objs, exe + 'w')

>>> if __name__ == "__main__":
>>>     compile("zastub.c")

The resulting launcher uses the "Limited ABI", so it will run unchanged with any version of Python 3.x. All it needs is for Python (python3.dll) to be on the user's PATH.

For a fully standalone distribution, you can distribute the launcher with your application appended, bundled with the Python "embedded" distribution. This will run on any PC with the appropriate architecture (32 bit or 64 bit).

Caveats

There are some limitations to the process of bundling your application into a single file. In most, if not all, cases they can be addressed without needing major changes to your application.

  1. 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).
  2. If you are shipping a Windows executable as described above, you either need to ensure that your users have python3.dll on their PATH (which is not the default behaviour of the installer) or you should bundle your application with the embedded distribution.
  3. The suggested launcher above uses the Python embedding API. This means that in your application, sys.executable will be your application, and not a conventional Python interpreter. Your code and its dependencies need to be prepared for this possibility. For example, if your application uses the multiprocessing module, it will need to call multiprocessing.set_executable() to let the module know where to find the standard Python interpreter.

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:

  1. 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.
  2. 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 »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

Python ランタイムサービス

この章では、Python インタープリタや Python 環境に深く関連する各種の機能を解説します。以下に一覧を示します:

  • sys --- システムパラメータと関数
  • sysconfig --- Python の構成情報にアクセスする
    • 構成変数
    • インストールパス
    • その他の関数
    • sysconfig をスクリプトとして使う
  • builtins --- 組み込みオブジェクト
  • __main__ --- トップレベルのスクリプト環境
  • warnings --- 警告の制御
    • 警告カテゴリ
    • 警告フィルタ
      • Describing Warning Filters
      • Default Warning Filter
      • Overriding the default filter
    • 一時的に警告を抑制する
    • 警告のテスト
    • Updating Code For New Versions of Dependencies
    • 利用可能な関数
    • 利用可能なコンテキストマネージャー
  • dataclasses --- データクラス
    • モジュールレベルのデコレータ、クラス、関数
    • 初期化後の処理
    • クラス変数
    • 初期化限定変数
    • 凍結されたインスタンス
    • 継承
    • デフォルトファクトリ関数
    • 可変なデフォルト値
    • 例外
  • contextlib --- Utilities for with-statement contexts
    • ユーティリティ
    • 例とレシピ
      • 可変数個のコンテキストマネージャーをサポートする
      • __enter__ メソッドからの例外をキャッチする
      • __enter__ 実装内のクリーンアップ
      • try-finally + flag 変数パターンを置き換える
      • コンテキストマネージャーを関数デコレーターとして使う
    • Single use, reusable and reentrant context managers
      • Reentrant context managers
      • Reusable context managers
  • abc --- 抽象基底クラス
  • atexit --- 終了ハンドラ
    • atexit の例
  • traceback --- スタックトレースの表示または取得
    • TracebackException オブジェクト
    • StackSummary オブジェクト
    • FrameSummary オブジェクト
    • トレースバックの例
  • __future__ --- future 文の定義
  • gc --- ガベージコレクタインターフェース
  • inspect --- 活動中のオブジェクトの情報を取得する
    • 型とメンバー
    • ソースコードの情報取得
    • Signature オブジェクトで呼び出し可能オブジェクトを内省する
    • クラスと関数
    • インタープリタスタック
    • 属性の静的なフェッチ
    • ジェネレータおよびコルーチンの現在の状態
    • Code Objects Bit Flags
    • コマンドラインインターフェイス
  • site --- サイト固有の設定フック
    • readline の設定
    • モジュールの内容

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


sys --- システムパラメータと関数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

sys --- システムパラメータと関数

このモジュールでは、インタプリタで使用・管理している変数や、インタプリタの動作に深く関連する関数を定義しています。このモジュールは常に利用可能です。

sys.abiflags

Python が標準的な configure でビルトされた POSIX システムにおいて、 PEP 3149 に記述された ABI フラグを含みます。

バージョン 3.2 で追加.

sys.argv

Pythonスクリプトに渡されたコマンドライン引数のリスト。 argv[0] はスクリプトの名前となりますが、フルパス名かどうかは、OSによって異なります。コマンドライン引数に -c を付けて Pythonを起動した場合、 argv[0] は文字列 '-c' となります。スクリプト名なしでPythonを起動した場合、 argv[0] は空文字列になります。

標準入力もしくはコマンドライン引数で指定されたファイルのリストに渡ってループするには、 fileinput モジュールを参照してください。

sys.base_exec_prefix

Python の起動中、site.py が実行される前、exec_prefix と同じ値が設定されます。仮想環境 で実行されたのでなければ、この値は変化しません; site.py が仮想環境で使用されていると判断した場合、prefix および exec_prefix は仮想環境を示すよう変更され、base_prefix および base_exec_prefix は引き続き (仮想環境が作成された) ベースの Python インストール先を示します。

バージョン 3.3 で追加.

sys.base_prefix

Python の起動中、site.py が実行される前、prefix と同じ値が設定されます。仮想環境 で実行されたのでなければ、この値は変化しません; site.py が仮想環境で使用されていると検出した場合、prefix および exec_prefix は仮想環境を示すよう変更され、base_prefix および base_exec_prefix は引き続き (仮想環境が作成された) ベースの Python インストール先を示します。

バージョン 3.3 で追加.

sys.byteorder

プラットフォームのバイト順を示します。ビッグエンディアン (最上位バイトが先頭) のプラットフォームでは 'big', リトルエンディアン (最下位バイトが先頭) では 'little' となります。

sys.builtin_module_names

コンパイル時にPythonインタプリタに組み込まれた、全てのモジュール名のタプル(この情報は、他の手段では取得することができません。 modules.keys() は、インポートされたモジュールのみのリストを返します。)

sys.call_tracing(func, args)

トレーシングが有効な間、 func(*args) を呼び出します。トレーシングの状態は保存され、後で復元されます。これは、別のコードをチェックポイントから再帰的にデバッグするために、デバッガから呼び出されることを意図しています。

sys.copyright

Python インタプリタの著作権を表示する文字列です。

sys._clear_type_cache()

内部の型キャッシュをクリアします。型キャッシュは属性とメソッドの検索を高速化するために利用されます。この関数は、参照リークをデバッグするときに不要な参照を削除するため だけ に利用してください。

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。

sys._current_frames()

各スレッドの識別子を関数が呼ばれた時点のそのスレッドでアクティブになっている一番上のスタックフレームに結びつける辞書を返します。モジュール traceback の関数を使えばそのように与えられたフレームのコールスタックを構築できます。

この関数はデッドロックをデバッグするのに非常に有効です。デッドロック状態のスレッドの協調動作を必要としませんし、そういったスレッドのコールスタックはデッドロックである限りフリーズしたままです。デッドロックにないスレッドのフレームについては、そのフレームを調べるコードを呼んだ時にはそのスレッドの現在の実行状況とは関係ないところを指し示しているかもしれません。

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。

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 は 調べられない ことにも注意してください。

バージョン 3.7 で追加.

sys._debugmallocstats()

CPython のメモリアロケータの状態に関する低レベルの情報を標準エラー出力に出力します。

Python が configure 時に --with-pydebug オプションを指定してビルドされている場合、負荷のかかる一貫性チェックも行います。

バージョン 3.3 で追加.

CPython implementation detail: この関数は CPython 固有です。正確な出力形式は定義されていませんし、変更されるかもしれません。

sys.dllhandle

Integer specifying the handle of the 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の対話セッションで入力された式(expression)が評価されたときに呼び出されます。対話セッションの出力をカスタマイズする場合、 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.excepthook(type, value, traceback)

指定したトレースバックと例外を sys.stderr に出力します。

例外が発生し、その例外が捕捉されない場合、インタプリタは例外クラス・例外インスタンス・トレースバックオブジェクトを引数として sys.excepthook を呼び出します。対話セッション中に発生した場合はプロンプトに戻る直前に呼び出され、Pythonプログラムの実行中に発生した場合はプログラムの終了直前に呼び出されます。このトップレベルでの例外情報出力処理をカスタマイズする場合、 sys.excepthook に引数の数が三つの関数を指定します。

sys.__breakpointhook__
sys.__displayhook__
sys.__excepthook__

これらのオブジェクトはそれぞれ、プログラム起動時の breakpointhook, displayhook, excepthook の値を保存しています。 この値は、 breakpointhook, displayhook, excepthook に不正なオブジェクトや別のオブジェクトが指定された場合に、元の値に復旧するために使用します。

バージョン 3.7 で追加: __breakpointhook__

sys.exc_info()

現在処理中の例外を示す 3 個の値のタプルを返します。この値は、現在のスレッドおよび現在のスタックフレームのものです。現在のスタックフレームが例外処理中でない場合、例外処理中のスタックフレームが見つかるまでその呼び出したスタックフレームや呼び出し元などを調べます。ここで、"例外処理中" とは "except 節を実行中である" フレームを指します。どのスタックフレームでも、最後に処理した例外の情報のみを参照できます。

スタック上で例外が発生していない場合、3 個の None 値のタプルを返します。例外が発生している場合、(type, value, traceback) を返します。type は処理中の例外の型 (BaseException のサブクラス)を示します。value は例外インスタンス (例外の型のインスタンス) を、traceback は最初に例外が発生したポイントのコールスタックをカプセル化したトレースバックオブジェクト (リファレンスマニュアルを参照) を示します。

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])

Python を終了します。 exit() は SystemExit を送出するので、 try ステートメントの finally 節に終了処理を記述したり、上位レベルで例外を捕捉して exit 処理を中断したりすることができます。

オプション引数 arg には、終了ステータスとして整数 (デフォルトは0）や他の型のオブジェクトを指定することができます。整数を指定した場合、シェル等は 0 は "正常終了"、0 以外の整数を "異常終了" として扱います。多くのシステムでは、有効な終了ステータスは 0--127 で、これ以外の値を返した場合の動作は未定義です。システムによっては特定の終了コードに個別の意味を持たせている場合がありますが、このような定義は僅かしかありません。Unix プログラムでは構文エラーの場合には 2 を、それ以外のエラーならば 1 を返します。arg に None を指定した場合は、数値の 0 を指定した場合と同じです。それ以外の型のオブジェクトを指定すると、そのオブェクトが stderr に出力され、終了コードとして 1 を返します。エラー発生時には sys.exit("エラーメッセージ") と書くと、簡単にプログラムを終了することができます。

究極には、 exit() は例外を送出する "だけ" なので、これがメインスレッドから呼び出されたときは、プロセスを終了するだけで、例外は遮断されません。

バージョン 3.6 で変更: Python インタープリタが (バッファされたデータを標準ストリームに吐き出すときのエラーなどの) SystemExit を捕捉した後の後始末でエラーが起きた場合、終了ステータスは 120 に変更されます。

sys.flags

コマンドラインフラグの状態を表す 構造体シーケンス です。各属性は読み出し専用になっています。

属性 | フラグ
debug | -d
inspect -i
interactive | -i
isolated | -I
optimize | -O または -OO
dont_write_bytecode -B
no_user_site | -s
no_site | -S
ignore_environment | -E
verbose | -v
bytes_warning | -b
quiet | -q
hash_randomization | -R
dev_mode | -X dev
utf8_mode | -X utf8

バージョン 3.2 で変更: 新しい -q 向けに quiet 属性が追加されました。

バージョン 3.2.3 で追加: hash_randomization 属性が追加されました。

バージョン 3.3 で変更: 廃止済みの division_warning 属性を削除しました。

バージョン 3.4 で変更: -I isolated フラグ向けに isolated 属性が追加されました。

バージョン 3.7 で変更: 新しい -X dev フラグ向けに dev_mode 属性が追加され、新しい -X utf8 フラグ向けに utf8_mode 属性が追加されました。

sys.float_info

float 型に関する情報を保持している 構造体シーケンス です。精度と内部表現に関する低レベル情報を含んでいます。これらの値は 'C' 言語の標準ヘッダファイル float.h で定義されている様々な浮動小数点定数に対応しています。詳細は 1999 ISO/IEC C standard [C99] の 5.2.4.2.2 節 'Characteristics of floating types' を参照してください。

属性 | float.h のマクロ | 説明
epsilon | DBL_EPSILON | 1と、その次の表現可能なfloat値の差
dig | DBL_DIG | 浮動小数点数で正確に表示できる最大の10進数桁; 以下参照
mant_dig | DBL_MANT_DIG | 浮動小数点精度: 浮動小数点数の主要部の桁 base-radix
max | DBL_MAX | floatが表せる最大の(infiniteではない)値
max_exp | DBL_MAX_EXP | floatが radix**(e-1) で表現可能な、最大の整数 e
max_10_exp | DBL_MAX_10_EXP | float が 10**e で表現可能な、最大の整数 e
min | DBL_MIN | float が表現可能な最小の正の値
min_exp | DBL_MIN_EXP | radix**(e-1) が正規化floatであるような最小の整数 e
min_10_exp | DBL_MIN_10_EXP | 10**e が正規化floatであるような最小の整数 e
radix | FLT_RADIX | 指数部の基数
rounds | FLT_ROUNDS | 算術演算で利用される丸めモードを表す整数定数。これはインタプリタ起動時のシステムの FLT_ROUNDS マクロの値を示します。取りうる値とその意味については、C99 標準の 5.2.4.2.2 節を参照してください。

sys.float_info.dig に対してはさらに説明が必要です。もし、文字列 s が表す 10 進数の有効桁数が多くても sys.float_info.dig の時には、 s を浮動小数点数に変換して戻すと同じ 10 進数を表す文字列に復元されます:

>>> 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 と同じように振る舞います。

バージョン 3.1 で追加.

sys.getallocatedblocks()

サイズに関わりなく、現在インタプリタから確保されたメモリブロックの数を返します。 この関数は主にメモリリークを追跡しバグを見付けるのに便利です。 インタプリタの内部的なキャッシュがあるために、呼び出しごとに結果が変わることがあります。より結果が予測しやすくなる _clear_type_cache() や gc.collect() を呼ぶ必要があるかもしれません。

Python のあるビルドや実装が適切にこの情報を計算できない場合は、その代わりに getallocatedblocks() は 0 を返すことが許されています。

バージョン 3.4 で追加.

sys.getandroidapilevel()

ビルト時の Android のバージョンを整数で返します。

利用可能な環境: Android 。

バージョン 3.7 で追加.

sys.getcheckinterval()

インタプリタの "チェックインターバル (check interval)" を返します; setcheckinterval() を参照してください。

バージョン 3.2 で非推奨: 代わりに getswitchinterval() を使ってください。

sys.getdefaultencoding()

Unicode 実装で使用される現在のデフォルトエンコーディング名を返します。

sys.getdlopenflags()

dlopen() の呼び出しで使われるフラグの現在の値を返します。 フラグの値のシンボル名は os から見付けられます (RTLD_xxx 定数、例えば os.RTLD_LAZY)。

利用可能な環境: Unix。

sys.getfilesystemencoding()

Unicode ファイル名と bytes ファイル名どうしを変換するのに使われるエンコーディングの名前を返します。 最良の互換性のために、たとえファイル名の表現に bytes がサポートされていたとしても、全てのケースで str をファイル名に使うべきです。 ファイル名を受け取ったり返したりする関数は str と bytes をサポートし、すぐにシステムにとって好ましい表現に変換すべきです。

このエンコーディングは常に ASCII 互換です。

os.fsencode() や os.fsdecode() を、正しいエンコーディングやエラーモードが使われていることを保証するために使うべきです。

  • UTF-8 モードでは、どのプラットフォームでもエンコーディングは utf-8 です。
  • Mac OS X では、エンコーディングは 'utf-8' となります。
  • Unix では、エンコーディングはロケールのエンコーディングです。
  • Windows では、エンコーディングはユーザの設定によって 'utf-8' または 'mbcs' のどちらかになります。

バージョン 3.2 で変更: getfilesystemencoding() の結果が None になることはなくなりました。

バージョン 3.6 で変更: Windows はもう 'mbcs' を返す保証は無くなりました。 より詳しいことは PEP 529 および _enablelegacywindowsfsencoding() を参照してください。

バージョン 3.7 で変更: UTF-8 モードで 'utf-8' を返すようになりました。

sys.getfilesystemencodeerrors()

Unicode ファイルシステムと bytes ファイル名どうしの変換で使われるエラーモード名を返します。 エンコーディング名は getfilesystemencoding() から返されます。

os.fsencode() や os.fsdecode() を、正しいエンコーディングやエラーモードが使われていることを保証するために使うべきです。

バージョン 3.6 で追加.

sys.getrefcount(object)

object の参照数を返します。 object は (一時的に) getrefcount() からも参照されるため、参照数は予想される数よりも 1 多くなります。

sys.getrecursionlimit()

現在の最大再帰数を返します。最大再帰数は、Python インタプリタスタックの最大の深さです。この制限は Python プログラムが無限に再帰し、C スタックがオーバーフローしてクラッシュすることを防止するために設けられています。この値は setrecursionlimit() で指定することができます。

sys.getsizeof(object[, default])

object のサイズをバイト数で返します。object は任意の型のオブジェクトです。すべての組み込みオブジェクトは正しい値を返します。サードパーティー製の型については実装依存になります。

オブジェクトに直接起因するメモリ消費のみを表し、参照するオブジェクトは含みません。

オブジェクトがサイズを取得する手段を提供していない時は default が返されます。default が指定されていない場合は TypeError が送出されます。

getsizeof() は object の __sizeof__ メソッドを呼び出し、そのオブジェクトがガベージコレクタに管理されていた場合はガベージコレクタのオーバーヘッドを増やします。

getsizeof() を再帰的に使い、コンテナとその中身のサイズを割り出す例は、 再帰的な sizeof のレシピ を参照してください。

sys.getswitchinterval()

インタプリタの "スレッド切り替え間隔" を返します。setswitchinterval() を参照してください。

バージョン 3.2 で追加.

sys._getframe([depth])

コールスタックからフレームオブジェクトを返します。オプション引数 depth を指定すると、スタックのトップから depth だけ下のフレームオブジェクトを取得します。 depth がコールスタックよりも深ければ、 ValueError が発生します。 depth のデフォルト値は 0 で、この場合はコールスタックのトップのフレームを返します。

CPython implementation detail: この関数は、内部的かつ特殊な目的にのみ利用されるべきです。全ての Python 実装で存在することが保証されているわけではありません。

sys.getprofile()

setprofile() 関数で設定したプロファイラ関数を取得します。

sys.gettrace()

settrace() 関数で設定したトレース関数を取得します。

CPython implementation detail: 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 は 2 (VER_PLATFORM_WIN32_NT) になっているでしょう。

product_type は、以下の値のいずれかになります。:

定数 | 意味
1 (VER_NT_WORKSTATION) | システムはワークステーションです。
2 (VER_NT_DOMAIN_CONTROLLER) | システムはドメインコントローラです。
3 (VER_NT_SERVER) | システムはサーバですが、ドメインコントローラではありません。

この関数は、Win32 GetVersionEx() 関数を呼び出します。これらのフィールドに関する詳細は OSVERSIONINFOEX() についてのマイクロソフトのドキュメントを参照してください。

platform_version returns 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. It is intended for use in logging rather than for feature detection.

利用可能な環境: 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 を引数に取る関数と、イベントループが非同期ジェネレータの終了処理をスケジューリングするのに使う関数であることが求められます。

バージョン 3.6 で追加: より詳しくは PEP 525 を参照をしてください。

注釈

This function has been added on a provisional basis (see PEP 411 for details.)

sys.get_coroutine_origin_tracking_depth()

Get the current coroutine origin tracking depth, as set by set_coroutine_origin_tracking_depth().

バージョン 3.7 で追加.

注釈

This function has been added on a provisional basis (see PEP 411 for details.) Use it only for debugging purposes.

sys.get_coroutine_wrapper()

Returns None, or a wrapper set by set_coroutine_wrapper().

バージョン 3.5 で追加: より詳しくは PEP 492 を参照をしてください。

注釈

This function has been added on a provisional basis (see PEP 411 for details.) Use it only for debugging purposes.

バージョン 3.7 で非推奨: The coroutine wrapper functionality has been deprecated, and will be removed in 3.8. See bpo-32591 for details.

sys.hash_info

数値のハッシュ実装のパラメータを与える 構造体シーケンス です。数値型のハッシュ化についての詳細は 数値型のハッシュ化 を参照してください。

属性 | 説明
width | ハッシュ値に利用されるビット幅
modulus | 数値ハッシュ計算に利用される素数の法
inf | 正の無限大に対して返されるハッシュ値
nan | nan に対して返されるハッシュ値
imag | 複素数の虚部を表すための乗数
algorithm | str、bytes、memoryview オブジェクトのハッシュアルゴリズムの名前
hash_bits | ハッシュアルゴリズムの内部出力サイズ
seed_bits | ハッシュアルゴリズムのシードキーのサイズ

バージョン 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 進数に変換しなければ値の意味を持ちません。より読みやすいバージョン番号が必要な場合には 構造体シーケンス sys.version_info を使用してください。

More details of hexversion can be found at 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 may contain additional attributes specific to the Python implementation. These non-standard attributes must start with an underscore, and are not described here. Regardless of its contents, sys.implementation will not change during a run of the interpreter, nor between implementation versions. (It may change between Python language versions, however.) See PEP 421 for more information.

バージョン 3.3 で追加.

sys.int_info

Python における整数の内部表現に関する情報を保持する、構造体シーケンス です。この属性は読み出し専用です。

属性 | 説明
bits_per_digit | 各桁に保持されるビットの数です。Python の整数は、内部的に 2**int_info.bits_per_digit を基数として保存されます
sizeof_digit | 桁を表すために使われる、C 型の大きさ (バイト) です

バージョン 3.1 で追加.

sys.__interactivehook__

この属性が存在する場合、インタープリタが 対話モード で起動したときに値は (引数なしで) 自動的に呼ばれます。これは PYTHONSTARTUP ファイルの読み込み後に行われるため、それにこのフックを設定することが出来ます。site モジュールで 設定します。

バージョン 3.4 で追加.

sys.intern(string)

string を "隔離" された文字列のテーブルに入力し、隔離された文字列を返します -- この文字列は string 自体かコピーです。隔離された文字列は辞書検索のパフォーマンスを少しだけ向上させるのに有効です -- 辞書中のキーが隔離されており、検索するキーが隔離されている場合、(ハッシュ化後の) キーの比較は文字列の比較ではなくポインタの比較で行うことができるからです。通常、Python プログラム内で利用されている名前は自動的に隔離され、モジュール、クラス、またはインスタンス属性を保持するための辞書は隔離されたキーを持っています。

隔離された文字列はイモータルではありません。その恩恵を受けるためには intern() の返り値への参照を維持しなくてはなりません。

sys.is_finalizing()

Return True if the Python interpreter is shutting down, False otherwise.

バージョン 3.5 で追加.

sys.last_type
sys.last_value
sys.last_traceback

通常は定義されておらず、捕捉されない例外が発生してインタプリタがエラーメッセージとトレースバックを出力した場合にのみ設定されます。この値は、対話セッション中にエラーが発生した時、デバッグモジュールをロード (例: import pdb; pdb.pm() など。詳細は pdb モジュールを参照) して発生したエラーを調査する場合に利用します。デバッガをロードすると、プログラムを再実行せずに情報を取得することができます

変数の意味は、上記 exc_info() の返り値と同じです。

sys.maxsize

Py_ssize_t 型の変数が取りうる最大値を示す整数です。通常、32 ビットプラットフォームでは 2**31 - 1、64 ビットプラットフォームでは 2**63 - 1 になります。

sys.maxunicode

Unicode コードポイントの最大値を示す整数、すなわち 1114111 (16 進数で 0x10FFFF) です。

バージョン 3.3 で変更: PEP 393 以前は、オプション設定に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. 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. Earlier versions of Python looked for a method called find_module(). This is still called as a fallback if a meta_path entry doesn't have a find_spec() method.

sys.modules

既に読み込まれているモジュールとモジュール名がマップされている辞書です。これを使用してモジュールの強制再読み込みやその他のトリック操作が行えます。ただし、この辞書の置き換えは想定された操作ではなく、必要不可欠なアイテムを削除することで Python が異常終了してしまうかもしれません。

sys.path

モジュールを検索するパスを示す文字列のリスト。 PYTHONPATH 環境変数と、インストール時に指定したデフォルトパスで初期化されます。

起動時に初期化された後、リストの先頭 (path[0]) には Python インタプリタを起動したスクリプトのあるディレクトリが挿入されます。スクリプトのディレクトリがない (インタプリタが対話セッションで起動された時や、スクリプトを標準入力から読み込んだ場合など) 場合、 path[0] は空文字列となり、Python はカレントディレクトリからモジュールの検索を開始します。スクリプトディレクトリは、 PYTHONPATH で指定したディレクトリの 前 に挿入されますので注意が必要です。

プログラムはその目的のために、このリストを自由に修正できます。文字列とバイト列だけが sys.path に追加でき、 ほかの全てのデータ型はインポート中に無視されます。

参考

site モジュールのドキュメントで、 .pth ファイルを使って sys.path を拡張する方法を解説しています。

sys.path_hooks

path を引数にとって、その path に対する finder の作成を試みる呼び出し可能オブジェクトのリスト。 finder の作成に成功したら、その呼出可能オブジェクトのは finder を返します。失敗した場合は、 ImportError を発生させます。

オリジナルの仕様は PEP 302 を参照してください。

sys.path_importer_cache

finder オブジェクトのキャッシュ機能を果たす辞書です。キーは sys.path_hooks に渡されているパスで、値は見つかった finder になります。パスが正常なファイルシステムパスであり、finder が sys.path_hooks 上に見つからない場合は None が格納されます。

オリジナルの仕様は PEP 302 を参照してください。

バージョン 3.3 で変更: finder が見つからない時、imp.NullImporter ではなく None が格納されるようになりました。

sys.platform

プラットフォームを識別する文字列で、sys.path にプラットフォーム固有のサブディレクトリを追加する場合などに利用します。

Linux を除く Unix システムでは、uname -s が返す小文字の OS 名に uname -r が返すバージョン名の先頭を追加したものになります (例: 'sunos5'、'freebsd8')。この値は Python がビルドされた時点のもの です。システム固有のバージョンをテストする場合を除き、以下のような用法で使うことを推奨します:

if sys.platform.startswith('freebsd'):
    # FreeBSD-specific code here...
elif sys.platform.startswith('linux'):
    # Linux-specific code here...

その他のシステムでは以下の値になります:

システム | platform の値
Linux | 'linux'
Windows | 'win32'
Windows/Cygwin | 'cygwin'
Mac OS X | 'darwin'

バージョン 3.3 で変更: Linuxでは、 sys.platform はもはやメジャーバージョン番号を含みません。 'linux2' や 'linux3' の代わりに 'linux' が格納されます。 古いPythonではこの変数はバージョン番号を含むため、前述した startswith イディオムを使用することをお勧めします。

参考

os.name が持つ情報はおおざっぱな括りであり、os.uname() はシステムに依存したバージョン情報になります。

platform モジュールはシステムの詳細な識別情報をチェックする機能を提供しています。

sys.prefix

Python のプラットフォーム非依存なファイルがインストールされているディレクトリの接頭辞を示す文字列です。この値はサイト固有であり、デフォルトでは '/usr/local' ですが、ビルド時に configure スクリプトの --prefix 引数で指定する事ができます。Python ライブラリの主要部分は prefix/lib/pythonX.Y にインストールされ、プラットフォーム非依存なヘッダファイル (pyconfig.h 以外すべて) は prefix/include/pythonX.Y に格納されます (X.Y は 3.2 のような Python のバージョン番号)。

注釈

仮想環境 で起動されている場合、この値は site.py によって仮想環境を示すよう変更されます。実際の Python のインストール先は base_prefix から取得できます。

sys.ps1
sys.ps2

インタプリタの一次プロンプト、二次プロンプトを指定する文字列。対話モードで実行中のみ定義され、初期値は '>>> ' と '... ' です。文字列以外のオブジェクトを指定した場合、インタプリタが対話コマンドを読み込むごとにオブジェクトの str() を評価します。この機能は、動的に変化するプロンプトを実装する場合に利用します。

sys.setcheckinterval(interval)

インタプリタの "チェック間隔" を示す整数値を指定します。この値はスレッドスイッチやシグナルハンドラのチェックを行う周期を決定します。デフォルト値は 100 で、この場合 100 の Python 仮想命令を実行するとチェックを行います。この値を大きくすればスレッドを利用するプログラムのパフォーマンスが向上します。この値が 0 以下 の場合、各仮想命令を実行するたびにチェックを行い、レスポンス速度が最大になりますがオーバヘッドもまた最大となります。

バージョン 3.2 で非推奨: スレッドスイッチングと非同期タスクの内部ロジックが変更されたため、この関数はもはや効果がありません 。代わりに setswitchinterval() を使用してください。

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

Profile functions should have three arguments: frame, event, and arg. frame is the current stack frame. event is a string: 'call', 'return', 'c_call', 'c_return', or 'c_exception'. arg depends on the event type.

event には以下の意味があります。

'call'
A function is called (or some other code block entered). The profile function is called; arg is None.
'return'
A function (or other code block) is about to return. The profile function is called; arg is the value that will be returned, or None if the event is caused by an exception being raised.
'c_call'
C 関数(拡張関数かビルトイン関数)が呼ばれようとしている。 arg は C 関数オブジェクト。
'c_return'
C 関数から戻った。 arg は C の関数オブジェクト。
'c_exception'
C 関数が例外を発生させた。 arg は C の関数オブジェクト。
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スレッドに割り当てられたタイムスライスの理想的な処理時間です。実際の値はより高くなることがあり、特に長時間実行される内部関数やメソッドが使われた時や、他にスレッドが、その間隔の終了をオペレーティングシステムが決定するようスケジュールされた場合などが該当します。インタプリタは自身のスケジューラを持ちません。

バージョン 3.2 で追加.

sys.settrace(tracefunc)

システムのトレース関数を登録します。トレース関数は Python のソースデバッガを実装するために使用できます。トレース関数はスレッド毎に設定することができるので、デバッグを行うすべてのスレッドで settrace() を呼び出し、トレース関数を登録してください。

Trace functions should have three arguments: frame, event, and arg. frame is the current stack frame. event is a string: 'call', 'line', 'return', 'exception' or 'opcode'. arg depends on the event type.

trace 関数は (event に 'call' を渡された状態で) 新しいローカルスコープに入るたびに呼ばれます。この場合、そのスコープで利用するローカルの trace 関数への参照か、そのスコープを trace しないのであれば None を返します。

ローカル trace 関数は自身への参照 (もしくはそのスコープの以降の trace を行う別の関数) を返すべきです。もしくは、そのスコープの trace を止めるために None を返します。

If there is any error occurred in the trace function, it will be unset, just like settrace(None) is called.

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' イベントは各レベルで発生します。

code と frame オブジェクトについては、 標準型の階層 を参照してください。

CPython implementation detail: settrace() 関数は、デバッガ、プロファイラ、カバレッジツール等で使うためだけのものです。この関数の挙動は言語定義よりも実装プラットフォームの分野の問題で、全ての Python 実装で利用できるとは限りません。

バージョン 3.7 で変更: 'opcode' event type added; f_trace_lines and f_trace_opcodes attributes added to frames

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.

バージョン 3.6 で追加: See PEP 525 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

注釈

This function has been added on a provisional basis (see PEP 411 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.

バージョン 3.7 で追加.

注釈

This function has been added on a provisional basis (see PEP 411 for details.) Use it only for debugging purposes.

sys.set_coroutine_wrapper(wrapper)

Allows intercepting creation of coroutine objects (only ones that are created by an async def function; generators decorated with types.coroutine() or asyncio.coroutine() will not be intercepted).

The wrapper argument must be either:

  • a callable that accepts one argument (a coroutine object);
  • None, to reset the wrapper.

If called twice, the new wrapper replaces the previous one. The function is thread-specific.

The wrapper callable cannot define new coroutines directly or indirectly:

def wrapper(coro):
    async def wrap(coro):
        return await coro
    return wrap(coro)
sys.set_coroutine_wrapper(wrapper)

async def foo():
    pass

# The following line will fail with a RuntimeError, because
# ``wrapper`` creates a ``wrap(coro)`` coroutine:
foo()

See also get_coroutine_wrapper().

バージョン 3.5 で追加: より詳しくは PEP 492 を参照をしてください。

注釈

This function has been added on a provisional basis (see PEP 411 for details.) Use it only for debugging purposes.

バージョン 3.7 で非推奨: The coroutine wrapper functionality has been deprecated, and will be removed in 3.8. See bpo-32591 for details.

sys._enablelegacywindowsfsencoding()

Changes the default filesystem encoding and errors mode 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.

利用可能な環境: Windows 。

バージョン 3.6 で追加: より詳しくは PEP 529 を参照をしてください。

sys.stdin
sys.stdout
sys.stderr

インタプリタが使用する、それぞれ標準入力、標準出力、および標準エラー出力の ファイルオブジェクト です:

  • stdin は (input() の呼び出しも含む) すべての対話型入力に使われます。
  • stdout は print() および expression 文の出力と、input() のプロンプトに使用されます。
  • インタプリタ自身のプロンプトおよびエラーメッセージは stderr に出力されます。

これらのストリームは open() が返すような通常の テキストファイル です。引数は以下のように選択されます:

  • The character encoding is platform-dependent. Under Windows, if the stream is interactive (that is, if its isatty() method returns True), the console codepage is used, otherwise the ANSI code page. Under other platforms, the locale encoding is used (see locale.getpreferredencoding()).

    Under all platforms though, you can override this value by setting the PYTHONIOENCODING environment variable before starting Python.

  • When interactive, stdout and stderr streams are line-buffered. Otherwise, they are block-buffered like regular text files. You can override this value with the -u command-line option.

注釈

標準ストリームにバイナリーデータの読み書きを行うには下位のバイナリー 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* オブジェクトが(訳注:別のファイルライクオブジェクトに)リダイレクトされている場合でも、実際の標準ストリームへの出力に利用できます。

また、標準ストリームが壊れたオブジェクトに置き換えられた場合に、動作する実際のファイルを復元するために利用することもできます。しかし、明示的に置き換え前のストリームを保存しておき、そのオブジェクトを復元る事を推奨します。

注釈

Under some conditions stdin, stdout and stderr as well as the original values __stdin__, __stdout__ and __stderr__ can be None. It is usually the case for Windows GUI apps that aren't connected to a console and Python apps started with pythonw.

sys.thread_info

スレッドの実装に関する情報が格納された 構造体シーケンス です。

属性 | 説明
name

スレッド実装の名前:

  • 'nt': Windows スレッド
  • 'pthread': POSIX スレッド
  • 'solaris': Solaris スレッド
lock

ロック実装の名前:

  • 'semaphore': セマフォを使用するロック
  • 'mutex+cond': mutex と条件変数を使用するロック
  • None この情報が不明の場合
version | Name and version of the thread library. It is a string, or None if this information is unknown.

バージョン 3.3 で追加.

sys.tracebacklimit

捕捉されない例外が発生した時、出力されるトレースバック情報の最大レベル数を指定する整数値(デフォルト値は 1000)。 0 以下の値が設定された場合、トレースバック情報は出力されず例外型と例外値のみが出力されます。

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 first three characters of version. 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._xoptions

A dictionary of the various implementation-specific flags passed through the -X command-line option. Option names are either mapped to their values, if given explicitly, or to True. Example:

$ ./python -Xa=b -Xc
Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys._xoptions
{'a': 'b', 'c': True}

CPython implementation detail: この -X によって渡されたオプションにアクセスする方法は CPython 固有です。他の実装ではそれらは他の意味でエクスポートされるか、あるいは何もしません。

バージョン 3.2 で追加.

出典

[C99] ISO/IEC 9899:1999. "Programming languages -- C." この標準のパブリックドラフトが参照できます: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


sysconfig --- Python の構成情報にアクセスする

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

sysconfig --- Python の構成情報にアクセスする

バージョン 3.2 で追加.

ソースコード: Lib/sysconfig.py

sysconfig モジュールは、インストールパスのリストや、現在のプラットフォームに関連した構成などの、Python の構成情報 (configuration information) へのアクセスを提供します。

構成変数

Python の配布物は、Python 自体のバイナリや、distutils によってコンパイルされる外部の C 拡張をビルドするために必要な、Makefile と pyconfig.h ヘッダーファイルを含んでいます。

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 はプラットフォームとインストールオプションによって、異なるインストールスキームを利用します。このスキームは、os.name の値に基づいてユニークな識別子で sysconfig に格納されます。

distutils やそれに基づいたシステムによって新しいコンポーネントをインストールするときは、同じスキームに従ってファイルを正しい場所にコピーします。

Python は現在7つのスキームをサポートしています:

  • posix_prefix: Linux や Mac OS X などの Posix プラットフォーム用のスキームです。これは Python やコンポーネントをインストールするときに使われるデフォルトのスキームです。
  • posix_home: インストール時に home オプションが利用された場合における、Posix プラットフォーム用のスキームです。このスキームはコンポーネントが Distutils に特定の home prefix を指定してインストールされたときに利用されます。
  • posix_user: Distutils に user オプションを指定してコンポーネントをインストールするときに使われる、Posix プラットフォーム用のスキームです。このスキームはユーザーのホームディレクトリ以下に配置されたパスヲ定義します。
  • nt: Windows などの NT プラットフォーム用のスキームです。
  • nt_user: user オプションが利用された場合の、NT プラットフォーム用のスキームです。

各スキームは、ユニークな識別子を持ったいくつかのパスの集合から成っています。現在 Python は8つのパスを利用します:

  • stdlib: プラットフォーム非依存の、標準 Python ライブラリファイルを格納するディレクトリ.
  • platstdlib: プラットフォーム依存の、標準 Python ライブラリファイルを格納するディレクトリ.
  • platlib: プラットフォーム依存の、site ごとのファイルを格納するディレクトリ。
  • purelib: プラットフォーム非依存の、site ごとのファイルを格納するディレクトリ。
  • include: プラットフォーム非依存のヘッダーファイルを格納するディレクトリ。
  • platinclude: プラットフォーム依存の、ヘッダーファイルを格納するディレクトリ。
  • scripts: スクリプトファイルのためのディレクトリ。
  • data: データファイルのためのディレクトリ。

sysconfig はこれらのパスを決定するためのいくつかの関数を提供しています。

sysconfig.get_scheme_names()

現在 sysconfig でサポートされているすべてのスキームを格納したタプルを返します。

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() が返すリストに含まれる値でなければなりません。指定されなかった場合は、現在のプラットフォームでのデフォルトスキームが利用されます。

vars が指定された場合、get_config_vars() が返す辞書をアップデートする変数辞書でなければなりません。

expand が False に設定された場合、パスは変数を使って展開されません。

name が見つからない場合、None を返します。

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()

現在のプラットフォームを識別するための文字列を返します。

This is used mainly to distinguish platform-specific build directories and platform-specific built distributions. Typically includes the OS name and version and the architecture (as supplied by 'os.uname()'), although the exact information included depends on the OS; e.g., on Linux, the kernel version isn't particularly important.

返される値の例:

  • linux-i586
  • linux-alpha (?)
  • solaris-2.6-sun4u

Windows では以下のどれかを返します:

  • win-amd64 (64bit Windows on AMD64, aka x86_64, Intel64, and EM64T)
  • win32 (その他すべて - 具体的には sys.platform が返す値)

Mac OS X では以下のどれかを返します:

  • 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() が返す情報を標準出力に出力します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


builtins --- 組み込みオブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

builtins --- 組み込みオブジェクト

このモジュールは 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 upper-case.'''

    def __init__(self, f):
        self._f = f

    def read(self, count=-1):
        return self._f.read(count).upper()

    # ...

ほとんどのモジュールではグローバル変数の一部として __builtins__ が利用できるようになっています。 __builtins__ の内容は通常このモジュールそのものか、あるいはこのモジュールの __dict__ 属性です。これは実装の詳細部分なので、異なる Python の実装では __builtins__ は使われていないこともあります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


__main__ --- トップレベルのスクリプト環境

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

__main__ --- トップレベルのスクリプト環境

'__main__' はトップレベルのコードが実行されるスコープの名前です。モジュールが、標準入力から読み込まれたとき、スクリプトとして実行されたとき、あるいはインタラクティブプロンプトのとき、__name__ には '__main__' が設定されます。

モジュールは、自身の __name__ をチェックすることでメインスコープで実行されているかどうかを確認できます。これはモジュールがスクリプトとして、あるいはインポートでなく python -m で起動されたときに実行するコードの条件として使用できる一般的なイディオムです:

if __name__ == "__main__":
    # execute only if run as a script
    main()

パッケージについては、__main__.py モジュールを用意することで同じ効果を得られます。__main__.py にモジュールが -m オプションで呼びだされたときに実行したいコードを書くことができます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


warnings --- 警告の制御

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

warnings --- 警告の制御

ソースコード: Lib/warnings.py

警告メッセージは一般に、ユーザに警告しておいた方がよいような状況下にプログラムが置かれているが、その状況は (通常は) 例外を送出したりそのプログラムを終了させるほどの正当な理由がないといった状況で発されます。例えば、プログラムが古いモジュールを使っている場合には警告を発したくなるかもしれません。

Python プログラマは、このモジュールの warn() 関数を使って警告を発することができます。(C 言語のプログラマは PyErr_WarnEx() を使います; 詳細は 例外処理 を参照してください)。

警告メッセージは通常 sys.stderr に出力されますが、その処理方法は柔軟に変更することができます。すべての警告を無視することも、警告を例外に変更することもできます。警告の処理方法は警告カテゴリ (以下参照)、警告メッセージテキスト、そして警告を発したソースコード上の場所に基づいて変更することができます。ソースコード上の同じ場所に対して特定の警告が繰り返された場合、通常は抑制されます。

警告制御には 2 つの段階 (stage) があります: 第一に、警告が発されるたびに、メッセージを出力すべきかどうかの決定が行われます; 次に、メッセージを出力するなら、メッセージはユーザによって設定が可能なフックを使って書式化され印字されます。

警告メッセージを出力するかどうかの決定は、警告フィルタによって制御されます。警告フィルタは一致規則 (matching rule)と動作からなるシーケンスです。 filterwarnings() を呼び出して一致規則をフィルタに追加することができ、 resetwarnings() を呼び出してフィルタを標準設定の状態にリセットすることができます。

警告メッセージの印字は showwarning() を呼び出して行うことができ、この関数は上書きすることができます; この関数の標準の実装では、 formatwarning() を呼び出して警告メッセージを書式化しますが、この関数についても自作の実装を使うことができます。

参考

logging.captureWarnings() を使うことで、標準ロギング基盤ですべての警告を扱うことができます。

警告カテゴリ

There are a number of built-in exceptions that represent warning categories. This categorization is useful to be able to filter out groups of warnings.

While these are technically built-in exceptions, they are documented here, because conceptually they belong to the warnings mechanism.

標準の警告カテゴリをユーザの作成したコード上でサブクラス化することで、さらに別の警告カテゴリを定義することができます。警告カテゴリは常に Warning クラスのサブクラスでなければなりません。

The following warnings category classes are currently defined:

Class | 説明
Warning | すべての警告カテゴリクラスの基底クラスです。 Exception のサブクラスです。
UserWarning | warn() の標準のカテゴリです。
DeprecationWarning | Base category for warnings about deprecated features when those warnings are intended for other Python developers (ignored by default, unless triggered by code in __main__).
SyntaxWarning | その文法機能があいまいであることを示す警告カテゴリの基底クラスです。
RuntimeWarning | そのランタイム機能があいまいであることを示す警告カテゴリの基底クラスです。
FutureWarning | Base category for warnings about deprecated features when those warnings are intended for end users of applications that are written in 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.

警告フィルタ

警告フィルタは、ある警告を無視すべきか、表示すべきか、あるいは (例外を送出する) エラーにするべきかを制御します。

Conceptually, the warnings filter maintains an ordered list of filter specifications; any specific warning is matched against each filter specification in the list in turn until a match is found; the filter determines the disposition of the match. Each entry is a tuple of the form (action, message, category, module, lineno), where:

  • 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 は正規表現を含む文字列で、警告メッセージの先頭はこのパターンに一致しなければなりません。正規表現は常に大小文字の区別をしないようにコンパイルされます。

  • category はクラス (Warning のサブクラス) です。警告クラスはこのクラスのサブクラスに一致しなければなりません。

  • 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"
                             # and any subpackages of "mymodule"

Default Warning Filter

By default, Python installs several warning filters, which can be overridden by the -W command-line option, the PYTHONWARNINGS environment variable and calls to 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 debug builds, 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)

警告を発するか、無視するか、あるいは例外を送出します。 category 引数が与えられた場合、警告カテゴリクラスでなければなりません (上記を参照してください); 標準の値は UserWarning です。 message を Warning インスタンスで代用することもできますが、この場合 category は無視され、 message.__class__ が使われ、メッセージ文は str(message) になります。発された例外が前述した警告フィルタによってエラーに変更された場合、この関数は例外を送出します。引数 stacklevel は Python でラッパー関数を書く際に利用することができます。例えば:

def deprecation(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)

こうすることで、警告が参照するソースコード部分を、 deprecation() 自身ではなく deprecation() を呼び出した側にできます (というのも、前者の場合は警告メッセージの目的を台無しにしてしまうからです)。

source 引数が与えられた場合、これは ResourceWarning を発生させた破壊されたオブジェクトです。

バージョン 3.6 で変更: source 引数を追加しました。

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)

警告フィルタと showwarning() 関数をコピーし、終了時に復元するコンテキストマネージャーです。 record 引数が False (デフォルト値)だった場合、コンテキスト開始時には None を返します。もし record が True だった場合、リストを返します。このリストにはカスタムの showwarning() 関数(この関数は同時に sys.stdout への出力を抑制します)によってオブジェクトが継続的に追加されます。リストの中の各オブジェクトは、 showwarning() 関数の引数と同じ名前の属性を持っています。

module 引数は、保護したいフィルタを持つモジュールを取ります。 warnings を import して得られるモジュールの代わりに利用されます。この引数は、主に warnings モジュール自体をテストする目的で追加されました。

注釈

catch_warnings マネージャーは、モジュールの showwarning() 関数と内部のフィルタ仕様のリストを置き換え、その後復元することによって動作しています。これは、コンテキストマネージャーがグローバルな状態を変更していることを意味していて、したがってスレッドセーフではありません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


dataclasses --- データクラス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

dataclasses --- データクラス

ソースコード: Lib/dataclasses.py

このモジュールは、__init__() や __repr__() のような special method を生成し、ユーザー定義のクラスに自動的に追加するデコレータや関数を提供します。このモジュールは PEP 557 に記載されました。

これらの生成されたメソッドで利用されるメンバー変数は PEP 526 型アノテーションを用いて定義されます。例えば、このコードでは:

@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

とりわけ、以下のような __init__() が追加されます:

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

このメソッドは自動的にクラスに追加される点に留意して下さい。上記の InventoryItem クラスの定義中にこのメソッドが直接明記されるわけではありません。

バージョン 3.7 で追加.

モジュールレベルのデコレータ、クラス、関数

@dataclasses.dataclass(*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)

この関数は、後述する special method を生成し、クラスに追加する decorator です。

The dataclass() decorator examines the class to find fields. A field is defined as class variable that has a type annotation. With two exceptions described below, nothing in dataclass() examines the type specified in the variable annotation.

生成されるすべてのメソッドの中でのフィールドの順序は、それらのフィールドがクラス定義に現れた順序です。

dataclass() デコレータは、後述する様々な "ダンダー" メソッド (訳注：dunderはdouble underscoreの略で、メソッド名の前後にアンダースコアが2つ付いているメソッド) をクラスに追加します。クラスに既にこれらのメソッドが存在する場合の動作は、後述する引数によって異なります。デコレータは呼び出した際に指定したクラスと同じクラスを返します。新しいクラスは生成されません。

dataclass() が引数を指定しない単純なデコレータとして使用された場合、ドキュメントに記載されているシグネチャのデフォルト値のとおりに動作します。つまり、以下の３つの dataclass() の用例は同等です:

@dataclass
class C:
    ...

@dataclass()
class C:
    ...

@dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)
class C:
   ...

dataclass() の引数は以下の通りです:

  • init: (デフォルトの)真の場合、 __init__() メソッドが生成されます。

    もしクラスに __init__() が既に定義されていた場合は、この引数は無視されます。

  • repr: (デフォルトの)真の場合、 __repr__() メソッドが生成されます。 生成された repr 文字列には、クラス名、各フィールドの名前および repr 文字列が、クラス上での定義された順序で並びます。 repr から除外するように印が付けられたフィールドは、 repr 文字列には含まれません。 例えば、このようになります: InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10) 。

    もしクラスに __repr__() が既に定義されていた場合は、この引数は無視されます。

  • eq: (デフォルトの)真の場合、 __eq__() メソッドが生成されます。このメソッドはクラスの比較を、そのクラスのフィールドからなるタプルを比較するように行います。比較する2つのインスタンスのクラスは同一でなければなりません。

    もしクラスに __eq__() が既に定義されていた場合は、この引数は無視されます。

  • order: 真 (デフォルト値は False) の場合、 __lt__()、__le__()、__gt__()、__ge__() メソッドが生成されます。これらの比較は、クラスをそのフィールドからなるタプルであるかのように取り扱います。比較される2つのインスタンスは、同一の型でなければなりません。もし order が true で、 eq に falseを指定すすると、ValueError が送出されます。

    もし、クラスで既に __lt__(), __le__(), __gt__(), __ge__() のうちいずれかが定義されていると TypeError が送出されます。

  • unsafe_hash: (デフォルトの)``False`` の場合、 eq と frozen がどう設定されているかに従って __hash__() メソッドが生成されます。

    __hash__() は、組み込みの hash() から使われたり、 dict や set のようなハッシュ化されたコレクションにオブジェクトを追加するときに使われます。 __hash__() があるということはそのクラスのインスタンスが不変 (イミュータブル) であることを意味します。 可変性というのは複雑な性質で、プログラマの意図、 __eq__() が存在しているかどうかとその振る舞い、 dataclass() デコレータの eq フラグと frozen フラグの値に依存します。

    デフォルトでは、 dataclass() は追加しても安全でない限り __hash__() メソッドを暗黙的には追加しません。
また、明示的に定義され存在している __hash__() メソッドに追加したり変更したりはしません。
クラスの属性の __hash__ = None という設定は、 Python にとって __hash__() のドキュメントにあるような特別な意味があります。

    __hash__() が明示的に定義されていなかったり、 None に設定されていた場合は、 dataclass() は暗黙的に __hash__() メソッドを追加する かもしれません 。 推奨はできませんが、 unsafe_hash=True とすることで dataclass() に __hash__() メソッドを作成させられます。 こうしてしまうと、クラスが論理的には不変だがそれにもかかわらず変更できてしまう場合、問題になり得ます。 こうするのは特別なユースケースで、慎重に検討するべきです。

    __hash__() メソッドが暗黙的に作られるかどうかを決定する規則は次の通りです。 データクラスに明示的な __hash__() メソッドを持たせた上で、 unsafe_hash=True と設定することはできません; こうすると TypeError になります。

    eq と frozen が両方とも真だった場合、デフォルトでは dataclass() は __hash__() メソッドを生成します。 eq が真で frozen が偽の場合、__hash__() は None に設定され、(可変なので) ハッシュ化不可能とされます。 eq が偽の場合は、 __hash__() は手を付けないまま、つまりスーパークラスの __hash__() メソッドが使われることになります (スーパークラスが object だった場合は、 id に基づいたハッシュ化にフォールバックするということになります)。

  • frozen: 真 (デフォルト値は偽) の場合、フィールドへの代入は例外を生成します。 これにより読み出し専用の凍結されたインスタンスを模倣します。 __setattr__() あるいは __delattr__() がクラスに定義されていた場合は、 TypeError が送出されます。 後にある議論を参照してください。

フィールド には、通常の Python の文法でデフォルト値を指定できます。

@dataclass
class C:
    a: int       # 'a' has no default value
    b: int = 0   # assign a default value for 'b'

この例では、生成された __init__() メソッドには a と b の両方が含まれ、以下のように定義されます:

def __init__(self, a: int, b: int = 0):

デフォルト値を指定しないフィールドを、デフォルト値を指定したフィールドの後ろに定義すると、 TypeError が送出されます。これは、単一のクラスであっても、クラス継承の結果でも起きえます。

dataclasses.field(*, default=MISSING, default_factory=MISSING, repr=True, hash=None, init=True, compare=True, metadata=None)

通常の単純なユースケースでは、この他の機能は必要ありません。 しかし、データクラスには、フィールドごとの情報を必要とする機能もあります。 追加の情報の必要性に応えるために、デフォルトのフィールドの値をモジュールから提供されている field() 関数の呼び出しに置き換えられます。 例えば次のようになります:

@dataclass
class C:
    mylist: List[int] = field(default_factory=list)

c = C()
c.mylist += [1, 2, 3]

上にあるように、 MISSING 値は default パラメータと default_factory パラメータが提供されたかどうかを検出するのに使われる番兵オブジェクトです。 この番兵が使われるのは、 None が default の有効な値だからです。 どんなコードでも MISSING 値を直接使うべきではありません。

field() の引数は次の通りです:

  • default: 与えられた場合、このフィールドのデフォルト値になります。 これが必要なのは、 field() の呼び出しそのものが通常ではデフォルト値がいる位置を横取りしているからです。

  • default_factory: 提供されていた場合、0 引数の呼び出し可能オブジェクトでなければならず、このフィールドの初期値が必要になったときに呼び出されます。 他の目的も含めて、下で議論されているように、フィールドに可変なデフォルト値を指定するのに使えます。 default と default_factory の両方を指定するとエラーになります。

  • init: (デフォルトの)真の場合、 生成される __init__() メソッドの引数にこのフィールドを含めます。

  • repr: (デフォルトの)真の場合、生成される __repr__() メソッドによって返される文字列に、このフィールドを含めます。

  • compare: (デフォルトの) 真の場合、生成される等価関数と比較関数( __eq__() 、__gt__() など)にこのフィールドを含めます。

  • hash: これは真偽値あるいは None に設定できます。 真の場合、このフィールドは、生成された __hash__() メソッドに含まれます。 (デフォルトの) None の場合、 compare の値を使います: こうすることは普通は期待通りの振る舞いになります。 比較で使われるフィールドはハッシュに含まれるものと考えるべきです。 この値を None 以外に設定することは推奨されません。

    フィールドのハッシュ値を計算するコストが高い場合に、 hash=False だが compare=True と設定する理由が 1 つあるとすれば、フィールドが等価検査に必要かつ、その型のハッシュ値を計算するのに他のフィールドも使われることです。 フィールドがハッシュから除外されていたとしても、比較には使えます。

  • metadata: これはマッピングあるいは None に設定できます。 None は空の辞書として扱われます。 この値は MappingProxyType() でラップされ、読み出し専用になり、 Field オブジェクトに公開されます。 これはデータクラスから使われることはなく、サードパーティーの拡張機構として提供されます。 複数のサードパーティーが各々のキーを持て、メタデータの名前空間として使えます。

field() の呼び出しでフィールドのデフォルト値が指定されている場合は、このフィールドのクラス属性は、その指定された default 値で置き換えられます。 default が提供されていない場合は、そのクラス属性は削除されます。 こうする意図は、 dataclass() デコレータが実行された後には、ちょうどデフォルト値そのものが指定されたかのように、クラス属性がデフォルト値を全て持っているようにすることです。 例えば、次のような場合:

@dataclass
class C:
    x: int
    y: int = field(repr=False)
    z: int = field(repr=False, default=10)
    t: int = 20

クラス属性 C.z は 10 、クラス属性 C.t は 20 になり、クラス属性 C.x と C.y には値が設定されません。

class dataclasses.Field

Field オブジェクトはそれぞれの定義されたフィールドを記述します。 このオブジェクトは内部で作られ、モジュールレベル関数の fields() によって返されます (下の解説を見てください)。 ユーザーは絶対に Field オブジェクトを直接インスタンス化すべきではありません。 ドキュメント化されている属性は次の通りです:

  • name: フィールド名
  • type: フィールドの型
  • default, default_factory, init, repr, hash, compare, metadata は field() の宣言と同じ意味と値を持ちます。

他の属性があることもありますが、それらはプライベートであり、調べたり、依存したりしてはなりません。

dataclasses.fields(class_or_instance)

このデータクラスのフィールドを定義する Field オブジェクトをタプルで返します。 データクラスあるいはデータクラスのインスタンスを受け付けます。 データクラスやデータクラスのインスタンスが渡されなかった場合は、 TypeError を送出します。 ClassVar や InitVar といった疑似フィールドは返しません。

dataclasses.asdict(instance, *, dict_factory=dict)

データクラスの instance を (ファクトリ関数 dict_factory を使い) 辞書に変換します。 それぞれのデータクラスは、 name: value という組になっている、フィールドの辞書に変換されます。 データクラス、辞書、リスト、タプルは再帰的に処理されます。 例えば、次のようになります:

@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}]}

instance がデータクラスのインスタンスでなかった場合、 TypeError を送出します。

dataclasses.astuple(instance, *, tuple_factory=tuple)

データクラスの instance を (ファクトリ関数 tuple_factory を使い) タプルに変換します。 それぞれのデータクラスは、フィールドの値のタプルに変換されます。 データクラス、辞書、リスト、タプルは再帰的に処理されます。

1つ前の例の続きです:

assert astuple(p) == (10, 20)
assert astuple(c) == ([(0, 0), (10, 4)],)

instance がデータクラスのインスタンスでなかった場合、 TypeError を送出します。

dataclasses.make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)

cls_name という名前、 fields で定義されるフィールド、 bases で与えられた基底クラス、 namespace で与えられた名前空間付きで初期化されたデータクラスを作成します。 fields はイテラブルで、要素が name, (name, type), (name, type, Field) のうちのどれかです。 単に name だけが与えられた場合は、 typing.Any が type として使われます。 init, repr, eq, order, unsafe_hash, frozen の値は、 dataclass() のときと同じ意味を持ちます。

厳密にはこの関数は必須ではありません。というのは、 __annotations__ 付きのクラスを新しく作成するどの Python の機構でも、 dataclass() 関数を適用してそのクラスをデータクラスに変換できるからです。 この関数は便利さのために提供されています。 例えば次のように使います:

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(instance, **changes)

instance と同じ型のオブジェクトを新しく作成し、フィールドを changes にある値で置き換えます。 instance がデータクラスではなかった場合、 TypeError を送出します。 changes にある値がフィールドを指定していなかった場合も、 TypeError を送出します。

新しく返されるオブジェクトは、データクラスの __init__() メソッドを呼び出して作成されます。 これにより、もしあれば __post_init__() も呼び出されることが保証されます。

初期化限定変数でデフォルト値を持たないものがもしあれば、 replace() の呼び出し時に初期値が指定され、 __init__() と __post_init__() に渡せるようにしなければなりません。

changes に、 init=False と定義されたフィールドが含まれているとエラーになります。 この場合 ValueError が送出されます。

replace() を呼び出しているときに init=False であるフィールドがどのように働くかに気を付けてください。
そのフィールドは元のオブジェクトからコピーされるのではなく、仮に初期化されたとしても結局は __post_init__() で初期化されます。
init=False であるフィールドは滅多に使いませんし、使うとしたら注意深く使用します。
そのようなフィールドが使われている場合は、代わりのクラスコンストラクタ、あるいは、インスタンスのコピー処理をする独自実装の replace() (もしくは似た名前の) メソッドを持たせるのが賢明でしょう。

dataclasses.is_dataclass(class_or_instance)

引数がデータクラスかデータクラスのインスタンスだった場合に True を返します。それ以外の場合は False を返します。

引数がデータクラスのインスタンスである (そして、データクラスそのものではない) かどうかを知る必要がある場合は、 not isinstance(obj, type) で追加のチェックをしてください:

def is_dataclass_instance(obj):
    return is_dataclass(obj) and not isinstance(obj, type)

初期化後の処理

生成された __init__() のコードは、 __post_init__() という名前のメソッドがクラスに定義されていたら、それを呼び出します。
通常は self.__post_init__() のように呼び出されます。
しかし InitVar フィールドが定義されていた場合、それらもクラスに定義された順序で __post_init__() に渡されます。
__init__() メソッドが生成されなかった場合は、 __post_init__() は自動的には呼び出されません。

他の機能と組み合わせることで、他の 1 つ以上のフィールドに依存しているフィールドが初期化できます。 例えば次のようにできます:

@dataclass
class C:
    a: float
    b: float
    c: float = field(init=False)

    def __post_init__(self):
        self.c = self.a + self.b

下にある初期化限定変数についての節で、 __post_init__() にパラメータを渡す方法を参照してください。 replace() が init=False であるフィールドをどう取り扱うかについての警告も参照してください。

クラス変数

dataclass() が実際にフィールドの型の検査を行う 2 箇所のうち 1 つは、フィールドが PEP 526 で定義されたクラス変数かどうかの判定です。 その判定はフィールドの型が typing.ClassVar かどうかで行います。 フィールドが ClassVar の場合、フィールドとは見なされなくなり、データクラスの機構からは無視されます。 そのような ClassVar 疑似フィールドは、モジュールレベル関数 fields() の返り値には含まれません。

初期化限定変数

dataclass() が型アノテーションの検査を行うもう 1 つの箇所は、フィールドが初期化限定変数かどうかの判定です。 その判定はフィールドの型が dataclasses.InitVar 型であるかどうかで行います。 フィールドが InitVar の場合、初期化限定フィールドと呼ばれる疑似フィールドと見なされます。 これは本物のフィールドではないので、モジュールレベル関数 fields() の返り値には含まれません。 初期化限定フィールドは生成された __init__() メソッドに引数として追加され、オプションの __post_init__() メソッドにも渡されます。 初期化限定フィールドは、データクラスからはそれ以外では使われません。

例えば、あるフィールドがデータベースから初期化されると仮定して、クラスを作成するときには値が与えられない次の場合を考えます:

@dataclass
class C:
    i: int
    j: int = None
    database: InitVar[DatabaseType] = 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)

このケースでは、 fields() は i と j の Field オブジェクトは返しますが、 database の Field オブジェクトは返しません。

凍結されたインスタンス

真に不変な Python のオブジェクトを作成するのは不可能です。 しかし、 frozen=True を dataclass() デコレータに渡すことで、不変性の模倣はできます。 このケースでは、データクラスは __setattr__() メソッドと __delattr__() メソッドをクラスに追加します。 これらのメソッドは起動すると FrozenInstanceError を送出します。

frozen=True を使うとき、実行する上でのわずかな代償があります: __init__() でフィールドを初期化するのに単純に割り当てることはできず、 object.__setattr__() を使わなくてはなりません。

継承

データクラスが dataclass() デコレータで作成されるとき、 MRO を逆向きに (すなわち、 object を出発点として) 全ての基底クラスを調べていき、見付かったデータクラスそれぞれについて、その基底クラスが持っているフィールドを順序付きマッピングオブジェクトに追加します。 全ての基底クラスのフィールドが追加し終わったら、自分自身のフィールドを順序付きマッピングオブジェクトに追加します。 生成された全てのメソッドは、このフィールドが集められ整列された順序付きのマッピングオブジェクトを利用します。 フィールドは挿入順序で並んでいるので、派生クラスは基底クラスをオーバーライドします。 例えば次のようになります:

@dataclass
class Base:
    x: Any = 15.0
    y: int = 0

@dataclass
class C(Base):
    z: int = 10
    x: int = 15

最終的に出来上がるフィールドのリストは x, y, z の順番になります。 最終的な x の型は、 クラス C で指定されている通り int です。

C の生成された __init__() メソッドは次のようになります:

def __init__(self, x: int = 15, y: int = 0, z: int = 10):

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

field() に default_factory を指定した場合、そのフィールドのデフォルト値が必要とされたときに、引数無しで呼び出されます。 これは例えば、リストの新しいインスタンスを作成するために使います:

mylist: list = field(default_factory=list)

あるフィールドが (init=False を使って) __init__() から除外され、かつ、 default_factory が指定されていた場合、デフォルトファクトリ関数は生成された __init__() 関数から常に呼び出されます。 フィールドに初期値を与える方法が他に無いので、このような動きになります。

可変なデフォルト値

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

クラス C の 2 つのインスタンスが、予想通り同じクラス変数 x を共有していることに注意してください。

データクラスを使っているこのコードが もし仮に 有効なものだとしたら:

@dataclass
class D:
    x: List = []
    def add(self, element):
        self.x += element

データクラスは次のようなコードを生成するでしょう:

class D:
    x = []
    def __init__(self, x=x):
        self.x = x
    def add(self, element):
        self.x += element

assert D().x is D().x

これには、クラス C を使ったさっきの例と同じ問題があります。 すなわち、クラス D の 2 つのインスタンスは、クラスインスタンスを作成するときに x の具体的な値を指定しておらず、同じ x のコピーを共有します。 データクラスは Python の通常のクラス作成の仕組みを使っているだけなので、この同じ問題を抱えています。 データクラスがこの問題を検出する一般的な方法を持たない代わりに、データクラスは型が list や dict や set のデフォルトパラメーターを検出した場合、 TypeError を送出します。 これは完全ではない解決法ですが、よくあるエラーの多くを防げます。

デフォルトファクトリ関数を使うのが、フィールドのデフォルト値として可変な型の新しいインスタンスを作成する手段です:

@dataclass
class D:
    x: list = field(default_factory=list)

assert D().x is not D().x

例外

exception dataclasses.FrozenInstanceError

frozen=True 付きで定義されたデータクラスで、暗黙的に定義された __setattr__() または __delattr__() が呼び出されたときに送出されます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


contextlib --- Utilities for with-statement contexts

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

contextlib --- Utilities for with-statement contexts

ソースコード: Lib/contextlib.py

このモジュールは with 文に関わる一般的なタスクのためのユーティリティを提供します。詳しい情報は、 コンテキストマネージャ型 と with文とコンテキストマネージャ を参照してください。

ユーティリティ

以下の関数とクラスを提供しています:

class contextlib.AbstractContextManager

An abstract base class for classes that implement object.__enter__() and object.__exit__(). A default implementation for object.__enter__() is provided which returns self while object.__exit__() is an abstract method which by default returns None. See also the definition of コンテキストマネージャ型.

バージョン 3.6 で追加.

class contextlib.AbstractAsyncContextManager

An abstract base class for classes that implement object.__aenter__() and object.__aexit__(). A default implementation for object.__aenter__() is provided which returns self while object.__aexit__() is an abstract method which by default returns None. See also the definition of 非同期コンテクストマネージャ (Asynchronous Context Manager).

バージョン 3.7 で追加.

@contextlib.contextmanager

この関数は with 文コンテキストマネージャのファクトリ関数を定義するために利用できる デコレータ です。新しいクラスや __enter__() と __exit__() メソッドを別々に定義しなくても、ファクトリ関数を定義することができます。

While many objects natively support use in with statements, sometimes a resource needs to be managed that isn't a context manager in its own right, and doesn't implement a close() method for use with contextlib.closing

An abstract example would be the following to ensure correct resource management:

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

The function being decorated must return a generator-iterator when called. This iterator must yield exactly one value, which will be bound to the targets in the with statement's as clause, if any.

At the point where the generator yields, the block nested in the with statement is executed. The generator is then resumed after the block is exited. If an unhandled exception occurs in the block, it is reraised inside the generator at the point where the yield occurred. Thus, you can use a try...except...finally statement to trap the error (if any), or ensure that some cleanup takes place. If an exception is trapped merely in order to log it or to perform some action (rather than to suppress it entirely), the generator must reraise that exception. Otherwise the generator context manager will indicate to the with statement that the exception has been handled, and execution will resume with the statement immediately following the with statement.

contextmanager() は ContextDecorator を使っているので、 contextmanager() で作ったコンテキストマネージャは with 文だけでなくデコレータとしても利用できます。デコレーターとして利用された場合、新しい generator インスタンスが関数呼び出しのたびに暗黙に生成されます (このことによって、 contextmanager() によって作られたなにがしか「単発」コンテキストマネージャを、コンテキストマネージャがデコレータとして使われるためには多重に呼び出されることをサポートする必要がある、という要件に合致させることが出来ます。)

バージョン 3.2 で変更: ContextDecorator の使用。

@contextlib.asynccontextmanager

Similar to contextmanager(), but creates an 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.

A simple example:

from contextlib import asynccontextmanager

@asynccontextmanager
async def get_connection():
    conn = await acquire_db_connection()
    try:
        yield conn
    finally:
        await release_db_connection(conn)

async def get_all_users():
    async with get_connection() as conn:
        return conn.query('SELECT ...')

バージョン 3.7 で追加.

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('http://www.python.org')) as page:
    for line in page:
        print(line)

page を明示的に close する必要は無く、エラーが発生した場合でも、 with ブロックを出るときに page.close() が呼ばれます。

contextlib.nullcontext(enter_result=None)

Return a context manager that returns enter_result from __enter__, but otherwise does nothing. It is intended to be used as a stand-in for an optional context manager, for example:

def myfunction(arg, ignore_exceptions=False):
    if ignore_exceptions:
        # Use suppress to ignore all exceptions.
        cm = contextlib.suppress(Exception)
    else:
        # Do not ignore any exceptions, cm has no effect.
        cm = contextlib.nullcontext()
    with cm:
        # Do something

An example using 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

バージョン 3.7 で追加.

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

このコンテキストマネージャは 再入可能(リエントラント) です。

バージョン 3.4 で追加.

contextlib.redirect_stdout(new_target)

Context manager for temporarily redirecting sys.stdout to another file or file-like object.

This tool adds flexibility to existing functions or classes whose output is hardwired to stdout.

For example, the output of help() normally is sent to sys.stdout. You can capture that output in a string by redirecting the output to an io.StringIO object:

f = io.StringIO()
with redirect_stdout(f):
    help(pow)
s = f.getvalue()

To send the output of help() to a file on disk, redirect the output to a regular file:

with open('help.txt', 'w') as f:
    with redirect_stdout(f):
        help(pow)

To send the output of help() to sys.stderr:

with redirect_stdout(sys.stderr):
    help(pow)

Note that the global side effect on sys.stdout means that this context manager is not suitable for use in library code and most threaded applications. It also has no effect on the output of subprocesses. However, it is still a useful approach for many utility scripts.

このコンテキストマネージャは 再入可能(リエントラント) です。

バージョン 3.4 で追加.

contextlib.redirect_stderr(new_target)

Similar to redirect_stdout() but redirecting sys.stderr to another file or file-like object.

このコンテキストマネージャは 再入可能(リエントラント) です。

バージョン 3.5 で追加.

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

注釈

As the decorated function must be able to be called multiple times, the underlying context manager must support use in multiple with statements. If this is not the case, then the original construct with the explicit with statement inside the function should be used.

バージョン 3.2 で追加.

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

各インスタンスは登録されたコールバックのスタックを管理し、インスタンスが (明示的に、あるいは with 文の終わりに暗黙的に) close されるときに逆順でそれを呼び出します。コンテキストスタックのインスタンスが暗黙的にガベージコレクトされたときには callback は呼び出され ません 。

このスタックモデルは、(file オブジェクトのように) __init__ メソッドでリソースを確保するコンテキストマネージャーを正しく扱うためのものです。

登録されたコールバックが登録の逆順で実行されるので、複数のネストされた with 文を利用するのと同じ振る舞いをします。これは例外処理にも適用されます。内側のコールバックが例外を抑制したり置き換えたりした場合、外側のコールバックには更新された状態に応じた引数が渡されます。

これは正しく exit callback の stack を巻き戻すための、比較的低レベルな API です。アプリケーション独自のより高レベルなコンテキストマネージャーを作るための基板として使うのに適しています。

バージョン 3.3 で追加.

enter_context(cm)

新しいコンテキストマネージャーに enter し、その __exit__() method をコールバックスタックに追加します。渡されたコンテキストマネージャーの __enter__() メソッドの戻り値を返します。

コンテキストマネージャーは、普段 with 文で利用された時と同じように、例外を抑制することができます。

push(exit)

コンテキストマネージャーの __exit__() メソッドをコールバックスタックに追加します。

このメソッドは __enter__ を 呼び出さない ので、コンテキストマネージャーを実装するときに、 __enter__() の実装の一部を自身の __exit__() メソッドでカバーするために利用できます。

コンテキストマネージャーではないオブジェクトが渡された場合、このメソッドはそのオブジェクトをコンテキストマネージャーの __exit__() メソッドと同じシグネチャを持つコールバック関数だと仮定して、直接コールバックスタックに追加します。

それらのコールバック関数も、コンテキストマネージャーの __exit__() と同じく、 true 値を返すことで例外を抑制することができます。

この関数はデコレータとしても使えるように、受け取ったオブジェクトをそのまま返します。

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

An asynchronous context manager, similar to ExitStack, that supports combining both synchronous and asynchronous context managers, as well as having coroutines for cleanup logic.

The close() method is not implemented, aclose() must be used instead.

enter_async_context(cm)

Similar to enter_context() but expects an asynchronous context manager.

push_async_exit(exit)

Similar to push() but expects either an asynchronous context manager or a coroutine function.

push_async_callback(callback, *args, **kwds)

Similar to callback() but expects a coroutine function.

aclose()

Similar to close() but properly handles awaitables.

Continuing the example for 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.

バージョン 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__ 実装内のクリーンアップ

ExitStack.push() のドキュメントで言及したとおり、このメソッドはすでに獲得したリソースを、 __enter__() メソッドの残りのステップが失敗した時にクリーンアップするために利用することができます。

次の例では、リソースの確保と開放の関数に加えて、オプションのバリデーション関数を受け取るコンテキストマネージャーで、この方法を使ってコンテキストマネージャープロトコルを提供しています:

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(Callback, self).__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()

Due to the way the decorator protocol works, a callback function declared this way cannot take any parameters. Instead, any resources to be released must be accessed as closure variables.

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

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()

コンテキストマネージャーを関数デコレーターとして使う場合、 __enter__() メソッドの戻り値にアクセスする手段がないという制限があることに注意してください。もしその値が必要であれば、明示的な with 文を使う必要があります。

参考

PEP 343 - "with" ステートメント
Python の with 文の仕様、背景、および例が記載されています。

Single use, reusable and reentrant context managers

Most context managers are written in a way that means they can only be used effectively in a with statement once. These single use context managers must be created afresh each time they're used - attempting to use them a second time will trigger an exception or otherwise not work correctly.

This common limitation means that it is generally advisable to create context managers directly in the header of the with statement where they are used (as shown in all of the usage examples above).

Files are an example of effectively single use context managers, since the first with statement will close the file, preventing any further IO operations using that file object.

Context managers created using contextmanager() are also single use context managers, and will complain about the underlying generator failing to yield if an attempt is made to use them a second time:

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

Reentrant context managers

More sophisticated context managers may be "reentrant". These context managers can not only be used in multiple with statements, but may also be used inside a with statement that is already using the same context manager.

threading.RLock is an example of a reentrant context manager, as are suppress() and redirect_stdout(). Here's a very simple example of reentrant use:

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

Real world examples of reentrancy are more likely to involve multiple functions calling each other and hence be far more complicated than this example.

Note also that being reentrant is not the same thing as being thread safe. redirect_stdout(), for example, is definitely not thread safe, as it makes a global modification to the system state by binding sys.stdout to a different stream.

Reusable context managers

Distinct from both single use and reentrant context managers are "reusable" context managers (or, to be completely explicit, "reusable, but not reentrant" context managers, since reentrant context managers are also reusable). These context managers support being used multiple times, but will fail (or otherwise not work correctly) if the specific context manager instance has already been used in a containing with statement.

threading.Lock is an example of a reusable, but not reentrant, context manager (for a reentrant lock, it is necessary to use threading.RLock instead).

Another example of a reusable, but not reentrant, context manager is ExitStack, as it invokes all currently registered callbacks when leaving any with statement, regardless of where those callbacks were added:

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

As the output from the example shows, reusing a single stack object across multiple with statements works correctly, but attempting to nest them will cause the stack to be cleared at the end of the innermost with statement, which is unlikely to be desirable behaviour.

Using separate ExitStack instances instead of reusing a single instance avoids that problem:

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


abc --- 抽象基底クラス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

abc --- 抽象基底クラス

ソースコード: Lib/abc.py

このモジュールは Python に PEP 3119 で概要が示された 抽象基底クラス (ABC) を定義する基盤を提供します。なぜこれが Python に付け加えられたかについてはその PEP を参照してください。 (ABC に基づいた数の型階層を扱った 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

ABCMeta をメタクラスとするヘルパークラスです。このクラスを使うと、混乱しがちなメタクラスを使わずに、単に ABC を継承するだけで抽象基底クラスを作成できます。例:

from abc import ABC

class MyABC(ABC):
    pass

ABC の型はやはり ABCMeta であり、そのため ABC から継承するときは、メタクラスの衝突を引き起こし得る多重継承のような、メタクラスを使う上でのいつもの用心が求められることに注意してください。 metaclass キーワードを渡し、 ABCMeta を直接利用することで、抽象基底クラスを直接定義することもできます。例:

from abc import ABCMeta

class MyABC(metaclass=ABCMeta):
    pass

バージョン 3.4 で追加.

class abc.ABCMeta

抽象基底クラス(ABC)を定義するためのメタクラス。

ABC を作るときにこのメタクラスを使います。ABC は直接的にサブクラス化することができ、ミックスイン(mix-in)クラスのように振る舞います。また、無関係な具象クラス(組み込み型でも構いません)と無関係な ABC を "仮想的サブクラス" として登録できます -- これらとその子孫は組み込み関数 issubclass() によって登録した ABC のサブクラスと判定されますが、登録した ABC は MRO (Method Resolution Order, メソッド解決順)には現れませんし、この ABC のメソッド実装が(super() を通してだけでなく)呼び出し可能になるわけでもありません。 [1]

メタクラス ABCMeta を使って作られたクラスには以下のメソッドがあります:

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 で変更: register() の呼び出しを検出するために、get_cache_token() 関数を使うことができます。

また、次のメソッドを抽象基底クラスの中でオーバーライドできます:

__subclasshook__(subclass)

(クラスメソッドとして定義しなければなりません。)

subclass がこの ABC のサブクラスと見なせるかどうかチェックします。これによって ABC のサブクラスと見なしたい全てのクラスについて register() を呼び出すことなく issubclass の振る舞いをさらにカスタマイズできます。 (このクラスメソッドは ABC の __subclasscheck__() メソッドから呼び出されます。)

このメソッドは True, False または NotImplemented を返さなければなりません。True を返す場合は、subclass はこの ABC のサブクラスと見なされます。False を返す場合は、subclass はたとえ通常の意味でサブクラスであっても ABC のサブクラスではないと見なされます。NotImplemented の場合、サブクラスチェックは通常のメカニズムに戻ります。

この概念のデモとして、次の 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)

ABC MyIterable は標準的なイテラブルのメソッド __iter__() を抽象メソッドとして定義します。ここで与えられている抽象クラスの実装は、サブクラスから呼び出すことができます。 get_iterator() メソッドも MyIterable 抽象基底クラスの一部ですが、抽象的でない派生クラスはこれをオーバーライドする必要はありません。

ここで定義されるクラスメソッド __subclasshook__() の意味は、 __iter__() メソッドがクラスの(または __mro__ でアクセスされる基底クラスの一つの) __dict__ にある場合にもそのクラスが MyIterable だと見なされるということです。

最後に、一番下の行は Foo を __iter__() メソッドを定義しないにもかかわらず MyIterable の仮想的サブクラスにします(Foo は古い様式の __len__() と __getitem__() を用いたイテレータプロトコルを使っています。)。これによって Foo のメソッドとして get_iterator が手に入るわけではないことに注意してください。それは別に提供されています。

abc モジュールは以下のデコレータも提供しています:

@abc.abstractmethod

抽象メソッドを示すデコレータです。

このデコレータを使うには、クラスのメタクラスが ABCMeta かそれを継承したものである必要があります。 ABCMeta の派生クラスをメタクラスに持つクラスは、全ての抽象メソッドとプロパティをオーバーロードしない限りインスタンス化することができません。抽象メソッドは通常の 'super' 呼び出し方法で呼ぶことができます。 abstractmethod() はプロパティやデスクリプタのために抽象メソッドを定義することもできます。

クラスに動的に抽象メソッドを追加する、あるいはメソッドやクラスが作られた後から抽象的かどうかの状態を変更しようと試みることは、サポートされません。 abstractmethod() が影響を与えるのは正規の継承により派生したサブクラスのみで、ABC の register() メソッドで登録された "仮想的サブクラス" は影響されません。

abstractmethod() が他のメソッドデスクリプタと組み合わされる場合、次の例のように、一番内側のデコレータとして適用しなければなりません:

class C(ABC):
    @abstractmethod
    def my_abstract_method(self, ...):
        ...
    @classmethod
    @abstractmethod
    def my_abstract_classmethod(cls, ...):
        ...
    @staticmethod
    @abstractmethod
    def my_abstract_staticmethod(...):
        ...

    @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 呼び出しの終点として有効です。

abc モジュールは以下のレガシーなデコレータも提供しています:

@abc.abstractclassmethod

バージョン 3.2 で追加.

バージョン 3.3 で非推奨: classmethod を abstractmethod() と一緒に使えるようになったため、このデコレータは冗長になりました。

組み込みの classmethod() のサブクラスで、抽象クラスメソッドであることを示します。それ以外は abstractmethod() と同じです。

この特殊ケースは classmethod() デコレータが抽象メソッドに適用された場合に抽象的だと正しく認識されるようになったため撤廃されます:

class C(ABC):
    @classmethod
    @abstractmethod
    def my_abstract_classmethod(cls, ...):
        ...
@abc.abstractstaticmethod

バージョン 3.2 で追加.

バージョン 3.3 で非推奨: staticmethod を abstractmethod() と一緒に使えるようになったため、このデコレータは冗長になりました。

組み込みの staticmethod() のサブクラスで、抽象静的メソッドであることを示します。それ以外は abstractmethod() と同じです。

この特殊ケースは staticmethod() デコレータが抽象メソッドに適用された場合に抽象的だと正しく認識されるようになったため撤廃されます:

class C(ABC):
    @staticmethod
    @abstractmethod
    def my_abstract_staticmethod(...):
        ...
@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):
        ...

abc モジュールは以下の関数も提供しています:

abc.get_cache_token()

現在の抽象基底クラスのキャッシュトークンを返します。

このトークンは、仮想サブクラスのための抽象基底クラスの現在のバージョンを特定する (等価性検査をサポートしている) 不透明なオブジェクトです。 任意のABCでの ABCMeta.register() の呼び出しごとに、トークンは変更されます。

バージョン 3.4 で追加.

脚注

[1] C++ プログラマは Python の仮想的基底クラスの概念は C++ のものと同じではないということを銘記すべきです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


atexit --- 終了ハンドラ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

atexit --- 終了ハンドラ

atexit モジュールは、クリーンアップ関数の登録およびその解除を行う関数を定義します。登録された関数はインタプリタの通常終了時に自動的に実行されます。atexit はそれら関数を登録した順と 逆に 実行します; A、B、C の順に登録した場合、インタプリタ終了時に C、B、A の順に実行されます。

注意: このモジュールを使用して登録された関数は、プログラムが Python が扱わないシグナルによって kill された場合、Python 内部で致命的なエラーが検出された場合、あるいは os._exit() が呼び出された場合は実行されません。

バージョン 3.7 で変更: When used with C-API subinterpreters, registered functions are local to the interpreter they were registered in.

atexit.register(func, *args, **kwargs)

func を終了時に実行する関数として登録します。func に渡す引数は register() の引数として指定しなければなりません。同じ関数を同じ引数で複数回登録できます。

通常のプログラムの終了時、例えば sys.exit() が呼び出されるとき、あるいは、メインモジュールの実行が完了したときに、登録された全ての関数を、最後に登録されたものから順に呼び出します。通常、より低レベルのモジュールはより高レベルのモジュールより前に import されるので、後で後始末が行われるという仮定に基づいています。

終了ハンドラの実行中に例外が発生すると、(SystemExit 以外の場合は)トレースバックを表示して、例外の情報を保存します。全ての終了ハンドラに動作するチャンスを与えた後に、最後に送出された例外を再送出します。

この関数は func を返し、これをデコレータとして利用できます。

atexit.unregister(func)

func をインタプリタ終了時に実行される関数のリストから削除します。unregister() で削除されると、func は、たとえ複数個登録されていてもインタプリタ終了時に呼び出されないことが保証されます。func が登録されていない場合、unregister() は何もせず、何も通知しません。

参考

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

デコレータとして利用できるのは、その関数が引数なしで呼び出された場合に限られます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


traceback --- スタックトレースの表示または取得

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

traceback --- スタックトレースの表示または取得

ソースコード: Lib/traceback.py

このモジュールは Python プログラムのスタックトレースを抽出し、書式を整え、表示するための標準インターフェースを提供します。モジュールがスタックトレースを表示するとき、Python インタープリタの動作を正確に模倣します。インタープリタの"ラッパー"の場合のように、プログラムの制御の元でスタックトレースを表示したいと思ったときに役に立ちます。

モジュールはトレースバックオブジェクトを使用します。このオブジェクトの型は sys.last_traceback 変数に格納され、sys.exc_info() の三番目に返されます。

このモジュールには、以下の関数が定義されています:

traceback.print_tb(tb, limit=None, file=None)

limit が正の場合、トレースバックオブジェクト tb から limit までのスタックトレース項目 (呼び出し側のフレームから開始) を出力します。 そうでない場合、最新 abs(limit) 項目を出力します。 limit が省略されるか None の場合、すべての項目が出力されます。 file が省略されるか None の場合は、 sys.stderr へ出力されます。 そうでない場合、 file は出力を受け取る開いたファイルまたは file-like オブジェクトでなければなりません。

バージョン 3.5 で変更: 負の limit がサポートされました。

traceback.print_exception(etype, value, tb, limit=None, file=None, chain=True)

トレースバックオブジェクト tb から例外の情報とスタックトレースの項目を file に出力します。 この関数は以下の点で print_tb() と異なります:

  • tb が None でない場合ヘッダ Traceback (most recent call last): を出力します
  • スタックトレースの後に例外 etype と value を出力します
  • type(value) が SyntaxError であり、 value が適切な形式を持っていれば、そのエラーのおおよその位置を示すマークと共にシンタックスエラーが発生した行が表示されます。

オプション引数 limit の意味は print_tb() のものと同じです。 chain が真の場合 (デフォルト)、連鎖した例外 (例外の __cause__ か __context__ 属性) も出力されます。 これはインタープリタ自身が処理されていない例外を出力するときと同じです。

バージョン 3.5 で変更: 引数 etype は無視され、 value の型から推論されます。

traceback.print_exc(limit=None, file=None, chain=True)

print_exception(*sys.exc_info(), limit, file, chain) の省略表現です。

traceback.print_last(limit=None, file=None, chain=True)

print_exception(sys.last_type, sys.last_value, sys.last_traceback, limit, file, chain) の省略表現です。 一般に、例外が対話的なプロンプトに達した後にのみ機能します (sys.last_type 参照)。

traceback.print_stack(f=None, limit=None, file=None)

limit が正の場合、最大 limit 個のスタックトレース項目 (呼び出し地点から開始) を出力します。 そうでない場合、最新の abs(limit) 個を出力します。 limit が省略されるか None の場合、すべての項目が出力されます。オプションの f 引数は、開始するスタックフレームを指定するために用いることができます。オプションの file 引数は print_tb() の file 引数と同様の意味を持っています。

バージョン 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. The line is a string with leading and trailing whitespace stripped; if the source is not available it is None.

traceback.extract_stack(f=None, limit=None)

現在のスタックフレームから生のトレースバックを取り出します。戻り値は extract_tb() と同じ形式です。オプションの f と limit 引数は print_stack() と同じ意味を持ちます。

traceback.format_list(extracted_list)

Given a list of tuples or FrameSummary objects as returned by extract_tb() or extract_stack(), return a list of strings ready for printing. Each string in the resulting list corresponds to the item with the same index in the argument list. Each string ends in a newline; the strings may contain internal newlines as well, for those items whose source text line is not None.

traceback.format_exception_only(etype, value)

トレースバックの例外部分を書式化します。引数は sys.last_type と sys.last_value のような例外の型と値です。戻り値はそれぞれが改行で終わっている文字列のリストです。通常、リストは一つの文字列を含んでいます。しかし、 SyntaxError 例外に対しては、 (出力されるときに) 構文エラーが起きた場所についての詳細な情報を示す行をいくつか含んでいます。どの例外が起きたのかを示すメッセージは、常にリストの最後の文字列です。

traceback.format_exception(etype, value, tb, limit=None, chain=True)

スタックトレースと例外情報を書式化します。引数は print_exception() の対応する引数と同じ意味を持ちます。戻り値は文字列のリストで、それぞれの文字列は改行で終わり、そのいくつかは内部に改行を含みます。これらの行が連結されて出力される場合は、厳密に print_exception() と同じテキストが出力されます。

バージョン 3.5 で変更: 引数 etype は無視され、 value の型から推論されます。

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)

各フレームオブジェクトの clear() メソッドを呼んでトレースバック tb 内の全スタックフレームの局所変数を消去します。

バージョン 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().

バージョン 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().

バージョン 3.5 で追加.

このモジュールは以下のクラスも定義しています:

TracebackException オブジェクト

バージョン 3.5 で追加.

TracebackException オブジェクトは実際の例外から作られ、後の出力のために軽量な方法でデータをキャプチャします。

class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False)

後のレンダリングのために例外をキャプチャします。 limit、lookup_lines、capture_locals は StackSummary class のものです。

局所変数がキャプチャされたとき、それらはトレースバックに表示されることに注意してください。

__cause__

元々の __cause__ の TracebackException。

__context__

元々の __context__ の TracebackException。

__suppress_context__

元々の例外からの __suppress_context__。

stack

トレースバックを表す StackSummary。

exc_type

元々のトレースバックのクラス。

filename

構文エラー用 - エラーが発生したファイルの名前。

lineno

構文エラー用 - エラーが発生した行番号。

text

構文エラー用 - エラーが発生したテクスト。

offset

構文エラー用 - エラーが発生したテクストへのオフセット。

msg

構文エラー用 - コンパイラのエラーメッセージ。

classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)

後のレンダリングのために例外をキャプチャします。 limit、lookup_lines、capture_locals は StackSummary class のものです。

局所変数がキャプチャされたとき、それらはトレースバックに表示されることに注意してください。

format(*, chain=True)

例外を書式化します。

chain が True でない場合 __cause__ と __context__ は書式化されません。

返り値は文字列のジェネレータで、それぞれ改行で終わりますが、内部に改行を持つものもあります。 print_exception() はこのメソッドのラッパで、単にファイルに出力します。

例外発生を指すメッセージは常に出力の最後の文字列です。

format_exception_only()

トレースバックの例外部を書式化します。

返り値は文字列のジェネレータで、それぞれ改行で終わります。

通常、ジェネレータが出す文字列は一つです。 しかしながら SyntaxError 例外の場合、構文例外が発生した箇所の詳細な情報を表す行を複数出します。

例外発生を指すメッセージは常に出力の最後の文字列です。

StackSummary オブジェクト

バージョン 3.5 で追加.

StackSummary オブジェクトは書式化の準備ができているコールスタックを表します。

class traceback.StackSummary
classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)

ジェネレータ (例えば walk_stack() や walk_tb() が返すもの) から StackSummary を構築します。

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.

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.

FrameSummary オブジェクト

バージョン 3.5 で追加.

FrameSummary オブジェクトトレースバック内の単一のフレームを表します。

class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)

Represent a single frame in the traceback or stack that is being formatted or printed. It may optionally have a stringified version of the frames 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.

トレースバックの例

この簡単な例では基本的な 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_death()

def bright_side_of_death():
    return tuple()[0]

try:
    lumberjack()
except IndexError:
    exc_type, exc_value, exc_traceback = sys.exc_info()
    print("*** print_tb:")
    traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)
    print("*** print_exception:")
    # exc_type below is ignored on 3.5 and later
    traceback.print_exception(exc_type, exc_value, exc_traceback,
                              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:")
    # exc_type below is ignored on 3.5 and later
    print(repr(traceback.format_exception(exc_type, exc_value,
                                          exc_traceback)))
    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_death()
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_death()
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...>", line 10, in <module>\n    lumberjack()\n',
 '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
 '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\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_death>]
*** format_tb:
['  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
 '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
 '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\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']

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


__future__ --- future 文の定義

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

__future__ --- future 文の定義

ソースコード: Lib/__future__.py

__future__ は実際にモジュールであり、次の3つの役割があります:

  • import 文を解析する既存のツールを混乱させることを避け、インポートしようとしているモジュールを見つけられるようにするため。
  • 2.1 以前のリリースで future 文 が実行された場合に、最低でもランタイム例外を投げるようにするため (__future__ のインポートは失敗します。なぜなら、 2.1 以前にはそういう名前のモジュールはなかったからです)。
  • 互換性のない変化がいつ言語に導入され、いつ言語の一部になる --- あるいは、なった --- のかを文書化するため。これは実行できる形式で書かれたドキュメントなので、 __future__ をインポートしてその中身を調べることでプログラムから調査することができます。

__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
)

OptionalRelease はその機能が導入された最初のリリースを記録します。

まだ時期が来ていない MandatoryRelease の場合、MandatoryRelease はその機能が言語の一部となるリリースを記します。

その他の場合、MandatoryRelease はその機能がいつ言語の一部になったのかを記録します。そのリリースから、あるいはそれ以降のリリースでは、この機能を使う際に future 文は必要ではありませんが、future 文を使い続けても構いません。

MandatoryRelease は None になるかもしれません。つまり、予定された機能が破棄されたということです。

_Feature クラスのインスタンスには対応する2つのメソッド、 getOptionalRelease() と getMandatoryRelease() があります。

CompilerFlag は、動的にコンパイルされるコードでその機能を有効にするために、組み込み関数 compile() の第4引数に渡す(ビットフィールド)フラグです。このフラグは _Feature インスタンスの compiler_flag 属性に保存されています。

機能の記述が __future__ から削除されたことはまだありません。 Python 2.1 で future 文が導入されて以来、この仕組みを使って以下の機能が言語に導入されてきました:

feature | optional in | mandatory in | effect
nested_scopes | 2.1.0b1 | 2.2 | PEP 227: Statically Nested Scopes
generators | 2.2.0a1 | 2.3 | PEP 255: Simple Generators
division | 2.2.0a2 | 3.0 | PEP 238: Changing the Division Operator
absolute_import | 2.5.0a1 | 3.0 | PEP 328: Imports: Multi-Line and Absolute/Relative
with_statement | 2.5.0a1 | 2.6 | PEP 343: The "with" Statement
print_function | 2.6.0a2 | 3.0 | PEP 3105: Make print a function
unicode_literals | 2.6.0a2 | 3.0 | PEP 3112: Bytes literals in Python 3000
generator_stop | 3.5.0b1 | 3.7 | PEP 479: StopIteration handling inside generators
annotations | 3.7.0b1 | 4.0 | PEP 563: Postponed evaluation of annotations

参考

future 文 (future statement)
コンパイラがどのように future インポートを扱うか。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


inspect --- 活動中のオブジェクトの情報を取得する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

inspect --- 活動中のオブジェクトの情報を取得する

ソースコード: Lib/inspect.py

inspect は、活動中のオブジェクト (モジュール、クラス、メソッド、関数、トレースバック、フレームオブジェクト、コードオブジェクトなど) から情報を取得する関数を定義しており、クラスの内容を調べたり、メソッドのソースコードを取得したり、関数の引数リストを取り出して整形したり、詳細なトレースバックを表示するのに必要な情報を取得したりするために利用できます。

このモジュールの機能は4種類に分類することができます。型チェック、ソースコードの情報取得、クラスや関数からの情報取得、インタープリタのスタック情報の調査です。

型とメンバー

getmembers() は、クラスやモジュールなどのオブジェクトからメンバーを取得します。名前が "is" で始まる関数は、主に getmembers() の第2引数として利用するために提供されています。以下のような特殊属性を参照できるかどうか調べる時にも使えるでしょう:

型 | 属性 | 説明
モジュール | __doc__ | ドキュメント文字列
 | __file__ | ファイル名 (組み込みモジュールには存在しません)
クラス | __doc__ | ドキュメント文字列
 | __name__ | クラスの定義名
 | __qualname__ | qualified name
 | __module__ | クラスを定義しているモジュールの名前
メソッド | __doc__ | ドキュメント文字列
 | __name__ | メソッドの定義名
 | __qualname__ | qualified name
 | __func__ | メソッドを実装している関数オブジェクト
 | __self__ | メソッドに結合しているインスタンス、または None
関数 | __doc__ | ドキュメント文字列
 | __name__ | 関数の定義名
 | __qualname__ | qualified name
 | __code__ | 関数をコンパイルしたバイトコード (bytecode) を格納するコードオブジェクト
 | __defaults__ | 位置またはキーワード引数の全ての既定値のタプル
 | __kwdefaults__ | キーワード専用引数の全ての既定値のマッピング
 | __globals__ | 関数が定義されたグローバル名前空間
 | __annotations__ | 仮引数名からアノテーションへのマッピング; "return" キーは return アノテーションに予約されています
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_kwonlyargcount | number of keyword only arguments (not including ** arg)
 | co_name | コードオブジェクトが定義されたときの名前
 | co_names | ローカル変数名のタプル
 | co_nlocals | ローカル変数の数
 | co_stacksize | 必要とされる仮想マシンのスタックスペース
 | co_varnames | 引数名とローカル変数名のタプル
ジェネレータ | __name__ | 名前
 | __qualname__ | qualified name
 | gi_frame | フレーム
 | gi_running | ジェネレータが実行中かどうか
 | gi_code | コード
 | gi_yieldfrom | yield from でイテレートされているオブジェクト、または None
コルーチン | __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.

inspect.getmembers(object[, predicate])

オブジェクトの全メンバーを、(名前, 値) の組み合わせのリストで返します。リストはメンバー名でソートされています。predicate が指定されている場合、predicate の戻り値が真となる値のみを返します。

注釈

引数がクラスで属性がメタクラスのカスタム __dir__() に列挙されている場合、getmembers() はメタクラスで定義されたクラス属性のみを返します。

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)

オブジェクトがモジュールの場合真を返します。

inspect.isclass(object)

オブジェクトが組み込みか Python が生成したクラスの場合に真を返します。

inspect.ismethod(object)

オブジェクトがメソッドの場合真を返します。

inspect.isfunction(object)

オブジェクトが Python 関数(lambda 式で生成されたものを含む) の場合に真を返します。

inspect.isgeneratorfunction(object)

object が Python のジェネレータ関数の場合真を返します。

inspect.isgenerator(object)

object がジェネレータの場合真を返します。

inspect.iscoroutinefunction(object)

オブジェクトが コルーチン関数 (async def シンタックスで定義された関数) の場合真を返します。

バージョン 3.5 で追加.

inspect.iscoroutine(object)

オブジェクトが async def で生成された コルーチン の場合真を返します。

バージョン 3.5 で追加.

inspect.isawaitable(object)

オブジェクトを await 式内で使用できる場合真を返します。

ジェネレータベースのコルーチンと通常のジェネレータを区別するのに使うこともできます。

def gen():
    yield
@types.coroutine
def gen_coro():
    yield

assert not isawaitable(gen())
assert isawaitable(gen_coro())

バージョン 3.5 で追加.

inspect.isasyncgenfunction(object)

オブジェクトが asynchronous generator 関数の場合に真を返します。例:

>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True

バージョン 3.6 で追加.

inspect.isasyncgen(object)

オブジェクトが asynchronous generator 関数によって生成された asynchronous generator iterator である場合に真を返します。

バージョン 3.6 で追加.

inspect.istraceback(object)

オブジェクトがトレースバックの場合は真を返します。

inspect.isframe(object)

オブジェクトがフレームの場合は真を返します。

inspect.iscode(object)

オブジェクトがコードの場合は真を返します。

inspect.isbuiltin(object)

オブジェクトが組み込み関数か束縛済みの組み込みメソッドの場合に真を返します。

inspect.isroutine(object)

オブジェクトがユーザ定義か組み込みの関数またはメソッドの場合は真を返します。

inspect.isabstract(object)

object が抽象規定型 (ABC) であるときに真を返します。

inspect.ismethoddescriptor(object)

オブジェクトがメソッドデスクリプタであり、 ismethod(), isclass(), isfunction(), isbuiltin() でない場合に真を返します。

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.

デスクリプタを使って実装されたメソッドで、上記のいずれかのテストもパスしているものは、 ismethoddescriptor() では偽を返します。これは単に他のテストの方がもっと確実だからです -- 例えば、 ismethod() をパスしたオブジェクトは __func__ 属性などを持っていると期待できます。

inspect.isdatadescriptor(object)

オブジェクトがデータデスクリプタの場合に真を返します。

データデスクリプタは __get__ および __set__ 属性の両方を持ちます。データデスクリプタの例は (Python 上で定義された) プロパティや getset やメンバーです。後者のふたつは C で定義されており、個々の型に特有のテストも行います。そのため、Python の実装よりもより確実です。通常、データデスクリプタは __name__ や __doc__ 属性を持ちます (プロパティ、 getset 、メンバーは両方の属性を持っています) が、保証されているわけではありません。

inspect.isgetsetdescriptor(object)

オブジェクトが getset デスクリプタの場合に真を返します。

CPython implementation detail: getset とは、拡張モジュールで PyGetSetDef 構造体を用いて定義された属性のことです。そのような型を持たない Python 実装の場合は、このメソッドは常に False を返します。

inspect.ismemberdescriptor(object)

オブジェクトがメンバーデスクリプタの場合に真を返します。

CPython implementation detail: メンバーデスクリプタとは、拡張モジュールで 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.

バージョン 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)

オブジェクトを定義しているモジュールを推測します。

inspect.getsourcefile(object)

オブジェクトを定義している Python ソースファイルの名前を返します。オブジェクトが組み込みのモジュール、クラス、関数の場合には、 TypeError 例外が発生します。

inspect.getsourcelines(object)

オブジェクトのソース行のリストと開始行番号を返します。引数にはモジュール、クラス、メソッド、関数、トレースバック、フレーム、コードオブジェクトを指定することができます。戻り値は指定したオブジェクトに対応するソースコードのソース行リストと元のソースファイル上での開始行となります。ソースコードを取得できない場合は OSError が発生します。

バージョン 3.3 で変更: IOError の代わりに OSError を送出します。前者は後者のエイリアスです。

inspect.getsource(object)

オブジェクトのソースコードを返します。引数にはモジュール、クラス、メソッド、関数、トレースバック、フレーム、コードオブジェクトを指定することができます。ソースコードは単一の文字列で返します。ソースコードを取得できない場合は OSError が発生します。

バージョン 3.3 で変更: IOError の代わりに OSError を送出します。前者は後者のエイリアスです。

inspect.cleandoc(doc)

コードブロックと位置を合わせるためのインデントを docstring から削除します。

先頭行の行頭の空白文字は全て削除されます。 2行目以降では全行で同じ数の行頭の空白文字が、削除できるだけ削除されます。 その後、先頭と末尾の空白行が削除され、全てのタブが空白に展開されます。

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

バージョン 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)

与えられた callable の Signature オブジェクトを返します:

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

Accepts a wide range of Python callables, from plain functions and classes to functools.partial() objects.

シグネチャが提供できない場合は、 ValueError を 送出し、オブジェクトの型がサポートされない場合は、 TypeError を送出します。

バージョン 3.5 で追加: follow_wrapped parameter. Pass False to get a signature of callable specifically (callable.__wrapped__ will not be used to unwrap decorated callables.)

注釈

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.

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, is the "return" annotation of the callable.

Signature オブジェクトは イミュータブル です。変更されたコピーを作成するには Signature.replace() を使用してください。

バージョン 3.5 で変更: Signature オブジェクトがピックル並びにハッシュ可能になりました。

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)

Return a Signature (or its subclass) object for a given callable obj. Pass follow_wrapped=False to get a signature of obj without unwrapping its __wrapped__ chain.

このメソッドは Signature のサブクラス化を単純化します:

class MySignature(Signature):
    pass
sig = MySignature.from_callable(min)
assert isinstance(sig, MySignature)

バージョン 3.5 で追加.

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

Parameter オブジェクトは イミュータブル です。変更されたコピーを作成するには Parameter.replace() を使用してください。

バージョン 3.5 で変更: Parameter オブジェクトがピックル並びにハッシュ可能になりました。

empty

デフォルト値とアノテーションがないことを指すクラスレベルの特殊マーカです。

name

仮引数名 (文字列) です。名前は有効な Python 識別子でなければなりません。

CPython implementation detail: 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 exposed by this module as names like implicit0.

default

引数のデフォルト値です。引数にデフォルト値がない場合、この属性は Parameter.empty に設定されます。

annotation

引数のアノテーションです。引数にアノテーションがない場合、この属性は Parameter.empty に設定されます。

kind

実引数値がどのように仮引数に束縛されるかを記述します。有効な値 (Parameter を通じてアクセスできます、たとえば Parameter.KEYWORD_ONLY) は:

名前 | 意味
POSITIONAL_ONLY

値を位置引数として渡さなければなりません。

Python には引数が位置のみであることを定義する明示的な文法はありませんが、組み込みおよび拡張モジュールの多くの関数 (特に1つか2つの引数を取るもの) は位置引数のみを取ります。
POSITIONAL_OR_KEYWORD | 値をキーワードまたは位置引数として渡すことができます (これは Python で実装された関数の標準的な束縛動作です)。
VAR_POSITIONAL | その他の仮引数に束縛されていない位置引数のタプルです。Python の関数定義における *args 仮引数に対応します。
KEYWORD_ONLY | 値をキーワード引数として渡さなければなりません。キーワード専用引数は Python の関数定義において * や *args の後に現れる引数です。
VAR_KEYWORD | その他の仮引数に束縛されていないキーワード引数の辞書です。Python の関数定義における **kwargs 仮引数に対応します。

例: デフォルト値のない全てのキーワード専用引数を出力します:

>>> 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
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 で変更: Python 3.3 では、Parameter オブジェクトは kind が POSITIONAL_ONLY の場合 None に設定された name を持つことができました。 これはもう許可されません。

class inspect.BoundArguments

Result of a Signature.bind() or Signature.bind_partial() call. Holds the mapping of arguments to the function's parameters.

arguments

An ordered, mutable mapping (collections.OrderedDict) 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.

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
OrderedDict([('a', 'spam'), ('b', 'ham'), ('args', ())])

バージョン 3.5 で追加.

args および kwargs 属性を使用して関数を呼び出すことができます:

def test(a, *, b):
    ...

sig = signature(test)
ba = sig.bind(10, b=20)
test(*ba.args, **ba.kwargs)

参考

PEP 362 - Function Signature Object.
The detailed specification, implementation details and examples.

クラスと関数

inspect.getclasstree(classes, unique=False)

リストで指定したクラスの継承関係から、ネストしたリストを作成します。ネストしたリストには、直前の要素から派生したクラスが格納されます。各要素は長さ2のタプルで、クラスと基底クラスのタプルを格納しています。unique が真の場合、各クラスは戻り値のリスト内に一つだけしか格納されません。真でなければ、多重継承を利用したクラスとその派生クラスは複数回格納される場合があります。

inspect.getargspec(func)

Get the names and default values of a Python function's parameters. A named tuple ArgSpec(args, varargs, keywords, defaults) is returned. args is a list of the parameter names. varargs and keywords are the names of the * and ** parameters or None. defaults is a tuple of default argument values or None if there are no default arguments; if this tuple has n elements, they correspond to the last n elements listed in args.

バージョン 3.0 で非推奨: Use getfullargspec() for an updated API that is usually a drop-in replacement, but also correctly handles function annotations and keyword-only parameters.

Alternatively, use signature() and Signature Object, which provide a more structured introspection API for callables.

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)

Get information about arguments passed into a particular frame. A named tuple ArgInfo(args, varargs, keywords, locals) is returned. args is a list of the argument names. varargs and keywords are the names of the * and ** arguments or None. locals is the locals dictionary of the given frame.

注釈

This function was inadvertently marked as deprecated in Python 3.5.

inspect.formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])

Format a pretty argument spec from the values returned by getfullargspec().

The first seven arguments are (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations).

The other six arguments are functions that are called to turn argument names, * argument name, ** argument name, default values, return annotation and individual annotations into strings, respectively.

例えば:

>>> from inspect import formatargspec, getfullargspec
>>> def f(a: int, b: float):
...     pass
...
>>> formatargspec(*getfullargspec(f))
'(a: int, b: float)'

バージョン 3.5 で非推奨: Use signature() and Signature Object, which provide a better introspecting API for callables.

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)

args と kwds を、Python の関数もしくはメソッド func を呼び出した場合と同じように引数名に束縛します。束縛済みメソッド(bound method)の場合、最初の引数(慣習的に self という名前が付けられます)にも、関連づけられたインスタンスを束縛します。引数名 (* や ** 引数が存在すればその名前も) に args と kwds からの値をマップした辞書を返します。func を正しく呼び出せない場合、つまり func(*args, **kwds) がシグネチャの不一致のために例外を投げるような場合には、それと同じ型で同じか似ているメッセージの例外を発生させます。例:

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

バージョン 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 が送出されます。

バージョン 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.

バージョン 3.4 で追加.

インタープリタスタック

When the following functions return "frame records," each record is a named tuple FrameInfo(frame, filename, lineno, function, code_context, index). The tuple contains the frame object, the filename, the line number of the current line, the function name, a list of lines of context from the source code, and the index of the current line within that list.

バージョン 3.5 で変更: タプルではなく名前付きタプルを返します。

注釈

フレームレコードの最初の要素などのフレームオブジェクトへの参照を保存すると、循環参照になってしまう場合があります。循環参照ができると、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)

フレームまたはトレースバックオブジェクトの情報を取得します。 名前付きタプル Traceback(filename, lineno, function, code_context, index) が返されます。

inspect.getouterframes(frame, context=1)

指定したフレームと、その外側の全フレームのフレームレコードを返します。外側のフレームとは frame が生成されるまでのすべての関数呼び出しを示します。戻り値のリストの先頭は frame のフレームレコードで、末尾の要素は frame のスタックにある最も外側のフレームのフレームレコードとなります。

バージョン 3.5 で変更: A list of named tuples FrameInfo(frame, filename, lineno, function, code_context, index) is returned.

inspect.getinnerframes(traceback, context=1)

指定したフレームと、その内側の全フレームのフレームレコードを返します。内のフレームとは frame から続く一連の関数呼び出しを示します。戻り値のリストの先頭は traceback のフレームレコードで、末尾の要素は例外が発生した位置を示します。

バージョン 3.5 で変更: A list of named tuples FrameInfo(frame, filename, lineno, function, code_context, index) is returned.

inspect.currentframe()

呼び出し元のフレームオブジェクトを返します。

CPython implementation detail: この関数はインタプリタの Python スタックフレームサポートに依存します。これは Python のすべての実装に存在している保証はありません。Python スタックフレームサポートのない環境では、この関数は None を返します。

inspect.stack(context=1)

呼び出し元スタックのフレームレコードのリストを返します。最初の要素は呼び出し元のフレームレコードで、末尾の要素はスタックにある最も外側のフレームのフレームレコードとなります。

バージョン 3.5 で変更: A list of named tuples FrameInfo(frame, filename, lineno, function, code_context, index) is returned.

inspect.trace(context=1)

実行中のフレームと処理中の例外が発生したフレームの間のフレームレコードのリストを返します。最初の要素は呼び出し元のフレームレコードで、末尾の要素は例外が発生した位置を示します。

バージョン 3.5 で変更: A list of named tuples FrameInfo(frame, filename, lineno, function, code_context, index) 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.

バージョン 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

ジェネレータおよびコルーチンの現在の状態

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: 実行が完了しました。

バージョン 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: 実行が完了しました。

バージョン 3.5 で追加.

ジェネレータの現在の内部状態を問い合わせることも出来ます。これは主に内部状態が期待通り更新されているかどうかを確認するためのテストの目的に有用です。

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 implementation detail: This function relies on the generator exposing a Python stack frame for introspection, which isn't guaranteed to be the case in all implementations of Python. In such cases, this function will always return an empty dictionary.

バージョン 3.3 で追加.

inspect.getcoroutinelocals(coroutine)

This function is analogous to getgeneratorlocals(), but works for coroutine objects created by async def functions.

バージョン 3.5 で追加.

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_NOFREE

The flag is set if there are no free or cell variables.

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 for more details.

バージョン 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 for more details.

バージョン 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 for more details.

バージョン 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.

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

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


site --- サイト固有の設定フック

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python ランタイムサービス »

site --- サイト固有の設定フック

ソースコード: Lib/site.py

このモジュールは初期化中に自動的にインポートされます。 自動インポートはインタプリタの -S オプションで禁止できます。

このモジュールをインポートすると、 -S オプションを使わない限り、サイト固有のパスをモジュール検索パスに追加し、いくつかの組み込み関数を追加します。 -S オプションを使った場合、このモジュールはモジュール検索パスの変更や組み込み関数の追加を自動で行うことはなく、安全にインポートできます。 通常のサイト固有の追加処理を明示的に起動するには、 site.main() 関数を呼んでください。

バージョン 3.3 で変更: 以前は -S を使っているときでも、モジュールをインポートするとパス変更が起動されていました。

site.main() 関数の処理は、前部と後部からなる最大で四つまでのディレクトリを構築するところから始まります。 前部では sys.prefix と sys.exec_prefix を使用します; 空の前部は使われません。 後部では、1つ目は空文字列を使い、2つ目は lib/site-packages (Windows) または lib/pythonX.Y/site-packages (Unix と Macintosh) を使います。 前部-後部の異なる組み合わせごとに、それが存在しているディレクトリを参照しているかどうかを調べ、存在している場合は 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" に "false" (大文字小文字は区別しない) 以外が設定されている場合は、 site-packages を探しにシステムレベルのプレフィックスも見に行きます; そうでない場合は見に行きません。

パス設定ファイルは name.pth という形式の名前をもつファイルで、上の4つのディレクトリのひとつにあります。その内容は sys.path に追加される追加項目(一行に一つ)です。存在しない項目は sys.path へは決して追加されませんが、項目がファイルではなくディレクトリを参照しているかどうかはチェックされません。項目が sys.path へ二回以上追加されることはありません。空行と # で始まる行は読み飛ばされます。 import で始まる(そしてその後ろにスペースかタブが続く)行は実行されます。

例えば、 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 はどちらのパス設定ファイルにも記載されていないため、省略されます。

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.

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の間のミスマッチ)あるいは管理者によって、ユーザサイトディレクトリが無効になっていることを示しています。ユーザサイトディレクトリのステータスを示すフラグ。 True の場合、ユーザサイトディレクトリが有効で sys.path に追加されていることを意味しています。 False の場合、ユーザによるリクエスト(オプション -s か PYTHONNOUSERSITE)によって、 None の場合セキュリティ上の理由(ユーザまたはグループIDと実効IDの間のミスマッチ)あるいは管理者によって、ユーザサイトディレクトリが無効になっていることを示しています。

site.USER_SITE

Python 実行時のユーザの site-packages へのパスです。 getusersitepackages() がまだ呼び出されていなければ None かもしれません。デフォルト値は UNIX と frameworkなしの Mac OS X ビルドでは ~/.local/lib/pythonX.Y/site-packages 、Mac framework ビルドでは ~/Library/Python/X.Y/lib/python/site-packages、Windows では %APPDATA%\Python\PythonXY\site-packages です。このディレクトリは site ディレクトリなので、 ここにいる .pth ファイルが処理されます。

site.USER_BASE

ユーザの site-packages のベースとなるディレクトリへのパスです。 getuserbase() がまだ呼び出されていなければ None かもしれません。デフォルト値は UNIX と frameworkなしの Mac OS X ビルドでは ~/.local 、Mac framework ビルドでは ~/Library/Python/X.Y 、Windows では %APPDATA%\Python です。この値は Distutils が、スクリプト、データファイル、Python モジュールなどのインストール先のディレクトリを user installation scheme で計算するのに使われます。 PYTHONUSERBASE も参照してください。

site.main()

モジュール検索パスに標準のサイト固有ディレクトリを追加します。この関数は、Python インタプリタが -S で開始されていない限り、このモジュールインポート時に自動的に呼び出されます。

バージョン 3.3 で変更: この関数は以前は無条件に呼び出されていました。

site.addsitedir(sitedir, known_paths=None)

sys.path にディレクトリを追加し、その .pth ファイル群を処理します。典型的には sitecustomize か usercustomize 内で使われます(上述)。

site.getsitepackages()

全てのグローバルな site-packages ディレクトリのリストを返します。

バージョン 3.2 で追加.

site.getuserbase()

ユーザのベースディレクトリへのパス USER_BASE を返します。未初期化であればこの関数は PYTHONUSERBASE を参考にして、設定もします。

バージョン 3.2 で追加.

site.getusersitepackages()

ユーザのベースディレクトリへのパス USER_SITE を返します。未初期化であればこの関数は PYTHONNOUSERSITE と USER_BASE を参考にして、設定もします。

バージョン 3.2 で追加.

site モジュールはユーザディレクトリをコマンドラインから得る手段も提供しています:

$ python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages

引数なしで呼び出された場合、sys.path の中身を表示し、続けて USER_BASE とそのディレクトリが存在するかどうか、 USER_SITE とそのディレクトリが存在するかどうか、最後に ENABLE_USER_SITE の値を、標準出力に出力します。

--user-base

ユーザのベースディレクトリを表示します。

--user-site

ユーザの site-packages ディレクトリを表示します。

両方のオプションが指定された場合、ユーザのベースとユーザの site が(常にこの順序で) os.pathsep 区切りで表示されます。

If any option is given, the script will exit with one of these values: 0 if the user site-packages directory is enabled, 1 if it was disabled by the user, 2 if it is disabled for security reasons or by an administrator, and a value greater than 2 if there is an error.

参考

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python ランタイムサービス »


カスタム Python インタプリタ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

カスタム Python インタプリタ

この章で解説されるモジュールで Python の対話インタプリタに似たインタフェースを書くことができます。もし Python そのもの以外に何か特殊な機能をサポートした Python インタプリタを作りたければ、 code モジュールを参照してください。 (codeop モジュールはより低レベルで、不完全(かもしれない) Python コード断片のコンパイルをサポートするために使われます。)

この章で解説されるモジュールの完全な一覧は:

  • code --- インタプリタ基底クラス
    • 対話的なインタプリタオブジェクト
    • 対話的なコンソールオブジェクト
  • codeop --- Pythonコードをコンパイルする

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


code --- インタプリタ基底クラス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • カスタム Python インタプリタ »

code --- インタプリタ基底クラス

ソースコード: 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>")

対話的なPythonインタプリタの振る舞いを厳密にエミュレートします。このクラスは InteractiveInterpreter を元に作られていて、通常の sys.ps1 と sys.ps2 をつかったプロンプト出力と入力バッファリングが追加されています。

code.interact(banner=None, readfunc=None, local=None, exitmsg=None)

read-eval-print ループを実行するための便利な関数。これは InteractiveConsole の新しいインスタンスを作り、 readfunc が与えられた場合は InteractiveConsole.raw_input() メソッドとして使われるように設定します。 local が与えられた場合は、インタプリタループのデフォルト名前空間として使うために InteractiveConsole コンストラクタへ渡されます。そして、インスタンスの interact() メソッドは（もし提供されていれば）見出しと終了メッセージして使うために banner と exitmsg を受け取り実行されます。コンソールオブジェクトは使われた後捨てられます。

バージョン 3.6 で変更: exitmsg 引数が追加されました.

code.compile_command(source, filename="<input>", symbol="single")

この関数はPythonのインタプリタメインループ(別名、read-eval-printループ)をエミュレートしようとするプログラムにとって役に立ちます。扱いにくい部分は、ユーザが(完全なコマンドや構文エラーではなく)さらにテキストを入力すれば完全になりうる不完全なコマンドを入力したときを決定することです。この関数は ほとんど の場合に実際のインタプリタメインループと同じ決定を行います。

source はソース文字列です。filename はオプションのソースが読み出されたファイル名で、デフォルトで '<input>' です。symbol はオプションの文法の開始記号で、'single' (デフォルト)または 'eval' のどちらかにすべきです。

コマンドが完全で有効ならば、コードオブジェクトを返します(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)

ソーステキストの一行をインタプリタへ送ります。その行の末尾に改行がついていてはいけません。内部に改行を持っているかもしれません。その行はバッファへ追加され、ソースとして連結された内容が渡されインタプリタの runsource() メソッドが呼び出されます。コマンドが実行されたか、有効であることをこれが示している場合は、バッファはリセットされます。そうでなければ、コマンドが不完全で、その行が付加された後のままバッファは残されます。さらに入力が必要ならば、戻り値は True です。その行がある方法で処理されたならば、 False です(これは runsource() と同じです)。

InteractiveConsole.resetbuffer()

入力バッファから処理されていないソーステキストを取り除きます。

InteractiveConsole.raw_input(prompt="")

プロンプトを書き込み、一行を読み込みます。返る行は末尾に改行を含みません。ユーザがEOFキーシーケンスを入力したときは、 EOFError を発生させます。基本実装では、 sys.stdin から読み込みます。サブクラスはこれを異なる実装と置き換えるかもしれません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • カスタム Python インタプリタ »


codeop --- Pythonコードをコンパイルする

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • カスタム Python インタプリタ »

codeop --- Pythonコードをコンパイルする

ソースコード: Lib/codeop.py

codeop モジュールは、 code モジュールで行われているようなPythonの read-eval-printループをエミュレートするユーティリティを提供します。そのため、このモジュールを直接利用する場面はあまり無いでしょう。プログラムにこのようなループを含めたい場合は、 code モジュールの方が便利です。

この仕事には二つの部分があります:

  1. 入力の一行がPythonの文として完全であるかどうかを見分けられること: 簡単に言えば、次が '>>>' か、あるいは '...' かどうかを見分けます。
  2. どの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' 、デフォルト) 、または 式 としてコンパイルされるかを決定します('eval')。他のどんな値も ValueError を発生させる原因となります。

注釈

ソースの終わりに達する前に、成功した結果をもってパーサは構文解析を止めることがあります。このような場合、後ろに続く記号はエラーとならずに無視されます。例えば、バックスラッシュの後ろに改行が2つあって、その後ろにゴミがあるかもしれません。パーサのAPIがより良くなればすぐに、この挙動は修正されるでしょう。

class codeop.Compile

このクラスのインスタンスは組み込み関数 compile() とシグネチャが一致する __call__() メソッドを持っていますが、インスタンスが __future__ 文を含むプログラムテキストをコンパイルする場合は、インスタンスは有効なその文とともに続くすべてのプログラムテキストを'覚えていて'コンパイルするという違いがあります。

class codeop.CommandCompiler

このクラスのインスタンスは compile_command() とシグネチャが一致する __call__() メソッドを持っています。インスタンスが __future__ 文を含むプログラムテキストをコンパイルする場合に、インスタンスは有効なその文とともにそれに続くすべてのプログラムテキストを'覚えていて'コンパイルするという違いがあります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • カスタム Python インタプリタ »


モジュールのインポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

モジュールのインポート

この章で解説されるモジュールは他のPythonモジュールをインポートする新しい方法と、インポート処理をカスタマイズするためのフックを提供します。

この章で解説されるモジュールの完全な一覧は:

  • zipimport --- Zip アーカイブからモジュールを import する
    • zipimporter オブジェクト
    • 使用例
  • pkgutil --- パッケージ拡張ユーティリティ
  • modulefinder --- スクリプト中で使われているモジュールを検索する
    • ModuleFinder の使用例
  • runpy --- Python モジュールの位置特定と実行
  • importlib --- The implementation of import
    • はじめに
    • 関数
    • importlib.abc -- インポートに関連する抽象基底クラス
    • importlib.resources -- Resources
    • importlib.machinery -- インポータおよびパスフック
    • importlib.util -- インポータのためのユーティリティコード
    • 使用例
      • プログラムからのインポート
      • モジュールがインポートできるか確認する
      • ソースファイルから直接インポートする
      • インポーターのセットアップ
      • Approximating importlib.import_module()

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


zipimport --- Zip アーカイブからモジュールを import する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • モジュールのインポート »

zipimport --- Zip アーカイブからモジュールを import する

このモジュールは、 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 がない場合は、インポートが多少遅くなるかもしれないので注意してください。

アーカイブコメント付きの ZIP アーカイブは現在のところサポートされていません。

参考

PKZIP Application Note
ZIP ファイルフォーマットおよびアルゴリズムを作成した Phil Katz によるドキュメント。
PEP 273 - Zip アーカイブからモジュールをインポートする
このモジュールの実装も行った、James C. Ahlstrom による PEP です。Python 2.3 は PEP 273 の仕様に従っていますが、Just van Rossum の書いた import フックによる実装を使っています。import フックは PEP 302 で解説されています。
PEP 302 - 新たなインポートフック
このモジュールを動作させる助けになっている import フックの追加を提案している PEP です。

このモジュールでは例外を一つ定義しています:

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 を送出します。

find_module(fullname[, path])

fullname で指定されたモジュールを検索します。 fullname は完全に修飾された (ドット表記の) モジュール名でなければなりません。モジュールが見つかった場合には zipimporter インスタンス自体を返し、そうでない場合には None を返します。オプションの path 引数は無視されます --- この引数は importer プロトコルとの互換性を保つためのものです。

get_code(fullname)

fullname に指定したモジュールのコードオブジェクトを返します。モジュールがない場合には ZipImportError を送出します。

get_data(pathname)

pathname に関連付けられたデータを返します。該当するファイルが見つからなかった場合には OSError を送出します。

バージョン 3.3 で変更: 以前は OSError の代わりに IOError が送出されていました。

get_filename(fullname)

指定されたモジュールが import された場合、そのモジュールに設定した __file__ の値を返します。モジュールが見つからない場合、 ZipImportError を送出します。

バージョン 3.1 で追加.

get_source(fullname)

fullname で指定されたモジュールのソースコードを返します。モジュールが見つからない場合、ZipImportError を送出します。アーカイブにはモジュールがあるもののソースコードがない場合、 None を返します。

is_package(fullname)

fullname で指定されたモジュールがパッケージの場合 True を返します。モジュールを見つけられない場合 ZipImportError を送出します。

load_module(fullname)

fullname で指定されたモジュールをロードします。 fullname は完全修飾された (ドット表記の) モジュール名でなければなりません。 import 済みのモジュールを返します。モジュールがない場合には ZipImportError を送出します。

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 --- パッケージ拡張ユーティリティ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • モジュールのインポート »

pkgutil --- パッケージ拡張ユーティリティ

ソースコード: Lib/pkgutil.py

このモジュールはインポートシステムの、特にパッケージサポートに関するユーティリティです。

class pkgutil.ModuleInfo(module_finder, name, ispkg)

モジュールの概要情報を格納する namedtuple

バージョン 3.6 で追加.

pkgutil.extend_path(path, name)

パッケージを構成するモジュールの検索パスを拡張します。パッケージの __init__.py で次のように書くことを意図したものです:

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

上記はパッケージの __path__ に sys.path の全ディレクトリのサブディレクトリとしてパッケージ名と同じ名前を追加します。これは1つの論理的なパッケージの異なる部品を複数のディレクトリに分けて配布したいときに役立ちます。

同時に *.pkg の * の部分が name 引数に指定された文字列に一致するファイルの検索もおこないます。この機能は import で始まる特別な行がないことを除き *.pth ファイルに似ています (site の項を参照)。 *.pkg は重複のチェックを除き、信頼できるものとして扱われます。 *.pkg ファイルの中に見つかったエントリはファイルシステム上に実在するか否かを問わず、そのまますべてパスに追加されます。(このような仕様です。)

入力パスがリストでない場合(フリーズされたパッケージのとき)は何もせずにリターンします。入力パスが変更されていなければ、アイテムを末尾に追加しただけのコピーを返します。

sys.path はシーケンスであることが前提になっています。 sys.path の要素の内、実在するディレクトリを指す文字列となっていないものは無視されます。ファイル名として使ったときにエラーが発生する sys.path の Unicode要素がある場合、この関数(os.path.isdir() を実行している行) で例外が発生する可能性があります。

class pkgutil.ImpImporter(dirname=None)

Python の「旧式の」インポートアルゴリズムをラップする、 PEP 302 に基づく Finder です。

If dirname is a string, a PEP 302 finder is created that searches that directory. If dirname is None, a PEP 302 finder is created that searches the current sys.path, plus any modules that are frozen or built-in.

ImpImporter は現在のところ sys.meta_path に配置しての利用をサポートしていないことに注意してください。

バージョン 3.3 で非推奨: 標準インポートメカニズムが完全に PEP 302 準拠になり、これが importlib で利用可能であるため、このエミュレーションはもはや必要ありません。

class pkgutil.ImpLoader(fullname, file, filename, etc)

Loader that wraps Python's "classic" import algorithm.

バージョン 3.3 で非推奨: 標準インポートメカニズムが完全に PEP 302 準拠になり、これが importlib で利用可能であるため、このエミュレーションはもはや必要ありません。

pkgutil.find_loader(fullname)

Retrieve a module loader for the given fullname.

これは後方互換性のために提供している importlib.util.find_spec() へのラッパーで、そこでのほどんどの失敗を ImportError に変換し、完全な ModuleSpec を返す代わりにローダのみを返しています。

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

バージョン 3.4 で変更: PEP 451 ベースに更新されました。

pkgutil.get_importer(path_item)

Retrieve a finder for the given path_item.

The returned finder is cached in sys.path_importer_cache if it was newly created by a path hook.

キャッシュ (やその一部) は、 sys.path_hooks のリスキャンが必要になった場合は手動でクリアすることができます。

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.get_loader(module_or_name)

Get a loader object for module_or_name.

module か package が通常の import 機構によってアクセスできる場合、その機構の該当部分に対するラッパーを返します。モジュールが見つからなかったり import できない場合は None を返します。その名前のモジュールがまだ import されていない場合、そのモジュールを含むパッケージが(あれば)そのパッケージの __path__ を確立するために import されます。

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

バージョン 3.4 で変更: PEP 451 ベースに更新されました。

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 されます。

If no module name is specified, all top level finders are produced.

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.iter_modules(path=None, prefix='')

Yields ModuleInfo for all submodules on path, or, if path is None, all top-level modules on sys.path.

path は None か、モジュールを検索する path のリストのどちらかでなければなりません。

prefix は出力の全てのモジュール名の頭に出力する文字列です。

注釈

これは iter_modules() メソッドを定義している finder に対してのみ動作します。このインターフェイスは非標準なので、モジュールは importlib.machinery.FileFinder と zipimport.zipimporter の実装も提供します。

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.walk_packages(path=None, prefix='', onerror=None)

Yields ModuleInfo for all modules recursively on path, or, if path is None, all accessible modules.

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 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.get_data(package, resource)

パッケージからリソースを取得します。

This is a wrapper for the loader get_data API. The package argument should be the name of a package, in standard module format (foo.bar). The resource argument should be in the form of a relative filename, using / as the path separator. The parent directory name .. is not allowed, and nor is a rooted name (starting with a /).

この関数が返すのは指定されたリソースの内容であるバイナリ文字列です。

ファイルシステム中に位置するパッケージで既にインポートされているものに対しては、次と大体同じです:

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.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • モジュールのインポート »


modulefinder --- スクリプト中で使われているモジュールを検索する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • モジュールのインポート »

modulefinder --- スクリプト中で使われているモジュールを検索する

ソースコード: 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__
sre_compile:  isstring,_sre,_optimize_unicode
_sre:
sre_constants:  REPEAT_ONE,makedict,AT_END_LINE
sys:
re:  __module__,finditer,_expand
itertools:
__main__:  re,itertools,baconhameggs
sre_parse:  _PATTERNENDERS,SRE_FLAG_UNICODE
array:
types:  __module__,IntType,TypeType
---------------------------------------------------
Modules not imported:
guido.python.ham
baconhameggs

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • モジュールのインポート »


runpy --- Python モジュールの位置特定と実行

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • モジュールのインポート »

runpy --- Python モジュールの位置特定と実行

ソースコード: 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)

指定されたモジュールのコードを実行し、実行後のモジュールグローバル辞書を返します。モジュールのコードはまず標準インポート機構(詳細は PEP 302 を参照) を使ってモジュールの位置を特定され、まっさらなモジュール名前空間で実行されます。

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.

オプションの辞書型引数 init_globals はコードを実行する前にモジュールグローバル辞書に前もって必要な設定しておくのに使われます。与えられた辞書は変更されません。その辞書の中に以下に挙げる特別なグローバル変数が定義されていたとしても、それらの定義は run_module() 関数によってオーバーライドされます。

特別なグローバル変数 __name__, __spec__, __file__, __cached__, __loader__, __package__ はモジュールコードが実行される前にグローバル辞書にセットされます。(この変数群は修正される最小セットです。これ以外の変数もインタプリタの実装の詳細として暗黙的に設定されるかもしれません)。

__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__] はどちらも関数が処理を戻す前にもとの値に復旧します。

この sys に対する操作はスレッドセーフではないということに注意してください。他のスレッドは部分的に初期化されたモジュールを見たり、入れ替えられた引数リストを見たりするかもしれません。この関数をスレッド化されたコードから起動するときは sys モジュールには手を触れないことが推奨されます。

参考

コマンドラインから、 -m オプションを与えることで同じ機能を実現出来ます。

バージョン 3.1 で変更: __main__ サブモジュールを検索することによってパッケージを実行する機能が追加されました。

バージョン 3.2 で変更: __cached__ グローバル変数が追加されました ( PEP 3147 を参照)。

バージョン 3.4 で変更: Updated to take advantage of the module spec feature added by PEP 451. 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.

runpy.run_path(file_path, init_globals=None, run_name=None)

指定されたファイルシステム上の場所にあるコードを実行して、結果としてそのモジュールグローバル辞書を返します。通常の CPython 実行時にコマンドラインで指定するスクリプト名と同じく、指定できるパスは Python ソースファイル、コンパイルされたバイトコードファイル、もしくは __main__ モジュールを含む有効な sys.path エントリ(例: トップレベルに __main__.py ファイルを持つ zip ファイル)です。

シンプルなスクリプトを指定した場合は、指定されたコードはシンプルに新しいモジュール名前空間で実行されます。有効な sys.path エントリ (一般的には zip ファイルかディレクトリ) を指定した場合は、最初にそのエントリが sys.path の先頭に追加されます。次に更新した sys.path を元に __main__ モジュールを検索して実行します。指定された場所に __main__ モジュールが無かった時、 sys.path のどこか他のエントリに存在する別の __main__ を実行してしまう可能性があることに注意してください。

オプションの辞書型引数 init_globals はコードを実行する前にモジュールグローバル辞書に前もって必要な設定しておくのに使われます。与えられた辞書は変更されません。その辞書の中に以下に挙げる特別なグローバル変数が定義されていたとしても、それらの定義は run_path() 関数によってオーバーライドされます。

特別なグローバル変数 __name__, __spec__, __file__, __cached__, __loader__, __package__ はモジュールコードが実行される前にグローバル辞書にセットされます。(この変数群は修正される最小セットです。これ以外の変数もインタプリタの実装の詳細として暗黙的に設定されるかもしれません)。

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

sys モジュールに対していくつかの変更操作が行われます。まず、 sys.path が上記のように修正されます。 sys.argv[0] は file_path に更新され、 sys.modules[__name__] は実行されるモジュールのための一時モジュールオブジェクトに更新されます。 sys の要素に対する全ての変更は、この関数から戻る前に元に戻されます。

run_module() と違い、 sys に対する変更はオプションではありません。これらの変更は sys.path エントリの実行に必要不可欠だからです。スレッドセーフ性に関する制限はこの関数にも存在します。この関数をマルチスレッドプログラムから実行する場合は、 import lock によりシリアライズして実行するか、別プロセスに委譲してください。

参考

コマンドラインから インターフェイスオプション で同じ機能を使えます (python path/to/script)。

バージョン 3.2 で追加.

バージョン 3.4 で変更: Updated to take advantage of the module spec feature added by PEP 451. 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.

参考

PEP 338 - モジュールをスクリプトとして実行する
Nick Coghlan によって書かれ実装された PEP。
PEP 366 - main モジュールの明示的な相対インポート
Nick Coghlan によって書かれ実装された PEP。
PEP 451 -- A ModuleSpec Type for the Import System
PEP written and implemented by Eric Snow

コマンドラインと環境 - CPython コマンドライン詳細

importlib.import_module() 関数

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • モジュールのインポート »


importlib --- The implementation of import

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • モジュールのインポート »

importlib --- The implementation of import

バージョン 3.1 で追加.

ソースコード: Lib/importlib/__init__.py

はじめに

The purpose of the importlib package is two-fold. One is to provide the implementation of the import statement (and thus, by extension, the __import__() function) in Python source code. This provides an implementation of import which is portable to any Python interpreter. This also provides an implementation which is easier to comprehend than one implemented in a programming language other than Python.

2つ目の目的は、このパッケージが公開している import を実装するための要素を利用して、(インポーター として知られる) インポートプロセスで動作するカスタムのオブジェクトを実装しやすくすることです。

参考

The import statement
import 文の言語リファレンス。
Packages specification
パッケージの元の仕様。幾つかの動作はこの仕様が書かれた頃から変更されています (例: sys.modules で None に基づくリダイレクト)。
__import__() 関数
import 文はこの関数のシンタックスシュガーです。
PEP 235
大文字小文字を区別しないプラットフォームでのインポート
PEP 263
Python のソースコードのエンコーディング
PEP 302
新しいインポートフック
PEP 328
複数行のインポートと、絶対/相対インポート
PEP 366
main モジュールの明示的な相対インポート
PEP 420
暗黙的な名前空間パッケージ
PEP 451
インポートシステムのための ModuleSpec 型
PEP 488
PYO ファイルの撤廃
PEP 489
複数フェーズでの拡張モジュールの初期化
PEP 552
Deterministic pycs
PEP 3120
デフォルトのソースエンコーディングとして UTF-8 を使用
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.find_loader(name, path=None)

モジュールのローダーを、オプションで指定された path 内から、検索します。モジュールが sys.modules にあれば、 sys.modules[name].__loader__ が返されます (ただしローダーが None であるか設定されていなければ ValueError が送出されます)。なければ、 sys.meta_path を使った検索がなされます。ローダーが見つからなければ None が返ります。

ドットのついた名前表記は、親モジュールのロードが必要なときに暗黙にインポートしないので、望ましくありません。 サブモジュールを適切にインポートするには、そのサブモジュールの全ての親パッケージをインポートし、 path に正しい引数を使ってください。

バージョン 3.3 で追加.

バージョン 3.4 で変更: __loader__ が set でない場合、None に設定されているときと同様に ValueError を送出します。

バージョン 3.4 で非推奨: 代わりに importlib.util.find_spec() を使用してください。

importlib.invalidate_caches()

sys.meta_path に保存されたファインダーの内部キャッシュを無効にします。ファインダーが invalidate_caches() を実装していれば、無効化を行うためにそれが呼び出されます。すべてのファインダーが新しいモジュールの存在に気づくことを保証しているプログラムの実行中に、モジュールが作成またはインストールされたなら、この関数が呼び出されるべきです。

バージョン 3.3 で追加.

importlib.reload(module)

以前にインポートされた module をリロードします。引数はモジュールオブジェクトでなければならず、したがってそれ以前に必ずインポートに成功していなければなりません。この関数は、モジュールのソースファイルを外部エディタで編集していて Python インタープリタから離れることなく新しいバージョンを試したい際に便利です。戻り値はモジュールオブジェクトです。 (もし再インポートが異なるオブジェクトを sys.modules に配置したら、元の module とは異なるかもしれません。)

reload() が実行された場合:

  • Python モジュールのコードは再コンパイルされ、モジュールレベルのコードが再度実行されます。モジュールの辞書中にある何らかの名前に結び付けられたオブジェクトは、そのモジュールを最初にロードしたときの ローダー を再利用して新たに定義されます。拡張モジュールの init 関数が二度呼び出されることはありません。
  • Python における他のオブジェクトと同様、以前のオブジェクトのメモリ領域は、参照カウントがゼロにならないかぎり再利用されません。
  • モジュール名前空間内の名前は新しいオブジェクト (または更新されたオブジェクト) を指すよう更新されます。
  • 以前のオブジェクトが (外部の他のモジュールなどからの) 参照を受けている場合、それらを新たなオブジェクトに再束縛し直すことはないので、必要なら自分で名前空間を更新しなければなりません。

いくつか補足説明があります:

モジュールが再ロードされた際、その辞書 (モジュールのグローバル変数を含みます) はそのまま残ります。名前の再定義を行うと、以前の定義を上書きするので、一般的には問題はありません。新たなバージョンのモジュールが古いバージョンで定義された名前を定義していない場合、古い定義がそのまま残ります。辞書がグローバルテーブルやオブジェクトのキャッシュを維持していれば、この機能をモジュールを有効性を引き出すために使うことができます --- つまり、 try 文を使えば、必要に応じてテーブルがあるかどうかをテストし、その初期化を飛ばすことができます:

try:
    cache
except NameError:
    cache = {}

組み込みモジュールや動的にロードされるモジュールを再ロードすることは、一般的にそれほど便利ではありません。 sys, __main__, builtins やその他重要なモジュールの再ロードはお勧め出来ません。多くの場合、拡張モジュールは 1 度以上初期化されるようには設計されておらず、再ロードされた場合には何らかの理由で失敗するかもしれません。

If a module imports objects from another module using from ... import ..., calling reload() for the other module does not redefine the objects imported from it --- one way around this is to re-execute the from statement, another is to use import and qualified names (module.name) instead.

あるモジュールがクラスのインスタンスを生成している場合、そのクラスを定義しているモジュールの再ロードはそれらインスタンスのメソッド定義に影響しません --- それらは古いクラス定義を使い続けます。これは派生クラスの場合でも同じです。

バージョン 3.4 で追加.

バージョン 3.7 で変更: ModuleNotFoundError is raised when the module being reloaded lacks a ModuleSpec.

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

ソースコード: Lib/importlib/abc.py

importlib.abc モジュールは、 import に使われるすべてのコア抽象基底クラス含みます。コア抽象基底クラスの実装を助けるために、コア抽象基底クラスのサブクラスもいくつか提供されています。

抽象基底クラス階層:

object
 +-- Finder (deprecated)
 |    +-- MetaPathFinder
 |    +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader
class importlib.abc.Finder

finder を表す抽象基底クラスです。

バージョン 3.3 で非推奨: 代わりに MetaPathFinder または PathEntryFinder を使ってください。

abstractmethod find_module(fullname, path=None)

An abstract method for finding a loader for the specified module. Originally specified in PEP 302, this method was meant for use in sys.meta_path and in the path-based import subsystem.

バージョン 3.4 で変更: 呼び出されたときに NotImplementedError を送出する代わりに None を返します。

class importlib.abc.MetaPathFinder

meta path finder を表す抽象基底クラスです。互換性のため、これは Finder のサブクラスです。

バージョン 3.3 で追加.

find_spec(fullname, path, target=None)

指定されたモジュールに対応する スペック を検索する抽象メソッド。もしこれがトップレベルのインポートなら、 path は None です。そうでなければ、これはサブパッケージまたはモジュールのための検索で、 path は親パッケージの __path__ の値です。スペックが見つからなければ None が返されます。 target は、渡されてきたならモジュールオブジェクトです。これはファインダーがどのようなスペックを返せばよいか推測するために使用します。

バージョン 3.4 で追加.

find_module(fullname, path)

指定されたモジュールの ローダー を検索するためのレガシーなメソッドです。これがトップレベルのインポートなら、 path は None になります。そうでなければ、これはサブパッケージまたはモジュールの検索で、 path は親パッケージの __path__ の値になります。ローダーが見つからなければ、 None が返されます。

find_spec() が定義された場合、後方互換な機能が提供されます。

バージョン 3.4 で変更: このメソッドが呼ばれた場合 NotImplementedError を投げる代わりに None を返します。この機能を提供するのに find_spec() を使用できます。

バージョン 3.4 で非推奨: 代わりに find_spec() を使用してください。

invalidate_caches()

このファインダーで使われている内部キャッシュがあれば無効にするオプションのメソッドです。 sys.meta_path 上のすべてのファインダーのキャッシュを無効化する際、 importlib.invalidate_caches() によって使われます。

バージョン 3.4 で変更: 呼び出されたときに NotImplemented を送出する代わりに None を返します。

class importlib.abc.PathEntryFinder

パスエントリ・ファインダー を表す抽象基底クラスです。 MetaPathFinder と似ているところがありますが、 PathEntryFinder は PathFinder の与えるパスに基づくインポートサブシステムの中でのみ使うことが意図されています。この抽象基底クラスは互換性の理由だけのために、 Finder のサブクラスにしてあります。

バージョン 3.3 で追加.

find_spec(fullname, target=None)

指定されたモジュールに対応する スペック を検索する抽象メソッド。ファインダーは、割り当てられている パス・エントリー 内のモジュールだけを検索します。スペックが見つからなければ None が返されます。 target は、渡されてきたならモジュールオブジェクトです。これはファインダーがどのようなスペックを返せばよいか推測するために使用します。

バージョン 3.4 で追加.

find_loader(fullname)

指定されたモジュールの ローダー を検索する抽象メソッドです。 (loader, portion) の 2-タプルを返します。ただし portion は名前空間パッケージの部分に寄与するファイルシステム上の場所のシーケンスです。 loader は名前空間パッケージへのファイルシステム上の場所の寄与を表す portion を明記するとき None にできます。loader が名前空間パッケージの一部ではないことを明記するとき portion に空のリストが使えます。 loader が None で portion が空のリストなら、名前空間パッケージのローダーや場所が見つかりませんでした (すなわち、モジュールの何も見つかりませんでした)。

find_spec() が定義された場合、後方互換な機能が提供されます。

バージョン 3.4 で変更: NotImplementedError を送出する代わりに (None, []) を返します。機能を提供できる場合 find_spec() を使用します。

バージョン 3.4 で非推奨: 代わりに find_spec() を使用してください。

find_module(fullname)

Finder.find_module() の具象実装で、 self.find_loader(fullname)[0] と等価です。

バージョン 3.4 で非推奨: 代わりに find_spec() を使用してください。

invalidate_caches()

このファインダーで使われている内部キャッシュがあれば無効にするオプションのメソッドです。キャッシュされたすべてのファインダーの無効化する際、 PathFinder.invalidate_caches() によって使われます。

class importlib.abc.Loader

loader の抽象基底クラスです。ローダーの厳密な定義は PEP 302 を参照してください。

Loaders that wish to support resource reading should implement a get_resource_reader(fullname) method as specified by importlib.abc.ResourceReader.

バージョン 3.7 で変更: Introduced the optional get_resource_reader() method.

create_module(spec)

モジュールをインポートする際に使用されるモジュールオブジェクトを返すメソッド。このメソッドは None を戻すことができ、その場合はデフォルトのモジュール作成のセマンティクスが適用されることを示します。

バージョン 3.4 で追加.

バージョン 3.5 で変更: Python 3.6 からは、 exec_module() が定義されている場合は、このメソッドはオプションではなくなります。

exec_module(module)

モジュールがインポートまたはリロードされる際に、そのモジュールをモジュール自身の名前空間の中で実行する抽象的なメソッド。 exec_module() が呼ばれる時点で、モジュールはすでに初期設定されている必要があります。 このメソッドが存在するときは、 create_module() の定義が必須です。

バージョン 3.4 で追加.

バージョン 3.6 で変更: create_module() の定義が必須となりました。

load_module(fullname)

モジュールをロードするためのレガシーなメソッドです。モジュールがロードできなければ ImportError を送出し、ロードできればロードされたモジュールを返します。

要求されたモジュールが既に sys.modules に存在したなら、そのモジュールが使われリロードされる必要があります。存在しなければ、インポートからの再帰を防ぐため、ローダーはロードが始まる前に新しいモジュールを作成して sys.modules に挿入する必要があります。ローダーがモジュールを挿入した後にロードが失敗したなら、ローダーはそのモジュールを sys.modules から削除する必要があります。ローダーが実行を始める前に既に sys.modules にあったモジュールは、そのままにします (importlib.util.module_for_loader() を参照してください)。

ローダーはモジュールにいくつかの属性を設定する必要があります。(なお、これらの属性には、モジュールがリロードされた際に変化するものがあります):

  • __name__
    モジュールの名前です。
  • __file__
    モジュールのデータが保存されている場所へのパスです (組み込みモジュールには設定されません)。
  • __cached__
    モジュールのコンパイルされた版が保存されている (べき) 場所へのパスです (この属性が適切でないときには設定されません)。
  • __path__
    パッケージ内の検索パスを指定する文字列のリストです。この属性はモジュールには設定されません。
  • __package__
    モジュールやパッケージの親パッケージです。そのモジュールがトップレベルなら、空文字列の値をとります。 importlib.util.module_for_loader() デコレータで、__package__ の詳細を扱えます。
  • __loader__
    モジュールをロードするのに使われたローダーです。 importlib.util.module_for_loader() デコレータで、 __package__ の詳細を扱えます。

exec_module() が利用可能な場合、後方互換な機能が提供されます。

バージョン 3.4 で変更: このメソッドが呼ばれた時に、 NotImplementedError の代わりに ImportError を送出します。 exec_module() が利用可能な時は、この機能は提供されます。

バージョン 3.4 で非推奨: モジュールをロードするための推奨される API は、 exec_module() (および create_module()) です。ローダーは load_module() の代わりにそれを実装するべきです。 exec_module() が実装されている場合、インポート機構は load_module() の他のすべての責任を肩代わりします。

module_repr(module)

実装されていた場合、与えられたモジュールの repr を計算して文字列として返すためのレガシーなメソッドです。モジュール型のデフォルトの repr() は、必要に応じてこのメソッドの結果を使います。

バージョン 3.3 で追加.

バージョン 3.4 で変更: 抽象メソッドではなくオプショナルになりました。

バージョン 3.4 で非推奨: インポート機構はこれを自動的に考慮するようになりました。

class importlib.abc.ResourceReader

An abstract base class to provide the ability to read resources.

From the perspective of this ABC, a resource is a binary artifact that is shipped within a package. Typically this is something like a data file that lives next to the __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_loader(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.7 で追加.

abstractmethod open_resource(resource)

Returns an opened, file-like object for binary reading of the resource.

If the resource cannot be found, FileNotFoundError is raised.

abstractmethod resource_path(resource)

Returns the file system path to the resource.

If the resource does not concretely exist on the file system, raise FileNotFoundError.

abstractmethod is_resource(name)

Returns True if the named name is considered a resource. FileNotFoundError is raised if name does not exist.

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

loader の抽象基底クラスで、ストレージバックエンドから任意のリソースをロードするオプションの PEP 302 プロトコルを実装します。

バージョン 3.7 で非推奨: This ABC is deprecated in favour of supporting resource loading through importlib.abc.ResourceReader.

abstractmethod get_data(path)

path に割り当てられたデータのバイト列を返す抽象メソッドです。任意のデータを保管できるファイル的なストレージバックエンドをもつローダーは、この抽象メソッドを実装して、保管されたデータに直接アクセスさせるようにできます。 path が見つからなければ OSError を送出する必要があります。 path は、モジュールの __file__ 属性を使って、またはパッケージの __path__ の要素を使って、構成されることが期待されます。

バージョン 3.4 で変更: NotImplementedError の代わりに OSError を送出します。

class importlib.abc.InspectLoader

loader の抽象基底クラスで、ローダーがモジュールを検査するためのオプションの PEP 302 プロトコルを実装します。

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__) を呼ぶことでモジュール内でコードを実行できます。

バージョン 3.4 で追加.

バージョン 3.5 で変更: スタティックメソッドになりました。

exec_module(module)

Loader.exec_module() の実装です。

バージョン 3.4 で追加.

load_module(fullname)

Loader.load_module() の実装です。

バージョン 3.4 で非推奨: 代わりに exec_module() を使用してください。

class importlib.abc.ExecutionLoader

InspectLoader から継承された抽象基底クラスで、実装されていれば、モジュールをスクリプトとして実行する助けになります。この抽象基底クラスはオプションの PEP 302 プロトコルを表します。

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 引数は、モジュールのファイルへのパスです。

バージョン 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 が送出されます。

バージョン 3.3 で追加.

バージョン 3.4 で変更: NotImplementedError の代わりに OSError を送出します。

path_mtime(path)

指定されたパスの更新時刻を返す、オプションの抽象メソッドです。

バージョン 3.3 で非推奨: このメソッドは廃止され、 path_stats() が推奨されます。このモジュールを実装する必要はありませんが、互換性のため現在も利用できます。パスが扱えなければ、 OSError が送出されます。

バージョン 3.4 で変更: NotImplementedError の代わりに OSError を送出します。

set_data(path, data)

ファイルパスに指定されたバイト列を書き込むオプションの抽象メソッドです。存在しない中間ディレクトリがあれば、自動で作成されます。

パスへの書き込みが読み出し専用のために失敗したとき (errno.EACCES/PermissionError) 、その例外を伝播させません。

バージョン 3.4 で変更: 呼ばれたときに NotImplementedError を送出することは最早ありません。

get_code(fullname)

InspectLoader.get_code() の具象実装です。

exec_module(module)

Loader.exec_module() の具象実装です。

バージョン 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__ で終わらないこと。

importlib.resources -- Resources

Source code: Lib/importlib/resources.py

バージョン 3.7 で追加.

This module leverages Python's import system to provide access to resources within packages. If you can import a package, you can access resources within that package. Resources can be opened or read, in either binary or text mode.

Resources are roughly akin to files inside directories, though it's important to keep in mind that this is just a metaphor. Resources and packages do not have to exist as physical files and directories on the file system.

注釈

This module provides functionality similar to pkg_resources Basic Resource Access without the performance overhead of that package. This makes reading resources included in packages easier, with more stable and consistent semantics.

The standalone backport of this module provides more information on using importlib.resources and migrating from pkg_resources to importlib.resources.

Loaders that wish to support resource reading should implement a get_resource_reader(fullname) method as specified by importlib.abc.ResourceReader.

The following types are defined.

importlib.resources.Package

The Package type is defined as Union[str, ModuleType]. This means that where the function describes accepting a Package, you can pass in either a string or a module. Module objects must have a resolvable __spec__.submodule_search_locations that is not None.

importlib.resources.Resource

This type describes the resource names passed into the various functions in this package. This is defined as Union[str, os.PathLike].

The following functions are available.

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.

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.

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.

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.

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

importlib.resources.is_resource(package, name)

Return True if there is a resource named name in the package, otherwise False. Remember that directories are not resources! package is either a name or a module object which conforms to the Package requirements.

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.

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

ソースコード: Lib/importlib/machinery.py

このモジュールには、 import がモジュールを検索してロードするのに役立つ様々なオブジェクトがあります。

importlib.machinery.SOURCE_SUFFIXES

認識されているソースモジュールのファイル接尾辞を表す文字列のリストです。

バージョン 3.3 で追加.

importlib.machinery.DEBUG_BYTECODE_SUFFIXES

最適化されていないバイトコードモジュールのファイル接尾辞を表す文字列のリストです。

バージョン 3.3 で追加.

バージョン 3.5 で非推奨: 代わりに BYTECODE_SUFFIXES を使ってください。

importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES

最適化されたバイトコードモジュールのファイル接尾辞を表す文字列のリストです。

バージョン 3.3 で追加.

バージョン 3.5 で非推奨: 代わりに BYTECODE_SUFFIXES を使ってください。

importlib.machinery.BYTECODE_SUFFIXES

認識されているバイトコードモジュールのファイル接尾辞を表す文字列のリストです (先頭のドットを含みます)。

バージョン 3.3 で追加.

バージョン 3.5 で変更: この値は __debug__ に依存しなくなりました。

importlib.machinery.EXTENSION_SUFFIXES

認識されている最適化された拡張モジュールのファイル接尾辞を表す文字列のリストです。

バージョン 3.3 で追加.

importlib.machinery.all_suffixes()

標準のインポート機構によって認識されているすべてのファイル接尾辞を表す文字列の組み合わせられたリストを返します。これが役立つのは、あるファイルシステムパスがモジュールを参照する可能性があるかだけを知りたくて、そのモジュールの種類を詳しく知る必要はないコード (例えば inspect.getmodulename()) です。

バージョン 3.3 で追加.

class importlib.machinery.BuiltinImporter

組み込みモジュールの importer です。すべての既知のモジュールは sys.builtin_module_names に列挙されています。このクラスは importlib.abc.MetaPathFinder および importlib.abc.InspectLoader 抽象基底クラスを実装します。

インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

バージョン 3.5 で変更: PEP 489 の一環として、ビルトインインポーターは Loader.create_module() と Loader.exec_module() を実装しています。

class importlib.machinery.FrozenImporter

フリーズされたモジュールの インポーター です。このクラスは importlib.abc.MetaPathFinder および importlib.abc.InspectLoader 抽象基底クラスを実装します。

インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

class importlib.machinery.WindowsRegistryFinder

Windows レジストリで宣言されたモジュールの Finder です。このクラスは importlib.abc.MetaPathFinder 抽象基底クラスを実装します。

インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

バージョン 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 が保管され、また返されます。

バージョン 3.4 で追加.

バージョン 3.5 で変更: もしカレントワーキングディレクトリ -- 空の文字列によって表されている -- がすでに有効でなければ、 None が返されますが値は sys.path_importer_cache にキャッシュされません。

classmethod find_module(fullname, path=None)

find_spec() まわりのレガシーなラッパです。

バージョン 3.4 で非推奨: 代わりに find_spec() を使用してください。

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() を呼び出してください。

バージョン 3.3 で追加.

path

ファインダーが検索されるパスです。

find_spec(fullname, target=None)

path 内で fullname を扱うスペックの探索を試みます。

バージョン 3.4 で追加.

find_loader(fullname)

path 内で fullname を扱うローダーの検索を試みます。

invalidate_caches()

内部キャッシュを完全に消去します。

classmethod path_hook(*loader_details)

sys.path_hooks で使用するクロージャを返すクラスメソッドです。クロージャに直接渡された path 引数を直接的に、 loader_details を間接的に使って、 FileFinder のインスタンスが返されます。

クロージャへの引数が存在するディレクトリでなければ、 ImportError が送出されます。

class importlib.machinery.SourceFileLoader(fullname, path)

importlib.abc.FileLoader を継承し、その他いくつかのメソッドの具象実装を提供する、 importlib.abc.SourceLoader の具象実装です。

バージョン 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 ではバイトコードフォーマットが変更されていたら使用できません。

バージョン 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 引数は拡張モジュールのファイルへのパスです。

バージョン 3.3 で追加.

name

ローダーがサポートするモジュールの名前です。

path

拡張モジュールへのパスです。

create_module(spec)

与えられたスペックから PEP 489 に従ってモジュールオブジェクトを作成します。

バージョン 3.5 で追加.

exec_module(module)

与えられたモジュールオブジェクトを PEP 489 に従って初期化します。

バージョン 3.5 で追加.

is_package(fullname)

EXTENSION_SUFFIXES に基づいて、ファイルパスがパッケージの __init__ モジュールを指していれば True を返します。

get_code(fullname)

拡張モジュールにコードオブジェクトがなければ None を返します。

get_source(fullname)

拡張モジュールにソースコードがなければ None を返します。

get_filename(fullname)

path を返します。

バージョン 3.4 で追加.

class importlib.machinery.ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)

モジュールのインポートシステムに関する状態の仕様。 これは通常はモジュールの __spec__ 属性として公開されています。 この後の解説では、モジュールオブジェクトから直接利用できる属性で、それぞれの仕様に対応しているものの名前が括弧書きで書かれています。 例えば、 module.__spec__.origin == module.__file__ です。 ただし、属性の 値 はたいていは同一ですが、2つのオブジェクトどうしは同期されないため、異なっている可能性があることに注意してください。 例えば、モジュールの __path__ を実行時に更新できますが、 __spec__.submodule_search_locations に自動的には反映されません。

バージョン 3.4 で追加.

name

(__name__)

モジュールの完全修飾名を表す文字列です。

loader

(__loader__)

ロードに使うローダです。名前空間パッケージの場合 None に設定しなければなりません。

origin

(__file__)

Name of the place from which the module is loaded, e.g. "builtin" for built-in modules and the filename for modules loaded from source. Normally "origin" should be set, but it may be None (the default) which indicates it is unspecified (e.g. for namespace packages).

submodule_search_locations

(__path__)

パッケージの場合サブモジュールを見付けるべき場所を表す文字列のリスト (そうでない場合は None) です。

loader_state

ロード中に使う拡張モジュール指定のデータのコンテナ (または None) です。

cached

(__cached__)

コンパイルされたモジュールを保存すべき場所を表す文字列 (または None) です。

parent

(__package__)

(読み出し専用) サブモジュールとしてモジュールが属するパッケージの完全修飾名 (または None) です。

has_location

モジュールの "origin" 属性がロード可能な場所を参照しているかどうかを示すブール値です。

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

ソースコード: Lib/importlib/util.py

このモジュールには、 インポーター の構築を助ける様々なオブジェクトがあります。

importlib.util.MAGIC_NUMBER

バイトコードバージョン番号を表しているバイト列。バイトコードのロード／書き込みについてヘルプが必要なら importlib.abc.SourceLoader を参照してください。

バージョン 3.4 で追加.

importlib.util.cache_from_source(path, debug_override=None, *, optimization=None)

ソース path に関連付けられたバイトコンパイルされたファイルの PEP 3147/ PEP 488 パスを返します。例えば、 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 が上げられます。

バージョン 3.4 で追加.

バージョン 3.5 で変更: optimization パラメータが追加され、 debug_override パラメータは deprecated になりました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

importlib.util.source_from_cache(path)

Given the path to a PEP 3147 file name, return the associated source code file path. For example, if path is /foo/bar/__pycache__/baz.cpython-32.pyc the returned path would be /foo/bar/baz.py. path need not exist, however if it does not conform to PEP 3147 or PEP 488 format, a ValueError is raised. If sys.implementation.cache_tag is not defined, NotImplementedError is raised.

バージョン 3.4 で追加.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

importlib.util.decode_source(source_bytes)

与えられたソースコードを表すバイト列をデコードして、文字列としてそれを一般的な改行形式 (universal newlines) で返します (importlib.abc.InspectLoader.get_source() で要求されるように)。

バージョン 3.4 で追加.

importlib.util.resolve_name(name, package)

相対的なモジュール名を解決して絶対的なものにします。

name の先頭にドットがなければ、単に name が返されます。これにより、例えば importlib.util.resolve_name('sys', __package__) を使うときに package 変数が必要かどうかを確認する必要がなくなります。

name が相対的なモジュール名であるにもかかわらず package が偽値 (例えば None や空文字列) ならば、 ValueError が送出されます。相対的な名前がそれを含むパッケージから抜け出る (例えば spam パッケージ内から ..bacon を要求する) 場合にも ValueError が送出されます。

バージョン 3.3 で追加.

importlib.util.find_spec(name, package=None)

モジュールの spec を、オプションで指定された package 名に対する相対で検索します。モジュールが sys.modules にあれば、 sys.modules[name].__spec__ が返されます (ただしスペックが None であるか設定されていなければ ValueError が送出されます)。なければ、 sys.meta_path を使った検索がなされます。スペックが見つからなければ None が返ります。

name がサブモジュールを示している (ドットを含む) 場合、親モジュールは自動的にインポートされます。

name と package は import_module() に対するものと同じように機能します。

バージョン 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 が使用されるからです。

バージョン 3.5 で追加.

@importlib.util.module_for_loader

ロードに使う適切なモジュールオブジェクトの選択を扱うための、 importlib.abc.Loader.load_module() への decorator です。このデコレータメソッドのシグニチャは、2 つの位置引数をとることを期待されます (例えば load_module(self, module)) 。第2引数はローダーによって使われるモジュール object になります。なお、このデコレータは 2 つの引数を想定するため、スタティックメソッドには働きません。

デコレートされたメソッドは、 loader がロードしようとするモジュールの name を受け取ります。そのモジュールが sys.modules に見つからなければ新しいモジュールが構築されます。モジュールの出所に関わらず、 __loader__ は self に設定され、 (もし利用可能なら) __package__ は importlib.abc.InspectLoader.is_package() の戻り値に基づいて設定されます。これらの属性は、リロードをサポートするために無条件に設定されます。

デコレートされたメソッドによって例外が送出されたとき、モジュールが sys.modules に加えられていたら、部分的に初期化されたモジュールが sys.modules に残らないよう、そのモジュールは取り除かれます。モジュールが既に sys.modules にあったなら、それは残されます。

バージョン 3.3 で変更: __loader__ および __package__ は (可能なら) 自動的に設定されます。

バージョン 3.4 で変更: リロードをサポートするために __name__ __loader__ __package__ は無条件に設定されます。

バージョン 3.4 で非推奨: インポート機構はこの関数が提供する全機能を直接実行するようになりました。

@importlib.util.set_loader

返されたモジュールの __loader__ 属性を設定する、 importlib.abc.Loader.load_module() への decorator です。属性が既に設定されていたら、このデコレータは何もしません。ラップされたメソッド (すなわち self) への1つ目の位置引数は __loader__ に設定される値であると仮定されます。

バージョン 3.4 で変更: もし __loader__ 属性が None に設定されていれば、属性が存在しないかのように __loader__ を設定します。

バージョン 3.4 で非推奨: インポート機構はこれを自動的に考慮するようになりました。

@importlib.util.set_package

__package__ 属性を戻り値のモジュールに設定するための、 importlib.abc.Loader.load_module() への decorator です。もし __package__ が設定されていて None 以外の値を持っているなら、それは変更されません。

バージョン 3.4 で非推奨: インポート機構はこれを自動的に考慮するようになりました。

importlib.util.spec_from_loader(name, loader, *, origin=None, is_package=None)

この関数は、スペックに不足している情報を埋めるために InspectLoader.is_package() のような利用可能な loader API を使います。

バージョン 3.4 で追加.

importlib.util.spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None)

ファイルへのパスにもとづいて ModuleSpec インスタンスを生成するためのファクトリー関数。不足している情報は、ローダー API を利用してスペックから得られる情報と、モジュールがファイルベースであるという暗黙的な情報によって埋められます。

バージョン 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.

バージョン 3.7 で追加.

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.

注釈

起動時間が重要なプロジェクトでは、もし決して使われないモジュールがあれば、このクラスを使ってモジュールをロードするコストを最小化できるかもしれません。スタートアップ時間が重要でないプロジェクトでは、遅延されたロードの際に発生して文脈の外で起こるエラーメッセージのため、このクラスの使用は 著しく 推奨されません。

バージョン 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() を使ってください。

import importlib.util
import sys

# For illustrative purposes.
name = 'itertools'

spec = importlib.util.find_spec(name)
if spec is None:
    print("can't find the itertools module")
else:
    # If you chose to perform the actual import ...
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    # Adding the module to sys.modules is optional.
    sys.modules[name] = module

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

To import a Python source file directly, use the following recipe (Python 3.5 and newer only):

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)
spec.loader.exec_module(module)
# Optional; only necessary if you want to be able to import the module
# by name later.
sys.modules[module_name] = module

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

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() (Python 3.4 and newer for the importlib usage, Python 3.6 and newer for other parts of the code).

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:
        raise ImportError(f'No module named {absolute_name!r}')
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    sys.modules[absolute_name] = module
    if path is not None:
        setattr(parent_module, child_name, module)
    return module

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • モジュールのインポート »


Python言語サービス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

Python言語サービス

PythonにはPython言語を使って作業するときに役に立つモジュールがたくさん提供されています。これらのモジュールはトークンの切り出し、パース、構文解析、バイトコードのディスアセンブリおよびその他のさまざまな機能をサポートしています。

これらのモジュールには、次のものが含まれています:

  • parser --- Python 解析木にアクセスする
    • ST オブジェクトを作成する
    • ST オブジェクトを変換する
    • ST オブジェクトに対する問い合わせ
    • 例外とエラー処理
    • ST オブジェクト
    • 例: compile() のエミュレーション
  • ast --- 抽象構文木
    • Node クラス
    • 抽象文法 (Abstract Grammar)
    • ast ヘルパー
  • symtable --- コンパイラの記号表へのアクセス
    • 記号表の生成
    • 記号表の検査
  • symbol --- Python 解析木と共に使われる定数
  • token --- Python 解析木と共に使われる定数
  • keyword --- Python キーワードチェック
  • tokenize --- Pythonソースのためのトークナイザ
    • 入力のトークナイズ
    • コマンドラインからの使用
    • 使用例
  • tabnanny --- あいまいなインデントの検出
  • pyclbr --- Python クラスブラウザサポート
    • Function オブジェクト
    • クラスオブジェクト
  • py_compile --- Python ソースファイルのコンパイル
  • compileall --- Python ライブラリをバイトコンパイル
    • コマンドラインでの使用
    • パブリックな関数
  • dis --- Python バイトコードの逆アセンブラ
    • バイトコード解析
    • 解析関数
    • Python バイトコード命令
    • 命令コードコレクション
  • pickletools --- pickle 開発者のためのツール群
    • コマンドラインの使い方
      • コマンドラインオプション
    • プログラミングインターフェース

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


ast --- 抽象構文木

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

ast --- 抽象構文木

ソースコード: Lib/ast.py

ast モジュールは、Python アプリケーションで Python の抽象構文木を処理しやすくするものです。抽象構文そのものは、Python のリリースごとに変化する可能性があります。このモジュールを使用すると、現在の文法をプログラム上で知る助けになるでしょう。

抽象構文木を作成するには、 ast.PyCF_ONLY_AST を組み込み関数 compile() のフラグとして渡すか、あるいはこのモジュールで提供されているヘルパー関数 parse() を使います。その結果は、 ast.AST を継承したクラスのオブジェクトのツリーとなります。抽象構文木は組み込み関数 compile() を使って Python コード・オブジェクトにコンパイルすることができます。

Node クラス

class ast.AST

このクラスは全ての AST ノード・クラスの基底です。実際のノード・クラスは 後ほど 示す Parser/Python.asdl ファイルから派生したものです。これらのクラスは _ast C モジュールで定義され、 ast にもエクスポートし直されています。

抽象文法の左辺のシンボル一つずつにそれぞれ一つのクラスがあります (たとえば ast.stmt や ast.expr)。それに加えて、右辺のコンストラクタ一つずつにそれぞれ一つのクラスがあり、これらのクラスは左辺のツリーのクラスを継承しています。たとえば、 ast.BinOp は ast.expr から継承しています。代替を伴った生成規則 (production rules with alternatives) (別名 "sums") の場合、左辺は抽象クラスとなり、特定のコンストラクタ・ノードのインスタンスのみが作成されます。

_fields

各具象クラスは属性 _fields を持っており、すべての子ノードの名前をそこに保持しています。

具象クラスのインスタンスは、各子ノードに対してそれぞれひとつの属性を持っています。この属性は、文法で定義された型となります。たとえば ast.BinOp のインスタンスは left という属性を持っており、その型は ast.expr です。

これらの属性が、文法上 (クエスチョンマークを用いて) オプションであるとマークされている場合は、その値が None となることもあります。属性が0個以上の複数の値をとりうる場合 (アスタリスクでマークされている場合) は、値は Python のリストで表されます。全ての属性は AST を compile() でコンパイルする際には存在しなければならず、そして妥当な値でなければなりません。

lineno
col_offset

ast.expr や ast.stmt のサブクラスのインスタンスにはさらに lineno や col_offset といった属性があります。 lineno はソーステキスト上の行番号 (1 から数え始めるので、最初の行の行番号は 1 となります)、そして col_offset はノードが生成した最初のトークンの UTF-8 バイトオフセットとなります。 UTF-8 オフセットが記録される理由は、パーサが内部で UTF-8 を使用するからです。

クラス ast.T のコンストラクタは引数を次のように解析します:

  • 位置引数があるとすれば、 T._fields にあるのと同じだけの個数が無ければなりません。これらの引数はそこにある名前を持った属性として割り当てられます。
  • キーワード引数があるとすれば、それらはその名前の属性にその値を割り当てられます。

たとえば、 ast.UnaryOp ノードを生成して属性を埋めるには、次のようにすることができます

node = ast.UnaryOp()
node.op = ast.USub()
node.operand = ast.Num()
node.operand.n = 5
node.operand.lineno = 0
node.operand.col_offset = 0
node.lineno = 0
node.col_offset = 0

もしくはよりコンパクトにも書けます

node = ast.UnaryOp(ast.USub(), ast.Num(5, lineno=0, col_offset=0),
                   lineno=0, col_offset=0)

抽象文法 (Abstract Grammar)

抽象文法は、現在次のように定義されています:

-- ASDL's 7 builtin types are:
-- identifier, int, string, bytes, object, singleton, constant
--
-- singleton: None, True or False
-- constant can be None, whereas None means "no value" for object.

module Python
{
    mod = Module(stmt* body)
        | Interactive(stmt* body)
        | Expression(expr body)

        -- not really an actual node but useful in Jython's typesystem.
        | Suite(stmt* body)

    stmt = FunctionDef(identifier name, arguments args,
                       stmt* body, expr* decorator_list, expr? returns)
          | AsyncFunctionDef(identifier name, arguments args,
                             stmt* body, expr* decorator_list, expr? returns)

          | ClassDef(identifier name,
             expr* bases,
             keyword* keywords,
             stmt* body,
             expr* decorator_list)
          | Return(expr? value)

          | Delete(expr* targets)
          | Assign(expr* targets, 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)
          | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse)
          | While(expr test, stmt* body, stmt* orelse)
          | If(expr test, stmt* body, stmt* orelse)
          | With(withitem* items, stmt* body)
          | AsyncWith(withitem* items, stmt* body)

          | Raise(expr? exc, expr? cause)
          | Try(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

          -- XXX Jython will be different
          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset)

          -- BoolOp() can use left & right?
    expr = BoolOp(boolop op, expr* values)
         | 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)
         | Num(object n) -- a number as a PyObject.
         | Str(string s) -- need to specify raw, unicode, etc?
         | FormattedValue(expr value, int? conversion, expr? format_spec)
         | JoinedStr(expr* values)
         | Bytes(bytes s)
         | NameConstant(singleton value)
         | Ellipsis
         | Constant(constant value)

         -- the following expression can appear in assignment context
         | Attribute(expr value, identifier attr, expr_context ctx)
         | Subscript(expr value, slice 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)

          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset)

    expr_context = Load | Store | Del | AugLoad | AugStore | Param

    slice = Slice(expr? lower, expr? upper, expr? step)
          | ExtSlice(slice* dims)
          | Index(expr value)

    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)

    arguments = (arg* args, arg? vararg, arg* kwonlyargs, expr* kw_defaults,
                 arg? kwarg, expr* defaults)

    arg = (identifier arg, expr? annotation)
           attributes (int lineno, int col_offset)

    -- keyword arguments supplied to call (NULL identifier for **kwargs)
    keyword = (identifier? arg, expr value)

    -- import name with optional 'as' alias.
    alias = (identifier name, identifier? asname)

    withitem = (expr context_expr, expr? optional_vars)
}

ast ヘルパー

ノード・クラスの他に、 ast モジュールは以下のような抽象構文木をトラバースするためのユーティリティ関数やクラスも定義しています:

ast.parse(source, filename='<unknown>', mode='exec')

source を解析して AST ノードにします。compile(source, filename, mode, ast.PyCF_ONLY_AST) と等価です。

警告

十分に大きい文字列や複雑な文字列によって Python の抽象構文木コンパイラのスタックの深さの限界を越えることで、 Python インタプリタをクラッシュさせることができます。

ast.literal_eval(node_or_string)

式ノードまたは Python のリテラルまたはコンテナのディスプレイ表現を表す文字列を安全に評価します。与えられる文字列またはノードは次のリテラルのみからなるものに限られます: 文字列、バイト列、数、タプル、リスト、辞書、集合、ブール値、 None 。

この関数は Python の式を含んだ信頼出来ない出どころからの文字列を、値自身を解析することなしに安全に評価するのに使えます。この関数は、例えば演算や添え字を含んだ任意の複雑な表現を評価するのには使えません。

警告

十分に大きい文字列や複雑な文字列によって Python の抽象構文木コンパイラのスタックの深さの限界を越えることで、 Python インタプリタをクラッシュさせることができます。

バージョン 3.2 で変更: バイト列リテラルと集合リテラルが受け取れるようになりました。

ast.get_docstring(node, clean=True)

Return the docstring of the given node (which must be a FunctionDef, AsyncFunctionDef, ClassDef, or Module node), or None if it has no docstring. If clean is true, clean up the docstring's indentation with inspect.cleandoc().

バージョン 3.5 で変更: AsyncFunctionDef is now supported.

ast.fix_missing_locations(node)

compile() はノード・ツリーをコンパイルする際、 lineno と col_offset 両属性をサポートする全てのノードに対しそれが存在するものと想定します。生成されたノードに対しこれらを埋めて回るのはどちらかというと退屈な作業なので、このヘルパーが再帰的に二つの属性がセットされていないものに親ノードと同じ値をセットしていきます。再帰の出発点が node です。

ast.increment_lineno(node, n=1)

node から始まるツリーの全てのノードの行番号を n ずつ増やします。これはファイルの中で別の場所に「コードを動かす」ときに便利です。

ast.copy_location(new_node, old_node)

ソースの場所 (lineno と col_offset) を old_node から new_node に可能ならばコピーし、 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() を呼び出すかそれ自身で子ノードを訪れない限り訪れられないということです。

トラバースの途中でノードを変化させたいならば NodeVisitor を使ってはいけません。そうした目的のために変更を許す特別なビジター (NodeTransformer) があります。

class ast.NodeTransformer

NodeVisitor のサブクラスで抽象構文木を渡り歩きながらノードを変更することを許すものです。

NodeTransformer は抽象構文木(AST)を渡り歩き、ビジター・メソッドの戻り値を使って古いノードを置き換えたり削除したりします。ビジター・メソッドの戻り値が None ならば、ノードはその場から取り去られ、そうでなければ戻り値で置き換えられます。置き換えない場合は戻り値が元のノードそのものであってもかまいません。

それでは例を示しましょう。Name (たとえば foo) を見つけるたび全て data['foo'] に書き換える変換器 (transformer) です:

class RewriteName(NodeTransformer):

    def visit_Name(self, node):
        return copy_location(Subscript(
            value=Name(id='data', ctx=Load()),
            slice=Index(value=Str(s=node.id)),
            ctx=node.ctx
        ), node)

操作しようとしているノードが子ノードを持つならば、その子ノードの変形も自分で行うか、またはそのノードに対し最初に generic_visit() メソッドを呼び出すか、それを行うのはあなたの責任だということを肝に銘じましょう。

文のコレクションであるようなノード (全ての文のノードが当てはまります) に対して、このビジターは単独のノードではなくノードのリストを返すかもしれません。

たいてい、変換器の使い方は次のようになります:

node = YourTransformer().visit(node)
ast.dump(node, annotate_fields=True, include_attributes=False)

node 中のツリーのフォーマットされたダンプを返します。主な使い道はデバッグです。返される文字列は名前とフィールドの値を表示します。これを使うとコードは評価できなくなりますので、評価が必要ならば annotate_fields に False をセットしなければなりません。行番号や列オフセットのような属性はデフォルトではダンプされません。これが欲しければ、include_attributes を True にセットすることができます。

参考

Green Tree Snakes, an external documentation resource, has good details on working with Python ASTs.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


symtable --- コンパイラの記号表へのアクセス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

symtable --- コンパイラの記号表へのアクセス

ソースコード: 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()

記号表の型を返します。有り得る値は 'class', 'module', 'function' です。

get_id()

記号表の識別子を返します。

get_name()

記号表の名前を返します。この名前は記号表がクラスに対するものであればクラス名であり、関数に対するものであれば関数名であり、グローバルな (get_type() が 'module' を返す) 記号表であれば 'top' です。

get_lineno()

この記号表に対応するブロックの一行目の行番号を返します。

is_optimized()

この記号表に含まれるローカル変数が最適化できるならば True を返します。

is_nested()

ブロックが入れ子のクラスまたは関数のとき True を返します。

has_children()

ブロックが入れ子の名前空間を含んでいるならば True を返します。入れ子の名前空間は get_children() で得られます。

has_exec()

ブロックの中で exec が使われているならば True を返します。

get_identifiers()

この記号表にある記号の名前のリストを返します。

lookup(name)

記号表から名前 name を見つけ出して Symbol インスタンスとして返します。

get_symbols()

記号表中の名前を表す Symbol インスタンスのリストを返します。

get_children()

入れ子になった記号表のリストを返します。

class symtable.Function

関数またはメソッドの名前空間。このクラスは SymbolTable を継承しています。

get_parameters()

この関数の引数名からなるタプルを返します。

get_locals()

この関数のローカル変数の名前からなるタプルを返します。

get_globals()

この関数のグローバル変数の名前からなるタプルを返します。

get_frees()

この関数の自由変数の名前からなるタプルを返します。

class symtable.Class

クラスの名前空間。このクラスは SymbolTable を継承しています。

get_methods()

このクラスで宣言されているメソッド名からなるタプルを返します。

class symtable.Symbol

SymbolTable のエントリーでソースの識別子に対応するものです。コンストラクタはパブリックではありません。

get_name()

記号の名前を返します。

is_referenced()

記号がそのブロックの中で使われていれば True を返します。

is_imported()

記号が import 文で作られたものならば True を返します。

is_parameter()

記号がパラメータならば True を返します。

is_global()

記号がグローバルならば True を返します。

is_declared_global()

記号が global 文によってグローバルであると宣言されているなら True を返します。

is_local()

記号がそのブロックに対してローカルならば True を返します。

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 が送出されます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


symbol --- Python 解析木と共に使われる定数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

symbol --- Python 解析木と共に使われる定数

ソースコード: Lib/symbol.py

このモジュールは解析木の内部ノードの数値を表す定数を提供します。ほとんどの Python 定数とは違い、これらは小文字の名前を使います。言語の文法のコンテキストにおける名前の定義については、 Python ディストリビューションのファイル Grammar/Grammar を参照してください。名前がマップする特定の数値は Python のバージョン間で変わります。

このモジュールには、データオブジェクトも一つ付け加えられています:

symbol.sym_name

ディクショナリはこのモジュールで定義されている定数の数値を名前の文字列へマップし、より人が読みやすいように解析木を表現します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


token --- Python 解析木と共に使われる定数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

token --- Python 解析木と共に使われる定数

ソースコード: Lib/token.py

このモジュールは解析木の葉ノード(終端記号)の数値を表す定数を提供します。言語の文法のコンテキストにおける名前の定義については、 Python ディストリビューションのファイル Grammar/Grammar を参照してください。名前がマップする特定の数値は Python のバージョン間で変わります。

このモジュールは、数値コードから名前へのマッピングと、いくつかの関数も提供しています。関数は Python の C ヘッダファイルの定義を反映します。

token.tok_name

ディクショナリはこのモジュールで定義されている定数の数値を名前の文字列へマップし、より人が読みやすいように解析木を表現します。

token.ISTERMINAL(x)

終端トークンの値に対して真を返します。

token.ISNONTERMINAL(x)

非終端トークンの値に対して真を返します。

token.ISEOF(x)

x が入力の終わりを示すマーカーならば、真を返します。

token の定数一覧:

token.ENDMARKER
token.NAME
token.NUMBER
token.STRING
token.NEWLINE
token.INDENT
token.DEDENT
token.LPAR
token.RPAR
token.LSQB
token.RSQB
token.COLON
token.COMMA
token.SEMI
token.PLUS
token.MINUS
token.STAR
token.SLASH
token.VBAR
token.AMPER
token.LESS
token.GREATER
token.EQUAL
token.DOT
token.PERCENT
token.LBRACE
token.RBRACE
token.EQEQUAL
token.NOTEQUAL
token.LESSEQUAL
token.GREATEREQUAL
token.TILDE
token.CIRCUMFLEX
token.LEFTSHIFT
token.RIGHTSHIFT
token.DOUBLESTAR
token.PLUSEQUAL
token.MINEQUAL
token.STAREQUAL
token.SLASHEQUAL
token.PERCENTEQUAL
token.AMPEREQUAL
token.VBAREQUAL
token.CIRCUMFLEXEQUAL
token.LEFTSHIFTEQUAL
token.RIGHTSHIFTEQUAL
token.DOUBLESTAREQUAL
token.DOUBLESLASH
token.DOUBLESLASHEQUAL
token.AT
token.ATEQUAL
token.RARROW
token.ELLIPSIS
token.OP
token.ERRORTOKEN
token.N_TOKENS
token.NT_OFFSET

The following token type values aren't used by the C tokenizer but are needed for the tokenize module.

token.COMMENT

コメントであることを表すために使われるトークン値です。

token.NL

Token value used to indicate a non-terminating newline. The NEWLINE token indicates the end of a logical line of Python code; NL tokens are generated when a logical line of code is continued over multiple physical lines.

token.ENCODING

Token value that indicates the encoding used to decode the source bytes into text. The first token returned by tokenize.tokenize() will always be an ENCODING token.

バージョン 3.5 で変更: Added AWAIT and ASYNC tokens.

バージョン 3.7 で変更: Added COMMENT, NL and ENCODING tokens.

バージョン 3.7 で変更: Removed AWAIT and ASYNC tokens. "async" and "await" are now tokenized as NAME tokens.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


keyword --- Python キーワードチェック

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

keyword --- Python キーワードチェック

ソースコード: Lib/keyword.py

このモジュールでは、Python プログラムで文字列がキーワードか否かをチェックする機能を提供します。

keyword.iskeyword(s)

s が Python のキーワードであれば真を返します。

keyword.kwlist

インタープリタで定義している全てのキーワードのシーケンス。特定の __future__ 宣言がなければ有効ではないキーワードでもこのリストには含まれます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


tokenize --- Pythonソースのためのトークナイザ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

tokenize --- Pythonソースのためのトークナイザ

ソースコード: Lib/tokenize.py

tokenize モジュールでは、Python で実装された Python ソースコードの字句解析器を提供します。さらに、このモジュールの字句解析器はコメントもトークンとして返します。このため、このモジュールはスクリーン上で表示する際の色付け機能 (colorizers) を含む "清書出力器 (pretty-printer)" を実装する上で便利です。

To simplify token stream handling, all operator and delimiter tokens and Ellipsis are returned using the generic OP token type. The exact type can be determined by checking the exact_type property on the named tuple returned from tokenize.tokenize().

入力のトークナイズ

第一のエントリポイントはジェネレータ(generator)です:

tokenize.tokenize(readline)

The tokenize() generator requires one argument, readline, which must be a callable object which provides the same interface as the io.IOBase.readline() method of file objects. Each call to the function should return one line of input as bytes.

このジェネレータは次の5要素のタプルを返します; トークンタイプ; トークン文字列; ソース内でそのトークンがどの行、列で開始するかを示す int の (srow, scol) タプル; どの行、列で終了するかを示す int の (erow, ecol) タプル; トークンが見つかった行。 (タプルの最後の要素にある) 行は 論理 行で、継続行が含まれます。この5要素のタプルは named tuple として返され、フィールド名は type string start end line になります。

The returned named tuple has an additional property named exact_type that contains the exact operator type for OP tokens. For all other token types exact_type equals the named tuple type field.

バージョン 3.1 で変更: named tuple のサポートを追加。

バージョン 3.3 で変更: exact_type のサポートを追加。

tokenize() determines the source encoding of the file by looking for a UTF-8 BOM or encoding cookie, according to PEP 263.

All constants from the token module are also exported from tokenize.

もう一つの関数がトークン化プロセスを逆転するために提供されています。これは、スクリプトを字句解析し、トークンのストリームに変更を加え、変更されたスクリプトを書き戻すようなツールを作成する際に便利です。

tokenize.untokenize(iterable)

トークンの列を Python ソースコードに変換します。 iterable は少なくとも二つの要素、トークンタイプおよびトークン文字列、からなるシーケンスを返さなければいけません。 その他のシーケンスの要素は無視されます。

再構築されたスクリプトは一つの文字列として返されます。得られる結果はもう一度字句解析すると入力と一致することが保証されるので、変換がロスレスでありラウンドトリップできることは間違いありません。この保証はトークン型およびトークン文字列に対してのものでトークン間のスペース (コラム位置)のようなものは変わることがあり得ます。

It returns bytes, encoded using the ENCODING token, which is the first token sequence output by tokenize().

tokenize() needs to detect the encoding of source files it tokenizes. The function it uses to do this is available:

tokenize.detect_encoding(readline)

The detect_encoding() function is used to detect the encoding that should be used to decode a Python source file. It requires one argument, readline, in the same way as the tokenize() generator.

readline を最大2回呼び出し、利用するエンコーディング (文字列として) と、読み込んだ行を (bytes からデコードされないままの状態で) 返します。

It detects the encoding from the presence of a UTF-8 BOM or an encoding cookie as specified in PEP 263. If both a BOM and a cookie are present, but disagree, a SyntaxError will be raised. Note that if the BOM is found, 'utf-8-sig' will be returned as an encoding.

エンコーディングが指定されていない場合、デフォルトの 'utf-8' が返されます。

Use open() to open Python source files: it uses detect_encoding() to detect the file encoding.

tokenize.open(filename)

detect_encoding() を使って検出したエンコーディングを利用して、ファイルを読み出し専用モードで開きます。

バージョン 3.2 で追加.

exception tokenize.TokenError

docstring や複数行にわたることが許される式がファイル内のどこかで終わっていない場合に送出されます。例えば:

"""Beginning of
docstring

もしくは:

[1,
 2,
 3

Note that unclosed single-quoted strings do not cause an error to be raised. They are tokenized as ERRORTOKEN, followed by the tokenization of their contents.

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

バージョン 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      ''

The exact token type names can be displayed using the -e option:

$ 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      ''

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


tabnanny --- あいまいなインデントの検出

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

tabnanny --- あいまいなインデントの検出

ソースコード: 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ソースコードの字句解析器。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


pyclbr --- Python クラスブラウザサポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

pyclbr --- Python クラスブラウザサポート

ソースコード: 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.

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.

バージョン 3.7 で追加: Descriptors for nested definitions. They are accessed through the new children attibute. 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 Function instances describe functions defined by def statements. They have the following attributes:

Function.file

Name of the file in which the function is defined.

Function.module

The name of the module defining the function described.

Function.name

関数の名前です。

Function.lineno

The line number in the file where the definition starts.

Function.parent

For top-level functions, None. For nested functions, the parent.

バージョン 3.7 で追加.

Function.children

A dictionary mapping names to descriptors for nested functions and classes.

バージョン 3.7 で追加.

クラスオブジェクト

Class Class instances describe classes defined by class statements. They have the same attributes as Functions and two more.

Class.file

Name of the file in which the class is defined.

Class.module

The name of the module defining the class described.

Class.name

クラスの名前です。

Class.lineno

The line number in the file where the definition starts.

Class.parent

For top-level classes, None. For nested classes, the parent.

バージョン 3.7 で追加.

Class.children

A dictionary mapping names to descriptors for nested functions and classes.

バージョン 3.7 で追加.

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

Class.methods

A dictionary mapping method names to line numbers. This can be derived from the newer children dictionary, but remains for back-compatibility.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


py_compile --- Python ソースファイルのコンパイル

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

py_compile --- Python ソースファイルのコンパイル

ソースコード: 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)

ソースファイルをバイトコードにコンパイルして、バイトコードのキャッシュファイルに書き出します。ソースコードはファイル名 file で渡します。バイトコードは cfile に書き込まれ、デフォルトでは PEP 3147 や PEP 488 にある .pyc で終わるパスです。例えば、 file が /foo/bar/baz.py だった場合、 cfile は Python 3.2 ではデフォルトで /foo/bar/__pycache__/baz.cpython-32.pyc になります。もし dfile が指定されたら、 file の代わりにソースファイルの名前としてエラーメッセージの中で使われます。 doraise が真の場合、コンパイル中にエラーが発生すると PyCompileError を送出します。 doraise が (デフォルトである) 偽の場合はエラーメッセージは sys.stderr に出力されますが、例外は送出しません。この関数はバイトコンパイルされたファイルへのパス、つまり実際に使われた cfile の値を返します。

(明示的に指定されたか計算された結果の) 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 に準拠し 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. 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.

class py_compile.PycInvalidationMode

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

バージョン 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.

py_compile.main(args=None)

いくつか複数のソースファイルをコンパイルします。 args で (あるいは args が None であればコマンドラインで) 指定されたファイルをコンパイルし、できたバイトコードを通常の方法で保存します。この関数はソースファイルの存在するディレクトリを検索しません; 指定されたファイルをコンパイルするだけです。 args が '-' 1つだけだった場合、ファイルのリストは標準入力から取られます。

バージョン 3.2 で変更: '-' のサポートが追加されました。

このモジュールがスクリプトとして実行されると、 main() がコマンドラインで指定されたファイルを全てコンパイルします。一つでもコンパイルできないファイルがあると終了ステータスが 0 でない値になります。

参考

compileall モジュール
ディレクトリツリー内の Python ソースファイルを全てコンパイルするライブラリ。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


compileall --- Python ライブラリをバイトコンパイル

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

compileall --- Python ライブラリをバイトコンパイル

ソースコード: Lib/compileall.py

このモジュールは、Python ライブラリのインストールを助けるユーティリティ関数群を提供します。この関数群は、ディレクトリツリー内の Python ソースファイルをコンパイルします。このモジュールを使って、キャッシュされたバイトコードファイルをライブラリのインストール時に生成することで、ライブラリディレクトリに書き込み権限をもたないユーザでも、これらを利用できるようになります。

コマンドラインでの使用

このモジュールは、 (python -m compileall を使って) Python ソースをコンパイルするスクリプトとして機能します。

directory ...
file ...

位置引数は、コンパイルするファイル群か、再帰的に横断されるディレクトリでソースファイル群を含むものです。引数が与えられなければ、-l <directories from sys.path> を渡したのと同じように動作します。

-l

サブディレクトリを再帰処理せず、指名または暗示されたディレクトリ群に含まれるソースコードファイル群だけをコンパイルします。

-f

タイムスタンプが最新であってもリビルドを強制します。

-q

コンパイルされたファイルのリストを出力しません。 一つ渡された場合でもエラーメッセージは出力されます。 二つ (-qq) の場合全ての出力は抑制されます。

-d destdir

コンパイルされるそれぞれのファイルへのパスの先頭に、ディレクトリを追加します。これはコンパイル時トレースバックに使われ、バイトコードファイルが実行される時点でソースファイルが存在しない場合に、トレースバックやその他のメッセージに使われるバイトコードファイルにもコンパイルされます。

-x regex

regex を使って、コンパイル候補のそれぞれのファイルのフルパスを検索し、regex がマッチしたファイルを除外します。

-i list

ファイル list を読み込み、そのファイルのそれぞれの行を、コンパイルするファイルとディレクトリのリストに加えます。list が - なら、stdin の行を読み込みます。

-b

バイトコードファイルを、他のバージョンの Python によって生成されたバイトコードファイルを上書きするかもしれない、レガシーな場所に生成します。デフォルトでは PEP 3147 で決められた場所と名前を使い、複数のバージョンの Python が共存できるようにします。

-r

サブディレクトリの最大再起深度を制御します。 このオプションが与えられた場合、-l オプションは無視されます。 python -m compileall <directory> -r 0 は python -m compileall <directory> -l と等価です。

-j N

与えられたディレクトリ内のファイルを N ワーカでコンパイルします。0 の場合 os.cpu_count() の結果が使用されます。

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

Control how the generated byte-code files are invalidated at runtime. The timestamp value, means that .pyc files with the source timestamp and size embedded will be generated. The checked-hash and unchecked-hash values cause hash-based pycs to be generated. Hash-based pycs embed a hash of the source file contents rather than a timestamp. See キャッシュされたバイトコードの無効化 for more information on how Python validates bytecode cache files at runtime. The default is timestamp if the SOURCE_DATE_EPOCH environment variable is not set, and checked-hash if the SOURCE_DATE_EPOCH environment variable is set.

バージョン 3.2 で変更: -i, -b, -h オプションを追加。

バージョン 3.5 で変更: -j, -r, -qq オプションが追加されました。-q オプションが複数のレベルの値に変更されました。-b は常に拡張子 .pyc のバイトエンコーディングファイルを生成し、.pyo を作りません。

バージョン 3.7 で変更: Added the --invalidation-mode parameter.

compile() 関数で利用される最適化レベルを制御するコマンドラインオプションはありません。 Python インタプリタ自体のオプションを使ってください: python -O -m compileall.

パブリックな関数

compileall.compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=py_compile.PycInvalidationMode.TIMESTAMP)

dir という名前のディレクトリーツリーをたどり、途中で見つけた全ての .py をコンパイルします。全ファイルのコンパイルが成功した場合は真を、それ以外の場合は偽を返します。

maxlevels 引数で最大再帰深度を制限します。デフォルトは 10 です。

ddir が与えられた場合、コンパイルされるそれぞれのファイルへのパスの先頭に、そのディレクトリを追加します。これはコンパイル時トレースバックに使われ、バイトコードファイルが実行される時点でソースファイルが存在しない場合に、トレースバックやその他のメッセージに使われるバイトコードファイルにもコンパイルされます。

force が真の場合、タイムスタンプが最新のであってもモジュールは再コンパイルされます。

rx が与えられた場合、コンパイル候補のそれぞれのファイルのフルパスに対して検索メソッドが呼び出され、それが真値を返したら、そのファイルは除外されます。

quiet が False か 0 (デフォルト) の場合、ファイル名とその他の情報は標準出力に表示されます。 1 の場合エラーのみが表示されます。 2 の場合出力はすべて抑制されます。

legacy が真の時、バイトコードファイルは古い場所と名前に書かれ、他のバージョンの Python によって作られたバイトコードファイルを上書きする可能性があります。デフォルトは PEP 3147 で決められた場所と名前を使い、複数のバージョンの Python のバイトコードファイルが共存できるようにします。

optimize でコンパイラの最適化レベルを指定します。これは組み込みの compile() 関数に渡されます。

引数 workers でファイルを並列でコンパイルするワーカの数を指定します。デフォルトでは複数のワーカを使いません。 複数のワーカを使えないプラットフォームで workers が与えられた場合、逐次コンパイルにフォールバックします。workers が 0 未満の場合 ValueError を送出します。

invalidation_mode should be a member of the py_compile.PycInvalidationMode enum and controls how the generated pycs are invalidated at runtime.

バージョン 3.2 で変更: legacy と optimize 引数が追加されました。

バージョン 3.5 で変更: workers パラメータが追加されました。

バージョン 3.5 で変更: quiet 引数が複数のレベルの値に変更されました。

バージョン 3.5 で変更: optimize の値に関わらず、legacy 引数は .pyc ファイルのみを書き出し、.pyo ファイルを書き出さないようになりました。

バージョン 3.6 で変更: path-like object を受け取るようになりました。

バージョン 3.7 で変更: The invalidation_mode parameter was added.

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=py_compile.PycInvalidationMode.TIMESTAMP)

パス fullname のファイルをコンパイルします。コンパイルが成功すれば真を、そうでなければ偽を返します。

ddir が与えられた場合、コンパイルされるファイルのパスの先頭にそのディレクトリを追加します。これはコンパイル時トレースバックに使われ、バイトコードファイルが実行される時点でソースファイルが存在しない場合に、トレースバックやその他のメッセージに使われるバイトコードファイルにもコンパイルされます。

rx が与えられた場合、コンパイル候補のファイルのフルパスに対して検索メソッドが呼び出され、それが真値を返したら、ファイルはコンパイルされず、True が返されます。

quiet が False か 0 (デフォルト) の場合、ファイル名とその他の情報は標準出力に表示されます。 1 の場合エラーのみが表示されます。 2 の場合出力はすべて抑制されます。

legacy が真の時、バイトコードファイルは古い場所と名前に書かれ、他のバージョンの Python によって作られたバイトコードファイルを上書きする可能性があります。デフォルトは PEP 3147 で決められた場所と名前を使い、複数のバージョンの Python のバイトコードファイルが共存できるようにします。

optimize でコンパイラの最適化レベルを指定します。これは組み込みの compile() 関数に渡されます。

invalidation_mode should be a member of the py_compile.PycInvalidationMode enum and controls how the generated pycs are invalidated at runtime.

バージョン 3.2 で追加.

バージョン 3.5 で変更: quiet 引数が複数のレベルの値に変更されました。

バージョン 3.5 で変更: optimize の値に関わらず、legacy 引数は .pyc ファイルのみを書き出し、.pyo ファイルを書き出さないようになりました。

バージョン 3.7 で変更: The invalidation_mode parameter was added.

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=py_compile.PycInvalidationMode.TIMESTAMP)

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 で変更: The invalidation_mode parameter was added.

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
一つのソースファイルをバイトコンパイルします。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


dis --- Python バイトコードの逆アセンブラ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

dis --- Python バイトコードの逆アセンブラ

ソースコード: Lib/dis.py

dis モジュールは CPython バイトコード (bytecode) を逆アセンブルすることでバイトコードの解析をサポートします。 このモジュールが入力として受け取る CPython バイトコードはファイル Include/opcode.h に定義されており、 コンパイラとインタプリタが使用しています。

CPython implementation detail: バイトコードは CPython インタプリタの実装詳細です。Python のバージョン間でバイトコードの追加や、削除、変更がないという保証はありません。このモジュールを使用することによって Python の異なる VM または異なるリリースの間で動作すると考えるべきではありません。

バージョン 3.6 で変更: 従来は使用されるバイト数は命令ごとに異なりましたが、このモジュールでは各々一つの命令につき2バイト使用することとなっています。

例: 以下の関数 myfunc() を考えると

def myfunc(alist):
    return len(alist)

myfunc() の逆アセンブル結果を表示するために次のコマンドを使うことができます:

>>> dis.dis(myfunc)
  2           0 LOAD_GLOBAL              0 (len)
              2 LOAD_FAST                0 (alist)
              4 CALL_FUNCTION            1
              6 RETURN_VALUE

("2" は行番号です)。

バイトコード解析

バージョン 3.4 で追加.

バイトコード解析の API を使うと、 Python のコード片を Bytecode オブジェクトでラップでき、コンパイルされたコードの細かいところに簡単にアクセスできます。

class dis.Bytecode(x, *, first_line=None, current_offset=None)

Analyse the bytecode corresponding to a function, generator, asynchronous generator, coroutine, method, string of source code, or a code object (as returned by compile()).

これは、下で並べられている関数の多くのものをまとめた便利なラッパーです。 とりわけ目立つのは get_instructions() で、 Bytecode インスタンスに対し反復処理をしながら、バイトコード命令を Instruction インスタンスとして返します。

first_line が None でない場合は、それを逆アセンブルしたコードのソースの最初の行に表示する行番号とします。 そうでない場合は、ソースの行の情報 (もしあれば) を逆アセンブルされたコードオブジェクトから直接取得します。

current_offset が None でない場合は、逆アセンブルされたコードでのあるインストラクションのオフセット位置を示します。 これを設定すると、 dis() の出力において、指定された命令コード (opcode) に "現在の命令 (instruction)" を表す印が表示されます。

classmethod from_traceback(tb)

与えられたトレースバックから Bytecode インスタンスを構築し、 current_offset がその例外の原因となった命令となるよう設定します。

codeobj

コンパイルされたコードオブジェクト。

first_line

コードオブジェクトのソースの最初の行 (利用可能であれば)

dis()

バイトコード命令の整形された表示を返します (dis.dis() と同じ出力になりますが、複数行文字列として返されます)。

info()

code_info() のようなコードオブジェクトの詳細を含んだ整形された複数行文字列を返します。

バージョン 3.7 で変更: This can now handle coroutine and asynchronous generator objects.

以下はプログラム例です:

>>> bytecode = dis.Bytecode(myfunc)
>>> for instr in bytecode:
...     print(instr.opname)
...
LOAD_GLOBAL
LOAD_FAST
CALL_FUNCTION
RETURN_VALUE

解析関数

dis モジュールには、以下に挙げる入力を直接欲しい出力に変換する解析関数も定義してあります。 1つの命令だけが実行されている場合は、解析オブジェクトをいったん作るよりはこちらの方が便利です:

dis.code_info(x)

Return a formatted multi-line string with detailed code object information for the supplied function, generator, asynchronous generator, coroutine, method, source code string or code object.

この結果は実装に強く依存しており、Python VM や Python のバージョンによって異なることがあります。

バージョン 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) の便利なショートカットです。

バージョン 3.2 で追加.

バージョン 3.4 で変更: file 引数が追加されました。

dis.dis(x=None, *, file=None, depth=None)

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 (the code of comprehensions, generator expressions and nested functions, and the code used for building nested classes). 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.

バージョン 3.4 で変更: file 引数が追加されました。

バージョン 3.7 で変更: Implemented recursive disassembling and added depth parameter.

バージョン 3.7 で変更: This can now handle coroutine and asynchronous generator objects.

dis.distb(tb=None, *, file=None)

トレースバックのスタックの先頭の関数を逆アセンブルします。Noneが渡された場合は最後のトレースバックを使います。例外を引き起こした命令が表示されます。

file 引数が渡された場合は、アセンブリをそこに書き込みます。 そうでない場合は sys.stdout に出力します。

バージョン 3.4 で変更: file 引数が追加されました。

dis.disassemble(code, lasti=-1, *, file=None)
dis.disco(code, lasti=-1, *, file=None)

コードオブジェクトを逆アセンブルします。lasti が与えられた場合は、最後の命令を示します。出力は次のようなカラムに分割されます:

  1. 各行の最初の命令に対する行番号。
  2. 現在の命令。 --> として示されます。
  3. ラベル付けされた命令。 >> とともに表示されます。
  4. 命令のアドレス。
  5. 命令コード名。
  6. 命令パラメタ。
  7. パラメタの解釈を括弧で囲んだもの。

パラメタの解釈は、ローカル変数とグローバル変数の名前、定数の値、 分岐先、比較命令を認識します。

file 引数が渡された場合は、アセンブリをそこに書き込みます。 そうでない場合は sys.stdout に出力します。

バージョン 3.4 で変更: file 引数が追加されました。

dis.get_instructions(x, *, first_line=None)

渡された関数、メソッド、ソースコード文字列、コードオブジェクトにある命令のイテレータを返します。

イテレータは、与えられたコードの各命令の詳細情報を保持する名前付きタプル Instruction からなる列を生成します。

first_line が None でない場合は、それを逆アセンブルしたコードのソースの最初の行に表示する行番号とします。 そうでない場合は、ソースの行の情報 (もしあれば) を逆アセンブルされたコードオブジェクトから直接取得します。

バージョン 3.4 で追加.

dis.findlinestarts(code)

This generator function uses the co_firstlineno and co_lnotab attributes 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. See Objects/lnotab_notes.txt for the co_lnotab format and how to decode it.

バージョン 3.6 で変更: Line numbers can be decreasing. Before, they were always increasing.

dis.findlabels(code)

ジャンプ先であるコードオブジェクト code のすべてのオフセットを 求め、これらのオフセットのリストを返します。

dis.stack_effect(opcode[, oparg])

opcode と引数 oparg がスタックに与える影響を計算します。

バージョン 3.4 で追加.

Python バイトコード命令

get_instructions() 関数と Bytecode クラスはバイトコード命令の詳細を Instruction インスタンスの形で提供します:

class dis.Instruction

バイトコード命令の詳細

opcode

以下の命令コードの値と 命令コードコレクション のバイトコードの値に対応する、命令の数値コードです。

opname

人間が読むための命令名

arg

(ある場合は) 命令の数値引数、無ければ None

argval

(もし分かっていれば) 解決された引数の値、そうでない場合は arg と同じもの

argrepr

人間が読むための命令引数の説明

offset

バイトコード列の中での命令の開始位置

starts_line

(ある場合は) この命令コードが始まる行、無ければ None

is_jump_target

他のコードからここへジャンプする場合は True 、そうでない場合は False

バージョン 3.4 で追加.

現在 Python コンパイラは次のバイトコード命令を生成します。

一般的な命令

NOP

なにもしないコード。バイトコードオプティマイザでプレースホルダとして使われます。

POP_TOP

スタックの先頭 (TOS) の要素を取り除きます。

ROT_TWO

スタックの先頭の 2 つの要素を入れ替えます。

ROT_THREE

スタックの二番目と三番目の要素の位置を 1 つ上げ、先頭を三番目へ下げます。

DUP_TOP

スタックの先頭にある参照の複製を作ります。

バージョン 3.2 で追加.

DUP_TOP_TWO

スタックの先頭の2つの参照を、そのままの順番で複製します。

バージョン 3.2 で追加.

1オペランド命令

1オペランド命令はスタックの先頭を取り出して操作を適用し、結果をスタックへプッシュし戻します。

UNARY_POSITIVE

TOS = +TOS を実行します。

UNARY_NEGATIVE

TOS = -TOS を実行します。

UNARY_NOT

TOS = not TOS を実行します。

UNARY_INVERT

TOS = ~TOS を実行します。

GET_ITER

TOS = iter(TOS) を実行します。

GET_YIELD_FROM_ITER

TOS が generator iterator もしくは coroutine オブジェクトの場合は、そのままにしておきます。 そうでない場合は TOS = iter(TOS) を実行します。

バージョン 3.5 で追加.

2オペランド命令

二項命令はスタックの先頭 (TOS) と先頭から二番目の要素をスタックから取り除きます。 命令を実行し、スタックへ結果をプッシュし戻します。

BINARY_POWER

TOS = TOS1 ** TOS を実行します。

BINARY_MULTIPLY

TOS = TOS1 * TOS を実行します。

BINARY_MATRIX_MULTIPLY

TOS = TOS1 @ TOS を実行します。

バージョン 3.5 で追加.

BINARY_FLOOR_DIVIDE

TOS = TOS1 // TOS を実行します。

BINARY_TRUE_DIVIDE

TOS = TOS1 / TOS を実行します。

BINARY_MODULO

TOS = TOS1 % TOS を実行します。

BINARY_ADD

TOS = TOS1 + TOS を実行します。

BINARY_SUBTRACT

TOS = TOS1 - TOS を実行します。

BINARY_SUBSCR

TOS = TOS1[TOS] を実行します。

BINARY_LSHIFT

TOS = TOS1 << TOS を実行します。

BINARY_RSHIFT

TOS = TOS1 >> TOS を実行します。

BINARY_AND

TOS = TOS1 & TOS を実行します。

BINARY_XOR

TOS = TOS1 ^ TOS を実行します。

BINARY_OR

TOS = TOS1 | TOS を実行します。

インプレース (in-place) 命令

インプレース命令は TOS と TOS1 を取り除いて結果をスタックへプッシュするという点で二項命令と似ています。 しかし、TOS1 がインプレース命令をサポートしている場合には操作が直接 TOS1 に行われます。 また、操作結果の TOS は (常に同じというわけではありませんが) 元の TOS1 と同じオブジェクトになることが多いです。

INPLACE_POWER

インプレースの TOS = TOS1 ** TOS を実行します。

INPLACE_MULTIPLY

インプレースの TOS = TOS1 * TOS を実行します。

INPLACE_MATRIX_MULTIPLY

インプレースの TOS = TOS1 @ TOS を実行します。

バージョン 3.5 で追加.

INPLACE_FLOOR_DIVIDE

インプレースの TOS = TOS1 // TOS を実行します。

INPLACE_TRUE_DIVIDE

インプレースの TOS = TOS1 / TOS を実行します。

INPLACE_MODULO

インプレースの TOS = TOS1 % TOS を実行します。

INPLACE_ADD

インプレースの TOS = TOS1 + TOS を実行します。

INPLACE_SUBTRACT

インプレースの TOS = TOS1 - TOS を実行します。

INPLACE_LSHIFT

インプレースの TOS = TOS1 << TOS を実行します。

INPLACE_RSHIFT

インプレースの TOS = TOS1 >> TOS を実行します。

INPLACE_AND

インプレースの TOS = TOS1 & TOS を実行します。

INPLACE_XOR

インプレースの TOS = TOS1 ^ TOS を実行します。

INPLACE_OR

インプレースの TOS = TOS1 | TOS を実行します。

STORE_SUBSCR

TOS1[TOS] = TOS2 を実行します。

DELETE_SUBSCR

del TOS1[TOS] を実行します。

コルーチン命令コード

GET_AWAITABLE

TOS = get_awaitable(TOS) を実行します。 get_awaitable(o) は、 o がコルーチンオブジェクトもしくは CO_ITERABLE_COROUTINE フラグの付いたジェネレータオブジェクトの場合に o を返し、そうでない場合は o.__await__ を解決します。

バージョン 3.5 で追加.

GET_AITER

Implements TOS = TOS.__aiter__().

バージョン 3.5 で追加.

バージョン 3.7 で変更: Returning awaitable objects from __aiter__ is no longer supported.

GET_ANEXT

PUSH(get_awaitable(TOS.__anext__())) を実行します。 get_awaitable の詳細については GET_AWAITABLE を参照してください。

バージョン 3.5 で追加.

BEFORE_ASYNC_WITH

スタックの先頭にあるオブジェクトの __aenter__ と __aexit__ を解決します。 __aexit__ と __aenter__() の結果をスタックに積みます。

バージョン 3.5 で追加.

SETUP_ASYNC_WITH

新たなフレームオブジェクトを作成します。

バージョン 3.5 で追加.

その他の命令コード

PRINT_EXPR

対話モードのための式文を実行します。TOS はスタックから取り除かれ表示されます。 非対話モードにおいては、式文は POP_TOP で終了しています。

BREAK_LOOP

break 文によってループを終了します。

CONTINUE_LOOP(target)

continue 文によってループを継続します。 target はジャンプするアドレスです (アドレスは FOR_ITER 命令でなければなりません)。

SET_ADD(i)

set.add(TOS1[-i], TOS) を呼び出します。集合内包表記の実装に使われます。

LIST_APPEND(i)

list.append(TOS1[-i], TOS) を呼び出します。リスト内包表記の実装に使われます。

MAP_ADD(i)

dict.setitem(TOS1[-i], TOS, TOS1) を呼び出します。辞書内包表記の実装に使われます。

バージョン 3.1 で追加.

SET_ADD, LIST_APPEND, MAP_ADD は、追加した値または key/value ペアをスタックから取り除きますが、コンテナオブジェクトはループの次のイテレーションで利用できるようにスタックに残しておきます。

RETURN_VALUE

関数の呼び出し元へ TOS を返します。

YIELD_VALUE

TOS をポップし、それをジェネレータ (generator) から yield します。

YIELD_FROM

TOS をポップし、それを generator から取得したサブイテレーターとして delegate します。

バージョン 3.3 で追加.

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.

バージョン 3.6 で追加.

IMPORT_STAR

'_' で始まっていないすべてのシンボルをモジュール TOS から直接ローカル名前空間へロードします。 モジュールはすべての名前をロードした後にポップされます。 この命令コードは from module import * を実行します。

POP_BLOCK

ブロックスタックからブロックを一つ取り除きます。 フレームごとにブロックのスタックがあり、ネストしたループや try 文などを表しています。

POP_EXCEPT

ブロックスタックからブロックを1つ取り除きます。 ポップされたブロックは、例外ハンドラに入ったときに暗黙的に生成された例外ハンドラのブロックでなければなりません。 フレームスタックから本質的でない値をポップするのに加えて、直前にポップした3つの値が例外状態を回復するのに使われます。

END_FINALLY

finally 節を終了します。 インタプリタは例外を再送出しなければならないかどうか、あるいは、 関数から return して外側の次のブロックに続くかどうかを再度判断します。

LOAD_BUILD_CLASS

builtins.__build_class__() をスタックにプッシュします。 これはクラスを構築するために、後で CALL_FUNCTION に呼ばれます。

SETUP_WITH(delta)

この命令コードは、with ブロックが開始する前にいくつかの命令を行います。 まず、コンテキストマネージャから __exit__() をロードし、 後から WITH_CLEANUP で使うためにスタックにプッシュします。 そして、 __enter__() が呼び出され、 delta を指す finally ブロックがプッシュされます。最後に、enter メソッドを呼び出した 結果がスタックにプッシュされます。次の命令コードはこれを無視 (POP_TOP) するか、変数に保存 (STORE_FAST, STORE_NAME, または UNPACK_SEQUENCE) します。

バージョン 3.2 で追加.

WITH_CLEANUP_START

with 式ブロックを抜けるときに、スタックをクリーンアップします。 TOS はコンテキストマネージャの __exit__() メソッドです。 TOS の下は 1--3 個の値で、それらはなぜ/どのように finally 節に 到達したかを表しています:

  • SECOND = None
  • (SECOND, THIRD) = (WHY_{RETURN,CONTINUE}), retval
  • SECOND = WHY_*; no retval below it
  • (SECOND, THIRD, FOURTH) = exc_info()

最後のケースでは TOS(SECOND, THIRD, FOURTH) が呼び出され、それ以外では TOS(None, None, None) が呼び出されます。 SECOND と先程の呼び出し結果がスタックにプッシュされます。

WITH_CLEANUP_FINISH

例外の型と 'exit' 関数を呼び出した結果をスタックからポップします。

スタックが例外処理中の状態を示し、 かつ 関数呼び出しが 'true' 値を返した場合、 END_FINALLY が例外を再送出するのを防ぐため、この情報を無かったことにして単一の WHY_SILENCED で置き換えます。 (ただし、 non-local goto は再開されます。)

All of the following opcodes use their arguments.

STORE_NAME(namei)

name = TOS を実行します。 namei はコードオブジェクトの属性 co_names における name のインデックスです。 コンパイラは可能ならば STORE_FAST または STORE_GLOBAL を使おうとします。

DELETE_NAME(namei)

del name を実行します。 namei はコードオブジェクトの co_names 属性へのインデックスです。

UNPACK_SEQUENCE(count)

TOS を count 個の個別の値にアンパックして、右から左の順にスタックに積みます。

UNPACK_EX(counts)

星付きの対象ありの代入を実行します: TOS にあるイテラブルを個別の値にばらしますが、ばらした値の総数はイテラブルの要素数より小さくなることがあります: そのときは、値の1つはばらされずに残った要素からなるリストです。

counts の下位バイトはそのリスト値より前にある値の個数で、 counts の上位バイトはそれより後ろにある値の個数です。 そうしてできた値は右から左の順でスタックに積まれます。

STORE_ATTR(namei)

TOS.name = TOS1 を実行します。 namei は co_names における名前のインデックスです。

DELETE_ATTR(namei)

del TOS.name を実行します。 co_names へのインデックスとして namei を使います。

STORE_GLOBAL(namei)

STORE_NAME と同じように動作しますが、 name をグローバルとして保存します。

DELETE_GLOBAL(namei)

DELETE_NAME と同じように動作しますが、グローバルの name を削除します。

LOAD_CONST(consti)

co_consts[consti] をスタックにプッシュします。

LOAD_NAME(namei)

co_names[namei] に関連付けられた値をスタックにプッシュします。

BUILD_TUPLE(count)

スタックから count 個の要素を消費してタプルを作り出し、できたタプルをスタックにプッシュします。

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: {..., TOS3: TOS2, TOS1: TOS}.

バージョン 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. count values are consumed from the stack. The top element on the stack contains a tuple of keys.

バージョン 3.6 で追加.

BUILD_STRING(count)

Concatenates count strings from the stack and pushes the resulting string onto the stack.

バージョン 3.6 で追加.

BUILD_TUPLE_UNPACK(count)

Pops count iterables from the stack, joins them in a single tuple, and pushes the result. Implements iterable unpacking in tuple displays (*x, *y, *z).

バージョン 3.5 で追加.

BUILD_TUPLE_UNPACK_WITH_CALL(count)

This is similar to BUILD_TUPLE_UNPACK, but is used for f(*x, *y, *z) call syntax. The stack item at position count + 1 should be the corresponding callable f.

バージョン 3.6 で追加.

BUILD_LIST_UNPACK(count)

This is similar to BUILD_TUPLE_UNPACK, but pushes a list instead of tuple. Implements iterable unpacking in list displays [*x, *y, *z].

バージョン 3.5 で追加.

BUILD_SET_UNPACK(count)

This is similar to BUILD_TUPLE_UNPACK, but pushes a set instead of tuple. Implements iterable unpacking in set displays {*x, *y, *z}.

バージョン 3.5 で追加.

BUILD_MAP_UNPACK(count)

Pops count mappings from the stack, merges them into a single dictionary, and pushes the result. Implements dictionary unpacking in dictionary displays {**x, **y, **z}.

バージョン 3.5 で追加.

BUILD_MAP_UNPACK_WITH_CALL(count)

This is similar to BUILD_MAP_UNPACK, but is used for f(**x, **y, **z) call syntax. The stack item at position count + 2 should be the corresponding callable f.

バージョン 3.5 で追加.

バージョン 3.6 で変更: The position of the callable is determined by adding 2 to the opcode argument instead of encoding it in the second byte of the argument.

LOAD_ATTR(namei)

TOS を getattr(TOS, co_names[namei]) と入れ替えます。

COMPARE_OP(opname)

ブール命令を実行します。命令名は cmp_op[opname] にあります。

IMPORT_NAME(namei)

モジュール co_names[namei] をインポートします。 TOS と TOS1 がポップされ、 __import__() の fromlist と level 引数になります。モジュールオブジェクトはスタックへプッシュされます。現在の名前空間は影響されません: 適切な import 文のためには、後続の STORE_FAST 命令が名前空間を変更します。

IMPORT_FROM(namei)

TOS にあるモジュールから属性 co_names[namei] をロードします。作成されたオブジェクトはスタックにプッシュされ、後続の STORE_FAST 命令によって保存されます。

JUMP_FORWARD(delta)

バイトコードカウンタを delta だけ増加させます。

POP_JUMP_IF_TRUE(target)

TOS が真ならば、バイトコードカウンタを target に設定します。 TOS はポップされます。

バージョン 3.1 で追加.

POP_JUMP_IF_FALSE(target)

TOS が偽ならば、バイトコードカウンタを target に設定します。 TOS はポップされます。

バージョン 3.1 で追加.

JUMP_IF_TRUE_OR_POP(target)

TOS が真ならば、バイトコードカウンタを target に設定し、TOS は スタックに残されます。そうでない (TOS が偽) なら、TOS はポップされます。

バージョン 3.1 で追加.

JUMP_IF_FALSE_OR_POP(target)

TOS が偽ならば、バイトコードカウンタを target に設定し、TOS は スタックに残されます。そうでない (TOS が真) なら、TOS はポップされます。

バージョン 3.1 で追加.

JUMP_ABSOLUTE(target)

バイトコードカウンタを target に設定します。

FOR_ITER(delta)

TOS はイテレータです。 その __next__() メソッドを呼び出します。 新しい値が yield された場合は、それをスタックにプッシュします (イテレータはその下に残されます)。 イテレータの呼び出しで要素が尽きたことが示された場合は、 TOS がポップされ、バイトコードカウンタが delta だけ増やされます。

LOAD_GLOBAL(namei)

co_names[namei] という名前のグローバルをスタック上にロードします。

SETUP_LOOP(delta)

ループのためのブロックをブロックスタックにプッシュします。 ブロックは現在の命令から delta バイトの大きさを占めます。

SETUP_EXCEPT(delta)

try-except 節から try ブロックをブロックスタックにプッシュします。 delta は最初の except ブロックを指します。

SETUP_FINALLY(delta)

try-except 節から try ブロックをブロックスタックにプッシュします。 delta は finally ブロックを指します。

LOAD_FAST(var_num)

ローカルな co_varnames[var_num] への参照をスタックにプッシュします。

STORE_FAST(var_num)

TOS をローカルな co_varnames[var_num] の中に保存します。

DELETE_FAST(var_num)

ローカルな co_varnames[var_num] を削除します。

LOAD_CLOSURE(i)

セルと自由変数の記憶領域のスロット i に含まれるセルへの参照をプッシュします。 i が co_cellvars の長さより小さければ、変数の名前は co_cellvars[i] です。 そうでなければ co_freevars[i - len(co_cellvars)] です。

LOAD_DEREF(i)

セルと自由変数の記憶領域のスロット i に含まれるセルをロードします。 セルが持つオブジェクトへの参照をスタックにプッシュします。

LOAD_CLASSDEREF(i)

LOAD_DEREF とほぼ同じですが、セルを調べる前にまずローカルの辞書を確認します。 これはクラス本体に自由変数を読み込むために使います。

バージョン 3.4 で追加.

STORE_DEREF(i)

セルと自由変数の記憶領域のスロット i に含まれるセルへTOSを保存します。

DELETE_DEREF(i)

セルと自由変数の記憶領域のスロット i にあるセルを空にします。 del 文で使われます。

バージョン 3.2 で追加.

RAISE_VARARGS(argc)

Raises an exception. argc indicates the number of arguments to the raise statement, ranging from 0 to 3. The handler will find the traceback as TOS2, the parameter as TOS1, and the exception as TOS.

CALL_FUNCTION(argc)

Calls a callable object with positional arguments. argc indicates the number of positional arguments. The top of the stack contains positional arguments, with the right-most argument on top. Below the arguments is a callable object to call. CALL_FUNCTION pops all arguments and the callable object off the stack, calls the callable object with those arguments, and pushes the return value returned by the callable object.

バージョン 3.6 で変更: This opcode is used only for calls with positional arguments.

CALL_FUNCTION_KW(argc)

Calls a callable object with positional (if any) and keyword arguments. argc indicates the total number of positional and keyword arguments. The top element on the stack contains a tuple of keyword argument names. Below that are keyword arguments in the order corresponding to the tuple. Below that are positional arguments, with the right-most parameter on top. Below the arguments is a callable object to call. CALL_FUNCTION_KW pops all arguments and the callable object off the stack, calls the callable object with those arguments, and pushes the return value returned by the callable object.

バージョン 3.6 で変更: Keyword arguments are packed in a tuple instead of a dictionary, argc indicates the total number of arguments.

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. Below that is an iterable object containing positional arguments and a callable object to call. BUILD_MAP_UNPACK_WITH_CALL and BUILD_TUPLE_UNPACK_WITH_CALL can be used for merging multiple mapping objects and iterables containing 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.

バージョン 3.6 で追加.

LOAD_METHOD(namei)

Loads a method named co_names[namei] from TOS object. TOS is popped and method and TOS are pushed when interpreter can call unbound method directly. TOS will be used as the first argument (self) by CALL_METHOD. Otherwise, NULL and method is pushed (method is bound method or something else).

バージョン 3.7 で追加.

CALL_METHOD(argc)

Calls a method. argc is number of positional arguments. Keyword arguments are not supported. This opcode is designed to be used with LOAD_METHOD. Positional arguments are on top of the stack. Below them, two items described in LOAD_METHOD on the stack. All of them are popped and return value is pushed.

バージョン 3.7 で追加.

MAKE_FUNCTION(argc)

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 an annotation dictionary
  • 0x08 a tuple containing cells for free variables, making a closure
  • 関数に関連付けられたコード (TOS1の位置)
  • 関数の qualified name (TOSの位置)
BUILD_SLICE(argc)

スライスオブジェクトをスタックにプッシュします。 argc は2あるいは3でなければなりません。 2 ならば slice(TOS1, TOS) がプッシュされます。 3 ならば slice(TOS2, TOS1, TOS) がプッシュされます。 これ以上の情報については、 slice() 組み込み関数を参照してください。

EXTENDED_ARG(ext)

デフォルトの 2 バイトに収まりきらない大きな引数を持つあらゆる命令コードの前に置かれます。 ext は追加の 2 バイトを保持し、後続の命令コードの引数と組み合わされます。 それらは 4 バイト引数を構成し、 ext はその最上位バイトです。

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.

バージョン 3.6 で追加.

HAVE_ARGUMENT

This is not really an opcode. It identifies the dividing line between opcodes which don't use their argument and those that do (< HAVE_ARGUMENT and >= HAVE_ARGUMENT, respectively).

バージョン 3.6 で変更: Now every instruction has an argument, but opcodes < HAVE_ARGUMENT ignore it. Before, only opcodes >= HAVE_ARGUMENT had an argument.

命令コードコレクション

これらのコレクションは、自動でバイトコード命令を解析するために提供されています:

dis.opname

命令コード名のリスト。 バイトコードをインデックスに使って参照できます。

dis.opmap

命令コード名をバイトコードに対応づける辞書。

dis.cmp_op

すべての比較命令の名前のリスト。

dis.hasconst

Sequence of bytecodes that access a constant.

dis.hasfree

自由変数にアクセスするバイトコードのリスト (この文脈での '自由' とは、現在のスコープにある名前で内側のスコープから参照されているもの、もしくは外側のスコープにある名前で現在のスコープから参照しているものを指します。グローバルスコープや組み込みのスコープへの参照は含み ません)。

dis.hasname

名前によって属性にアクセスするバイトコードのリスト。

dis.hasjrel

相対ジャンプ先を持つバイトコードのリスト。

dis.hasjabs

絶対ジャンプ先を持つバイトコードのリスト。

dis.haslocal

ローカル変数にアクセスするバイトコードのリスト。

dis.hascompare

ブール命令のバイトコードのリスト。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


pickletools --- pickle 開発者のためのツール群

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Python言語サービス »

pickletools --- pickle 開発者のためのツール群

ソースコード: Lib/pickletools.py

このモジュールには、 pickle モジュールの詳細に関わる様々な定数や実装に関する長大なコメント、そして pickle 化されたデータを解析する上で有用な関数をいくつか定義しています。このモジュールの内容は pickle の実装に関わっている Python コア開発者にとって有用なものです; 普通の pickle 利用者にとっては、 pickletools モジュールはおそらく関係ないものでしょう。

コマンドラインの使い方

バージョン 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 で追加: annotate 引数。

pickletools.genops(pickle)

pickle 内の全ての opcode を取り出すイテレータ(iterator)を返します。このイテレータは (opcode, arg, pos) の三つ組みからなる配列を返します。 opcode は OpcodeInfo クラスのインスタンスのクラスです。 arg は opcode の引数としてデコードされた Python オブジェクトの値です。 pos は opcode の場所を表す値です。 pickle は文字列でもファイル類似オブジェクトでもかまいません。

pickletools.optimize(picklestring)

使われていない PUT 命令コードを除去した上で、その新しい pickle 文字列を返します。最適化された pickle は、長さがより短く、転送時間がより少なく、必要とするストレージ領域がより狭く、unpickle 化がより効率的になります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python言語サービス »


各種サービス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

各種サービス

この章では、Pythonのすべてのバージョンで利用可能な各種サービスについて説明します。以下に概要を示します:

  • formatter --- 汎用の出力書式化機構
    • formatter インタフェース
    • formatter 実装
    • writer インタフェース
    • writer 実装

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


MS Windows 固有のサービス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

MS Windows 固有のサービス

この章では、MS Windows プラットフォーム上でのみ利用可能なモジュール群について記述します。

  • msilib --- Microsoft インストーラーファイルの読み書き
    • データベースオブジェクト
    • ビューオブジェクト
    • サマリー情報オブジェクト
    • レコードオブジェクト
    • エラー
    • CAB オブジェクト
    • ディレクトリオブジェクト
    • フィーチャー
    • GUI クラス
    • 事前に計算されたテーブル
  • msvcrt --- MS VC++実行時システムの有用なルーチン群
    • ファイル操作関連
    • コンソール I/O 関連
    • その多の関数
  • winreg --- Windows レジストリへのアクセス
    • 関数
    • 定数
      • HKEY_* 定数
      • アクセス権限
        • 64-bit 特有のアクセス権
      • 値の型
    • レジストリハンドルオブジェクト
  • winsound --- Windows 用の音声再生インタフェース

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • MS Windows 固有のサービス »

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

ソースコード: Lib/msilib/__init__.py

msilib モジュールは Microsoft インストーラー(.msi)の作成を支援します。このファイルは大抵の場合埋め込まれた「キャビネット」ファイル (.cab) を含むので、CAB ファイル作成用の API も公開されています。.cab ファイルの読み出しは現時点では実装されていませんが、 .msi データベースの読み出しは可能です。

このパッケージの目的は .msi ファイルにある全てのテーブルへの完全なアクセスの提供であり、提供されているものは非常に低レベルな API です。このパッケージの二つの主要な使用目的は distutils の bdist_msi コマンドと、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 UuidCreate UuidToString

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

Database.OpenView(sql)

MSIDatabaseOpenView() を呼び出して取得したビューオブジェクトを返します。 sql は実行される SQL ステートメントです。

Database.Commit()

MSIDatabaseCommit() を呼び出して現在のトランザクションで保留されている変更をコミットします。

Database.GetSummaryInformation(count)

MsiGetSummaryInformation() を呼び出して新しいサマリー情報オブジェクトを返します。 count は更新された値の最大数です。

Database.Close()

Close the database object, through MsiCloseHandle().

バージョン 3.7 で追加.

参考

MSIDatabaseOpenView MSIDatabaseCommit MSIGetSummaryInformation MsiCloseHandle

ビューオブジェクト

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 MSIViewGetColumnInfo MsiViewFetch MsiViewModify MsiViewClose

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

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 MsiSummaryInfoGetPropertyCount MsiSummaryInfoSetProperty MsiSummaryInfoPersist

レコードオブジェクト

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 MsiRecordSetString MsiRecordSetStream MsiRecordSetInteger MsiRecordClearData

エラー

All wrappers around MSI functions raise MSIError; the string inside the exception will contain more detail.

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()

Remove .pyc files on uninstall.

参考

Directory Table File Table Component Table FeatureComponents Table

フィーチャー

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

GUI クラス

msilib はMSIデータベースにあるGUIテーブルをラップしたいくつかのクラスを提供します。しかし、標準的なユーザーインタフェースは提供されません。ユーザーインタフェースを備えたPythonパッケージをインストールするMSIを作成するには bdist_msi を使用してください。

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 Control Table Control Types ControlCondition Table ControlEvent Table EventMapping Table RadioButton Table

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

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 テーブルの定義を含んでいます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • MS Windows 固有のサービス »


msvcrt --- MS VC++実行時システムの有用なルーチン群

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • MS Windows 固有のサービス »

msvcrt --- MS VC++実行時システムの有用なルーチン群

このモジュールの関数は、 Windows プラットフォームの便利な機能のいくつかに対するアクセス機構を提供しています。高レベルモジュールのいくつかは、提供するサービスを Windows で実装するために、これらの関数を使っています。例えば、 getpass モジュールは関数 getpass() を実装するためにこのモジュールの関数を使います。

ここに挙げた関数の詳細なドキュメントについては、プラットフォーム API ドキュメントで見つけることができます。

このモジュールは、通常版とワイド文字列版の両方のコンソールI/O APIを実装しています。通常版の API は ASCII 文字列のためのもので、国際化アプリケーションでは利用が制限されます。可能な限りワイド文字列版APIを利用するべきです。

バージョン 3.3 で変更: このモジュールの操作で以前は IOError が送出されていたところで OSError が送出されるようになりました。

ファイル操作関連

msvcrt.locking(fd, mode, nbytes)

C 言語による実行時システムにおけるファイル記述子 fd に基づいて、ファイルの一部にロックをかけます。失敗すると OSError が送出されます。ロックされるファイルの領域は、現在のファイル位置から nbytes バイトで、ファイルの末端まで延長することができます。 mode は以下に列挙する LK_* のいずれか一つでなければなりません。一つのファイルの複数の領域を同時にロックすることは可能ですが、領域が重複してはなりません。連接する領域をまとめて指定することはできません; それらの領域は個別にロック解除しなければなりません。

msvcrt.LK_LOCK
msvcrt.LK_RLCK

指定されたバイト列にロックをかけます。指定領域がロックできなかった場合、プログラムは 1 秒後に再度ロックを試みます。10 回再試行した後でもロックをかけられない場合、 OSError が送出されます。

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)

C 言語による実行時システムにおけるファイル記述子をファイルハンドル handle から生成します。 flags パラメタは os.O_APPEND 、 os.O_RDONLY 、および os.O_TEXT をビット単位で OR したものになります。返されるファイル記述子は os.fdopen() でファイルオブジェクトを生成するために使うことができます。

msvcrt.get_osfhandle(fd)

ファイル記述子 fd のファイルハンドルを返します。 fd が認識できない場合、 OSError を送出します。

コンソール I/O 関連

msvcrt.kbhit()

読み出し待ちの打鍵イベントが存在する場合に真を返します。

msvcrt.getch()

打鍵を読み取り、読み出された文字を返します。コンソールには何もエコーバックされません。この関数呼び出しは読み出し可能な打鍵がない場合にはブロックしますが、文字を読み出せるようにするために Enter の打鍵を待つ必要はありません。打鍵されたキーが特殊機能キー (function key) である場合、この関数は '\000' または '\xe0' を返します; キーコードは次に関数を呼び出した際に返されます。この関数で Control-C の打鍵を読み出すことはできません。

msvcrt.getwch()

getch() のワイド文字列版。Unicode の値を返します。

msvcrt.getche()

getch() に似ていますが、打鍵した字が印字可能な文字の場合エコーバックされます。

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()

強制的に malloc() ヒープをクリーンさせ、未使用のブロックをオペレーティングシステムに返させます。失敗した場合、 OSError を送出します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • MS Windows 固有のサービス »


winsound --- Windows 用の音声再生インタフェース

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • MS Windows 固有のサービス »

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

The sound parameter to PlaySound() is a memory image of a WAV file, as a bytes-like object.

注釈

このモジュールはメモリ上のイメージを非同期に再生する機能をサポートしていません。従って、このフラグと 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 を再生します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • MS Windows 固有のサービス »


Unix 固有のサービス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

Unix 固有のサービス

本章に記述されたモジュールは、Unix オペレーティングシステム、あるいはそれから派生した多くのものに固有の機能のためのインタフェースを提供します。その概要を以下に述べます:

  • posix --- 最も一般的な POSIX システムコール群
    • ラージファイルのサポート
    • 注目すべきモジュールの内容
  • pwd --- パスワードデータベースへのアクセスを提供する
  • spwd --- シャドウパスワードデータベース
  • grp --- グループデータベースへのアクセス
  • crypt --- Unix パスワードをチェックするための関数
    • ハッシュ化方式
    • モジュール属性
    • モジュール関数
    • 使用例
  • termios --- POSIX スタイルの端末制御
    • 使用例
  • tty --- 端末制御のための関数群
  • pty --- 擬似端末ユーティリティ
    • 使用例
  • fcntl --- fcntl および ioctl システムコール
  • pipes --- シェルパイプラインへのインタフェース
    • テンプレートオブジェクト
  • resource --- リソース使用状態の情報
    • リソースの制限
    • リソースの使用状態
  • nis --- Sun の NIS (Yellow Pages) へのインタフェース
  • syslog --- Unix syslog ライブラリルーチン群
    • 使用例
      • シンプルな例

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


posix --- 最も一般的な POSIX システムコール群

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

posix --- 最も一般的な POSIX システムコール群

このモジュールはオペレーティングシステムの機能のうち、C 言語標準および (Unix インタフェースをほんの少し隠蔽した) POSIX 標準で標準化されている機能に対するアクセス機構を提供します。

このモジュールを直接インポートしてはいけません。 その代わりに、このインターフェースの ポータブル 版である os モジュールをインポートしてください。 Unix では、os モジュールは posix インターフェースのスーパーセットを提供しています。非 Unix オペレーティングシステムでは、 posix モジュールは利用できませんが、その一部分は os インターフェースを通して常に利用可能です。一度 os をインポートし posix の代わりにそれを使えば、パフォーマンス上の代償は ありません 。加えて os は、 os.environ の要素が変更されたときに putenv() を呼び出すなどの追加の機能も提供します。

エラーは例外として報告されます; よくある例外は型エラーです。一方、システムコールから報告されたエラーは以下に述べるように OSError を送出します。

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

いくつかのオペレーティングシステム (AIX, HP-UX, Irix および Solaris が含まれます) は、 int および long を 32 ビット値とする C プログラムモデルで 2GB を超えるサイズのファイルのサポートを提供しています。このサポートは典型的には関連するサイズとオフセットの組合せを 64-bit 値として定義することで実現しています。このようなファイルは時にラージファイル (large files) と呼ばれます。

Python では、 off_t のサイズが long より大きく、かつ long long 型を利用することができて、少なくとも off_t 型と同じくらい大きなサイズである場合、ラージファイルのサポートが有効になります。この場合、ファイルのサイズ、オフセットおよび Python の通常整数型の範囲を超えるような値の表現には Python の長整数型が使われます。このモードを有効にするのに、 configure で Python のコンパイルに特定のコンパイルフラグを必要とするかもしれません。例えば、ラージファイルのサポートは Irix の最近のバージョンでは標準で有効ですが、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 モジュール版を使う方が推奨されています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


pwd --- パスワードデータベースへのアクセスを提供する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

pwd --- パスワードデータベースへのアクセスを提供する

このモジュールは Unix のユーザアカウントとパスワードのデータベースへのアクセスを提供します。全ての Unix 系 OS で利用できます。

パスワードデータベースの各エントリはタプルのようなオブジェクトで提供され、それぞれの属性は 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 が発生します。

注釈

伝統的なUnixでは、 pw_passwd フィールドはDES由来のアルゴリズムで暗号化されたパスワード(crypt モジュールをごらんください)が含まれています。しかし、近代的なUNIX系OSでは シャドウパスワード とよばれる仕組みを利用しています。この場合には pw_passwd フィールドにはアスタリスク('*')か、 'x' という一文字だけが含まれており、暗号化されたパスワードは、一般には見えない /etc/shadow というファイルに入っています。 pw_passwd フィールドに有用な値が入っているかはシステムに依存します。利用可能なら、暗号化されたパスワードへのアクセスが必要なときには spwd モジュールを利用してください。

このモジュールでは以下の内容を定義しています:

pwd.getpwuid(uid)

与えられたUIDに対応するパスワードデータベースのエントリを返します。

pwd.getpwnam(name)

与えられたユーザ名に対応するパスワードデータベースのエントリを返します。

pwd.getpwall()

パスワードデータベースの全てのエントリを、任意の順番で並べたリストを返します。

参考

grp モジュール
このモジュールに似た、グループデータベースへのアクセスを提供するモジュール。
spwd モジュール
このモジュールと類似の、シャドウパスワードデータベースへのインタフェース。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

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

このモジュールは Unix のシャドウパスワードデータベースへのアクセスを提供します。様々な Unix 環境で利用できます。

シャドウパスワードデータベースへアクセスできる権限が必要(大抵の場合 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 モジュール
このモジュールに似た通常のパスワードデータベースへのインタフェース。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


grp --- グループデータベースへのアクセス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

grp --- グループデータベースへのアクセス

このモジュールでは Unix グループ (group) データベースへのアクセス機構を提供します。全ての Unix バージョンで利用可能です。

このモジュールはグループデータベースのエントリをタプルに似たオブジェクトとして報告されます。このオブジェクトの属性は group 構造体の各メンバ (以下の属性フィールド、<pwd.h> を参照) に対応します:

インデックス | 属性 | 意味
0 | gr_name | グループ名
1 | gr_passwd | (暗号化された) グループパスワード; しばしば空文字列になります
2 | gr_gid | 数字のグループ ID
3 | gr_mem | グループメンバの全てのユーザ名

gid は整数、名前およびパスワードは文字列、そしてメンバリストは文字列からなるリストです。 (ほとんどのユーザは、パスワードデータベースで自分が入れられているグループのメンバとしてグループデータベース内では明示的に列挙されていないので注意してください。完全なメンバ情報を取得するには両方のデータベースを調べてください。また、 + や - で始まる gr_name は YP/NIS 参照である可能性があり、 getgrnam() や getgrgid() でアクセスできないかもしれないことにも注意してください。)

このモジュールでは以下の内容を定義しています:

grp.getgrgid(gid)

与えられたグループ ID に対するグループデータベースエントリを返します。要求したエントリが見つからなかった場合、 KeyError が送出されます。

バージョン 3.6 で非推奨: Python 3.6から、浮動小数点数や文字列のような非整数値の引数のサポートが撤廃されました。

grp.getgrnam(name)

与えられたグループ名に対するグループデータベースエントリを返します。要求したエントリが見つからなかった場合、 KeyError が送出されます。

grp.getgrall()

全ての入手可能なグループエントリを返します。順番は決まっていません。

参考

pwd モジュール
このモジュールと類似の、ユーザデータベースへのインタフェース。
spwd モジュール
このモジュールと類似の、シャドウパスワードデータベースへのインタフェース。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

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

ソースコード: Lib/crypt.py

このモジュールは修正 DES アルゴリズムに基づいた一方向ハッシュ関数である crypt(3) ルーチンを実装しています。詳細については Unix マニュアルページを参照してください。このモジュールは、実際に入力されたパスワードを記録することなくチェック出来るようにするためのハッシュ化パスワードを記録したり、Unix パスワードに (脆弱性検査のための) 辞書攻撃を試みるのに使えます。

このモジュールは実行環境の crypt(3) の実装に依存しています。そのため、現在の実装で利用可能な拡張を、このモジュールでもそのまま利用できます。

ハッシュ化方式

バージョン 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.

バージョン 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文字のハッシュ値を持つモジュラー暗号形式です。これが最も弱い方式です。

モジュール属性

バージョン 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 will be used (as returned by methods()).

通常は、生の文字列のパスワードを word として渡し、前回の crypt() を呼び出した結果と今回の呼び出しの結果が同じになることで、パスワードの確認を行います。

salt (2文字から16文字のランダムな文字列で、方式を示す $digit$ が先頭に付いているかもしれません) は、暗号化アルゴリズムにぶれを生じさせるために使われます。 salt に含まれる文字は、モジュラー暗号形式の先頭にある $digit$ を除いて、集合 [./a-zA-Z0-9] に含まれていなければいけません。

ハッシュ化されたパスワードを文字列として返します。それは salt と同じアルファベット文字から構成されます。

いくつかの拡張された crypt(3) は異なる値と salt の長さを許しているので、パスワードをチェックする際には crypt されたパスワード文字列全体を salt として渡すよう勧めます。

バージョン 3.3 で変更: 文字列に加え、 salt が crypt.METHOD_* 値も受け取るようになりました。

crypt.mksalt(method=None, *, rounds=None)

指定された方式のランダムに生成されたソルトを返します。 method が与えられなかった場合は、 methods() で返される方式のうち最も強いものが使われます。

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 (24) and 2_147_483_648 (231), the default is 4096 (212).

バージョン 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")

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


termios --- POSIX スタイルの端末制御

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

termios --- POSIX スタイルの端末制御

This module provides an interface to the POSIX calls for tty I/O control. For a complete description of these calls, see termios(3) Unix manual page. It is only available for those Unix versions that support POSIX termios style tty I/O control configured during installation.

このモジュールの関数は全て、ファイル記述子 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)

ファイル記述子 fd の端末属性を attributes から取り出して設定します。 attributes は tcgetattr() が返すようなリストです。引数 when は属性がいつ変更されるかを決定します: TCSANOW は即時変更を行い、 TCSADRAIN は現在キューされている出力を全て転送した後に変更を行い、 TCSAFLUSH は現在キューされている出力を全て転送し、全てのキューされている入力を無視した後に変更を行います。

termios.tcsendbreak(fd, duration)

Send a break on file descriptor fd. A zero duration sends a break for 0.25--0.5 seconds; a nonzero duration has a system dependent meaning.

termios.tcdrain(fd)

ファイル記述子 fd に書き込まれた全ての出力が転送されるまで待ちます。

termios.tcflush(fd, queue)

ファイル記述子 fd にキューされたデータを無視します。どのキューかは queue セレクタで指定します: TCIFLUSH は入力キュー、 TCOFLUSH は出力キュー、 TCIOFLUSH は両方のキューです。

termios.tcflow(fd, action)

ファイル記述子 fd の入力または出力をサスペンドしたりレジュームしたりします。引数 action は出力をサスペンドする TCOOFF 、出力をレジュームする TCOON 、入力をサスペンドする TCIOFF 、入力をレジュームする TCION をとることができます。

参考

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


tty --- 端末制御のための関数群

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

tty --- 端末制御のための関数群

ソースコード: Lib/tty.py

tty モジュールは端末を cbreak および raw モードにするための関数を定義しています。

このモジュールは termios モジュールを必要とするため、 Unix でしか動作しません。

tty モジュールでは、以下の関数を定義しています:

tty.setraw(fd, when=termios.TCSAFLUSH)

ファイル記述子 fd のモードを raw モードに変えます。 when を省略すると標準の値は termios.TCSAFLUSH になり、 termios.tcsetattr() に渡されます。

tty.setcbreak(fd, when=termios.TCSAFLUSH)

ファイル記述子 fd のモードを cbreakモードに変えます。 when を省略すると標準の値は termios.TCSAFLUSH になり、 termios.tcsetattr() に渡されます。

参考

モジュール termios
低水準端末制御インタフェース。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


pty --- 擬似端末ユーティリティ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

pty --- 擬似端末ユーティリティ

ソースコード: Lib/pty.py

pty モジュールは擬似端末(他のプロセスを実行してその制御をしている端末をプログラムで読み書きする)を制御する操作を定義しています。

擬似端末の制御はプラットフォームに強く依存するので、Linux用のコードしか存在していません。(Linux用のコードは他のプラットフォームでも動作するように作られていますがテストされていません。)

pty モジュールでは以下の関数を定義しています:

pty.fork()

forkします。子プロセスの制御端末を擬似端末に接続します。返り値は (pid, fd) です。子プロセスは pid として0、fd として invalid をそれぞれ受けとります。親プロセスは pid として子プロセスのPID、fd として子プロセスの制御端末 (子プロセスの標準入出力に接続されている)のファイル記述子を受けとります。

pty.openpty()

新しい擬似端末のペアを開きます。利用できるなら os.openpty() を使い、利用できなければ一般的なUnixシステム用のエミュレーションコードを使います。マスター、スレーブそれぞれのためのファイル記述子、 (master, slave) のタプルを返します。

pty.spawn(argv[, master_read[, stdin_read]])

プロセスを生成して制御端末を現在のプロセスの標準入出力に接続します。これは制御端末を読もうとするプログラムをごまかすために利用されます。

master_read と stdin_read にはファイル記述子から読み込む関数を指定してください。デフォルトでは呼ばれるたびに1024バイトずつ読み込もうとします。

バージョン 3.4 で変更: spawn() が os.waitpid() が返す子プロセスのステータス値を返すようになりました。

使用例

下記のプログラムは Unix コマンド 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)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


fcntl --- fcntl および ioctl システムコール

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

fcntl --- fcntl および ioctl システムコール

このモジュールでは、ファイル記述子 (file descriptor) に基づいたファイル制御および I/O 制御を実現します。 このモジュールは、 Unix のルーチンである fcntl() および ioctl() へのインタフェースです。 これらのシステムコールの完全な説明は、 fcntl(2) と ioctl(2) のUnix マニュアルページを参照してください。

このモジュール内の全ての関数はファイル記述子 fd を最初の引数に取ります。 この値は sys.stdin.fileno() が返すような整数のファイル記述子でも、 sys.stdin 自体のような、純粋にファイル記述子だけを返す fileno() メソッドを提供している io.IOBase オブジェクトでもかまいません。

バージョン 3.3 で変更: 以前は IOError を送出していたこのモジュールの操作が、 OSError を送出するようになりました。

このモジュールには、以下の関数が定義されています:

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 バイトよりも大きい場合、大抵はセグメンテーション違反となるか、より不可思議なデータの破損を引き起こします。

fcntl() が失敗した場合、 OSError が送出されます。

fcntl.ioctl(fd, request, arg=0, mutate_flag=True)

この関数は fcntl() 関数と同じですが、引数の扱いがより複雑であるところが異なります。

パラメータ request は32ビットに収まる値に制限されます。 request 引数として使うのに関係のある追加の定数は termios モジュールにあり、関連する C ヘッダファイルで使われているのと同じ名前が付けられています。

パラメタ arg は、整数、 (bytes のような) 読み出し専用のバッファインタフェースをサポートするオブジェクト、読み書きバッファインタフェースをサポートするオブジェクトのどれかです。

最後の型のオブジェクトを除き、動作は fcntl() 関数と同じです。

可変なバッファが渡された場合、動作は mutate_flag 引数の値で決定されます。

この値が偽の場合、バッファの可変性は無視され、読み出し専用バッファの場合と同じ動作になりますが、上で述べた 1024 バイトの制限は回避されます -- 従って、オペレーティングシステムが希望するバッファ長までであれば正しく動作します。

mutate_flag が真 (デフォルト) の場合、バッファは (実際には) 根底にある ioctl() システムコールに渡され、後者の戻り値が呼び出し側の Python に引き渡され、バッファの新たな内容は ioctl() の動作を反映します。この説明はやや単純化されています。というのは、与えられたバッファが 1024 バイト長よりも短い場合、バッファはまず 1024 バイト長の静的なバッファにコピーされてから ioctl() に渡され、その後引数で与えたバッファに戻しコピーされるからです。

ioctl() が失敗すると、 OSError 例外が送出されます。

以下に例を示します:

>>> 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])
fcntl.flock(fd, operation)

ファイル記述子 fd (fileno() メソッドを提供しているファイルオブジェクトも含む) に対してロック操作 operation を実行します。 詳細は Unix マニュアルの flock(2) を参照してください (システムによっては、この関数は fcntl() を使ってエミュレーションされています)。

flock() が失敗すると、 OSError 例外が送出されます。

fcntl.lockf(fd, cmd, len=0, start=0, whence=0)

本質的に fcntl() によるロッキングの呼び出しをラップしたものです。 fd はロックまたはアンロックするファイルのファイル記述子で、 cmd は以下の値のうちいずれかになります:

  • LOCK_UN -- アンロック
  • LOCK_SH -- 共有ロックを取得
  • LOCK_EX -- 排他的ロックを取得

cmd が LOCK_SH または LOCK_EX の場合、 LOCK_NB とビット OR にすることでロック取得時にブロックしないようにすることができます。 LOCK_NB が使われ、ロックが取得できなかった場合、 OSError が送出され、例外は errno 属性を持ち、その値は EACCES または EAGAIN になります (オペレーティングシステムに依存します; 可搬性のため、両方の値をチェックしてください)。少なくともいくつかのシステムでは、ファイル記述子が参照しているファイルが書き込みのために開かれている場合、 LOCK_EX だけしか使うことができません。

len はロックを行いたいバイト数、 start はロック領域先頭の whence からの相対的なバイトオフセット、 whence は io.IOBase.seek() と同じで、具体的には:

  • 0 -- ファイル先頭からの相対位置 (os.SEEK_SET)
  • 1 -- 現在のバッファ位置からの相対位置 (os.SEEK_CUR)
  • 2 -- ファイルの末尾からの相対位置 (os.SEEK_END)

start の標準の値は 0 で、ファイルの先頭から開始することを意味します。len の標準の値は 0 で、ファイルの終了までロックすることを表します。whence の標準の値も 0 です。

以下に (全ての 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 モジュール
もし os モジュールに os.O_SHLOCK と os.O_EXLOCK が 存在する場合 (BSD のみ)、 os.open() 関数は lockf() や flock() 関数を代替できます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

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

ソースコード: Lib/pipes.py

pipes モジュールでは、 pipeline の概念 --- あるファイルを別のファイルに変換する機構の直列接続 --- を抽象化するためのクラスを定義しています。

このモジュールは /bin/sh コマンドラインを利用するため、 os.system() および os.popen() のための POSIX 準拠のシェル、または互換のシェルが必要です。

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 にコピーします。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


resource --- リソース使用状態の情報

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

resource --- リソース使用状態の情報

このモジュールでは、プログラムによって使用されているシステムリソースを計測したり制御するための基本的なメカニズムを提供します。

特定のシステムリソースを指定したり、現在のプロセスやその子プロセスのリソース使用情報を要求するためにシンボル定数が使われます。

システムコールが失敗した場合 OSError を送出します。

exception resource.error

OSError の非推奨のエイリアスです。

バージョン 3.3 で変更: PEP 3151 に基づき、このクラスは OSError のエイリアスになりました。

リソースの制限

リソースの使用は下に述べる setrlimit() 関数を使って制限することができます。各リソースは二つ組の制限値: ソフトリミット (soft limit) 、およびハードリミット (hard limit) 、で制御されます。ソフトリミットは現在の制限値で、時間とともにプロセスによって下げたり上げたりできます。ソフトリミットはハードリミットを超えることはできません。ハードリミットはソフトリミットよりも高い任意の値まで下げることができますが、上げることはできません。 (スーパユーザの有効な UID を持つプロセスのみがハードリミットを上げることができます。)

制限をかけるべく指定できるリソースはシステムに依存します。指定できるリソースは 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 を送出する場合があります。

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 を送出します。

Availability: Linux 2.6.36 or later with glibc 2.13 or later.

バージョン 3.4 で追加.

以下のシンボルは、後に述べる関数 setrlimit() および getrlimit() を使って消費量を制御することができるリソースを定義しています。これらのシンボルの値は、C プログラムで使われているシンボルと全く同じです。

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

プロセスが占有できるマップメモリの最大領域です。

resource.RLIMIT_AS

アドレス空間でプロセスが占有できる最大領域 (バイト単位) です。

resource.RLIMIT_MSGQUEUE

POSIX メッセージキューに割り当てることの出来るバイト数です。

Availability: Linux 2.6.8 or later.

バージョン 3.4 で追加.

resource.RLIMIT_NICE

プロセスの nice の上限です (20 - rlim_cur)。

Availability: Linux 2.6.12 or later.

バージョン 3.4 で追加.

resource.RLIMIT_RTPRIO

リアルタイム優先順位の上限です。

Availability: Linux 2.6.12 or later.

バージョン 3.4 で追加.

resource.RLIMIT_RTTIME

The time limit (in microseconds) on CPU time that a process can spend under real-time scheduling without making a blocking syscall.

Availability: Linux 2.6.25 or later.

バージョン 3.4 で追加.

resource.RLIMIT_SIGPENDING

プロセスがキュー出来るシグナルの数です。

Availability: Linux 2.6.8 or later.

バージョン 3.4 で追加.

resource.RLIMIT_SBSIZE

The maximum size (in bytes) of socket buffer usage for this user. This limits the amount of network memory, and hence the amount of mbufs, that this user may hold at any time.

Availability: FreeBSD 9 or later.

バージョン 3.4 で追加.

resource.RLIMIT_SWAP

The maximum size (in bytes) of the swap space that may be reserved or used by all of this user id's processes. This limit is enforced only if bit 1 of the vm.overcommit sysctl is set. Please see tuning(7) for a complete description of this sysctl.

Availability: FreeBSD 9 or later.

バージョン 3.4 で追加.

resource.RLIMIT_NPTS

このユーザ ID が作成する擬似端末の数の上限です。

Availability: FreeBSD 9 or later.

バージョン 3.4 で追加.

リソースの使用状態

以下の関数はリソース使用情報を取得するために使われます:

resource.getrusage(who)

この関数は、 who 引数で指定される、現プロセスおよびその子プロセスによって消費されているリソースを記述するオブジェクトを返します。 who 引数は以下に記述される RUSAGE_* 定数のいずれかを使って指定します。

返される値の各フィールドはそれぞれ、個々のシステムリソースがどれくらい使用されているか、例えばユーザモードでの実行に費やされた時間やプロセスが主記憶からスワップアウトされた回数、を示しています。幾つかの値、例えばプロセスが使用しているメモリ量は、内部時計の最小単位に依存します。

以前のバージョンとの互換性のため、返される値は 16 要素からなるタプルとしてアクセスすることもできます。

戻り値のフィールド ru_utime および ru_stime は浮動小数点数で、それぞれユーザモードでの実行に費やされた時間、およびシステムモードでの実行に費やされた時間を表します。それ以外の値は整数です。これらの値に関する詳しい情報は getrusage(2) を調べてください。以下に簡単な概要を示します:

インデックス | フィールド | リソース
0 | ru_utime | ユーザモード実行時間 (float)
1 | ru_stime | システムモード実行時間 (float)
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()

システムページ内のバイト数を返します。(ハードウェアページサイズと同じとは限りません。)

以下の RUSAGE_* シンボルはどのプロセスの情報を提供させるかを指定するために関数 getrusage() に渡されます。

resource.RUSAGE_SELF

getrusage() に渡すと呼び出し中のプロセスが消費しているリソースを要求します。そのプロセスの全スレッドが使用するリソースの合計です。

resource.RUSAGE_CHILDREN

Pass to getrusage() to request resources consumed by child processes of the calling process which have been terminated and waited for.

resource.RUSAGE_BOTH

getrusage() に渡すと現在のプロセスおよび子プロセスの両方が消費しているリソースを要求します。全てのシステムで利用可能なわけではありません。

resource.RUSAGE_THREAD

getrusage() に渡すと現在のスレッドが消費しているリソースを要求します。全てのシステムで利用可能なわけではありません。

バージョン 3.2 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

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

nis モジュールは複数のホストを集中管理する上で便利な NIS ライブラリを薄くラップします。

NIS は Unix システム上にしかないので、このモジュールは Unix でしか利用できません。

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 関数がエラーコードを返した場合に送出されます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


syslog --- Unix syslog ライブラリルーチン群

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • Unix 固有のサービス »

syslog --- Unix syslog ライブラリルーチン群

このモジュールでは Unix syslog ライブラリルーチン群へのインタフェースを提供します。syslog の便宜レベルに関する詳細な記述は Unix マニュアルページを参照してください。

このモジュールはシステムの syslog ファミリのルーチンをラップしています。 syslog サーバーと通信できる pure Python のライブラリが、 logging.handlers モジュールの SysLogHandler にあります。

このモジュールには、以下の関数が定義されています:

syslog.syslog(message)
syslog.syslog(priority, message)

文字列 message をシステムログ機構に送信します。末尾の改行文字は必要に応じて追加されます。各メッセージは facility および level からなる優先度でタグ付けされます。オプションの priority 引数はメッセージの優先度を定義します。標準の値は LOG_INFO です。 priority 中に、便宜レベルが (LOG_INFO | LOG_USER のように) 論理和を使ってコード化されていない場合、 openlog() を呼び出した際の値が使われます。

syslog() が呼び出される前に openlog() が呼び出されなかった場合、 openlog() が引数なしで呼び出されます。

syslog.openlog([ident[, logoption[, facility]]])

openlog() 関数を呼び出すことで以降の syslog() の呼び出しに対するログオプションを設定することができます。ログがまだ開かれていない状態で syslog() を呼び出すと openlog() が引数なしで呼び出されます。

オプションの ident キーワード引数は全てのメッセージの先頭に付く文字列で、デフォルトでは sys.argv[0] から前方のパス部分を取り除いたものです。オプションの logoption キーワード引数 (デフォルトは 0) はビットフィールドです。組み合わせられる値については下記を参照してください。オプションの facility キーワード引数 (デフォルトは LOG_USER) は明示的に facility が encode されていないメッセージに設定される facility です。

バージョン 3.2 で変更: In previous versions, keyword arguments were not allowed, and ident was required. The default for ident was dependent on the system libraries, and often was python instead of the name of the Python program file.

syslog.closelog()

syslog モジュールの値をリセットし、システムライブラリの closelog() を呼び出します。

この関数を呼ぶと、モジュールが最初に import されたときと同じようにふるまいます。例えば、(openlog() を呼び出さないで) syslog() を最初に呼び出したときに、 openlog() が呼び出され、 ident やその他の openlog() の引数はデフォルト値にリセットされます。

syslog.setlogmask(maskpri)

優先度マスクを maskpri に設定し、以前のマスク値を返します。 maskpri に設定されていない優先度レベルを持った syslog() の呼び出しは無視されます。標準では全ての優先度をログ出力します。関数 LOG_MASK(pri) は個々の優先度 pri に対する優先度マスクを計算します。関数 LOG_UPTO(pri) は優先度 pri までの全ての優先度を含むようなマスクを計算します。

このモジュールでは以下の定数を定義しています:

優先度 (降順):
LOG_EMERG 、 LOG_ALERT 、 LOG_CRIT 、 LOG_ERR 、 LOG_WARNING 、 LOG_NOTICE 、 LOG_INFO 、 LOG_DEBUG 。
機能:
LOG_KERN 、 LOG_USER 、 LOG_MAIL 、 LOG_DAEMON 、 LOG_AUTH 、 LOG_LPR 、 LOG_NEWS 、 LOG_UUCP 、 LOG_CRON 、LOG_SYSLOG 、 LOG_LOCAL0 から LOG_LOCAL7 、および <syslog.h> で定義されていれば、 LOG_AUTHPRIV 。
ログオプション:
LOG_PID 、 LOG_CONS 、 LOG_NDELAY 、また <syslog.h> で定義されている場合、 LOG_ODELAY、 LOG_NOWAIT 、および 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...')

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Unix 固有のサービス »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

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

この章に記述されたモジュール群は非推奨で、後方互換性のためにのみ保存されています。これらは他のモジュール群に取って代わられました。

  • optparse --- コマンドラインオプション解析器
    • 背景
      • 用語集
      • オプションとは何か
      • 位置引数とは何か
    • チュートリアル
      • オプション・アクションを理解する
      • store アクション
      • ブール値 (フラグ) オプションの処理
      • その他のアクション
      • デフォルト値
      • ヘルプの生成
        • オプションをグループ化する
      • バージョン番号の出力
      • optparse のエラー処理法
      • 全てをつなぎ合わせる
    • リファレンスガイド
      • parserを作る
      • パーザへのオプション追加
      • オプションの定義
      • オプション属性
      • 標準的なオプション・アクション
      • 標準のオプション型
      • 引数を解析する
      • オプション解析器への問い合わせと操作
      • オプション間の衝突
      • クリーンアップ
      • その他のメソッド
    • オプション処理コールバック
      • callbackオプションの定義
      • コールバック関数はどのように呼び出されるか
      • コールバック中で例外を送出する
      • コールバックの例 1: ありふれたコールバック
      • コールバックの例 2: オプションの順番をチェックする
      • コールバックの例 3: オプションの順番をチェックする (汎用的)
      • コールバックの例 4: 任意の条件をチェックする
      • コールバックの例5: 固定引数
      • コールバックの例6: 可変個の引数
    • optparse の拡張
      • 新しい型の追加
      • 新しいアクションの追加
  • imp --- import 内部へのアクセス
    • 使用例

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


optparse --- コマンドラインオプション解析器

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 取って代わられたモジュール群 »

optparse --- コマンドラインオプション解析器

ソースコード: Lib/optparse.py

バージョン 3.2 で非推奨: optparse モジュールは廃止予定であり、これ以上の開発は行われません。argparse モジュールを使用してください。

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

コマンドライン解析の中で、 optparse はユーザの指定したコマンドライン引数値に応じて parse_args() の返す options の属性値を設定してゆきます。 parse_args() がコマンドライン解析から処理を戻したとき、 options.filename は "outfile" に、 options.verbose は False になっているはずです。 optparse は長い形式と短い形式の両方のオプション表記をサポートしており、短い形式は結合して指定できます。また、様々な形でオプションに引数値を関連付けられます。従って、以下のコマンドラインは全て上の例と同じ意味になります:

<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 ではサポートしておらず、今後もサポートする予定はありません。これは故意によるものです: 最初の三つはどの環境の標準でもなく、最後の一つは VMS や MS-DOS, そして Windows を対象にしているときにしか意味をなさないからです。

オプション引数 (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()

(お望みなら、 parse_args() に自作の引数リストを渡してもかまいません。とはいえ、実際にはそうした必要はほとんどないでしょう: optionparser はデフォルトで sys.argv[1:] を使うからです。)

parse_args() は二つの値を返します:

  • 全てのオプションに対する値の入ったオブジェクト 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)

オプション文字列 -f を見つけると、 optparse は次の引数である foo.txt を消費し、その値を options.filename に保存します。従って、この parse_args() 呼び出し後には options.filename は "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"
定数値を保存します
"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 になります; 特定の目的変数に対するデフォルト値として有効なのは、最後に指定した値だからです。

デフォルト値をすっきりと指定するには、 OptionParser の set_defaults() メソッドを使います。このメソッドは 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]")
プログラムが間違った方法で実行されるかまたはヘルプオプションを付けて実行された場合に表示される使用法です。 optparse は使用法の文字列を表示する際に %prog を os.path.basename(sys.argv[0]) (または prog キーワード引数が指定されていればその値) に展開します。使用法メッセージを抑制するためには特別な 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_true"
真 (True) を保存します
"store_false"
偽 (False) を保存します
"append"
オプションの引数を指定のリストに追加します
"append_const"
オプションの引数をリストに追加します
"count"
指定のカウンタを 1 増やします
"callback"
指定の関数を呼び出します
"help"
全てのオプションとそのドキュメントの入った使用法メッセージを出力します

(アクションを指定しない場合、デフォルトは "store" になります。このアクションでは、 type および dest オプション属性を指定できます。 標準的なオプション・アクション を参照してください。)

すでにお分かりのように、ほとんどのアクションはどこかに値を保存したり、値を更新したりします。この目的のために、 optparse は常に特別なオブジェクトを作り出し、それは通常 options と呼ばれます (optparse.Values のインスタンスになっています)。オプションの引数 (や、その他の様々な値) は、 dest (保存先: destination) オプション属性に従って、 options の属性として保存されます。

例えばこれを呼び出した場合

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 だけなのです。

オプション属性

以下のオプション属性は 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 オプション(--help のような)を指定したときに表示される、使用可能な全オプションのリストの中のこのオプションに関する説明文です。説明文を提供しておかなければ、オプションは説明文なしで表示されます。オプションを隠すには特殊な値 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]

    "store_const" の特殊なケースで、真 (True) を dest に保存します。

  • "store_false" [関連: dest]

    "store_true" と似ていて、偽 (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 文字列から生成します。

    オプションに help 文字列が指定されていなくても、オプションはヘルプメッセージ中に列挙されます。オプションを完全に表示させないようにするには、特殊な値 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 を送出します。

引数を解析する

OptionParser を作成してオプションを追加していく上で大事なポイントは、 parse_args() メソッドの呼び出しです:

(options, args) = parser.parse_args(args=None, values=None)

ここで入力パラメータは

args
処理する引数のリスト (デフォルト: sys.argv[1:])
values
オプション引数を格納する optparse.Values のオブジェクト (デフォルト: 新しい Values のインスタンス) -- 既存のオブジェクトを指定した場合、オプションのデフォルトは初期化されません

であり、戻り値は

options
values に渡されたものと同じオブジェクト、または optparse によって生成された optparse.Values インスタンス
args
全てのオプションの処理が終わった後で残った位置引数

一番普通の使い方は一切キーワード引数を使わないというものです。 values を指定した場合、それは繰り返される setattr() の呼び出し (大雑把に言うと保存される各オプション引数につき一回ずつ) で更新されていき、 parse_args() で返されます。

parse_args() が引数リストでエラーに遭遇した場合、 OptionParser の error() メソッドを適切なエンドユーザ向けのエラーメッセージとともに呼び出します。この呼び出しにより、最終的に終了ステータス 2 (伝統的な Unix におけるコマンドラインエラーの終了ステータス) でプロセスを終了させることになります。

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

オプションパーザのデフォルトの振る舞いは、ある程度カスタマイズすることができます。また、オプションパーザの中を調べることもできます。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 がある場合、真を返します。

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)

上で説明したコンストラクタの usage キーワード引数での規則に従った使用法の文字列をセットします。 None を渡すとデフォルトの使用法文字列が使われるようになり、 optparse.SUPPRESS_USAGE によって使用法メッセージを抑制できます。

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
現在放置されている引数、すなわち、すでに消費されたものの、オプションでもオプション引数でもない引数からなるリストです。 parser.largs は自由に変更でき、たとえば引数を追加したりできます (このリストは args 、すなわち 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)

    values に attr 属性が無いか None だった場合に、 ensure_value() は最初に value をセットし、それから value を返します。この振る舞いは "extend", "append", "count" のように、データを変数に集積し、またその変数がある型 (最初の二つはリスト、最後のは整数) であると期待されるアクションを作るのにとても使い易いものです。 ensure_value() を使えば、作ったアクションを使うスクリプトはオプションに保存先にデフォルト値をセットすることに煩わされずに済みます。デフォルトを None にしておけば ensure_value() がそれが必要になったときに適当な値を返してくれます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 取って代わられたモジュール群 »


imp --- import 内部へのアクセス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »
  • 取って代わられたモジュール群 »

imp --- import 内部へのアクセス

ソースコード: Lib/imp.py

バージョン 3.4 で非推奨: imp パッケージは importlib を後継として廃止予定です。

このモジュールは import 文を実装するために使われているメカニズムへのインターフェイスを提供します。次の定数と関数が定義されています:

imp.get_magic()

バイトコンパイルされたコードファイル(.pyc ファイル)を認識するために使われるマジック文字列値を返します。 (この値は Python の各バージョンで異なります。)

バージョン 3.4 で非推奨: 代わりに importlib.util.MAGIC_NUMBER を使用してください。

imp.get_suffixes()

3要素のタプルのリストを返します。それぞれのタプルは特定の種類のモジュールを説明しています。各タプルは (suffix, mode, type) という形式です。ここで、 suffix は探すファイル名を作るためにモジュール名に追加する文字列です。そのファイルをオープンするために、 mode は組み込み open() 関数へ渡されるモード文字列です (これはテキストファイル対しては 'r' 、バイナリファイルに対しては 'rb' となります)。 type はファイル型で、以下で説明する値 PY_SOURCE, PY_COMPILED あるいは、 C_EXTENSION の一つを取ります。

バージョン 3.3 で非推奨: 代わりに importlib.machinery で定義された定数を使ってください。

imp.find_module(name[, path])

モジュール name を見つけようとします。 path が省略されるか None ならば、 sys.path によって与えられるディレクトリ名のリストが検索されます。しかし、最初にいくつか特別な場所を検索します。まず、所定の名前をもつ組み込みモジュール(C_BUILTIN)を見つけようとします。それから、フリーズされたモジュール(PY_FROZEN)、そしていくつかのシステムでは他の場所が同様に検索されます (Windowsでは、特定のファイルを指すレジストリの中を見ます)。

それ以外の場合、 path はディレクトリ名のリストでなければなりません。上の get_suffixes() が返す拡張子のいずれかを伴ったファイルを各ディレクトリの中で検索します。リスト内の有効でない名前は黙って無視されます(しかし、すべてのリスト項目は文字列でなければなりません)。

検索が成功すれば、戻り値は3要素のタプル (file, pathname, description) です:

file は先頭に位置合わせされたオープン ファイルオブジェクト で、 pathname は見つかったファイルのパス名です。そして、 description は get_suffixes() が返すリストに含まれているような3要素のタプルで、見つかったモジュールの種類を説明しています。

モジュールがファイルとして存在していなければ、返された file は None で、 pathname は空文字列、 description タプルはその拡張子とモードに対して空文字列を含みます。モジュール型は上の括弧の中に示されます。検索が失敗すれば、 ImportError が発生します。他の例外は引数または環境に問題があることを示唆します。

モジュールがパッケージならば、 file は None で、 pathname はパッケージのパスで description タプルの最後の項目は PKG_DIRECTORY です。

この関数は階層的なモジュール名(ドットを含む名前)を扱いません。 P.M 、すなわちパッケージ P のサブモジュール M を見つけるためには、まず find_module() と load_module() を使用してパッケージ P を見つけてロードして、次に P.__path__ を path 引数にして find_module() を呼び出してください。もし P 自体がドット付きの名前を持つ場合、このレシピを再帰的に適用してください。

バージョン 3.3 で非推奨: Python 3.3 との互換性が不要であれば、importlib.util.find_spec() を使用してください, 互換性が必要な場合は importlib.find_loader() を使用してください。前者の使用例は、importlib ドキュメントの:ref:importlib-examples セクションを参照してください。

imp.load_module(name, file, pathname, description)

find_module() を使って(あるいは、互換性のある結果を作り出す検索を行って)以前見つけたモジュールをロードします。この関数はモジュールをインポートするという以上のことを行います: モジュールが既にインポートされているならば、リロードします! name 引数は(これがパッケージのサブモジュールならばパッケージ名を含む)完全なモジュール名を示します。 file 引数はオープンしたファイルで、 pathname は対応するファイル名です。モジュールがパッケージであるかファイルからロードされようとしていないとき、これらはそれぞれ None と '' であっても構いません。 get_suffixes() が返すように description 引数はタプルで、どの種類のモジュールがロードされなければならないかを説明するものです。

ロードが成功したならば、戻り値はモジュールオブジェクトです。そうでなければ、例外(たいていは ImportError)が発生します。

重要: file 引数が None でなければ、例外が発生した場合でも呼び出し側にはそれを閉じる責任があります。これを行うには、 try ... finally 文を使うことが最も良いです。

バージョン 3.3 で非推奨: If previously used in conjunction with imp.find_module() then consider using importlib.import_module(), otherwise use the loader returned by the replacement you chose for imp.find_module(). If you called imp.load_module() and related functions directly with file path arguments then use a combination of importlib.util.spec_from_file_location() and importlib.util.module_from_spec(). See the 使用例 section of the importlib documentation for details of the various approaches.

imp.new_module(name)

name という名前の新しい空モジュールオブジェクトを返します。このオブジェクトは sys.modules に挿入され ません 。

バージョン 3.4 で非推奨: 代わりに:func:importlib.util.module_from_spec を使用してください。

imp.reload(module)

すでにインポートされた module を再解釈し、再初期化します。引数はモジュールオブジェクトでなければならないので、予めインポートに成功していなければなりません。この関数はモジュールのソースコードファイルを外部エディタで編集して、Python インタプリタから離れることなく新しいバージョンを試したい際に有効です。戻り値は (module 引数と同じ) モジュールオブジェクトです。

reload(module) を実行すると、以下の処理が行われます:

  • Python モジュールのコードは再コンパイルされ、モジュールレベルのコードは再度実行されます。モジュールの辞書中にある、何らかの名前に結び付けられたオブジェクトを新たに定義します。拡張モジュール中の init 関数が二度呼び出されることはありません。
  • Python における他のオブジェクトと同様、以前のオブジェクトのメモリ領域は、参照カウントがゼロにならないかぎり再利用されません。
  • モジュール名前空間内の名前は新しいオブジェクト (または更新されたオブジェクト) を指すよう更新されます。
  • 以前のオブジェクトが (外部の他のモジュールなどからの) 参照を受けている場合、それらを新たなオブジェクトに再束縛し直すことはないので、必要なら自分で名前空間を更新しなければなりません。

いくつか補足説明があります:

モジュールが再ロードされた際、その辞書 (モジュールのグローバル変数を含みます) はそのまま残ります。名前の再定義を行うと、以前の定義を上書きするので、一般的には問題はありません。新たなバージョンのモジュールが古いバージョンで定義された名前を定義していない場合、古い定義がそのまま残ります。辞書がグローバルテーブルやオブジェクトのキャッシュを維持していれば、この機能をモジュールを有効性を引き出すために使うことができます --- つまり、 try 文を使えば、必要に応じてテーブルがあるかどうかをテストし、その初期化を飛ばすことができます:

try:
    cache
except NameError:
    cache = {}

ビルトインのモジュールや動的にロードされたモジュールをリロードすることは、 sys, __main__, builtins を除いて一般にはそれほど有用ではありませんが、合法です。しかし、多くの場合、拡張モジュールは二度以上初期化されるようには作られておらず、リロードされた時に無作為な方法で失敗するかもしれません。

If a module imports objects from another module using from ... import ..., calling reload() for the other module does not redefine the objects imported from it --- one way around this is to re-execute the from statement, another is to use import and qualified names (module.*name*) instead.

あるモジュールがクラスのインスタンスを生成している場合、そのクラスを定義しているモジュールの再ロードはそれらインスタンスのメソッド定義に影響しません --- それらは古いクラス定義を使い続けます。これは派生クラスの場合でも同じです。

バージョン 3.3 で変更: リロードされるモジュール上で、__name__ だけでなく __name__ と __loader__ の両方が定義されていることに依存します。

バージョン 3.4 で非推奨: 代わりに importlib.reload() を使用してください。

以下は、 PEP 3147 のバイトコンパイルされたファイルパスを扱うために便利な関数です。

バージョン 3.2 で追加.

imp.cache_from_source(path, debug_override=None)

ソース path に関連付けられたバイトコンパイルされたファイルの PEP 3147 パスを返します。例えば、 path が /foo/bar/baz.py なら、 Python 3.2 の場合返り値は /foo/bar/__pycache__/baz.cpython-32.pyc になります。 cpython-32 という文字列は、現在のマジックタグから得られます (マジックタグについては get_tag() を参照; sys.implementation.cache_tag が未定義なら NotImplementedError が送出されます)。 debug_override に True あるいは False を渡すことによって、 __debug__ システム値をオーバーライドして最適化されたバイトコードを得ることができます。

path は存在している必要はありません。

バージョン 3.3 で変更: sys.implementation.cache_tag が None の場合、 NotImplementedError が上げられます。

バージョン 3.4 で非推奨: 代わりに importlib.util.cache_from_source() を使用してください。

バージョン 3.5 で変更: debug_override 引数は .pyo ファイルを作成することはもうありません。

imp.source_from_cache(path)

Given the path to a PEP 3147 file name, return the associated source code file path. For example, if path is /foo/bar/__pycache__/baz.cpython-32.pyc the returned path would be /foo/bar/baz.py. path need not exist, however if it does not conform to PEP 3147 format, a ValueError is raised. If sys.implementation.cache_tag is not defined, NotImplementedError is raised.

バージョン 3.3 で変更: sys.implementation.cache_tag が定義されていない場合、 NotImplementedError が上げられます。

バージョン 3.4 で非推奨: 代わりに importlib.util.source_from_cache() を使用してください。

imp.get_tag()

get_magic() によって返されるのと同じ、このバージョンの Python のマジックナンバーと一致する PEP 3147 のマジックタグ文字列を返します。

バージョン 3.4 で非推奨: Python 3.3 からは sys.implementation.cache_tag を直接使ってください。

以下の関数はインポートシステムの内部ロックメカニズムとのやりとりをサポートします。インポートのロックセマンティクスはリリース毎に変わる可能性のある実装詳細です。ただし、Python は循環インポートがデッドロックなしで動作することを保証しています。

imp.lock_held()

現在グローバルなインポートロックが保持されている場合 True を返し、そうでなければ False を返します。スレッドのないプラットフォームでは常に False を返します。

スレッドを持つプラットフォームでは、まずインポートを実行するスレッドがグローバルなインポートロックを保持し、次にインポートの残りの部分を実行するためにモジュール単位のロックをセットアップします。これは、他のスレッドが同じモジュールをインポートするのをオリジナルのインポートが完了するまでブロックして、他のスレッドがオリジナルのスレッドによって構築された不完全なモジュールオブジェクトを見てしまわないようにします。循環インポートに対しては例外が発生します。これは、そのようなモジュールを構築するためには、どこかの時点で不完全なモジュールオブジェクトを露出しなければならないためです。

バージョン 3.3 で変更: ロックスキームは、大部分がモジュール毎のロックに変わりました。グローバルなインポートロックは、モジュール毎のロックを初期化するようないくつかのクリティカルタスクのために維持されます。

バージョン 3.4 で非推奨.

imp.acquire_lock()

現在のスレッドに対するインタープリタのグローバルなインポートロックを獲得します。このロックは、モジュールをインポートする際にスレッドセーフ性を保証するために、インポートフックによって使用されるべきです。

一旦スレッドがインポートロックを取得したら、その同じスレッドはブロックされることなくそのロックを再度取得できます。スレッドはロックを取得するのと同じだけ解放しなければなりません。

スレッドのないプラットホームではこの関数は何もしません。

バージョン 3.3 で変更: ロックスキームは、大部分がモジュール毎のロックに変わりました。グローバルなインポートロックは、モジュール毎のロックを初期化するようないくつかのクリティカルタスクのために維持されます。

バージョン 3.4 で非推奨.

imp.release_lock()

インタープリタのグローバルなインポートロックを解放します。スレッドのないプラットフォームでは何もしません。

バージョン 3.3 で変更: ロックスキームは、大部分がモジュール毎のロックに変わりました。グローバルなインポートロックは、モジュール毎のロックを初期化するようないくつかのクリティカルタスクのために維持されます。

バージョン 3.4 で非推奨.

整数値をもつ次の定数はこのモジュールの中で定義されており、 find_module() の検索結果を表すために使われます。

imp.PY_SOURCE

ソースファイルとしてモジュールが発見された。

バージョン 3.3 で非推奨.

imp.PY_COMPILED

コンパイルされたコードオブジェクトファイルとしてモジュールが発見された。

バージョン 3.3 で非推奨.

imp.C_EXTENSION

動的にロード可能な共有ライブラリとしてモジュールが発見された。

バージョン 3.3 で非推奨.

imp.PKG_DIRECTORY

パッケージディレクトリとしてモジュールが発見された。

バージョン 3.3 で非推奨.

imp.C_BUILTIN

モジュールが組み込みモジュールとして発見された。

バージョン 3.3 で非推奨.

imp.PY_FROZEN

モジュールが frozen モジュールとして発見された。

バージョン 3.3 で非推奨.

class imp.NullImporter(path_string)

NullImporter 型は PEP 302 インポートフックで、何もモジュールが見つからなかったときの非ディレクトリパス文字列を処理します。この型を既存のディレクトリや空文字列に対してコールすると ImportError が発生します。それ以外の場合は NullImporter のインスタンスが返されます。

インスタンスはたった一つのメソッドを持ちます:

find_module(fullname[, path])

このメソッドは常に None を返し、要求されたモジュールが見つからなかったことを表します。

バージョン 3.3 で変更: NullImporter のインスタンスの代わりに None が sys.path_importer_cache に挿入されます。

バージョン 3.4 で非推奨: 代わりに None を sys.path_importer_cache に挿入してください。

使用例

次の関数は Python 1.4 までの標準 import 文(階層的なモジュール名がない)をエミュレートします。 (この 実装 はそのバージョンでは動作しないでしょう。なぜなら、 find_module() は拡張されており、また load_module() が 1.4 で追加されているからです。)

import imp
import sys

def __import__(name, globals=None, locals=None, fromlist=None):
    # Fast path: see if the module has already been imported.
    try:
        return sys.modules[name]
    except KeyError:
        pass

    # If any of the following calls raises an exception,
    # there's a problem we can't handle -- let the caller handle it.

    fp, pathname, description = imp.find_module(name)

    try:
        return imp.load_module(name, fp, pathname, description)
    finally:
        # Since we may exit via an exception, close fp explicitly.
        if fp:
            fp.close()

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • 取って代わられたモジュール群 »


ドキュメント化されていないモジュール

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python 標準ライブラリ »

ドキュメント化されていないモジュール

現在ドキュメント化されていないが、ドキュメント化すべきモジュールを以下にざっと列挙します。どうぞこれらのドキュメントを寄稿してください！ (電子メールで docs@python.org に送ってください。)

この章のアイデアと元の文章内容は Fredrik Lundh のポストによるものです; この章の特定の内容は実際には改訂されてきています。

プラットフォーム固有のモジュール

これらのモジュールは os.path モジュールを実装するために用いられていますが、ここで触れる内容を超えてドキュメントされていません。これらはもう少しドキュメント化する必要があります。

ntpath
--- Win32, Win64 プラットフォームにおける os.path 実装です。
posixpath
--- POSIXにおける os.path 実装です。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

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

このドキュメントでは、Pythonインタプリンタを拡張する新しいモジュールをで C またはC++ で書く方法を解説しています。このようなモジュールでは新しい関数を定義するだけではなく、新しい型や、そのメソッドを定義することができます。ドキュメントでは他のアプリケーションでPythonを拡張言語として使用するために、Pythonインタプリタをアプリケーションに埋め込む方法についても解説します。最後に、下層のオペレーティングシステムが動的(実行時)ロードをサポートしていれば、拡張モジュールが動的にライブラリにロードされるように、モジュールをコンパイルしリンクする方法について解説します。

このドキュメントでは、読者は Python について基礎的な知識を持ち合わせているものと仮定しています。形式ばらない Python 言語の入門には、 Python チュートリアル を読んでください。 Python 言語リファレンス を読めば、 Python 言語についてより形式的な定義を得られます。また、 Python 標準ライブラリ では、Python に広い適用範囲をもたらしている既存のオブジェクト型、関数、および (組み込み、および Python で書かれたものの両方の) モジュールについて解説しています。

Python/C API 全体の詳しい説明は、別のドキュメントである、 Python/C API リファレンスマニュアル を参照してください。

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

This guide only covers the basic tools for creating extensions provided as part of this version of CPython. Third party tools like Cython, cffi, SWIG and Numba offer both simpler and more sophisticated approaches to creating C and C++ extensions for Python.

参考

Python Packaging User Guide: 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. distutils による C および C++ 拡張モジュールのビルド
    • 4.2. 拡張モジュールの配布
  • 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 系システムにおけるコンパイルとリンク

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python インタプリタの拡張と埋め込み »

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

Python では、組み込みの str 型や list 型のような Python コードから走査できる新しい型を C 拡張モジュールの作者が定義できます。 全ての拡張の型のコードはあるパターンに従うのですが、書き始める前に理解しておくべき細かいことがあります。 このドキュメントはその話題についてのやさしい入門です。

2.1. 基本的なこと

CPython ランタイムは Python の全てのオブジェクトを PyObject* 型の変数と見なします。 PyObject* は Python の全てのオブジェクトの "基底型 (base type)" となっています。 PyObject 構造体自身は参照カウント (reference count) と、オブジェクトの "型オブジェクト (type object)" へのポインタのみを持ちます。 ここには動作が定義されています; 型オブジェクトは、例えば、ある属性があるオブジェクトから検索されたり、メソッドが呼ばれたり、他のオブジェクトによって操作されたりしたときに、どの (C) 関数がインタプリタから呼ばれるのかを決定します。 これらの C 関数は "タイプメソッド (type method)" と呼ばれます。

それなので、新しい拡張の型を定義したいときは、新しい型オブジェクトを作成すればよいわけです。

この手のことは例を見たほうが早いでしょうから、以下に C 拡張モジュール custom にある Custom という名前の新しい型を定義する、最小限ながら完全なモジュールをあげておきます:

注釈

ここで紹介している例は、 静的な 拡張の型を定義する伝統的な実装方法です。 これはほとんどの場面で十分なものなのです。 C API では、 PyType_FromSpec() 関数を使い、ヒープ上に配置された拡張の型も定義できますが、これについてはこのチュートリアルでは扱いません。

#include <Python.h>

typedef struct {
    PyObject_HEAD
    /* Type-specific fields go here. */
} CustomObject;

static PyTypeObject CustomType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom.Custom",
    .tp_doc = "Custom objects",
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT,
    .tp_new = PyType_GenericNew,
};

static PyModuleDef custommodule = {
    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);
    PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
    return m;
}

一度に把握するにはちょっと量が多いですが、前の章よりはとっつきやすくなっていることと重います。このファイルでは、3つの要素が定義されています:

  1. Custom オブジェクト が何を含んでいるか: これが CustomObject 構造体で、 Custom インスタンスごとに1回だけメモリ確保が行われます。
  2. Custom 型 がどのように振る舞うか: これが CustomType 構造体で、フラグと関数ポインタの集まりを定義しています。特定の操作が要求されたときに、この関数ポインタをインタプリタが見に行きます。
  3. custom モジュールをどう初期化するか: これが PyInit_custom 関数とそれに関係する custommodule 構造体です。

まず最初はこれです:

typedef struct {
    PyObject_HEAD
} CustomObject;

これが Custom オブジェクトの内容です。 PyObject_HEAD はそれぞれのオブジェクト構造体の先頭に必須なもので、 PyObject 型の ob_base という名前のフィールドを定義します。 PyObject 型には (それぞれ Py_REFCNT マクロおよび Py_TYPE マクロからアクセスできる) 型オブジェクトへのポインタと参照カウントが格納されています。 このマクロが用意されている理由は、構造体のレイアウトを抽象化し、デバッグビルドでフィールドを追加できるようにするためです。

注釈

上の例では PyObject_HEAD マクロの後にセミコロンはありません。 うっかりセミコロンを追加しないように気を付けてください: これを警告するコンパイラもあります。

もちろん、一般的にはオブジェクトは標準的な PyObject_HEAD ボイラープレートの他にもデータを保持しています; 例えば、これは Python 標準の浮動小数点数の定義です:

typedef struct {
    PyObject_HEAD
    double ob_fval;
} PyFloatObject;

2つ目は型オブジェクトの定義です。

static PyTypeObject CustomType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom.Custom",
    .tp_doc = "Custom objects",
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_new = PyType_GenericNew,
};

注釈

上にあるように C99 スタイルの指示付き初期化子を使って、 PyTypeObject の特に関心の無いフィールドまで全て並べたり、フィールドを宣言する順序に気を使ったりせずに済ませるのをお薦めします。

object.h にある実際の PyTypeObject の定義には上の定義にあるよりももっと多くの フィールド があります。 ここに出てきていないフィールドは C コンパイラによってゼロで埋められるので、必要でない限り明示的には値の指定をしないのが一般的な作法になっています。

一度に1つずつフィールドを取り上げていきましょう:

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

型の名前が、モジュール名とモジュールにおける型の名前の両方をドットでつないだ名前になっていることに注意してください。 この場合は、モジュールは custom で型は Custom なので、型の名前を custom.Custom に設定しました。 実際のドット付きのインポートパスを使うのは、 pydoc モジュールや pickle モジュールと互換性を持たせるために重要なのです。

.tp_basicsize = sizeof(CustomObject),
.tp_itemsize = 0,

tp_basicsize は、新しい Custom インスタンスを作るとき Python が割り当てるべきメモリがどのくらいなのかを知るためのものです。 tp_itemsize は可変サイズのオブジェクトでのみ使うものなので、サイズが可変でないオブジェクトでは 0 にすべきです。

注釈

あなたのタイプを Python でサブクラス化可能にしたい場合、そのタイプが基底タイプと同じ tp_basicsize をもっていると多重継承のときに問題が生じることがあります。そのタイプを Python のサブクラスにしたとき、その __bases__ リストにはあなたのタイプが最初にくるようにしなければなりません。さもないとエラーの発生なしにあなたのタイプの __new__() メソッドを呼び出すことはできなくなります。この問題を回避するには、つねにあなたのタイプの tp_basicsize をその基底タイプよりも大きくしておくことです。ほとんどの場合、あなたのタイプは object か、そうでなければ基底タイプにデータ用のメンバを追加したものでしょうから、したがって大きさはつねに増加するためこの条件は満たされています。

Py_TPFLAGS_DEFAULT にクラスフラグを設定します。

.tp_flags = Py_TPFLAGS_DEFAULT,

すべての型はフラグにこの定数を含めておく必要があります。これは最低でも Python 3.3 までに定義されているすべてのメンバを許可します。それ以上のメンバが必要なら、対応するフラグの OR をとる必要があります。

この型の docstring は tp_doc に入れます。

.tp_doc = "Custom objects",

オブジェクトが生成できるように、 tp_new ハンドラを提供する必要があります。 これは Python のメソッド __new__() と同等のものですが、明示的に与える必要があります。 今の場合では、 API 関数の PyType_GenericNew() として提供されるデフォルトをそのまま使えます。

.tp_new = PyType_GenericNew,

ファイルの残りの部分はきっと馴染みやすいものだと思いますが、 PyInit_custom() の一部のコードはそうではないでしょう:

if (PyType_Ready(&CustomType) < 0)
    return;

これは、 NULL に初期化された ob_type も含めて、いくつかのメンバーを適切なデフォルト値で埋めて、 Custom 型を初期化します。

PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);

これは型をモジュールの辞書に追加します。 こうすることで Custom クラスの呼び出しで Custom インスタンスが作成できるようになります:

>>> import custom
>>> mycustom = custom.Custom()

以上です! 残りの作業はビルドだけです; custom.c という名前のファイルにここまでのコードを書き込み、次の内容を持つ setup.py を用意します:

from distutils.core import setup, Extension
setup(name="custom", version="1.0",
      ext_modules=[Extension("custom", ["custom.c"])])

そして、シェルから以下のように入力します

$ python setup.py build

at a shell should produce a file custom.so in a subdirectory; move to that directory and fire up Python --- you should be able to import custom and play around with Custom objects.

そんなにむずかしくありません、よね?

Of course, the current Custom type is pretty uninteresting. It has no data and doesn't do anything. It can't even be subclassed.

注釈

While this documentation showcases the standard distutils module for building C extensions, it is recommended in real-world use cases to use the newer and better-maintained setuptools library. Documentation on how to do this is out of scope for this document and can be found in the Python Packaging User's Guide.

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:

#include <Python.h>
#include "structmember.h"

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, *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;
}

static PyMemberDef Custom_members[] = {
    {"first", T_OBJECT_EX, offsetof(CustomObject, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(CustomObject, last), 0,
     "last name"},
    {"number", 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 = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom2.Custom",
    .tp_doc = "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 = {
    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;

    Py_INCREF(&CustomType);
    PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
    return m;
}

このバージョンでは、いくつもの変更をおこないます。

以下の include を追加します:

#include <structmember.h>

すこしあとでふれますが、この include には属性を扱うための宣言が入っています。

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.

注釈

The explicit cast to destructor above is needed because we defined Custom_dealloc to take a CustomObject * argument, but the tp_dealloc function pointer expects to receive a PyObject * argument. Otherwise, the compiler will emit a warning. This is object-oriented polymorphism, in C!

We want to make sure that the first and last names are initialized to empty strings, so we provide a tp_new implementation:

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 shouldn't call tp_init explicitly, as the interpreter will do it itself.

The tp_new implementation calls the tp_alloc slot to allocate memory:

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.

注釈

もし協力的な tp_new (基底タイプの tp_new または __new__() を呼んでいるもの) を作りたいのならば、実行時のメソッド解決順序をつかってどのメソッドを呼びだすかを決定しようとしては いけません 。つねに呼び出す型を静的に決めておき、直接その tp_new を呼び出すか、あるいは type->tp_base->tp_new を経由してください。こうしないと、あなたが作成したタイプの Python サブクラスが他の Python で定義されたクラスも継承している場合にうまく動かない場合があります。 (とりわけ、そのようなサブクラスのインスタンスを 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?

  • when we absolutely know that the reference count is greater than 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", T_OBJECT_EX, offsetof(CustomObject, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(CustomObject, last), 0,
     "last name"},
    {"number", 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.

この方法の欠点は、Python 属性に代入できるオブジェクトの型を制限する方法がないことです。ここではファーストネーム first とラストネーム last に、ともに文字列が入るよう期待していますが、今のやり方ではどんな Python オブジェクトも代入できてしまいます。加えてこの属性は削除 (del) できてしまい、その場合、 C のポインタには NULL が設定されます。たとえもしメンバが NULL 以外の値に初期化されるようにしてあったとしても、属性が削除されればメンバは NULL になってしまいます。

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)
{
    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)

first メンバと last メンバがそれぞれ NULL かどうかチェックしなければならないことに注意してください。これらは削除される可能性があり、その場合値は NULL にセットされます。この属性の削除を禁止して、そこに入れられる値を文字列に限定できればなおいいでしょう。次の節ではこれについて扱います。

さて、メソッドを定義したので、ここでメソッド定義用の配列を作成する必要があります:

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 build the new module:

from distutils.core import setup, Extension
setup(name="custom", version="1.0",
      ext_modules=[
         Extension("custom", ["custom.c"]),
         Extension("custom2", ["custom2.c"]),
         ])

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.

#include <Python.h>
#include "structmember.h"

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, *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;
}

static PyMemberDef Custom_members[] = {
    {"number", T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

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;
}

static PyObject *
Custom_getlast(CustomObject *self, void *closure)
{
    Py_INCREF(self->last);
    return self->last;
}

static int
Custom_setlast(CustomObject *self, PyObject *value, void *closure)
{
    PyObject *tmp;
    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;
    }
    tmp = self->last;
    Py_INCREF(value);
    self->last = value;
    Py_DECREF(tmp);
    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 = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom3.Custom",
    .tp_doc = "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 = {
    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;

    Py_INCREF(&CustomType);
    PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
    return m;
}

first 属性と last 属性をよりこまかく制御するためには、カスタムメイドの getter 関数と setter 関数を使います。以下は first 属性から値を取得する関数 (getter) と、この属性に値を格納する関数 (setter) です:

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", 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;
}

これらの変更によって、first メンバと last メンバが決して NULL にならないと保証できました。これでほとんどすべてのケースから NULL 値のチェックを除けます。これは多くの Py_XDECREF() 呼び出しを Py_DECREF() 呼び出しに変えられることを意味します。唯一これを変えられないのは tp_dealloc の実装中で、なぜならそこでは tp_new でのメンバ初期化が失敗している可能性があるからです。

さて、先ほどもしたように、このモジュール初期化関数と初期化関数内にあるモジュール名を変更しましょう。そして setup.py ファイルに追加の定義をくわえます。

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

Python は:term:`循環ガベージコレクタ(GC)機能<garbage collection> `をもっており、これは不要なオブジェクトを、たとえ参照カウントがゼロでなくても発見することができます。そのような状況はオブジェクトの参照が循環しているときに起こりえます。たとえば以下の例を考えてください:

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

#include <Python.h>
#include "structmember.h"

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, *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;
}

static PyMemberDef Custom_members[] = {
    {"number", T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

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)
{
    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_INCREF(value);
    Py_CLEAR(self->first);
    self->first = value;
    return 0;
}

static PyObject *
Custom_getlast(CustomObject *self, void *closure)
{
    Py_INCREF(self->last);
    return 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_INCREF(value);
    Py_CLEAR(self->last);
    self->last = 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 = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom4.Custom",
    .tp_doc = "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 = {
    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;

    Py_INCREF(&CustomType);
    PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
    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;
}

循環した参照に含まれるかもしれない各内部オブジェクトに対して、 traversal メソッドに渡された visit() 関数を呼びます。 visit() 関数は内部オブジェクトと、traversal メソッドに渡された追加の引数 arg を引数としてとります。この関数はこの値が非負の場合に返される整数の値を返します。

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);
}

最後に、 Py_TPFLAGS_HAVE_GC フラグをクラス定義のフラグに加えます:

.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,

これで完了です。 tp_alloc スロットまたは tp_free ハンドラが書かれていれば、それらを循環ガベージコレクションに使えるよう修正すればよいのです。ほとんどの拡張機能は自動的に提供されるバージョンを使うでしょう。

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

既存の型を継承した新しい拡張型を作成することができます。組み込み型から継承するのは特に簡単です。必要な PyTypeObject を簡単に利用できるからです。それに比べて、 PyTypeObject 構造体を拡張モジュール間で共有するのは難しいです。

次の例では、ビルトインの list 型を継承した SubList 型を作成しています。新しい型は通常のリスト型と完全に互換性がありますが、追加で内部のカウンタを増やす increment() メソッドを持っています:

>>> import sublist
>>> s = sublist.SubList(range(3))
>>> s.extend(s)
>>> print(len(s))
6
>>> print(s.increment())
1
>>> print(s.increment())
2

#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 = "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);
    PyModule_AddObject(m, "SubList", (PyObject *) &SubListType);
    return m;
}

見てわかるように、ソースコードは前の節の Custom の時と非常に似ています。違う部分をそれぞれを見ていきます。

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);
    PyModule_AddObject(m, "SubList", (PyObject *) &SubListType);
    return m;
}

PyType_Read() を呼ぶ前に、型の構造体の tp_base スロットは埋められていなければなりません。既存の型を継承する際には、 tp_alloc スロットを PyType_GenericNew() で埋める必要はありません。 -- 基底型のアロケーション関数が継承されます。

この後は、 PyType_Ready() 関数を呼び、タイプオブジェクトをモジュールへ追加するのは、基本的な Custom の例と同じです。

脚注

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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python インタプリタの拡張と埋め込み »


3. Defining Extension Types: Assorted Topics

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python インタプリタの拡張と埋め込み »

3. Defining Extension Types: Assorted Topics

この節ではさまざまな実装可能なタイプメソッドと、それらが何をするものであるかについて、ざっと説明します。

以下は PyTypeObject の定義です。デバッグビルドでしか使われないいくつかのメンバは省いてあります:

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;
    printfunc tp_print;
    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 */

    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* 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;
    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;

} 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(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_CallObject(self->my_callback, NULL);
        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 で新しいファイナライズの仕組みが説明されています。

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);
}

tp_repr ハンドラが指定されていなければ、インタプリタはその型の tp_name とそのオブジェクトの一意な識別値をもちいて文字列表現を作成します。

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. 属性を管理する

属性をもつどのオブジェクトに対しても、その型は、それらオブジェクトの属性をどのように解決するか制御する関数を提供する必要があります。必要な関数としては、属性を (それが定義されていれば) 取り出すものと、もうひとつは属性に (それが許可されていれば) 値を設定するものです。属性を削除するのは特殊なケースで、この場合は新しい値としてハンドラに NULL が渡されます。

Python は 2つの属性ハンドラの組をサポートしています。属性をもつ型はどちらか一組を実装するだけでよく、それらの違いは一方の組が属性の名前を char* として受け取るのに対してもう一方の組は属性の名前を PyObject* として受け取る、というものです。それぞれの型はその実装にとって都合がよい方を使えます。

getattrfunc  tp_getattr;        /* char * version */
setattrfunc  tp_setattr;
/* ... */
getattrofunc tp_getattro;       /* PyObject * version */
setattrofunc tp_setattro;

オブジェクトの属性へのアクセスがつねに (すぐあとで説明する) 単純な操作だけならば、 PyObject* を使って属性を管理する関数として、総称的 (generic) な実装を使えます。特定の型に特化した属性ハンドラの必要性は Python 2.2 からほとんど完全になくなりました。しかし、多くの例はまだ、この新しく使えるようになった総称的なメカニズムを使うよう更新されてはいません。

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

ほとんどの型は 単純な 属性を使うだけです。では、どのような属性が単純だといえるのでしょうか? それが満たすべき条件はごくわずかです:

  1. PyType_Ready() が呼ばれたとき、すでに属性の名前がわかっていること。
  2. 属性を参照したり設定したりするときに、特別な記録のための処理が必要でなく、また参照したり設定した値に対してどんな操作も実行する必要がないこと。

これらの条件は、属性の値や、値が計算されるタイミング、または格納されたデータがどの程度妥当なものであるかといったことになんら制約を課すものではないことに注意してください。

PyType_Ready() が呼ばれると、これはそのタイプオブジェクトに参照されている 3つのテーブルを使って、そのタイプオブジェクトの辞書中にデスクリプタ(descriptor) を作成します。各デスクリプタは、インスタンスオブジェクトの属性に対するアクセスを制御します。それぞれのテーブルはなくてもかまいません。もしこれら 3つがすべて NULL だと、その型のインスタンスはその基底型から継承した属性だけを持つことになります。また、 tp_getattro および tp_setattro が NULL のままだった場合も、基底型にこれらの属性の操作がまかせられます。

テーブルはタイプオブジェクト中の 3つのメンバとして宣言されています:

struct PyMethodDef *tp_methods;
struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset;

tp_methods が NULL でない場合、これは PyMethodDef 構造体への配列を指している必要があります。テーブル中の各エントリは、つぎのような構造体のインスタンスです:

typedef struct PyMethodDef {
    const char  *ml_name;       /* method name */
    PyCFunction  ml_meth;       /* implementation function */
    int          ml_flags;      /* flags */
    const char  *ml_doc;        /* docstring */
} PyMethodDef;

その型が提供する各メソッドについてひとつのエントリを定義する必要があります。基底型から継承してきたメソッドについてはエントリは必要ありません。これの最後には、配列の終わりを示すための見張り番 (sentinel) として追加のエントリがひとつ必要です。この場合、 ml_name メンバが sentinel として使われ、その値は NULL でなければなりません。

2番目のテーブルは、インスタンス中に格納されるデータと直接対応づけられた属性を定義するのに使います。いくつもの C の原始的な型がサポートされており、アクセスを読み出し専用にも読み書き可能にもできます。このテーブルで使われる構造体は次のように定義されています:

typedef struct PyMemberDef {
    const char *name;
    int         type;
    int         offset;
    int         flags;
    const char *doc;
} PyMemberDef;

このテーブルの各エントリに対してデスクリプタ(descriptor)が作成され、値をインスタンスの構造体から抽出しうる型に対してそれらが追加されます。 type メンバは structmember.h ヘッダで定義された型のコードをひとつ含んでいる必要があります。この値は Python における値と C における値をどのように変換しあうかを定めるものです。 flags メンバはこの属性がどのようにアクセスされるかを制御するフラグを格納するのに使われます。

以下のフラグ用定数は structmember.h で定義されており、これらはビットごとの OR を取って組み合わせられます。

定数 | 意味
READONLY | 絶対に変更できない。
READ_RESTRICTED | 制限モード (restricted mode) では参照できない。
WRITE_RESTRICTED | 制限モード (restricted mode) では変更できない。
RESTRICTED | 制限モード (restricted mode) では参照も変更もできない。

tp_members を使ったひとつの面白い利用法は、実行時に使われるデスクリプタを作成しておき、単にテーブル中にテキストを置いておくことによって、この方法で定義されたすべての属性に doc string を関連付けられるようにすることです。アプリケーションはこのイントロスペクション用 API を使って、クラスオブジェクトからデスクリプタを取り出し、その __doc__ 属性を使って doc string を得られます。

tp_methods テーブルと同じように、ここでも name メンバの値を NULL にした見張り用エントリが必要です。

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

話を単純にするため、ここでは char* を使ったバージョンのみを示します。name パラメータの型はインターフェイスとして char* を使うか PyObject* を使うかの違いしかありません。この例では、上の総称的な例と同じことを効率的にやりますが、 Python 2.2 で追加された総称的な型のサポートを使わずにやります。これはハンドラの関数がどのようにして呼ばれるのかを説明します。これで、たとえその機能を拡張する必要があるとき、何をどうすればいいかわかるでしょう。

tp_getattr ハンドラはオブジェクトが属性への参照を要求するときに呼ばれます。これは、そのクラスの __getattr__() メソッドが呼ばれるであろう状況と同じ状況下で呼び出されます。

以下に例を示します。:

static PyObject *
newdatatype_getattr(newdatatypeobject *obj, char *name)
{
    if (strcmp(name, "data") == 0)
    {
        return PyLong_FromLong(obj->data);
    }

    PyErr_Format(PyExc_AttributeError,
                 "'%.50s' object has no attribute '%.400s'",
                 tp->tp_name, name);
    return NULL;
}

tp_setattr ハンドラは、クラスのインスタンスの __setattr__() または __delattr__() メソッドが呼ばれるであろう状況で呼び出されます。ある属性が削除されるとき、3番目のパラメータは NULL になります。以下の例はたんに例外を発生させるものですが、もし本当にこれと同じことをしたいなら、 tp_setattr ハンドラを 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;

tp_richcompare ハンドラは比較処理が要求されたときに呼び出されます。 __lt__() のような 拡張比較メソッド に類似しており、 PyObject_RichCompare() と PyObject_RichCompareBool() からも呼び出されます。

この関数は 2 つの Python オブジェクトと演算子を引数に取り、演算子は Py_EQ, Py_NE, Py_LE, Py_GT, Py_LT, Py_GT のどれか 1 つです。関数は指定された演算子に従って 2 つのオブジェクトを比較し、比較に成功した場合の Py_True および Py_False か、比較処理が実装されておらず、もう一方のオブジェクトの比較処理を試行することを示す Py_NotImplemented か、例外が設定された場合の NULL のいづれかを返します。

これは内部ポインタのサイズが等しければ等しいと見なすデータ型のサンプル実装です:

static PyObject *
newdatatype_richcmp(PyObject *obj1, PyObject *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) で解説されています。

これら多数の抽象的なインターフェイスは、Python の実装が開発される初期の段階で定義されていました。とりわけ数値や辞書、そしてシーケンスなどのプロトコルは最初から Python の一部だったのです。それ以外のプロトコルはその後追加されました。型の実装にあるいくつかのハンドラルーチンに依存するようなプロトコルのために、古いプロトコルはハンドラの入ったオプションのブロックとして定義し、型オブジェクトから参照するようになりました。タイプオブジェクトの主部に追加のスロットをもつ新しいプロトコルについては、フラグ用のビットを立てることでそれらのスロットが存在しており、インタプリタがチェックすべきであることを指示できます。(このフラグ用のビットは、そのスロットの値が非 NULL であることを示しているわけではありません。フラグはスロットの存在を示すのに使えますが、そのスロットはまだ埋まっていないかもしれないのです。)

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つの引数をとります:

  1. self は呼び出しの対象となるデータ型のインスタンスです。 たとえば呼び出しが obj1('hello') の場合、self は obj1 になります。
  2. args は呼び出しの引数を格納しているタプルです。ここから引数を取り出すには PyArg_ParseTuple() を使います。
  3. kwds はキーワード引数のための辞書です。これが NULL でなく、キーワード引数をサポートしている場合は、 PyArg_ParseTupleAndKeywords() をつかって引数を取り出せます。キーワード引数をサポートしていないのにこれが NULL でない場合は、キーワード引数はサポートしていない旨のメッセージとともに TypeError を発生させてください。

以下は tp_call の簡易な実装です:

static PyObject *
newdatatype_call(newdatatypeobject *self, 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 do two things:

  1. Include a PyObject* field in the C object structure dedicated to the weak reference mechanism. The object's constructor should leave it NULL (which is automatic when using the default tp_alloc).
  2. Set the tp_weaklistoffset type member to the offset of the aforementioned field in the C object structure, so that the interpreter knows how to access and modify that field.

Concretely, here is how a trivial object structure would be augmented with the required field:

typedef struct {
    PyObject_HEAD
    PyObject *weakreflist;  /* List of weak references */
} TrivialObject;

And the corresponding member in the statically-declared type object:

static PyTypeObject TrivialType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    /* ... other members omitted for brevity ... */
    .tp_weaklistoffset = offsetof(TrivialObject, weakreflist),
};

The only further addition is that tp_dealloc needs to clear any weak references (by calling PyObject_ClearWeakRefs()) if the field is non-NULL:

static void
Trivial_dealloc(TrivialObject *self)
{
    /* Clear weakrefs first before calling any destructors */
    if (self->weakreflist != NULL)
        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

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python インタプリタの拡張と埋め込み »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python インタプリタの拡張と埋め込み »

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

CPython の C 拡張は 初期化関数 をエクスポートした共有ライブラリ (例、 Linux の .so ファイルや Windows の .pyd ファイル) です。

インポートできるように、共有ライブラリは使える状態で PYTHONPATH 上になければならず、ファイル名をモジュール名に揃え、適切な拡張子になっていなければいけません。 distutils を使っているときは、自動的に正しいファイル名が生成されます。

初期化関数のシグネチャは次のとおりです:

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 の "Multiple modules in one library" 節を参照してください。

4.1. distutils による C および C++ 拡張モジュールのビルド

拡張モジュールは Python に含まれる distutils を使ってビルドできます。 distutils はバイナリパッケージの作成もサポートしているので、ユーザが拡張モジュールをインストールする際に、必ずしもコンパイラや distutils が必要というわけではありません。

distutils ベースのパッケージには、駆動スクリプト (driver script) となる setup.py が入っています。 setup.py は普通の Python プログラムファイルで、ほとんどの場合以下のような内容になっています:

from distutils.core import setup, Extension

module1 = Extension('demo',
                    sources = ['demo.c'])

setup (name = 'PackageName',
       version = '1.0',
       description = 'This is a demo package',
       ext_modules = [module1])

この setup.py とファイル demo.c があるとき、以下のコマンド

python setup.py build

を実行すると、 demo.c をコンパイルして、 demo という名前の拡張モジュールを build ディレクトリ内に生成します。システムによってはモジュールファイルは build/lib.system サブディレクトリに生成され、 demo.so や demo.pyd といった名前になることがあります。

setup.py 内では、コマンドの実行はすべて setup 関数を呼び出して行います。 この関数は可変個のキーワード引数を取ります。上の例ではその一部を使っているにすぎません。 もっと具体的にいうと、この例の中ではパッケージをビルドするためのメタ情報と、パッケージの内容を指定しています。 通常、パッケージには Python ソースモジュールやドキュメント、サブパッケージ等といった別のモジュールも入ります。 distutils の機能に関する詳細は、 Python モジュールの配布 (レガシーバージョン) に書かれている distutils のドキュメントを参照してください; この節では拡張モジュールのビルドについてのみ説明します。

駆動スクリプトの構成をよりよくするために、 setup() への引数を前もって計算しておくことがよくあります。 上の例では、 setup() の ext_modules は拡張モジュールのリストで、リストの各々の要素は Extension クラスのインスタンスになっています。 上の例では、 demo という名の拡張モジュールを定義していて、単一のソースファイル demo.c をコンパイルしてビルドするよう定義しています。

多くの場合、拡張モジュールのビルドはもっと複雑になります。 というのは、プリプロセッサ定義やライブラリの追加指定が必要になることがあるからです。 例えば以下のファイルがその実例です。

from distutils.core import setup, Extension

module1 = Extension('demo',
                    define_macros = [('MAJOR_VERSION', '1'),
                                     ('MINOR_VERSION', '0')],
                    include_dirs = ['/usr/local/include'],
                    libraries = ['tcl83'],
                    library_dirs = ['/usr/local/lib'],
                    sources = ['demo.c'])

setup (name = 'PackageName',
       version = '1.0',
       description = 'This is a demo package',
       author = 'Martin v. Loewis',
       author_email = 'martin@v.loewis.de',
       url = 'https://docs.python.org/extending/building',
       long_description = '''
This is really just a demo package.
''',
       ext_modules = [module1])

この例では、メタ情報が追加された状態で setup() が呼び出されていますが、配布パッケージを構築するにあたっては、メタ情報を付けておくことが推奨されます。 拡張モジュール自体についてのメタ情報には、プリプロセッサ定義、インクルードファイルのディレクトリ、ライブラリのディレクトリ、ライブラリといった指定があります。 distutils はこの情報をコンパイラに応じて異なるやり方で引渡します。 例えば Unix では、上の設定は以下のようなコンパイルコマンドになるかもしれません

gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o

gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so

これらのコマンドラインは実演目的で書かれたものです; distutils のユーザは distutils が正しくコマンドを実行すると信用してください。

4.2. 拡張モジュールの配布

拡張モジュールをうまくビルドできたら、三通りの使い方があります。

エンドユーザは普通モジュールをインストールしようと考えます; これには、次を実行します

python setup.py install

モジュールメンテナはソースパッケージを作成します; これには、次を実行します

python setup.py sdist

場合によってはソース配布物に追加のファイルを含める必要があります; これには MANIFEST.in ファイルを使います; 詳しくは 配布するファイルを指定する を参照してください。

ソースコード配布物をうまく構築できたら、メンテナはバイナリ配布物も作成できます。プラットフォームに応じて、以下のコマンドのいずれかを使います。

python setup.py bdist_wininst
python setup.py bdist_rpm
python setup.py bdist_dumb

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python インタプリタの拡張と埋め込み »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python インタプリタの拡張と埋め込み »

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 スクリプトを実行するためのものです。例えばこれは、一つのファイル上で何らかの操作を実現するのに利用できます。

#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;
}

Py_SetProgramName() は Py_Initialize() の前に呼び出す必要があります。これによりインタプリタにランタイムライブラリへのパスを伝えることが出来ます。続いて、Python インタプリタを Py_Initialize() で初期化し、続いてハードコードされた Python スクリプトで日付と時間の出力を実行します。その後、 Py_FinalizeEx() の呼び出しでインタプリタを終了し, プログラムの終了に続きます。実際のプログラムでは、Python スクリプトを他のソース、おそらくテキストエディタルーチンやファイル、データベースから取り出したいと考えるかもしれません。Python コードをファイルから取り出すには、 PyRun_SimpleFile() 関数を使うのがよいでしょう。この関数はメモリを確保して、ファイルの内容をロードする手間を省いてくれます。

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

高水準インタフェースは、断片的な Python コードをアプリケーションから実行できるようにしてくれますが、アプリケーションと Python コードの間でのデータのやり取りは、控えめに言っても煩わしいものです。データのやり取りをしたいなら、より低水準のインタフェース呼び出しを利用しなくてはなりません。より多く C コードを書かねばならない代わりに、ほぼ何でもできるようになります。

Python の拡張と埋め込みは、趣旨こそ違え、同じ作業であるということに注意せねばなりません。これまでの章で議論してきたトピックのほとんどが埋め込みでもあてはまります。これを示すために、 Python から C への拡張を行うコードが実際には何をするか考えてみましょう:

  1. データ値を Python から C に変換する。
  2. 変換された値を使って C ルーチンの関数呼び出しを行い、
  3. 呼び出しで得られたデータ値 C から Python に変換する。

Python を埋め込む場合には、インタフェースコードが行う作業は以下のようになります:

  1. データ値を C から Python に変換する。
  2. 変換された値を使って Python インタフェースルーチンの関数呼び出しを行い、
  3. 呼び出しで得られたデータ値 Python から C に変換する。

一見して分かるように、データ変換のステップは、言語間でデータを転送する方向が変わったのに合わせて単に入れ替えただけです。唯一の相違点は、データ変換の間にあるルーチンです。拡張を行う際には C ルーチンを呼び出しますが、埋め込みの際には Python ルーチンを呼び出します。

この章では、Python から C へ、そしてその逆へとデータを変換する方法については議論しません。また、正しい参照の使い方やエラーの扱い方についてすでに理解しているものと仮定します。これらの側面についてはインタプリタの拡張と何ら変わるところがないので、必要な情報については以前の章を参照できます。

1.3. 純粋な埋め込み

最初に例示するプログラムは、Python スクリプト内の関数を実行するためのものです。超高水準インタフェースに関する節で挙げた例と同様に、Python インタプリタはアプリケーションと直接やりとりはしません (が、次の節でやりとりするよう変更します)。

Python スクリプト内で定義されている関数を実行するためのコードは以下のようになります:

#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);

これら二つの行は numargs 変数を初期化し、埋め込み Python インタプリタから emb.numargs() 関数にアクセスできるようにします。これらの拡張モジュール関数を使うと、 Python スクリプトは以下のようなことができます。

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.4-config --cflags
-I/opt/include/python3.4m -I/opt/include/python3.4m -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes

  • pythonX.Y-config --ldflags は推奨のリンクオプションを出力します:

    $ /opt/bin/python3.4-config --ldflags
-L/opt/lib/python3.4/config-3.4m -lpthread -ldl -lutil -lm -lpython3.4m -Xlinker -export-dynamic

注釈

複数 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 インタプリタの拡張と埋め込み »


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

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

このマニュアルでは、拡張モジュールを書いたり Python インタプリタをアプリケーションに埋め込んだりしたい C/C++ プログラマが利用できる API について述べています。 Python インタプリタの拡張と埋め込み は拡張モジュールを書く際の一般的な決まりごとについて記述していますが、 API の詳細までは記述していないので、このドキュメントが手引きになります。

  • はじめに
    • コーディング基準
    • インクルードファイル
    • 便利なマクロ
    • オブジェクト、型および参照カウント
    • 例外
    • Python の埋め込み
    • デバッグ版ビルド (Debugging Builds)
  • 安定 ABI (Stable Appliction Binary Interface)
  • 超高水準レイヤ
  • 参照カウント
  • 例外処理
    • 出力とクリア
    • 例外の送出
    • 警告
    • エラーインジケータの問い合わせ
    • シグナルハンドリング
    • 例外クラス
    • 例外オブジェクト
    • Unicode 例外オブジェクト
    • 再帰の管理
    • 標準例外
    • Standard Warning Categories
  • ユーティリティ
    • オペレーティングシステム関連のユーティリティ
    • システム関数
    • プロセス制御
    • モジュールのインポート
    • データ整列化 (data marshalling) のサポート
    • 引数の解釈と値の構築
    • 文字列の変換と書式化
    • リフレクション
    • codec レジストリとサポート関数
  • 抽象オブジェクトレイヤ (abstract objects layer)
    • オブジェクトプロトコル (object protocol)
    • 数値型プロトコル (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)
    • スレッドローカルストレージのサポート
  • メモリ管理
    • 概要
    • 生メモリインタフェース
    • メモリインタフェース
    • Object allocators
    • Default Memory Allocators
    • メモリアロケータをカスタマイズする
    • pymalloc アロケータ
    • tracemalloc C API
    • 使用例
  • オブジェクト実装サポート (object implementation support)
    • オブジェクトをヒープ上にメモリ確保する
    • 共通のオブジェクト構造体 (common object structure)
    • 型オブジェクト
    • 数値オブジェクト構造体
    • マップオブジェクト構造体
    • シーケンスオブジェクト構造体
    • バッファオブジェクト構造体 (buffer object structure)
    • async オブジェクト構造体
    • 循環参照ガベージコレクションをサポートする
  • API と ABI のバージョニング

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


安定 ABI (Stable Appliction Binary Interface)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

安定 ABI (Stable Appliction Binary Interface)

伝統的に Python の C API はリリース毎に変更されます。多くの変更はソース互換性を保っていて、既存の API を変更したり取り除いたりすることはありません (ただし、いくつかの API は、一旦非推奨と指定された後に、削除されます)。

残念ながら API の互換性はバイナリレベルの互換性 (ABI) までには適用されません。その理由は主に、構造体フィールドの新規追加や型の変更によって、たとえ API は壊れなくても ABI は壊れてしまうからです。その結果として、拡張モジュールを Python のリリース毎に再コンパイルする必要があります (Unix でその影響を受けるインターフェイスが使用されていない場合は例外かもしれませんが)。また、 Windows では、何らかの pythonXY.dll とリンクしている拡張モジュールは、再コンパイルした後に新しい dll とリンクし直す必要があります。

Python 3.2 以降では、安定 ABI を保証するための API サブセットが宣言されています。拡張モジュールでこのAPI ("limited API" と呼ばれます) を使うには Py_LIMITED_API を定義してください。拡張モジュールの細部は大部分隠蔽され、代わりに再コンパイルなしにバージョン 3.x (x>=2) 上で動くモジュールがビルドされます。

いくつかのケースでは、安定 ABI を新しい関数で拡張する必要があります。これらの新しい API を使用したい拡張モジュールは、 Py_LIMITED_API にサポートしたい最小の Python バージョンの PY_VERSION_HEX の値 (API と ABI のバージョニング を参照) を設定してください。 (例えば Python3.3 なら 0x03030000)。 モジュールは後続のすべての Pythonリリースで動作しますが、 (シンボルが存在しないため) 古いリリースでは動作しません。

Python 3.2 からは limited API は PEP 384 に文書化されています。 C API のドキュメントでは、 limited API の一部でない API は、 "Not part of the limited API" とマークされています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


超高水準レイヤ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

超高水準レイヤ

この章の関数を使うとファイルまたはバッファにある Python ソースコードを実行できますが、より詳細なやり取りをインタプリタとすることはできないでしょう。

これらの関数のいくつかは引数として文法の開始記号を受け取ります。使用できる開始記号は Py_eval_input と Py_file_input 、 Py_single_input です。開始記号の説明はこれらを引数として取る関数の後にあります。

これらの関数のいくつかが FILE* 引数をとることにも注意してください。注意深く扱う必要がある特別な問題の1つは、異なるCライブラリの FILE 構造体は異なっていて互換性がない可能性があるということです。実際に(少なくとも)Windowsでは、動的リンクされる拡張が異なるライブラリを使うことが可能であり、したがって、 FILE* 引数がPythonランタイムが使っているライブラリと同じライブラリによって作成されたことが確かならば、単にこれらの関数へ渡すだけということに注意すべきです。

int Py_Main(int argc, wchar_t **argv)

標準インタプリタのためのメインプログラム。Pythonを組み込むプログラムのためにこれを利用できるようにしています。 argc と argv 引数をCプログラムの main() 関数 (ユーザのロケールに従って wchar_t に変換されます) へ渡されるものとまったく同じに作成すべきです。引数リストが変更される可能性があるという点に注意することは重要です。 (しかし、引数リストが指している文字列の内容は変更されません)。戻り値はインタプリタが(例外などではなく)普通に終了した時は 0 に、例外で終了したときには 1 に、引数リストが正しい Python コマンドラインが渡されなかったときは 2 になります。

Py_InspectFlag が設定されていない場合、未処理の SystemExit 例外が発生すると、この関数は 1 を返すのではなくプロセスを exit することに気をつけてください。

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 ならば、この関数はファイル名として "???" を使います。

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 の意味については、後述します。

Py_InspectFlag が設定されていない場合、未処理の SystemExit 例外が発生すると、この関数は 1 を返すのではなくプロセスを exit することに気をつけてください。

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 はそのファイルの名前でなければならず、ファイルシステムのエンコーディング (sys.getfilesystemencoding()) でデコードされます。 closeit に真を指定した場合は、PyRun_SimpleFileExFlags が処理を戻す前にファイルを閉じます。

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 はファイルシステムのエンコーディング (sys.getfilesystemencoding()) でデコードされます。

入力が正常に実行されたときは 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 はファイルシステムのエンコーディング (sys.getfilesystemencoding()) でデコードされます。 EOFに達すると 0 を返すか、失敗したら負の数を返します。

int (*PyOS_InputHook)(void)

int func(void) というプロトタイプの関数へのポインタが設定できます。 この関数は、 Python のインタプリタのプロンプトがアイドル状態になりターミナルからのユーザの入力を待つようになったときに呼び出されます。 返り値は無視されます。 このフックを上書きすることで、 Python のソースコードの中で Modules/_tkinter.c がやっているように、インタプリタのプロンプトと他のイベントループを統合できます。

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() でメモリ確保したものでなければなりません。

struct _node* PyParser_SimpleParseString(const char *str, int start)

下記の PyParser_SimpleParseStringFlagsFilename() の filename を NULL に、 flags を 0 にして単純化したインタフェースです。

struct _node* PyParser_SimpleParseStringFlags(const char *str, int start, int flags)

下記の PyParser_SimpleParseStringFlagsFilename() の filename を NULL にして単純化したインタフェースです。

struct _node* PyParser_SimpleParseStringFlagsFilename(const char *str, const char *filename, int start, int flags)

開始トークン start を使って str に含まれる Python ソースコードを flags 引数に従ってパースします。効率的に評価可能なコードオブジェ クトを作成するためにその結果を使うことができます。コード断片を何度も評価しなければならない場合に役に立ちます。 filename はファイルシステムエンコーディング (sys.getfilesystemencoding()) でデコードされます。

struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)

下記の PyRun_SimpleParseFileFlags() の flags を 0 にして単純化したインタフェースです。

struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)

PyParser_SimpleParseStringFlagsFilename() に似ていますが、 Pythonソースコードをメモリ内の文字列ではなく fp から読み込みます。 filename はそのファイルの名前でなけれななりません。

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 はそのファイルの名前でなければならず、ファイルシステムのエンコーディング (sys.getfilesystemencoding()) でデコードされます。もし closeit を真にすると、 PyRun_FileExFlags() が処理を戻す前にファイルを閉じます。

PyObject* Py_CompileString(const char *str, const char *filename, int start)
Return value: New reference.

下記の 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)

str 内の Python ソースコードをパースしてコンパイルし、作られたコードオブジェクトを返します。開始トークンは start によって与えられます。これはコンパイル可能なコードを制限するために使うことができ、 Py_eval_input 、 Py_file_input もしくは Py_single_input であるべきです。 filename で指定されるファイル名はコードオブジェクトを構築するために使われ、トレースバックあるいは SyntaxError 例外メッセージに出てくる可能性があります。コードがパースできなかったりコンパイルできなかったりした場合に、これは NULL を返します。

整数 optimize は、コンパイラの最適化レベルを指定します; -1 は、インタプリタの -O オプションで与えられるのと同じ最適化レベルを選びます。明示的なレベルは、 0 (最適化なし、 __debug__ は真)、 1 (assert は取り除かれ、 __debug__ は偽)、 2 (docstring も取り除かれる) です。

バージョン 3.4 で追加.

PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)

Py_CompileStringObject() と似ていますが、 filename はファイルシステムのエンコーディングでデコード (os.fsdecode()) されたバイト文字列です。

バージョン 3.2 で追加.

PyObject* PyEval_EvalCode( PyObject *co, PyObject *globals, PyObject *locals)
Return value: New reference.

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)

Evaluate a precompiled code object, given a particular environment for its evaluation. This environment consists of a dictionary of global variables, a mapping object of local variables, arrays of arguments, keywords and defaults, a dictionary of default values for keyword-only arguments and a closure tuple of cells.

PyFrameObject

フレームオブジェクトを表現するために使われるオブジェクトのC構造体。 この型のフィールドはいつでも変更され得ます。

PyObject* PyEval_EvalFrame( PyFrameObject *f)

実行フレームを評価します。これは PyEval_EvalFrameEx() に対するシンプルなインタフェースで、後方互換性のためのものです。

PyObject* PyEval_EvalFrameEx( PyFrameObject *f, int throwflag)

Python のインタープリタの主要な、直接的な関数です。 この関数には 2000 行ほどあります。 実行フレーム 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 の内容を変更できます。

PyCompilerFlags *flags が NULL の場合、 cf_flags は 0 として扱われ、 from __future__ import による変更は無視されます。

struct PyCompilerFlags {
    int cf_flags;
}
int CO_FUTURE_DIVISION

このビットを flags にセットすると、除算演算子 / は PEP 238 による「真の除算 (true division)」として扱われます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


参照カウント

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

参照カウント

この節のマクロはPythonオブジェクトの参照カウントを管理するために使われます。

void Py_INCREF( PyObject *o)

オブジェクト o に対する参照カウントを一つ増やします。オブジェクトが NULL であってはいけません。それが NULL ではないと確信が持てないならば、 Py_XINCREF() を使ってください。

void Py_XINCREF( PyObject *o)

オブジェクト o に対する参照カウントを一つ増やします。オブジェクトが NULL であってもよく、その場合マクロは何の影響も与えません。

void Py_DECREF( PyObject *o)

オブジェクト o に対する参照カウントを一つ減らします。オブジェクトが NULL であってはいけません。それが NULL ではないと確信が持てないならば、 Py_XDECREF() を使ってください。参照カウントがゼロになったら、オブジェクトの型のメモリ解放関数(NULL であってはならない)が呼ばれます。

警告

(例えば __del__() メソッドをもつクラスインスタンスがメモリ解放されたときに)メモリ解放関数は任意のPythonコードを呼び出すことができます。このようなコードでは例外は伝播しませんが、実行されたコードはすべてのPythonグローバル変数に自由にアクセスできます。これが意味するのは、 Py_DECREF() が呼び出されるより前では、グローバル変数から到達可能などんなオブジェクトも一貫した状態にあるべきであるということです。例えば、リストからオブジェクトを削除するコードは削除するオブジェクトへの参照を一時変数にコピーし、リストデータ構造を更新し、それから一時変数に対して Py_DECREF() を呼び出すべきです。

void Py_XDECREF( PyObject *o)

オブジェクト o への参照カウントを一つ減らします。オブジェクトは NULL でもかまいませんが、その場合マクロは何の影響も与えません。それ以外の場合、結果は Py_DECREF() と同じです。また、注意すべきことも同じです。

void Py_CLEAR( PyObject *o)

o の参照カウントを減らします。オブジェクトは NULL でもよく、その場合このマクロは何も行いません。オブジェクトが NULL でなければ、引数を NULL にした Py_DECREF() と同じ効果をもたらします。このマクロは一時変数を使って、参照カウントをデクリメントする前に引数を NULL にセットしてくれるので、 Py_DECREF() に使うときの警告を気にしなくてすみます。

ガベージコレクション中に追跡される可能性のある変数の参照デクリメントを行うには、このマクロを使うのがよいでしょう。

以下の関数: Py_IncRef(PyObject *o), Py_DecRef(PyObject *o), は、実行時の動的な Python 埋め込みで使われる関数です。これらの関数はそれぞれ Py_XINCREF() および Py_XDECREF() をエクスポートしただけです。

以下の関数やマクロ: _Py_Dealloc(), _Py_ForgetReference(), _Py_NewReference() は、インタプリタのコアの内部においてのみ使用するためのものです。また、グローバル変数 _Py_RefTotal も同様です。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


例外処理

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

例外処理

この章で説明する関数を使うと、 Python の例外の処理や例外の送出ができるようになります。 Python の例外処理の基本をいくらか理解することが大切です。例外は POSIX errno 変数にやや似た機能を果たします: 発生した中で最も新しいエラーの (スレッド毎の) グローバルなインジケータがあります。実行に成功した場合にはほとんどの C API 関数がこれをクリアしませんが、失敗したときにはエラーの原因を示すために設定します。ほとんどの C API 関数はエラーインジケータも返し、通常は関数がポインタを返すことになっている場合は NULL であり、関数が整数を返す場合は -1 です。(例外: PyArg_*() 関数は実行に成功したときに 1 を返し、失敗したときに 0 を返します).

具体的には、エラーインジケータは3つのオブジェクトポインタから構成されます: 例外型、例外値、トレースバックオブジェクトです。 これらのポインタは設定されない場合は NULL でもかまいません (ただし、禁止されている組み合わせもあります。例えば、例外型が NULL の場合は、非 NULL なトレースバックはありません)。

ある関数が呼び出した関数がいくつか失敗したために、その関数が失敗しなければならないとき、一般的にエラーインジケータを設定しません。呼び出した関数がすでに設定しています。エラーを処理して例外をクリアするか、あるいは (オブジェクト参照またはメモリ割り当てのような)それが持つどんなリソースも取り除いた後に戻るかのどちらか一方を行う責任があります。エラーを処理する準備をしていなければ、普通に続けるべきでは ありません。エラーのために戻る場合は、エラーが設定されていると呼び出し元に知らせることが大切です。エラーが処理されていない場合または丁寧に伝えられている場合には、Python/C APIのさらなる呼び出しは意図した通りには動かない可能性があり、不可解な形で失敗するかもしれません。

注釈

エラー識別子は sys.exc_info() の結果 ではありません。エラー識別子はまだ捕捉されていない例外 (したがってまだ伝播します) に対応しているのに対し、 sys.exc_info() の結果は捕捉された後の例外を返します (したがってもう伝播しません)。

出力とクリア

void PyErr_Clear()

エラーインジケータをクリアします。エラーインジケータが設定されていないならば、効果はありません。

void PyErr_PrintEx(int set_sys_last_vars)

sys.stderr へ標準トレースバックを出力し、エラーインジケータをクリアします。エラーインジケータが設定されているときにだけ、この関数を呼び出してください。(それ以外の場合、致命的なエラーを引き起こすでしょう!)

set_sys_last_vars が非ゼロであれば、 sys.last_type, sys.last_value, sys.last_traceback 変数が、表示される例外のタイプ、値、トレースバックそれぞれに反映されます。

void PyErr_Print()

PyErr_PrintEx(1) のエイリアスです。

void PyErr_WriteUnraisable( PyObject *obj)

例外が設定されているがインタプリタが実際に例外を発生させることができないときに、このユーティリティ関数は警告メッセージを sys.stderr へ出力します。例えば、例外が __del__() メソッドで発生したときに使われます。

発生させられない例外が起きたコンテキストを指し示す単一の引数 obj で関数が呼び出されます。 可能な場合は、 obj の repr 文字列が警告メッセージに出力されます。

例外の送出

以下の関数は、現在のスレッドのエラーインジケータを設定する助けになります。 return 文で使うのに都合が良いように、いくつかの関数は常に NULL ポインタを返します。

void PyErr_SetString( PyObject *type, const char *message)

これはエラーインジケータを設定するための最も一般的な方法です。第一引数は例外の型を指定します。通常は標準例外の一つ、例えば PyExc_RuntimeError です。その参照カウントを増加させる必要はありません。第二引数はエラーメッセージで、 'utf-8' からデコードされます。

void PyErr_SetObject( PyObject *type, PyObject *value)

この関数は PyErr_SetString() に似ていますが、例外の "値(value)" として任意のPythonオブジェクトを指定することができます。

PyObject* PyErr_Format( PyObject *exception, const char *format, ...)
Return value: Always NULL.

この関数はエラーインジケータを設定し NULL を返します。 exception はPython例外クラスであるべきです。 format と以降の引数はエラーメッセージを作るためのもので, PyUnicode_FromFormat() の引数と同じ意味を持っています。 format は ASCII エンコードされた文字列です。

PyObject* PyErr_FormatV( PyObject *exception, const char *format, va_list vargs)
Return value: Always NULL.

PyErr_Format() と同じですが、可変長引数の代わりに va_list 引数を受け取ります。

バージョン 3.5 で追加.

void PyErr_SetNone( PyObject *type)

これは PyErr_SetObject(type, Py_None) を省略したものです。

int PyErr_BadArgument()

これは PyErr_SetString(PyExc_TypeError, message) を省略したもので、ここで message は組み込み操作が不正な引数で呼び出されたということを表しています。主に内部で使用するためのものです。

PyObject* PyErr_NoMemory()
Return value: Always NULL.

これは PyErr_SetNone(PyExc_MemoryError) を省略したもので、NULL を返します。したがって、メモリ不足になったとき、オブジェクト割り当て関数は return PyErr_NoMemory(); と書くことができます。

PyObject* PyErr_SetFromErrno( PyObject *type)
Return value: Always NULL.

Cライブラリ関数がエラーを返してC変数 errno を設定したときに、これは例外を発生させるために便利な関数です。第一要素が整数 errno 値で、第二要素が (strerror() から得られる)対応するエラーメッセージであるタプルオブジェクトを構成します。それから、 PyErr_SetObject(type, object) を呼び出します。 Unixでは、 errno 値が EINTR であるとき、すなわち割り込まれたシステムコールを表しているとき、これは PyErr_CheckSignals() を呼び出し、それがエラーインジケータを設定した場合は設定されたままにしておきます。関数は常に NULL を返します。したがって、システムコールがエラーを返したとき、システムコールのラッパー関数は return PyErr_SetFromErrno(type); と書くことができます。

PyObject* PyErr_SetFromErrnoWithFilenameObject( PyObject *type, PyObject *filenameObject)

PyErr_SetFromErrno() に似ていますが、 filenameObject が NULL でない場合に、 type のコンストラクタに第三引数として渡すというふるまいが追加されています。 OSError 例外の場合では、 filenameObject が例外インスタンスの filename 属性を定義するのに使われます。

PyObject* PyErr_SetFromErrnoWithFilenameObjects( PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)

PyErr_SetFromErrnoWithFilenameObject() に似てますが、ファイル名を2つ取る関数が失敗したときに例外を送出するために、2つ目のファイル名オブジェクトを受け取ります。

バージョン 3.4 で追加.

PyObject* PyErr_SetFromErrnoWithFilename( PyObject *type, const char *filename)
Return value: Always NULL.

PyErr_SetFromErrnoWithFilenameObject() に似ていますが、ファイル名は C 文字列として与えられます。 filename はファイルシステムのエンコーディング (os.fsdecode()) でデコードされます。

PyObject* PyErr_SetFromWindowsErr(int ierr)
Return value: Always NULL.

This is a convenience function to raise WindowsError. 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 tuple object whose first item is the ierr value and whose second item is the corresponding error message (gotten from FormatMessage()), and then calls PyErr_SetObject(PyExc_WindowsError, object). This function always returns NULL.

利用可能な環境: Windows 。

PyObject* PyErr_SetExcFromWindowsErr( PyObject *type, int ierr)
Return value: Always NULL.

Similar to PyErr_SetFromWindowsErr(), with an additional parameter specifying the exception type to be raised.

利用可能な環境: Windows 。

PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
Return value: Always NULL.

Similar to PyErr_SetFromWindowsErrWithFilenameObject(), but the filename is given as a C string. filename is decoded from the filesystem encoding (os.fsdecode()).

利用可能な環境: Windows 。

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject( PyObject *type, int ierr, PyObject *filename)

Similar to PyErr_SetFromWindowsErrWithFilenameObject(), with an additional parameter specifying the exception type to be raised.

利用可能な環境: Windows 。

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects( PyObject *type, int ierr, PyObject *filename, PyObject *filename2)

Similar to PyErr_SetExcFromWindowsErrWithFilenameObject(), but accepts a second filename object.

利用可能な環境: Windows 。

バージョン 3.4 で追加.

PyObject* PyErr_SetExcFromWindowsErrWithFilename( PyObject *type, int ierr, const char *filename)
Return value: Always NULL.

Similar to PyErr_SetFromWindowsErrWithFilename(), with an additional parameter specifying the exception type to be raised.

利用可能な環境: Windows 。

PyObject* PyErr_SetImportError( PyObject *msg, PyObject *name, PyObject *path)

ImportError を簡単に送出するための関数です。 msg は例外のメッセージ文字列としてセットされます。 name と path はどちらも NULL にしてよく、それぞれ ImportError の name 属性と path 属性としてセットされます。

バージョン 3.3 で追加.

void PyErr_SyntaxLocationObject( PyObject *filename, int lineno, int col_offset)

現在の例外のファイル、行、オフセットの情報をセットします。 現在の例外が SyntaxError でない場合は、例外を表示するサブシステムが、例外が SyntaxError であると思えるように属性を追加します。

バージョン 3.4 で追加.

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)

PyErr_SyntaxLocationObject() と似ていますが、 filename はファイルシステムのエンコーディングでデコードされた (os.fsdecode()) バイト文字列です。

バージョン 3.2 で追加.

void PyErr_SyntaxLocation(const char *filename, int lineno)

PyErr_SyntaxLocationEx() と似ていますが、 col_offset 引数が除去されています。

void PyErr_BadInternalCall()

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)

警告メッセージを発行します。 category 引数は警告カテゴリ(以下を参照) かまたは NULL で、 message 引数は UTF-8 エンコードされた文字列です。 stacklevel はスタックフレームの数を示す正の整数です; 警告はそのスタックフレームの中の実行している行から発行されます。 stacklevel が 1 だと PyErr_WarnEx() を呼び出している関数が、2 だとその上の関数が Warning の発行元になります。

Warning categories must be subclasses of PyExc_Warning; PyExc_Warning is a subclass of PyExc_Exception; the default warning category is PyExc_RuntimeWarning. The standard Python warning categories are available as global variables whose names are enumerated at Standard Warning Categories.

警告をコントロールするための情報については、 warnings モジュールのドキュメンテーションとコマンドライン・ドキュメンテーションの -W オプションを参照してください。警告コントロールのためのC APIはありません。

PyObject* PyErr_SetImportErrorSubclass( PyObject *msg, PyObject *name, PyObject *path)

PyErr_SetImportError() とよく似ていますが、この関数は送出する例外として、 ImportError のサブクラスを指定できます。

バージョン 3.6 で追加.

int PyErr_WarnExplicitObject( PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)

すべての警告の属性を明示的に制御した警告メッセージを出します。これは Python 関数 warnings.warn_explicit() の直接的なラッパで、さらに情報を得るにはそちらを参照してください。そこに説明されているデフォルトの効果を得るために、 module と registry 引数は NULL に設定することができます。

バージョン 3.4 で追加.

int PyErr_WarnExplicit( PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)

PyErr_WarnExplicitObject() に似ていますが、 message と module が UTF-8 エンコードされた文字列であるところが異なり、 filename はファイルシステムのエンコーディング (os.fsdecode()) でデコードされます。

int PyErr_WarnFormat( PyObject *category, Py_ssize_t stack_level, const char *format, ...)

PyErr_WarnEx() に似たような関数ですが、警告メッセージをフォーマットするのに PyUnicode_FromFormat() を使用します。 format は ASCII にエンコードされた文字列です。

バージョン 3.2 で追加.

int PyErr_ResourceWarning( PyObject *source, Py_ssize_t stack_level, const char *format, ...)

PyErr_WarnFormat() に似た関数で、category は ResourceWarning であり、 source は warnings.WarningMessage() に渡されます。

バージョン 3.6 で追加.

エラーインジケータの問い合わせ

PyObject* PyErr_Occurred()
Return value: Borrowed reference.

エラーインジケータが設定されているかテストします。設定されている場合は、例外の 型 (PyErr_Set*() 関数の一つあるいは PyErr_Restore() への最も新しい呼び出しに対する第一引数)を返します。設定されていない場合は NULL を返します。あなたは戻り値への参照を持っていませんので、それに Py_DECREF() する必要はありません。

注釈

戻り値を特定の例外と比較しないでください。その代わりに、下に示す PyErr_ExceptionMatches() を使ってください。(比較は簡単に失敗するでしょう。なぜなら、例外はクラスではなくインスタンスかもしれないし、あるいは、クラス例外の場合は期待される例外のサブクラスかもしれないからです。)

int PyErr_ExceptionMatches( PyObject *exc)

PyErr_GivenExceptionMatches(PyErr_Occurred(), exc) と同じ。例外が実際に設定されたときにだけ、これを呼び出だすべきです。例外が発生していないならば、メモリアクセス違反が起きるでしょう。

int PyErr_GivenExceptionMatches( PyObject *given, PyObject *exc)

例外 given が exc の例外型と適合する場合に真を返します。 exc がクラスオブジェクトである場合も、 given がサブクラスのインスタンスであるときに真を返します。 exc がタプルの場合は、タプルにある (およびそのサブタプルに再帰的にある) すべての例外型が適合するか調べられます。

void PyErr_Fetch( PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

エラーインジケータをアドレスを渡す三つの変数の中へ取り出します。エラーインジケータが設定されていない場合は、三つすべての変数を NULL に設定します。エラーインジケータが設定されている場合はクリアされ、あなたは取り出されたそれぞれのオブジェクトへの参照を持つことになります。型オブジェクトが NULL でないときでさえ、その値とトレースバックオブジェクトは NULL かもしれません。

注釈

通常、この関数は例外を捕捉する必要のあるコードや、エラーインジケータを一時的に保存して復元する必要のあるコードでのみ使います。

{
   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)

三つのオブジェクトからエラーインジケータを設定します。エラーインジケータがすでに設定されている場合は、最初にクリアされます。オブジェクトが NULL ならば、エラーインジケータがクリアされます。NULL のtypeと非 NULL のvalueあるいは tracebackを渡してはいけません。例外の型(type)はクラスであるべきです。無効な例外の型(type)あるいは値(value)を渡してはいけません。(これらの規則を破ると後で気付きにくい問題の原因となるでしょう。) この呼び出しはそれぞれのオブジェクトへの参照を取り除きます: あなたは呼び出しの前にそれぞれのオブジェクトへの参照を持たなければならないのであり、また呼び出しの後にはもはやこれらの参照を持っていません。(これを理解していない場合は、この関数を使ってはいけません。注意しておきます。)

注釈

通常、この関数はエラーインジケータを一時的に保存し復元する必要のあるコードでのみ使います。 現在のエラーインジケータを保存するためには PyErr_Fetch() を使ってください。

void PyErr_NormalizeException( PyObject**exc, PyObject**val, PyObject**tb)

ある状況では、以下の PyErr_Fetch() が返す値は "正規化されていない" 可能性があります。つまり、 *exc はクラスオブジェクトだが *val は同じクラスのインスタンスではないという意味です。この関数はそのような場合にそのクラスをインスタンス化するために使われます。その値がすでに正規化されている場合は何も起きません。遅延正規化はパフォーマンスを改善するために実装されています。

注釈

この関数は例外値に暗黙的に __traceback__ 属性を設定 しません 。 トレースバックを適切に設定する必要がある場合は、次の追加のコード片が必要です:

if (tb != NULL) {
  PyException_SetTraceback(val, tb);
}
void PyErr_GetExcInfo( PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

sys.exc_info() で得られる例外情報を取得します。 これは 既に捕まえた 例外を参照するもので、新たに送出された例外への参照は持っていません。 新しい3つのオブジェクトへの参照を返しますが、その中には NULL があるかもしれません。この関数は例外情報の状態を変更しません。

注釈

この関数は、通常は例外を扱うコードでは使用されません。正確に言うと、これは例外の状態を一時的に保存し、元に戻す必要があるコードで使用することができます。例外の状態を元に戻す、もしくはクリアするには PyErr_SetExcInfo() を使ってください。

バージョン 3.3 で追加.

void PyErr_SetExcInfo( PyObject *type, PyObject *value, PyObject *traceback)

sys.exc_info() で得られる例外情報を設定します。 これは 既に捕まえた 例外を参照するもので、新たに送出された例外への参照は持っていません。 この関数は引数への参照を盗みます。 例外の状態をクリアしたい場合は、3 つ全ての引数に NULL を渡してください。 3 つの引数についての一般的な規則は、 PyErr_Restore() を参照してください。

注釈

この関数は、通常は例外を扱うコードでは使用されません。正確に言うと、これは例外の状態を一時的に保存し、元に戻す必要があるコードで使用することができます。例外の状態を取得するには PyErr_GetExcInfo() を使ってください。

バージョン 3.3 で追加.

シグナルハンドリング

int PyErr_CheckSignals()

この関数はPythonのシグナル処理とやりとりすることができます。シグナルがそのプロセスへ送られたかどうかチェックし、そうならば対応するシグナルハンドラを呼び出します。 signal モジュールがサポートされている場合は、これはPythonで書かれたシグナルハンドラを呼び出せます。すべての場合で、 SIGINT のデフォルトの効果は KeyboardInterrupt 例外を発生させることです。例外が発生した場合、エラーインジケータが設定され、関数は -1 を返します。そうでなければ、関数は 0 を返します。エラーインジケータが以前に設定されている場合は、それがクリアされるかどうかわからない。

void PyErr_SetInterrupt()

この関数は廃止されています。 SIGINT シグナルが到達した影響をシミュレートします --- 次に PyErr_CheckSignals() が呼ばれるとき、 KeyboardInterrupt は送出されるでしょう。インタプリタロックを保持することなく呼び出すことができます。

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.

このユーティリティ関数は新しい例外クラスを作成して返します。 name 引数は新しい例外の名前、 module.classname 形式の C文字列でなければならない。 base と dict 引数は通常 NULL です。これはすべての例外のためのルート、組み込み名 Exception (Cでは PyExc_Exception としてアクセス可能)をルートとして派生したクラスオブジェクトを作成します。

新しいクラスの __module__ 属性は name 引数の前半部分(最後のドットまで)に設定され、クラス名は後半部分(最後のドットの後)に設定されます。 base 引数は代わりのベースクラスを指定するために使えます; 一つのクラスでも、クラスのタプルでも構いません。 dict 引数はクラス変数とメソッドの辞書を指定するために使えます。

PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)
Return value: New reference.

PyErr_NewException() とほぼ同じですが、新しい例外クラスに簡単に docstring を設定できます。 doc が NULL で無い場合、それが例外クラスの docstring になります。

バージョン 3.2 で追加.

例外オブジェクト

PyObject* PyException_GetTraceback( PyObject *ex)
Return value: New reference.

Python で __traceback__ 属性からアクセスできるものと同じ、例外に関する traceback の新しい参照を返します。関係する traceback が無い場合は、 NULL を返します。

int PyException_SetTraceback( PyObject *ex, PyObject *tb)

その例外に関する traceback に tb をセットします。クリアするには Py_None を使用してください。

PyObject* PyException_GetContext( PyObject *ex)

Python で __context__ 属性からアクセスできるものと同じ、例外に関するコンテキスト (ex が送出されたときに処理していた別の例外インスタンス) の新しい参照を返します。関係するコンテキストが無い場合は、 NULL を返します。

void PyException_SetContext( PyObject *ex, PyObject *ctx)

例外に関するコンテキストに ctx をセットします。クリアするには NULL を使用してください。ctx が例外インスタンスかどうかを確かめる型チェックは行われません。これは ctx への参照を盗みます。

PyObject* PyException_GetCause( PyObject *ex)

Python で __cause__ 属性からアクセスできるものと同じ、例外に関する原因 (raise ... from ... によってセットされる例外インスタンス、もしくは None) の新しい参照を返します。

void PyException_SetCause( PyObject *ex, PyObject *cause)

例外に関係する原因に cause をセットします。 クリアするには NULL を使用してください。 cause が例外インスタンスか None のどちらかであることを確かめる型チェックは行われません。 これは cause への参照を盗みます。

この関数によって暗黙的に __suppress_context__ に True がセットされます。

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)

encoding, object, length, start, end, reason 属性をもった UnicodeDecodeError オブジェクトを作成します。 encoding および reason は UTF-8 エンコードされた文字列です。

PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

encoding, object, length, start, end, reason 属性を持った UnicodeEncodeError オブジェクトを作成します。 encoding および reason は UTF-8 エンコードされた文字列です。

PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

object, length, start, end, reason 属性を持った UnicodeTranslateError オブジェクトを作成します。 reason は UTF-8 エンコードされた文字列です。

PyObject* PyUnicodeDecodeError_GetEncoding( PyObject *exc)
PyObject* PyUnicodeEncodeError_GetEncoding( PyObject *exc)

与えられた例外オブジェクトの encoding 属性を返します。

PyObject* PyUnicodeDecodeError_GetObject( PyObject *exc)
PyObject* PyUnicodeEncodeError_GetObject( PyObject *exc)
PyObject* PyUnicodeTranslateError_GetObject( PyObject *exc)

与えられた例外オブジェクトの 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)

渡された例外オブジェクトから 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)

渡された例外オブジェクトの 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)

渡された例外オブジェクトから 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)

渡された例外オブジェクトの end 属性を end に設定します。成功したら 0 を、失敗したら -1 を返します。

PyObject* PyUnicodeDecodeError_GetReason( PyObject *exc)
PyObject* PyUnicodeEncodeError_GetReason( PyObject *exc)
PyObject* PyUnicodeTranslateError_GetReason( PyObject *exc)

渡された例外オブジェクトの 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)

渡された例外オブジェクトの reason 属性を reason に設定します。成功したら 0 を、失敗したら -1 を返します。

再帰の管理

これら2つの関数は C レベルの再帰呼び出しを安全に実行する方法を、コアモジュールにも拡張モジュールにも提供します。再帰を使ったコードが必ずしも Python コードを実行するわけではない場合 (Python コードは再帰の深さを自動的に追跡します)、これらの関数が必要となります。

int Py_EnterRecursiveCall(const char *where)

C レベルの再帰呼び出しをしようとしているところに印を付けます。

USE_STACKCHECK が定義されている場合、 OS のスタックがオーバーフローがしたかどうかを PyOS_CheckStack() を使ってチェックします。もしオーバーフローしているなら、 MemoryError をセットしゼロでない値を返します。

次にこの関数は再帰の上限に達していないかをチェックします。 上限に達している場合、 RecursionError をセットしゼロでない値を返します。 そうでない場合はゼロを返します。

where は " in instance check" のような文字列にして、再帰の深さの限界に達したことで送出される RecursionError のメッセージに連結できるようにすべきです。

void Py_LeaveRecursiveCall()

Py_EnterRecursiveCall() を終了させます。 Py_EnterRecursiveCall() の 成功した 呼び出しに対し 1 回呼ばなければなりません。

コンテナ型に対し tp_repr を適切に実装するには、特殊な再帰の処理が求められます。スタックの防護に加え、 tp_repr は循環処理を避けるためにオブジェクトを辿っていく必要があります。次の 2 つの関数はその機能を容易にします。実質的には、これらは reprlib.recursive_repr() と同等な C の実装です。

int Py_ReprEnter( PyObject *object)

循環処理を検知するために、 tp_repr の実装の先頭で呼び出します。

そのオブジェクトが既に処理されたものだった場合、この関数は正の整数を返します。その場合、 tp_repr の実装は、循環を示す文字列オブジェクトを返すべきです。例えば、 dict オブジェクトは {...} を返しますし、 list オブジェクトは [...] を返します。

再帰回数の上限に達した場合は、この関数は負の整数を返します。この場合、 tp_repr の実装は一般的には NULL を返すべきです。

それ以外の場合は、関数はゼロを返し、 tp_repr の実装は通常どおり処理を続けてかまいません。

void Py_ReprLeave( PyObject *object)

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 | (2)
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 |

バージョン 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 により導入されました。

バージョン 3.5 で追加: PyExc_StopAsyncIteration and PyExc_RecursionError.

バージョン 3.6 で追加: PyExc_ModuleNotFoundError.

これらは互換性のある PyExc_OSError のエイリアスです:

C名 | 注釈
PyExc_EnvironmentError |
PyExc_IOError |
PyExc_WindowsError | (3)

バージョン 3.3 で変更: これらのエイリアスは例外の種類を分けるために使われます。

注釈:

  1. これは別の標準例外のためのベースクラスです。
  2. これは weakref.ReferenceError と同じです。
  3. Windowsでのみ定義されています。プリプロセッサマクロ MS_WINDOWS が定義されているかテストすることで、これを使うコードを保護してください。

Standard Warning Categories

All standard Python warning categories are available as global variables whose names are PyExc_ followed by the Python exception name. These have the type PyObject*; they are all class objects. For completeness, here are all the variables:

C名 | Python名 | 注釈
PyExc_Warning | Warning | (1)
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 |

バージョン 3.2 で追加: PyExc_ResourceWarning.

注釈:

  1. This is a base class for other standard warning categories.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


ユーティリティ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

ユーティリティ

この章の関数は、C で書かれたコードをプラットフォーム間で可搬性のあるものにする上で役立つものから、C から Python モジュールを使うもの、そして関数の引数を解釈したり、C の値から Python の値を構築するものまで、様々なユーティリティ的タスクを行います。

  • オペレーティングシステム関連のユーティリティ
  • システム関数
  • プロセス制御
  • モジュールのインポート
  • データ整列化 (data marshalling) のサポート
  • 引数の解釈と値の構築
    • 引数を解析する
      • 文字列とバッファ
      • 数
      • その他のオブジェクト
      • API 関数
    • 値の構築
  • 文字列の変換と書式化
  • リフレクション
  • codec レジストリとサポート関数
    • コーデック検索API
    • Unicode エラーハンドラ用レジストリ API

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


オペレーティングシステム関連のユーティリティ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »

オペレーティングシステム関連のユーティリティ

PyObject* PyOS_FSPath( PyObject *path)
Return value: New reference.

Return the file system representation for path. If the object is a str or bytes object, then its reference count is incremented. 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.

バージョン 3.6 で追加.

int Py_FdIsInteractive(FILE *fp, const char *filename)

filename という名前の標準 I/O ファイル fp が対話的 (interactive) であると考えられる場合に真 (非ゼロ) を返します。これは isatty(fileno(fp)) が真になるファイルの場合です。グローバルなフラグ Py_InteractiveFlag が真の場合には、 filename ポインタが NULL か、名前が '<stdin>' または '???' のいずれかに等しい場合にも真を返します。

void PyOS_BeforeFork()

Function to prepare some internal state before a process fork. This should be called before calling fork() or any similar function that clones the current process. Only available on systems where fork() is defined.

バージョン 3.7 で追加.

void PyOS_AfterFork_Parent()

Function to update some internal state after a process fork. This should be called from the parent process after calling fork() or any similar function that clones the current process, regardless of whether process cloning was successful. Only available on systems where fork() is defined.

バージョン 3.7 で追加.

void PyOS_AfterFork_Child()

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.

バージョン 3.7 で追加.

参考

os.register_at_fork() allows registering custom Python functions
to be called by PyOS_BeforeFork(),
PyOS_AfterFork_Parent() and  PyOS_AfterFork_Child().

void PyOS_AfterFork()

プロセスが fork した後の内部状態を更新するための関数です; fork 後 Python インタプリタを使い続ける場合、新たなプロセス内でこの関数を呼び出さねばなりません。新たなプロセスに新たな実行可能物をロードする場合、この関数を呼び出す必要はありません。

バージョン 3.7 で非推奨: This function is superseded by PyOS_AfterFork_Child().

int PyOS_CheckStack()

インタプリタがスタック空間を使い尽くしたときに真を返します。このチェック関数には信頼性がありますが、 USE_STACKCHECK が定義されている場合 (現状では Microsoft Visual C++ コンパイラでビルドした Windows 版) にしか利用できません . USE_STACKCHECK は自動的に定義されます; 自前のコードでこの定義を変更してはなりません。

PyOS_sighandler_t PyOS_getsig(int i)

シグナル i に対する現在のシグナルハンドラを返します。この関数は sigaction() または signal() のいずれかに対する薄いラッパです。 sigaction() や signal() を直接呼び出してはなりません! PyOS_sighandler_t は void (*)(int) の typedef による別名です。

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

シグナル i に対する現在のシグナルハンドラを h に設定します; 以前のシグナルハンドラを返します。この関数は sigaction() または signal() のいずれかに対する薄いラッパーです。 sigaction() や signal() を直接呼び出してはなりません! PyOS_sighandler_t は void (*)(int) の typedef による別名です。

wchar_t* Py_DecodeLocale(const char* arg, size_t *size)

surrogateescape エラーハンドラ を使って、ロケールエンコーディングのバイト文字列をデコードします: デコードできないバイトは U+DC80 から U+DCFF までの範囲の文字としてデコードされます。 バイト列がサロゲート文字としてデコードされる場合は、そのままデコードするのではなく surrogateescape エラーハンドラを使ってバイト列をエスケープします。

Encoding, highest priority to lowest priority:

  • UTF-8 on macOS and Android;
  • UTF-8 if the Python UTF-8 mode is enabled;
  • ASCII if the LC_CTYPE locale is "C", nl_langinfo(CODESET) returns the ASCII encoding (or an alias), and mbstowcs() and wcstombs() functions uses the ISO-8859-1 encoding.
  • the current locale encoding.

新しくメモリ確保されたワイドキャラクター文字列へのポインタを返します。 このメモリを解放するのには PyMem_RawFree() を使ってください。 引数 size が NULL でない場合は、 null 文字以外のワイドキャラクターの数を *size へ書き込みます。

デコードもしくはメモリ確保でエラーが起きると NULL を返します。 size が NULL でない場合は、メモリエラーのときは (size_t)-1 を、デコードでのエラーのときは (size_t)-2 を *size に設定します。

C ライブラリーにバグがない限り、デコードでのエラーは起こりえません。

キャラクター文字列をバイト文字列に戻すには Py_EncodeLocale() 関数を使ってください。

参考

PyUnicode_DecodeFSDefaultAndSize() および PyUnicode_DecodeLocaleAndSize() 関数。

バージョン 3.5 で追加.

バージョン 3.7 で変更: The function now uses the UTF-8 encoding in the UTF-8 mode.

char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)

surrogateescape エラーハンドラ を使って、ワイドキャラクター文字列をロケールエンコーディングにエンコードします: U+DC80 から U+DCFF までの範囲のサロゲート文字は 0x80 から 0xFF までのバイトに変換されます。

Encoding, highest priority to lowest priority:

  • UTF-8 on macOS and Android;
  • UTF-8 if the Python UTF-8 mode is enabled;
  • ASCII if the LC_CTYPE locale is "C", nl_langinfo(CODESET) returns the ASCII encoding (or an alias), and mbstowcs() and wcstombs() functions uses the ISO-8859-1 encoding.
  • the current locale encoding.

The function uses the UTF-8 encoding in the Python UTF-8 mode.

新しくメモリ確保されたバイト文字列へのポインタを返します。 このメモリを解放するのには 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.

バイト文字列をワイドキャラクター文字列に戻すには Py_DecodeLocale() 関数を使ってください。

バージョン 3.7 で変更: The function now uses the UTF-8 encoding in the UTF-8 mode.

参考

PyUnicode_EncodeFSDefault() および PyUnicode_EncodeLocale() 関数。

バージョン 3.5 で追加.

バージョン 3.7 で変更: The function now supports the UTF-8 mode.

システム関数

sys モジュールが提供している機能にCのコードからアクセスする関数です。すべての関数は現在のインタプリタスレッドの sys モジュールの辞書に対して動作します。この辞書は内部のスレッド状態構造体に格納されています。

PyObject *PySys_GetObject(const char *name)
Return value: Borrowed reference.

sys モジュールの name オブジェクトを返すか、存在しなければ例外を設定せずに NULL を返します。

int PySys_SetObject(const char *name, PyObject *v)

v が NULL で無い場合、 sys モジュールの name に v を設定します。 v が NULL なら、 sys モジュールから name を削除します。成功したら 0 を、エラー時は -1 を返します。

void PySys_ResetWarnOptions()

Reset sys.warnoptions to an empty list. This function may be called prior to Py_Initialize().

void PySys_AddWarnOption(const wchar_t *s)

Append s to sys.warnoptions. This function must be called prior to Py_Initialize() in order to affect the warnings filter list.

void PySys_AddWarnOptionUnicode( PyObject *unicode)

sys.warnoptions に unicode を追加します。

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.

void PySys_SetPath(const wchar_t *path)

sys.path を path に含まれるパスの、リストオブジェクトに設定します。 path はプラットフォームの検索パスデリミタ(Unixでは :, Windows では ;) で区切られたパスのリストでなければなりません。

void PySys_WriteStdout(const char *format, ...)

format で指定された出力文字列を sys.stdout に出力します。切り詰めが起こった場合を含め、例外は一切発生しません (後述)。

format は、フォーマット後の出力文字列のトータルの大きさを1000バイト以下に抑えるべきです。-- 1000 バイト以降の出力文字列は切り詰められます。特に、制限のない "%s" フォーマットを使うべきではありません。"%.<N>s" のようにして N に10進数の値を指定し、<N> + その他のフォーマット後の最大サイズが1000を超えないように設定するべきです。同じように "%f" にも気を付ける必要があります。非常に大きい数値に対して、数百の数字を出力する可能性があります。

問題が発生したり、 sys.stdout が設定されていなかった場合、フォーマット後のメッセージは本物の(Cレベルの) stdout に出力されます。

void PySys_WriteStderr(const char *format, ...)

PySys_WriteStdout() と同じですが、 sys.stderr もしくは stderr に出力します。

void PySys_FormatStdout(const char *format, ...)

PySys_WriteStdout() に似た関数ですが、 PyUnicode_FromFormatV() を使ってメッセージをフォーマットし、メッセージを任意の長さに切り詰めたりはしません。

バージョン 3.2 で追加.

void PySys_FormatStderr(const char *format, ...)

PySys_FormatStdout() と同じですが、 sys.stderr もしくは stderr に出力します。

バージョン 3.2 で追加.

void PySys_AddXOption(const wchar_t *s)

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

バージョン 3.2 で追加.

PyObject *PySys_GetXOptions()
Return value: Borrowed reference.

sys._xoptions と同様、 -X オプションの現在の辞書を返します。エラーが起きると、 NULL が返され、例外がセットされます。

バージョン 3.2 で追加.

プロセス制御

void Py_FatalError(const char *message)

致命的エラーメッセージ (fatal error message) を出力してプロセスを強制終了 (kill) します。後始末処理は行われません。この関数は、Python インタプリタを使い続けるのが危険であるような状況が検出されたとき; 例えば、オブジェクト管理が崩壊していると思われるときにのみ、呼び出されるようにしなければなりません。Unixでは、標準 C ライブラリ関数 abort() を呼び出して core を生成しようと試みます。

void Py_Exit(int status)

Exit the current process. This calls Py_FinalizeEx() and then calls the standard C library function exit(status). If Py_FinalizeEx() indicates an error, the exit status is set to 120.

バージョン 3.6 で変更: Errors from finalization no longer ignored.

int Py_AtExit(void (*func)())

Register a cleanup function to be called by Py_FinalizeEx(). The cleanup function will be called with no arguments and should return no value. At most 32 cleanup functions can be registered. When the registration is successful, Py_AtExit() returns 0; on failure, it returns -1. The cleanup function registered last is called first. Each cleanup function will be called at most once. Since Python's internal finalization will have completed before the cleanup function, no Python APIs should be called by func.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »


モジュールのインポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »

モジュールのインポート

PyObject* PyImport_ImportModule(const char *name)
Return value: New reference.

この関数は下で述べる PyImport_ImportModuleEx() を単純化したインタフェースで、 globals および locals 引数を NULL のままにし、 level を 0 にしたものです。 name 引数にドットが含まれる場合 (あるパッケージのサブモジュールを指定している場合)、 fromlist 引数がリスト ['*'] に追加され、戻り値がモジュールを含むトップレベルパッケージではなく名前つきモジュール (named module) になるようにします。 (残念ながらこのやり方には、 name が実際にはサブモジュールでなくサブパッケージを指定している場合、パッケージの __all__ 変数に指定されているサブモジュールがロードされてしまうという副作用があります。) インポートされたモジュールへの新たな参照を返します。失敗した場合には例外をセットし、 NULL を返します。インポートに失敗したモジュールは sys.modules に残りません。

この関数は常に絶対インポートを使用します。

PyObject* PyImport_ImportModuleNoBlock(const char *name)

この関数は、 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)

モジュールをインポートします。モジュールのインポートについては組み込みの Python 関数 __import__() を読むとよく分かります。というのも、標準の __import__() はこの関数を直接呼び出しているからです。

戻り値は、インポートされたモジュールかトップレベルパッケージへの新しい参照か、失敗した場合は例外を設定して NULL を返します。 __import__() と同じように、パッケージのサブモジュールが要求されたときは、空でない fromlist を渡された時以外は、トップレベルのパッケージを返します。

バージョン 3.3 で追加.

PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
Return value: New reference.

PyImport_ImportModuleLevelObject() と似ていますが、name が Unicode オブジェクトではなく UTF-8 でエンコードされた文字列である点で異なります。

バージョン 3.3 で変更: level にはもはや負の値は使用できません。

PyObject* PyImport_Import( PyObject *name)
Return value: New reference.

現在の "インポートフック関数" を呼び出すための高水準のインタフェースです (level に 0 を明示すると、絶対インポートを意味します)。 この関数は現在のグローバル変数辞書内の __builtins__ から __import__() 関数を呼び出します。すなわち、現在の環境にインストールされているインポートフック使ってインポートを行います。

この関数は常に絶対インポートを使用します。

PyObject* PyImport_ReloadModule( PyObject *m)
Return value: New reference.

モジュールを再ロード (reload) します。戻り値は再ロードしたモジュールかトップレベルパッケージへの新たな参照になります。失敗した場合には例外をセットし、NULL を返します (その場合でも、モジュールは生成されている場合があります)。

PyObject* PyImport_AddModuleObject( PyObject *name)

モジュール名に対応するモジュールオブジェクトを返します。name 引数は package.module の形式でもかまいません。まずモジュール辞書に該当するモジュールがあるかどうか調べ、なければ新たなモジュールを生成してモジュール辞書に挿入します。失敗した場合には例外をセットして NULL を返します。

注釈

この関数はモジュールのインポートやロードを行いません; モジュールがまだロードされていなければ、空のモジュールオブジェクトを得ることになります。 PyImport_ImportModule() やその別形式を使ってモジュールをインポートしてください。ドット名表記で指定した name が存在しない場合、パッケージ構造は作成されません。

バージョン 3.3 で追加.

PyObject* PyImport_AddModule(const char *name)
Return value: Borrowed reference.

PyImport_AddModuleObject() と似ていますが、name が UTF-8 でエンコードされた文字列ではなく Unicode オブジェクトを使用する点で異なります。

PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)
Return value: New reference.

モジュール名 (package.module 形式でも構いません) および Python のバイトコードファイルや組み込み関数 compile() で得られたコードオブジェクトを元にモジュールをロードします。モジュールオブジェクトへの新たな参照を返します。失敗した場合には例外をセットし、 NULL を返します。たとえ PyImport_ExecCodeModule() の処理に入った時に name が sys.modules に入っていたとしても、インポートに失敗したモジュールは sys.modules に残りません。初期化の不完全なモジュールを sys.modules に残すのは危険であり、そのようなモジュールをインポートするコードにとっては、モジュールの状態がわからない (モジュール作者の意図から外れた壊れた状態かもしれない) からです。

モジュールの __spec__ と __loader__ がまだ設定されていなければ、適切な値が設定されます。spec の ローダーは、モジュールの __loader__ が (もし設定されていれば) それに設定され、そうでなければ SourceFileLoader のインスタンスに設定されます。

モジュールの __file__ 属性はコードオブジェクトの co_filename へ設定されます。もし適切な場合は、 __cached__ へも設定されます。

この関数は、すでにインポートされているモジュールの場合には再ロードを行います。意図的にモジュールの再ロードを行う方法は PyImport_ReloadModule() を参照してください。

name が package.module 形式のドット名表記であった場合、まだ作成されていないパッケージ構造はその作成されないままになります。

PyImport_ExecCodeModuleEx() と PyImport_ExecCodeModuleWithPathnames() も参照してください。

PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
Return value: New reference.

PyImport_ExecCodeModule() と似ていますが、pathname が NULL でない場合にモジュールオブジェクトの __file__ 属性に pathname が設定される点が異なります。

PyImport_ExecCodeModuleWithPathnames() も参照してください。

PyObject* PyImport_ExecCodeModuleObject( PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)

PyImport_ExecCodeModuleEx() と似ていますが、cpathname が NULL でない場合にモジュールオブジェクトの __cached__ 属性に cpathname が設定される点が異なります。これらの 3 つの関数のうち、この関数の使用が望ましいです。

バージョン 3.3 で追加.

PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)

PyImport_ExecCodeModuleObject() と似ていますが、 name と pathname、 cpathname が UTF-8 でエンコードされた文字列である点が異なります。もし pathname が NULL の場合、cpathname から、pathname どのような値になるべきかを知る試みもなされます。

バージョン 3.2 で追加.

バージョン 3.3 で変更: バイトコードのパスが与えられた場合にのみ imp.source_from_cache() がソースパスの計算に使用されます。

long PyImport_GetMagicNumber()

Python バイトコードファイル (別名 .pyc ファイル) のマジックナンバーを返します。マジックナンバーはバイトコードファイルの最初の4バイトに、リトルエンディアンバイトオーダーで現れるべきです。エラーの場合は -1 を返します。

バージョン 3.3 で変更: 失敗した場合は -1 の値を返します。

const char * PyImport_GetMagicTag()

マジックタグ文字列を Python バイトコードファイル名の PEP 3147 フォーマットで返します。sys.implementation.cache_tag の値が信頼でき、かつこの関数の代わりに使用すべきであることを肝に命じましょう。

バージョン 3.2 で追加.

PyObject* PyImport_GetModuleDict()
Return value: Borrowed reference.

モジュール管理のための辞書 (いわゆる sys.modules)を返します。この辞書はインタプリタごとに一つだけある変数なので注意してください。

PyObject* PyImport_GetModule( PyObject *name)
Return value: New reference.

与えられた名前の既にインポート済みのモジュールを返します。 モジュールがインポートされていなかった場合は、 NULL を返しますが、エラーはセットしません。 モジュールの検索に失敗した場合は、 NULL を返し、エラーをセットします。

バージョン 3.7 で追加.

PyObject* PyImport_GetImporter( PyObject *path)

sys.path もしくは pkg.__path__ の要素である path を見付けるためのオブジェクトを返します。場合によっては sys.path_importer_cache 辞書から取得することもあります。 もしまだオブジェクトがキャッシュされていなかった場合は、 path 要素を扱えるフックが見付かるまで sys.path_hooks を走査します。 どのフックも path 要素を扱えない場合は None を返します; これにより、 path based finder がこの path 要素を見付けるためのオブジェクトが得られなかったことを呼び出し元に伝えます。 最終的に得られたオブジェクトを sys.path_importer_cache へキャッシュし、オブジェクトへの新たな参照を返します。

void _PyImport_Init()

インポート機構を初期化します。内部使用だけのための関数です。

void PyImport_Cleanup()

モジュールテーブルを空にします。内部使用だけのための関数です。

void _PyImport_Fini()

インポート機構を終了処理します。内部使用だけのための関数です。

int PyImport_ImportFrozenModuleObject( PyObject *name)

name という名前のフリーズ (freeze) されたモジュールをロードします。成功すると 1 を、モジュールが見つからなかった場合には 0 を、初期化が失敗した場合には例外をセットして -1 を返します。ロードに成功したモジュールにアクセスするには PyImport_ImportModule() を使ってください。 (Note この関数はいささか誤解を招く名前です --- この関数はモジュールがすでにインポートされていたらリロードしてしまいます。)

バージョン 3.3 で追加.

バージョン 3.4 で変更: __file__ 属性はもうモジュールにセットされません。

int PyImport_ImportFrozenModule(const char *name)

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;
};
const struct _frozen* PyImport_FrozenModules

このポインタは struct _frozen のレコードからなり、終端の要素のメンバが NULL かゼロになっているような配列を指すよう初期化されます。フリーズされたモジュールをインポートするとき、このテーブルを検索します。サードパーティ製のコードからこのポインタに仕掛けを講じて、動的に生成されたフリーズ化モジュールの集合を提供するようにできます。

int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void))

既存の組み込みモジュールテーブルに単一のモジュールを追加します。この関数は利便性を目的とした PyImport_ExtendInittab() のラッパ関数で、テーブルが拡張できないときには -1 を返します。新たなモジュールは name でインポートでき、最初にインポートを試みた際に呼び出される関数として initfunc を使います。 Py_Initialize() よりも前に呼び出さなければなりません。

struct _inittab

組み込みモジュールリスト内の一つのエントリを記述している構造体です。リスト内の各構造体には、インタプリタ内に組み込まれているモジュールの名前と初期化関数が指定されています。 Python を埋め込むようなプログラムは、この構造体の配列と PyImport_ExtendInittab() を組み合わせて、追加の組み込みモジュールを提供できます。構造体は Include/import.h で以下のように定義されています:

struct _inittab {
    const char *name;           /* ASCII encoded string */
    PyObject* (*initfunc)(void);
};
int PyImport_ExtendInittab(struct _inittab *newtab)

組み込みモジュールのテーブルに一群のモジュールを追加します。配列 newtab は name フィールドが NULL になっているセンチネル (sentinel) エントリで終端されていなければなりません; センチネル値を与えられなかった場合にはメモリ違反になるかもしれません。成功すると 0 を、内部テーブルを拡張するのに十分なメモリを確保できなかった場合には -1 を返します。操作が失敗した場合、モジュールは一切内部テーブルに追加されません。 Py_Initialize() よりも前に呼び出さなければなりません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »


データ整列化 (data marshalling) のサポート

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »

データ整列化 (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 はファイルフォーマットを示します。

void PyMarshal_WriteObjectToFile( PyObject *value, FILE *file, int version)

Python オブジェクト value を file へ整列化します。version はファイルフォーマットを示します。

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, exc:TypeError) を設定し NULL を返します。

PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
Return value: New reference.

読み出し用に開かれた FILE* 内のデータストリームから、 Python オブジェクトを読み出して返します。 PyMarshal_ReadObjectFromFile() と違い、この関数はファイル中に後続のオブジェクトが存在しないと仮定し、ファイルからメモリ上にファイルデータを一気にメモリにロードして、逆整列化機構がファイルから一バイトづつ読み出す代わりにメモリ上のデータを操作できるようにします。対象のファイルから他に何も読み出さないと分かっている場合にのみ、この関数を使ってください。

エラーの場合適切な例外 (EOFError, ValueError, exc:TypeError) を設定し NULL を返します。

PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
Return value: New reference.

data が指す len バイトのバイト列バッファ内のデータストリームから Python オブジェクトを返します。

エラーの場合適切な例外 (EOFError, ValueError, exc:TypeError) を設定し NULL を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »


引数の解釈と値の構築

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »

引数の解釈と値の構築

これらの関数は独自の拡張モジュール用の関数やメソッドを作成する際に便利です。詳しい情報や用例は Python インタプリタの拡張と埋め込み にあります。

最初に説明する 3 つの関数、 PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords(),および PyArg_Parse() はいずれも 書式文字列 (format string) を使います。書式文字列は、関数が受け取るはずの引数に関する情報を伝えるのに用いられます。いずれの関数における書式文字列も、同じ書式を使っています。

引数を解析する

書式文字列は、ゼロ個またはそれ以上の "書式単位 (format unit)" から成り立ちます。 1つの書式単位は1つの Python オブジェクトを表します; 通常は単一の文字か、書式単位からなる文字列を括弧で囲ったものになります。例外として、括弧で囲われていない書式単位文字列が単一のアドレス引数に対応する場合がいくつかあります。以下の説明では、引用符のついた形式は書式単位です; (丸)括弧で囲った部分は書式単位に対応する Python のオブジェクト型です; [角] 括弧は値をアドレス渡しする際に使う C の変数型です。

文字列とバッファ

以下のフォーマットはオブジェクトに連続したメモリチャンクとしてアクセスするためのものです。返される unicode や bytes のために生のストレージを用意する必要はありません。

一般に、フォーマットがバッファにポインタをセットする時は、そのバッファは対応する Python オブジェクトにより管理され、バッファはそのオブジェクトのライフタイムを共有します。自分自身でメモリを解放する必要はありません。この例外は、 es, es#, et, et# だけです。

ただし、 Py_buffer 構造体に格納されたバッファーはロックされて、呼び出し側はそのバッファーを Py_BEGIN_ALLOW_THREADS ブロック内でも、 mutable なデータが破棄されたりリサイズされたりするリスク無しに利用することができます。そのかわりに、そのデータに対する処理が終わった場合 (もしくは処理せずに中断した場合) には 必ず PyBuffer_Release() を呼ばなければなりません。

特に言及されていない場合、バッファーは NUL 終端されていません。

いくつかのフォーマットは読み込み専用の bytes-like オブジェクト を必要とし、バッファ構造体の代わりにポインタをセットします。それらは、オブジェクトの PyBufferProcs.bf_releasebuffer フィールドが NULL であることをチェックして動きます。これは bytearray などの変更可能オブジェクトを禁止します。

注釈

全ての # 型のフォーマット (s#, y#, など) において、length 引数の型 (int か Py_ssize_t) は Python.h を include する前に PY_SSIZE_T_CLEAN マクロを定義することで制御します。マクロが定義されている場合、 length は int 型ではなく Py_ssize_t 型になります。この挙動は将来の Python バージョンで変更され、 Py_ssize_t のみがサポートされて int はサポートされなくなるでしょう。常に PY_SSIZE_T_CLEAN を定義したほうが良いです。

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 *, int or Py_ssize_t]
s* と同じですが、 mutable なオブジェクトを受け取りません。結果は2つのC変数に格納されます。1つ目はC文字列へのポインターで、2つ目はその長さです。受け取った文字列は null バイトを含むかもしれません。 Unicode オブジェクトは 'utf-8' エンコーディングを利用して C 文字列に変換されます。
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 *, int]
s# に似ていますが、Python オブジェクトは None でもよく、その場合には C のポインタは NULL にセットされます。
y (読み出し専用の bytes-like object) [const char *]

このフォーマットは bytes-like object をキャラクタ文字列を指す C のポインタに変換します; Unicode オブジェクトを受け付けません。バイトバッファは null バイトを含むべきではありません; null バイトを含む場合は ValueError 例外を送出します。

バージョン 3.5 で変更: 以前は bytes バッファにヌルバイトが埋め込まれていたときに TypeError を送出していました。

y* (bytes-like object) [Py_buffer]
s* の変形で、 Unicode オブジェクトを受け付けず、 bytes-like object のみを受け付けます。 バイナリデータを受け付ける目的には、このフォーマットを使うことを推奨します。
y# (読み出し専用の bytes-like object) [const char *, int]
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) [const Py_UNICODE *]

Python Unicodeオブジェクトを NUL終端されたUnicode文字バッファへのポインタに変換します。 Py_UNICODE ポインタ変数へのアドレスを渡さなければならず、このアドレスに存在する Unicode バッファへのポインタが格納されます。 Py_UNICODE 文字のバイト幅はコンパイルオプション(16 または32ビットのどちらか)に依存することに注意してください。Python 文字列は null コードポイントを含んではなりません; null コードポイントを含む場合、 ValueError 例外が送出されます。

バージョン 3.5 で変更: 以前は Python 文字列に null コードポイントが埋め込まれていたときに TypeError を送出していました。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です。PyUnicode_AsWideCharString() を使用するように移行してください。

u# (str) [const Py_UNICODE *, int]

これは u のバリエーションで、値を二つの変数に記録します。一つ目の変数は Unicode データバッファへのポインタで、二つ目はその長さです。このフォーマットは null コードポイントを含むことができます。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です。PyUnicode_AsWideCharString() を使用するように移行してください。

Z (str or None) [const Py_UNICODE *]

u に似ていますが、Python オブジェクトは None でもよく、その場合には Py_UNICODE ポインタは NULL にセットされます。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です。PyUnicode_AsWideCharString() を使用するように移行してください。

Z# (str or None) [const Py_UNICODE *, int]

u# に似ていますが、 Python オブジェクトは None でもよく、その場合には Py_UNICODE ポインタは NULL にセットされます。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です。PyUnicode_AsWideCharString() を使用するように移行してください。

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, int *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, int *buffer_length]
es# と同じです。ただし、バイト文字列オブジェクトをエンコードし直さずに渡します。その代わり、実装ではバイト文字列オブジェクトがパラメタに渡したエンコードを使っているものと仮定します。

数

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のintを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 *]
Python オブジェクトを (一切変換を行わずに) C の Python オブジェクト型ポインタに保存します。これにより、C プログラムは実際のオブジェクトを受け渡しされます。オブジェクトの参照カウントは増加しません。保存されるポインタが 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が値の真偽をどのように判定するかを知りたければ、 真理値判定 を参照してください。

バージョン 3.3 で追加.

(items) (tuple) [matching-items]
オブジェクトは items に入っている書式単位の数だけの長さを持つ Python のシーケンス型でなければなりません。各 C 引数は items 内の個々の書式単位に対応づけできなければなりません。シーケンスの書式単位は入れ子構造にできます。

"長" 整数 (プラットフォームの LONG_MAX を超える値の整数) を渡すのは可能です; しかしながら、適切な値域チェックはまったく行われません --- 値を受け取るためのフィールドが、値全てを受け取るには小さすぎる場合、上桁のビット群は暗黙のうちに切り詰められます (実際のところ、このセマンティクスは C のダウンキャスト (downcast) から継承しています --- その恩恵は人それぞれかもしれませんが)。

その他、書式文字列において意味を持つ文字がいくつかあります。それらの文字は括弧による入れ子内には使えません。以下に文字を示します:

|
Python 引数リスト中で、この文字以降の引数がオプションであることを示します。オプションの引数に対応する C の変数はデフォルトの値で初期化しておかなければなりません --- オプションの引数が省略された場合、 PyArg_ParseTuple() は対応する C 変数の内容に手を加えません。
$

PyArg_ParseTupleAndKeywords() でのみ使用可能: 後続のPython引数が keyword-onlyであることを示します。現在、すべてのkeyword-only 引数は任意の引数でなければならず、そのため フォーマット文字列中の | は常に $ より前に指定されなければなりません。

バージョン 3.3 で追加.

:
この文字があると、書式単位の記述はそこで終わります; コロン以降の文字列は、エラーメッセージにおける関数名 (PyArg_ParseTuple() が送出する例外の "付属値 (associated value)") として使われます。
;
この文字があると、書式単位の記述はそこで終わります; セミコロン以降の文字列は、デフォルトエラーメッセージを 置き換える エラーメッセージとして使われます。 : と ; は相互に排他の文字です。

呼び出し側に提供されるオブジェクトへの参照はすべて 借用 参照 (borrowed reference) になります; これらのオブジェクトの参照カウントをデクリメントしてはなりません!

以下の関数に渡す補助引数 (additional argument) は、書式文字列から決定される型へのアドレスでなければなりません; 補助引数に指定したアドレスは、タプルから入力された値を保存するために使います。上の書式単位のリストで説明したように、補助引数を入力値として使う場合がいくつかあります; その場合、対応する書式単位の指定する形式に従うようにしなければなりません。

変換を正しく行うためには、 arg オブジェクトは書式文字に一致しなければならず、かつ書式文字列内の書式単位に全て値が入るようにしなければなりません。成功すると、 PyArg_Parse*() 関数は真を返します。それ以外の場合には偽を返し、適切な例外を送出します。書式単位のどれかの変換失敗により PyArg_Parse*() が失敗した場合、失敗した書式単位に対応するアドレスとそれ以降のアドレスの内容は変更されません。

API 関数

int PyArg_ParseTuple( PyObject *args, const char *format, ...)

位置引数のみを引数にとる関数のパラメタを解釈して、ローカルな変数に変換します。成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。

int PyArg_VaParse( PyObject *args, const char *format, va_list vargs)

PyArg_ParseTuple() と同じですが、可変長の引数ではなく va_list を引数にとります。

int PyArg_ParseTupleAndKeywords( PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)

位置引数とキーワード引数の両者を取る関数の引数を解釈します。 keywords 引数は NULL で終端されたキーワード名の配列です。 空の名前は 位置引数のみ を示します。成功した場合、真を返します。失敗した場合は偽を返し、また適切な例外を発生させます。

バージョン 3.6 で変更: 位置引数のみ を追加した。

int PyArg_VaParseTupleAndKeywords( PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)

PyArg_ParseTupleAndKeywords() と同じですが、可変長の引数ではなく va_list を引数にとります。

int PyArg_ValidateKeywordArguments( PyObject *)

キーワード引数を格納した辞書のキーが文字列であることを確認します。この関数は PyArg_ParseTupleAndKeywords() を使用しないときにのみ必要で、その理由は後者の関数は同様のチェックを実施するためです。

バージョン 3.2 で追加.

int PyArg_Parse( PyObject *args, const char *format, ...)

"旧スタイル" の関数における引数リストを分析するために使われる関数です --- 旧スタイルの関数は、引数解釈手法に、Python 3 で削除された METH_OLDARGS を使います。新たに書かれるコードでのパラメタ解釈にはこの関数の使用は奨められず、標準のインタプリタにおけるほとんどのコードがもはや引数解釈のためにこの関数を使わないように変更済みです。この関数を残しているのは、この関数が依然として引数以外のタプルを分析する上で便利だからですが、この目的においては将来も使われつづけるかもしれません。

int PyArg_UnpackTuple( PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)

パラメータ取得を簡単にした形式で、引数の型を指定する書式文字列を使いません。パラメタの取得にこの手法を使う関数は、関数宣言テーブル、またはメソッド宣言テーブル内で METH_VARARGS として宣言しなければなりません。実引数の入ったタプルは args に渡します; このタプルは本当のタプルでなければなりません。タプルの長さは少なくとも min で、 max を超えてはなりません; min と max が等しくてもかまいません。補助引数を関数に渡さなければならず、各補助引数は PyObject* 変数へのポインタでなければなりません; これらの補助引数には、 args の値が入ります; 値の参照は借用参照です。オプションのパラメタに対応する変数のうち、 args に指定していないものには値が入りません; 呼び出し側はそれらの値を初期化しておかなければなりません。この関数は成功すると真を返し、 args がタプルでない場合や間違った数の要素が入っている場合に偽を返します; 何らかの失敗が起きた場合には例外をセットします。

この関数の使用例を以下に示します。この例は、弱参照のための _weakref 補助モジュールのソースコードからとったものです:

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.

PyArg_Parse*() ファミリの関数が受け取るのと似た形式の書式文字列および値列に基づいて、新たな値を生成します。生成した値を返します。エラーの場合には NULL を返します; NULL を返す場合、例外を送出するでしょう。

Py_BuildValue() は常にタプルを生成するとは限りません。この関数がタプルを生成するのは、書式文字列に二つ以上の書式単位が入っているときだけです。書式文字列が空の場合 None を返します; 書式単位が厳密に一つだけ入っている場合、書式単位で指定されている何らかのオブジェクト単体を返します。サイズがゼロや 1 のタプルを返すように強制するには、丸括弧で囲われた書式文字列を使います。

書式単位 s や s# の場合のように、オブジェクトを構築する際にデータを供給するためにメモリバッファをパラメタとして渡す場合には、指定したデータはコピーされます。 Py_BuildValue() が生成したオブジェクトは、呼び出し側が提供したバッファを決して参照しません。別の言い方をすれば、 malloc() を呼び出してメモリを確保し、それを Py_BuildValue() に渡した場合、コード内で Py_BuildValue() が返った後で free() を呼び出す責任があるということです。

以下の説明では、引用符のついた形式は書式単位です; (丸)括弧で囲った部分は書式単位が返す Python のオブジェクト型です; [角] 括弧は関数に渡す値の C 変数型です。

書式文字列内では、(s# のような書式単位を除いて) スペース、タブ、コロンおよびコンマは無視されます。これらの文字を使うと、長い書式文字列をちょっとだけ読みやすくできます。

s (str or None) [const char *]
null終端された C 文字列を、 'utf-8' エンコーディングを用いて、 Python str オブジェクトに変換します。もし C 文字列ポインタが NULL の場合、 None になります。
s# (str or None) [const char *, int]
C 文字列とその長さを 'utf-8' エンコーディングを使って Python str オブジェクトに変換します。C 文字列ポインタが NULL の場合、長さは無視され、 None になります。
y (bytes) [const char *]
C 文字列をPython bytes オブジェクトに変換します。もしC 文字列ポインタが NULL だった場合、None を返します。
y# (bytes) [const char *, int]
これは C 文字列とその長さから Python オブジェクトに変換します。C 文字列ポインタが NULL の場合、長さは無視され None になります。
z (str または None) [const char *]
s と同じです。
z# (str or None) [const char *, int]
s# と同じです。
u (str) [const wchar_t *]
null 終端された Unicode (UTF-16 または UCS-4) データの wchar_t バッファから Python Unicode オブジェクトに変換します。 Unicode バッファポインタが NULL の場合、 None になります。
u# (str) [const wchar_t *, int]
Unicode (UTF-16 または UCS-4) データのバッファとその長さから Python Unicode オブジェクトに変換します。 Unicode バッファポインタが NULL の場合、長さは無視され None になります。
U (str or None) [const char *]
s と同じです。
U# (str or None) [const char *, int]
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のintオブジェクトへ変換する。
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 *]
Python オブジェクトを手を加えずに渡します (ただし、参照カウントは 1 インクリメントします)。渡したオブジェクトが NULL ポインタの場合、この引数を生成するのに使った何らかの呼び出しがエラーになったのが原因であると仮定して、例外をセットします。従ってこのとき Py_BuildValue() は NULL を返しますが例外は送出しません。例外をまだ送出していなければ SystemError をセットします。
S (object) [PyObject *]
O と同じです。
N (object) [PyObject *]
O と同じです。ただし、オブジェクトの参照カウントをインクリメントしません。オブジェクトが引数リスト内のオブジェクトコンストラクタ呼び出しによって生成されている場合に便利です。
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)

Py_BuildValue() と同じですが、可変長引数の代わりに va_list を受け取ります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »


文字列の変換と書式化

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »

文字列の変換と書式化

数値変換と、書式化文字列出力のための関数群。

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

書式文字列 format と追加の引数から、 size バイトを超えない文字列を str に出力します。 Unix man page の snprintf(2) を参照してください。

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

書式文字列 format と可変長引数リスト va から、 size バイトを超えない文字列を str に出力します。 Unix man page の vsnprintf(2) を参照してください。

PyOS_snprintf() と PyOS_vsnprintf() は標準Cライブラリの snprintf() と vsnprintf() 関数をラップします。これらの関数の目的は、C標準ライブラリが保証していないコーナーケースでの動作を保証することです。

これらのラッパ関数は、戻るときに str*[*size-1] が常に '\0' であることを保証します。(str の末尾の '\0' を含めて) size バイト以上を書き込みません。str != NULL, size > 0, format != NULL を要求します。

もし vsnprintf() のないプラットフォームで、切り捨てを避けるために必要なバッファサイズが size を512バイトより大きく超過していれば、 Python は Py_FatalError で abort します。

これらの関数の戻り値 (以下では 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 非依存な文字列から数値への変換を行ないます。

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

文字列 s を double に変換します。失敗したときは Python の例外を発生させます。受け入れられる文字列は、 Python の float() コンストラクタが受け付ける文字列に準拠しますが、 s の先頭と末尾に空白文字があってはならないという部分が異なります。この変換は現在のロケールに依存しません。

If endptr is NULL, convert the whole string. Raise ValueError and return -1.0 if the string is not a valid representation of a floating-point number.

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 を返します。

バージョン 3.1 で追加.

char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

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() を使って解放する責任があります。

バージョン 3.1 で追加.

int PyOS_stricmp(const char *s1, const char *s2)

大文字/小文字を区別しない文字列比較。大文字/小文字を無視する以外は、 strcmp() と同じ動作をします。

int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)

大文字/小文字を区別しない文字列比較。大文字/小文字を無視する以外は、 strncmp() と同じ動作をします。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »


リフレクション

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »

リフレクション

PyObject* PyEval_GetBuiltins()
Return value: Borrowed reference.

現在の実行フレーム内のビルトインの辞書か、もし実行中のフレームがなければスレッド状態のインタプリタのビルトイン辞書を返します。

PyObject* PyEval_GetLocals()
Return value: Borrowed reference.

現在の実行フレーム内のローカル変数の辞書か、実行中のフレームがなければ NULL を返します。

PyObject* PyEval_GetGlobals()
Return value: Borrowed reference.

現在の実行フレームのグローバル変数の辞書か、実行中のフレームがなければ NULL を返します。

PyFrameObject* PyEval_GetFrame()
Return value: Borrowed reference.

現在のスレッド状態のフレームを返します。現在実行中のフレームがなければ NULL を返します。

int PyFrame_GetLineNumber( PyFrameObject *frame)

frame が現在実行している行番号を返します。

const char* PyEval_GetFuncName( PyObject *func)

func が関数、クラス、インスタンスオブジェクトであればその名前を、そうでなければ func の型を返します。

const char* PyEval_GetFuncDesc( PyObject *func)

func の型に依存する、解説文字列(description string)を返します。戻り値は、関数とメソッドに対しては "()", " constructor", " instance", " object" です。 PyEval_GetFuncName() と連結された結果、 func の解説になります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »


codec レジストリとサポート関数

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »

codec レジストリとサポート関数

int PyCodec_Register( PyObject *search_function)

新しい codec 検索関数を登録します。

副作用として、この関数は encodings パッケージが常に検索関数の先頭に来るように、まだロードされていない場合はロードします。

int PyCodec_KnownEncoding(const char *encoding)

Return 1 or 0 depending on whether there is a registered codec for the given encoding.

PyObject* PyCodec_Encode( PyObject *object, const char *encoding, const char *errors)

汎用の codec ベースの encode API.

encoding に応じて見つかったエンコーダ関数に対して object を渡します。エラーハンドリングメソッドは errors で指定します。 errors は NULL でもよく、その場合はその codec のデフォルトのメソッドが利用されます。エンコーダが見つからなかった場合は LookupError を発生させます。

PyObject* PyCodec_Decode( PyObject *object, const char *encoding, const char *errors)

汎用の codec ベースのデコード API.

encoding に応じて見つかったデコーダ関数に対して object を渡します。エラーハンドリングメソッドは errors で指定します。 errors は NULL でもよく、その場合はその codec のデフォルトのメソッドが利用されます。デコーダが見つからなかった場合は LookupError を発生させます。

コーデック検索API

以下の関数では、文字列 encoding は全て小文字に変換することで、効率的に、大文字小文字を無視した検索をします。コーデックが見つからない場合、 KeyError を設定して NULL を返します。

PyObject* PyCodec_Encoder(const char *encoding)

与えられた encoding のエンコーダ関数を返します。

PyObject* PyCodec_Decoder(const char *encoding)

与えられた encoding のデコーダ関数を返します。

PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)

与えられた encoding の IncrementalEncoder オブジェクトを返します。

PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)

与えられた encoding の IncrementalDecoder オブジェクトを返します。

PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)

与えられた encoding の StreamReader ファクトリ関数を返します。

PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)

与えられた encoding の StreamWriter ファクトリ関数を返します。

Unicode エラーハンドラ用レジストリ API

int PyCodec_RegisterError(const char *name, PyObject *error)

エラーハンドルのためのコールバック関数 error を name で登録します。このコールバック関数は、コーデックがエンコードできない文字/デコードできないバイトに遭遇した時に、そのエンコード/デコード関数の呼び出しで name が指定されていたら呼び出されます。

コールバックは1つの引数として、 UnicodeEncodeError, UnicodeDecodeError, UnicodeTranslateError のどれかのインスタンスを受け取ります。このインスタンスは問題のある文字列やバイト列に関する情報と、その元の文字列中のオフセットを持っています。(その情報を取得するための関数については Unicode 例外オブジェクト を参照してください。) コールバックは渡された例外を発生させるか、2要素のタプルに問題のシーケンスの代替と、 encode/decode を再開する元の文字列中のオフセットとなる整数を格納して返します。

成功したら 0 を、エラー時は -1 を返します。

PyObject* PyCodec_LookupError(const char *name)

name で登録されたエラーハンドリングコールバック関数を検索します。特別な場合として、NULL が渡された場合、"strict" のエラーハンドリングコールバック関数を返します。

PyObject* PyCodec_StrictErrors( PyObject *exc)

exc を例外として発生させます。

PyObject* PyCodec_IgnoreErrors( PyObject *exc)

unicode エラーを無視し、問題の入力をスキップします。

PyObject* PyCodec_ReplaceErrors( PyObject *exc)

unicode エラーを ? か U+FFFD で置き換えます。

PyObject* PyCodec_XMLCharRefReplaceErrors( PyObject *exc)

unicode encode エラーを XML文字参照で置き換えます。

PyObject* PyCodec_BackslashReplaceErrors( PyObject *exc)

unicode encode エラーをバックスラッシュエスケープ (\x, \u, \U) で置き換えます。

PyObject* PyCodec_NameReplaceErrors( PyObject *exc)

unicode encode エラーを \N{...} で置き換えます。

バージョン 3.5 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • ユーティリティ »


抽象オブジェクトレイヤ (abstract objects layer)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

抽象オブジェクトレイヤ (abstract objects layer)

この章で説明する関数は、オブジェクトの型に依存しないような Python オブジェクトの操作や、(数値型全て、シーケンス型全てといった) 大まかな型のオブジェクトに対する操作を行ないます。関数を適用対象でないオブジェクトに対して使った場合、Python の例外が送出されることになります。

これらの関数は、 PyList_New() で作成された後に NULL 以外の値を設定されていないリストのような、適切に初期化されていないオブジェクトに対して使うことはできません。

  • オブジェクトプロトコル (object protocol)
  • 数値型プロトコル (number protocol)
  • シーケンス型プロトコル (sequence protocol)
  • マップ型プロトコル (mapping protocol)
  • イテレータプロトコル (iterator protocol)
  • バッファプロトコル (buffer Protocol)
    • buffer 構造体
    • バッファリクエストのタイプ
      • リクエストに依存しないフィールド
      • readonly, format
      • shape, strides, suboffsets
      • 隣接性のリクエスト
      • 複合リクエスト
    • 複雑な配列
      • NumPy スタイル: shape, strides
      • PIL スタイル: shape, strides, suboffsets
    • バッファ関連の関数
  • 古いバッファプロトコル

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


オブジェクトプロトコル (object protocol)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »

オブジェクトプロトコル (object protocol)

PyObject* Py_NotImplemented

与えられたオブジェクトとメソッドの引数の型の組み合わせの処理が未実装である印として使われる、 未実装 (NotImplemented) シングルトン。

Py_RETURN_NOTIMPLEMENTED

C 関数から Py_NotImplemented を返す処理を適切に行います (すなわち、 NotImplemented シングルトンの参照カウントを増やし、返却します) 。

int PyObject_Print( PyObject *o, FILE *fp, int flags)

オブジェクト o をファイル fp に出力します。失敗すると -1 を返します。 flags 引数は何らかの出力オプションを有効にする際に使います。現在サポートされている唯一のオプションは Py_PRINT_RAW です; このオプションを指定すると、 repr() の代わりに str() を使ってオブジェクトを書き込みます。

int PyObject_HasAttr( PyObject *o, PyObject *attr_name)

o が属性 attr_name を持つときに 1 を、それ以外のときに 0 を返します。この関数は Python の式 hasattr(o, attr_name) と同じです。この関数は常に成功します。

int PyObject_HasAttrString( PyObject *o, const char *attr_name)

o が属性 attr_name を持つときに 1 を、それ以外のときに 0 を返します。この関数は Python の式 hasattr(o, attr_name) と同じです。この関数は常に成功します。

PyObject* PyObject_GetAttr( PyObject *o, PyObject *attr_name)
Return value: New reference.

オブジェクト o から、名前 attr_name の属性を取得します。成功すると属性値を返し失敗すると NULL を返します。この関数は Python の式 o.attr_name と同じです。

PyObject* PyObject_GetAttrString( PyObject *o, const char *attr_name)
Return value: New reference.

オブジェクト o から、名前 attr_name の属性を取得します。成功すると属性値を返し失敗すると NULL を返します。この関数は Python の式 o.attr_name と同じです。

PyObject* PyObject_GenericGetAttr( PyObject *o, PyObject *name)

型オブジェクトの tp_getattro スロットに置かれる、属性を取得する総称的な関数です。この関数は、 (もし存在すれば) オブジェクトの属性 __dict__ に加え、オブジェクトの MRO にあるクラスの辞書にあるデスクリプタを探します。 デスクリプタ (descriptor) の実装 で概要が述べられている通り、データのデスクリプタはインスタンスの属性より優先され、非データデスクリプタは後回しにされます。見付からなかった場合は AttributeError を送出します。

int PyObject_SetAttr( PyObject *o, PyObject *attr_name, PyObject *v)

オブジェクト 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)

オブジェクト o の attr_name という名の属性に、値 v を設定します。 失敗すると例外を送出し -1 を返します; 成功すると 0 を返します。 この関数は Python の式 o.attr_name = v と同じです。

v が NULL の場合は属性が削除されますが、この機能は非推奨であり PyObject_DelAttrString() を使うのが望ましいです。

int PyObject_GenericSetAttr( PyObject *o, PyObject *name, PyObject *value)

属性の設定と削除を行う汎用的な関数で、型オブジェクトの 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)

オブジェクト o の attr_name という名の属性を削除します。失敗すると -1 を返します。この関数は Python の文 del o.attr_name と同じです。

PyObject* PyObject_GenericGetDict( PyObject *o, void *context)

__dict__ デスクリプタの getter の総称的な実装です。必要な場合は、辞書を作成します。

バージョン 3.3 で追加.

int PyObject_GenericSetDict( PyObject *o, void *context)

__dict__ デスクリプタの setter の総称的な実装です。この実装では辞書を削除することは許されていません。

バージョン 3.3 で追加.

PyObject* PyObject_RichCompare( PyObject *o1, PyObject *o2, int opid)
Return value: New reference.

o1 と o2 を opid に指定した演算によって比較します。 opid は Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, または Py_GE, のいずれかでなければならず、それぞれ <, <=, ==, !=, >, および >= に対応します。この関数は Python の式 o1 op o2 と同じで、 op が opid に対応する演算子です。成功すると比較結果の値を返し失敗すると NULL を返します。

int PyObject_RichCompareBool( PyObject *o1, PyObject *o2, int opid)

o1 と o2 を opid に指定した演算によって比較します。 opid は Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, または Py_GE, のいずれかでなければならず、それぞれ <, <=, ==, !=, >, および >= に対応します。比較結果が真ならば 1 を、偽ならば 0 を、エラーが発生すると -1 を返します。この関数は Python の式 o1 op o2 と同じで、 op が opid に対応する演算子です。

注釈

o1 と o2 が同一のオブジェクトである場合、 PyObject_RichCompareBool() は Py_EQ に対して常に 1 を返し、 Py_NE に対して常に 0 を返します。

PyObject* PyObject_Repr( PyObject *o)
Return value: New reference.

オブジェクト o の文字列表現を計算します。成功すると文字列表現を返し、失敗すると NULL を返します。 Python 式 repr(o) と同じです。この関数は組み込み関数 repr() の処理で呼び出されます。

バージョン 3.4 で変更: アクティブな例外を黙って捨てないことを保証するのに便利なように、この関数はデバッグアサーションを含むようになりました。

PyObject* PyObject_ASCII( PyObject *o)

PyObject_Repr() と同様、オブジェクト o の文字列表現を計算しますが、 PyObject_Repr() によって返された文字列に含まれる非 ASCII 文字を、エスケープ文字 \x 、 \u 、 \U でエスケープします。この関数は Pythoh 2 の PyObject_Repr() が返す文字列と同じ文字列を生成します。 ascii() によって呼び出されます。

PyObject* PyObject_Str( PyObject *o)
Return value: New reference.

オブジェクト o の文字列表現を計算します。成功すると文字列表現を返し、失敗すると NULL を返します。 Python 式 str(o) と同じです。この関数は組み込み関数 str() や、 print() 関数の処理で呼び出されます。

バージョン 3.4 で変更: アクティブな例外を黙って捨てないことを保証するのに便利なように、この関数はデバッグアサーションを含むようになりました。

PyObject* PyObject_Bytes( PyObject *o)

オブジェクト o のバイト列表現を計算します。失敗すると NULL を返し、成功すると bytes オブジェクトを返します。 o が整数でないときの、 Python 式 bytes(o) と同じです。 bytes(o) と違って、 o が整数のときには、ゼロで初期化された bytes オブジェクトを返すのではなく TypeError が送出されます。

int PyObject_IsSubclass( PyObject *derived, PyObject *cls)

クラス derived がクラス cls と同一であるか、そこから派生したクラスである場合は 1 を返し、そうでない場合は 0 を返します。 エラーが起きた場合は -1 を返します。

cls がタプルの場合、 cls の全ての要素に対してチェックします。 少なくとも1つのチェックで 1 が返ったとき、結果は 1 となり、それ以外のとき 0 になります。

cls に __subclasscheck__() メソッドがある場合は、子クラスの状態が PEP 3119 にある通りかどうかを判定するために呼ばれます。 そうでないとき derived が cls の子クラスになるのは、直接的あるいは間接的な子クラスである場合、つまり cls.__mro__ に含まれる場合です。

通常は、クラスオブジェクト、つまり type のインスタンスやそこから派生したクラスだけがクラスと見なされます。 しかし、オブジェクトに属性 __bases__ (これは基底クラスのタプルでなければならない) を持たせることで上書きできます。

int PyObject_IsInstance( PyObject *inst, PyObject *cls)

inst がクラス cls もしくは cls の子クラスのインスタンスである場合に 1 を返し、そうでない場合に 0 を返します。 エラーが起きると -1 を返し例外を設定します。

cls がタプルの場合、 cls の全ての要素に対してチェックします。 少なくとも1つのチェックで 1 が返ったとき、結果は 1 となり、それ以外のとき 0 になります。

cls に __instancecheck__() メソッドがある場合は、子クラスの状態が PEP 3119 にある通りかどうかを判定するために呼ばれます。 そうでないとき inst が cls のインスタンスになるのは、そのクラスが cls の子クラスである場合です。

インスタンス inst に属性 __class__ を持たせることで、そのクラスと見なされるものを上書きできます。

オブジェクト cls とその基底クラスがクラスと見なされる場合、属性 __bases__ (これは基底クラスのタプルでなければならない) を持たせることで上書きできます。

int PyCallable_Check( PyObject *o)

オブジェクト o が呼び出し可能オブジェクトかどうか調べます。オブジェクトが呼び出し可能であるときに 1 を返し、そうでないときには 0 を返します。この関数呼び出しは常に成功します。

PyObject* PyObject_Call( PyObject *callable, PyObject *args, PyObject *kwargs)
Return value: New reference.

呼び出し可能な Python のオブジェクト callable を、タプル args として与えられる引数と辞書 kwargs として与えられる名前付き引数とともに呼び出します。

args は NULL であってはならず、引数を必要としない場合は空のタプルを使ってください。 kwargs は NULL でも構いません。

成功したら呼び出しの結果を返します。失敗したら NULL を返します。

これは次の Python の式と同等です: callable(*args, **kwargs) 。

PyObject* PyObject_CallObject( PyObject *callable, PyObject *args)
Return value: New reference.

呼び出し可能な Python のオブジェクト callable を、タプル args として与えられる引数とともに呼び出します。 引数が必要な場合は、 args は NULL で構いません。

成功したら呼び出しの結果を返します。失敗したら NULL を返します。

これは次の Python の式と同等です: callable(*args) 。

PyObject* PyObject_CallFunction( PyObject *callable, const char *format, ...)
Return value: New reference.

呼び出し可能な Python オブジェクト callable を可変数個の C 引数とともに呼び出します。 C 引数は Py_BuildValue() 形式のフォーマット文字列を使って記述します。

成功したら呼び出しの結果を返します。失敗したら 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.

オブジェクト 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, ..., NULL)
Return value: New reference.

呼び出し可能な Python オブジェクト callable を可変数個の PyObject* 引数とともに呼び出します。引数列は末尾に NULL がついた可変数個のパラメタとして与えます。

成功したら呼び出しの結果を返します。失敗したら NULL を返します。

これは次の Python の式と同等です: callable(arg1, arg2, ...) 。

PyObject* PyObject_CallMethodObjArgs( PyObject *obj, PyObject *name, ..., NULL)
Return value: New reference.

Python オブジェクト obj のメソッドを呼び出します、メソッド名は Python 文字列オブジェクト name で与えます。可変数個の PyObject* 引数と共に呼び出されます. 引数列は末尾に NULL がついた可変数個のパラメタとして与えます。成功すると呼び出し結果として得られたオブジェクトを返し失敗すると NULL を返します。

Py_hash_t PyObject_Hash( PyObject *o)

オブジェクト o のハッシュ値を計算して返します。失敗すると -1 を返します。 Python の式 hash(o) と同じです。

バージョン 3.2 で変更: 返り値の型が Py_hash_t になりました。この型は、 Py_ssize_t と同じサイズをもつ符号付き整数です。

Py_hash_t PyObject_HashNotImplemented( PyObject *o)

type(o) がハッシュ不可能であることを示す TypeError を設定し、 -1 を返します。この関数は tp_hash スロットに格納されたときには特別な扱いを受け、その type がハッシュ不可能であることをインタプリタに明示的に示します。

int PyObject_IsTrue( PyObject *o)

o が真を表すとみなせる場合には 1 を、そうでないときには 0 を返します。 Python の式 not not o と同じです。失敗すると -1 を返します。

int PyObject_Not( PyObject *o)

o が真を表すとみなせる場合には 0 を、そうでないときには 1 を返します。 Python の式 not o と同じです。失敗すると -1 を返します。

PyObject* PyObject_Type( PyObject *o)
Return value: New reference.

o が NULL でない場合、オブジェクト o のオブジェクト型に相当する型オブジェクトを返します。失敗すると SystemError を送出して NULL を返します。 Python の式 type(o) と同じです。 この関数は戻り値の参照カウントをインクリメントします。参照カウントのインクリメントが必要でない限り、広く使われていて PyTypeObject* 型のポインタを返す表記法 o->ob_type の代わりに使う理由は全くありません。

int PyObject_TypeCheck( PyObject *o, PyTypeObject *type)

オブジェクト o が、 type か type のサブタイプであるときに真を返します。どちらのパラメタも NULL であってはなりません。

Py_ssize_t PyObject_Size( PyObject *o)
Py_ssize_t PyObject_Length( PyObject *o)

o の長さを返します。ただしオブジェクト o がシーケンス型プロトコルとマップ型プロトコルの両方を提供している場合、シーケンスとしての長さを返します。エラーが生じると -1 を返します。 Python の式 len(o) と同じです。

Py_ssize_t PyObject_LengthHint( PyObject *o, Py_ssize_t default)

オブジェクト o の概算の長さを返します。 最初に実際の長さを、次に __length_hint__() を使って概算の長さを、そして最後にデフォルトの値を返そうとします。 この関数は Python の式 operator.length_hint(o, default) と同じです。

バージョン 3.4 で追加.

PyObject* PyObject_GetItem( PyObject *o, PyObject *key)
Return value: New reference.

オブジェクト key に対応する o の要素を返します。失敗すると NULL を返します。Python の式 o[key] と同じです。

int PyObject_SetItem( PyObject *o, PyObject *key, PyObject *v)

オブジェクト key を値 v に対応付けます。 失敗すると例外を送出し -1 を返します; 成功すると 0 を返します。 Python の文 o[key] = v と同じです。

int PyObject_DelItem( PyObject *o, PyObject *key)

オブジェクト o から key に関する対応付けを削除します。失敗すると -1 を返します。Python の文 del o[key] と同じです。

PyObject* PyObject_Dir( PyObject *o)
Return value: New reference.

この関数は Python の式 dir(o) と同じで、オブジェクトの変数名に割り当てている文字列からなるリスト (空の場合もあります) を返します。エラーの場合には NULL を返します。引数を NULL にすると、Python における dir() と同様に、現在のローカルな名前を返します; この場合、アクティブな実行フレームがなければ NULL を返しますが、 PyErr_Occurred() は偽を返します。

PyObject* PyObject_GetIter( PyObject *o)
Return value: New reference.

Python の式 iter(o) と同じです。引数にとったオブジェクトに対する新たなイテレータか、オブジェクトがすでにイテレータの場合にはオブジェクト自身を返します。オブジェクトが反復処理不可能であった場合には TypeError を送出して NULL を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »


数値型プロトコル (number protocol)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »

数値型プロトコル (number protocol)

int PyNumber_Check( PyObject *o)

オブジェクト o が数値型プロトコルを提供している場合に 1 を返し、そうでないときには偽を返します。この関数呼び出しは常に成功します。

PyObject* PyNumber_Add( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 と o2 を加算した結果を返し、失敗すると NULL を返します。Python の式 o1 + o2 と同じです。

PyObject* PyNumber_Subtract( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 から o2 を減算した結果を返し、失敗すると NULL を返します。Python の式 o1 - o2 と同じです。

PyObject* PyNumber_Multiply( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 と o2 を乗算した結果を返し、失敗すると NULL を返します。Python の式 o1 * o2 と同じです。

PyObject* PyNumber_MatrixMultiply( PyObject *o1, PyObject *o2)

成功すると o1 と o2 を行列乗算した結果を返し、失敗すると NULL を返します。 Python の式 o1 @ o2 と同じです。

バージョン 3.5 で追加.

PyObject* PyNumber_FloorDivide( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 を o2 で除算した切捨て値を返し、失敗すると NULL を返します。"旧仕様の" 整数間での除算と同じです。

PyObject* PyNumber_TrueDivide( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると、数学的な o1 の o2 による除算値に対する妥当な近似 (reasonable approximation) を返し、失敗すると NULL を返します。全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は "近似値" しか表現できません。このため、戻り値も近似になります。この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。

PyObject* PyNumber_Remainder( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 を o2 で除算した剰余を返し、失敗すると NULL を返します。Python の式 o1 % o2 と同じです。

PyObject* PyNumber_Divmod( PyObject *o1, PyObject *o2)
Return value: New reference.

組み込み関数 divmod() を参照してください。失敗すると NULL を返します。 Python の式 divmod(o1, o2) と同じです。

PyObject* PyNumber_Power( PyObject *o1, PyObject *o2, PyObject *o3)
Return value: New reference.

組み込み関数 pow() を参照してください。失敗すると NULL を返します。 Python の式 pow(o1, o2, o3) と同じです。 o3 はオプションです。 o3 を無視させたいなら、 Py_None を入れてください (o3 に NULL を渡すと、不正なメモリアクセスを引き起こすことがあります)。

PyObject* PyNumber_Negative( PyObject *o)
Return value: New reference.

成功すると o の符号反転を返し、失敗すると NULL を返します。Python の式 -o と同じです。

PyObject* PyNumber_Positive( PyObject *o)
Return value: New reference.

成功すると o を返し、失敗すると NULL を返します。Python の式 +o と同じです。

PyObject* PyNumber_Absolute( PyObject *o)
Return value: New reference.

成功すると o の絶対値を返し、失敗すると NULL を返します。Python の式 abs(o) と同じです。

PyObject* PyNumber_Invert( PyObject *o)
Return value: New reference.

成功すると o のビット単位反転 (bitwise negation) を返し、失敗すると NULL を返します。Python の式 ~o と同じです。

PyObject* PyNumber_Lshift( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 を o2 だけ左シフトした結果を返し、失敗すると NULL を返します。Python の式 o1 << o2 と同じです。

PyObject* PyNumber_Rshift( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 を o2 だけ右シフトした結果を返し、失敗すると NULL を返します。Python の式 o1 >> o2 と同じです。

PyObject* PyNumber_And( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 と o2 の "ビット単位論理積 (bitwise and)" を返し、失敗すると NULL を返します。Python の式 o1 & o2 と同じです。

PyObject* PyNumber_Xor( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 と o2 の "ビット単位排他的論理和 (bitwise exclusive or)" を返し、失敗すると NULL を返します。Python の式 o1 ^ o2 と同じです。

PyObject* PyNumber_Or( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 と o2 の "ビット単位論理和 (bitwise or)" を返し失敗すると NULL を返します。Python の式 o1 | o2 と同じです。

PyObject* PyNumber_InPlaceAdd( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 と o2 を加算した結果を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 += o2 と同じです。

PyObject* PyNumber_InPlaceSubtract( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 から o2 を減算した結果を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 -= o2 と同じです。

PyObject* PyNumber_InPlaceMultiply( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 と o2 を乗算した結果を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 *= o2 と同じです。

PyObject* PyNumber_InPlaceMatrixMultiply( PyObject *o1, PyObject *o2)

成功すると o1 と o2 を行列乗算した結果を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、 in-place 演算を行います。 Python の文 o1 @= o2 と同じです。

バージョン 3.5 で追加.

PyObject* PyNumber_InPlaceFloorDivide( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 を o2 で除算した切捨て値を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 //= o2 と同じです。

PyObject* PyNumber_InPlaceTrueDivide( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると、数学的な o1 の o2 による除算値に対する妥当な近似 (reasonable approximation) を返し、失敗すると NULL を返します。全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は "近似値" しか表現できません。このため、戻り値も近似になります。この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。o1 が in-place 演算をサポートする場合、in-place 演算を行います。

PyObject* PyNumber_InPlaceRemainder( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 を o2 で除算した剰余を返し、, 失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 %= o2 と同じです。

PyObject* PyNumber_InPlacePower( PyObject *o1, PyObject *o2, PyObject *o3)
Return value: New reference.

組み込み関数 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.

成功すると o1 を o2 だけ左シフトした結果を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 <<= o2 と同じです。

PyObject* PyNumber_InPlaceRshift( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 を o2 だけ右シフトした結果を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 >>= o2 と同じです。

PyObject* PyNumber_InPlaceAnd( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 と o2 の "ビット単位論理積 (bitwise and)" を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 &= o2 と同じです。

PyObject* PyNumber_InPlaceXor( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると 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.

成功すると o1 と o2 の "ビット単位論理和 (bitwise or)" を返し失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 |= o2 と同じです。

PyObject* PyNumber_Long( PyObject *o)
Return value: New reference.

成功すると o を整数に変換したものを返し、失敗すると NULL を返します。Python の式 int(o) と同じです。

PyObject* PyNumber_Float( PyObject *o)
Return value: New reference.

成功すると o を浮動小数点数に変換したものを返し、失敗すると NULL を返します。Python の式 float(o) と同じです。

PyObject* PyNumber_Index( PyObject *o)

o をPythonのint型に変換し、成功したらその値を返します。失敗したら NULL が返され、 TypeError 例外が送出されます。

PyObject* PyNumber_ToBase( PyObject *n, int base)

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)

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)

Returns 1 if o is an index integer (has the nb_index slot of the tp_as_number structure filled in), and 0 otherwise.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »


シーケンス型プロトコル (sequence protocol)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »

シーケンス型プロトコル (sequence protocol)

int PySequence_Check( PyObject *o)

オブジェクトがシーケンス型プロトコルを提供している場合は 1 を、そうでない場合は 0 を返します。 __getitem__() メソッドを持つ Python クラスについては、それらが dict のサブクラスでない限り、 1 を返すのに注意してください。そうなる理由は、一般的なケースではオブジェクトがどの種類のキーをサポートしているかを判別するのが不可能だからです。 この関数は常に成功します。

Py_ssize_t PySequence_Size( PyObject *o)
Py_ssize_t PySequence_Length( PyObject *o)

成功するとシーケンス o 中のオブジェクトの数を返し、失敗すると -1 を返します。これは、Python の式 len(o) と同じになります。

PyObject* PySequence_Concat( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると o1 と o2 の連結 (concatenation) を返し、失敗すると NULL を返します。Python の式 o1 + o2 と同じです。

PyObject* PySequence_Repeat( PyObject *o, Py_ssize_t count)
Return value: New reference.

成功するとオブジェクト o の count 回繰り返しを返し、失敗すると NULL を返します。Python の式 o * count と同じです。

PyObject* PySequence_InPlaceConcat( PyObject *o1, PyObject *o2)
Return value: New reference.

成功すると 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.

成功するとオブジェクト o の count 回繰り返しを返し、失敗すると NULL を返します。o が in-place 演算をサポートする場合、in-place 演算を行います。Python の式 o *= count と同じです。

PyObject* PySequence_GetItem( PyObject *o, Py_ssize_t i)
Return value: New reference.

成功すると o の i 番目の要素を返し、失敗すると NULL を返します。Python の式 o[i] と同じです。

PyObject* PySequence_GetSlice( PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Return value: New reference.

成功すると o の i1 から i2 までの間のスライスを返し、失敗すると NULL を返します。Python の式 o[i1:i2] と同じです。

int PySequence_SetItem( PyObject *o, Py_ssize_t i, PyObject *v)

o の i 番目の要素に v を代入します。 失敗すると、例外を送出し -1 を返します; 成功すると 0 を返します。 これは Python の文 o[i] = v と同じです。 この関数は v への参照を 盗み取りません 。

v が NULL の場合はその要素が削除されますが、この機能は非推奨であり、 PyObject_DelAttr() を使うのが望ましいです。

int PySequence_DelItem( PyObject *o, Py_ssize_t i)

o の i 番目の要素を削除します。失敗すると -1 を返します。Python の文 del o[i] と同じです。

int PySequence_SetSlice( PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)

o の i1 から i2 までの間のスライスに v を代入します。Python の文 o[i1:i2] = v と同じです。

int PySequence_DelSlice( PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

シーケンスオブジェクト o の i1 から i2 までの間のスライスを削除します。失敗すると -1 を返します。Python の文 del o[i1:i2] と同じです。

Py_ssize_t PySequence_Count( PyObject *o, PyObject *value)

o における value の出現回数、すなわち o[key] == value となる key の個数を返します。失敗すると -1 を返します。Python の式 o.count(value) と同じです。

int PySequence_Contains( PyObject *o, PyObject *value)

o に value が入っているか判定します。o のある要素が value と等価 (equal) ならば 1 を返し、それ以外の場合には 0 を返します。エラーが発生すると -1 を返します。Python の式 value in o と同じです。

Py_ssize_t PySequence_Index( PyObject *o, PyObject *value)

o[i] == value となる最初に見つかったインデクス i を返します。エラーが発生すると -1 を返します。Python の式 o.index(value) と同じです。

PyObject* PySequence_List( PyObject *o)
Return value: New reference.

シーケンスもしくはイテラブル o と同じ内容を持つリストオブジェクトを返します。 失敗したら NULL を返します。 返されるリストは新しく作られたことが保証されています。 これは Python の式 list(o) と同等です。

PyObject* PySequence_Tuple( PyObject *o)
Return value: New reference.

シーケンスあるいはイテラブルである o と同じ内容を持つタプルオブジェクトを返します。 失敗したら NULL を返します。o がタプルの場合、新たな参照を返します。 それ以外の場合、適切な内容が入ったタプルを構築して返します。 Pythonの式 tuple(o) と同等です。

PyObject* PySequence_Fast( PyObject *o, const char *m)
Return value: New reference.

シーケンスかイテラブルの o をリストとして返します。 o が既にタプルかリストだった場合は o をそのまま返します。 返されたタプルのメンバにアクセスするには PySequence_Fast_GET_ITEM() を使います。 失敗すると NULL を返します。 オブジェクトがシーケンスやイテラブルでなければ、 m をメッセージテキストにとする TypeError を送出します。

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() ですが、 o への PySequence_Check() が真になるかチェックせず、負のインデクスに対する調整を行いません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »


マップ型プロトコル (mapping protocol)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »

マップ型プロトコル (mapping protocol)

PyObject_GetItem(), PyObject_SetItem(), PyObject_DelItem() も参照してください。

int PyMapping_Check( PyObject *o)

オブジェクトがマップ型プロトコルを提供しているか、スライスをサポートしている場合は 1 を、そうでない場合は 0 を返します。 __getitem__() メソッドを持つ Python クラスについては 1 を返すのに注意してください。そうなる理由は、一般的なケースではオブジェクトがどの種類のキーをサポートしているかを判別するのが不可能だからです。

Py_ssize_t PyMapping_Size( PyObject *o)
Py_ssize_t PyMapping_Length( PyObject *o)

成功するとオブジェクト o 中のキーの数を返し、失敗すると -1 を返します。これは、Python の式 len(o) と同じになります。

PyObject* PyMapping_GetItemString( PyObject *o, const char *key)
Return value: New reference.

文字列 key に対応する o の要素を返します。失敗すると NULL を返します。 Python の式 o[key] と同じです。 PyObject_GetItem() も参照してください。

int PyMapping_SetItemString( PyObject *o, const char *key, PyObject *v)

オブジェクト o 上で文字列 key を値 v に対応付けます。失敗すると -1 を返します。 Python の文 o[key] = v と同じです。 PyObject_SetItem() も参照してください。

int PyMapping_DelItem( PyObject *o, PyObject *key)

オブジェクト o から、オブジェクト key に関する対応付けを削除します。 失敗すると -1 を返します。 Python の文 del o[key] と同じです。 この関数は PyObject_DelItem() の別名です。

int PyMapping_DelItemString( PyObject *o, const char *key)

オブジェクト o から、文字列 key に関する対応付けを削除します。 失敗すると -1 を返します。 Python の文 del o[key] と同じです。

int PyMapping_HasKey( PyObject *o, PyObject *key)

マップ型オブジェクトがキー key を持つ場合に 1 を返し、そうでないときには 0 を返します。これは、Python の式 key in o と等価です。この関数呼び出しは常に成功します。

int PyMapping_HasKeyString( PyObject *o, const char *key)

マップ型オブジェクトがキー key を持つ場合に 1 を返し、そうでないときには 0 を返します。これは、Python の式 key in o と等価です。この関数呼び出しは常に成功します。

PyObject* PyMapping_Keys( PyObject *o)
Return value: New reference.

成功するとオブジェクト o のキーからなるリストを返します。 失敗すると NULL を返します。

バージョン 3.7 で変更: 以前は、関数はリストもしくはタプルを返していました。

PyObject* PyMapping_Values( PyObject *o)
Return value: New reference.

成功するとオブジェクト o の値からなるリストを返します。 失敗すると NULL を返します。

バージョン 3.7 で変更: 以前は、関数はリストもしくはタプルを返していました。

PyObject* PyMapping_Items( PyObject *o)
Return value: New reference.

成功するとオブジェクト o の要素からなるリストを返し、各要素はキーと値のペアが入ったタプルになっています。 失敗すると NULL を返します。

バージョン 3.7 で変更: 以前は、関数はリストもしくはタプルを返していました。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »


イテレータプロトコル (iterator protocol)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »

イテレータプロトコル (iterator protocol)

イテレータを扱うための固有の関数は二つあります。

int PyIter_Check( PyObject *o)

o がイテレータプロトコルをサポートする場合に真を返します。

PyObject* PyIter_Next( PyObject *o)
Return value: New reference.

反復処理 o における次の値を返します。オブジェクトはイテレータでなければなりません (これをチェックするのは呼び出し側の責任です)。要素が何も残っていない場合は、例外がセットされていない状態で NULL を返します。要素を取り出す際にエラーが生じた場合は、NULL を返し、発生した例外を送出します。

イテレータの返す要素にわたって反復処理を行うループを書くと、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 */
}

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »


バッファプロトコル (buffer Protocol)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »

バッファプロトコル (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() を参照してください。

Py_buffer
void *buf

バッファフィールドが表している論理構造の先頭を指すポインタ。バッファを提供するオブジェクトの下層物理メモリブロック中のどの位置にもなりえます。たとえば、たとえば strides が負だと、この値はメモリブロックの末尾かもしれません。

連続 配列の場合この値はメモリブロックの先頭を指します。

void *obj

エクスポートされているオブジェクトの新しい参照。参照は消費者によって所有され、PyBuffer_Release() によって自動的にデクリメントされて NULL に設定されます。このフィールドは標準的なC-API 関数の戻り値と等価です。

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

メモリがN次元配列を表している時の次元数。 0 の場合、 buf はスカラ値を表す1つの要素を指しています。 この場合、 shape, strides, suboffsets は NULL でなければなりません。

PyBUF_MAX_NDIM は次元数の最大値を64に制限しています。 提供側はこの制限を尊重しなければなりません。 多次元配列の消費側は 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 といった配列をバッファを開放するときに同時に解放するべきかどうかを管理するフラグに使うことができるでしょう。バッファを受け取る側は、この値を決して変更してはなりません。

バッファリクエストのタイプ

バッファは通常、 PyObject_GetBuffer() を使うことで、エクスポートするオブジェクトにバッファリクエストを送ることで得られます。メモリの論理的な構造の複雑性は多岐にわたるため、消費者は flags 引数を使って、自身が扱えるバッファの種類を指定します。

Py_buffer の全フィールドは、リクエストの種類によって曖昧さを残さずに定義されます。

リクエストに依存しないフィールド

下記のフィールドは 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)

Return 1 if obj supports the buffer interface otherwise 0. When 1 is returned, it doesn't guarantee that PyObject_GetBuffer() will succeed.

int PyObject_GetBuffer( PyObject *exporter, Py_buffer *view, int flags)

exporter に flags で指定された方法で view を埋めるように要求します。 もし exporter が指定されたとおりにバッファを提供できない場合、 PyExc_BufferError を送出し、 view->obj を NULL に設定した上で、 -1 を返さなければなりません。

成功したときは、 view を埋め、 view->obj に exporter への新しい参照を設定し、0を返します。チェイン状のバッファプロバイダがリクエストを単一のオブジェクトにリダイレクトするケースでは、 view->obj は exporter の代わりにこのオブジェクトを参照します (バッファオブジェクト構造体 を参照してください)。

malloc() と free() のように、呼び出しに成功した PyObject_GetBuffer() と対になる PyBuffer_Release() の呼び出しがなけれなればなりません。 従って、バッファの利用が済んだら PyBuffer_Release() が厳密に1回だけ呼び出されなければなりません。

void PyBuffer_Release( Py_buffer *view)

バッファ view を解放し、 view->obj の参照カウントを1つ減らします。 この関数はバッファが使われることがなくなったときに呼び出さなければならず、そうしないと参照のリークが起こり得ます。

PyObject_GetBuffer() を通して取得していないバッファに対してこの関数を呼び出すのは間違いです。

Py_ssize_t PyBuffer_SizeFromFormat(const char *)

itemsize の値を format から計算して返します。 この関数はまだ実装されていません。

int PyBuffer_IsContiguous( Py_buffer *view, char order)

Return 1 if the memory defined by the view is C-style (order is 'C') or Fortran-style (order is 'F') contiguous or either one (order is 'A'). Return 0 otherwise.

int PyBuffer_ToContiguous(void *buf, Py_buffer *src, Py_ssize_t len, char order)

src から len バイトを連続表現で buf 上にコピーします。 order は 'C' または 'F' (C スタイルまたは Fortran スタイルの順序) が指定できます。 成功したら 0 が返り、エラーなら -1 が返ります。

len != src->len の場合、この関数は失敗します。

void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)

strides 配列を、 itemsize の大きさの要素がバイト単位の、 shape の形をした連続な (contiguous) (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)

サイズが len の buf を readonly に従った書き込み可/不可の設定で公開するバッファリクエストを処理します。 buf は符号無しバイトの列として解釈されます。

flags 引数はリクエストのタイプを示します。 この関数は、 buf が読み出し専用と指定されていて、 flags に PyBUF_WRITABLE が設定されていない限り、常にフラグに指定された通りに view を埋めます。

成功したときは、 view->obj に exporter への新しい参照を設定し、 0 を返します。 失敗したときは、 PyExc_BufferError を送出し、 view->obj に NULL を設定し、 -1 を返します;

この関数を getbufferproc の一部として使う場合には、 exporter はエクスポートするオブジェクトに設定しなければならず、さらに flags は変更せずに渡さなければなりません。 そうでない場合は、 exporter は NULL でなければなりません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »


古いバッファプロトコル

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »

古いバッファプロトコル

バージョン 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)

文字ベースの入力として使える読み出し専用メモリ上の位置へのポインタを返します。 obj 引数は単一セグメントからなる文字バッファインタフェースをサポートしていなければなりません。成功すると 0 を返し、 buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、 TypeError をセットします。

int PyObject_AsReadBuffer( PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)

任意のデータを収めた読み出し専用のメモリ上の位置へのポインタを返します。 obj 引数は単一セグメントからなる読み出し可能バッファインタフェースをサポートしていなければなりません。成功すると 0 を返し、 buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、 TypeError をセットします。

int PyObject_CheckReadBuffer( PyObject *o)

Returns 1 if o supports the single-segment readable buffer interface. Otherwise returns 0.

int PyObject_AsWriteBuffer( PyObject *obj, void **buffer, Py_ssize_t *buffer_len)

書き込み可能なメモリ上の位置へのポインタを返します。 obj 引数は単一セグメントからなる文字バッファインタフェースをサポートしていなければなりません。成功すると 0 を返し、 buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、 TypeError をセットします。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 抽象オブジェクトレイヤ (abstract objects layer) »


具象オブジェクト (concrete object) レイヤ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

具象オブジェクト (concrete object) レイヤ

この章では、特定の Python オブジェクト型固有の関数について述べています。これらの関数に間違った型のオブジェクトを渡すのは良い考えではありません; Python プログラムから何らかのオブジェクトを受け取ったとき、そのオブジェクトが正しい型になっているか確信をもてないのなら、まず型チェックを行わなければなりません; 例えば、あるオブジェクトが辞書型か調べるには、 PyDict_Check() を使います。この章は Python のオブジェクト型における "家計図" に従って構成されています。

警告

この章で述べている関数は、渡されたオブジェクトの型を注意深くチェックしはするものの、多くの関数は渡されたオブジェクトが有効な NULL なのか有効なオブジェクトなのかをチェックしません。これらの関数に NULL を渡させてしまうと、関数はメモリアクセス違反を起こして、インタプリタを即座に終了させてしまうはずです。

基本オブジェクト (fundamental object)

この節では、Python の型オブジェクトとシングルトン(singleton)オブジェクト None について述べます。

  • 型オブジェクト
  • None オブジェクト

数値型オブジェクト (numeric object)

  • 整数型オブジェクト (integer object)
  • Boolean オブジェクト
  • 浮動小数点型オブジェクト (floating point object)
  • 複素数オブジェクト (complex number object)
    • C 構造体としての複素数
    • Python オブジェクトとしての複素数型

シーケンスオブジェクト (sequence object)

シーケンスオブジェクトに対する一般的な操作については前の章ですでに述べました; この節では、Python 言語にもともと備わっている特定のシーケンスオブジェクトについて扱います。

  • バイトオブジェクト
  • bytearray オブジェクト
    • 型チェックマクロ
    • ダイレクト API 関数
    • マクロ
  • Unicode オブジェクトと codec
    • Unicode オブジェクト
      • Unicode 型
      • Unicode 文字プロパティ
      • Unicode 文字列の生成とアクセス
      • 廃止予定の Py_UNICODE API群
      • ロケールエンコーディング
      • ファイルシステムエンコーディング
      • 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)
  • コードオブジェクト

その他のオブジェクト

  • ファイルオブジェクト
  • モジュールオブジェクト (module object)
    • Cモジュールの初期化
      • 一段階初期化
      • 多段階初期化
      • 低水準モジュール作成関数
      • サポート関数
    • モジュール検索
  • イテレータオブジェクト (iterator object)
  • デスクリプタオブジェクト (descriptor object)
  • スライスオブジェクト (slice object)
  • Ellipsis オブジェクト
  • memoryview オブジェクト
  • 弱参照オブジェクト
  • カプセル
  • ジェネレータオブジェクト
  • コルーチンオブジェクト
  • コンテキスト変数オブジェクト
  • DateTime オブジェクト

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


型オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

型オブジェクト

PyTypeObject

組み込み型を記述する際に用いられる、オブジェクトを表す C 構造体です。

PyObject* PyType_Type

型オブジェクト自身の型オブジェクトです; Python レイヤにおける type と同じオブジェクトです。

int PyType_Check( PyObject *o)

オブジェクト o が型オブジェクトの場合に真を返します。標準型オブジェクトから派生したサブタイプのインスタンスも含みます。その他の場合には偽を返します。

int PyType_CheckExact( PyObject *o)

オブジェクト o が型オブジェクトの場合に真を返します。標準型のサブタイプの場合は含みません。その他の場合には偽を返します。

unsigned int PyType_ClearCache()

内部の検索キャッシュをクリアします。現在のバージョンタグを返します。

unsigned long PyType_GetFlags( PyTypeObject* type)

type のメンバーである tp_flags を返します。この関数は基本的に Py_LIMITED_API を定義して使うことを想定しています。それぞれのフラグはpythonの異なるリリースで安定していることが保証されていますが、 tp_flags 自体は限定されたAPIの一部ではありません。

バージョン 3.2 で追加.

バージョン 3.4 で変更: The return type is now unsigned long rather than long.

void PyType_Modified( PyTypeObject *type)

内部の検索キャッシュを、その type とすべてのサブタイプに対して無効にします。この関数は type の属性や基底クラス列を変更したあとに手動で呼び出さなければなりません。

int PyType_HasFeature( PyTypeObject *o, int feature)

型オブジェクト o に、型機能 feature が設定されている場合に真を返します。型機能は各々単一ビットのフラグで表されます。

int PyType_IS_GC( PyTypeObject *o)

型オブジェクトが o が循環参照検出をサポートしている場合に真を返します; この関数は型機能フラグ Py_TPFLAGS_HAVE_GC の設定状態をチェックします。

int PyType_IsSubtype( PyTypeObject *a, PyTypeObject *b)

a が b のサブタイプの場合に真を返します。

この関数は実際のサブクラスをチェックするだけです。つまり、 __subclasscheck__() は b に対し呼ばれません。 issubclass() と同じチェックをするには PyObject_IsSubclass() を呼んでください。

PyObject* PyType_GenericAlloc( PyTypeObject *type, Py_ssize_t nitems)
Return value: New reference.

型オブジェクトの tp_alloc に対するジェネリックハンドラです。 Python のデフォルトのメモリアロケートメカニズムを使って新しいインスタンスをアロケートし、すべての内容を NULL で初期化します。

PyObject* PyType_GenericNew( PyTypeObject *type, PyObject *args, PyObject *kwds)
Return value: New reference.

型オブジェクトの tp_new に対するジェネリックハンドラです。型の tp_alloc スロットを使って新しいインスタンスを作成します。

int PyType_Ready( PyTypeObject *type)

型オブジェクトのファイナライズを行います。この関数は全てのオブジェクトで初期化を完了するために呼び出されなくてはなりません。この関数は、基底クラス型から継承したスロットを型オブジェクトに追加する役割があります。成功した場合には 0 を返し、エラーの場合には -1 を返して例外情報を設定します。

PyObject* PyType_FromSpec(PyType_Spec *spec)

関数引数に与えられた spec からヒープタイプのオブジェクトを作って返します。

PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)

spec からヒープタイプのオブジェクトを生成して返します。加えて、生成されたヒープタイプは bases タプルが保持するすべての型を基底の型として保持します。他のヒープ型を基底型として参照できます。

バージョン 3.3 で追加.

void* PyType_GetSlot( PyTypeObject *type, int slot)

与えられたスロットに格納されている関数ポインタを返します。返り値が NULL の場合は、スロットが NULL か、関数が不正な引数で呼ばれたことを示します。通常、呼び出し側は返り値のポインタを適切な関数型にキャストします。

バージョン 3.4 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


None オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

None オブジェクト

None に対する PyTypeObject は、 Python/C API では直接公開されていないので注意してください。 None は単量子 (singleton) なので、オブジェクトの同一性テスト (C では ==) を使うだけで十分だからです。同じ理由から、 PyNone_Check() 関数はありません。

PyObject* Py_None

Python における None オブジェクトで、値がないことを表します。このオブジェクトにはメソッドがありません。参照カウントについては、このオブジェクトも他のオブジェクトと同様に扱う必要があります。

Py_RETURN_NONE

C 関数からの Py_None の返却を適切に扱います。 (これは None の参照カウントをインクリメントして返します。)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


整数型オブジェクト (integer object)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

整数型オブジェクト (integer object)

すべての整数は任意の長さをもつ "long" 整数として実装されます。

On error, most PyLong_As* APIs return (return type)-1 which cannot be distinguished from a number. Use PyErr_Occurred() to disambiguate.

PyLongObject

この PyObject のサブタイプは整数型を表現します。

PyTypeObject PyLong_Type

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

v から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。

現在の実装では、-5 から 256 までの全ての整数に対する整数オブジェクトの配列を保持するようにしており、この範囲の数を生成すると、実際には既存のオブジェクトに対する参照が返るようになっています。従って、1 の値を変えることすら可能です。変えてしまった場合の Python の挙動は未定義です :-)

PyObject* PyLong_FromUnsignedLong(unsigned long v)
Return value: New reference.

Cの unsigned long から新たな PyLongObject オブジェクトを生成して返します。失敗した際には NULL を返します。

PyObject* PyLong_FromSsize_t(Py_ssize_t v)

C の Py_ssize_t 型から新たな PyLongObject オブジェクトを生成して返します。 失敗のときには NULL を返します。

PyObject* PyLong_FromSize_t(size_t v)

C の size_t 型から新たな PyLongObject オブジェクトを生成して返します。 失敗のときには NULL を返します。

PyObject* PyLong_FromLongLong(long long v)
Return value: New reference.

C の long long 型から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。

PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
Return value: New reference.

C の unsigned long long 型から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。

PyObject* PyLong_FromDouble(double v)
Return value: New reference.

v の整数部から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。

PyObject* PyLong_FromString(const char *str, char **pend, int base)
Return value: New reference.

str の文字列値に基づいて、新たな PyLongObject を返します。 このとき base を基数として文字列を解釈します。 pend が NULL でない場合は、 *pend は str 中で数が表現されている部分以降の先頭文字のアドレスを指しています。 base が 0 の場合は、 str は 整数リテラル の定義を使って解釈されます; この場合では、先頭に 0 がある 0 でない十進数は ValueError を送出します。 base が 0 でなければ、 base は 2 以上 36 以下の数でなければなりません。 先頭の空白、基数の指定の後や数字の間にある単一のアンダースコアは無視されます。 数字が全くない場合、 ValueError が送出されます。

PyObject* PyLong_FromUnicode( Py_UNICODE *u, Py_ssize_t length, int base)
Return value: New reference.

Unicode 数値列を Python 整数値に変換します。Unicode 文字列はまず PyUnicode_EncodeDecimal() を用いてバイト文字列にエンコードされ、次に PyLong_FromString() を用いて変換されます。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyLong_FromUnicodeObject() を使用するように移行してください。

PyObject* PyLong_FromUnicodeObject( PyObject *u, int base)

u 文字列中の Unicode 数値列を Python 整数値に変換します。Unicode 文字列はまず PyUnicode_EncodeDecimal() を用いてバイト文字列にエンコードされ、次に PyLong_FromString() を用いて変換されます。

バージョン 3.3 で追加.

PyObject* PyLong_FromVoidPtr(void *p)
Return value: New reference.

ポインタ p から Python 整数値を生成します。ポインタの値は PyLong_AsVoidPtr() を適用した結果から取得されます。

long PyLong_AsLong( PyObject *obj)

obj が表す、Cの long 表現を返します。もし obj が PyLongObject のインスタンスでなければ、まず、その __int__() メソッドを (もしあれば) 呼び出して、オブジェクトを PyLongObject に変換します。

もし obj の値が long の範囲外であれば、 OverflowError を送出します。

Returns -1 on error. Use PyErr_Occurred() to disambiguate.

long PyLong_AsLongAndOverflow( PyObject *obj, int *overflow)

obj が表す、Cの long 表現を返します。もし obj が PyLongObject のインスタンスでなければ、まず、その __int__() メソッドを (もしあれば) 呼び出して、オブジェクトを PyLongObject に変換します。

もし、 obj の値が LONG_MAX より大きいか、 LONG_MIN より小さければ、 *overflow は、それぞれ 1 か -1 に設定され、 -1 を返します; さもなければ *overflow は 0 に設定されます。もし、ほかの例外が発生した場合は *overflow が 0 に設定され -1 を返します。

Returns -1 on error. Use PyErr_Occurred() to disambiguate.

long long PyLong_AsLongLong( PyObject *obj)

obj が表す、Cの long long 表現を返します。もし obj が PyLongObject のインスタンスでなければ、まず、その __int__() メソッドを (もしあれば) 呼び出して、オブジェクトを PyLongObject に変換します。

もし obj の値が long の範囲外であれば、 OverflowError を送出します。

Returns -1 on error. Use PyErr_Occurred() to disambiguate.

long long PyLong_AsLongLongAndOverflow( PyObject *obj, int *overflow)

obj が表す、Cの long long 表現を返します。もし obj が PyLongObject のインスタンスでなければ、まず、その __int__() メソッドを (もしあれば) 呼び出して、オブジェクトを PyLongObject に変換します。

もし、 obj の値が PY_LLONG_MAX より大きいか、 PY_LLONG_MIN より小さければ、 *overflow は、それぞれ 1 か -1 に設定され、 -1 を返します; さもなければ *overflow は 0 に設定されます。もし、ほかの例外が発生した場合は *overflow が 0 に設定され -1 を返します。

Returns -1 on error. Use PyErr_Occurred() to disambiguate.

バージョン 3.2 で追加.

Py_ssize_t PyLong_AsSsize_t( PyObject *pylong)

pylong を表す C の Py_ssize_t を返します。 pylong は PyLongObject のインスタンスでなければなりません。

もし pylong の値が Py_ssize_t の範囲外であれば、 OverflowError を送出します。

Returns -1 on error. Use PyErr_Occurred() to disambiguate.

unsigned long PyLong_AsUnsignedLong( PyObject *pylong)

pylong を表す C の unsigned long を返します。 pylong は PyLongObject のインスタンスでなければなりません。

もし pylong の値が unsigned long の範囲外であれば、 OverflowError を送出します。

Returns (unsigned long)-1 on error. Use PyErr_Occurred() to disambiguate.

size_t PyLong_AsSize_t( PyObject *pylong)

pylong を表す C の size_t を返します。 pylong は PyLongObject のインスタンスでなければなりません。

もし pylong の値が size_t の範囲外であれば、 OverflowError を送出します。

Returns (size_t)-1 on error. Use PyErr_Occurred() to disambiguate.

unsigned long long PyLong_AsUnsignedLongLong( PyObject *pylong)

pylong を表す C の unsigned long long を返します。 pylong は PyLongObject のインスタンスでなければなりません。

もし pylong の値が unsigned long long の範囲外であれば、 OverflowError を送出します。

Returns (unsigned long long)-1 on error. Use PyErr_Occurred() to disambiguate.

バージョン 3.1 で変更: 負 pylong を指定した際に TypeError ではなく、 OverflowError を送出するようになりました。

unsigned long PyLong_AsUnsignedLongMask( PyObject *obj)

obj が表す、C の unsigned long 表現を返します。もし obj が PyLongObject のインスタンスでなければ、まず、その __int__() メソッドを (もしあれば) 呼び出して、オブジェクトを PyLongObject に変換します。

obj の値が unsigned long の範囲から外れていた場合は、 ULONG_MAX + 1 を法とした剰余を返します。

Returns -1 on error. Use PyErr_Occurred() to disambiguate.

unsigned long long PyLong_AsUnsignedLongLongMask( PyObject *obj)

obj が表す、C の unsigned long long 表現を返します。もし obj が PyLongObject のインスタンスでなければ、まず、その __int__() メソッドを (もしあれば) 呼び出して、オブジェクトを PyLongObject に変換します。

obj の値が unsigned long long の範囲から外れていた場合は、 PY_ULLONG_MAX + 1 を法とした剰余を返します。

Returns -1 on error. Use PyErr_Occurred() to disambiguate.

double PyLong_AsDouble( PyObject *pylong)

pylong を表す C の double を返します。 pylong は PyLongObject のインスタンスでなければなりません。

もし pylong の値が double の範囲外であれば、 OverflowError を送出します。

Returns -1.0 on error. Use PyErr_Occurred() to disambiguate.

void* PyLong_AsVoidPtr( PyObject *pylong)

Python の整数型を指す pylong を、 C の void ポインタに変換します。 pylong を変換できなければ、 OverflowError を送出します。この関数は PyLong_FromVoidPtr() で値を生成するときに使うような void ポインタ型を生成できるだけです。

Returns NULL on error. Use PyErr_Occurred() to disambiguate.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


Boolean オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

Boolean オブジェクト

Python の Bool 型は整数のサブクラスとして実装されています。ブール型の値は、 Py_False と Py_True の 2 つしかありません。従って、通常の生成／削除関数はブール型にはあてはまりません。とはいえ、以下のマクロが利用できます。

int PyBool_Check( PyObject *o)

o が PyBool_Type の場合に真を返します。

PyObject* Py_False

Python における False オブジェクトです。このオブジェクトはメソッドを持ちません。参照カウントの点では、他のオブジェクトと同様に扱う必要があります。

PyObject* Py_True

Python における True オブジェクトです。このオブジェクトはメソッドを持ちません。参照カウントの点では、他のオブジェクトと同様に扱う必要があります。

Py_RETURN_FALSE

Py_False に適切な参照カウントのインクリメントを行って、関数から返すためのマクロです。

Py_RETURN_TRUE

Py_True に適切な参照カウントのインクリメントを行って、関数から返すためのマクロです。

PyObject* PyBool_FromLong(long v)
Return value: New reference.

v の値に応じて Py_True または Py_False への新しい参照を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


浮動小数点型オブジェクト (floating point object)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

浮動小数点型オブジェクト (floating point object)

PyFloatObject

この PyObject のサブタイプは Python 浮動小数点オブジェクトを表現します。

PyTypeObject PyFloat_Type

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

str の文字列値をもとに PyFloatObject オブジェクトを生成します。失敗すると NULL を返します。

PyObject* PyFloat_FromDouble(double v)
Return value: New reference.

v から PyFloatObject オブジェクトを生成して返します。失敗すると NULL を返します。

double PyFloat_AsDouble( PyObject *pyfloat)

pyfloat の指す値を、 C の double 型表現で返します。 pyfloat が Python 浮動小数点オブジェクトではなく、かつ __float__() メソッドを持っていれば、 pyfloat を浮動小数点に変換するためにこのメソッドが最初に呼ばれます。失敗した場合 -1.0 を返します。そのため呼び出し元は PyErr_Occurred() を呼んでエラーをチェックすべきです。

double PyFloat_AS_DOUBLE( PyObject *pyfloat)

pyfloat の指す値を、 C の double 型表現で返しますが、エラーチェックを行いません。

PyObject* PyFloat_GetInfo(void)

float の精度、最小値、最大値に関する情報を含む structseq インスタンスを返します。これは、 float.h ファイルの薄いラッパーです。

double PyFloat_GetMax()

float の表現できる最大限解値 DBL_MAX を C の double 型で返します。

double PyFloat_GetMin()

float の正規化された最小の正の値 DBL_MIN を C の double 型で返します。

int PyFloat_ClearFreeList()

float の free list をクリアします。解放できなかったアイテム数を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


複素数オブジェクト (complex number object)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

複素数オブジェクト (complex number object)

Python の複素数オブジェクトは、C API 側から見ると二つの別個の型として実装されています: 一方は Python プログラムに対して公開されている Python のオブジェクトで、他方は実際の複素数値を表現する C の構造体です。API では、これら双方を扱う関数を提供しています。

C 構造体としての複素数

複素数の C 構造体を引数として受理したり、戻り値として返したりする関数は、ポインタ渡しを行うのではなく 値渡し を行うので注意してください。これは API 全体を通して一貫しています。

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 complex)

複素数 complex の符号反転 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 オブジェクトとしての複素数型

PyComplexObject

この PyObject のサブタイプは Python の複素数型を表現します。

PyTypeObject PyComplex_Type

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

新たな PyComplexObject オブジェクトを real と imag から生成します。

double PyComplex_RealAsDouble( PyObject *op)

op の実数部分を C の double 型で返します。

double PyComplex_ImagAsDouble( PyObject *op)

op の虚数部分を C の double 型で返します。

Py_complex PyComplex_AsCComplex( PyObject *op)

複素数値 op から Py_complex 型を生成します。

op が Python の複素数オブジェクトではないが、 __complex__() メソッドを持っていた場合、このメソッドが最初に呼ばれ、 op が Python の複素数オブジェクトに変換されます。エラーが起きた場合は、このメソッドは実数の -1.0 を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


バイトオブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

バイトオブジェクト

下記の関数は、バイトオブジェクトを期待している引数にバイトオブジェクトでないパラメタを指定して呼び出されると、 TypeError を送出します。

PyBytesObject

この PyObject のサブタイプは、Python バイトオブジェクトを表します。

PyTypeObject PyBytes_Type

この PyTypeObject のインスタンスは、Python バイト型を表します; Pythonレイヤの bytes と同じオブジェクトです。

int PyBytes_Check( PyObject *o)

オブジェクト o がバイトオブジェクトか、またはbytes型のサブタイプのインスタンスである場合に真を返します。

int PyBytes_CheckExact( PyObject *o)

オブジェクト o がバイトオブジェクトであり、かつbytes型のサブタイプのインスタンスでない場合に真を返します。

PyObject* PyBytes_FromString(const char *v)

成功時に、文字列 v のコピーを値とする新しいバイトオブジェクトを返し、失敗時に NULL を返します引数 v は NULL であってはなりません; そのチェックは行われません。

PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)

成功時に、文字列 v のコピーを値とする長さ len の新しいバイトオブジェクトを返し、失敗時に NULL を返します。引数 v が NULL の場合、バイトオブジェクトの中身は初期化されていません。

PyObject* PyBytes_FromFormat(const char *format, ...)

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) For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion flag has effect even when a precision is given.
PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)

ちょうど２つの引数を取ることを除いて、 PyBytes_FromFormat() と同じです。

PyObject* PyBytes_FromObject( PyObject *o)

バッファプロトコルを実装するオブジェクト o のバイト表現を返します。

Py_ssize_t PyBytes_Size( PyObject *o)

バイトオブジェクト o のバイト単位の長さを返します。

Py_ssize_t PyBytes_GET_SIZE( PyObject *o)

PyBytes_Size() をマクロで実装したもので、エラーチェックをを行いません。

char* PyBytes_AsString( PyObject *o)

o の中身へのポインタを返します。ポインタは o のコピーではなく、len(o) + 1 からなる内部バッファを参照します。 他に 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)

obj のnull 終端された中身を、出力用の変数 buffer と length を介して返します。

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)

newpart の内容を bytes の後ろに連結した新しいバイトオブジェクトを *bytes に生成します; 呼び出し側は新しい参照を所有します。 bytes の古い値の参照は盗まれます。 もし新しいオブジェクトが生成できない場合、古い bytes の参照は放棄され、 *bytes の値は NULL に設定されます; 適切な例外が設定されます。

void PyBytes_ConcatAndDel( PyObject **bytes, PyObject *newpart)

newpart の内容を bytes の後ろに連結した新しいバイトオブジェクトを *bytes に生成します; この関数は、 newpart の参照カウントをデクリメントします。

int _PyBytes_Resize( PyObject **bytes, Py_ssize_t newsize)

本来 "変更不可能 (immutable)" なバイトオブジェクトをリサイズする方法です。 作成されたばかりのバイトオブジェクトにのみこれをしようしてください; 他のコードですでに使用されている可能性のあるバイトオブジェクトに使用してはいけません。 入力されたバイトオブジェクトの参照カウントが 1 でない場合、この関数はエラーになります。 左辺値として存在する (つまり書き込み可能な) バイトオブジェクトのアドレスを受け取り、新しいサイズを要求します。 成功時には、*bytes はリサイズされたバイトオブジェクトを保持し、0 が返されます; *bytes のアドレスは入力された際のアドレスと異なるかもしれません。 再割り当て (reallocation) が失敗した場合、 *bytes が元々指してしたバイトオブジェクトを解放し、*bytes を NULL に設定し、 MemoryError を設定し、そして -1 が返されます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


bytearray オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

bytearray オブジェクト

PyByteArrayObject

この PyObject のサブタイプは Python の bytearray オブジェクトを表します。

PyTypeObject PyByteArray_Type

この PyTypeObject のインスタンスは、 Python bytearray 型を示します。 Python レイヤでの bytearray と同じオブジェクトです。

型チェックマクロ

int PyByteArray_Check( PyObject *o)

o が bytearray かそのサブタイプのインスタンスだった場合に真を返します。

int PyByteArray_CheckExact( PyObject *o)

o が bytearray オブジェクトで、そのサブタイプのインスタンスでは無いときに、真を返します。

ダイレクト API 関数

PyObject* PyByteArray_FromObject( PyObject *o)

buffer protocol を実装した任意のオブジェクト o から、新しいbytearrayオブジェクトを作成し、返します。

PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)

string とその長さ len から新しい bytearray オブジェクトを返します。失敗した場合は NULL を返します。

PyObject* PyByteArray_Concat( PyObject *a, PyObject *b)

bytearray a と b を連結した結果を新しい bytearray として返します。

Py_ssize_t PyByteArray_Size( PyObject *bytearray)

NULL ポインタチェックの後に bytearray のサイズを返します。

char* PyByteArray_AsString( PyObject *bytearray)

NULL ポインタチェックの後に bytearray の内容を char 配列として返します。返される配列には、常に余分な null バイトが追加されます。

int PyByteArray_Resize( PyObject *bytearray, Py_ssize_t len)

bytearray の内部バッファを len へリサイズします。

マクロ

以下のマクロは、ポインタのチェックをしないことにより安全性を犠牲にしてスピードを優先しています。

char* PyByteArray_AS_STRING( PyObject *bytearray)

PyByteArray_AsString() のマクロバージョン。

Py_ssize_t PyByteArray_GET_SIZE( PyObject *bytearray)

PyByteArray_Size() のマクロバージョン。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


Unicode オブジェクトと codec

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

Unicode オブジェクトと codec

Unicode オブジェクト

Python3.3 の PEP 393 実装から、メモリ効率を維持しながらUnicode文字の完全な範囲を扱えるように、Unicodeオブジェクトは内部的に多様な表現形式を用いています。すべてのコードポイントが128、256または65536以下の文字列に対して特別なケースが存在しますが、それ以外ではコードポイントは1114112以下(これはすべてのUnicode範囲です)でなければなりません。

Py_UNICODE* 表現形式および UTF-8表現形式はオンデマンドで作成され、Unicode オブジェクト内にキャッシュされます。Py_UNICODE* 表現は推奨されず、非効率ですので、重要なタスクを実行し、メモリを消費している状況下では避けるべきです。

古いAPI群と新しいAPI群での変換のために、ユニコードオブジェクトは、オブジェクトがどのように生成されたかによって、内部的に２つの状態を持ちます。

  • "正統な" unicode オブジェクトは、非推奨ではないunicode APIで作成されたすべてのオブジェクトです。これらのオブジェクトは実装が許すかぎり最も効率の良い表現形式を使用します。
  • "古い" unicode オブジェクトは、非推奨の API (たいていは PyUnicode_FromUnicode()) で作成されたオブジェクトで、 Py_UNICODE* 表現形式しか持ってません; 他の API を呼び出す前に、このオブジェクトに対し PyUnicode_READY() を呼び出す必要があるでしょう。

Unicode 型

以下は Python の Unicode 実装に用いられている基本 Unicode オブジェクト型です:

Py_UCS4
Py_UCS2
Py_UCS1

これらの型は、それぞれ、32ビット、16ビット、そして8ビットの文字を保持するのに充分な幅を持つ符号なしの整数型のtypedefです。単一のUnicode文字を扱う場合は、 Py_UCS4 を用いてください。

バージョン 3.3 で追加.

Py_UNICODE

これは、wchar_t のtypedef で、プラットフォームに依存して16ビットか32ビットの型になります。

バージョン 3.3 で変更: 以前のバージョンでは、Pythonをビルドした際に "narrow" または "wide" Unicode バージョンのどちらを選択したかによって、 16ビットか32ビットのどちらかの型になっていました。

PyASCIIObject
PyCompactUnicodeObject
PyUnicodeObject

これらの PyObject のサブタイプは Python Unicode オブジェクトを表現します。 Unicode オブジェクトを扱う全ての API 関数は PyObject へのポインタを受け取って PyObject へのポインタを返すので、ほとんどの場合、これらの型を直接使うべきではありません。

バージョン 3.3 で追加.

PyTypeObject PyUnicode_Type

この PyTypeObject のインスタンスは、Python Unicode型を表します。これは、Pythonコードに str として露出されます。

以下の API は実際には C マクロで、Unicode オブジェクト内部の読み取り専用データに対するチェックやアクセスを高速に行います:

int PyUnicode_Check( PyObject *o)

o が Unicode 文字列型か Unicode 文字列型のサブタイプであるときに真を返します。

int PyUnicode_CheckExact( PyObject *o)

o が Unicode 文字列型で、かつ Unicode 文字列型のサブタイプでないときに真を返します。

int PyUnicode_READY( PyObject *o)

文字列オブジェクト o が "正統な" 表現形式であることを保証します。 このマクロは、下で説明しているどのアクセスマクロを使うときも必要となります。

成功のときには 0 を返し、失敗のときには例外を設定し -1 を返します。 後者は、メモリ確保に失敗したときに特に起きやすいです。

バージョン 3.3 で追加.

Py_ssize_t PyUnicode_GET_LENGTH( PyObject *o)

Unicode 文字列のコードポイントでの長さを返します。 o は "正統な" 表現形式の Unicode オブジェクトでなければなりません (ただしチェックはしません)。

バージョン 3.3 で追加.

Py_UCS1* PyUnicode_1BYTE_DATA( PyObject *o)
Py_UCS2* PyUnicode_2BYTE_DATA( PyObject *o)
Py_UCS4* PyUnicode_4BYTE_DATA( PyObject *o)

文字に直接アクセスするために、 UCS1, UCS2, UCS4 のいずれかの整数型にキャストされた正統な表現形式へのポインタを返します。
正統な表現が適正な文字サイズになっているかどうかのチェックはしません;
PyUnicode_KIND() を使って正しいマクロを選んでください。
このオブジェクトにアクセスする前に、忘れずに PyUnicode_READY() を呼び出してください。

バージョン 3.3 で追加.

PyUnicode_WCHAR_KIND
PyUnicode_1BYTE_KIND
PyUnicode_2BYTE_KIND
PyUnicode_4BYTE_KIND

PyUnicode_KIND() マクロの返り値です。

バージョン 3.3 で追加.

int PyUnicode_KIND( PyObject *o)

この Unicode がデータを保存するのに1文字あたり何バイト使っているかを示す PyUnicode 種別の定数 (上を読んでください) のうち1つを返します。 o は "正統な" 表現形式の Unicode オブジェクトでなければなりません (ただしチェックはしません)。

バージョン 3.3 で追加.

void* PyUnicode_DATA( PyObject *o)

生の unicode バッファへの void ポインタを返します。 o は "正統な" 表現形式の Unicode オブジェクトでなければなりません (ただしチェックはしません)。

バージョン 3.3 で追加.

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)

正統な表現形式となっている (PyUnicode_DATA() で取得した) data に書き込みます。 このマクロは正常性のチェックを一切行わない、ループで使われるためのものです。 呼び出し側は、他のマクロを呼び出して取得した kind 値と data ポインタをキャッシュすべきです。 index は文字列の (0始まりの) インデックスで、 value はその場所に書き込まれることになる新しいコードポイントの値です。

バージョン 3.3 で追加.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)

正統な表現形式となっている (PyUnicode_DATA() で取得した) data からコードポイントを読み取ります。 チェックや事前確認のマクロ呼び出しは一切行われません。

バージョン 3.3 で追加.

Py_UCS4 PyUnicode_READ_CHAR( PyObject *o, Py_ssize_t index)

Unicode オブジェクト o から文字を読み取ります。 この Unicode オブジェクトは "正統な" 表現形式でなければなりません。 何度も連続して読み取る場合には、このマクロは PyUnicode_READ() よりも非効率的です。

バージョン 3.3 で追加.

PyUnicode_MAX_CHAR_VALUE( PyObject *o)

o に基づいて他の文字列を作るのに適した最大のコードポイントを返します。 この Unicode オブジェクトは "正統な" 表現形式でなければなりません。 この値は常に概算値ですが、文字列全体を調べるよりも効率的です。

バージョン 3.3 で追加.

int PyUnicode_ClearFreeList()

free list をクリアします。解放された要素数を返します。

Py_ssize_t PyUnicode_GET_SIZE( PyObject *o)

非推奨の Py_UNICODE 表現形式のサイズをコード単位で返します (サロゲートペアを2つとしています)。 o は Unicode オブジェクトでなければなりません (ただしチェックはしません)。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Unicode APIの一部なので、 PyUnicode_GET_LENGTH() を使用するように移行してください。

Py_ssize_t PyUnicode_GET_DATA_SIZE( PyObject *o)

非推奨の Py_UNICODE 表現形式のサイズをバイト単位で返します。 o は Unicode オブジェクトでなければなりません (ただしチェックはしません)。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Unicode APIの一部なので、 PyUnicode_GET_LENGTH() を使用するように移行してください。

Py_UNICODE* PyUnicode_AS_UNICODE( PyObject *o)
const char* PyUnicode_AS_DATA( PyObject *o)

与えられたオブジェクトの Py_UNICODE 表現形式へのポインタを返します。 返されるバッファは常に終端に null コードポイントが1つ余分に付いています。 それとは別の null コードポイントがバッファに含まれることもあるかもしれませんが、たいていの C 関数ではそのような文字列は切り詰められてしまうでしょう。 AS_DATA の方はポインタを const char * にキャストしています。 引数 o は Unicode オブジェクトでなければなりません (ただしチェックはしません)。

バージョン 3.3 で変更: このマクロは今では非効率なものになりました。 というのも、多くのケースで Py_UNICODE 表現形式が登場せず、作成されず、そして失敗し得ます (例外を設定して NULL を返します)。 コードを修正して、 PyUnicode_nBYTE_DATA() マクロを使うか PyUnicode_WRITE() や PyUnicode_READ() を使うようにしてください。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Unicode APIの一部なので、 PyUnicode_nBYTE_DATA() 系のマクロを使用するように移行してください。

Unicode 文字プロパティ

Unicode は数多くの異なる文字プロパティ (character property) を提供しています。よく使われる文字プロパティは、以下のマクロで利用できます。これらのマクロは Python の設定に応じて、各々 C の関数に対応付けられています。

int Py_UNICODE_ISSPACE( Py_UNICODE ch)

ch が空白文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISLOWER( Py_UNICODE ch)

ch が小文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISUPPER( Py_UNICODE ch)

ch が大文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISTITLE( Py_UNICODE ch)

ch がタイトルケース文字 (titlecase character) かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISLINEBREAK( Py_UNICODE ch)

ch が改行文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISDECIMAL( Py_UNICODE ch)

ch が decimal 文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISDIGIT( Py_UNICODE ch)

ch が digit 文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISNUMERIC( Py_UNICODE ch)

ch が数字 (numeric) 文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISALPHA( Py_UNICODE ch)

ch がアルファベット文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISALNUM( Py_UNICODE ch)

ch が英数文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISPRINTABLE( Py_UNICODE ch)

ch が文字が印字可能な文字かどうかに基づいて 1 または 0 を返します。 非印字可能文字は、 Unicode 文字データベースで "Other" または "Separator" と定義されている文字の、印字可能と見なされる ASCII space (0x20) 以外のものです。 (なお、この文脈での印字可能文字は、文字列に repr() が呼び出されるときにエスケープすべきでない文字のことです。これは sys.stdout や sys.stderr に書き込まれる文字列の操作とは関係ありません。)

以下の API は、高速に直接文字変換を行うために使われます:

Py_UNICODE Py_UNICODE_TOLOWER( Py_UNICODE ch)

ch を小文字に変換したものを返します。

バージョン 3.3 で非推奨: この関数は単純な大文字小文字変換を使ってます。

Py_UNICODE Py_UNICODE_TOUPPER( Py_UNICODE ch)

ch を大文字に変換したものを返します。

バージョン 3.3 で非推奨: この関数は単純な大文字小文字変換を使ってます。

Py_UNICODE Py_UNICODE_TOTITLE( Py_UNICODE ch)

ch をタイトルケース文字に変換したものを返します。

バージョン 3.3 で非推奨: この関数は単純な大文字小文字変換を使ってます。

int Py_UNICODE_TODECIMAL( Py_UNICODE ch)

ch を 10 進の正の整数に変換したものを返します。不可能ならば -1 を返します。このマクロは例外を送出しません。

int Py_UNICODE_TODIGIT( Py_UNICODE ch)

ch を一桁の 2 進整数に変換したものを返します。不可能ならば -1 を返します。このマクロは例外を送出しません。

double Py_UNICODE_TONUMERIC( Py_UNICODE ch)

ch を double に変換したものを返します。不可能ならば -1.0 を返します。このマクロは例外を送出しません。

これらの API はサロゲートにも使えます:

Py_UNICODE_IS_SURROGATE(ch)

ch がサロゲートかどうか (0xD800 <= ch <= 0xDFFF) をチェックします。

Py_UNICODE_IS_HIGH_SURROGATE(ch)

ch が上位サロゲートかどうか (0xD800 <= ch <= 0xDBFF) をチェックします。

Py_UNICODE_IS_LOW_SURROGATE(ch)

ch が下位サロゲートかどうか (0xDC00 <= ch <= 0xDFFF) をチェックします。

Py_UNICODE_JOIN_SURROGATES(high, low)

2つのサロゲート文字を組み合わせて単一の Py_UCS4 値を返します。 high と low はそれぞれサロゲートペアの前半分と後半分です。

Unicode 文字列の生成とアクセス

Unicode オブジェクトを生成したり、Unicode のシーケンスとしての基本的なプロパティにアクセスしたりするには、以下の API を使ってください:

PyObject* PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

新しい Unicode オブジェクトを生成します。 maxchar は文字列に並べるコードポイントの正しい最大値にすべきです。 その値は概算値として 127, 255, 65535, 1114111 の一番近い値に切り上げられます。

これは新しい Unicode オブジェクトを生成する推奨された方法です。 この関数を使って生成されたオブジェクトはサイズ変更は不可能です。

バージョン 3.3 で追加.

PyObject* PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)

与えられた kind (取り得る値は PyUnicode_1BYTE_KIND などの PyUnicode_KIND() が返す値です) の Unicode オブジェクトを生成します。 buffer は、与えられた kind に従って1文字あたり 1, 2, 4 バイトのいずれかを単位として、長さ size の配列へのポインタでなければなりません。

バージョン 3.3 で追加.

PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)

char 型バッファ u から Unicode オブジェクトを生成します。 u の内容は UTF-8 でエンコードされているものとします。 バッファの内容は新たなオブジェクトにコピーされます。 バッファが NULL でない場合、帰り値は共有されたオブジェクトになることがあります。 つまり、この関数が返す Unicode オブジェクトの変更は許されていません。

u が NULL の場合は、この関数は PyUnicode_FromUnicode() でバッファ u を NULL にセットしたのと同じように振る舞います。 この関数は非推奨です。変わりに PyUnicode_New() を使ってください。

PyObject *PyUnicode_FromString(const char *u)

UTF-8 エンコードされたnull終端のchar 型バッファ u から Unicode オブジェクトを生成します。

PyObject* PyUnicode_FromFormat(const char *format, ...)

printf() スタイルの format 文字列と可変長引数を受け取り、結果の unicode 文字の長さを計算し、フォーマットされた文字列を含む unicode オブジェクトを返します。可変長引数は C の型を持っていて、 format ASCII エンコード文字列で指定された書式指定文字に完全に従う必要があります。以下の書式指定文字が利用できます:

書式指定文字 | 型 | 備考
%% n/a リテラルの % 文字
%c | int | C の整数型で表現される単一の文字。
%d | int | printf("%d") と同等。 [1]
%u | unsigned int | printf("%u") と同等。 [1]
%ld | long | printf("%ld") と同等。 [1]
%li | long | printf("%li") と同等。 [1]
%lu | unsigned long | printf("%lu") と同等。 [1]
%lld | long long | printf("%lld") と同等。 [1]
%lli | long long | printf("%lli") と同等。 [1]
%llu | unsigned long long | printf("%llu") と同等。 [1]
%zd | Py_ssize_t | printf("%zd") と同等。 [1]
%zi | Py_ssize_t | printf("%zi") と同等。 [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 が付きます。
%A | PyObject* | ascii() の戻り値。
%U | PyObject* | unicode オブジェクト。
%V | PyObject*, const char* | unicode オブジェクト(NULL でも良い)と、 2つめの引数として NUL 終端の C 文字列 (2つめの引数は1つめの引数が NULL だった時にのみ利用されます)。
%S | PyObject* | PyObject_Str() の戻り値。
%R | PyObject* | PyObject_Repr() の戻り値。

識別できない書式指定文字があった場合、残りの書式文字列はそのまま出力文字列にコピーされ、残りの引数は無視されます。

注釈

幅フォーマッタの単位はバイト数ではなく文字数です。 精度フォーマッタの単位は、 "%s" と (PyObject* 引数が NULL の場合の) "%V" ではバイト数、 "%A", "%U", "%S", "%R" および (PyObject* 引数が NULL でない場合の) "%V" では文字数です。

[1] (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13) For integer specifiers (d, u, ld, li, lu, lld, lli, llu, zd, zi, zu, i, x): the 0-conversion flag has effect even when a precision is given.

バージョン 3.2 で変更: "%lld", "%llu" のサポートが追加されました。

バージョン 3.3 で変更: "%li", "%lli", "%zi" のサポートが追加されました。

バージョン 3.4 で変更: "%s", "%A", "%U", "%V", "%S", "%R" での幅フォーマッタおよび精度フォーマッタのサポートが追加されました。

PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)

ちょうど２つの引数を取ることを除いて、 PyUnicode_FromFormat() と同じです。

PyObject* PyUnicode_FromEncodedObject( PyObject *obj, const char *encoding, const char *errors)
Return value: New reference.

エンコードされている 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)

Unicode オブジェクトの長さをコードポイントで返します。

バージョン 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 を返し、例外を設定します。そうでない場合は、コピーした文字数を返します。

バージョン 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 を返し例外を送出します。

バージョン 3.3 で追加.

int PyUnicode_WriteChar( PyObject *unicode, Py_ssize_t index, Py_UCS4 character)

文字列に文字を書き込みます。 文字列は PyUnicode_New() で作成しなければなりません。 Unicode 文字列は不変とされているので、この文字列は共有されていたり、これまでにハッシュ化されていてはいけません。

この関数は unicode が Unicode オブジェクトであること、インデックスが範囲内であること、オブジェクトが安全に変更できる (つまり参照カウントが1である) ことをチェックします。

バージョン 3.3 で追加.

Py_UCS4 PyUnicode_ReadChar( PyObject *unicode, Py_ssize_t index)

文字列から文字を読み取ります。 マクロ版の PyUnicode_READ_CHAR() とは対照的に、この関数は unicode が Unicode オブジェクトであること、インデックスが範囲内であることをチェックします。

バージョン 3.3 で追加.

PyObject* PyUnicode_Substring( PyObject *str, Py_ssize_t start, Py_ssize_t end)

str の文字インデックス start (端点を含む) から文字インデックス end (端点を含まず) までの部分文字列を返します。 負のインデックスはサポートされていません。

バージョン 3.3 で追加.

Py_UCS4* PyUnicode_AsUCS4( PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)

文字列 u を UCS4 のバッファへコピーします。 copy_null が設定されている場合は、ヌル文字も含めます。 エラーが起きたときは、 NULL を返し、例外を設定します (buflen が u の長さより短かった場合については、 SystemError が設定されます)。 成功したときは buffer を返します。

バージョン 3.3 で追加.

Py_UCS4* PyUnicode_AsUCS4Copy( PyObject *u)

文字列 u を PyMem_Malloc() でメモリ確保された新しい UCS4 型のバッファにコピーします。 これが失敗した場合は、 NULL を返し MemoryError をセットします。 返されたバッファは必ず null コードポイントが追加されています。

バージョン 3.3 で追加.

廃止予定の Py_UNICODE API群

Deprecated since version 3.3, will be removed in version 4.0.

これらのAPI 関数は PEP 393 の実装により廃止予定です。Python 3.x では削除されないため、拡張モジュールはこれらの関数を引き続き使えますが、これらの関数の使用はパフォーマンスとメモリに影響があることを念頭に置いてください。

PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
Return value: New reference.

size で指定された長さを持つ Py_UNICODE 型バッファ u から Unicode オブジェクトを生成します。 u を NULL にしてもよく、その場合オブジェクトの内容は未定義です。 バッファに必要な情報を埋めるのはユーザの責任です。 バッファの内容は新たなオブジェクトにコピーされます。

バッファが NULL でない場合、戻り値は共有されたオブジェクトになることがあります。 従って、この関数が返す Unicode オブジェクトを変更してよいのは u が NULL のときだけです。

バッファが NULL の場合、文字列の内容が埋められたなら PyUnicode_KIND() のようなアクセスマクロを使う前に PyUnicode_READY() を呼び出さなければなりません。

PyUnicode_FromKindAndData(), PyUnicode_New(), PyUnicode_FromWideChar() のいずれかを使用するように移行してください。

Py_UNICODE* PyUnicode_AsUnicode( PyObject *unicode)

Unicode オブジェクトの Py_UNICODE 型の内部バッファへの読み出し専用のポインタを返すか、失敗のときには NULL を返します。 オブジェクトの Py_UNICODE* 表現形式が無い場合には作成します。 結果の Py_UNICODE 文字列には null コードポイントが含まれていることがあり、たいていの C 関数では、そのような文字列は切り詰められてしまうことに注意してください。

PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() や類似の新しい API を使用するように移行してください。

PyObject* PyUnicode_TransformDecimalToASCII( Py_UNICODE *s, Py_ssize_t size)

与えられた長さ size を持つ Py_UNICODE 型のバッファにある全ての decimal digit を、それらの10進の値に対応する 0 から 9 までの ASCII 数字に置き換えた Unicode オブジェクトを生成します。 例外が起きた場合は NULL を返します。

Py_UNICODE* PyUnicode_AsUnicodeAndSize( PyObject *unicode, Py_ssize_t *size)

PyUnicode_AsUnicode() に似てますが、さらに (追加の null 終端子を除いた) Py_UNICODE() 配列の長さを size に保存します。 結果の Py_UNICODE 文字列には null コードポイントが含まれていることがあり、たいていの C 関数では、そのような文字列は切り詰められてしまうことに注意してください。

バージョン 3.3 で追加.

Py_UNICODE* PyUnicode_AsUnicodeCopy( PyObject *unicode)

終端に null コードポイントが付加された Unicode 文字列のコピーを作成します。 メモリ確保に失敗したときは NULL を返し MemoryError 例外を送出します。 そうでないときは新しくメモリ確保されたバッファを返します (このバッファを解放するときには PyMem_Free() を使ってください)。 結果の Py_UNICODE 文字列には null コードポイントが含まれていることがあり、たいていの C 関数では、そのような文字列は切り詰められてしまうことに注意してください。

バージョン 3.2 で追加.

PyUnicode_AsUCS4Copy() や類似の新しい API を使用するように移行してください。

Py_ssize_t PyUnicode_GetSize( PyObject *unicode)

非推奨の Py_UNICODE 表現形式のサイズをコード単位で返します (サロゲートペアを2つとしています)。

PyUnicode_GetLength() を使用するように移行してください。

PyObject* PyUnicode_FromObject( PyObject *obj)
Return value: New reference.

Unicode のサブタイプのインスタンスを、必要な場合は本物の Unicode オブジェクトにコピーします。 obj が (サブタイプではない) 既に本物の Unicode オブジェクトだった場合は、参照カウントを1つ増やした参照を返します。

Unicode やそのサブタイプ以外のオブジェクトでは TypeError が引き起こされます。

ロケールエンコーディング

現在のロケールエンコーディングはオペレーティングシステムのテキストをデコードするのに使えます。

PyObject* PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t len, const char *errors)

Android では UTF-8 の文字列を、それ以外のプラットフォームでは現在のロケールエンコーディングの文字列をデコードします。 サポートされているエラーハンドラは "strict" および "surrogateescape" ( PEP 383) です。 errors が NULL の場合は、デコーダは "strict" エラーハンドラを使用します。 str は終端が null 文字でなければならず、 null 文字を含めることはできません。

PyUnicode_DecodeFSDefaultAndSize() を使って (Python の起動時に読み込まれるロケールエンコーディングの) Py_FileSystemDefaultEncoding の文字列をデコードします。

この関数は Python の UTF-8 モードを無視します。

参考

Py_DecodeLocale() 関数。

バージョン 3.3 で追加.

バージョン 3.7 で変更: この関数は、 Android 以外では現在のロケールエンコーディングを surrogateescape エラーハンドラで使うようになりました。 以前は、 Py_DecodeLocale() が surrogateescape で使われ、現在のロケールエンコーディングは strict で使われていました。

PyObject* PyUnicode_DecodeLocale(const char *str, const char *errors)

PyUnicode_DecodeLocaleAndSize() と似てますが、 strlen() を使って文字列の長さを計算します。

バージョン 3.3 で追加.

PyObject* PyUnicode_EncodeLocale( PyObject *unicode, const char *errors)

Android では UTF-8 で、それ以外のプラットフォームでは現在のロケールエンコーディングで Unicode オブジェクトをエンコードします。 サポートされているエラーハンドラは "strict" および "surrogateescape" ( PEP 383) です。 errors が NULL の場合は、エンコーダは "strict" エラーハンドラを使用します。 bytes オブジェクトを返します。 unicode には null 文字を含められません。

PyUnicode_EncodeFSDefault() を使って (Python の起動時に読み込まれるロケールエンコーディングの) Py_FileSystemDefaultEncoding の文字列へエンコードします。

この関数は Python の UTF-8 モードを無視します。

参考

Py_EncodeLocale() 関数。

バージョン 3.3 で追加.

バージョン 3.7 で変更: この関数は、 Android 以外では現在のロケールエンコーディングを surrogateescape エラーハンドラで使うようになりました。 以前は、 Py_EncodeLocale() が surrogateescape で使われ、現在のロケールエンコーディングは strict で使われていました。

ファイルシステムエンコーディング

ファイル名や他の環境文字列のエンコードやデコードを行うには、 Py_FileSystemDefaultEncoding をエンコーディングとして使い、 Py_FileSystemDefaultEncodeErrors をエラーハンドラとして使うべきです ( PEP 383 および PEP 529)。 引数の構文解析中にファイル名を bytes にエンコードするには、 "O&" コンバーターを使い、 PyUnicode_FSConverter() を変換関数として渡すべきです:

int PyUnicode_FSConverter( PyObject* obj, void* result)

ParseTuple コンバーター: PyUnicode_EncodeFSDefault() を使い -- 直接あるいは os.PathLike インターフェースを通して取得した -- str オブジェクトを bytes へエンコードします; bytes オブジェクトはそのまま出力されます。 result は PyBytesObject* でなければならず、使われなくなったときには解放されなければなりません。

バージョン 3.1 で追加.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

引数の構文解析中にファイル名を str にデコードするには、 "O&" コンバーターを使い、 PyUnicode_FSDecoder() を変換関数として渡すのがよいです:

int PyUnicode_FSDecoder( PyObject* obj, void* result)

ParseTuple コンバーター: PyUnicode_DecodeFSDefaultAndSize() を使い -- 直接的あるいは間接的に os.PathLike インターフェースを通して取得した -- bytes オブジェクトを str へエンコードします; bytes オブジェクトはそのまま出力されます。 result は PyUnicodeObject* でなければならず、使われなくなったときには解放されなければなりません。

バージョン 3.2 で追加.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)

Py_FileSystemDefaultEncoding と Py_FileSystemDefaultEncodeErrors エラーハンドラを使い、文字列をデコードします。

Py_FileSystemDefaultEncoding が設定されていない場合は、ロケールエンコーディングに差し戻されます。

Py_FileSystemDefaultEncoding は起動時にロケールエンコーディングで初期化され、それ以降は変更できません。 現在のロケールエンコーディングで文字列をデコードする必要がある場合は、 PyUnicode_DecodeLocaleAndSize() を使ってください。

参考

Py_DecodeLocale() 関数。

バージョン 3.6 で変更: Py_FileSystemDefaultEncodeErrors エラーハンドラを使うようになりました。

PyObject* PyUnicode_DecodeFSDefault(const char *s)

Py_FileSystemDefaultEncoding と Py_FileSystemDefaultEncodeErrors エラーハンドラを使い、 null 終端文字列をデコードします。

Py_FileSystemDefaultEncoding が設定されていない場合は、ロケールエンコーディングに差し戻されます。

文字列の長さが分かっている場合は、 PyUnicode_DecodeFSDefaultAndSize() を使ってください。

バージョン 3.6 で変更: Py_FileSystemDefaultEncodeErrors エラーハンドラを使うようになりました。

PyObject* PyUnicode_EncodeFSDefault( PyObject *unicode)

Py_FileSystemDefaultEncoding エラーハンドラで Unicode オブジェクトを Py_FileSystemDefaultEncoding にエンコードし、 bytes を返します。 返される bytes オブジェクトは null バイトを含んでいるかもしれないことに注意してください。

Py_FileSystemDefaultEncoding が設定されていない場合は、ロケールエンコーディングに差し戻されます。

Py_FileSystemDefaultEncoding は起動時にロケールエンコーディングで初期化され、それ以降は変更できません。 現在のロケールエンコーディングで文字列をエンコードする必要がある場合は、 PyUnicode_EncodeLocale() を使ってください。

参考

Py_EncodeLocale() 関数。

バージョン 3.2 で追加.

バージョン 3.6 で変更: Py_FileSystemDefaultEncodeErrors エラーハンドラを使うようになりました。

wchar_t サポート

wchar_t をサポートするプラットフォームでの wchar_t サポート:

PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
Return value: New reference.

size の wchar_t バッファ w から Unicode オブジェクトを生成します。 size として -1 を渡すことで、 wcslen を使い自身で長さを計算しなければならないことを関数に指示します。 失敗すると NULL を返します。

Py_ssize_t PyUnicode_AsWideChar( PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)

Unicode オブジェクトの内容を wchar_t バッファ w にコピーします。 最大で size 個の wchar_t 文字を (末尾の null 終端文字を除いて) コピーします。 コピーした wchar_t 文字の個数を返します。エラーの時には -1 を返します。 wchar_t 文字列は null 終端されている場合も、されていない場合もあります。 関数の呼び出し側の責任で、アプリケーションの必要に応じて wchar_t 文字列を null 終端してください。 また、結果の wchar_t* 文字列には文字列の途中にも null 文字が含まれていることがあり、たいていの C 関数では、そのような文字列は切り詰められてしまうことに注意してください。

wchar_t* PyUnicode_AsWideCharString( PyObject *unicode, Py_ssize_t *size)

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_Alloc() (use PyMem_Free() to free it) on success. On error, returns NULL and *size is undefined. Raises a MemoryError if memory allocation is failed.

バージョン 3.2 で追加.

バージョン 3.7 で変更: size が NULL かつ wchar_t* 文字列が null 文字を含んでいた場合、 ValueError を送出します。

組み込み codec (built-in codec)

Python には、処理速度を高めるために C で書かれた codec が揃えてあります。これら全ての codec は以下の関数を介して直接利用できます。

以下の API の多くが、 encoding と errors という二つの引数をとります。これらのパラメータは、組み込みの文字列コンストラクタである str() における同名のパラメータと同じ意味を持ちます。

encoding を NULL にすると、デフォルトエンコーディングである ASCII を使います。 ファイルシステムに関する関数の呼び出しでは、ファイル名に対するエンコーディングとして PyUnicode_FSConverter() を使わねばなりません。 これは内部で変数 Py_FileSystemDefaultEncoding を使用しています。 この変数は読み出し専用の変数として扱わねばなりません: この変数は、あるシステムによっては静的な文字列に対するポインタであったり、また別のシステムでは、(アプリケーションが setlocale を呼んだときなどに) 変わったりもします。

errors で指定するエラー処理もまた、 NULL を指定できます。 NULL を指定すると、codec で定義されているデフォルト処理の使用を意味します。全ての組み込み codec で、デフォルトのエラー処理は "strict" (ValueError を送出する) になっています。

個々の codec は全て同様のインタフェースを使っています。個別の codec の説明では、説明を簡単にするために以下の汎用のインタフェースとの違いだけを説明しています。

汎用 codec

以下は汎用 codec の API です:

PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
Return value: New reference.

size バイトのエンコードされた文字列 s をデコードして Unicode オブジェクトを生成します。 encoding と errors は、組み込み関数 str() の同名のパラメータと同じ意味を持ちます。 使用する codec の検索は、 Python の codec レジストリを使って行います。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsEncodedString( PyObject *unicode, const char *encoding, const char *errors)
Return value: New reference.

Unicode オブジェクトをエンコードし、その結果を Python の bytes オブジェクトとして返します。 encoding および errors は Unicode 型の encode() メソッドに与える同名のパラメータと同じ意味を持ちます。 使用する codec の検索は、 Python の codec レジストリを使って行います。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
Return value: New reference.

size で指定されたサイズの Py_UNICODE バッファ s をエンコードした Python の bytes オブジェクトを返します。 encoding および errors は Unicode 型の encode() メソッドに与える同名のパラメータと同じ意味を持ちます。 使用する codec の検索は、 Python の codec レジストリを使って行います。 codec が例外を送出した場合には NULL を返します。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsEncodedString() を使用するように移行してください。

UTF-8 Codecs

以下は UTF-8 codec の APIです:

PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference.

UTF-8 でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
Return value: New reference.

consumed が NULL の場合、 PyUnicode_DecodeUTF8() と同じように動作します。 consumed が NULL でない場合、 PyUnicode_DecodeUTF8Stateful() は末尾の不完全な UTF-8 バイト列をエラーとみなしません。これらのバイト列はデコードされず、デコードされたバイト数を consumed に返します。

PyObject* PyUnicode_AsUTF8String( PyObject *unicode)
Return value: New reference.

UTF-8 で Unicode オブジェクトをエンコードし、結果を Python バイト列オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

const char* PyUnicode_AsUTF8AndSize( PyObject *unicode, Py_ssize_t *size)

Unicode オブジェクトを UTF-8 でエンコードしたものへのポインタを返し、エンコードされた表現形式でのサイズ (バイト単位) を size に格納します。 size 引数は NULL でも構いません; その場合はサイズは格納されません。 返されるバッファには、 null コードポイントがあるかどうかに関わらず、常に null バイトが終端に付加されています (これは size には勘定されません)。

エラーが起きた場合は、 NULL を返し、例外を設定し、 size には何も格納しません。

この関数は、 Unicode オブジェクトの文字列の UTF-8 表現形式をキャッシュし、それ以降の呼び出しでは同じバッファへのポインタを返します。 呼び出し側にバッファを解放する責任はありません。

バージョン 3.3 で追加.

バージョン 3.7 で変更: 返り値の型が char * ではなく const char * になりました。

const char* PyUnicode_AsUTF8( PyObject *unicode)

PyUnicode_AsUTF8AndSize() とほぼ同じですが、サイズを格納しません。

バージョン 3.3 で追加.

バージョン 3.7 で変更: 返り値の型が char * ではなく const char * になりました。

PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Return value: New reference.

与えられたサイズの Py_UNICODE バッファ s を UTF-8 でエンコードして、 Python の bytes オブジェクトとして返します。 codec が例外を発生させたときは NULL を返します。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsUTF8String(), PyUnicode_AsUTF8AndSize(), PyUnicode_AsEncodedString() のいずれかを使用するように移行してください。

UTF-32 Codecs

以下は UTF-32 codec API です:

PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

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 *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

consumed が NULL のとき、 PyUnicode_DecodeUTF32() と同じように振る舞います。 consumed が NULL でないとき、 PyUnicode_DecodeUTF32Stateful() は末尾の不完全な (4 で割り切れない長さのバイト列などの) UTF-32 バイト列をエラーとして扱いません。末尾の不完全なバイト列はデコードされず、デコードされたバイト数が consumed に格納されます。

PyObject* PyUnicode_AsUTF32String( PyObject *unicode)

ネイティブバイトオーダーで UTF-32 エンコーディングされた Python バイト文字列を返します。 文字列は常に BOM マークで始まります。 エラーハンドラは "strict" です。 codec が例外を発生させたときは NULL を返します。

PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

s の Unicode データを UTF-32 にエンコードし、その値を Python の bytes オブジェクトに格納して返します。 出力は以下のバイトオーダーで従って書かれます:

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

byteorder が 0 のとき、出力文字列は常に Unicode BOM マーク (U+FEFF) で始まります。それ以外の2つのモードでは、先頭に BOM マークは出力されません。

Py_UNICODE_WIDE が定義されていない場合は、サロゲートペアを 1 つのコードポイントとして出力します。

codec が例外を発生させたときは NULL を返します。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsUTF32String() または PyUnicode_AsEncodedString() を使用するように移行してください。

UTF-16 Codecs

以下は UTF-16 codec の APIです:

PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
Return value: New reference.

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 *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
Return value: New reference.

consumed が NULL の場合、 PyUnicode_DecodeUTF16() と同じように動作します。 consumed が NULL でない場合、 PyUnicode_DecodeUTF16Stateful() は末尾の不完全な UTF-16 バイト列 (奇数長のバイト列や分割されたサロゲートペア) をエラーとみなしません。これらのバイト列はデコードされず、デコードされたバイト数を consumed に返します。

PyObject* PyUnicode_AsUTF16String( PyObject *unicode)
Return value: New reference.

ネイティブバイトオーダーで UTF-16 エンコーディングされた Python バイト文字列を返します。 文字列は常に BOM マークで始まります。 エラーハンドラは "strict" です。 codec が例外を発生させたときは NULL を返します。

PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
Return value: New reference.

s の Unicode データを UTF-16 にエンコードし、その値を Python の bytes オブジェクトに格納して返します。 出力は以下のバイトオーダーに従って書かれます:

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

byteorder が 0 のとき、出力文字列は常に Unicode BOM マーク (U+FEFF) で始まります。それ以外の2つのモードでは、先頭に BOM マークは出力されません。

Py_UNICODE_WIDE が定義されている場合、単一の Py_UNICODE 値はサロゲートペアとして表現されることがあります。 Py_UNICODE_WIDE が定義されていなければ、各 Py_UNICODE 値は UCS-2 文字として表現されます。

codec が例外を発生させたときは NULL を返します。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsUTF16String() または PyUnicode_AsEncodedString() を使用するように移行してください。

UTF-7 Codecs

以下は UTF-7 codec の API です:

PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)

UTF-7 でエンコードされた size バイトの文字列 s をデコードして Unicode オブジェクトを作成します。 codec が例外を発生させたときは NULL を返します。

PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

consumed が NULL のとき、 PyUnicode_DecodeUTF7() と同じように動作します。 consumed が NULL でないとき、末尾の不完全な UTF-7 base-64 部分をエラーとしません。不完全な部分のバイト列はデコードせずに、デコードしたバイト数を consumed に格納します。

PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)

与えられたサイズの Py_UNICODE バッファを UTF-7 でエンコードして、 Python の bytes オブジェクトとして返します。 codec が例外を発生させたときは NULL を返します。

base64SetO がゼロでないとき、 "Set O" 文字 (他の場合には何も特別な意味を持たない句読点) を base-64 エンコードします。 base64WhiteSpace がゼロでないとき、空白文字を base-64 エンコードします。 Python の "utf-7" codec では、両方ともゼロに設定されています。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsEncodedString() を使用するように移行してください。

Unicode-Escape Codecs

以下は "Unicode Escape" codec の API です:

PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference.

Unicode-Escape でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsUnicodeEscapeString( PyObject *unicode)
Return value: New reference.

Unicode-Escape を使い Unicode オブジェクトをエンコードし、結果を bytes オブジェクトとして返します。 エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
Return value: New reference.

Unicode-Escape を使い size で指定された長さを持つ Py_UNICODE 型バッファをエンコードし、 bytes オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsUnicodeEscapeString() を使用するように移行してください。

Raw-Unicode-Escape Codecs

以下は "Raw Unicode Escape" codec の APIです:

PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference.

Raw-Unicode-Escape でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsRawUnicodeEscapeString( PyObject *unicode)
Return value: New reference.

Raw-Unicode-Escape を使い Unicode オブジェクトをエンコードし、結果を bytes オブジェクトとして返します。 エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Return value: New reference.

Raw-Unicode-Escape を使い size で指定された長さを持つ Py_UNICODE 型バッファをエンコードし、 bytes オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsRawUnicodeEscapeString() または PyUnicode_AsEncodedString() を使用するように移行してください。

Latin-1 Codecs

以下は Latin-1 codec の APIです: Latin-1 は、 Unicode 序数の最初の 256 個に対応し、エンコード時にはこの 256 個だけを受理します。

PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference.

Latin-1 でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsLatin1String( PyObject *unicode)
Return value: New reference.

Latin-1 で Unicode オブジェクトをエンコードし、結果を Python bytes オブジェクトとして返します。 エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Return value: New reference.

size で指定された長さを持つ Py_UNICODE 型バッファを Latin-1 でエンコードし、 Python bytes オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsLatin1String() または PyUnicode_AsEncodedString() を使用するように移行してください。

ASCII Codecs

以下は ASCII codec の APIです。 7 ビットの ASCII データだけを受理します。その他のコードはエラーになります。

PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference.

ASCII でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsASCIIString( PyObject *unicode)
Return value: New reference.

ASCII で Unicode オブジェクトをエンコードし、結果を Python bytes オブジェクトとして返します。 エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Return value: New reference.

size で指定された長さを持つ Py_UNICODE 型バッファを ASCII でエンコードし、 Python bytes オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsASCIIString() または PyUnicode_AsEncodedString() を使用するように移行してください。

Character Map Codecs

この codec は、多くの様々な codec を実装する際に使われるという点で特殊な codec です (実際、 encodings パッケージに入っている標準 codecs のほとんどは、この codec を使っています)。 この codec は、文字のエンコードやデコードに対応表を使います。 提供される対応表のオブジェクトは __getitem__() マッピングインターフェースをサポートしていなければなりません; 辞書やシーケンスがそれに適しています。

以下は mapping codec の APIです:

PyObject* PyUnicode_DecodeCharmap(const char *data, Py_ssize_t size, PyObject *mapping, const char *errors)
Return value: New reference.

与えられた mapping オブジェクトを使って、 size バイトのエンコードされた文字列 s をデコードして 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.

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.

PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
Return value: New reference.

Encode the Py_UNICODE buffer of the given size using the given mapping object and return the result as a bytes object. Return NULL if an exception was raised by the codec.

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsCharmapString() または PyUnicode_AsEncodedString() を使用するように移行してください。

以下の codec API は Unicode から Unicode への対応付けを行う特殊なものです。

PyObject* PyUnicode_Translate( PyObject *unicode, PyObject *mapping, const char *errors)
Return value: New reference.

Translate a Unicode object using the given mapping object and return the resulting Unicode object. Return NULL if an exception was raised by the codec.

The mapping object must map Unicode ordinal integers to Unicode strings, integers (which are then interpreted as Unicode ordinals) or None (causing deletion of the character). Unmapped character ordinals (ones which cause a LookupError) are left untouched and are copied as-is.

PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
Return value: New reference.

Translate a Py_UNICODE buffer of the given size by applying a character mapping table to it and return the resulting Unicode object. Return NULL when an exception was raised by the codec.

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_Translate(). または 汎用の codec ベースの API を使用するように移行してください。

Windows 用の MBCS codec

以下は MBCS codec の API です。この codec は現在のところ、 Windows 上だけで利用でき、変換の実装には Win32 MBCS 変換機構 (Win32 MBCS converter) を使っています。 MBCS (または DBCS) はエンコード方式の種類 (class) を表す言葉で、単一のエンコード方式を表すわけでなないので注意してください。利用されるエンコード方式 (target encoding) は、 codec を動作させているマシン上のユーザ設定で定義されています。

PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference.

MBCS でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)

consumed が NULL のとき、 PyUnicode_DecodeMBCS() と同じ動作をします。 consumed が NULL でないとき、 PyUnicode_DecodeMBCSStateful() は文字列の最後にあるマルチバイト文字の前半バイトをデコードせず、 consumed にデコードしたバイト数を格納します。

PyObject* PyUnicode_AsMBCSString( PyObject *unicode)
Return value: New reference.

MBCS で Unicode オブジェクトをエンコードし、結果を Python バイト列オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)

指定されたコードページを使い Unicode オブジェクトをエンコードし、 Python bytes オブジェクトを返します。 codec が例外を送出した場合には NULL を返します。 CP_ACP コードページを使い MBCS エンコーダを取得してください。

バージョン 3.3 で追加.

PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Return value: New reference.

size で指定された長さを持つ Py_UNICODE 型バッファを MBCS でエンコードし、 Python bytes オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です; PyUnicode_AsMBCSString(), PyUnicode_EncodeCodePage(), PyUnicode_AsEncodedString() のいずれかを使用するように移行してください。

メソッドとスロット

メソッドおよびスロット関数 (slot function)

以下の API は Unicode オブジェクトおよび文字列を入力に取り (説明では、どちらも文字列と表記しています)、場合に応じて Unicode オブジェクトか整数を返す機能を持っています。

これらの関数は全て、例外が発生した場合には NULL または -1 を返します。

PyObject* PyUnicode_Concat( PyObject *left, PyObject *right)
Return value: New reference.

二つの文字列を結合して、新たな Unicode 文字列を生成します。

PyObject* PyUnicode_Split( PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
Return value: New reference.

Unicode 文字列のリストを分割して、 Unicode 文字列からなるリストを返します。 sep が NULL の場合、全ての空白文字を使って分割を行います。それ以外の場合、指定された文字を使って分割を行います。最大で maxsplit 個までの分割を行います。 maxsplit が負ならば分割数に制限を設けません。分割結果のリスト内には分割文字は含みません。

PyObject* PyUnicode_Splitlines( PyObject *s, int keepend)
Return value: New reference.

Unicode 文字列を改行文字で区切り、Unicode 文字列からなるリストを返します。 CRLF は一個の改行文字とみなします。 keepend が 0 の場合、分割結果のリスト内に改行文字を含めません。

PyObject* PyUnicode_Translate( PyObject *str, PyObject *table, const char *errors)

文字列に文字対応表 table を適用して変換し、変換結果を Unicode オブジェクトで返します。

対応表は、Unicode 序数を表す整数を Unicode 序数を表す整数または None (その文字を削除する) に対応付けなければなりません。

対応表が提供する必要があるメソッドは __getitem__() インタフェースだけです; 従って、辞書やシーケンス型を使ってもうまく動作します。 対応付けを行っていない (LookupError を起こすような) 文字序数に対しては、変換は行わず、そのままコピーします。

errors は codecs で通常使われるのと同じ意味を持ちます。 errors は NULL にしてもよく、デフォルトエラー処理の使用を意味します。

PyObject* PyUnicode_Join( PyObject *separator, PyObject *seq)
Return value: New reference.

指定した separator で文字列からなるシーケンスを連結 (join) し、連結結果を Unicode 文字列で返します。

Py_ssize_t PyUnicode_Tailmatch( PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

substr が str[start:end] の末端 (direction == -1 は先頭一致、 direction == 1 は末尾一致) でとマッチする場合に 1 を返し、それ以外の場合には 0 を返します。 エラーが発生した時は -1 を返します。

Py_ssize_t PyUnicode_Find( PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

str[start:end] 中に substr が最初に出現する場所を返します。 このとき指定された検索方向 direction (direction == 1 は順方向検索、 direction == -1 は逆方向検索) で検索します。 戻り値は最初にマッチが見つかった場所のインデックスです; 戻り値 -1 はマッチが見つからなかったことを表し、 -2 はエラーが発生して例外情報が設定されていることを表します。

Py_ssize_t PyUnicode_FindChar( PyObject *str, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)

str[start:end] 中に文字 ch が最初に出現する場所を返します。 このとき指定された検索方向 direction (direction == 1 は順方向検索、 direction == -1 は逆方向検索) で検索します。 戻り値は最初にマッチが見つかった場所のインデックスです; 戻り値 -1 はマッチが見つからなかったことを表し、 -2 はエラーが発生して例外情報が設定されていることを表します。

バージョン 3.3 で追加.

バージョン 3.7 で変更: start and end are now adjusted to behave like str[start:end].

Py_ssize_t PyUnicode_Count( PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)

str[start:end] に substr が重複することなく出現する回数を返します。エラーが発生した場合には -1 を返します。

PyObject* PyUnicode_Replace( PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
Return value: New reference.

str 中に出現する substr を最大で maxcount 個 replstr に置換し、置換結果である Unicode オブジェクトを返します。 maxcount == -1 にすると、文字列中に現れる全ての substr を置換します。

int PyUnicode_Compare( PyObject *left, PyObject *right)

二つの文字列を比較して、左引数が右引数より小さい場合、左右引数が等価の場合、左引数が右引数より大きい場合に対して、それぞれ -1, 0, 1 を返します。

この関数は、失敗したときに -1 を返すので、 PyErr_Occurred() を呼び出して、エラーをチェックすべきです。

int PyUnicode_CompareWithASCIIString( PyObject *uni, const char *string)

Unicode オブジェクト uni と string を比較して、左引数が右引数より小さい場合、左右引数が等価の場合、左引数が右引数より大きい場合に対して、それぞれ -1, 0, 1 を返します。 ASCII エンコードされた文字列だけを渡すのが最も良いですが、入力文字列に非 ASCII 文字が含まれている場合は ISO-8859-1 として解釈します。

この関数は例外を送出しません。

PyObject* PyUnicode_RichCompare( PyObject *left, PyObject *right, int op)

二つのunicode文字列を比較して、下のうちの一つを返します:

  • NULL を、例外が発生したときに返します。
  • Py_True もしくは Py_False を、正しく比較できた時に返します。
  • Py_NotImplemented を、 left と right のどちらかに対する PyUnicode_FromObject() が失敗したときに返します。(原文: in case the type combination is unknown)

op に入れられる値は、 Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT, and Py_LE のどれかです。

PyObject* PyUnicode_Format( PyObject *format, PyObject *args)
Return value: New reference.

新たな文字列オブジェクトを format および args から生成して返します; このメソッドは format % args のようなものです。

int PyUnicode_Contains( PyObject *container, PyObject *element)

element が container 内にあるか調べ、その結果に応じて真または偽を返します。

element は単要素の Unicode 文字に型強制できなければなりません。エラーが生じた場合には -1 を返します。

void PyUnicode_InternInPlace( PyObject **string)

引数 *string をインプレースで収容 (intern) します。 引数は Python Unicode 文字列オブジェクトを指すポインタ変数のアドレスでなければなりません。 *string と等しい、すでに収容済みの文字列が存在する場合は、 *string にその文字列を設定します (そして、元の渡された文字列オブジェクトの参照カウントをデクリメントし、すでに収容済みの文字列オブジェクトの参照カウントをインクリメントします)。 そうでない場合は、 *string は変更せず、そのまま収容します (そして、参照カウントをインクリメントします)。 (解説: 参照カウントについては沢山説明して来ましたが、この関数は参照カウント中立 (reference-count-neutral) と考えてください; この関数を呼び出した後にオブジェクトの所有権を持っているのは、関数を呼び出す前にすでに所有権を持っていた場合かつその場合に限ります。)

PyObject* PyUnicode_InternFromString(const char *v)

PyUnicode_FromString() と PyUnicode_InternInPlace() を組み合わせたもので、収容済みの新たな文字列オブジェクトを返すか、同じ値を持つ収容済みの Unicode 文字列オブジェクトに対する新たな ("所有権のある") 参照を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


タプルオブジェクト (tuple object)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

タプルオブジェクト (tuple object)

PyTupleObject

この PyObject のサブタイプは Python のタプルオブジェクトを表現します。

PyTypeObject PyTuple_Type

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

サイズが len の新たなタプルオブジェクトを返します。失敗すると NULL を返します。

PyObject* PyTuple_Pack(Py_ssize_t n, ...)
Return value: New reference.

サイズが n の新たなタプルオブジェクトを返します。失敗すると NULL を返します。タプルの値は後続の n 個の Python オブジェクトを指す C 引数になります。PyTuple_Pack(2, a, b) は Py_BuildValue("(OO)", a, b) と同じです。

Py_ssize_t PyTuple_Size( PyObject *p)

タプルオブジェクトへのポインタを引数にとり、そのタプルのサイズを返します。

Py_ssize_t PyTuple_GET_SIZE( PyObject *p)

タプル p のサイズを返しますが、p は非 NULL でなくてはならず、タプルオブジェクトを指していなければなりません; この関数はエラーチェックを行いません。

PyObject* PyTuple_GetItem( PyObject *p, Py_ssize_t pos)
Return value: Borrowed reference.

p の指すタプルオブジェクト内の、位置 pos にあるオブジェクトを返します。 pos が範囲を超えている場合、 NULL を返して IndexError 例外をセットします。

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.

p の指すタプルオブジェクト内の、位置 low から high までのスライスを取り出して、タプルオブジェクトとして返します。

int PyTuple_SetItem( PyObject *p, Py_ssize_t pos, PyObject *o)

p の指すタプルオブジェクト内の位置 pos に、オブジェクト o への参照を挿入します。成功した場合には 0 を返します。

注釈

この関数は o への参照を "盗み取り" ます。

void PyTuple_SET_ITEM( PyObject *p, Py_ssize_t pos, PyObject *o)

PyTuple_SetItem() に似ていますが、エラーチェックを行わず、新たなタプルに値を入れるとき 以外には使ってはなりません 。

注釈

この関数は o への参照を "盗み取り" ます。

int _PyTuple_Resize( PyObject **p, Py_ssize_t newsize)

タプルをリサイズする際に使えます。 newsize はタプルの新たな長さです。タプルは変更不能なオブジェクト ということになっている ので、この関数はこのオブジェクトに対してただ一つしか参照がない時以外には使ってはなりません。タプルがコード中の他の部分ですでに参照されている場合には、この関数を 使ってはなりません 。タプルは常に指定サイズの末尾まで伸縮します。成功した場合には 0 を返します。クライアントコードは、 *p の値が呼び出し前と同じになると期待してはなりません。 *p が置き換えられた場合、オリジナルの *p は破壊されます。失敗すると -1 を返し、 *p を NULL に設定して、 MemoryError または SystemError を送出します。

int PyTuple_ClearFreeList()

free list をクリアします。解放された要素数を返します。

Struct Sequence オブジェクト

struct sequence オブジェクトは namedtuple() オブジェクトと等価なC オブジェクトです。 つまり、その要素に属性を通してアクセスすることができるシーケンスです。 struct sequence を生成するには、まず特定のstruct sequence 型を生成しなければなりません。

PyTypeObject* PyStructSequence_NewType( PyStructSequence_Desc *desc)

後述の 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 を返します。

バージョン 3.4 で追加.

PyStructSequence_Desc

生成するstruct sequence 型のメタデータを保持します。

フィールド | C の型 | 意味
name | const char * | 生成するstruct sequence 型の名前
doc | const char * | 生成する型のdocstringへのポインタ、または省略する場合は NULL
fields | PyStructSequence_Field * | 新しい型のフィールド名を格納した NULL 終端された配列へのポインタ
n_in_sequence | int | Python 側で可視となるフィールドの数 (もしタプルとして使用する場合)
PyStructSequence_Field

struct sequenceのフィールドについて記述します。struct sequence はタプルをモデルにしているため、全てのフィールドは PyObject* として型付けされます。 PyStructSequence_Desc の fields 配列の添え字によって struct sequenceのどのフィールドについて記載しているかが決まります。

フィールド | C の型 | 意味
name | const char * | フィールドの名前。もし名前づけされたフィールドのリストの終端を表す場合は NULL。名前がないままにする場合は、PyStructSequence_UnnamedField を設定します
doc | const char * | フィールドのdocstring、省略する場合は NULL
char* PyStructSequence_UnnamedField

フィールド名を名前がないままするための特殊な値。

PyObject* PyStructSequence_New( PyTypeObject *type)

type のインスタンスを生成します。 type は PyStructSequence_NewType() によって事前に生成していなければなりません。

PyObject* PyStructSequence_GetItem( PyObject *p, Py_ssize_t pos)

p の指すstruct sequence内の、位置 pos にあるオブジェクトを返します。境界チェックを行いません。

PyObject* PyStructSequence_GET_ITEM( PyObject *p, Py_ssize_t pos)

PyStructSequence_GetItem() と同等のマクロです。

void PyStructSequence_SetItem( PyObject *p, Py_ssize_t pos, PyObject *o)

struct sequence p の pos の位置にあるフィールドに値 o を設定します。PyTuple_SET_ITEM() のように、生成したてのインスタンスに対してのみ使用すべきです。

注釈

この関数は o への参照を "盗み取り" ます。

PyObject* PyStructSequence_SET_ITEM( PyObject *p, Py_ssize_t *pos, PyObject *o)

PyStructSequence_SetItem() と同等のマクロ。

注釈

この関数は o への参照を "盗み取り" ます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


リストオブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

リストオブジェクト

PyListObject

この PyObject のサブタイプは Python のリストオブジェクトを表現します。

PyTypeObject PyList_Type

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

サイズが len 新たなリストオブジェクトを返します。失敗すると NULL を返します。

注釈

len が0より大きいとき、返されるリストオブジェクトの要素には NULL がセットされています。なので、 PyList_SetItem() で本当にオブジェクトをセットするまでは、Pythonコードにこのオブジェクトを渡したり、 PySequence_SetItem() のような抽象APIを利用してはいけません。

Py_ssize_t PyList_Size( PyObject *list)

リストオブジェクト 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.

list の指すリストオブジェクト内の、位置 index にあるオブジェクトを返します。位置は正である必要があり、リスト終端からのインデックスはサポートされていません。 index が範囲を超えている場合、 NULL を返して IndexError 例外をセットします。

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)

リストオブジェクト内の位置 index に、オブジェクト item を挿入します。成功した場合には 0 を返し、失敗すると -1 を返します。

注釈

この関数は 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)

要素 item をリスト list のインデックス index の前に挿入します。成功すると 0 を返します。失敗すると -1 を返し、例外をセットします。list.insert(index, item) に類似した機能です。

int PyList_Append( PyObject *list, PyObject *item)

オブジェクト item を list の末尾に追加します。成功すると 0 を返します; 失敗すると -1 を返し、例外をセットします。list.append(item) に類似した機能です。

PyObject* PyList_GetSlice( PyObject *list, Py_ssize_t low, Py_ssize_t high)
Return value: New reference.

list 内の、low から high の 間の オブジェクトからなるリストを返します。失敗すると NULL を返し、例外をセットします。list[low:high] に類似した機能です。ただし、Python のスライスにある負のインデックスはサポートされていません。

int PyList_SetSlice( PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)

list 内の、low から high の間のオブジェクトを、itemlist の内容にします。list[low:high] = itemlist と類似の機能です。itemlist は NULL でもよく、空リストの代入 (指定スライスの削除) になります。成功した場合には 0 を、失敗した場合には -1 を返します。Python のスライスにある負のインデックスはサポートされていません。

int PyList_Sort( PyObject *list)

list の内容をインプレースでソートします。成功した場合には 0 を、失敗した場合には -1 を返します。list.sort() と同じです。

int PyList_Reverse( PyObject *list)

list の要素をインプレースで反転します。成功した場合には 0 を、失敗した場合には -1 を返します。list.reverse() と同じです。

PyObject* PyList_AsTuple( PyObject *list)
Return value: New reference.

list の内容が入った新たなタプルオブジェクトを返します; tuple(list) と同じです。

int PyList_ClearFreeList()

free list をクリアします。解放された要素数を返します。

バージョン 3.3 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


辞書オブジェクト (dictionary object)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

辞書オブジェクト (dictionary object)

PyDictObject

この PyObject のサブタイプは Python の辞書オブジェクトを表現します。

PyTypeObject PyDict_Type

この PyTypeObject のインスタンスは Python の辞書を表現します。このオブジェクトは、Python レイヤにおける dict と同じオブジェクトです。

int PyDict_Check( PyObject *p)

引数が辞書オブジェクトか辞書型のサブタイプのインスタンスの場合に真を返します。

int PyDict_CheckExact( PyObject *p)

p が辞書オブジェクトであり、かつ辞書型のサブクラスのインスタンスでない場合に真を返します。

PyObject* PyDict_New()
Return value: New reference.

空の新たな辞書を返します。失敗すると NULL を返します。

PyObject* PyDictProxy_New( PyObject *mapping)
Return value: New reference.

あるマップ型オブジェクトに対して、読み出し専用に制限された types.MappingProxyType オブジェクトを返します。通常、この関数は動的でないクラス型 (non-dynamic class type) のクラス辞書が変更されないようにビューを作成するために使われます。

void PyDict_Clear( PyObject *p)

現在辞書に入っている全てのキーと値のペアを除去して空にします。

int PyDict_Contains( PyObject *p, PyObject *key)

辞書 p に key が入っているか判定します。p の要素が key に一致した場合は 1 を返し、それ以外の場合には 0 を返します。エラーの場合 -1 を返します。この関数は Python の式 key in p と等価です。

PyObject* PyDict_Copy( PyObject *p)
Return value: New reference.

p と同じキーと値のペアが入った新たな辞書を返します。

int PyDict_SetItem( PyObject *p, PyObject *key, PyObject *val)

辞書 p に、 key をキーとして値 value を挿入します。 key はハッシュ可能(hashable)でなければなりません; ハッシュ可能でない場合、 TypeError を送出します。成功した場合には 0 を、失敗した場合には -1 を返します。

int PyDict_SetItemString( PyObject *p, const char *key, PyObject *val)

辞書 p に、 key をキーとして値 value を挿入します。 key は const char* 型でなければなりません。キーオブジェクトは PyUnicode_FromString(key) で生成されます。成功した場合には 0 を、失敗した場合には -1 を返します。

int PyDict_DelItem( PyObject *p, PyObject *key)

辞書 p から key をキーとするエントリを除去します。 key はハッシュ可能でなければなりません; ハッシュ可能でない場合、 TypeError を送出します。成功した場合には 0 を、失敗した場合には -1 を返します。

int PyDict_DelItemString( PyObject *p, const char *key)

辞書 p から文字列 key をキーとするエントリを除去します。成功した場合には 0 を、失敗した場合には -1 を返します。

PyObject* PyDict_GetItem( PyObject *p, PyObject *key)
Return value: Borrowed reference.

辞書 p 内で key をキーとするオブジェクトを返します。キー key が存在しない場合には NULL を返しますが、例外をセット しません。

PyObject* PyDict_GetItemWithError( PyObject *p, PyObject *key)
Return value: Borrowed reference.

PyDict_GetItem() の変種で例外を隠しません。例外が発生した場合は、例外をセット した上で NULL を返します。キーが存在しなかった場合は、例外をセット せずに NULL を返します。

PyObject* PyDict_GetItemString( PyObject *p, const char *key)
Return value: Borrowed reference.

PyDict_GetItem() と同じですが、 key は PyObject* ではなく const char* で指定します。

PyObject* PyDict_SetDefault( PyObject *p, PyObject *key, PyObject *default)
Return value: Borrowed reference.

これは Python レベルの dict.setdefault() と同じです。 もしあれば、辞書 p から key に対応する値を返します。 キーが辞書になければ、値 defaultobj を挿入し defaultobj を返します。 この関数は、 key のハッシュ値を検索と挿入ごとに別々に評価するのではなく、一度だけしか評価しません。

バージョン 3.4 で追加.

PyObject* PyDict_Items( PyObject *p)
Return value: New reference.

辞書内の全ての要素対が入った PyListObject を返します。

PyObject* PyDict_Keys( PyObject *p)
Return value: New reference.

辞書内の全てのキーが入った PyListObject を返します。

PyObject* PyDict_Values( PyObject *p)
Return value: New reference.

辞書 p 内の全ての値が入った PyListObject を返します。

Py_ssize_t PyDict_Size( PyObject *p)

辞書内の要素の数を返します。辞書に対して len(p) を実行するのと同じです。

int PyDict_Next( PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)

辞書 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)

マップ型オブジェクト b の全ての要素にわたって、反復的にキー/値のペアを辞書 a に追加します。 b は辞書か、 PyMapping_Keys() または PyObject_GetItem() をサポートする何らかのオブジェクトにできます。 override が真ならば、 a のキーと一致するキーが b にある際に、既存のペアを置き換えます。それ以外の場合は、 b のキーに一致するキーが a にないときのみ追加を行います。成功した場合には 0 を返し、例外が送出された場合には -1 を返します。

int PyDict_Update( PyObject *a, PyObject *b)

C で表せば PyDict_Merge(a, b, 1) と同じで、また Python の a.update(b) と似ていますが、 PyDict_Update() は第二引数が "keys" 属性を持たない場合にキー/値ペアのシーケンスを反復することはありません。成功した場合には 0 を返し、例外が送出された場合には -1 を返します。

int PyDict_MergeFromSeq2( PyObject *a, PyObject *seq2, int override)

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_ClearFreeList()

free list をクリアします。解放された要素数を返します。

バージョン 3.3 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


Set オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

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() を含む) を使って利用できます。

PySetObject

この PyObject を継承した型は、 set と frozenset 両方の内部データを保存するのに用いられます。 PyDictObject と同じように、小さい集合(set)に対しては(タプルのように)固定サイズであり、そうでない集合に対しては(リストと同じように)可変長のメモリブロックを用います。この構造体のどのフィールドも、非公開で変更される可能性があると考えて下さい。すべてのアクセスは、構造体の中の値を直接操作するのではなく、ドキュメントされた API を用いて行うべきです。

PyTypeObject PySet_Type

この PyTypeObject のインスタンスは、Python の set 型を表します。

PyTypeObject PyFrozenSet_Type

この 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 PyAnySet_CheckExact( PyObject *p)

p が set か frozenset のどちらかのオブジェクトであるときに true を返します。サブタイプのオブジェクトは含みません。

int PyFrozenSet_CheckExact( PyObject *p)

p が frozenset のオブジェクトであるときに true を返します。サブタイプのオブジェクトは含みません。

PyObject* PySet_New( PyObject *iterable)
Return value: New reference.

iterable が返すオブジェクトを含む新しい set を返します。 iterable が NULL のときは、空の set を返します。成功したら新しい set を、失敗したら NULL を返します。 iterable がイテレート可能でない場合は、 TypeError を送出します。このコンストラクタは set をコピーするときにも使えます (c=set(s))。

PyObject* PyFrozenSet_New( PyObject *iterable)
Return value: New reference.

iterable が返すオブジェクトを含む新しい frozenset を返します。 iterable が NULL のときは、空の frozenset を返します。成功時には新しい set を、失敗時には NULL を返します。 iterable がイテレート可能でない場合は、 TypeError を送出します。

以降の関数やマクロは、 set と frozenset とそのサブタイプのインスタンスに対して利用できます。

Py_ssize_t PySet_Size( PyObject *anyset)

set や frozenset のオブジェクトの長さを返します。 len(anyset) と同じです。 anyset が set 、 frozenset およびそのサブタイプのオブジェクトでない場合は、 PyExc_SystemError を送出します。

Py_ssize_t PySet_GET_SIZE( PyObject *anyset)

エラーチェックを行わない、 PySet_Size() のマクロ形式。

int PySet_Contains( PyObject *anyset, PyObject *key)

見つかったら 1 を、見つからなかったら 0 を、エラーが発生した場合は -1 を返します。 Python の __contains__() メソッドと違って、この関数は非ハッシュ set を一時的な frozenset に自動で変換しません。 key がハッシュ可能で無い場合、 TypeError を送出します。 anyset が set, frozenset 及びそのサブタイプのオブジェクトで無い場合は PyExc_SystemError を送出します。

int PySet_Add( PyObject *set, PyObject *key)

set のインスタンスに key を追加します。 frozenset に対しても動作します (PyTuple_SetItem() のように、他のコードに見える前の新しい frozenset の値を埋めるために使用できます)。 成功したら 0 を、失敗したら -1 を返します。 key がハッシュ可能でない場合は、 TypeError を送出します。 set を大きくする余裕がない場合は、 MemoryError を送出します。 set が set かそのサブタイプのインスタンスでない場合は、 SystemError を送出します。

以降の関数は、 set とそのサブタイプに対して利用可能です。 frozenset とそのサブタイプには利用できません。

int PySet_Discard( PyObject *set, PyObject *key)

key が見つかって、値を削除したら 1 を返します。 見つからなかったら (何もせずに) 0 を返します。 エラーが発生した場合は -1 を返します。 key が無くても KeyError を送出しません。 key がハッシュ可能でない場合は TypeError を送出します。 Python の discard() メソッドと違って、この関数は非ハッシュ set を一時的な frozenset に変換しません。 set が set かそのサブタイプのインスタンスでないときは、 PyExc_SystemError を送出します。

PyObject* PySet_Pop( PyObject *set)
Return value: New reference.

set の中の要素のどれかに対する新しい参照を返し、そのオブジェクトを set から削除します。失敗したら NULL を返します。 set が空の場合には KeyError を送出します。 set が set とそのサブタイプのインスタンスでない場合は、 SystemError を送出します。

int PySet_Clear( PyObject *set)

set を空にします。

int PySet_ClearFreeList()

free list をクリアします。解放された要素数を返します。

バージョン 3.3 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


Function オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

Function オブジェクト

Functionオブジェクト固有の関数はわずかです。

PyFunctionObject

関数に使われるCの構造体。

PyTypeObject PyFunction_Type

PyTypeObject 型のインスタンスで、 Python の関数型を表します。これは Python プログラムに types.FunctionType として公開されています。

int PyFunction_Check( PyObject *o)

o が関数オブジェクト (PyFunction_Type 型なら) なら true を返します。引数は NULL であってはいけません。

PyObject* PyFunction_New( PyObject *code, PyObject *globals)
Return value: New reference.

コードオブジェクト code に関連付けられた新しい関数オブジェクトを返します。globals はこの関数からアクセスできるグローバル変数の辞書でなければなりません。

関数のドキュメント文字列と名前はコードオブジェクトから取得されます。 __module__ は globals から取得されます。引数のデフォルト値やアノテーション、クロージャは NULL に設定されます。 __qualname__ は関数名と同じ値に設定されます。

PyObject* PyFunction_NewWithQualName( PyObject *code, PyObject *globals, PyObject *qualname)
Return value: New reference.

PyFunction_New() に似ていますが、関数オブジェクトの __qualname__ 属性に値をセットすることができます。 qualname はユニコードオブジェクトか NULL でなくてはなりません; NULL だった場合、 __qualname__ 属性には __name__ 属性と同じ値がセットされます。

バージョン 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.

関数オブジェクト op の __module__ 属性を返します。これには普通はモジュール名の文字列が入っていますが、Python コードから他のオブジェクトをセットされることもあります。

PyObject* PyFunction_GetDefaults( PyObject *op)
Return value: Borrowed reference.

関数オブジェクト op の引数のデフォルト値を返します。引数のタプルか NULL になります。

int PyFunction_SetDefaults( PyObject *op, PyObject *defaults)

関数オブジェクト op の引数のデフォルト値を設定します。defaults は Py_None かタプルでなければいけません。

失敗した時は、 SystemError を発生させ、 -1 を返します。

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)

関数オブジェクト op のアノテーションを返します。返り値は修正可能な辞書か NULL になります。

int PyFunction_SetAnnotations( PyObject *op, PyObject *annotations)

関数オブジェクト op のアノテーションを設定します。annotations は辞書か、Py_None でなければなりません。

失敗した時は、 SystemError を発生させ、 -1 を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


インスタンスメソッドオブジェクト(Instance Method Objects)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

インスタンスメソッドオブジェクト(Instance Method Objects)

インスタンスメソッドとは PyCFunction のためのラッパーであり、 PyCFunction をクラスオブジェクトにバインドするための新しいやり方です。これは以前の 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)

任意の呼び出し可能オブジェクト func を使った新たなメソッドオブジェクトを返します。関数 func はメソッドが呼び出されたときに呼び出されるオブジェクトです。

PyObject* PyInstanceMethod_Function( PyObject *im)

インスタンスメソッド im に関連付けられた関数オブジェクトを返します。

PyObject* PyInstanceMethod_GET_FUNCTION( PyObject *im)

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() のマクロ版で、エラーチェックを行いません。

int PyMethod_ClearFreeList()

free list をクリアします。解放された要素数を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


セルオブジェクト (cell object)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

セルオブジェクト (cell object)

"セル (cell)" オブジェクトは、複数のスコープから参照される変数群を実装するために使われます。セルは各変数について作成され、各々の値を記憶します; この値を参照する各スタックフレームにおけるローカル変数には、そのスタックフレームの外側で同じ値を参照しているセルに対する参照が入ります。セルで表現された値にアクセスすると、セルオブジェクト自体の代わりにセル内の値が使われます。このセルオブジェクトを使った間接参照 (dereference) は、インタプリタによって生成されたバイトコード内でサポートされている必要があります; セルオブジェクトにアクセスした際に、自動的に間接参照は起こりません。上記以外の状況では、セルオブジェクトは役に立たないはずです。

PyCellObject

セルオブジェクトに使われる C 構造体です。

PyTypeObject PyCell_Type

セルオブジェクトに対応する型オブジェクトです。

int PyCell_Check(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 でなければならず、かつセルオブジェクトでなければなりません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


コードオブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

コードオブジェクト

コードオブジェクト(Code objects)は CPython 実装の低レベルな詳細部分です。各オブジェクトは関数に束縛されていない実行可能コードの塊を表現しています。

PyCodeObject

コードオブジェクトを表現するために利用されるC構造体。この型のフィールドは何時でも変更され得ます。

PyTypeObject PyCode_Type

これは Python の code 型を表現する PyTypeObject のインスタンスです。

int PyCode_Check( PyObject *co)

co が code オブジェクトのときに真を返します。

int PyCode_GetNumFree( PyCodeObject *co)

co 内の自由変数(free variables)の数を返します。

PyCodeObject* PyCode_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, int firstlineno, PyObject *lnotab)

新しいコードオブジェクトを返します。フレームを作成するためにダミーのコードオブジェクトが必要な場合は、代わりに PyCode_NewEmpty() を利用してください。バイトコードは頻繁に変更されるため、 PyCode_New() を直接呼び出すと、 Python の詳細バージョンに依存してしまうことがあります。

PyCodeObject* PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)

新しい空のコードオブジェクトを、指定されたファイル名、関数名、開始行番号で作成します。返されたコードオブジェクトに対しての exec() や eval() は許されていません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


ファイルオブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

ファイルオブジェクト

これらの API は、 Python 2 の組み込みのファイルオブジェクトの C API を最低限エミュレートするためのものです。それらは、標準 C ライブラリでサポートされているバッファ付き I/O (FILE*) に頼るために使われます。 Python 3 では、ファイルとストリームは新しい io モジュールを使用され、そこに OS の低レベルなバッファ付き I/O の上にいくつかの層が定義されています。下で解説されている関数は、それらの新しい API の便利な C ラッパーであり、インタプリタでの内部的なエラー通知に向いています; サードパーティーのコードは代わりに io の API を使うことが推奨されます。

PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)

既に開かれているファイル fd のファイルディスクリプタから Python のファイルオブジェクトを作成します。引数 name 、 encoding 、 errors 、 newline には NULL を指定してデフォルトの値を使うことができます; buffering には -1 を指定してデフォルトの値を使うことができます。 name は無視されるのですが、後方互換性のために残されています。失敗すると NULL を返します。より包括的な引数の解説は、 io.open() 関数のドキュメントを参照してください。

警告

Python ストリームは自身のバッファリング層を持つため、ファイル記述子のOSレベルのバッファリングと併用すると、様々な問題 (予期せぬデータ順) などを引き起こします。

バージョン 3.2 で変更: name 属性の無視。

int PyObject_AsFileDescriptor( PyObject *p)

p に関連づけられる ファイルディスクリプタを int として返します。オブジェクトが整数なら、その値を返します。 整数でない場合、オブジェクトに fileno() メソッドがあれば呼び出します; このメソッドの返り値は、ファイル記述子の値として返される整数でなければなりません。失敗すると例外を設定して -1 を返します。

PyObject* PyFile_GetLine( PyObject *p, int n)
Return value: New reference.

p.readline([n]) と同じで、この関数はオブジェクト p の各行を読み出します。 p はファイルオブジェクトか、 readline() メソッドを持つ何らかのオブジェクトでかまいません。 n が 0 の場合、行の長さに関係なく正確に 1 行だけ読み出します。 n が 0 より大きければ、 n バイト以上のデータは読み出しません; 従って、行の一部だけが返される場合があります。 どちらの場合でも、読み出し後すぐにファイルの終端に到達した場合には空文字列を 返します。 n が 0 より小さければ、長さに関わらず 1 行だけを 読み出しますが、すぐにファイルの終端に到達した場合には EOFError を送出します。

int PyFile_WriteObject( PyObject *obj, PyObject *p, int flags)

オブジェクト obj をファイルオブジェクト p に書き込みます。 flags がサポートするフラグは Py_PRINT_RAW だけです; このフラグを指定すると、オブジェクトに repr() ではなく str() を適用した結果をファイルに書き出します。成功した場合には 0 を返し、失敗すると -1 を返して適切な例外をセットします。

int PyFile_WriteString(const char *s, PyObject *p)

文字列 s をファイルオブジェクト p に書き出します。成功した場合には 0 を返し、失敗すると -1 を返して適切な例外をセットします。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


モジュールオブジェクト (module object)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

モジュールオブジェクト (module object)

PyTypeObject PyModule_Type

この PyTypeObject のインスタンスは Python のモジュールオブジェクト型を表現します。このオブジェクトは、Python プログラムには types.ModuleType として公開されています。

int PyModule_Check( PyObject *p)

p がモジュールオブジェクトかモジュールオブジェクトのサブタイプであるときに真を返します。

int PyModule_CheckExact( PyObject *p)

p がモジュールオブジェクトで、かつモジュールオブジェクトのサブタイプでないときに真を返します。 PyModule_Type.

PyObject* PyModule_NewObject( PyObject *name)

__name__ 属性に name が設定された新しいモジュールオブジェクトを返します。 モジュールの __name__, __doc__, __package__, __loader__ 属性に値が入っています (__name__ 以外は全て None です); __file__ 属性に値を入れるのは呼び出し側の責任です。

バージョン 3.3 で追加.

バージョン 3.4 で変更: __package__ と __loader__ は None に設定されます。

PyObject* PyModule_New(const char *name)
Return value: New reference.

Similar to PyModule_NewObject(), but the name is a UTF-8 encoded string instead of a Unicode object.

PyObject* PyModule_GetDict( PyObject *module)
Return value: Borrowed reference.

module の名前空間を実装する辞書オブジェクトを返します; このオブジェクトは、モジュールオブジェクトの __dict__ 属性と同じものです。 module がモジュールオブジェクト (もしくはモジュールオブジェクトのサブタイプ) でない場合は、 SystemError が送出され NULL が返されます。

拡張モジュールでは、モジュールの __dict__ を直接操作するよりも、 PyModule_*() および PyObject_*() 関数を使う方が推奨されます。

PyObject* PyModule_GetNameObject( PyObject *module)

module の __name__ の値を返します。モジュールがこの属性を提供していない場合や文字列型でない場合、 SystemError を送出して NULL を返します。

バージョン 3.3 で追加.

const char* PyModule_GetName( PyObject *module)

PyModule_GetNameObject() に似ていますが、 'utf-8' でエンコードされた name を返します。

void* PyModule_GetState( PyObject *module)

モジュールの "state"(モジュールを生成したタイミングで確保されるメモリブロックへのポインター) か、なければ NULL を返します。 PyModuleDef.m_size を参照してください。

PyModuleDef* PyModule_GetDef( PyObject *module)

モジュールが作られる元となった PyModuleDef 構造体へのポインタを返します。 モジュールが定義によって作られていなかった場合は NULL を返します。

PyObject* PyModule_GetFilenameObject( PyObject *module)

module の __file__ 属性をもとに module がロードされたもとのファイル名を返します。もしファイル名が定義されていない場合や、 Unicode 文字列ではない場合、 SystemError を発生させて NULL を返します。それ以外の場合は Unicode オブジェクトへの参照を返します。

バージョン 3.2 で追加.

const char* PyModule_GetFilename( PyObject *module)

PyModule_GetFilenameObject() と似ていますが、 'utf-8' でエンコードされたファイル名を返します。

バージョン 3.2 で非推奨: PyModule_GetFilename() はエンコードできないファイル名に対しては UnicodeEncodeError を送出します。これの代わりに PyModule_GetFilenameObject() を使用してください。

Cモジュールの初期化

通常、モジュールオブジェクトは拡張モジュール (初期化関数をエクスポートしている共有ライブラリ) または組み込まれたモジュール (PyImport_AppendInittab() を使って初期化関数が追加されているモジュール) から作られます。 詳細については C および C++ 拡張のビルド または 埋め込まれた Python の拡張 を見てください。

初期化関数は、モジュール定義のインスタンスを PyModule_Create() に渡して出来上がったモジュールオブジェクトを返してもよいですし、もしくは定義構造体そのものを返し"多段階初期化"を要求しても構いません。

PyModuleDef

モジュール定義構造体はモジュールオブジェクトを生成するのに必要なすべての情報を保持します。 通常は、それぞれのモジュールごとに静的に初期化されたこの型の変数が1つだけ存在します。

PyModuleDef_Base m_base

このメンバーは常に PyModuleDef_HEAD_INIT で初期化してください。

const char *m_name

新しいモジュールの名前。

const char *m_doc

モジュールの docstring。たいてい docstring は PyDoc_STRVAR() を利用して生成されます。

Py_ssize_t m_size

モジュールの状態は、静的なグローバルな領域ではなく PyModule_GetState() で取得できるモジュールごとのメモリ領域に保持されていることがあります。 これによってモジュールは複数のサブ・インタプリターで安全に使えます。

このメモリ領域は m_size に基づいてモジュール作成時に確保され、モジュールオブジェクトが破棄されるときに、 m_free 関数があればそれが呼ばれた後で解放されます。

m_size に -1 を設定すると、そのモジュールはグローバルな状態を持つためにサブ・インタープリターをサポートしていないということになります。

m_size を非負の値に設定すると、モジュールは再初期化でき、その状態のために必要となる追加のメモリ量を指定できるということになります。 非負の m_size は多段階初期化で必要になります。

詳細は 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

A traversal function to call during GC traversal of the module object, or NULL if not needed. This function may be called before module state is allocated (PyModule_GetState() may return NULL), and before the Py_mod_exec function is executed.

inquiry m_clear

A clear function to call during GC clearing of the module object, or NULL if not needed. This function may be called before module state is allocated (PyModule_GetState() may return NULL), and before the Py_mod_exec function is executed.

freefunc m_free

A function to call during deallocation of the module object, or NULL if not needed. This function may be called before module state is allocated (PyModule_GetState() may return NULL), and before the Py_mod_exec function is executed.

一段階初期化

モジュールの初期化関数が直接モジュールオブジェクトを生成して返す場合があります。 これは"一段階初期化"と呼ばれ、次の2つのモジュール生成関数のどちらか1つを使います:

PyObject* PyModule_Create( PyModuleDef *def)

def での定義に従って新しいモジュールオブジェクトを生成します。 これは PyModule_Create2() の module_api_version に PYTHON_API_VERSION を設定したときのように振る舞います。

PyObject* PyModule_Create2( PyModuleDef *def, int module_api_version)

APIバージョンを module_api_version として def での定義に従って新しいモジュールオブジェクトを生成します。 もし指定されたバージョンが実行しているインタープリターのバージョンと異なる場合は、 RuntimeWarning を発生させます。

注釈

ほとんどの場合、この関数ではなく PyModule_Create() を利用するべきです。この関数は、この関数の必要性を理解しているときにだけ利用してください。

モジュールオブジェクトが初期化関数から返される前に、たいていは PyModule_AddObject() などの関数を使ってモジュールオブジェクトにメンバを所属させます。

多段階初期化

拡張を直接生成するもう1つのやり方は、"多段階初期化"を要求する方法です。 この方法で作られる拡張モジュールは、よりPythonモジュールに近い振る舞いをします: 初期化処理は、モジュールオブジェクトを生成する 生成段階 とメンバを所属させる 実行段階 に分割されます。 この区別はクラスの __new__() メソッドと __init__() メソッドに似ています。

一段階初期化で生成されたモジュールと違い、多段階初期化で生成されたモジュールはシングルトンではありません: sys.modules のエントリーが削除されモジュールが再インポートされた場合、新しいモジュールオブジェクトが生成され、古いモジュールはPythonモジュールと同じように通常のガベージコレクションで処理されることになります。 デフォルトでは、同じ定義から作られた複数のモジュールは独立であるべきです: あるインスタンスに加えた変更は別のインスタンスに影響しません。 これは、(例えば PyModule_GetState() を使って取得できる) 全ての状態や、(モジュールの __dict__ や PyType_FromSpec() で生成された個々のクラスのような) モジュールに所属するものは、特定のモジュールオブジェクト特有のものであるべきということです。

多段階初期化を使って生成される全てのモジュールは サブ・インタプリター をサポートすることが求められます。 複数のモジュールが独立していることを保証するのには、たいていはこのサポートをするだけで十分です。

多段階初期化を要求するために、初期化関数 (PyInit_modulename) は空でない m_slots を持つ PyModuleDef を返します。 これを返す前に、 PyModuleDef インスタンスは次の関数で初期化されなくてはいけません:

PyObject* PyModuleDef_Init( PyModuleDef *def)

モジュール定義が型と参照カウントを正しく報告する、適切に初期化された Python オブジェクトであること保証します。

PyObject* にキャストされた def を返します。エラーが発生した場合 NULL を返します。

バージョン 3.5 で追加.

モジュール定義の m_slots メンバは PyModuleDef_Slot 構造体の配列を指さなければなりません:

PyModuleDef_Slot
int slot

スロット ID で、以下で説明されている利用可能な値から選ばれます。

void* value

スロットの値で、意味はスロット ID に依存します。

バージョン 3.5 で追加.

m_slots 配列はID 0 のスロットで終端されていなければなりません。

利用可能なスロットの型は以下です:

Py_mod_create

モジュールオブジェクト自身を生成するために呼ばれる関数を指定します。 このスロットの value ポインタは次のシグネチャを持つ関数を指していなくてはいけません:

PyObject* create_module( PyObject *spec, PyModuleDef *def)

PEP 451 で定義された 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 配列に現れた順に処理されていきます。

多段階初期化についてより詳しくは PEP 489 を見てください。

低水準モジュール作成関数

以下の関数は、多段階初期化を使うときに裏側で呼び出されます。 例えばモジュールオブジェクトを動的に生成するときに、これらの関数を直接使えます。 PyModule_FromDefAndSpec および PyModule_ExecDef のどちらも、呼び出した後にはモジュールが完全に初期化されていなければなりません。

PyObject * PyModule_FromDefAndSpec( PyModuleDef *def, PyObject *spec)

module と ModuleSpec オブジェクトの spec で定義されたとおりに新しいモジュールオブジェクトを生成します。 この関数は、 PyModule_FromDefAndSpec2() 関数の module_api_version に PYTHON_API_VERSION を指定した時とおなじようにふるまいます。

バージョン 3.5 で追加.

PyObject * PyModule_FromDefAndSpec2( PyModuleDef *def, PyObject *spec, int module_api_version)

APIバージョンを module_api_version として、 module と ModuleSpec オブジェクトの spec で定義されたとおりに新しいモジュールオブジェクトを生成します。 もし指定されたバージョンが実行しているインタープリターのバージョンと異なる場合は、 RuntimeWarning を発生させます。

注釈

ほとんどの場合、この関数ではなく PyModule_FromDefAndSpec() を利用するべきです。 この関数は、この関数の必要性を理解しているときにだけ利用してください。

バージョン 3.5 で追加.

int PyModule_ExecDef( PyObject *module, PyModuleDef *def)

def で与えられた任意の実行スロット (Py_mod_exec) を実行します。

バージョン 3.5 で追加.

int PyModule_SetDocString( PyObject *module, const char *docstring)

module の docstring を docstring に設定します。 この関数は、 PyModuleDef から PyModule_Create もしくは PyModule_FromDefAndSpec を使ってモジュールを生成するときに自動的に呼び出されます。

バージョン 3.5 で追加.

int PyModule_AddFunctions( PyObject *module, PyMethodDef *functions)

終端が NULL になっている functions 配列にある関数を module に追加します。 PyMethodDef 構造体の個々のエントリについては PyMethodDef の説明を参照してください (モジュールの名前空間が共有されていないので、 C で実装されたモジュールレベル "関数" はたいていモジュールを1つ目の引数として受け取り、 Python クラスのインスタンスメソッドに似た形にします)。 この関数は、 PyModuleDef から PyModule_Create もしくは PyModule_FromDefAndSpec を使ってモジュールを生成するときに自動的に呼び出されます。

バージョン 3.5 で追加.

サポート関数

モジュールの初期化関数 (一段階初期化を使う場合) 、あるいはモジュールの実行スロットから呼び出される関数 (多段階初期化を使う場合) は次の関数を使うと、モジュールの state の初期化を簡単にできます:

int PyModule_AddObject( PyObject *module, const char *name, PyObject *value)

module にオブジェクトを name として追加します。 この関数はモジュールの初期化関数から利用される便利関数です。 これは value への参照を盗みます。 エラーのときには -1 を、成功したときには 0 を返します。

int PyModule_AddIntConstant( PyObject *module, const char *name, long value)

module に整数定数を name として追加します。この便宜関数はモジュールの初期化関数から利用されています。エラーのときには -1 を、成功したときには 0 を返します。

int PyModule_AddStringConstant( PyObject *module, const char *name, const char *value)

module に文字列定数を name として追加します。 この便利関数はモジュールの初期化関数から利用されています。 文字列 value は NULL 終端されていなければなりません。 エラーのときには -1 を、成功したときには 0 を返します。

int PyModule_AddIntMacro( PyObject *module, macro)

module に int 定数を追加します。名前と値は macro から取得されます。例えば、 PyModule_AddIntMacro(module, AF_INET) とすると、 AF_INET という名前の int 型定数を AF_INET の値で module に追加します。エラー時には -1 を、成功時には 0 を返します。

int PyModule_AddStringMacro( PyObject *module, macro)

文字列定数を module に追加します。

モジュール検索

一段階初期化は、現在のインタプリタのコンテキストから探せるシングルトンのモジュールを生成します。 これによって、後からモジュール定義への参照だけでモジュールオブジェクトが取得できます。

多段階初期化を使うと単一の定義から複数のモジュールが作成できるので、これらの関数は多段階初期化を使って作成されたモジュールには使えません。

PyObject* PyState_FindModule( PyModuleDef *def)

現在のインタプリタの def から作られたモジュールオブジェクトを返します。このメソッドの前提条件として、前もって PyState_AddModule() でインタプリタの state にモジュールオブジェクトを連結しておくことを要求します。対応するモジュールオブジェクトが見付からない、もしくは事前にインタプリタの state に連結されていない場合は、 NULL を返します。

int PyState_AddModule( PyObject *module, PyModuleDef *def)

関数に渡されたモジュールオブジェクトを、インタプリタの state に連結します。この関数を使うことで PyState_FindModule() からモジュールオブジェクトにアクセスできるようになります。

一段階初期化を使って作成されたモジュールにのみ有効です。

バージョン 3.3 で追加.

int PyState_RemoveModule( PyModuleDef *def)

def から作られたモジュールオブジェクトをインタプリタ state から削除します。

バージョン 3.3 で追加.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


イテレータオブジェクト (iterator object)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

イテレータオブジェクト (iterator object)

Python では二種類のイテレータオブジェクトを提供しています。一つ目はシーケンスイテレータで、 __getitem__() メソッドをサポートする任意のシーケンスを取り扱います。二つ目は呼び出し可能オブジェクトとセンチネル値 (sentinel value) を扱い、シーケンス内の要素ごとに呼び出し可能オブジェクトを呼び出して、センチネル値が返されたときに反復処理を終了します。

PyTypeObject PySeqIter_Type

PySeqIter_New() や、組み込みシーケンス型に対して 1 引数形式の組み込み関数 iter() を呼び出したときに返される、イテレータオブジェクトの型オブジェクトです。

int PySeqIter_Check(op)

PySeqIter_Type の型が op のときに真を返します。

PyObject* PySeqIter_New( PyObject *seq)
Return value: New reference.

一般的なシーケンスオブジェクト seq を扱うイテレータを返します。反復処理は、シーケンスが添字指定操作の際に IndexError を返したときに終了します。

PyTypeObject PyCallIter_Type

PyCallIter_New() や、組み込み関数 iter() の 2 引数形式が返すイテレータオブジェクトの型オブジェクトです。

int PyCallIter_Check(op)

op の型が PyCallIter_Type のときに真を返します。

PyObject* PyCallIter_New( PyObject *callable, PyObject *sentinel)
Return value: New reference.

新たなイテレータを返します。最初のパラメタ callable は引数なしで呼び出せる Python の呼び出し可能オブジェクトならなんでもかまいません; callable は、呼び出されるたびに次の反復処理対象オブジェクトを返さなければなりません。生成されたイテレータは、callable が sentinel に等しい値を返すと反復処理を終了します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


デスクリプタオブジェクト (descriptor object)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

デスクリプタオブジェクト (descriptor object)

"デスクリプタ (descriptor)" は、あるオブジェクトのいくつかの属性について記述したオブジェクトです。デスクリプタオブジェクトは型オブジェクトの辞書内にあります。

PyTypeObject PyProperty_Type

組み込みデスクリプタ型の型オブジェクトです。

PyObject* PyDescr_NewGetSet( PyTypeObject *type, struct PyGetSetDef *getset)
Return value: New reference.
PyObject* PyDescr_NewMember( PyTypeObject *type, struct PyMemberDef *meth)
Return value: New reference.
PyObject* PyDescr_NewMethod( PyTypeObject *type, struct PyMethodDef *meth)
Return value: New reference.
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.
int PyDescr_IsData( PyObject *descr)

デスクリプタオブジェクト descr がデータ属性のデスクリプタの場合には真を、メソッドデスクリプタの場合には偽を返します。descr はデスクリプタオブジェクトでなければなりません; エラーチェックは行いません。

PyObject* PyWrapper_New( PyObject *, PyObject *)
Return value: New reference.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

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

PyTypeObject PySlice_Type

スライスオブジェクトの型オブジェクトです。これは、Pythonレイヤにおける slice と同じオブジェクトです。

int PySlice_Check( PyObject *ob)

ob がスライスオブジェクトの場合に真を返します; ob は NULL であってはなりません。

PyObject* PySlice_New( PyObject *start, PyObject *stop, PyObject *step)
Return value: New reference.

指定した値から新たなスライスオブジェクトを返します。パラメタ 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)

スライスオブジェクト slice における start, stop, および step のインデクス値を取得します。このときシーケンスの長さを length と仮定します。length よりも大きなインデクスになるとエラーとして扱います。

成功のときには 0 を、エラーのときには例外をセットせずに -1 を返します (ただし、指定インデクスのいずれか一つが None ではなく、かつ整数に変換できなかった場合を除きます。この場合、 -1 を返して例外をセットします)。

おそらく、あなたはこの関数を使いたくないでしょう。

バージョン 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)

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)

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.

バージョン 3.6.1 で追加.

Py_ssize_t PySlice_AdjustIndices(Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step)

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.

バージョン 3.6.1 で追加.

Ellipsis オブジェクト

PyObject *Py_Ellipsis

Python における Ellipsis オブジェクトです。 このオブジェクトはメソッドを持ちません。 参照カウントの点では、他のオブジェクトと同様に扱う必要があります。 Py_None のように、これもシングルトンオブジェクトです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


memoryview オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

memoryview オブジェクト

memoryview オブジェクトは、他のオブジェクトと同じように扱える Python オブジェクトの形をした C 言語レベルの バッファのインターフェース です。

PyObject *PyMemoryView_FromObject( PyObject *obj)

バッファインタフェースを提供するオブジェクトからmemoryview オブジェクトを生成します。もし obj が書き込み可能なバッファのエクスポートをサポートするなら、その memoryview オブジェクトは読み書き可能です。そうでなければ読出しのみになるか、エクスポーターの分別にもとづいて読み書きが可能となります。

PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags)

mem を配下のバッファとしてmemoryview オブジェクトを作成します。 flags は PyBUF_READ か PyBUF_WRITE のどちらかになります。

バージョン 3.3 で追加.

PyObject *PyMemoryView_FromBuffer( Py_buffer *view)

view として与えられたバッファ構造をラップする memoryview オブジェクトを作成します。単なるバイトバッファ向けには、 PyMemoryView_FromMemory() のほうが望ましいです。

PyObject *PyMemoryView_GetContiguous( PyObject *obj, int buffertype, char order)

buffer インタフェースを定義しているオブジェクトから ('C' か 'F'ortran の order で) 連続した (contiguous) メモリチャンクへの memoryview オブジェクトを作ります。メモリが連続している場合、 memoryview オブジェクトは元のメモリを参照します。それ以外の場合、メモリはコピーされて、 memoryview オブジェクトは新しい bytes オブジェクトを参照します。

int PyMemoryView_Check( PyObject *obj)

obj が memoryview オブジェクトの場合に真を返します。現在のところ、 memoryview のサブクラスの作成は許可されていません。

Py_buffer *PyMemoryView_GET_BUFFER( PyObject *mview)

書きだされたバッファーの memoryview のプライベート コピーに、ポインターを返します。 mview は memoryview インスタンスでなければなりません; このマクロは型をチェックしないので自前で型チェックしなければならず、それを怠るとクラッシュする恐れがあります。

Py_buffer *PyMemoryView_GET_BASE( PyObject *mview)

memoryview をエクスポートしているオブジェクトへのポインタを返します。 memoryview が PyMemoryView_FromMemory() か PyMemoryView_FromBuffer() のどちらかで作成されていた場合、 NULL を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


弱参照オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

弱参照オブジェクト

Python は 弱参照 を第一級オブジェクト (first-class object) としてサポートします。弱参照を直接実装する二種類の固有のオブジェクト型があります。第一は単純な参照オブジェクトで、第二はオリジナルのオブジェクトに対して可能な限りプロキシとして振舞うオブジェクトです。

int PyWeakref_Check(ob)

ob が参照オブジェクトかプロキシオブジェクトの場合に真を返します。

int PyWeakref_CheckRef(ob)

ob が参照オブジェクトの場合に真を返します。

int PyWeakref_CheckProxy(ob)

ob がプロキシオブジェクトの場合に真を返します。

PyObject* PyWeakref_NewRef( PyObject *ob, PyObject *callback)
Return value: New reference.

ob に対する弱参照オブジェクトを返します。この関数は常に新たな参照を返しますが、必ずしも新たなオブジェクトを作る保証はありません; 既存の参照オブジェクトが返されることもあります。第二のパラメタ callback は呼び出し可能オブジェクトで、 ob がガーベジコレクションされた際に通知を受け取ります; callback は弱参照オブジェクト自体を単一のパラメタとして受け取ります。 callback は None や NULL にしてもかまいません。 ob が弱参照できないオブジェクトの場合や、 callback が呼び出し可能オブジェクト、 None 、 NULL のいずれでもない場合は、 NULL を返して TypeError を送出します。

PyObject* PyWeakref_NewProxy( PyObject *ob, PyObject *callback)
Return value: New reference.

ob に対する弱参照プロキシオブジェクトを返します。この関数は常に新たな参照を返しますが、必ずしも新たなオブジェクトを作る保証はありません; 既存の参照オブジェクトが返されることもあります。第二のパラメタ callback は呼び出し可能オブジェクトで、 ob がガーベジコレクションされた際に通知を受け取ります; callback は弱参照オブジェクト自体を単一のパラメタとして受け取ります。 callback は None や NULL にしてもかまいません。 ob が弱参照できないオブジェクトの場合や、 callback が呼び出し可能オブジェクト、 None 、 NULL のいずれでもない場合は、 NULL を返して TypeError を送出します。

PyObject* PyWeakref_GetObject( PyObject *ref)
Return value: Borrowed reference.

弱参照 ref が参照しているオブジェクトを返します。被参照オブジェクトがすでに存続していない場合、 Py_None を返します。

注釈

この関数は参照先オブジェクトの 借り物の参照 を返します。そのため、そのオブジェクトを利用している間そのオブジェクトが破棄されないことが判っている場合を除き、常に Py_INCREF() を呼び出すべきです。

PyObject* PyWeakref_GET_OBJECT( PyObject *ref)
Return value: Borrowed reference.

PyWeakref_GetObject() に似ていますが、マクロで実装されていて、エラーチェックを行いません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


カプセル

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

カプセル

using-capsules 以下のオブジェクトを使う方法については 拡張モジュールに C API を提供する を参照してください。

バージョン 3.1 で追加.

PyCapsule

この PyObject のサブタイプは、任意の値を表し、C拡張モジュールから Pythonコードを経由して他のC言語のコードに任意の値を(void* ポインタの形で)渡す必要があるときに有用です。あるモジュール内で定義されているC言語関数のポインタを、他のモジュールに渡してそこから呼び出せるようにするためによく使われます。これにより、動的にロードされるモジュールの中の C API に通常の import 機構を通してアクセスすることができます。

PyCapsule_Destructor

カプセルに対するデストラクタコールバック型. 次のように定義されます:

typedef void (*PyCapsule_Destructor)(PyObject *);

PyCapsule_Destructor コールバックの動作については PyCapsule_New() を参照してください。

int PyCapsule_CheckExact( PyObject *p)

引数が PyCapsule だったときに true を返します。

PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
Return value: New reference.

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)

カプセルに保存されている pointer を取り出します。失敗した場合は例外を設定して NULL を返します。

name 引数はカプセルに保存されている名前と正確に一致しなければなりません。もしカプセルに格納されている name が NULL なら、この関数の name 引数も同じく NULL でなければなりません。 Python は C言語の strcmp() を使ってこの name を比較します。

PyCapsule_Destructor PyCapsule_GetDestructor( PyObject *capsule)

カプセルに保存されている現在のデストラクタを返します。失敗した場合、例外を設定して NULL を返します。

カプセルは NULL をデストラクタとして持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred() を利用して確認してください。

void* PyCapsule_GetContext( PyObject *capsule)

カプセルに保存されている現在のコンテキスト(context)を返します。失敗した場合、例外を設定して NULL を返します。

カプセルは NULL をコンテキストとして持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred() を利用して確認してください。

const char* PyCapsule_GetName( PyObject *capsule)

カプセルに保存されている現在の name を返します。失敗した場合、例外を設定して NULL を返します。

カプセルは NULL を name として持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred() を利用して確認してください。

void* PyCapsule_Import(const char *name, int no_block)

モジュールのカプセル属性から Cオブジェクトへのポインタをインポートします。 name 引数はその属性の完全名を module.attribute のように指定しなければなりません。カプセルに格納されている name はこの文字列に正確に一致しなければなりません。 no_block が真の時、モジュールを(PyImport_ImportModuleNoBlock() を使って) ブロックせずにインポートします。 no_block が偽の時、モジュールは (PyImport_ImportModule() を使って) 通常の方法でインポートされます。

成功した場合、カプセルの内部 ポインタ を返します。失敗した場合、例外を設定して NULL を返します。

int PyCapsule_IsValid( PyObject *capsule, const char *name)

capsule が有効なカプセルであるかどうかをチェックします。有効な capsule は、非 NULL で、 PyCapsule_CheckExact() をパスし、非 NULL なポインタを格納していて、内部の name が引数 name とマッチします。 (name の比較方法については PyCapsule_GetPointer() を参照)

言い換えると、 PyCapsule_IsValid() が真を返す場合、全てのアクセッサ (PyCapsule_Get() で始まる全ての関数) が成功することが保証されます。

オブジェクトが有効で name がマッチした場合に非 0 を、それ以外の場合に 0 を返します。この関数は絶対に失敗しません。

int PyCapsule_SetContext( PyObject *capsule, void *context)

capsule 内部のコンテキストポインタを context に設定します。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

int PyCapsule_SetDestructor( PyObject *capsule, PyCapsule_Destructor destructor)

capsule 内部のデストラクタを destructor に設定します。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

int PyCapsule_SetName( PyObject *capsule, const char *name)

capsule 内部の name を name に設定します。name が非 NULL のとき、それは capsule よりも長い寿命を持つ必要があります。もしすでに capsule に非 NULL の name が保存されていた場合、それに対する解放は行われません。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

int PyCapsule_SetPointer( PyObject *capsule, void *pointer)

capsule 内部のポインタを pointer に設定します。pointer は NULL であってはなりません。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


ジェネレータオブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

ジェネレータオブジェクト

ジェネレータオブジェクトは、 Python がジェネレータイテレータを実装するのに使っているオブジェクトです。ジェネレータオブジェクトは通常、 PyGen_New() や PyGen_NewWithQualName() の明示的な呼び出しではなく、値を yield する関数のイテレーションにより生成されます。

PyGenObject

ジェネレータオブジェクトに使われている C 構造体です。

PyTypeObject PyGen_Type

ジェネレータオブジェクトに対応する型オブジェクトです。

int PyGen_Check( PyObject *ob)

ob がジェネレータオブジェクトの場合に真を返します。ob が NULL であってはなりません。

int PyGen_CheckExact( PyObject *ob)

ob の型が PyGen_Type のとき真を返します。ob が 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 であってはなりません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


コルーチンオブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

コルーチンオブジェクト

バージョン 3.5 で追加.

コルーチンオブジェクトは async キーワードを使って定義した関数が返すオブジェクトです。

PyCoroObject

コルーチンオブジェクトのための C 構造体。

PyTypeObject PyCoro_Type

コルーチンオブジェクトに対応する型オブジェクト。

int PyCoro_CheckExact( PyObject *ob)

ob の型が PyCoro_Type のときに true を返します。 ob は NULL であってはいけません。

PyObject* PyCoro_New( PyFrameObject *frame, PyObject *name, PyObject *qualname)
Return value: New reference.

frame オブジェクトから新しいコルーチンオブジェクトを生成して、 __name__ と __qualname__ を name と qualname に設定して返します。 この関数は frame への参照を奪います。 frame 引数は NULL であってはなりません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


コンテキスト変数オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

コンテキスト変数オブジェクト

注釈

バージョン 3.7.1 で変更:

In Python 3.7.1 the signatures of all context variables C APIs were changed to use PyObject pointers instead of PyContext, PyContextVar, and PyContextToken, e.g.:

// in 3.7.0:
PyContext *PyContext_New(void);

// in 3.7.1+:
PyObject *PyContext_New(void);

See bpo-34762 for more details.

バージョン 3.7 で追加.

この節では、 contextvars モジュールの公開 C API の詳細について説明します。

PyContext

contextvars.Context オブジェクトを表現するための C 構造体。

PyContextVar

contextvars.ContextVar オブジェクトを表現するための C 構造体。

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 を返します。

int PyContext_ClearFreeList()

コンテキスト変数のフリーリストをクリアします。 解放された要素数を返します。 この関数は常に成功します。

コンテキスト変数の関数:

PyObject *PyContextVar_New(const char *name, PyObject *def)
Return value: New reference.

新しい ContextVar オブジェクトを作成します。 name 引数は内部走査とデバッグの目的で使われます。 def 引数はコンテキスト変数の値を指定しますが、オプションです。 エラーが起きた場合は、関数は NULL を返します。

int PyContextVar_Get( PyObject *var, PyObject *default_value, PyObject **value)

コンテキスト変数の値を取得します。 取得中にエラーが起きた場合は -1 を、値が見付かっても見付からなくてもエラーが起きなかった場合は 0 を返します。

コンテキスト変数が見付かった場合、 value はそれを指すポインタになっています。 コンテキスト変数が見付から なかった 場合は、 value が指すものは次のようになっています:

  • (NULL でなければ) default_value
  • (NULL でなければ) var のデフォルト値
  • NULL

値が見付かった場合、この関数はその値への新しい参照を作成します。

PyObject *PyContextVar_Set( PyObject *var, PyObject *value)
Return value: New reference.

Set the value of var to value in the current context. Returns a pointer to a PyObject object, or NULL if an error has occurred.

int PyContextVar_Reset( PyObject *var, PyObject *token)

var コンテキスト変数の状態をリセットし、 token を返した PyContextVar_Set() が呼ばれる前の状態に戻します。 この関数は成功したら 0 、失敗したら -1 を返します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


DateTime オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »

DateTime オブジェクト

datetime モジュールでは、様々な日付オブジェクトや時刻オブジェクトを提供しています。以下に示す関数を使う場合には、あらかじめヘッダファイル datetime.h をソースに include し (Python.h はこのファイルを include しません)、 PyDateTime_IMPORT マクロを、通常はモジュール初期化関数から、起動しておく必要があります。このマクロは以下のマクロで使われる静的変数 PyDateTimeAPI に C 構造体へのポインタを入れます。

Macro for access to the UTC singleton:

PyObject* PyDateTime_TimeZone_UTC

Returns the time zone singleton representing UTC, the same object as datetime.timezone.utc.

バージョン 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.

Return a datetime.date object with the specified year, month and day.

PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
Return value: New reference.

Return a datetime.datetime object with the specified year, month, day, hour, minute, second and microsecond.

PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
Return value: New reference.

Return a datetime.time object with the specified hour, minute, second and microsecond.

PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
Return value: New reference.

Return a datetime.timedelta object representing the given number of days, seconds and microseconds. Normalization is performed so that the resulting number of microseconds and seconds lie in the ranges documented for datetime.timedelta objects.

PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)
Return value: New reference.

Return a datetime.timezone object with an unnamed fixed offset represented by the offset argument.

バージョン 3.7 で追加.

PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name)
Return value: New reference.

Return a datetime.timezone object with a fixed offset represented by the offset argument and with tzname name.

バージョン 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 の間の整数で返します。

以下のマクロは 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 の間の整数で返します。

以下のマクロは time delta オブジェクトからフィールド値をとりだすためのものです。引数は PyDateTime_Delta かそのサブクラスのインスタンスでなければなりません。引数を NULL にしてはならず、型チェックは行いません:

int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)

日数を -999999999 から 999999999 の間の整数で返します。

バージョン 3.3 で追加.

int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)

秒数を 0 から 86399 の間の整数で返します。

バージョン 3.3 で追加.

int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)

マイクロ秒を 0 から 999999 の間の整数で返します。

バージョン 3.3 で追加.

以下のマクロは DB API を実装する上での便宜用です:

PyObject* PyDateTime_FromTimestamp( PyObject *args)
Return value: New reference.

Create and return a new datetime.datetime object given an argument tuple suitable for passing to datetime.datetime.fromtimestamp().

PyObject* PyDate_FromTimestamp( PyObject *args)
Return value: New reference.

Create and return a new datetime.date object given an argument tuple suitable for passing to datetime.date.fromtimestamp().

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • 具象オブジェクト (concrete object) レイヤ »


初期化 (initialization)、終了処理 (finalization)、スレッド

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

初期化 (initialization)、終了処理 (finalization)、スレッド

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()
  • 情報取得の関数:
    • 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 に設定され、 -b では Py_BytesWarningFlag が 2 に設定されます。

Py_BytesWarningFlag

bytes または bytearray を str と比較した場合、または、 bytes を int と比較した場合に警告を発生させます。 値が 2 以上になった場合は、エラーを発生させます。

-b オプションで設定します。

Py_DebugFlag

パーサーのデバッグ出力を有効にします。(専門家専用です。コンパイルオプションに依存します)。

-d オプションと PYTHONDEBUG 環境変数で設定します。

Py_DontWriteBytecodeFlag

非ゼロに設定された場合、Python はソースモジュールのインポート時に .pyc ファイルの作成を試みません。

-B オプションと PYTHONDONTWRITEBYTECODE 環境変数で設定します。

Py_FrozenFlag

Py_GetPath() の中でモジュール検索パスを割り出しているときのエラーメッセージを抑制します。

_freeze_importlib プログラムと frozenmain プログラムが使用する非公開フラグです。

Py_HashRandomizationFlag

PYTHONHASHSEED 環境変数が空でない文字列に設定された場合に、 1 にセットされます。

フラグがゼロでない場合、 PYTHONHASHSEED 環境変数を読みシークレットハッシュシードを初期化します。

Py_IgnoreEnvironmentFlag

全ての PYTHON* 環境変数を無視します。例えば、 PYTHONPATH や PYTHONHOME などです。

-E オプションと -I オプションで設定します。

Py_InspectFlag

最初の引数にスクリプトが指定されたときや -c オプションが利用されたとき、 sys.stdin がターミナルに出力されないときでも、スクリプトかコマンドを実行した後にインタラクティブモードに入ります。

-i オプションと PYTHONINSPECT 環境変数で設定します。

Py_InteractiveFlag

-i オプションで設定します。

Py_IsolatedFlag

Python を隔離モードで実行します。 隔離モードでは sys.path はスクリプトのディレクトリやユーザのサイトパッケージのディレクトリを含みません。

-I オプションで設定します。

バージョン 3.4 で追加.

Py_LegacyWindowsFSEncodingFlag

フラグがゼロでない場合は、ファイルシステムエンコーディングに UTF-8 エンコーディングの代わりに mbcs エンコーディングが使われます。

PYTHONLEGACYWINDOWSFSENCODING 環境変数が空でない文字列に設定された場合に、 1 にセットされます。

より詳しくは PEP 529 を参照をしてください。

利用可能な環境: Windows 。

Py_LegacyWindowsStdioFlag

フラグがゼロでない場合、 sys の標準ストリームに WindowsConsoleIO の代わりに io.FileIO が使われます。

PYTHONLEGACYWINDOWSSTDIO 環境変数が空でない文字列に設定された場合に、 1 にセットされます。

より詳しくは PEP 528 を参照をしてください。

利用可能な環境: Windows 。

Py_NoSiteFlag

site モジュールの import と、そのモジュールが行なっていた site ごとの sys.path への操作を無効にします。後に site を明示的に import しても、これらの操作は実行されません (実行したい場合は、 site.main() を呼び出してください)。

-S オプションで設定します。

Py_NoUserSiteDirectory

user site-packages directory を sys.path に追加しません。

-s オプション、 -I 、 PYTHONNOUSERSITE 環境変数で設定します。

Py_OptimizeFlag

-O オプションと PYTHONOPTIMIZE 環境変数で設定します。

Py_QuietFlag

インタラクティブモードでも copyright とバージョンのメッセージを表示しません。

-q オプションで設定します。

バージョン 3.2 で追加.

Py_UnbufferedStdioFlag

標準出力と標準エラーがバッファリングしないように強制します。

-u オプションと PYTHONUNBUFFERED 環境変数で設定します。

Py_VerboseFlag

モジュールが初期化されるたびにメッセージを出力し、それがどこ (ファイル名やビルトインモジュール) からロードされたのかを表示します。 値が 2 以上の場合は、モジュールを検索するときにチェックされた各ファイルごとにメッセージを出力します。また、終了時のモジュールクリーンアップに関する情報も提供します。

-v オプションと PYTHONVERBOSE 環境変数で設定します。

インタプリタの初期化と終了処理

void Py_Initialize()

Python インタプリタを初期化します。 Python の埋め込みを行うアプリケーションでは、他のあらゆる Python/C API を使用するよりも前にこの関数を呼び出さなければなりません。いくつかの例外については Python 初期化以前 を参照してください。

この関数はロード済みモジュールのテーブル (sys.modules) を初期化し、基盤となるモジュール群、 builtins, __main__, sys を生成します。また、モジュール検索パス (sys.path) も初期化します。 sys.argv の設定は行いません。設定するには、 PySys_SetArgvEx() を使ってください。この関数を (Py_FinalizeEx() を呼ばずに) 再度呼び出しても何も行いません。戻り値はありません。初期化が失敗すれば、それは致命的なエラーです。

注釈

Windows では O_TEXT から O_BINARY へコンソールモードが変更されますが、これはその C ランタイムを使っているコンソールでの Python 以外の使い勝手にも影響を及ぼします。

void Py_InitializeEx(int initsigs)

initsigs に 1 を指定した場合、この関数は Py_Initialize() と同じように動作します。 initsigs に 0 を指定した場合、初期化時のシグナルハンドラの登録をスキップすることができ、これは Python の埋め込みで便利でしょう。

int Py_IsInitialized()

Python インタプリタが初期化済みであれば真(非ゼロ)を、さもなければ偽(ゼロ)を返します。Py_FinalizeEx() を呼び出した後は、Py_Initialize() を再び呼び出すまで、この関数は偽を返します。

int Py_FinalizeEx()

Py_Initialize() とそれ以後の Python/C API 関数で行った全ての初期化処理を取り消し、最後の Py_Initialize() 呼び出し以後に Python インタプリタが生成した全てのサブインタプリタ (sub-interpreter, 下記の Py_NewInterpreter() を参照) を消去します。 理想的な状況では、この関数によって Python インタプリタが確保したメモリは全て解放されます。 この関数を (Py_Initialize() を呼ばずに) 再度呼び出しても何も行いません。 通常は返り値は 0 です。終了処理中 (バッファリングされたデータの書き出し) のエラーがあった場合は -1 が返されます。

この関数が提供されている理由はいくつかあります。Python の埋め込みを行っているアプリケーションでは、アプリケーションを再起動することなく Python を再起動したいことがあります。また、動的ロード可能イブラリ (あるいは DLL) から Python インタプリタをロードするアプリケーションでは、DLL をアンロードする前に Python が確保したメモリを全て解放したいと考えるかもしれません。アプリケーション内で起きているメモリリークを追跡する際に、開発者は Python が確保したメモリをアプリケーションの終了前に解放させたいと思う場合もあります。

バグおよび注意事項: モジュールやモジュール内のオブジェクトはランダムな順番で削除されます。このため、他のオブジェクト(関数オブジェクトも含みます) やモジュールに依存するデストラクタ (__del__() メソッド) が失敗してしまうことがあります。動的にロードされるようになっている拡張モジュールが Python によってロードされていた場合、アンロードされません。 Python が確保したメモリがわずかながら解放されないかもしれません (メモリリークを発見したら、どうか報告してください)。オブジェクト間の循環参照に捕捉されているメモリは解放されないことがあります。拡張モジュールが確保したメモリは解放されないことがあります。拡張モジュールによっては、初期化ルーチンを 2 度以上呼び出すと正しく動作しないことがあります。こうした状況は、 Py_Initialize() や Py_FinalizeEx() を 2 度以上呼び出すと起こり得ます。

バージョン 3.6 で追加.

void Py_Finalize()

この関数は Py_FinalizeEx() の後方互換性バージョンで、戻り値がありません。

プロセスワイドのパラメータ

int Py_SetStandardStreamEncoding(const char *encoding, const char *errors)

もし Py_Initialize() が呼ばれるなら、この関数はその前に呼ばなければなりません。標準の IO において、どのエンコーディングおよびどんなエラー処理を使うかを、 str.encode() と同様の意味で指定します。

これは、環境変数が働かない時に PYTHONIOENCODING の値を上書きし、埋め込みコードが IO エンコーディングをコントロールできるようにします。

encoding と errors のどちらかまたは両方を NULL にすることで、 PYTHONIOENCODING とデフォルト値のどちらかまたは両方を使うことができます (他の設定に依存します)。

この設定 (あるいは他の設定) に関わらず、 sys.stderr は常に "backslashreplace" エラーハンドラを使うことに注意してください。

Py_FinalizeEx() を呼び出した場合は、Py_Initialize() を呼び出す前に、この関数を再度呼び出す必要があるでしょう。

成功したら 0 を、エラーの場合は 0 でない値を返します (例えば、インタプリタが初期化された後に、この関数が呼び出された場合)。

バージョン 3.4 で追加.

void Py_SetProgramName(const wchar_t *name)

この関数を呼び出すなら、最初に Py_Initialize() を呼び出すよりも前に呼び出さなければなりません。この関数はインタプリタにプログラムの main() 関数に指定した argv[0] 引数の値を教えます (ワイドキャラクタに変換されます)。この引数値は、 Py_GetPath() や、以下に示すその他の関数が、インタプリタの実行可能形式から Python ランタイムライブラリへの相対パスを取得するために使われます。デフォルトの値は 'python' です。引数はゼロ終端されたワイドキャラクタ文字列で、静的な記憶領域に入っていなければならず、その内容はプログラムの実行中に変更してはなりません。 Python インタプリタ内のコードで、この記憶領域の内容を変更するものは一切ありません。

バイト文字列を wchar_* 文字列にデコードするには Py_DecodeLocale() を使ってください。

wchar* Py_GetProgramName()

Py_SetProgramName() で設定されたプログラム名か、デフォルトのプログラム名を返します。関数が返す文字列ポインタは静的な記憶領域を返します。関数の呼び出し側はこの値を変更できません。

wchar_t* Py_GetPrefix()

プラットフォーム非依存のファイル群がインストールされている場所である prefix を返します。この値は Py_SetProgramName() でセットされたプログラム名やいくつかの環境変数をもとに、数々の複雑な規則から導出されます。例えば、プログラム名が '/usr/local/bin/python' の場合、prefix は '/usr/local' になります。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値はトップレベルの Makefile に指定されている変数 prefix や、ビルド値に configure スクリプトに指定した --prefix 引数に対応しています。この値は Python コードからは sys.prefix として利用できます。これはUnixでのみ有用です。次に説明する関数も参照してください。

wchar_t* Py_GetExecPrefix()

プラットフォーム 依存 のファイルがインストールされている場所である exec-prefix を返します。この値は Py_SetProgramName() でセットされたプログラム名やいくつかの環境変数をもとに、数々の複雑な規則から導出されます。例えば、プログラム名が '/usr/local/bin/python' の場合、exec-prefix は '/usr/local' になります。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値はトップレベルの Makefile に指定されている変数 exec_prefix や、ビルド値に configure スクリプトに指定した --exec-prefix 引数に対応しています。この値は Python コードからは sys.exec_prefix として利用できます。 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 を共有するための設定方法を知っているでしょう。

wchar_t* Py_GetProgramFullPath()

Python 実行可能形式の完全なプログラム名を返します; この値はデフォルトのモジュール検索パスを (前述の Py_SetProgramName() で設定された) プログラム名から導出する際に副作用的に計算されます。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.executable として利用できます。

wchar_t* Py_GetPath()

デフォルトのモジュール検索パスを返します; パスは (上の Py_SetProgramName() で設定された) プログラム名と、いくつかの環境変数から計算されます。戻り値となる文字列は、プラットフォーム依存のパス区切り文字で分割された一連のディレクトリ名からなります。区切り文字は Unix と Mac OS X では ':', Windows では ';' です。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。 sys.path はインタプリタによってこの値で初期化され、その後にモジュールをロードする際の検索パスを変更するために修正することが可能で、たいていそうされます。

void Py_SetPath(const wchar_t *)

デフォルトのモジュール検索パスを設定します。この関数が Py_Initialize() より前に呼び出された場合、 Py_GetPath() はデフォルトの検索パスを計算しようとせず、代わりにこの関数が与えた検索パスを返します。これは、 Python がアプリケーションに組み込まれていて、そのアプリケーションが全てのモジュールの場所を完全に把握しているときに便利です。パスはプラットフォーム依存の区切り文字で分割されている必要があります。区切り文字は Unix と Mac OS X では ':' 、Windows では ';' です。

また、この関数は sys.executable に特に加工されていないプログラム名 (Py_SetProgramName() を参照) をセットし、 sys.prefix と sys.exec_prefix に空文字列をセットします。 Py_Initialize() が呼び出された後で、これらの値を変更する必要がある場合は、呼び出し側の責任で行います。

バイト文字列を wchar_* 文字列にデコードするには Py_DecodeLocale() を使ってください。

パス引数は内部でコピーされます。したがって、呼び出し完了後に呼び出し元は引数を解放できます。

const char* Py_GetVersion()

Python インタプリタのバージョンを返します。バージョンは、次のような形式の文字列です

"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"

第一ワード (最初のスペース文字まで) は、現在の Python のバージョンです; 最初の三文字は、ピリオドで区切られたメジャーバージョンとマイナーバージョンです。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version として利用できます。

const char* Py_GetPlatform()

現在のプラットフォームのプラットフォーム識別文字列を返します。Unixでは、オペレーティングシステムの "公式の" 名前を小文字に変換し、後ろにメジャーリビジョン番号を付けた構成になっています。例えば Solaris 2.x は、SunOS 5.x, としても知られていますが、'sunos5' になります。Mac OS X では 'darwin' です。Windows では 'win' です。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.platform として利用できます。

const char* Py_GetCopyright()

現在の Python バージョンに対する公式の著作権表示文字列を返します。例えば

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.copyright として利用できます。

const char* Py_GetCompiler()

現在使っているバージョンの Python をビルドする際に用いたコンパイラを示す文字列を、角括弧で囲った文字列を返します。例えば:

"[GCC 2.7.2.2]"

関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version の一部として取り出せます。

const char* Py_GetBuildInfo()

現在使っている Python インタプリタインスタンスの、シーケンス番号とビルド日時に関する情報を返します。例えば

"#67, Aug  1 1997, 22:34:28"

関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version の一部として取り出せます。

void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)

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() を使ってください。

注釈

単一のスクリプトを実行する以外の目的でPython インタプリタを埋め込んでいるアプリケーションでは、 updatepath に 0 を渡して、必要な場合は自分で sys.path を更新することをおすすめします。 CVE-2008-5983 を参照してください。

3.1.3 より前のバージョンでは、 PySys_SetArgv() の呼び出しが完了した後に sys.path の先頭の要素を取り出すことで、同じ効果が得られます。例えばこのように使います:

PyRun_SimpleString("import sys; sys.path.pop(0)\n");

バージョン 3.1.3 で追加.

void PySys_SetArgv(int argc, wchar_t **argv)

この関数は、 python インタプリタが -I オプション付きで実行されている場合を除き PySys_SetArgvEx() の updatepath に 1 を設定したのと同じように動作します。

バイト文字列を wchar_* 文字列にデコードするには Py_DecodeLocale() を使ってください。

バージョン 3.4 で変更: updatepath の値は -I オプションに依存します。

void Py_SetPythonHome(const wchar_t *home)

Python の標準ライブラリがある、デフォルトの "home" ディレクトリを設定します。引数の文字列の意味については PYTHONHOME を参照してください。

引数は静的なストレージに置かれてプログラム実行中に書き換えられないようなゼロ終端の文字列であるべきです。Python インタプリタはこのストレージの内容を変更しません。

バイト文字列を wchar_* 文字列にデコードするには Py_DecodeLocale() を使ってください。

w_char* Py_GetPythonHome()

前回の Py_SetPythonHome() 呼び出しで設定されたデフォルトの "home" か、 PYTHONHOME 環境変数が設定されていればその値を返します。

スレッド状態 (thread state) とグローバルインタプリタロック (global interpreter lock)

Python インタプリタは完全にはスレッドセーフではありません。マルチスレッドの Python プログラムをサポートするために、グローバルインタプリタロック(global interpreter lock, 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 を混ぜて使うことはサポートされていません。

注意しないといけないもう一つの重要な点は、 C の fork() を呼び出した時の動作です。ほとんどの fork() を持っているシステムでは、fork されたプロセスには fork を実行したスレッドしか存在しません。これは、別のスレッドに取得されたロックがずっと解放されないことを意味します。 Python は fork する前にロックを取得し、その後に fork を解放することでこの os.fork() の問題を解決しています。加えて、子プロセスではすべての Lock オブジェクト をリセットします。 Python を拡張したり埋め込んだりしている場合、 Python に fork 前に取得したり fork 後に解放しなければならない追加の (Python 以外の) ロックを Python に教える手段がありません。 Python と同じことを実現するには、 pthread_atfork() のようなOSの機能を使う必要があります。加えて、Python を拡張したり埋め込んだりしているときに、 os.fork() を通してではなく直接 fork() を呼び出すと、fork後に失われるスレッドに取得されていた Python の内部ロックのためにデッドロックが発生するかもしれません。 PyOS_AfterFork_Child() は必要なロックのリセットを試みますが、いつでもそれが可能とは限りません。

高レベルAPI

C拡張を書いたりPythonインタプリタを埋め込むときに最も一般的に使われる型や関数は次のとおりです:

PyInterpreterState

このデータ構造体は、協調動作する多数のスレッド間で共有されている状態を表現します。同じインタプリタに属するスレッドはモジュール管理情報やその他いくつかの内部的な情報を共有しています。この構造体には公開 (public) のメンバはありません。

異なるインタプリタに属するスレッド間では、利用可能なメモリ、開かれているファイルデスクリプタなどといったプロセス状態を除いて、初期状態では何も共有されていません。GILもまた、スレッドがどのインタプリタに属しているかに関わらずすべてのスレッドで共有されています。

PyThreadState

単一のスレッドの状態を表現する表現するデータ構造体です。スレッドのインタプリタ状態を指すポインタ PyInterpreterState * interp だけが公開されているデータメンバです。

void PyEval_InitThreads()

GIL を初期化し、獲得します。この関数は、主スレッドが第二のスレッドを生成する以前や、 PyEval_ReleaseThread(tstate) といった他のスレッド操作に入るよりも前に呼び出されるようにしておかなければなりません。 PyEval_SaveThread(), PyEval_RestoreThread() の前に呼び出す必要はありません。

二度目に呼び出すと何も行いません。

バージョン 3.7 で変更: この関数は Py_Initialize() から呼び出されるようになり、わざわざ呼び出す必要はもう無くなりました。

バージョン 3.2 で変更: この関数は Py_Initialize() より前に呼び出すことができなくなりました。

int PyEval_ThreadsInitialized()

PyEval_InitThreads() をすでに呼び出している場合は真 (非ゼロ) を返します。この関数は、GILを獲得せずに呼び出すことができますので、シングルスレッドで実行している場合にはロック関連のAPI呼び出しを避けるために使うことができます。

バージョン 3.7 で変更: GIL が Py_Initialize() で初期化されるようになりました。

PyThreadState* PyEval_SaveThread()

(GIL が生成されていて、スレッドサポートが有効の場合) GILを解放して、スレッドの状態を NULL にし、以前のスレッド状態 (NULL にはなりません) を返します。ロックがすでに生成されている場合、現在のスレッドがロックを獲得していなければなりません。

void PyEval_RestoreThread( PyThreadState *tstate)

(GIL が生成されていて、スレッドサポートが有効の場合) GIL を獲得して、現在のスレッド状態を tstate に設定します。 tstate は NULL であってはなりません。 GIL が生成されていて、この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。

PyThreadState* PyThreadState_Get()

現在のスレッド状態を返します。GIL を保持していなければなりません。現在のスレッド状態が NULL なら、(呼び出し側が NULL チェックをしなくてすむように) この関数は致命的エラーを起こすようになっています。

PyThreadState* PyThreadState_Swap( PyThreadState *tstate)

現在のスレッド状態を tstate に指定したスレッド状態と入れ変えます。tstate は NULL の場合があります。GIL を保持していなければならず、解放しません。

void PyEval_ReInitThreads()

この関数は PyOS_AfterFork_Child() から呼び出され、新しい子プロセスが、子プロセス内で実行していないスレッドが持っているロックを持たないようにします。

以下の関数はスレッドローカルストレージを利用していて、サブインタプリタとの互換性がありません:

PyGILState_STATE PyGILState_Ensure()

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 コードを実行できます。処理の失敗は致命的なエラーです。

void PyGILState_Release(PyGILState_STATE)

獲得したすべてのリソースを解放します。この関数を呼び出すと、Pythonの状態は対応する PyGILState_Ensure() を呼び出す前と同じとなります (通常、この状態は呼び出し元でははわかりませんので、GILState APIを利用するようにしてください)。

PyGILState_Ensure() を呼び出す場合は、必ず同一スレッド内で対応する PyGILState_Release() を呼び出してください。

PyThreadState* PyGILState_GetThisThreadState()

このスレッドの現在のスレッドの状態を取得します。これまで現在のスレッドで GILState API を使ったことが無い場合は、NULL が返ります。メインスレッドで自身のスレッド状態に関する呼び出しを全くしないとしても、メインスレッドは常にスレッド状態の情報を持っていることに注意してください。こうなっている目的は主にヘルパ機能もしくは診断機能のためです。

int PyGILState_Check()

現在のスレッドが GILを保持しているならば 1 を、そうでなければ 0 を返します。この関数はいつでもどのスレッドからでも呼び出すことができます。 Python スレッドの状態が初期化されており、現在 GIL を保持している場合にのみ 1 を返します。これは主にヘルパー/診断用の関数です。この関数は、例えばコールバックのコンテキストやメモリ割り当て機能で有益でしょう。なぜなら、 GIL がロックされていると知っていれば、呼び出し元は sensitive な行動を実行することができ、そうでなければ異なるやりかたで振る舞うことができるからです。

バージョン 3.4 で追加.

以下のマクロは、通常末尾にセミコロンを付けずに使います; Python ソース配布物内の使用例を見てください。

Py_BEGIN_ALLOW_THREADS

このマクロを展開すると { PyThreadState *_save; _save = PyEval_SaveThread(); になります。マクロに開き波括弧が入っていることに注意してください; この波括弧は後で Py_END_ALLOW_THREADS マクロと対応させなければなりません。マクロについての詳しい議論は上記を参照してください。

Py_END_ALLOW_THREADS

このマクロを展開すると PyEval_RestoreThread(_save); } になります。マクロに開き波括弧が入っていることに注意してください; この波括弧は事前の Py_BEGIN_ALLOW_THREADS マクロと対応していなければなりません。マクロについての詳しい議論は上記を参照してください。

Py_BLOCK_THREADS

このマクロを展開すると PyEval_RestoreThread(_save); になります: 閉じ波括弧のない Py_END_ALLOW_THREADS と同じです。

Py_UNBLOCK_THREADS

このマクロを展開すると _save = PyEval_SaveThread(); になります: 開き波括弧のない Py_BEGIN_ALLOW_THREADS と同じです。

低レベルAPI

次の全ての関数は Py_Initialize() の後に呼び出さなければなりません。

バージョン 3.7 で変更: Py_Initialize() は GIL を初期化するようになりました。

PyInterpreterState* PyInterpreterState_New()

新しいインタプリタ状態オブジェクトを生成します。GIL を保持しておく必要はありませんが、この関数を次々に呼び出す必要がある場合には保持しておいたほうがよいでしょう。

void PyInterpreterState_Clear( PyInterpreterState *interp)

インタプリタ状態オブジェクト内の全ての情報をリセットします。GIL を保持していなければなりません。

void PyInterpreterState_Delete( PyInterpreterState *interp)

インタプリタ状態オブジェクトを破壊します。GIL を保持しておく必要はありません。インタプリタ状態は PyInterpreterState_Clear() であらかじめリセットしておかなければなりません。

PyThreadState* PyThreadState_New( PyInterpreterState *interp)

指定したインタプリタオブジェクトに属する新たなスレッド状態オブジェクトを生成します。GIL を保持しておく必要はありませんが、この関数を次々に呼び出す必要がある場合には保持しておいたほうがよいでしょう。

void PyThreadState_Clear( PyThreadState *tstate)

スレッド状態オブジェクト内の全ての情報をリセットします。GIL を保持していなければなりません。

void PyThreadState_Delete( PyThreadState *tstate)

スレッド状態オブジェクトを破壊します。GIL を保持する必要はありません。スレッド状態は PyThreadState_Clear() であらかじめリセットしておかなければなりません。

PY_INT64_T PyInterpreterState_GetID( PyInterpreterState *interp)

インタプリタの一意な ID を返します。 処理中に何かエラーが起きたら、 -1 が返され、エラーがセットされます。

バージョン 3.7 で追加.

PyObject* PyThreadState_GetDict()
Return value: Borrowed reference.

拡張モジュールがスレッド固有の状態情報を保存できるような辞書を返します。各々の拡張モジュールが辞書に状態情報を保存するためには唯一のキーを使わなければなりません。現在のスレッド状態がない時にこの関数を呼び出してもかまいません。この関数が NULL を返す場合、例外はまったく送出されず、呼び出し側は現在のスレッド状態が利用できないと考えなければなりません。

int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)

スレッド内で非同期的に例外を送出します。 id 引数はターゲットとなるスレッドのスレッド id です; exc は送出する例外オブジェクトです。この関数は exc に対する参照を一切盗み取りません。安直な間違いを防ぐため、この関数を呼び出すには独自に C 拡張モジュールを書かなければなりません。 GIL を保持した状態で呼び出さなければなりません。状態が変更されたスレッドの数を返します; 通常は 1 ですが、スレッドが見付からなかった場合は 0 になることもあります。 exc が NULL の場合は、このスレッドのまだ送出されていない例外は (何であれ) 消去されます。この場合は例外を送出しません。

バージョン 3.7 で変更: id 引数の型が long から unsigned long へ変更されました。

void PyEval_AcquireThread( PyThreadState *tstate)

GIL を獲得し、現在のスレッド状態を tstate に設定します。 tstate は NULL であってはなりません。ロックはあらかじめ作成されていなければなりません。この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。

PyEval_RestoreThread() はいつでも (スレッドが初期化されたいないときでも) 利用可能な高レベル関数です。

void PyEval_ReleaseThread( PyThreadState *tstate)

現在のスレッド状態をリセットして NULL にし、GIL を解放します。ロックはあらかじめ作成されていなければならず、かつ現在のスレッドが保持していなければなりません。tstate は NULL であってはなりませんが、その値が現在のスレッド状態を表現しているかどうかを調べるためにだけ使われます --- もしそうでなければ、致命的エラーが報告されます。

PyEval_SaveThread() はより高レベルな関数で常に (スレッドが初期化されていないときでも) 利用できます。

void PyEval_AcquireLock()

GILを獲得します。ロックは前もって作成されていなければなりません。この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。

バージョン 3.2 で非推奨: この関数は現在のスレッドの状態を更新しません。代わりに PyEval_RestoreThread() もしくは PyEval_AcquireThread() を使用してください。

void PyEval_ReleaseLock()

GILを解放します。ロックは前もって作成されていなければなりません。

バージョン 3.2 で非推奨: この関数は現在のスレッドの状態を更新しません。代わりに PyEval_SaveThread() もしくは PyEval_ReleaseThread() を使用してください。

サブインタプリタサポート

ほとんどの場合は埋め込む Python インタプリタは1つだけですが、いくつかの場合に同一プロセス内、あるいは同一スレッド内で、複数の独立したインタプリタを作成する必要があります。サブインタプリタはこれを可能にします。 PyThreadState_Swap() 関数を使ってサブインタプリタを切り替えることができます。以下の関数を使ってサブインタプリタの作成と削除を行えます:

PyThreadState* Py_NewInterpreter()

新しいサブインタプリタ (sub-interpreter) を生成します。サブインタプリタとは、(ほぼ完全に) 個別に分割された Python コードの実行環境です。特に、新しいサブインタプリタは、 import されるモジュール全てについて個別のバージョンを持ち、これには基盤となるモジュール builtins, __main__ および sys も含まれます。ロード済みのモジュールからなるテーブル (sys.modules) およびモジュール検索パス (sys.path) もサブインタプリタ毎に別個のものになります。新たなサブインタプリタ環境には sys.argv 変数がありません。また、サブインタプリタは新たな標準 I/O ストリーム sys.stdin, sys.stdout, sys.stderr を持ちます (とはいえ、これらのストリームは根底にある同じファイル記述子を参照しています)。

戻り値は、新たなサブインタプリタが生成したスレッド状態 (thread state) オブジェクトのうち、最初のものを指しています。このスレッド状態が現在のスレッド状態 (current thread state) になります。実際のスレッドが生成されるわけではないので注意してください; 下記のスレッド状態に関する議論を参照してください。新たなインタプリタの生成に失敗すると、NULL を返します; 例外状態はセットされませんが、これは例外状態が現在のスレッド状態に保存されることになっていて、現在のスレッド状態なるものが存在しないことがあるからです。(他の Python/C API 関数のように、この関数を呼び出す前にはGILが保持されていなければならず、関数が処理を戻した際にも保持されたままになります; しかし、他の Python/C API 関数とは違い、関数から戻ったときの現在のスレッド状態が関数に入るときと同じとは限らないので注意してください。)

拡張モジュールは以下のような形で (サブ) インタプリタ間で共有されます: ある特定の拡張モジュールを最初に import すると、モジュールを通常通りに初期化し、そのモジュールの辞書の (浅い) コピーをしまい込んでおきます。他の (サブ) インタプリタが同じ拡張モジュールを import すると、新たなモジュールを初期化し、先ほどのコピーの内容で辞書の値を埋めます; 拡張モジュールの init 関数は呼び出されません。この挙動は、 Py_FinalizeEx() および Py_Initialize() を呼び出してインタプリタを完全に再初期化した後に拡張モジュールを import した際の挙動とは異なるので注意してください; 再初期化後に import を行うと、拡張モジュールの initmodule は再度 呼び出されます 。

void Py_EndInterpreter( PyThreadState *tstate)

指定されたスレッド状態 tstate で表現される (サブ) インタプリタを抹消します。 tstate は現在のスレッド状態でなければなりません。下記のスレッド状態に関する議論を参照してください。関数呼び出しが戻ったとき、現在のスレッド状態は NULL になっています。このインタプリタに関連付けられた全てのスレッド状態は抹消されます。 (この関数を呼び出す前にはGILを保持しておかなければならず、ロックは関数が戻ったときも保持されています。) Py_FinalizeEx() は、その時点で明示的に抹消されていない全てのサブインタプリタを抹消します。

バグと注意事項

サブインタプリタ (とメインインタプリタ) は同じプロセスの一部分なので、インタプリタ間の隔離は完璧ではありません --- 例えば、 os.close() のような低レベルのファイル操作を使うと、 (偶然なり故意なりに) 互いのインタプリタ下にある開かれたファイルに影響を及ぼせてしまいます。拡張モジュールを (サブ) インタプリタ間で共有する方法のせいで、拡張モジュールによっては正しく動作しないかもしれません; 拡張モジュールが (静的な) グローバル変数を利用している場合や、拡張モジュールが初期化後に自身のモジュール辞書を操作する場合には特にそうです。一つのサブインタプリタで生成されたオブジェクトは他のサブインタプリタの名前空間への挿入が可能です; ユーザ定義関数、メソッド、インスタンスおよびクラスをサブインタプリタをサブインタプリタ間で共有しないように十分注意してください。というのは、これらの共有オブジェクトが実行した import 文は間違った (サブ) インタプリタのロード済みモジュール辞書に影響を及ぼす場合があるからです。

サブインタプリタを PyGILState_*() API と組み合わせるのが難しいことにも注意してください。これらのAPIはPythonのスレッド状態とOSレベルスレッドが1対1で対応していることを前提にしていて、サブインタプリタが存在するとその前提が崩れるからです。対応する PyGILState_Ensure() と PyGILState_Release() の呼び出しのペアの間では、サブインタプリタの切り替えを行わないことを強く推奨します。さらに、(ctypes のような)これらのAPIを使ってPythonの外で作られたスレッドから Pythonコードを実行している拡張モジュールはサブインタプリタを使うと壊れる可能性があります。

非同期通知

インタプリタのメインスレッドに非同期な通知を行うために提供されている仕組みです。これらの通知は関数ポインタと void ポインタ引数という形態を取ります。

int Py_AddPendingCall(int (*func)(void *), void *arg)

インタプリタのメインスレッドから関数が呼び出される予定を組みます。成功すると 0 が返り、func はメインスレッドの呼び出しキューに詰められます。失敗すると、例外をセットせずに -1 が返ります。

無事にキューに詰められると、func は いつかは必ず インタプリタのメインスレッドから、arg を引数として呼び出されます。この関数は、通常の実行中の Python コードに対して非同期に呼び出されますが、次の両方の条件に合致したときに呼び出されます:

  • bytecode 境界上にいるとき、
  • メインスレッドが global interpreter lock を保持している (すなわち func が全ての C API を呼び出せる) とき。

成功したら func は 0 を返さねばならず、失敗したら -1 を返し例外をセットしなければいけません。func は、他の非同期通知を行うために、さらに割り込まれることはありませんが、グローバルインタプリタロックが解放された場合は、スレッドの切り替えによって割り込まれる可能性が残っています。

この関数は実行するのに現在のスレッド状態を必要とせず、グローバルインタプリタロックも必要としません。

警告

これは、非常に特別な場合にのみ役立つ、低レベルな関数です。 func が可能な限り早く呼び出される保証はありません。メインスレッドがシステムコールを実行するのに忙しい場合は、 func はシステムコールが返ってくるまで呼び出されないでしょう。この関数は一般的には、任意の C スレッドから Python コードを呼び出すのには 向きません 。これの代わりに、 PyGILState API を使用してください。

バージョン 3.1 で追加.

プロファイルとトレース (profiling and tracing)

Python インタプリタは、プロファイル: 分析 (profile) や実行のトレース: 追跡 (trace) といった機能を組み込むために低水準のサポートを提供しています。このサポートは、プロファイルやデバッグ、適用範囲分析 (coverage analysis) ツールなどに使われます。

この C インタフェースは、プロファイルやトレース作業時に、Python レベルの呼び出し可能オブジェクトが呼び出されることによるオーバヘッドを避け、直接 C 関数呼び出しが行えるようにしています。プロファイルやトレース機能の本質的な特性は変わっていません; インタフェースではトレース関数をスレッドごとにインストールでき、トレース関数に報告される基本イベント (basic event) は以前のバージョンにおいて Python レベルのトレース関数で報告されていたものと同じです。

int (*Py_tracefunc)( PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

PyEval_SetProfile() および PyEval_SetTrace() を使って登録できるトレース関数の形式です。最初のパラメタはオブジェクトで、登録関数に obj として渡されます。 frame はイベントが属している実行フレームオブジェクトで、 what は定数 PyTrace_CALL, PyTrace_EXCEPTION, PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_RETURN, PyTrace_OPCODE のいずれかで、 arg は 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

行番号イベントを報告するときに、 (プロファイル関数ではなく) Py_tracefunc 関数に what 引数として渡す値です。 f_trace_lines が 0 に設定されたフレームでは無効化されていることもあります。

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

新しい opcode が実行されるときに、 (プロファイル関数ではなく) Py_tracefunc 関数に what 引数として渡す値です。 デフォルトではイベントは発火しません。フレーム上で f_trace_lines を 1 に設定して、明示的に要請しなければなりません。

void PyEval_SetProfile( Py_tracefunc func, PyObject *obj)

プロファイル関数を func に設定します。 obj パラメタは関数の第一引数として渡されるもので、何らかの Python オブジェクトあるいは NULL です。 プロファイル関数がスレッド状態を維持する必要があるなら、各々のスレッドに異なる obj を使うことで、状態を記憶しておく便利でスレッドセーフな場所を提供できます。 プロファイル関数は、モニタされているイベントのうち、 PyTrace_LINE PyTrace_OPCODE, PyTrace_EXCEPTION を除く全てのイベントに対して呼び出されます。

void PyEval_SetTrace( Py_tracefunc func, PyObject *obj)

トレース関数を func に設定します。 この関数は PyEval_SetProfile() と同じですが、トレース関数は行番号イベントおよび opcode イベントを受け取り、呼び出された C 関数オブジェクトと関係する任意のイベントを受け取らないところが異なっています。 PyEval_SetTrace() で登録されたトレース関数は、what 引数の値として PyTrace_C_CALL, PyTrace_C_EXCEPTION, PyTrace_C_RETURN を受け取りません。

高度なデバッガサポート (advanced debugger support)

以下の関数は高度なデバッグツールでの使用のためだけのものです。

PyInterpreterState* PyInterpreterState_Head()

インタプリタ状態オブジェクトからなるリストのうち、先頭にあるものを返します。

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 を使います。

バージョン 3.7 で追加.

参考

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

Py_tss_t

This data structure represents the state of a thread key, the definition of which may depend on the underlying TLS implementation, and it has an internal field representing the key's initialization state. There are no public members in this structure.

Py_LIMITED_API が定義されていないときは、この型の Py_tss_NEEDS_INIT による静的メモリ確保ができます。

Py_tss_NEEDS_INIT

このマクロは Py_tss_t 変数の初期化子に展開されます。 このマクロは Py_LIMITED_API があるときは定義されません。

動的メモリ確保

Dynamic allocation of the Py_tss_t, required in extension modules built with Py_LIMITED_API, where static allocation of this type is not possible due to its implementation being opaque at build time.

Py_tss_t* PyThread_tss_alloc()

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)

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)

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)

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)

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)

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)

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.

Due to the compatibility problem noted above, this version of the API should not be used in new code.

int PyThread_create_key()
void PyThread_delete_key(int key)
int PyThread_set_key_value(int key, void *value)
void* PyThread_get_key_value(int key)
void PyThread_delete_key_value(int key)
void PyThread_ReInitTLS()

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


メモリ管理

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

メモリ管理

概要

Python におけるメモリ管理には、全ての Python オブジェクトとデータ構造が入ったプライベートヒープ (private heap) が必須です。プライベートヒープの管理は、内部的には Python メモリマネージャ (Python memory manager) が確実に行います。Python メモリマネージャには、共有 (sharing)、セグメント分割 (segmentation)、事前割り当て (preallocation)、キャッシュ化 (caching) といった、様々な動的記憶管理の側面を扱うために、個別のコンポーネントがあります。

最低水準層では、素のメモリ操作関数 (raw memory allocator) がオペレーティングシステムのメモリ管理機構とやりとりして、プライベートヒープ内にPython 関連の全てのデータを記憶するのに十分な空きがあるかどうか確認します。素のメモリ操作関数の上には、いくつかのオブジェクト固有のメモリ操作関数があります。これらは同じヒープを操作し、各オブジェクト型固有の事情に合ったメモリ管理ポリシを実装しています。例えば、整数オブジェクトは文字列やタプル、辞書とは違ったやり方でヒープ内で管理されます。というのも、整数には値を記憶する上で特別な要件があり、速度/容量のトレードオフが存在するからです。このように、Python メモリマネジャは作業のいくつかをオブジェクト固有のメモリ操作関数に委譲しますが、これらの関数がプライベートヒープからはみ出してメモリ管理を行わないようにしています。

It is important to understand that the management of the Python heap is performed by the interpreter itself and that the user has no control over it, even if they regularly manipulate object pointers to memory blocks inside that heap. The allocation of heap space for Python objects and other internal buffers is performed on demand by the Python memory manager through the Python/C API functions listed in this document.

メモリ管理の崩壊を避けるため、拡張モジュールの作者は決して 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 メモリマネージャーは戻り値として返される文字列オブジェクトを確保する時にだけ必要です。

とはいえ、ほとんどの状況では、メモリの操作は Python ヒープに固定して行うよう勧めます。なぜなら、Python ヒープは Python メモリマネジャの管理下にあるからです。例えば、インタプリタを C で書かれた新たなオブジェクト型で拡張する際には、ヒープでのメモリ管理が必要です。Python ヒープを使った方がよいもう一つの理由として、拡張モジュールが必要としているメモリについて Python メモリマネージャに 情報を提供 してほしいということがあります。たとえ必要なメモリが内部的かつ非常に特化した用途に対して排他的に用いられるものだとしても、全てのメモリ操作要求を Python メモリマネージャに委譲すれば、インタプリタはより正確なメモリフットプリントの全体像を把握できます。その結果、特定の状況では、Python メモリマネージャがガベージコレクションやメモリのコンパクト化、その他何らかの予防措置といった、適切な動作をトリガできることがあります。上の例で示したように C ライブラリのメモリ操作関数を使うと、I/O バッファ用に確保したメモリは Python メモリマネージャの管理から完全に外れることに注意してください。

参考

環境変数 PYTHONMALLOC を使用して Python が利用するメモリアロケータを制御することができます。

環境変数 PYTHONMALLOCSTATS を使用して、新たなオブジェクトアリーナが生成される時と、シャットダウン時に pymalloc メモリアロケータ の統計情報を表示できます。

生メモリインタフェース

以下の関数群はシステムのアロケータをラップします。 これらの関数はスレッドセーフで、 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.

バージョン 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 でないポインタを返します。

バージョン 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)

Frees the memory block pointed to by p, which must have been returned by a previous call to PyMem_RawMalloc(), PyMem_RawRealloc() or PyMem_RawCalloc(). Otherwise, or if PyMem_RawFree(p) has been called before, undefined behavior occurs.

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)

n バイトを割り当て、そのメモリを指す void* 型のポインタを返します。要求が失敗した場合 NULL を返します。

0バイトを要求すると、 PyMem_Malloc(1) が呼ばれたときと同じように、可能なら NULL でないユニークなポインタを返します。 確保されたメモリーにはいかなる初期化も行われません。

void* PyMem_Calloc(size_t nelem, size_t elsize)

各要素が elsize バイトの要素 nelem 個分のメモリーを確保し、そのメモリーを指す void* 型のポインタを返します。アロケートに失敗した場合は NULL を返します。確保されたメモリー領域はゼロで初期化されます。

要素数か要素のサイズが0バイトの要求に対しては、可能なら PyMem_Calloc(1, 1) が呼ばれたのと同じように、ユニークな NULL でないポインタを返します。

バージョン 3.5 で追加.

void* PyMem_Realloc(void *p, size_t n)

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)

p が指すメモリブロックを解放します。 p は以前呼び出した PyMem_Malloc()、 PyMem_Realloc()、または PyMem_Calloc() の返した値でなければなりません。それ以外の場合や PyMem_Free(p) を呼び出した後だった場合、未定義の動作になります。

p が NULL の場合何もしません。

以下に挙げる型対象のマクロは利便性のために提供されているものです。TYPE は任意の C の型を表します。

TYPE* PyMem_New(TYPE, size_t n)

PyMem_Malloc() と同じですが、 (n * sizeof(TYPE)) バイトのメモリを確保します。 TYPE* に型キャストされたポインタを返します。メモリには何の初期化も行われていません。

TYPE* PyMem_Resize(void *p, TYPE, size_t n)

PyMem_Realloc() と同じですが、 (n * sizeof(TYPE)) バイトにサイズ変更されたメモリを確保します。 TYPE* に型キャストされたポインタを返します。 関数が終わったとき、 p は新しいメモリ領域のポインタか、失敗した場合は NULL になります。

これは 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)

Object allocators

以下の関数群が利用して Python ヒープに対してメモリを確保したり解放したり出来ます。これらの関数は ANSI C 標準に従ってモデル化されていますが、0 バイトを要求した際の動作についても定義しています:

The default object allocator uses the pymalloc memory allocator.

警告

これらの関数を呼ぶときには、 GIL を保持しておく必要があります。

void* PyObject_Malloc(size_t n)

n バイトを割り当て、そのメモリを指す void* 型のポインタを返します。要求が失敗した場合 NULL を返します。

Requesting zero bytes returns a distinct non-NULL pointer if possible, as if PyObject_Malloc(1) had been called instead. The memory will not have been initialized in any way.

void* PyObject_Calloc(size_t nelem, size_t elsize)

各要素が elsize バイトの要素 nelem 個分のメモリーを確保し、そのメモリーを指す void* 型のポインタを返します。アロケートに失敗した場合は NULL を返します。確保されたメモリー領域はゼロで初期化されます。

Requesting zero elements or elements of size zero bytes returns a distinct non-NULL pointer if possible, as if PyObject_Calloc(1, 1) had been called instead.

バージョン 3.5 で追加.

void* PyObject_Realloc(void *p, size_t n)

p が指すメモリブロックを n バイトにリサイズします。古いサイズと新しいサイズの小さい方までの内容は変更されません。

If p is NULL, the call is equivalent to PyObject_Malloc(n); else if n is equal to zero, the memory block is resized but is not freed, and the returned pointer is non-NULL.

Unless p is NULL, it must have been returned by a previous call to PyObject_Malloc(), PyObject_Realloc() or PyObject_Calloc().

If the request fails, PyObject_Realloc() returns NULL and p remains a valid pointer to the previous memory area.

void PyObject_Free(void *p)

Frees the memory block pointed to by p, which must have been returned by a previous call to PyObject_Malloc(), PyObject_Realloc() or PyObject_Calloc(). Otherwise, or if PyObject_Free(p) has been called before, undefined behavior occurs.

p が NULL の場合何もしません。

Default Memory Allocators

Default memory allocators:

Configuration | 名前 | PyMem_RawMalloc | PyMem_Malloc | PyObject_Malloc
Release build | "pymalloc" | malloc | pymalloc | pymalloc
Debug build | "pymalloc_debug" | malloc + debug | pymalloc + debug | pymalloc + debug
Release build, without pymalloc | "malloc" | malloc | malloc | malloc
Debug build, without pymalloc | "malloc_debug" | malloc + debug | malloc + debug | malloc + debug

Legend:

  • 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 installed by PyMem_SetupDebugHooks()

メモリアロケータをカスタマイズする

バージョン 3.4 で追加.

PyMemAllocatorEx

メモリブロックアロケータを記述するための構造体です。4つのフィールドを持ちます:

フィールド | 意味
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 で変更: PyMemAllocator 構造体が PyMemAllocatorEx にリネームされた上で calloc フィールドが追加されました。

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 でないポインタを返さなければなりません。

PYMEM_DOMAIN_RAW ドメインでは、アロケータはスレッドセーフでなければなりません: アロケータが呼び出されたとき GIL は保持されていません。

新しいアロケータがフックでない (1つ前のアロケータを呼び出さない) 場合、 PyMem_SetupDebugHooks() 関数を呼び出して、新しいアロケータの上にデバッグフックを再度設置しなければなりません。

void PyMem_SetupDebugHooks(void)

Python メモリアロケータ関数のバグを検出するためのフックを設定します。

新たに割り当てられたメモリはバイト 0xCB で埋められ、解放されたメモリはバイト 0xDB で埋められます。

実行時チェック:

  • 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

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.

These hooks are installed by default if Python is compiled in debug mode. The PYTHONMALLOC environment variable can be used to install debug hooks on a Python compiled in release mode.

バージョン 3.6 で変更: This 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.

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

アリーナアロケータは、次の関数を使います:

  • Windows では VirtualAlloc() と VirtualFree()、
  • 利用できる場合、mmap() と munmap()、
  • それ以外の場合は malloc() と free()。

pymalloc アリーナアロケータのカスタマイズ

バージョン 3.4 で追加.

PyObjectArenaAllocator

アリーナアロケータを記述するための構造体です。3つのフィールドを持ちます:

フィールド | 意味
void *ctx | 第一引数として渡されるユーザコンテクスト
void* alloc(void *ctx, size_t size) | size バイトのアリーナを割り当てます
void free(void *ctx, size_t size, void *ptr) | アリーナを解放します
PyObject_GetArenaAllocator( PyObjectArenaAllocator *allocator)

アリーナアロケータを取得します。

PyObject_SetArenaAllocator( PyObjectArenaAllocator *allocator)

アリーナアロケータを設定します。

tracemalloc C API

バージョン 3.7 で追加.

使用例

最初に述べた関数セットを使って、 概要 節の例を 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()  */

素のメモリブロックを Python ヒープ上で操作する関数に加え、 PyObject_New() 、 PyObject_NewVar() 、および PyObject_Del() を使うと、 Python におけるオブジェクトをメモリ確保したり解放したりできます。

これらの関数については、次章の C による新しいオブジェクト型の定義や実装に関する記述の中で説明します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


オブジェクト実装サポート (object implementation support)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

オブジェクト実装サポート (object implementation support)

この章では、新しいオブジェクトの型を定義する際に使われる関数、型、およびマクロについて説明します。

  • オブジェクトをヒープ上にメモリ確保する
  • 共通のオブジェクト構造体 (common object structure)
  • 型オブジェクト
  • 数値オブジェクト構造体
  • マップオブジェクト構造体
  • シーケンスオブジェクト構造体
  • バッファオブジェクト構造体 (buffer object structure)
  • async オブジェクト構造体
  • 循環参照ガベージコレクションをサポートする

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


オブジェクトをヒープ上にメモリ確保する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • オブジェクト実装サポート (object implementation support) »

オブジェクトをヒープ上にメモリ確保する

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.

新たにメモリ確保されたオブジェクト op に対し、型と初期状態での参照 (initial reference) を初期化します。初期化されたオブジェクトを返します。type からそのオブジェクトが循環参照ガベージ検出の機能を有する場合、検出機構が監視対象とするオブジェクトのセットに追加されます。オブジェクトの他のフィールドには影響を及ぼしません。

PyVarObject* PyObject_InitVar( PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
Return value: Borrowed reference.

PyObject_Init() の全ての処理を行い、可変サイズオブジェクトの場合には長さ情報も初期化します。

TYPE* PyObject_New(TYPE, PyTypeObject *type)
Return value: New reference.

C 構造体型 TYPE と Python型オブジェクト type を使って、新しい Python オブジェクトをメモリ上に確保します。Pythonオブジェクトヘッダで定義されていないフィールドは初期化されません; オブジェクトの参照カウントは 1 になります。確保するメモリのサイズは型オブジェクトの tp_basicsize フィールドで決まります。

TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Return value: New reference.

C 構造体型 TYPE と Python 型オブジェクト type を使って新しい Python オブジェクトをメモリ上に確保します。 Python オブジェクトヘッダで定義されていないフィールドは初期化されません。確保されたメモリは、 TYPE 構造体に加え、type の tp_itemsize フィールドで指定されているサイズを size 個分の大きさを格納できます。この関数は、例えばタプルのように生成時にサイズを決定できるオブジェクトを実装する際に便利です。一連の複数のフィールドのメモリ割り当てを一度で行うことでアロケーション回数を減らし、メモリ管理の効率が向上します。

void PyObject_Del( PyObject *op)

PyObject_New() や PyObject_NewVar() で 確保したメモリを解放します。通常、この関数はオブジェクトの型に指定されている tp_dealloc ハンドラから呼び出されます。 この関数を呼び出した後は、メモリ領域はもはや有効な Python オブジェクトを表現していないので、オブジェクトのフィールド に対してアクセスしてはなりません。

PyObject _Py_NoneStruct

Python からは None に見えるオブジェクトです。この値へのアクセスは、このオブジェクトへのポインタを評価する Py_None マクロを使わなければなりません。

参考

PyModule_Create()
拡張モジュールのアロケートと生成。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • オブジェクト実装サポート (object implementation support) »


共通のオブジェクト構造体 (common object structure)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • オブジェクト実装サポート (object implementation support) »

共通のオブジェクト構造体 (common object structure)

Python では、オブジェクト型を定義する上で数多くの構造体が使われます。この節では三つの構造体とその利用方法について説明します。

全ての Python オブジェクトは、オブジェクトのメモリ内表現の先頭部分にある少数のフィールドを完全に共有しています。 このフィールドは PyObject 型および PyVarObject 型で表現されます。 これらの型もまた、他の全ての Python オブジェクトの定義で直接または間接的に使われているマクロを使って定義されています。

PyObject

全てのオブジェクト型はこの型を拡張したものです。 この型には、あるオブジェクトを指すポインタをオブジェクトとして Python から扱うのに必要な情報が入っています。 通常の "リリース" ビルドでは、この構造体にはオブジェクトの参照カウントとオブジェクトに対応する型オブジェクトだけが入っています。 実際には PyObject であることは宣言されていませんが、全ての Python オブジェクトへのポインタは PyObject* へキャストできます。 メンバにアクセスするには Py_REFCNT マクロと Py_TYPE マクロを使わなければなりません。

PyVarObject

PyObject を拡張して、 ob_size フィールドを追加したものです。 この構造体は、 長さ (length) の概念を持つオブジェクトだけに対して使います。 この型が Python/C API で使われることはほとんどありません。 メンバにアクセスするには Py_REFCNT マクロ、 Py_TYPE マクロ、 Py_SIZE マクロを使わなければなりません。

PyObject_HEAD

可変な長さを持たないオブジェクトを表現する新しい型を宣言するときに使うマクロです。 PyObject_HEAD マクロは次のように展開されます:

PyObject ob_base;

上にある PyObject のドキュメントを参照してください。

PyObject_VAR_HEAD

インスタンスごとに異なる長さを持つオブジェクトを表現する新しい型を宣言するときに使うマクロです。 PyObject_VAR_HEAD マクロは次のように展開されます:

PyVarObject ob_base;

上にある PyVarObject のドキュメントを参照してください。

Py_TYPE(o)

Python オブジェクトの ob_type メンバにアクセスするのに使うマクロです。 これは次のように展開されます:

(((PyObject*)(o))->ob_type)
Py_REFCNT(o)

Python オブジェクトの ob_refcnt メンバにアクセスするのに使うマクロです。 これは次のように展開されます:

(((PyObject*)(o))->ob_refcnt)
Py_SIZE(o)

Python オブジェクトの ob_size メンバにアクセスするのに使うマクロです。 これは次のように展開されます:

(((PyVarObject*)(o))->ob_size)
PyObject_HEAD_INIT(type)

新しい PyObject 型のための初期値に展開するマクロです。このマクロは次のように展開されます。

_PyObject_EXTRA_INIT
1, type,
PyVarObject_HEAD_INIT(type, size)

新しい、 ob_size フィールドを含む PyVarObject 型のための初期値に展開するマクロです。このマクロは次のように展開されます。

_PyObject_EXTRA_INIT
1, type, size,
PyCFunction

ほとんどの Python の呼び出し可能オブジェクトを C で実装する際に用いられている関数の型です。この型の関数は 2 つの PyObject* 型のパラメータを取り、 PyObject* 型の値を返します。戻り値を NULL にする場合、例外をセットしておかなければなりません。 NULL でない値を返す場合、戻り値は Python に関数の戻り値として公開される値として解釈されます。この型の関数は新たな参照を返さなければなりません。

PyCFunctionWithKeywords

キーワード引数をとるPythonの呼び出し可能オブジェクトを C で実装する際に用いられている関数の型です: この型の関数は 3 つの PyObject* 型のパラメータをとり、 PyObject* 型の値を返します。戻り値の意味については、上記の PyCFunction を参照して下さい。

PyMethodDef

拡張型のメソッドを記述する際に用いる構造体です。この構造体には 4 つのフィールドがあります:

フィールド | C の型 | 意味
ml_name | const char * | メソッド名
ml_meth | PyCFunction | C 実装へのポインタ
ml_flags | int | 呼び出しをどのように行うかを示すフラグビット
ml_doc | const char * | docstring の内容を指すポインタ

ml_meth は C の関数ポインタです。関数は別の型で定義されていてもかまいませんが、常に PyObject* を返します。関数が PyFunction でない場合、メソッドテーブル内でキャストを行うようコンパイラが要求することになるでしょう。 PyCFunction では最初のパラメタが PyObject* 型であると定義していますが、固有の C 型を self オブジェクトに使う実装はよく行われています。

ml_flags フィールドはビットフィールドで、以下のフラグが入ります。 個々のフラグは呼び出し規約 (calling convention) や束縛規約 (binding convention) を表します。 呼び出し規約フラグでは、 METH_VARARGS および METH_KEYWORDS だけが組み合わせられます。 呼び出し規約フラグは束縛規約フラグと組み合わせられます。

METH_VARARGS

PyCFunction 型のメソッドで典型的に使われる呼び出し規約です。関数は PyObject* 型の引数値を二つ要求します。最初の引数はメソッドの self オブジェクトです; モジュール関数の場合、これはモジュールオブジェクトです。第二のパラメタ (よく args と呼ばれます) は、全ての引数を表現するタプルオブジェクトです。パラメタは通常、 PyArg_ParseTuple() や PyArg_UnpackTuple() で処理されます。

METH_KEYWORDS

このフラグを持つメソッドは PyCFunctionWithKeywords 型でなければなりません。 この関数は 3 つのパラメータを要求します: self 、 args 、およびキーワード引数全てからなる辞書です。 このフラグは METH_VARARGS と組み合わせて用いられなければならず、パラメタは通常 PyArg_ParseTupleAndKeywords() で処理されます。

METH_NOARGS

引数のないメソッドは、 METH_NOARGS フラグをつけた場合、必要な引数が指定されているかをチェックしなくなります。こうしたメソッドは PyCFunction 型でなくてはなりません。第一のパラメタは self になり、モジュールかオブジェクトインスタンスへの参照を保持することになります。いずれにせよ、第二のパラメタは NULL になります。

METH_O

単一のオブジェクト引数だけをとるメソッドは、 PyArg_ParseTuple() を引数 "O" にして呼び出す代わりに、 METH_O フラグつきで指定できます。メソッドは PyCFunction 型で、 self パラメタと単一の引数を表現する PyObject* パラメタを伴います。

以下の二つの定数は、呼び出し規約を示すものではなく、クラスのメソッドとして使う際の束縛方式を示すものです。モジュールに対して定義された関数で用いてはなりません。メソッドに対しては、最大で一つしかこのフラグをセットできません。

METH_CLASS

メソッドの最初の引数には、型のインスタンスではなく型オブジェクトが渡されます。このフラグは組み込み関数 classmethod() を使って生成するのと同じ クラスメソッド (class method) を生成するために使われます。

METH_STATIC

メソッドの最初の引数には、型のインスタンスではなく NULL が渡されます。このフラグは、 staticmethod() を使って生成するのと同じ 静的メソッド (static method) を生成するために使われます。

もう一つの定数は、あるメソッドを同名の別のメソッド定義と置き換えるかどうかを制御します。

METH_COEXIST

メソッドを既存の定義を置き換える形でロードします。 METH_COEXIST を指定しなければ、デフォルトの設定にしたがって、定義が重複しないようスキップします。スロットラッパはメソッドテーブルよりも前にロードされるので、例えば sq_contains スロットはラップしているメソッド __contains__() を生成し、同名の PyCFunction のロードを阻止します。このフラグを定義すると、 PyCFunction はラッパオブジェクトを置き換える形でロードされ、スロットと連立します。 PyCFunctions の呼び出しはラッパオブジェクトの呼び出しよりも最適化されているので、こうした仕様が便利になります。

PyMemberDef

type の C 構造体のメンバとして格納されている、ある型の属性を表す構造体です。この構造体のフィールドは以下のとおりです:

フィールド | C の型 | 意味
name | const char * | メンバ名
type | int | C 構造体の中のメンバの型
offset | Py_ssize_t | そのメンバの type object 構造体中の場所の offset バイト数
flags | int | フィールドが読み出し専用か書込み可能なのかを示すビットフラグ
doc | const char * | docstring の内容を指すポインタ

type はたくさんのCの型を意味する T_ マクロのうちの1つです。メンバが Python からアクセスされるとき、そのメンバは対応する Python の型に変換されます。

マクロ名 | C の型
T_SHORT | short
T_INT | int
T_LONG | long
T_FLOAT | 浮動小数点数
T_DOUBLE | double
T_STRING | const char *
T_OBJECT | PyObject *
T_OBJECT_EX | PyObject *
T_CHAR | char
T_BYTE | char
T_UBYTE | unsigned char
T_UINT | unsigned int
T_USHORT | unsigned short
T_ULONG | unsigned long
T_BOOL | char
T_LONGLONG | long long
T_ULONGLONG | unsigned long long
T_PYSSIZET | Py_ssize_t

T_OBJECT と T_OBJECT_EX が異なっているのは、 T_OBJECT はメンバが NULL だったときに None を返すのに対し、 T_OBJECT_EX は AttributeError を送出する点です。 T_OBJECT_EX は T_OBJECT より属性に対する del 文を正しくあつかうので、できれば T_OBJECT ではなく T_OBJECT_EX を使ってください。

flags can be 0 for write and read access or READONLY for read-only access. Using T_STRING for type implies READONLY. T_STRING data is interpreted as UTF-8. Only T_OBJECT and T_OBJECT_EX members can be deleted. (They are set to NULL).

PyGetSetDef

Structure to define property-like access for a type. See also description of the PyTypeObject.tp_getset slot.

フィールド | C の型 | 意味
名前 | const char * | attribute name
get | getter | C Function to get the attribute
集合 | setter | optional C function to set or delete the attribute, if omitted the attribute is readonly
doc | const char * | optional docstring
closure | void * | optional function pointer, providing additional data for getter and setter

The get function takes one PyObject* parameter (the instance) and a function pointer (the associated closure):

typedef PyObject *(*getter)(PyObject *, void *);

It should return a new reference on success or NULL with a set exception on failure.

set functions take two PyObject* parameters (the instance and the value to be set) and a function pointer (the associated closure):

typedef int (*setter)(PyObject *, PyObject *, void *);

In case the attribute should be deleted the second parameter is NULL. Should return 0 on success or -1 with a set exception on failure.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • オブジェクト実装サポート (object implementation support) »


型オブジェクト

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • オブジェクト実装サポート (object implementation support) »

型オブジェクト

新スタイルの型を定義する構造体: PyTypeObject 構造体は、おそらく Python オブジェクトシステムの中で最も重要な構造体の1つでしょう。型オブジェクトは PyObject_*() 系や PyType_*() 系の関数で扱えますが、ほとんどの Python アプリケーションにとって、さして面白みのある機能を提供しません。型オブジェクトはオブジェクトがどのように振舞うかを決める基盤ですから、インタプリタ自体や新たな型を定義する拡張モジュールでは非常に重要な存在です。

型オブジェクトは標準の型 (standard type) に比べるとかなり大きな構造体です。各型オブジェクトは多くの値を保持しており、そのほとんどは C 関数へのポインタで、それぞれの関数はその型の機能の小さい部分を実装しています。この節では、型オブジェクトの各フィールドについて詳細を説明します。各フィールドは、構造体内で出現する順番に説明されています。

Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, intargfunc, intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, cmpfunc, reprfunc, hashfunc

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;
    printfunc tp_print;
    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 */

    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* 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;
    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;

} PyTypeObject;

型オブジェクト構造体は PyVarObject 構造体を拡張したものです。 ob_size フィールドは、(通常 class 文が呼び出す type_new() で生成される) 動的な型に使います。 PyType_Type (メタタイプ) は tp_itemsize を初期化するので注意してください。すなわち、 インスタンス (つまり型オブジェクト) には ob_size フィールドが存在しなければ なりません 。

PyObject* PyObject._ob_next
PyObject* PyObject._ob_prev

これらのフィールドはマクロ Py_TRACE_REFS が定義されている場合のみ存在します。 PyObject_HEAD_INIT マクロを使うと、フィールドを NULL に初期化します。静的にメモリ確保されているオブジェクトでは、これらのフィールドは常に NULL のままです。動的にメモリ確保されるオブジェクトの場合、これら二つのフィールドは、ヒープ上の 全ての 存続中のオブジェクトからなる二重リンクリストでオブジェクトをリンクする際に使われます。このことは様々なデバッグ目的に利用できます; 現状では、環境変数 PYTHONDUMPREFS が設定されているときに、プログラムの実行終了時点で存続しているオブジェクトを出力するのが唯一の用例です。

サブタイプはこのフィールドを継承しません。

Py_ssize_t PyObject.ob_refcnt

型オブジェクトの参照カウントで、 PyObject_HEAD_INIT はこの値を 1 に初期化します。静的にメモリ確保された型オブジェクトでは、型のインスタンス (ob_type が該当する型を指しているオブジェクト) は参照をカウントする対象には なりません 。動的にメモリ確保される型オブジェクトの場合、インスタンスは参照カウントの対象に なります 。

サブタイプはこのフィールドを継承しません。

PyTypeObject* PyObject.ob_type

型自体の型、別の言い方をするとメタタイプです。 PyObject_HEAD_INIT マクロで初期化され、通常は &PyType_Type になります。しかし、(少なくとも) Windows で利用できる動的ロード可能な拡張モジュールでは、コンパイラは有効な初期化ではないと文句をつけます。そこで、ならわしとして、 PyObject_HEAD_INIT には NULL を渡して初期化しておき、他の操作を行う前にモジュールの初期化関数で明示的にこのフィールドを初期化することになっています。この操作は以下のように行います:

Foo_Type.ob_type = &PyType_Type;

上の操作は、該当する型のいかなるインスタンス生成よりも前にしておかなければなりません。 PyType_Ready() は ob_type が NULL かどうか調べ、 NULL の場合には基底クラスの ob_type フィールドで初期化します。 ob_type フィールドがゼロでない場合、 PyType_Ready() はこのフィールドを変更しません。

サブタイプはこのフィールドを継承します。

Py_ssize_t PyVarObject.ob_size

静的にメモリ確保されている型オブジェクトの場合、このフィールドはゼロに初期化されます。動的にメモリ確保されている型オブジェクトの場合、このフィールドは内部使用される特殊な意味を持ちます。

サブタイプはこのフィールドを継承しません。

const char* PyTypeObject.tp_name

型の名前が入っている NUL 終端された文字列へのポインタです。モジュールのグローバル変数としてアクセスできる型の場合、この文字列は完全なモジュール名、ドット、そして型の名前と続く文字列になります; 組み込み型の場合、ただの型の名前です。モジュールがあるパッケージのサブモジュールの場合、完全なパッケージ名が完全なモジュール名の一部になっています。例えば、パッケージ P 内のサブモジュール Q に入っているモジュール M 内で定義されている T は、 tp_name を "P.Q.M.T" に初期化します。

動的にメモリ確保される型オブジェクトの場合、このフィールドは単に型の名前になり、モジュール名は型の辞書内でキー '__module__' に対する値として明示的に保存されます。

静的にメモリ確保される型オブジェクトの場合、 tp_name フィールドにはドットが含まれているはずです。 最後のドットよりも前にある部分文字列全体は __module__ 属性として、またドットよりも後ろにある部分は __name__ 属性としてアクセスできます。

ドットが入っていない場合、 tp_name フィールドの内容全てが __name__ 属性になり、 __module__ 属性は (前述のように型の辞書内で明示的にセットしないかぎり) 未定義になります。 このため、その型は pickle 化できないことになります。 さらに、 pydoc が作成するモジュールドキュメントのリストにも載らなくなります。

サブタイプはこのフィールドを継承しません。

Py_ssize_t PyTypeObject.tp_basicsize
Py_ssize_t PyTypeObject.tp_itemsize

これらのフィールドは、型インスタンスのバイトサイズを計算できるようにします。

型には二つの種類があります: 固定長インスタンスの型は、 tp_itemsize フィールドがゼロで、可変長インスタンスの方は tp_itemsize フィールドが非ゼロの値になります。固定長インスタンスの型の場合、全てのインスタンスは等しく tp_basicsize で与えられたサイズになります。

可変長インスタンスの型の場合、インスタンスには ob_size フィールドがなくてはならず、インスタンスのサイズは N をオブジェクトの "長さ" として、 tp_basicsize と tp_itemsize の N 倍を足したものになります。 N の値は通常、インスタンスの ob_size フィールドに記憶されます。ただし例外がいくつかあります: 例えば、整数では負の値を ob_size に使って、インスタンスの表す値が負であることを示し、 N 自体は abs(ob_size) になります。また、 ob_size フィールドがあるからといって、必ずしもインスタンスが可変長であることを意味しません (例えば、 リスト型の構造体は固定長のインスタンスになるにもかかわらず、インスタンスにはちゃんと意味を持った ob_size フィールドがあります)。

基本サイズには、 PyObject_HEAD マクロまたは PyObject_VAR_HEAD マクロ (インスタンス構造体を宣言するのに使ったどちらかのマクロ) で宣言されているフィールドが入っています。さらに、 _ob_prev および _ob_next フィールドがある場合、これらのフィールドもサイズに加算されます。従って、 tp_basicsize の正しい初期化値を得るには、インスタンスデータのレイアウトを宣言するのに使う構造体に対して sizeof 演算子を使うしかありません。基本サイズには、GC ヘッダサイズは入っていません。

これらのフィールドはサブタイプに別々に継承されます。基底タイプが 0 でない tp_itemsize を持っていた場合、基底タイプの実装に依存しますが、一般的にはサブタイプで別の 0 で無い値を tp_itemsize に設定するのは安全ではありません。

アラインメントに関する注釈: 変数の各要素を配置する際に特定のアラインメントが必要となる場合、 tp_basicsize の値に気をつけなければなりません。例: ある型が double の配列を実装しているとします。 tp_itemsize は sizeof(double) です。 tp_basicsize が sizeof(double) (ここではこれを double のアラインメントが要求するサイズと仮定する) の個数分のサイズになるようにするのはプログラマの責任です。

destructor PyTypeObject.tp_dealloc

インスタンスのデストラクタ関数へのポインタです。この関数は (単量子 None や Ellipsis の場合のように) インスタンスが決してメモリ解放されない型でない限り必ず定義しなければなりません。

デストラクタ関数は、参照カウントが新たにゼロになった際に Py_DECREF() や Py_XDECREF() マクロから呼び出されます。呼び出された時点では、インスタンスはまだ存在しますが、インスタンスに対する参照は全くない状態です。デストラクタ関数はインスタンスが保持している全ての参照を解放し、インスタンスが確保している全てのメモリバッファを (バッファの確保時に使った関数に対応するメモリ解放関数を使って) 解放し、最後に (デストラクタ関数の最後の操作として) その型の tp_free 関数を呼び出します。ある型がサブタイプを作成できない (Py_TPFLAGS_BASETYPE フラグがセットされていない) 場合、 tp_free の代わりにオブジェクトのメモリ解放関数 (deallocator) を直接呼び出してもかまいません。オブジェクトのメモリ解放関数は、インスタンスのメモリ確保を行う際に使った関数に対応したものでなければなりません; インスタンスを PyObject_New() や PyObject_VarNew() でメモリ 確保した場合には、通常 PyObject_Del() を使い、 PyObject_GC_New() や PyObject_GC_NewVar() で確保した場合には PyObject_GC_Del() を使います。

サブタイプはこのフィールドを継承します。

printfunc PyTypeObject.tp_print

予約済みのスロットです。 以前は Python 2.x でオブジェクトのフォーマット出力をするのに使われていました。

getattrfunc PyTypeObject.tp_getattr

オプションのポインタで、get-attribute-string を行う関数を指します。

このフィールドは非推奨です。 このフィールドを定義するときは、 tp_getattro 関数と同じように動作し、属性名は Python 文字列 オブジェクトではなく C 文字列で指定するような関数を指すようにしなければなりません。 シグネチャは次の通りです:

PyObject * tp_getattr(PyObject *o, char *attr_name);

このフィールドは tp_getattro と共にサブタイプに継承されます: すなわち、サブタイプの tp_getattr および tp_getattro が共に NULL の場合、サブタイプは基底タイプから tp_getattr と tp_getattro を両方とも継承します。

setattrfunc PyTypeObject.tp_setattr

オプションのポインタで、属性の設定と削除を行う関数を指します。

このフィールドは非推奨です。 このフィールドを定義するときは、 tp_setattro 関数と同じように動作し、属性名は Python 文字列 オブジェクトではなく C 文字列で指定するような関数を指すようにしなければなりません。 シグネチャは次の通りです:

PyObject * tp_setattr(PyObject *o, char *attr_name, PyObject *v);

引数 v に NULL を設定すると属性を削除します。 このフィールドは tp_setattro と共にサブタイプに継承されます: すなわち、サブタイプの tp_setattr および tp_setattro が両方とも NULL のとき、サブタイプは基底タイプから tp_setattr と tp_setattro を両方とも継承します。

PyAsyncMethods* tp_as_async

追加の構造体を指すポインタです。 この構造体は、 C レベルで awaitable プロトコルと asynchronous iterator プロトコルを実装するオブジェクトだけに関係するフィールドを持ちます。 詳しいことは async オブジェクト構造体 を参照してください。

バージョン 3.5 で追加: 以前は tp_compare や tp_reserved として知られていました。

reprfunc PyTypeObject.tp_repr

オプションのポインタで、組み込み関数 repr() を実装している関数を指します。

シグネチャは PyObject_Repr() と同じです。この関数は文字列オブジェクトか Unicode オブジェクトを返さなければなりません。理想的には、この関数が返す文字列は、適切な環境で eval() に渡した場合、同じ値を持つオブジェクトになるような文字列でなければなりません。不可能な場合には、オブジェクトの型と値から導出した内容の入った '<' から始まって '>' で終わる文字列を返さなければなりません。

このフィールドが設定されていない場合、 <%s object at %p> の形式をとる文字列が返されます。 %s は型の名前に、 %p はオブジェクトのメモリアドレスに置き換えられます。

サブタイプはこのフィールドを継承します。

PyNumberMethods* tp_as_number

数値プロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては 数値オブジェクト構造体 で説明されています。

tp_as_number フィールドは継承されませんが、そこの含まれるフィールドが個別に継承されます。

PySequenceMethods* tp_as_sequence

シーケンスプロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては シーケンスオブジェクト構造体 で説明されています。

tp_as_sequence フィールドは継承されませんが、これに含まれるフィールドが個別に継承されます。

PyMappingMethods* tp_as_mapping

マッピングプロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては マップオブジェクト構造体 で説明されています。

tp_as_mapping フィールドは継承されませんが、これに含まれるフィールドが個別に継承されます。

hashfunc PyTypeObject.tp_hash

オプションのポインタで、組み込み関数 hash() を実装している関数を指します。

シグネチャは PyObject_Hash() と同じです。この関数は型 Py_hash_t の値を返さなければなりません。通常時には -1 を戻り値にしてはなりません; ハッシュ値の計算中にエラーが生じた場合、関数は例外をセットして -1 を返さなければなりません。

このフィールドは明示的に PyObject_HashNotImplemented() に設定することで、親 type からのハッシュメソッドの継承をブロックすることができます。これは Python レベルでの __hash__ = None と同等に解釈され、 isinstance(o, collections.Hashable) が正しく False を返すようになります。逆もまた可能であることに注意してください - Python レベルで __hash__ = None を設定することで tp_hash スロットは PyObject_HashNotImplemented() に設定されます。

このフィールドがセットされていないときに、オブジェクトのハッシュ値を取ろうとすると TypeError が送出されます。

このフィールドは tp_richcompare と共にサブタイプに継承されます: すなわち、サブタイプの tp_richcompare および tp_hash が両方とも NULL のとき、サブタイプは基底タイプから tp_richcompare と tp_hash を両方とも継承します。

ternaryfunc PyTypeObject.tp_call

オプションのポインタで、オブジェクトの呼び出しを実装している関数を指します。オブジェクトが呼び出し可能でない場合には NULL にしなければなりません。シグネチャは PyObject_Call() と同じです。

サブタイプはこのフィールドを継承します。

reprfunc PyTypeObject.tp_str

オプションのポインタで、組み込みの演算 str() を実装している関数を指します。(str が型の一つになったため、 str() は str のコンストラクタを呼び出すことに注意してください。このコンストラクタは実際の処理を行う上で PyObject_Str() を呼び出し、さらに PyObject_Str() がこのハンドラを呼び出すことになります。)

シグネチャは PyObject_Str() と同じです; この関数は文字列オブジェクトか Unicode オブジェクトを返さなければなりません。また、この関数はオブジェクトを "分かりやすく (friendly)" 表現した文字列を返さなければなりません。というのは、この文字列はとりわけ print() 関数で使われることになる表記だからです。

このフィールドが設定されていない場合、文字列表現を返すためには PyObject_Repr() が呼び出されます。

サブタイプはこのフィールドを継承します。

getattrofunc PyTypeObject.tp_getattro

オプションのポインタで、get-attribute を実装している関数を指します。

シグネチャは PyObject_GetAttr() と同じです。 通常の属性検索を実装している PyObject_GenericGetAttr() をこのフィールドに設定しておくとたいていの場合は便利です。

このフィールドは tp_getattr と共にサブタイプに継承されます: すなわち、サブタイプの tp_getattr および tp_getattro が共に NULL の場合、サブタイプは基底タイプから tp_getattr と tp_getattro を両方とも継承します。

setattrofunc PyTypeObject.tp_setattro

オプションのポインタで、属性の設定と削除を行う関数を指します。

シグネチャは PyObject_SetAttr() と同じですが、 v に NULL を指定して属性を削除できるようにしなければなりません。 通常の属性設定を実装している PyObject_GenericSetAttr() をこのフィールドに設定しておくとたいていの場合は便利です。

このフィールドは tp_setattr と共にサブタイプに継承されます: すなわち、サブタイプの tp_setattr および tp_setattro が共に NULL の場合、サブタイプは基底タイプから tp_setattr と tp_setattro を両方とも継承します。

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 になっているとみなさなければなりません。

このフィールドの継承は込み入っています。ほとんどのフラグは個別に継承されます。すなわち、基底タイプのフラグビットが設定されていたら、サブタイプのフラグビットもそれを引き継ぎます。拡張機能構造体が継承される場合は、拡張機能構造体に関係するフラグビットは厳密に継承されます。すなわち、基底タイプのフラグビットの値は、拡張機能構造体へのポインタと共に、サブタイプにコピーされます。 Py_TPFLAGS_HAVE_GC フラグビットは tp_traverse フィールドと tp_clear フィールドと共に継承されます。すなわち、サブタイプにおいて、 Py_TPFLAGS_HAVE_GC フラグビットがクリアされていて、 tp_traverse フィールドと tp_clear フィールドが存在し NULL になっている場合に継承されます。

以下に挙げるビットマスクは現在定義されているものです; フラグは | 演算子で論理和を取って tp_flags フィールドの値を作成できます。 PyType_HasFeature() マクロは型とフラグ値、 tp および f をとり、 tp->tp_flags & f が非ゼロかどうか調べます。

Py_TPFLAGS_HEAPTYPE

型オブジェクト自体がヒープにメモリ確保される場合にセットされるビットです。型オブジェクト自体がヒープにメモリ確保される場合、インスタンスの ob_type フィールドは型オブジェクトへの参照とみなされます。この場合、新たなインスタンスを生成する度に型オブジェクトを INCREF し、インスタンスを解放するたびに DECREF します (サブタイプのインスタンスには適用されません; インスタンスが ob_type で参照している型だけが INCREF および DECREF されます)。

Py_TPFLAGS_BASETYPE

型を別の型の基底タイプとして使える場合にセットされるビットです。このビットがクリアならば、この型のサブタイプは生成できません (Java における "final" クラスに似たクラスになります)。

Py_TPFLAGS_READY

型オブジェクトが PyType_Ready() で完全に初期化されるとセットされるビットです。

Py_TPFLAGS_READYING

PyType_Ready() による型オブジェクトの初期化処理中にセットされるビットです。

Py_TPFLAGS_HAVE_GC

オブジェクトがガベージコレクション (GC) をサポートする場合にセットされるビットです。このビットがセットされている場合、インスタンスは PyObject_GC_New() を使って生成し、 PyObject_GC_Del() を使って破棄しなければなりません。詳しい情報は 循環参照ガベージコレクションをサポートする にあります。このビットは、GC に関連するフィールド tp_traverse および tp_clear が型オブジェクト内に存在することも示しています。

Py_TPFLAGS_DEFAULT

型オブジェクトおよび拡張機能構造体の特定のフィールドの存在の有無に関連する全てのビットからなるビットマスクです。現状では、このビットマスクには以下のビット: Py_TPFLAGS_HAVE_STACKLESS_EXTENSION および Py_TPFLAGS_HAVE_VERSION_TAG が入っています。

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 スロットが存在しているときにセットされるビットです。

バージョン 3.4 で追加.

const char* PyTypeObject.tp_doc

オプションのポインタで、この型オブジェクトの docstring を与える NUL 終端された C の文字列を指します。この値は型オブジェクトと型のインスタンスにおける __doc__ 属性として公開されます。

サブタイプはこのフィールドを継承 しません 。

traverseproc PyTypeObject.tp_traverse

オプションのポインタで、ガベージコレクタのためのトラバーサル関数 (traversal function) を指します。 Py_TPFLAGS_HAVE_GC がセットされている場合にのみ使われます。Pythonのガベージコレクションの枠組みに関する詳細は 循環参照ガベージコレクションをサポートする にあります。

tp_traverse ポインタは、ガベージコレクタが循環参照を見つけるために使われます。 tp_traverse 関数の典型的な実装は、インスタンスの Pythonオブジェクトである各メンバに対して Py_VISIT() を呼び出します。例えば、次のコードは _thread 拡張モジュールの local_traverse() 関数です:

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() 関数は循環参照になり得ないメンバも返します。

Py_VISIT() は local_traverse() が visit と arg という決まった名前の引数を持つことを要求します。

このフィールドは tp_clear および Py_TPFLAGS_HAVE_GC フラグビットと共にサブタイプに継承されます: すなわち、サブタイプの tp_traverse および tp_clear が両方ともゼロの場合、サブタイプは基底タイプから tp_traverse と tp_clear を両方とも継承します。

inquiry PyTypeObject.tp_clear

オプションのポインタで、ガベージコレクタにおける消去関数 (clear function) を指します。 Py_TPFLAGS_HAVE_GC がセットされている場合にのみ使われます。

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;
}

参照のクリアはデリケートなので、 Py_CLEAR() マクロを使うべきです: ポインタを NULL にセットするまで、そのオブジェクトの参照カウントをデクリメントしてはいけません。参照カウントのデクリメントすると、そのオブジェクトが破棄されるかもしれず、 (そのオブジェクトに関連付けられたファイナライザ、弱参照のコールバックにより) 任意のPythonコードの実行を含む後片付け処理が実行されるかもしれないからです。もしそういったコードが再び self を参照することがあれば、すでに持っていたオブジェクトへのポインタは NULL になっているので、 self は所有していたオブジェクトをもう利用できないことを認識できます。 Py_CLEAR() マクロはその手続きを安全な順番で実行します。

tp_clear 関数の目的は参照カウントを破壊することなので、 Python 文字列や Python 整数のような、循環参照に含むことのできないオブジェクトをクリアする必要はありません。一方、所有する全ての Python オブジェクトをクリアするようにし、その型の tp_dealloc 関数が tp_clear 関数を実行するようにすると実装が楽になるでしょう。

Pythonのガベージコレクションの仕組みについての詳細は、 循環参照ガベージコレクションをサポートする にあります。

このフィールドは tp_traverse および Py_TPFLAGS_HAVE_GC フラグビットと共にサブタイプに継承されます: すなわち、サブタイプの tp_traverse および tp_clear が両方ともゼロの場合、サブタイプは基底タイプから tp_traverse と tp_clear を両方とも継承します。

richcmpfunc PyTypeObject.tp_richcompare

オプションのポインタで、 PyObject *tp_richcompare(PyObject *a, PyObject *b, int op) というシグネチャを持つ拡張比較関数を指します。 1つ目の引数は、 PyTypeObject で定義された型のインスタンスであることが保証されています。

この関数は、比較結果を返すべきです。(普通は Py_True か Py_False です。) 比較が未定義の場合は、Py_NotImplemented を、それ以外のエラーが発生した場合には例外状態をセットして NULL を返さなければなりません。

注釈

限られた種類の比較だけが可能 (例えば、 == と != が可能で < などが不可能) な型を実装したい場合、拡張比較関数で直接 TypeError を返します。

このフィールドは tp_hash と共にサブタイプに継承されます: すなわち、サブタイプの tp_richcompare および tp_hash が両方とも NULL のとき、サブタイプは基底タイプから tp_richcompare と tp_hash を両方とも継承します。

tp_richcompare および PyObject_RichCompare() 関数の第三引数に使うための定数としては以下が定義されています:

定数 比較
Py_LT <
Py_LE <=
Py_EQ ==
Py_NE !=
Py_GT >
Py_GE >=

The following macro is defined to ease writing rich comparison functions:

PyObject *Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op)

Return Py_True or Py_False from the function, depending on the result of a comparison. VAL_A and VAL_B must be orderable by C comparison operators (for example, they may be C ints or floats). The third argument specifies the requested operation, as for PyObject_RichCompare().

The return value's reference count is properly incremented.

On error, sets an exception and returns NULL from the function.

バージョン 3.7 で追加.

Py_ssize_t PyTypeObject.tp_weaklistoffset

型のインスタンスが弱参照可能な場合、このフィールドはゼロよりも大きな数になり、インスタンス構造体における弱参照リストの先頭を示すオフセットが入ります (GC ヘッダがある場合には無視します); このオフセット値は PyObject_ClearWeakRefs() および PyWeakref_*() 関数が利用します。インスタンス構造体には、 NULL に初期化された PyObject* 型のフィールドが入っていなければなりません。

このフィールドを tp_weaklist と混同しないようにしてください; これは型オブジェクト自身への弱参照からなるリストの先頭です。

このフィールドはサブタイプに継承されますが、以下の規則を読んでください。サブタイプはこのオフセット値をオーバライドすることがあります; 従って、サブタイプでは弱参照リストの先頭が基底タイプとは異なる場合があります。リストの先頭は常に tp_weaklistoffset で分かるはずなので、このことは問題にはならないはずです。

class 文で定義された型に __slots__ 宣言が全くなく、かつ基底タイプが弱参照可能でない場合、その型を弱参照可能にするには弱参照リストの先頭を表すスロットをインスタンスデータレイアウト構造体に追加し、スロットのオフセットを tp_weaklistoffset に設定します。

型の __slots__ の宣言に __weakref__ という名前のスロットが含まれているとき、スロットはその型のインスタンスにおける弱参照リストの先頭を表すスロットになり、スロットのオフセットが型の tp_weaklistoffset に入ります。

型の __slots__ 宣言が __weakref__ という名前のスロットを含んでいないとき、その型は基底タイプから tp_weaklistoffset を継承します。

getiterfunc PyTypeObject.tp_iter

オプションの変数で、そのオブジェクトのイテレータを返す関数へのポインタです。この値が存在することは、通常この型のインスタンスがイテレート可能であることを示しています (しかし、シーケンスはこの関数がなくてもイテレート可能です)。

この関数は PyObject_GetIter() と同じシグネチャを持っています。

サブタイプはこのフィールドを継承します。

iternextfunc PyTypeObject.tp_iternext

オプションのポインタで、イテレータにおいて次の要素を返す関数を指します。イテレータの要素がなくなると、この関数は 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) だけがサポートされています; 多重継承はメタタイプの呼び出しによる動的な型オブジェクトの生成を必要とします。

(当たり前ですが) サブタイプはこのフィールドを継承しません。しかし、このフィールドのデフォルト値は (Python プログラマは object 型として知っている) &PyBaseObject_Type になります。

PyObject* PyTypeObject.tp_dict

型の辞書は PyType_Ready() によってこのフィールドに収められます。

このフィールドは通常、 PyType_Ready() を呼び出す前に NULL に初期化しておかなければなりません; あるいは、型の初期属性の入った辞書で初期化しておいてもかまいません。 PyType_Ready() が型をひとたび初期化すると、型の新たな属性をこの辞書に追加できるのは、属性が (__add__() のような) オーバロード用演算でないときだけです。

サブタイプはこのフィールドを継承しません (が、この辞書内で定義されている属性は異なるメカニズムで継承されます)。

警告

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

型のインスタンスにインスタンス変数の入った辞書がある場合、このフィールドは非ゼロの値になり、型のインスタンスデータ構造体におけるインスタンス変数辞書へのオフセットが入ります; このオフセット値は PyObject_GenericGetAttr() が使います。

このフィールドを tp_dict と混同しないようにしてください; これは型オブジェクト自身の属性の辞書です。

このフィールドの値がゼロより大きければ、値はインスタンス構造体の先頭からの オフセットを表します。値がゼロより小さければ、インスタンス構造体の 末尾 からのオフセットを表します。負のオフセットを使うコストは比較的高くつくので、 インスタンス構造体に可変長部分があるときのみ使うべきです。例えば、 str や tuple のサブタイプにインスタンス変数の辞書を追加する場合には、負のオフセットを使います。この場合、たとえ辞書が基本のオブジェクトレイアウトに含まれていなくても、 tp_basicsize フィールドは追加された辞書を考慮にいれなければならないことに注意してください。ポインタサイズが 4 バイトのシステムでは、 構造体の最後尾に辞書が宣言されていることを示す場合、 tp_dictoffset を -4 にしなければなりません。

負の tp_dictoffset から、インスタンスでの実際のオフセットを計算するには以下のようにします:

dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
if dictoffset is not aligned on sizeof(void*):
    round up to sizeof(void*)

ここで、 tp_basicsize、 tp_itemsize および tp_dictoffset は型オブジェクトから取り出され、 ob_size はインスタンスから取り出されます。 絶対値を取っているのは、整数は符号を記憶するのに ob_size の符号を使うためです。 (この計算を自分で行う必要はまったくありません; 計算は _PyObject_GetDictPtr() がやってくれます。)

このフィールドはサブタイプに継承されますが、以下の規則を読んでください。サブタイプはこのオフセット値をオーバライドすることがあります; 従って、サブタイプでは辞書のオフセットが基底タイプとは異なる場合があります。辞書のオフセットは常に tp_dictoffset で分かるはずなので、このことは問題にはならないはずです。

class 文で定義された型に __slots__ 宣言がなく、かつ基底タイプの全てにインスタンス変数辞書がない場合、辞書のスロットをインスタンスデータレイアウト構造体に追加し、スロットのオフセットを tp_dictoffset に設定します。

class 文で定義された型に __slots__ 宣言がある場合、この型は基底タイプから tp_dictoffset を継承します。

(__dict__ という名前のスロットを __slots__ 宣言に追加しても、期待どおりの効果は得られず、単に混乱を招くだけになります。とはいえ、これは将来 __weakref__ のように追加されるはずです。)

initproc PyTypeObject.tp_init

オプションのポインタで、インスタンス初期化関数を指します。

この関数はクラスにおける __init__() メソッドに対応します。 __init__() と同様、 __init__() を呼び出さずにインスタンスを作成できます。また、 __init__() を再度呼び出してインスタンスの再初期化もできます。

関数のシグネチャは次のとおりです

int tp_init(PyObject *self, PyObject *args, PyObject *kwds)

self 引数は初期化するインスタンスです; args および kwds 引数は、 __init__() を呼び出す際の位置引数およびキーワード引数です。

tp_init 関数のフィールドが NULL でない場合、通常の型を呼び出す方法のインスタンス生成において、型の tp_new 関数がインスタンスを返した後に呼び出されます。 tp_new が元の型のサブタイプでない別の型を返す場合、 tp_init は全く呼び出されません; tp_new が元の型のサブタイプのインスタンスを返す場合、サブタイプの tp_init が呼び出されます。

サブタイプはこのフィールドを継承します。

allocfunc PyTypeObject.tp_alloc

オプションのポインタで、インスタンスのメモリ確保関数を指します。

関数のシグネチャは次のとおりです

PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)

この関数の目的は、メモリ確保をメモリ初期化から分離することにあります。この関数は、インスタンス用の的確なサイズ、適切なアラインメント、ゼロによる初期化がなされ、 ob_refcnt を 1 に、 ob_type を型引数 (type argument) にセットしたメモリブロックへのポインタを返さねばなりません。型の tp_itemsize がゼロでない場合、オブジェクトの ob_size フィールドは nitems に初期化され、確保されるメモリブロックの長さは tp_basicsize + nitems*tp_itemsize を sizeof(void*) の倍数に切り上げた値になるはずです; それ以外の場合、 nitems の値は使われず、メモリブロックの長さは tp_basicsize になるはずです。

この関数をインスタンス初期化の他のどの処理にも、追加でメモリ確保をする場合でさえ使ってはなりません; そうした処理は tp_new で行わねばなりません。

静的なサブタイプはこのフィールドを継承しますが、動的なサブタイプ (class 文で生成するサブタイプ) の場合は継承しません; 後者の場合、このフィールドは常に PyType_GenericAlloc() にセットされ、標準のヒープ上メモリ確保戦略が強制されます。静的に定義する型の場合でも、 PyType_GenericAlloc() を推奨します。

newfunc PyTypeObject.tp_new

オプションのポインタで、インスタンス生成関数を指します。

このフィールドが NULL を指している型では、型を呼び出して新たなインスタンスを生成できません; こうした型では、おそらくファクトリ関数のように、インスタンスを生成する他の方法があるはずです。

関数のシグネチャは次のとおりです

PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)

subtype 引数は生成するオブジェクトの型です; args および kwds 引数は、型を呼び出すときの位置引数およびキーワード引数です。サブタイプは tp_new 関数を呼び出すときに使う型と同じである必要はないことに注意してください; その型の (無関係ではない) サブタイプのこともあります。

tp_new 関数は subtype->tp_alloc(subtype, nitems) を呼び出してオブジェクトのメモリ領域を確保し、初期化で絶対に必要とされる処理だけを行います。省略したり繰り返したりしても問題のない初期化処理は tp_init ハンドラ内に配置しなければなりません。だいたいの目安としては、変更不能な型では初期化は全て tp_new で行い、一方、変更可能な型ではほとんどの初期化を tp_init に回すべきです。

サブタイプはこのフィールドを継承します。例外として、 tp_base が NULL か &PyBaseObject_Type になっている静的な型では継承しません。

destructor PyTypeObject.tp_free

インスタンスのメモリ解放関数を指す、オプションのポインタです。シグネチャは freefunc です:

void tp_free(void *)

このシグネチャと互換性のある初期化子は PyObject_Free() です。

静的なサブタイプはこのフィールドを継承しますが、動的なサブタイプ (class 文で生成するサブタイプ) の場合は継承しません; 後者の場合、このフィールドには PyType_GenericAlloc() と Py_TPFLAGS_HAVE_GC フラグビットの値に対応させるのにふさわしいメモリ解放関数がセットされます。

inquiry PyTypeObject.tp_is_gc

オプションのポインタで、ガベージコレクタから呼び出される関数を指します。

ガベージコレクタは、オブジェクトを回収して良いかどうかを知る必要があります。通常は、オブジェクトの型の tp_flags フィールドを見て、 Py_TPFLAGS_HAVE_GC フラグビットを調べるだけで十分です。しかし、ある型では静的にメモリ確保されたインスタンスと動的にメモリ確保されたインスタンスが混じっていて、静的にメモリ確保されたインスタンスは回収できません。こうした型では、関数を定義しなければなりません; 関数はインスタンスが回収可能の場合には 1 を、回収不能の場合には 0 を返さねばなりません。シグネチャは

int tp_is_gc(PyObject *self)

(上記のような型の例は、型オブジェクト自体です。メタタイプ PyType_Type は、型のメモリ確保が静的か動的かを区別するためにこの関数を定義しています。)

サブタイプはこのフィールドを継承します。

PyObject* PyTypeObject.tp_bases

基底型からなるタプルです。

class 文で生成されたクラスの場合このフィールドがセットされます。静的に定義されている型の場合には、このフィールドは NULL になります。

このフィールドは継承されません。

PyObject* PyTypeObject.tp_mro

基底タイプ群を展開した集合が入っているタプルです。集合は該当する型自体からはじまり、 object で終わります。メソッド解決順序 (Method Resolution Order) に従って並んでいます。

このフィールドは継承されません; フィールドの値は PyType_Ready() で毎回計算されます。

destructor PyTypeObject.tp_finalize

オプションのポインタで、インスタンスの終了処理関数を指します。 シグネチャは destructor です:

void tp_finalize(PyObject *)

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);
}

このフィールドを (継承した場合も含めて) 考慮から漏らさないように、 Py_TPFLAGS_HAVE_FINALIZE フラグビットも設定しなければなりません。

サブタイプはこのフィールドを継承します。

バージョン 3.4 で追加.

参考

"オブジェクトの安全な終了処理" ( PEP 442)

PyObject* PyTypeObject.tp_cache

使用されていません。継承されません。内部で使用するためだけのものです。

PyObject* PyTypeObject.tp_subclasses

サブクラスへの弱参照からなるリストです。継承されません。内部で使用するためだけのものです。

PyObject* PyTypeObject.tp_weaklist

この型オブジェクトに対する弱参照からなるリストの先頭です。

残りのフィールドは、機能テスト用のマクロである COUNT_ALLOCS が定義されている場合のみ利用でき、内部で使用するためだけのものです。これらのフィールドについて記述するのは単に完全性のためです。サブタイプはこれらのフィールドを継承しません。

Py_ssize_t PyTypeObject.tp_allocs

メモリ確保の回数です。

Py_ssize_t PyTypeObject.tp_frees

メモリ解放の回数です。

Py_ssize_t PyTypeObject.tp_maxalloc

同時にメモリ確保できる最大オブジェクト数です。

PyTypeObject* PyTypeObject.tp_next

次のゼロでない tp_allocs フィールドを持つ型オブジェクトへのポインタです。

また、 Python のガベージコレクションでは、 tp_dealloc を呼び出すのはオブジェクトを生成したスレッドだけではなく、任意の Python スレッドかもしれないという点にも注意して下さい。 (オブジェクトが循環参照の一部の場合、任意のスレッドのガベージコレクションによって解放されてしまうかもしれません)。Python API 側からみれば、 tp_dealloc を呼び出すスレッドはグローバルインタプリタロック (GIL: Global Interpreter Lock) を獲得するので、これは問題ではありません。しかしながら、削除されようとしているオブジェクトが何らかの C や C++ ライブラリ由来のオブジェクトを削除する場合、 tp_dealloc を呼び出すスレッドのオブジェクトを削除することで、ライブラリの仮定している何らかの規約に違反しないように気を付ける必要があります。

数値オブジェクト構造体

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 を返して例外を設定しなければなりません。

注釈

nb_reserved フィールドは常に NULL でなければなりません。以前は nb_long と呼ばれていて、 Python 3.0.1 で名前が変更されました。

マップオブジェクト構造体

PyMappingMethods

この構造体はマップ型プロトコルを実装するために使われる関数群へのポインタを保持しています。 以下の3つのメンバを持っています:

lenfunc PyMappingMethods.mp_length

This function is used by PyMapping_Size() and PyObject_Size(), and has the same signature. This slot may be set to NULL if the object has no defined length.

binaryfunc PyMappingMethods.mp_subscript

This function is used by PyObject_GetItem() and PySequence_GetSlice(), and has the same signature as PyObject_GetItem(). This slot must be filled for the PyMapping_Check() function to return 1, it can be NULL otherwise.

objobjargproc PyMappingMethods.mp_ass_subscript

This function is used by PyObject_SetItem(), PyObject_DelItem(), PyObject_SetSlice() and PyObject_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.

シーケンスオブジェクト構造体

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

This function is used by PySequence_Concat() and has the same signature. It is also used by the + operator, after trying the numeric addition via the nb_add slot.

ssizeargfunc PySequenceMethods.sq_repeat

This function is used by PySequence_Repeat() and has the same signature. It is also used by the * operator, after trying numeric multiplication via the nb_multiply slot.

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.

負のインデックスは次のように処理されます: sq_length スロットが埋められていれば、それを呼び出してシーケンスの長さから正のインデックスを計算し、 sq_item に渡します。 sq_length が NULL の場合は、インデックスはそのままこの関数に渡されます。

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

This function may be used by PySequence_Contains() and has the same signature. This slot may be left to NULL, in this case PySequence_Contains() simply traverses the sequence until it finds a match.

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 inplace 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 inplace multiplication via the nb_inplace_multiply slot.

バッファオブジェクト構造体 (buffer object structure)

PyBufferProcs

この構造体は buffer プロトコル が要求する関数群へのポインタを保持しています。 そのプロトコルは、エクスポーターオブジェクトが如何にして、その内部データをコンシューマオブジェクトに渡すかを定義します。

getbufferproc PyBufferProcs.bf_getbuffer

この関数のシグネチャは以下の通りです:

int (PyObject *exporter, Py_buffer *view, int flags);

flags で指定された方法で view を埋めてほしいという exporter に対する要求を処理します。ステップ(3) を除いて、この関数の実装では以下のステップを行わなければなりません:

  1. リクエストが合致するか確認します。 合致しない場合は、 PyExc_BufferError を送出し、 view->obj に NULL を設定し -1 を返します。
  2. 要求されたフィールドを埋めます。
  3. エクスポートした回数を保持する内部カウンタをインクリメントします。
  4. view->obj に exporter を設定し、 view->obj をインクリメントします。
  5. 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) を行います:

  1. エクスポートした回数を保持する内部カウンタをデクリメントします。
  2. カウンタが 0 の場合は、view に関連付けられた全てのメモリを解放します。

エクスポータは、バッファ固有のリソースを監視し続けるために internal フィールドを使わなければなりません。このフィールドは、コンシューマが view 引数としてオリジナルのバッファのコピーを渡しているであろう間、変わらないことが保証されています。

この関数は、view->obj をデクリメントしてはいけません、なぜならそれは PyBuffer_Release() で自動的に行われるからです(この方式は参照の循環を防ぐのに有用です)。

PyBuffer_Release() は、この関数をラップするコンシューマ向けのインタフェースです。

async オブジェクト構造体

バージョン 3.5 で追加.

PyAsyncMethods

この構造体は awaitable オブジェクトと asynchronous iterator オブジェクトを実装するのに必要な関数へのポインタを保持しています。

以下は構造体の定義です:

typedef struct {
    unaryfunc am_await;
    unaryfunc am_aiter;
    unaryfunc am_anext;
} PyAsyncMethods;
unaryfunc PyAsyncMethods.am_await

この関数のシグネチャは以下の通りです:

PyObject *am_await(PyObject *self)

返されるオブジェクトはイテレータでなければなりません。 つまりこのオブジェクトに対して PyIter_Check() が 1 を返さなければなりません。

オブジェクトが awaitable でない場合、このスロットを NULL に設定します。

unaryfunc PyAsyncMethods.am_aiter

この関数のシグネチャは以下の通りです:

PyObject *am_aiter(PyObject *self)

awaitable オブジェクトを返さなければなりません。 詳しいことは __anext__() を参照してください。

オブジェクトが非同期反復処理のプロトコルを実装していない場合、このスロットを NULL に設定します。

unaryfunc PyAsyncMethods.am_anext

この関数のシグネチャは以下の通りです:

PyObject *am_anext(PyObject *self)

awaitable オブジェクトを返さなければなりません。 詳しいことは __anext__() を参照してください。 このスロットは NULL に設定されていることもあります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • オブジェクト実装サポート (object implementation support) »


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

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • オブジェクト実装サポート (object implementation support) »

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

Python が循環参照を含むガベージの検出とコレクションをサポートするには、他のオブジェクトに対する "コンテナ" (他のオブジェクトには他のコンテナも含みます) となるオブジェクト型によるサポートが必要です。他のオブジェクトに対する参照を記憶しないオブジェクトや、(数値や文字列のような) アトム型 (atomic type) への参照だけを記憶するような型では、ガベージコレクションに際して特別これといったサポートを提供する必要はありません。

コンテナ型を作るには、型オブジェクトの tp_flags フィールドに Py_TPFLAGS_HAVE_GC フラグが立っており、 tp_traverse ハンドラの実装を提供しなければなりません。実装する型のインスタンスが変更可能な場合は、 tp_clear の実装も提供しなければなりません。

Py_TPFLAGS_HAVE_GC

このフラグをセットした型のオブジェクトは、この節に述べた規則に適合しなければなりません。簡単のため、このフラグをセットした型のオブジェクトをコンテナオブジェクトと呼びます。

コンテナ型のコンストラクタは以下の二つの規則に適合しなければなりません:

  1. オブジェクトのメモリは PyObject_GC_New() または PyObject_GC_NewVar() で確保しなければなりません。
  2. 他のコンテナへの参照が入るかもしれないフィールドが全て初期化されたら、すぐに PyObject_GC_Track() を呼び出さなければなりません。
TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)

PyObject_New() に似ていますが、 Py_TPFLAGS_HAVE_GC のセットされたコンテナオブジェクト用です。

TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)

PyObject_NewVar() に似ていますが、 Py_TPFLAGS_HAVE_GC のセットされたコンテナオブジェクト用です。

TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)

PyObject_NewVar() が確保したオブジェクトのメモリをリサイズします。 リサイズされたオブジェクトを返します。失敗すると NULL を返します。 op はコレクタに追跡されていてはなりません。

void PyObject_GC_Track( PyObject *op)

オブジェクト op を、コレクタによって追跡されるオブジェクトの集合に追加します。コレクタは何回動くのかは予想できないので、追跡されている間はオブジェクトは正しい状態でいなければなりません。 tp_traverse の対象となる全てのフィールドが正しい状態になってすぐに、たいていはコンストラクタの末尾付近で、呼び出すべきです。

void _PyObject_GC_TRACK( PyObject *op)

PyObject_GC_Track() のマクロ版です。拡張モジュールに使ってはなりません。

バージョン 3.6 で非推奨: This macro is removed from Python 3.8.

同様に、オブジェクトのメモリ解放関数も以下の二つの規則に適合しなければなりません:

  1. 他のコンテナを参照しているフィールドを無効化する前に、 PyObject_GC_UnTrack() を呼び出さなければなりません。
  2. オブジェクトのメモリは PyObject_GC_Del() で解放しなければなりません。
void PyObject_GC_Del(void *op)

PyObject_GC_New() や PyObject_GC_NewVar() を使って確保されたメモリを解放します。

void PyObject_GC_UnTrack(void *op)

オブジェクト op を、コレクタによって追跡されるオブジェクトの集合から除去します。このオブジェクトに対して PyObject_GC_Track() を再度呼び出して、追跡されるオブジェクトの集合に戻すことも可能です。 tp_traverse ハンドラの対象となるフィールドが正しくない状態になる前に、デアロケータ (tp_dealloc ハンドラ) はオブジェクトに対して、この関数を呼び出すべきです。

void _PyObject_GC_UNTRACK( PyObject *op)

PyObject_GC_UnTrack() のマクロ版です。拡張モジュールに使ってはなりません。

バージョン 3.6 で非推奨: This macro is removed from Python 3.8.

tp_traverse ハンドラはこの型の関数パラメータを受け取ります:

int (*visitproc)( PyObject *object, void *arg)

tp_traverse ハンドラに渡されるビジター関数 (visitor function) の型です。この関数は、探索するオブジェクトを object として、 tp_traverse ハンドラの第 3 引数を arg として呼び出します。 Python のコアはいくつかのビジター関数を使って、ゴミとなった循環参照を検出する仕組みを実装します; ユーザが自身のためにビジター関数を書く必要が出てくることはないでしょう。

tp_traverse ハンドラは次の型を持っていなければなりません:

int (*traverseproc)( PyObject *self, visitproc visit, void *arg)

コンテナオブジェクトのためのトラバーサル関数 (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 でなければなりません。

int (*inquiry)( PyObject *self)

循環参照を形成しているとおぼしき参照群を放棄します。変更不可能なオブジェクトは循環参照を直接形成することが決してないので、この関数を定義する必要はありません。このメソッドを呼び出した後でもオブジェクトは有効なままでなければならないので注意してください (参照に対して Py_DECREF() を呼ぶだけにしないでください)。ガベージコレクタは、オブジェクトが循環参照を形成していることを検出した際にこのメソッドを呼び出します。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »
  • オブジェクト実装サポート (object implementation support) »


API と ABI のバージョニング

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python/C API リファレンスマニュアル »

API と ABI のバージョニング

PY_VERSION_HEX は、Python のバージョン番号を単一の整数に符号化したものです。

例えば、PY_VERSION_HEX に 0x030401a2 が設定されていれば、その値を下記のように32ビットの値として扱うことで、バージョン情報を得ることができます:

bytes | ビット (ビッグエンディアンオーダ) | 意味
1 | 1-8 | PY_MAJOR_VERSION (3.4.1a2 中の 3)
2 | 9-16 | PY_MINOR_VERSION (3.4.1a2 中の 4)
3 | 17-24 | PY_MICRO_VERSION (3.4.1a2 中の 1)
4 | 25-28 | PY_RELEASE_LEVEL (アルファ版では 0xA、ベータ版では 0xB、リリース候補版では 0xC、そして最終版は 0xF)、この例ではアルファ版を意味しています。
29-32 | PY_RELEASE_SERIAL (3.4.1a2 中の 2、最終リリースでは 0)

従って、3.4.1a2 は hexversionで 0x030401a2 です。

これらのマクロは Include/patchlevel.h で定義されています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python/C API リファレンスマニュアル »


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

Python HOWTO

Python HOWTO は、それぞれが単独の話題を取り扱って自己完結した文書群です。Linux Documentation Project の HOWTO 書庫をモデルに、Python ライブラリリファレンスよりも詳細な文書を作っていこうという努力の成果なのです。

今のところ揃っている HOWTO はこちらです:

  • Python 2 から Python 3 への移植
  • Python 3 への拡張モジュール移植
  • Python で Curses プログラミング
  • デスクリプタ HowTo ガイド
  • 関数型プログラミング HOWTO
  • Logging HOWTO
  • Logging クックブック
  • 正規表現 HOWTO
  • ソケットプログラミング HOWTO
  • ソート HOW TO
  • Unicode HOWTO
  • urllib パッケージを使ってインターネット上のリソースを取得するには
  • Argparse チュートリアル
  • ipaddressモジュールの紹介
  • Argument Clinic How-To
  • DTrace と SystemTap で CPython を測定する

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


Python 3 への拡張モジュール移植

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

Python 3 への拡張モジュール移植

author: Benjamin Peterson

概要

C-API の変更は Python 3 の目標には入っていませんでしたが、Python レベルでの変更がたくさんあったので、Python 2 の API を無傷で済ませることはできませんでした。実際、 int() と long() の統合などは C レベルのほうが目立ちます。この文書では、なくなった互換性と、その対処方法について記述しようと思います。

条件コンパイル

一部のコードを Python 3 にだけコンパイルするための一番簡単な方法は、 PY_MAJOR_VERSION が 3 以上かどうかチェックすることです。

#if PY_MAJOR_VERSION >= 3
#define IS_PY3K
#endif

存在しなくなった関数については、条件ブロックの中で同等品にエイリアスすれば良いでしょう。

オブジェクト API の変更

Python 3 では、似た機能を持つタイプのいくつかを、統合したり、きっちり分けたりしました。

str/unicode の統合

Python 3 の str() タイプは Python 2 の unicode() と同じもので、どちらも C 関数は PyUnicode_* と呼ばれます。昔の 8 ビット文字列タイプは bytes() になり、C 関数は PyBytes_* と呼ばれます。Python 2.6 以降には互換性ヘッダ bytesobject.h が用意されており、 PyBytes 系の名前を PyString 系にマップしています。Python 3 との互換性を最大限確保するには、 PyUnicode は文字データに、 PyBytes はバイナリデータにだけ使うべきです。ほかにも、Python 3 の PyBytes と PyUnicode は Python 2 の PyString と PyUnicode とは違って交換不可能だということも重要です。以下の例では PyUnicode, PyString, PyBytes に関するベストプラクティスを見ることができます。

#include "stdlib.h"
#include "Python.h"
#include "bytesobject.h"

/* text example */
static PyObject *
say_hello(PyObject *self, PyObject *args) {
    PyObject *name, *result;

    if (!PyArg_ParseTuple(args, "U:say_hello", &name))
        return NULL;

    result = PyUnicode_FromFormat("Hello, %S!", name);
    return result;
}

/* just a forward */
static char * do_encode(PyObject *);

/* bytes example */
static PyObject *
encode_object(PyObject *self, PyObject *args) {
    char *encoded;
    PyObject *result, *myobj;

    if (!PyArg_ParseTuple(args, "O:encode_object", &myobj))
        return NULL;

    encoded = do_encode(myobj);
    if (encoded == NULL)
        return NULL;
    result = PyBytes_FromString(encoded);
    free(encoded);
    return result;
}

long/int の統合

Python 3 には整数型が int() の一つしかありません。 これは実際には Python 2 の long() タイプと同じもので、 Python 2 で使われていた int() は取り除かれました。 C-API では PyInt_* 関数群が、同等の PyLong_* に置き換えられています。

モジュールの初期化と状態情報

Python 3 には、改良された拡張モジュール初期化システムがあります ( PEP 3121 参照)。モジュールの状態はグローバル変数に持つのではなく、インタプリタ固有の構造体に持つべきだということになったのです。Pythonk 2 と Python 3 のどちらでも動くモジュールを作るのにはコツが要ります。次の簡単な例で、その方法を実演してみます。

#include "Python.h"

struct module_state {
    PyObject *error;
};

#if PY_MAJOR_VERSION >= 3
#define GETSTATE(m) ((struct module_state*)PyModule_GetState(m))
#else
#define GETSTATE(m) (&_state)
static struct module_state _state;
#endif

static PyObject *
error_out(PyObject *m) {
    struct module_state *st = GETSTATE(m);
    PyErr_SetString(st->error, "something bad happened");
    return NULL;
}

static PyMethodDef myextension_methods[] = {
    {"error_out", (PyCFunction)error_out, METH_NOARGS, NULL},
    {NULL, NULL}
};

#if PY_MAJOR_VERSION >= 3

static int myextension_traverse(PyObject *m, visitproc visit, void *arg) {
    Py_VISIT(GETSTATE(m)->error);
    return 0;
}

static int myextension_clear(PyObject *m) {
    Py_CLEAR(GETSTATE(m)->error);
    return 0;
}

static struct PyModuleDef moduledef = {
        PyModuleDef_HEAD_INIT,
        "myextension",
        NULL,
        sizeof(struct module_state),
        myextension_methods,
        NULL,
        myextension_traverse,
        myextension_clear,
        NULL
};

#define INITERROR return NULL

PyMODINIT_FUNC
PyInit_myextension(void)

#else
#define INITERROR return

void
initmyextension(void)
#endif
{
#if PY_MAJOR_VERSION >= 3
    PyObject *module = PyModule_Create(&moduledef);
#else
    PyObject *module = Py_InitModule("myextension", myextension_methods);
#endif

    if (module == NULL)
        INITERROR;
    struct module_state *st = GETSTATE(module);

    st->error = PyErr_NewException("myextension.Error", NULL, NULL);
    if (st->error == NULL) {
        Py_DECREF(module);
        INITERROR;
    }

#if PY_MAJOR_VERSION >= 3
    return module;
#endif
}

CObject の Capsule への変更

Python 3.1 と 2.7 に Capsule オブジェクトが導入されました。これは CObject のかわりになるものです。 CObject は便利でしたが、 CObject API には問題がありました: 有効な CObject であればそれ以上の識別が不可能なので、合わない CObject を混ぜて使うとインタープリタをクラッシュさせかねなかったこと、そして API の一部が C の未定義な挙動に依存していたことです。 (Capsule の背景について詳しくは bpo-5630 をご覧ください。)

現時点で CObject を使っているのであれば、3.1 以降へ移行するには Capsule へ切り換える必要があります。 CObject は 3.1 および 2.7 で非推奨となり、Python 3.2 では完全に削除されたからです。 2.7 と 3.1 以上だけの対応でいいなら、単に Capsule へ切り換えるだけです。 しかし Python 3.0 や、あるいは 2.7 未満のバージョンに対応しなければならない場合は、CObject と Capsule の両方に対応する必要が出てきます。(ただし Python 3.0 はサポートが終了しているため現場利用には推奨されません。)

そうした問題は、下に例示する capsulethunk.h ヘッダファイルで解決できるかもしれません。 必要な作業は、 Capsule API でコードを書き、このヘッダファイルを Python.h の後でインクルードするだけです。 すると自動的に、Capsule のあるバージョンの Python では Capsule を使い、なければ CObject を使うようになります。

その場合 capsulethunk.h は CObject を使って Capsule をシミュレートします。 しかし CObject には capsule の "name" を保持する余地がありません。 よって、 capsulethunk.h でシミュレートされた Capsule オブジェクトの動作は、本物の Capsule とは少し異なります。 具体的には:

  • PyCapsule_New() に渡された name 引数は無視されます。
  • PyCapsule_IsValid() および PyCapsule_GetPointer() に渡された name 引数は無視され、name のエラーチェックも実行されません。
  • PyCapsule_GetName() は常に NULL を返します。
  • PyCapsule_SetName() は常に例外を送出して、失敗を返します。 (CObject に名前を格納する方法がないので、ここでは PyCapsule_SetName() のうるさい失敗は暗黙の失敗より好ましいと考えられました。これが不便な場合は、適切と思うやり方で自由にローカルコピーを修正してください。)

capsulethunk.h は Python のソースの中に Doc/includes/capsulethunk.h という名前で入っています。 読者の便宜のため、ここにも引用しておきましょう:

#ifndef __CAPSULETHUNK_H
#define __CAPSULETHUNK_H

#if (    (PY_VERSION_HEX <  0x02070000) \
     || ((PY_VERSION_HEX >= 0x03000000) \
      && (PY_VERSION_HEX <  0x03010000)) )

#define __PyCapsule_GetField(capsule, field, default_value) \
    ( PyCapsule_CheckExact(capsule) \
        ? (((PyCObject *)capsule)->field) \
        : (default_value) \
    ) \

#define __PyCapsule_SetField(capsule, field, value) \
    ( PyCapsule_CheckExact(capsule) \
        ? (((PyCObject *)capsule)->field = value), 1 \
        : 0 \
    ) \

#define PyCapsule_Type PyCObject_Type

#define PyCapsule_CheckExact(capsule) (PyCObject_Check(capsule))
#define PyCapsule_IsValid(capsule, name) (PyCObject_Check(capsule))

#define PyCapsule_New(pointer, name, destructor) \
    (PyCObject_FromVoidPtr(pointer, destructor))

#define PyCapsule_GetPointer(capsule, name) \
    (PyCObject_AsVoidPtr(capsule))

/* Don't call PyCObject_SetPointer here, it fails if there's a destructor */
#define PyCapsule_SetPointer(capsule, pointer) \
    __PyCapsule_SetField(capsule, cobject, pointer)

#define PyCapsule_GetDestructor(capsule) \
    __PyCapsule_GetField(capsule, destructor)

#define PyCapsule_SetDestructor(capsule, dtor) \
    __PyCapsule_SetField(capsule, destructor, dtor)

/*
 * Sorry, there's simply no place
 * to store a Capsule "name" in a CObject.
 */
#define PyCapsule_GetName(capsule) NULL

static int
PyCapsule_SetName(PyObject *capsule, const char *unused)
{
    unused = unused;
    PyErr_SetString(PyExc_NotImplementedError,
        "can't use PyCapsule_SetName with CObjects");
    return 1;
}

#define PyCapsule_GetContext(capsule) \
    __PyCapsule_GetField(capsule, descr)

#define PyCapsule_SetContext(capsule, context) \
    __PyCapsule_SetField(capsule, descr, context)

static void *
PyCapsule_Import(const char *name, int no_block)
{
    PyObject *object = NULL;
    void *return_value = NULL;
    char *trace;
    size_t name_length = (strlen(name) + 1) * sizeof(char);
    char *name_dup = (char *)PyMem_MALLOC(name_length);

    if (!name_dup) {
        return NULL;
    }

    memcpy(name_dup, name, name_length);

    trace = name_dup;
    while (trace) {
        char *dot = strchr(trace, '.');
        if (dot) {
            *dot++ = '\0';
        }

        if (object == NULL) {
            if (no_block) {
                object = PyImport_ImportModuleNoBlock(trace);
            } else {
                object = PyImport_ImportModule(trace);
                if (!object) {
                    PyErr_Format(PyExc_ImportError,
                        "PyCapsule_Import could not "
                        "import module \"%s\"", trace);
                }
            }
        } else {
            PyObject *object2 = PyObject_GetAttrString(object, trace);
            Py_DECREF(object);
            object = object2;
        }
        if (!object) {
            goto EXIT;
        }

        trace = dot;
    }

    if (PyCObject_Check(object)) {
        PyCObject *cobject = (PyCObject *)object;
        return_value = cobject->cobject;
    } else {
        PyErr_Format(PyExc_AttributeError,
            "PyCapsule_Import \"%s\" is not valid",
            name);
    }

EXIT:
    Py_XDECREF(object);
    if (name_dup) {
        PyMem_FREE(name_dup);
    }
    return return_value;
}

#endif /* #if PY_VERSION_HEX < 0x02070000 */

#endif /* __CAPSULETHUNK_H */

その他のオプション

新規に拡張モジュールを書こうと思っているのであれば、Cython を検討してみても良いでしょう。これは Python 風の言語を C に翻訳してくれるもので、出力される拡張モジュールは Python 3 と Python 2 に両方対応しています。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python HOWTO »


Python で Curses プログラミング

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

Python で Curses プログラミング

著者: | A.M. Kuchling, Eric S. Raymond
リリース: | 2.04

概要

このドキュメントでは curses 拡張モジュールでテキストモードディスプレイを制御する方法について記述します。

curses ってなに?

curses ライブラリは、VT100s や Linux コンソール、さまざまなプログラムが提供するエミュレーション端末といったテキストベースの端末（ターミナル）のために、端末に依存しないスクリーン描画や、キーボードの処理を提供します。端末はカーソルの移動や、画面のスクロール、領域の消去といった共通の操作を行うための様々な制御コードをサポートします。端末の種類によって大きく異なる制御コードを使うことがあり、しばしば独特の癖があります。

グラフィカルなディスプレイが当たり前の今となっては、「なんでわざわざ？」と疑問に思うかもしれません。確かに文字表示端末は時代遅れな技術ではありますが、ニッチな領域が存在していて、意匠を凝らすことができるため、いまだに価値のあるものとなっています。そのような領域の一つは、例えば X サーバーを持たない組み込みのUnixです。ほかにも、OSのインストーラや、カーネル設定などのツールで、これらはグラフィカルサポートが利用可能になる前に動作する必要があります。

The cursesライブラリは、プログラマーに重複しない複数のテキストウィンドウを含むディスプレイを抽象化した機能を提供します。ウィンドウの内容は複数の方法で変更が可能で、（文字の追加、削除、表示の変更等）cursesライブラリによって正しい出力を得るためのコントロールコードが判断されます。cursesが提供するユーザーインターフェースのコンセプトは限られています。ボタン、チェックボックス、ダイアログ等は含まれておりません。そのような機能が必要な場合は、Urwid.のようなユーザーインターフェースライブラリーの使用を検討してください。

curses ライブラリは元々 BSD UNIX 向けに書かれました; 後の AT&T から出た Unix System V バージョンで多くの機能と新機能が追加されました。BSD curses はいまやメンテナンスされておらず、これは AT&T インターフェースのオープンソース実装である ncurses にとって置き換えられました。Linux や FreeBSD のようなオープンソース Unix を利用している場合は、おそらくシステムは ncurses を利用しています。現在のほとんどの商用 Unix は System V のコードを基にしているため、ここで述べる全ての関数が利用できるはずです。しかし、古いバージョンの curses を持ついくつかのプロプライエタリ Unix は全てには対応していないでしょう。

Windows 版 Python には curses が含まれていません。 UniCurses という名の移植版が利用可能です。Fredrik Lundh の手による the Console module も試してみると良いでしょう。これには curses と同じ API を用いていませんが、カーソル位置指定でのテキスト出力と、マウス、キーボード入力のフルサポートを提供しています。

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.

This HOWTO is an introduction to writing text-mode programs with curses and Python. It doesn't attempt to be a complete guide to the curses API; for that, see the Python library guide's section on ncurses, and the C manual pages for ncurses. It will, however, give you the basic ideas.

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.

もし、スクリーンに複数のウィンドウやパッドを持っている場合、スクリーンをより効率よく更新し、スクリーンの各部が更新されるたびに起こるいらいらするちらつきを抑える方法があります。 refresh() は実際には二つの事を行っています。

  1. それぞれのウィンドウの noutrefresh() メソッドを呼び出して、配下にある、スクリーンの望ましい状態を表すデータ構造を更新します。
  2. doupdate() 関数を呼び出して、データ構造に記録された望ましい状態に合致するように、物理スクリーンを更新します。

かわりに、noutrefresh() を呼び出して、いくつかのウィンドウのデータ構造を更新し、その後に doupdate() を呼び出して、スクリーンを更新できます。

テキストの表示

C 言語のプログラマの視点からすると、curses はしばしば、混乱を招きやすい、微妙に似た関数を持っています。例えば addstr() は stdscr ウィンドウの現在のカーソル位置の文字列を表示し、一方で mvaddstr() は与えられた y,x 座標にまず移動して、文字列を表示します。 waddstr() はほとんど addstr() に似ていますが、デフォルトの stdscr を使う代わりに使うウィンドウを指定できます。 mvwaddstr() はウィンドウと座標の両方を指定できます。

幸運にも、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.getpreferredencoding().

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 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 モジュールのライブラリページはいまやかなり充実しています。次はこれを見るべきです。

curses 関数の詳細な振る舞いで不審に思ったら、それが ncurses であろうがプロプライエタリな Unix ベンダーのものであろうが、curses 実装のマニュアルページを調べてください。マニュアルページには、どんな気紛れ血の迷いでもドキュメントされ、関数、属性、 ACS_* 文字の完全なリストが提供されていることでしょう。

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 to learn more about submitting patches to Python.

  • Writing Programs with NCURSES: C プログラマ向けの非常に長いチュートリアルです。
  • The ncurses man page
  • The ncurses FAQ
  • "Use curses... don't swear": curses または Urwid を使って端末を制御する PyCon 2013 講演ビデオです。
  • "Console Applications with Urwid": Urwid で書かれたいくつかのアプリケーションをデモンストレーションしている PyCon CA 2012 講演ビデオです。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python HOWTO »


デスクリプタ HowTo ガイド

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

デスクリプタ HowTo ガイド

著者: | Raymond Hettinger
Contact: | <python at rcn dot com>

目次

  • デスクリプタ HowTo ガイド
    • 概要
    • 定義と導入
    • デスクリプタプロトコル
    • デスクリプタの呼び出し
    • デスクリプタの例
    • プロパティ
    • 関数とメソッド
    • 静的メソッドとクラスメソッド

概要

Defines descriptors, summarizes the protocol, and shows how descriptors are called. Examines a custom descriptor and several built-in Python descriptors including functions, properties, static methods, and class methods. Shows how each works by giving a pure Python equivalent and a sample application.

デスクリプタについて学ぶことにより、新しいツールセットが使えるようになるだけでなく、Python の仕組みや、洗練された設計のアプリケーションについてのより深い理解が得られます。

定義と導入

一般に、デスクリプタは "束縛動作 (binding behavior)" をもつオブジェクト属性で、その属性アクセスが、デスクリプタプロトコルのメソッドによってオーバーライドされたものです。このメソッドは、 __get__(), __set__(), および __delete__() です。これらのメソッドのいずれかが、オブジェクトに定義されていれば、それはデスクリプタと呼ばれます。

属性アクセスのデフォルトの振る舞いは、オブジェクトの辞書の属性の取得、設定、削除です。例えば a.x は、まず a.__dict__['x']、それから type(a).__dict__['x']、さらに type(a) のメタクラスを除く基底クラスへと続くというように探索が連鎖します。見つかった値が、デスクリプタメソッドのいずれかを定義しているオブジェクトなら、Python はそのデフォルトの振る舞いをオーバーライドし、代わりにデスクリプタメソッドを呼び出します。これがどの連鎖順位で行われるかは、どのデスクリプタメソッドが定義されているかに依ります。

デスクリプタは、強力な、多目的のプロトコルです。これはプロパティ、メソッド、静的メソッド、クラスメソッド、そして super() の背後にある機構です。これはバージョン 2.2 で導入された新スタイルクラスを実装するために、Python のいたるところで使われています。デスクリプタは、基幹にある C コードを簡潔にし、毎日の Python プログラムに、柔軟な新しいツール群を提供します。

デスクリプタプロトコル

descr.__get__(self, obj, type=None) -> value

descr.__set__(self, obj, value) -> None

descr.__delete__(self, obj) -> None

これで全てです。これらのメソッドのいずれかを定義すれば、オブジェクトはデスクリプタとみなされ、探索された際のデフォルトの振る舞いをオーバーライドできます。

あるオブジェクトが __get__() と __set__() の両方を定義していたら、それはデータデスクリプタとみなされます。 __get__() だけを定義しているデスクリプタは、非データデスクリプタと呼ばれます (これらは典型的にはメソッドに使われますが、他の使い方も出来ます)。

データデスクリプタと非データデスクリプタでは、オーバーライドがインスタンスの辞書のエントリに関してどのように計算されるかが異なります。インスタンスの辞書に、データデスクリプタと同名の項目があれば、データデスクリプタの方が優先されます。インスタンスの辞書に、非データデスクリプタと同名の項目があれば、辞書の項目の方が優先されます。

読み出し専用のデータデスクリプタを作るには、 __get__() と __set__() の両方を定義し、 __set__() が呼び出されたときに AttributeError が送出されるようにしてください。例外を送出する __set__() メソッドをプレースホルダとして定義すれば、データデスクリプタにするのに十分です。

デスクリプタの呼び出し

デスクリプタは、メソッド名で直接呼ぶことも出来ます。例えば、d.__get__(obj) です。

または、一般的に、デスクリプタは属性アクセスから自動的に呼び出されます。例えば、 obj.d は obj の辞書から d を探索します。 d がメソッド __get__() を定義していたら、以下に列挙する優先順位に従って、 d.__get__(obj) が呼び出されます。

呼び出しの詳細は、obj がオブジェクトかクラスかに依ります。

オブジェクトでは、その機構は b.x を type(b).__dict__['x'].__get__(b, type(b)) に変換する object.__getattribute__() にあります。データデスクリプタの優先度はインスタンス変数より高く、インスタンス変数の優先度は非データデスクリプタより高く、(提供されていれば) __getattr__() の優先度が最も低いように実装されています。完全な C 実装は、 Objects/object.c の PyObject_GenericGetAttr() で見つかります。

クラスでは、その機構は B.x を B.__dict__['x'].__get__(None, B) に変換する type.__getattribute__() にあります。 pure Python では、このようになります:

def __getattribute__(self, key):
    "Emulate type_getattro() in Objects/typeobject.c"
    v = object.__getattribute__(self, key)
    if hasattr(v, '__get__'):
        return v.__get__(None, self)
    return v

憶えておくべき重要な点は:

  • デスクリプタは __getattribute__() メソッドによって呼び出される
  • __getattribute__() をオーバーライドすると、自動的なデスクリプタの呼び出しが行われなくなる
  • object.__getattribute__() と type.__getattribute__() では、 __get__() の呼び出しが異なる。
  • データデスクリプタは、必ずインスタンス辞書をオーバーライドする。
  • 非データデスクリプタは、インスタンス辞書にオーバーライドされることがある。

super() が返したオブジェクトにはさらにデスクリプタを起動するカスタム __getattribute__() メソッドがあります。 super(B, obj).m() の呼び出しは、 B に続き基底クラス A を見つけるために obj.__class__.__mro__ を探索し、 A.__dict__['m'].__get__(obj, B) を返します。デスクリプタではない場合、 m が変更されずに返されます。辞書になければ、 m は object.__getattribute__() を使用した探索に戻ります。

実装の詳細は、 Objects/typeobject.c の super_getattro() と、 Guido's Tutorial にある等価な pure Python 版を参照してください。

上述の詳細は、デスクリプタの機構が、 __getattribute__() メソッドに埋めこまれ、 object, type, そして super() に使われているということを表しています。クラスは、 object から導出されたとき、または、同じような機能を提供するメタクラスをもつとき、この機構を継承します。同様に、 __getattribute__() をオーバーライドすることで、デスクリプタの呼び出しを無効にできます。

デスクリプタの例

以下のコードは、オブジェクトが取得と設定のたびにメッセージを表示するデータデスクリプタであるようなクラスを生成します。代わりに __getattribute__() をオーバーライドすると、全ての属性に対してこれができます。しかし、このデスクリプタは、少数の選ばれた属性を監視するのに便利です:

class RevealAccess(object):
    """A data descriptor that sets and returns values
       normally and prints a message logging their access.
    """

    def __init__(self, initval=None, name='var'):
        self.val = initval
        self.name = name

    def __get__(self, obj, objtype):
        print('Retrieving', self.name)
        return self.val

    def __set__(self, obj, val):
        print('Updating', self.name)
        self.val = val

>>> class MyClass(object):
...     x = RevealAccess(10, 'var "x"')
...     y = 5
...
>>> m = MyClass()
>>> m.x
Retrieving var "x"
10
>>> m.x = 20
Updating var "x"
>>> m.x
Retrieving var "x"
20
>>> m.y
5

The protocol is simple and offers exciting possibilities. Several use cases are so common that they have been packaged into individual function calls. Properties, bound methods, static methods, and class methods are all based on the descriptor protocol.

プロパティ

property() を呼び出すことで、属性へアクセスすると関数の呼び出しを引き起こす、データデスクリプタを簡潔に組み立てられます。シグネチャはこうです:

property(fget=None, fset=None, fdel=None, doc=None) -> property attribute

このドキュメントでは、管理された属性 x を定義する典型的な使用法を示します:

class C(object):
    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(object):
    "Emulate PyProperty_Type() in Objects/descrobject.c"

    def __init__(self, fget=None, fset=None, fdel=None, doc=None):
        self.fget = fget
        self.fset = fset
        self.fdel = fdel
        if doc is None and fget is not None:
            doc = fget.__doc__
        self.__doc__ = doc

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        if self.fget is None:
            raise AttributeError("unreadable attribute")
        return self.fget(obj)

    def __set__(self, obj, value):
        if self.fset is None:
            raise AttributeError("can't set attribute")
        self.fset(obj, value)

    def __delete__(self, obj):
        if self.fdel is None:
            raise AttributeError("can't delete attribute")
        self.fdel(obj)

    def getter(self, fget):
        return type(self)(fget, self.fset, self.fdel, self.__doc__)

    def setter(self, fset):
        return type(self)(self.fget, fset, self.fdel, self.__doc__)

    def deleter(self, fdel):
        return type(self)(self.fget, self.fset, fdel, self.__doc__)

組み込みの property() 関数は、ユーザインタフェースへの属性アクセスが与えられ、続く変更がメソッドの介入を要求するときに役立ちます。

例えば、スプレッドシートクラスが、Cell('b10').value でセルの値を取得できるとします。続く改良により、プログラムがアクセスの度にセルの再計算をすることを要求しました。しかしプログラマは、その属性に直接アクセスする既存のクライアントコードに影響を与えたくありません。この解決策は、property データデスクリプタ内に値属性へのアクセスをラップすることです:

class Cell(object):
    . . .
    def getvalue(self):
        "Recalculate the cell before returning value"
        self.recalc()
        return self._value
    value = property(getvalue)

関数とメソッド

Python のオブジェクト指向機能は、関数に基づく環境の上に構築されています。非データデスクリプタを使って、この 2 つはシームレスに組み合わされています。

Class dictionaries store methods as functions. In a class definition, methods are written using def or lambda, the usual tools for creating functions. Methods only differ from regular functions in that the first argument is reserved for the object instance. By Python convention, the instance reference is called self but may be called this or any other variable name.

To support method calls, functions include the __get__() method for binding methods during attribute access. This means that all functions are non-data descriptors which return bound methods when they are invoked from an object. In pure Python, it works like this:

class Function(object):
    . . .
    def __get__(self, obj, objtype=None):
        "Simulate func_descr_get() in Objects/funcobject.c"
        if obj is None:
            return self
        return types.MethodType(self, obj)

インタプリタを起動すると、この関数デスクリプタが実際にどうはたらくかを見られます:

>>> class D(object):
...     def f(self, x):
...         return x
...
>>> d = D()

# Access through the class dictionary does not invoke __get__.
# It just returns the underlying function object.
>>> D.__dict__['f']
<function D.f at 0x00C45070>

# Dotted access from a class calls __get__() which just returns
# the underlying function unchanged.
>>> D.f
<function D.f at 0x00C45070>

# The function has a __qualname__ attribute to support introspection
>>> D.f.__qualname__
'D.f'

# Dotted access from an instance calls __get__() which returns the
# function wrapped in a bound method object
>>> d.f
<bound method D.f of <__main__.D object at 0x00B18C90>>

# Internally, the bound method stores the underlying function,
# the bound instance, and the class of the bound instance.
>>> d.f.__func__
<function D.f at 0x1012e5ae8>
>>> d.f.__self__
<__main__.D object at 0x1012e1f98>
>>> d.f.__class__
<class 'method'>

静的メソッドとクラスメソッド

非データデスクリプタは、関数をメソッドに束縛する、各種の一般的なパターンに、単純な機構を提供します。

まとめると、関数は __get__() メソッドを持ち、属性としてアクセスされたとき、メソッドに変換されます。この非データディスクリプタは、 obj.f(*args) の呼び出しを f(obj, *args) に変換します。 klass.f(*args) を呼び出すと f(*args) になります。

このチャートは、束縛と、その 2 つの異なる便利な形をまとめています:

変換 | オブジェクトから呼び出される | クラスから呼び出される
function | f(obj, *args) | f(*args)
静的メソッド | f(*args) | f(*args)
クラスメソッド | f(type(obj), *args) | f(klass, *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(object):
...     def f(x):
...         print(x)
...     f = staticmethod(f)
...
>>> print(E.f(3))
3
>>> print(E().f(3))
3

非データデスクリプタプロトコルを使うと、pure Python 版の staticmethod() は以下のようになります:

class StaticMethod(object):
    "Emulate PyStaticMethod_Type() in Objects/funcobject.c"

    def __init__(self, f):
        self.f = f

    def __get__(self, obj, objtype=None):
        return self.f

静的メソッドとは違って、クラスメソッドは関数を呼び出す前にクラス参照を引数リストの先頭に加えます。このフォーマットは、呼び出し元がオブジェクトでもクラスでも同じです:

>>> class E(object):
...     def f(klass, x):
...         return klass.__name__, x
...     f = classmethod(f)
...
>>> print(E.f(3))
('E', 3)
>>> print(E().f(3))
('E', 3)

この振る舞いは、関数がクラス参照のみを必要とし、下にあるデータを考慮しないときに便利です。クラスメソッドの使い方の一つは、代わりのクラスコンストラクタを作ることです。Python 2.3 では、クラスメソッド dict.fromkeys() は新しい辞書をキーのリストから生成します。等価な pure Python 版は:

class Dict(object):
    . . .
    def fromkeys(klass, iterable, value=None):
        "Emulate dict_fromkeys() in Objects/dictobject.c"
        d = klass()
        for key in iterable:
            d[key] = value
        return d
    fromkeys = classmethod(fromkeys)

これで一意なキーを持つ新しい辞書が以下のように構成できます:

>>> Dict.fromkeys('abracadabra')
{'a': None, 'r': None, 'b': None, 'c': None, 'd': None}

非データデスクリプタプロトコルを使った、 classmethod() の pure Python 版はこのようになります:

class ClassMethod(object):
    "Emulate PyClassMethod_Type() in Objects/funcobject.c"

    def __init__(self, f):
        self.f = f

    def __get__(self, obj, klass=None):
        if klass is None:
            klass = type(obj)
        def newfunc(*args):
            return self.f(klass, *args)
        return newfunc

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python HOWTO »


Logging クックブック

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

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()

When run, the script should print something like the following:

   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.warn('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='/temp/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.')

When you run this, on the console you will see

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.

and in the file you will see something like

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 メッセージはファイルだけに出力され、その他のメッセージは両方に出力されます。

この例ではコンソールとファイルのハンドラだけを使っていますが、実際には任意の数のハンドラや組み合わせを使えます。

設定サーバの例

ログ記録設定サーバを使うモジュールの例です:

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.warn('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!

バージョン 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()

First run the server, and then the client. On the client side, nothing is printed on the console; on the server side, you should see something like:

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() メソッドをオーバーライドして代替手段を実装することで異なるシリアライズ手法を使用できます。代替シリアライズ手法を使うように上記のスクリプトを修正することもできます。

コンテキスト情報をログ記録出力に付加する

時にはログ記録出力にログ関数の呼び出し時に渡されたパラメータに加えてコンテキスト情報を含めたいこともあるでしょう。たとえば、ネットワークアプリケーションで、クライアント固有の情報 (例: リモートクライアントの名前、 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')

which, when run, produces something like:

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

複数のプロセスからの単一ファイルへのログ記録

ログ記録はスレッドセーフであり、単一プロセスの複数のスレッドからの単一ファイルへのログ記録はサポート されています が、 複数プロセス からの単一ファイルへのログ記録はサポート されません 。なぜなら、複数のプロセスをまたいで単一のファイルへのアクセスを直列化する標準の方法が Python には存在しないからです。複数のプロセスから単一ファイルへログ記録しなければならないなら、最も良い方法は、すべてのプロセスが SocketHandler に対してログ記録を行い、独立したプロセスとしてソケットサーバを動かすことです。ソケットサーバはソケットから読み取ってファイルにログを書き出します。 (この機能を実行するために、既存のプロセスの 1 つのスレッドを割り当てることもできます) この節 では、このアプローチをさらに詳細に文書化しています。動作するソケット受信プログラムが含まれているので、アプリケーションに組み込むための出発点として使用できるでしょう。

multiprocessing モジュールを含む最近のバージョンの Python を使用しているなら、複数のプロセスからファイルへのアクセスを直列化するために 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 プロセス側で生成されますが) 各メッセージを適切な出力先に出力します。

ファイルをローテートする

ログファイルがある大きさに達したら、新しいファイルを開いてそこにログを取りたいことがあります。そのファイルをある数だけ残し、その数のファイルが生成されたらファイルを循環し、ファイルの数も大きさも制限したいこともあるでしょう。この利用パターンのために、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)

The result should be 6 separate files, each with part of the log history for the application:

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 calls (logger.debug(), logger.info() etc.) only take positional parameters for the actual logging message itself, with keyword parameters used only for determining options for how to handle the actual logging call (e.g. the exc_info keyword parameter to indicate that traceback information should be logged, or the extra keyword parameter to indicate additional contextual information to be added to the log). So you cannot directly make logging calls using str.format() or string.Template syntax, because internally the logging package uses %-formatting to merge the format string and the variable arguments. There would be no changing this while preserving backward compatibility, since all logging calls which are out there in existing code will be using %-format strings.

しかし、{} や $ を使ってログメッセージをフォーマットする方法はあります。ログメッセージには任意のオブジェクトを 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(object):
    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 __init__(self, logger, extra=None):
        super(StyleAdapter, self).__init__(logger, extra or {})

    def log(self, level, msg, *args, **kwargs):
        if self.isEnabledFor(level):
            msg, kwargs = self.process(msg, kwargs)
            self.logger._log(level, Message(msg, args), (), **kwargs)

logger = StyleAdapter(logging.getLogger(__name__))

def main():
    logger.debug('Hello, {}', 'world!')

if __name__ == '__main__':
    logging.basicConfig(level=logging.DEBUG)
    main()

上のスクリプトは Python 3.2 以降では 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 を利用するだけでは望む結果が得られない場合にのみ使うべきです。

QueueHandler を継承する - ZeroMQ を使う例

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()

QueueListener のサブクラスを作る - ZeroMQ を使う例

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)

参考

logging モジュール
logging モジュールの API リファレンス。
logging.config モジュール
logging モジュールの環境設定 API です。
logging.handlers モジュール
logging モジュールに含まれる、便利なハンドラです。

logging 基本チュートリアル

logging 上級チュートリアル

辞書ベースで構成する例

次の例は辞書を使った logging の構成です。この例は Django プロジェクトのドキュメント から持ってきました。この辞書を dictConfig() に渡して設定を有効にします:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': True,
    'formatters': {
        'verbose': {
            'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'
        },
        'simple': {
            'format': '%(levelname)s %(message)s'
        },
    },
    'filters': {
        'special': {
            '()': 'project.logging.SpecialFilter',
            'foo': 'bar',
        }
    },
    'handlers': {
        'null': {
            'level':'DEBUG',
            'class':'django.utils.log.NullHandler',
        },
        'console':{
            'level':'DEBUG',
            'class':'logging.StreamHandler',
            'formatter': 'simple'
        },
        'mail_admins': {
            'level': 'ERROR',
            'class': 'django.utils.log.AdminEmailHandler',
            'filters': ['special']
        }
    },
    'loggers': {
        'django': {
            'handlers':['null'],
            'propagate': True,
            'level':'INFO',
        },
        'django.request': {
            'handlers': ['mail_admins'],
            'level': 'ERROR',
            'propagate': False,
        },
        'myproject.custom': {
            'handlers': ['console', 'mail_admins'],
            'level': 'INFO',
            'filters': ['special']
        }
    }
}

この構成方法についてのより詳しい情報は、 Django のドキュメントの 該当のセクション で見ることができます。

rotator と namer を使ってログローテートをカスタマイズする

次の、ログファイルを zlib ベースの圧縮をするスニペットでは、namer と rotater を定義する方法の例を提供してます:

def namer(name):
    return name + ".gz"

def rotator(source, dest):
    with open(source, "rb") as sf:
        data = sf.read()
        compressed = zlib.compress(data, 9)
        with open(dest, "wb") as df:
            df.write(compressed)
    os.remove(source)

rh = logging.handlers.RotatingFileHandler(...)
rh.rotator = rotator
rh.namer = namer

これは本当の .gz ファイルではなく、実際の gzip ファイルが持っている "コンテナ" がない生の圧縮データです。このスニペットはただの解説用です。

より手の込んだ 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):
        logger = logging.getLogger(record.name)
        # 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,
        'formatters': {
            'detailed': {
                'class': 'logging.Formatter',
                'format': '%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
            }
        },
        'handlers': {
            'console': {
                'class': 'logging.StreamHandler',
                'level': 'INFO',
            },
        },
        'root': {
            'level': 'DEBUG',
            'handlers': ['console']
        },
    }
    # 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': {
            'level': 'DEBUG',
            'handlers': ['queue']
        },
    }
    # 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',
                'level': 'INFO',
                'formatter': 'simple',
            },
            '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']
        },
    }
    # 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 requires that a Unicode message be sent to a syslog daemon as a set of bytes which have the following structure: an optional pure-ASCII component, followed by a UTF-8 Byte Order Mark (BOM), followed by Unicode encoded using UTF-8. (See the relevant section of the specification.)

Python 3.1 で SysLogHandler に、 message に BOM を挿入するコードが追加されました。しかし、そのときの実装が悪くて、 message の先頭に BOM をつけてしまうのでピュアASCII 部分をその前に書くことができませんでした。

As this behaviour is broken, the incorrect BOM insertion code is being removed from Python 3.2.4 and later. However, it is not being replaced, and if you want to produce RFC 5424-compliant messages which include a BOM, an optional pure-ASCII sequence before it and arbitrary Unicode after it, encoded using UTF-8, then you need to do the following:

  1. SysLogHandler のインスタンスに、次のような format 文字列を持った Formatter インスタンスをアタッチする:

    'ASCII section\ufeffUnicode section'

    Unicode のコードポイント U+FEFF は、UTF-8 でエンコードすると BOM -- b'\xef\xbb\xbf' -- になります。

  2. ASCII セクションを好きなプレースホルダに変更する。ただしその部分の置換結果が常に ASCII になるように注意する(UTF-8 でエンコードされてもその部分が変化しないようにする)。

  3. Unicode セクションを任意のプレースホルダに置き換える。この部分を置換したデータに ASCII 外の文字が含まれていても、それは単に UTF-8 でエンコードされるだけです。

The formatted message will be encoded using UTF-8 encoding by SysLogHandler. If you follow the above rules, you should be able to produce RFC 5424-compliant messages. If you don't, logging may not complain, but your messages will not be RFC 5424-compliant, and your syslog daemon may complain.

構造化ログを実装する

多くのログメッセージは人間が読むために書かれるため、機械的に処理しにくくなっていますが、場合によっては (複雑な正規表現を使ってログメッセージをパースしなくても) プログラムがパース できる 構造化されたフォーマットでメッセージを出力したい場合があります。 logging パッケージを使うと、これを簡単に実現できます。 実現する方法は幾つもありますが、次の例は JSON を使ってイベントを、機械でパースできる形にシリアライズする単純な方法です:

import json
import logging

class StructuredMessage(object):
    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))

If the above script is run, it prints:

message 1 >>> {"fnum": 123.456, "num": 123, "bar": "baz", "foo": "bar"}

要素の順序は Python のバージョンによって異なることに注意してください。

より特殊な処理が必要な場合、次の例のように、カスタムの JSON エンコーダを作ることができます:

from __future__ import unicode_literals

import json
import logging

# This next bit is to ensure the script runs unchanged on 2.x and 3.x
try:
    unicode
except NameError:
    unicode = str

class Encoder(json.JSONEncoder):
    def default(self, o):
        if isinstance(o, set):
            return tuple(o)
        elif isinstance(o, unicode):
            return o.encode('unicode_escape').decode('ascii')
        return super(Encoder, self).default(o)

class StructuredMessage(object):
    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()

When the above script is run, it prints:

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 でサポートされているのと同じ書式化のアプローチを採れます。これは最終的に出力されるログメッセージの書式化に影響を与えますが、個々のログメッセージが構築される方法とは完全に直交していることに注意してください。

logging の呼び出し (debug(), info() など) は、ログメッセージのために位置引数しか受け取らず、キーワード引数はそれを処理するときのオプションを指定するためだけに使われます。 (例えば、 exc_info キーワード引数を使ってログを取るトレースバック情報を指定したり、 extra キーワード引数を使ってログに付与する追加のコンテキスト情報を指定します。)logging パッケージは内部で % を使って format 文字列と引数をマージしているので、 str.format() や string.Template を使って logging を呼び出す事はできません。既存の logging 呼び出しは %-format を使っているので、後方互換性のためにこの部分を変更することはできません。

特定のロガーに関連付ける書式スタイルへの提案がなされてきましたが、そのアプローチは同時に後方互換性の問題にぶち当たります。あらゆる既存のコードはロガーの名前を使っているでしょうし、 % 形式書式化を使っているでしょう。

あらゆるサードパーティのライブラリ、あらゆるあなたのコードの間で相互運用可能なようにロギングを行うには、書式化についての決定は、個々のログ呼び出しのレベルで行う必要があります。これは受け容れ可能な代替書式化スタイルに様々な手段の可能性を広げます。

LogRecord ファクトリを使う

Python 3.2 において、上述した Formatter の変更とともに、 setLogRecordFactory() 関数を使って LogRecord のサブクラスをユーザに指定することを可能にするロギングパッケージの機能拡張がありました。これにより、 getMessage() をオーバライドして た　だ　し　い　ことをする、あなた自身の手による LogRecord のサブクラスをセットすることが出来ます。このメソッドの実装は基底クラスでは msg % args 書式化をし、あなたの代替の書式化の置換が出来る場所ですが、他のコードとの相互運用性を保障するために、全ての書式化スタイルをサポートするよう注意深く行うべきであり、また、%-書式化をデフォルトで認めるべきです。基底クラスの実装がそうしているように、 str(self.msg) 呼び出しもしてください。

さらに詳しい情報は、リファレンスの setLogRecordFactory(), LogRecord を参照してください。

カスタムなメッセージオブジェクトを使う

あなた独自のログメッセージを構築するのに {}- および $- 書式化を使えるようにするための、もうひとつの、おそらくもっと簡単な方法があります。ロギングの際には、あなたはメッセージ書式文字列として、任意のオブジェクトを使えることを(任意のオブジェクトをメッセージに使用する より)思い出してみましょう、そしてロギングパッケージはそのオブジェクトに対して実際の書式文字列を得るために str() を呼び出すことも。以下 2 つのクラスを検討してみましょう:

class BraceMessage(object):
    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(object):
    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')

This example shows how you can pass configuration data to the callable which constructs the instance, in the form of keyword parameters. When run, the above script will print:

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(OneLineExceptionFormatter, self).formatException(exc_info)
        return repr(result)  # or format into one line however you want to

    def format(self, record):
        s = super(OneLineExceptionFormatter, self).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()

When run, this produces a file with exactly two lines:

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)

When this script is run, the following output should be observed:

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

設定によって時刻を 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())

When this script is run, it should print something like:

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(object):
    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 でも動くことに注意してください。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python HOWTO »


正規表現 HOWTO

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

正規表現 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' または '$' にマッチします; '$' は通常は特殊文字ですが、文字クラス内部では特殊な性質は取り除かれます。

You can match the characters not listed within the class by complementing the set. This is indicated by including a '^' as the first character of the class; '^' outside a character class will simply match the '^' character. For example, [^5] will match any character except '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,.] は空白文字や ',' または '.' にマッチする文字クラスです。

The final metacharacter in this section is .. It matches anything except a newline character, and there's an alternate mode (re.DOTALL) where it will match even a newline. . is often used where you want to match "any character".

繰り返し

さまざまな文字集合をマッチさせることは正規表現で最初にできるようになることで、これは文字列に対するメソッドですぐにできることではありません。しかし、正規表現がより力を発揮する場面がこれだけだとすると、正規表現はあまり先進的とはいえません。正規表現の力をもう一つの能力は、正規表現の一部が何度も繰り返されるようものを指定できることです。

The first metacharacter for repeating things that we'll look at is *. * doesn't match the literal character '*'; instead, it specifies that the previous character can be matched zero or more times, instead of exactly once.

例えば、 ca*t は 'ct' ( 'a' という文字が 0 個の場合)、 'cat' ('a' が1個の場合)、 'caaat' ('a' が3個の場合)、などにマッチします。

* のような繰り返しは 貪欲 (greedy) です; 正規表現を繰り返したいとき、マッチングエンジンは可能な限り何度も繰り返そうと試みます。パターンの後ろの部分にマッチしない場合、マッチングエンジンは戻ってより少ない繰り返しを再び試みます。

A step-by-step example will make this more obvious. Let's consider the expression a[bcd]*b. This matches the letter 'a', zero or more letters from the class [bcd], and finally ends with a 'b'. Now imagine matching this RE against the string 'abcbd'.

ステップ | マッチした文字列 | 説明
1 | a | a が正規表現にマッチ。
2 | abcbd | 正規表現エンジンが [bcd]* で文字列の最後まで可能な限り進む。
3 | 失敗 | エンジンが b とのマッチを試みるが、現在の位置が文字列の最後なので、失敗する。
4 | abcb | 戻って [bcd]* は一文字少なくマッチ。
5 | 失敗 | 再び b へのマッチを試みるが、現在の文字は最後の文字 'd' 。
6 | abc | 再び戻る, [bcd]* は bc のみにマッチ。
6 | abcb | 再び b を試みる。今回の現在位置の文字は 'b' なので成功。

The end of the RE has now been reached, and it has matched 'abcb'. This demonstrates how the matching engine goes as far as it can at first, and if no match is found it will then progressively back up and retry the rest of the RE again and again. It will back up until it has tried zero matches for [bcd]*, and if that subsequently fails, the engine will conclude that the string doesn't match the RE at all.

Another repeating metacharacter is +, which matches one or more times. Pay careful attention to the difference between * and +; * matches zero or more times, so whatever's being repeated may not be present at all, while + requires at least one occurrence. To use a similar example, ca+t will match 'cat' (1 'a'), 'caaat' (3 'a's), but won't match 'ct'.

There are two more repeating qualifiers. The question mark character, ?, matches either once or zero times; you can think of it as marking something as being optional. For example, home-?brew matches either 'homebrew' or 'home-brew'.

The most complicated repeated qualifier is {m,n}, where m and n are decimal integers. This qualifier means there must be at least m repetitions, and at most n. For example, a/{1,3}b will match 'a/b', 'a//b', and 'a///b'. It won't match 'ab', which has no slashes, or 'a////b', which has four.

You can omit either m or n; in that case, a reasonable value is assumed for the missing value. Omitting m is interpreted as a lower limit of 0, while omitting n results in an upper bound of infinity.

還元主義的素養のある読者は、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 記法を使って書かれます。

In addition, special escape sequences that are valid in regular expressions, but not valid as Python string literals, now result in a DeprecationWarning and will eventually become a SyntaxError, which means the sequences will be invalid if raw string notation or escaping the backslashes isn't used.

通常の文字列 | Raw string
"ab*" | r"ab*"
"\\\\section" | r"\\section"
"\\w+\\s+\\1" | r"\w+\s+\1"

マッチの実行

一旦コンパイルした正規表現を表現するオブジェクトを作成したら、次に何をしますか? パターンオブジェクトはいくつかのメソッドや属性を持っています。ここでは、その中でも最も重要なものについて扱います; 完全なリストは re ドキュメントを参照して下さい。

メソッド/属性 | 目的
match() | 文字列の先頭で正規表現とマッチするか判定します。
search() | 文字列を操作して、正規表現がどこにマッチするか調べます。
findall() | 正規表現にマッチする部分文字列を全て探しだしリストとして返します。
finditer() | 正規表現にマッチする部分文字列を全て探しだし iterator として返します。

match() and search() return None if no match can be found. If they're successful, a match object instance is returned, containing information about the match: where it starts and ends, the substring it matched, and more.

re モジュールで対話的に実験することで学ぶこともできます。 tkinter が利用できれば、Python に含まれるデモプログラム Tools/demo/redemo.py を見るといいかもしれません。このデモは正規表現と文字列を入力し、正規表現がマッチしたかどうかを表示します。 redemo.py は複雑な正規表現のデバッグを試みるときにも便利に使うことができます。

この HOWTO では例として標準の Python インタプリタを使います。最初に Python インタプリタを起動して、 re モジュールをインポートし、正規表現をコンパイルします:

>>> import re
>>> p = re.compile('[a-z]+')
>>> p
re.compile('[a-z]+')

Now, you can try matching various strings against the RE [a-z]+. An empty string shouldn't match at all, since + means 'one or more repetitions'. match() should return None in this case, which will cause the interpreter to print no output. You can explicitly print the result of match() to make this clear.

>>> p.match("")
>>> print(p.match(""))
None

Now, let's try it on a string that it should match, such as tempo. In this case, match() will return a match object, so you should store the result in a variable for later use.

>>> m = p.match('tempo')
>>> m
<re.Match object; span=(0, 5), match='tempo'>

Now you can query the match object for information about the matching string. Match object instances also have several methods and attributes; the most important ones are:

メソッド/属性 | 目的
group() | 正規表現にマッチした文字列を返す
start() | マッチの開始位置を返す
end() | マッチの終了位置を返す
span() | マッチの位置 (start, end) を含むタプルを返す

これらのメソッドを試せば、その意味はすぐに理解できます:

>>> m.group()
'tempo'
>>> m.start(), m.end()
(0, 5)
>>> m.span()
(0, 5)

group() returns the substring that was matched by the RE. start() and end() return the starting and ending index of the match. span() returns both start and end indexes in a single tuple. Since the match() method only checks if the RE matches at the start of a string, start() will always be zero. However, the search() method of patterns scans through the string, so the match may not start at zero in that case.

>>> 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')

Two pattern methods return all of the matches for a pattern. findall() returns a list of matching strings:

>>> p = re.compile(r'\d+')
>>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')
['12', '11', '10']

The r prefix, making the literal a raw string literal, is needed in this example because escape sequences in a normal "cooked" string literal that are not recognized by Python, as opposed to regular expressions, now result in a DeprecationWarning and will eventually become a SyntaxError. See バックスラッシュ感染症.

findall() has to create the entire list before it can be returned as the result. The finditer() method returns a sequence of match object instances as an 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 | Make . match any character, including newlines.
IGNORECASE, I | Do case-insensitive matches.
LOCALE, L | Do a locale-aware match.
MULTILINE, M | Multi-line matching, affecting ^ and $.
VERBOSE, X ('X' は 'extended' の 'X') | 冗長な正規表現を利用できるようにして、よりきれいで理解しやすくまとめることができます。
I
IGNORECASE

Perform case-insensitive matching; character class and literal strings will match letters by ignoring case. For example, [A-Z] will match lowercase letters, too. Full Unicode matching also works unless the ASCII flag is used to disable non-ASCII matches. When the Unicode patterns [a-z] or [A-Z] are used in combination with the IGNORECASE flag, they will match the 52 ASCII letters and 4 additional non-ASCII letters: 'İ' (U+0130, Latin capital letter I with dot above), 'ı' (U+0131, Latin small letter dotless i), 'ſ' (U+017F, Latin small letter long s) and 'K' (U+212A, Kelvin sign). Spam will match 'Spam', 'spam', 'spAM', or 'ſpam' (the latter is matched only in Unicode mode). This lowercasing doesn't take the current locale into account; it will if you also set the LOCALE flag.

L
LOCALE

Make \w, \W, \b, \B and case-insensitive matching dependent on the current locale instead of the Unicode database.

Locales are a feature of the C library intended to help in writing programs that take account of language differences. For example, if you're processing encoded French text, you'd want to be able to write \w+ to match words, but \w only matches the character class [A-Za-z] in bytes patterns; it won't match bytes corresponding to é or ç. If your system is configured properly and a French locale is selected, certain C functions will tell the program that the byte corresponding to é should also be considered a letter. Setting the LOCALE flag when compiling a regular expression will cause the resulting compiled object to use these C functions for \w; this is slower, but also enables \w+ to match French words as you'd expect. The use of this flag is discouraged in Python 3 as the locale mechanism is very unreliable, it only handles one "culture" at a time, and it only works with 8-bit locales. Unicode matching is already enabled by default in Python 3 for Unicode (str) patterns, and it is able to handle different locales/languages.

M
MULTILINE

(^ と $ についてはまだ説明していません; これらは さらなる特殊文字 の節で説明します。)

通常 ^ は文字列の先頭にマッチし、 $ は文字列の末尾と文字列の末尾に改行(があれば)その直前にマッチします。このフラグが指定されると、 ^ は文字列の先頭と文字列の中の改行に続く各行の先頭にマッチします。同様に $ 特殊文字は文字列の末尾と各行の末尾(各改行の直前)のどちらにもマッチします。

S
DOTALL

特別な文字 '.' を改行を含む全ての任意の文字とマッチするようにします; このフラグが無しでは、 '.' は改行 以外 の全てにマッチします。

A
ASCII

\w, \W, \b, \B, \s, \S が、完全な Unicode マッチングではなく、ASCII のみのマッチングをするようにします。これは Unicode パターンにのみ意味があり、byte パターンには無視されます。

X
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 the "or" operator. If A and B are regular expressions, A|B will match any string that matches either A or B. | has very low precedence in order to make it work reasonably when you're alternating multi-character strings. Crow|Servo will match either 'Crow' or 'Servo', not 'Cro', a 'w' or an 'S', and '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

To match a literal '^', use \^.

$

行の末尾にマッチします、行の末尾は文字列の末尾と改行文字の直前として定義されます。

>>> 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 と逆で、現在の位置が単語の境界でないときにのみマッチします。

グルーピング

Frequently you need to obtain more information than just whether the RE matched or not. Regular expressions are often used to dissect strings by writing a RE divided into several subgroups which match different components of interest. For example, an RFC-822 header line is divided into a header name and a value, separated by a ':', like this:

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)

Groups indicated with '(', ')' also capture the starting and ending index of the text that they match; this can be retrieved by passing an argument to group(), start(), end(), and span(). Groups are numbered starting with 0. Group 0 is always present; it's the whole RE, so match object methods all have group 0 as their default argument. Later we'll see how to express groups that don't capture the span of text that they match.

>>> 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() can be passed multiple group numbers at a time, in which case it will return a tuple containing the corresponding values for those groups.

>>> m.group(2,1,2)
('b', 'abc', 'b')

The groups() method returns a tuple containing the strings for all the subgroups, from 1 up to however many there are.

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

名前つきグループは、番号を覚える代わりに、簡単に覚えられる名前を利用できるので、簡単に扱うことができます。これは 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') で取得した方が明らかに簡単にすみます。

The syntax for backreferences in an expression such as (...)\1 refers to the number of the group. There's naturally a variant that uses the group name instead of the number. This is another Python extension: (?P=name) indicates that the contents of the group called name should again be matched at the current point. The regular expression for finding doubled words, \b(\w+)\s+\1\b can also be written as \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() | Does the same thing as sub(), but returns the new string and the number of replacements

文字列の分割

The split() method of a pattern splits a string apart wherever the RE matches, returning a list of the pieces. It's similar to the split() method of strings but provides much more generality in the delimiters that you can split by; string split() only supports splitting by whitespace or by a fixed string. As you'd expect, there's a module-level re.split() function, too.

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

検索と置換

Another common task is to find all the matches for a pattern, and replace them with a different string. The sub() method takes a replacement value, which can be either a string or a function, and the string to be processed.

.sub(replacement, string[, count=0])

string 内で最も長く、他の部分と重複するところがない正規表現をを replacement に置換した文字列を返します。パターンが見つからなかった場合 string は変更されずに返されます。

オプション引数 count はパターンの出現の最大置換回数です; count は非負の整数でなければいけません。デフォルト値 0 は全ての出現で置換することを意味します。

Here's a simple example of using the sub() method. It replaces colour names with the word 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'

The subn() method does the same work, but returns a 2-tuple containing the new string value and the number of replacements that were performed:

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

Empty matches are replaced only when they're not adjacent to a previous empty match.

>>> 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' を返します。

よくある問題

正規表現はいくつかの応用に対して強力なツールですが、いくつかの部分でそれらの振る舞いは直感的ではなく、期待通りに振る舞わないことがあります。この節では最もよくある落とし穴を指摘します。

文字列メソッドを利用する

Sometimes using the re module is a mistake. If you're matching a fixed string, or a single character class, and you're not using any re features such as the IGNORECASE flag, then the full power of regular expressions may not be required. Strings have several methods for performing operations with fixed strings and they're usually much faster, because the implementation is a single small C loop that's been optimized for the purpose, instead of the large, more generalized regular expression engine.

One example might be replacing a single fixed string with another one; for example, you might replace word with deed. re.sub() seems like the function to use for this, but consider the replace() method. Note that replace() will also replace word inside words, turning swordfish into sdeedfish, but the naive RE word would have done that, too. (To avoid performing the substitution on parts of words, the pattern would have to be \bword\b, in order to require that word have a word boundary on either side. This takes the job beyond replace()'s abilities.)

Another common task is deleting every occurrence of a single character from a string or replacing it with another single character. You might do this with something like re.sub('\n', ' ', S), but translate() is capable of doing both tasks and will be faster than any regular expression operation can be.

要は、 re モジュールに向う前に問題が高速で単純な文字列メソッドで解決できるか考えましょうということです。

match() 対 search()

The match() function only checks if the RE matches at the beginning of the string while search() will scan forward through the string for a match. It's important to keep this distinction in mind. Remember, match() will only report a successful match which will start at 0; if the match wouldn't start at zero, match() will not report it.

>>> print(re.match('super', 'superstition').span())
(0, 5)
>>> print(re.match('super', 'insuperable'))
None

On the other hand, search() will scan forward through the string, reporting the first match it finds.

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

The RE matches the '<' in '<html>', and the .* consumes the rest of the string. There's still more left in the RE, though, and the > can't match at the end of the string, so the regular expression engine has to backtrack character by character until it finds a match for the >. The final match extends from the '<' in '<html>' to the '>' in '</title>', which isn't what you want.

この場合、解決法は非貪欲を示す修飾子 *?, +?, ?? または {m,n}? を利用することです、これらはテキストに可能な限り 少なく マッチします。上の例では、 '>' は最初の '<' とのマッチ後すぐに '>' を試みま、失敗した場合にはエンジンが文字を先に進め、'>' が毎ステップ再試行されます。この動作は正しい結果を生み出します:

>>> print(re.match('<.*?>', s).group())
<html>

(HTML や XML を正規表現でパースすることは苦痛を伴うものであることは記憶に留めておいて下さい。素早く、汚いパターンは大抵の場合うまく動作しますが、HTML と XML は正規表現が破綻する特別な例です; 全ての可能な場合にうまく動作する正規表現を書き上げたときには、パターンは 非常に 複雑なものになります。そのような作業をする場合には HTML や XML パーサを利用しましょう。)

re.VERBOSE の利用

ここまでで、正規表現がとても簡潔な表記であることに気づいたでしょう、また、正規表現は読みやすいものでもないということにも気づいたことでしょう。そこそこに入り組んだ正規表現ははバックスラッシュ、括弧、特殊文字が長く続いて、読みにくく、理解しづらいものになります。

For such REs, specifying the re.VERBOSE flag when compiling the regular expression can be helpful, because it allows you to format the regular expression more clearly.

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*$")

フィードバック

正規表現は複雑な話題です。このドキュメントは助けになったでしょうか？わかりにくかったところや、あなたが遭遇した問題が扱われていない等なかったでしょうか？もしそんな問題があれば、著者に改善の提案を送って下さい。

The most complete book on regular expressions is almost certainly Jeffrey Friedl's Mastering Regular Expressions, published by O'Reilly. Unfortunately, it exclusively concentrates on Perl and Java's flavours of regular expressions, and doesn't contain any Python material at all, so it won't be useful as a reference for programming in Python. (The first edition covered Python's now-removed regex module, which won't help you much.) Consider checking it out from your library.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python HOWTO »


ソート HOW TO

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

ソート HOW TO

著者: | Andrew Dalke and Raymond Hettinger
リリース: | 0.1

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.lower)
['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']

key パラメータは単一の引数をとり、ソートに利用される 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)]

operator モジュール関数

上述した key 関数のパターンはとても一般的です、 そのため、Python は高速で扱いやすいアクセサ関数を提供しています。 operator モジュールには itemgetter(), attrgetter() そして methodcaller() 関数があります。

これらの関数を利用すると、上の例はもっと簡単で高速になります:

>>> 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)]

昇順と降順

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 であることが保証されています。これはレコードの中に同じキーがある場合、元々の順序が維持されるということを意味します。

>>> 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)]

Python では Timsort アルゴリズムが利用されていて、効率良く複数のソートを行うことができます、これは現在のデータセット中のあらゆる順序をそのまま利用できるからです。

デコレート-ソート-アンデコレートを利用した古いやり方

このイディオムは以下の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 があります。これは Perl プログラマの間で有名な Randal L. Schwartz にちなんでいます。

いまや Python のソートは key 関数による方法を提供しているので、このテクニックは不要でしょう。

cmp パラメータを利用した古い方法

この HOWTO の内容の多くは Python 2.4 以降を仮定しています。それ以前では組み込み関数 sorted() と list.sort() はキーワード引数をとりませんでした。その代わりに Py2.x バージョンの全ては、ユーザが比較関数を指定するための cmp パラメータをサポートしました。

Py3.0 では cmp パラメータは完全に削除されました (ぜいたくな比較と __cmp__() マジックメソッドの衝突を除き、言語を単純化しまとめるための多大な労力の一環として)。

Py2.x ではソートにオプションとして比較に利用できる関数を与えることができます。関数は比較される二つの引数をとり、小さい場合には負の値を、等しい場合には 0 を、大きい場合には正の値を返さなければいけません。例えば、以下のようにできます:

>>> def numeric_compare(x, y):
...     return x - y
>>> sorted([5, 2, 4, 1, 3], cmp=numeric_compare) # doctest: +SKIP
[1, 2, 3, 4, 5]

また、比較順を逆にすることもできます:

>>> def reverse_numeric(x, y):
...     return y - x
>>> sorted([5, 2, 4, 1, 3], cmp=reverse_numeric) # doctest: +SKIP
[5, 4, 3, 2, 1]

Python 2.x から 3.x にコードを移植する場合、比較関数を持っている場合には key 関数に比較しなければならないような状況に陥るかもしれません。以下のラッパーがそれを簡単にしてくれるでしょう:

def cmp_to_key(mycmp):
    'Convert a cmp= function into a key= function'
    class K:
        def __init__(self, obj, *args):
            self.obj = obj
        def __lt__(self, other):
            return mycmp(self.obj, other.obj) < 0
        def __gt__(self, other):
            return mycmp(self.obj, other.obj) > 0
        def __eq__(self, other):
            return mycmp(self.obj, other.obj) == 0
        def __le__(self, other):
            return mycmp(self.obj, other.obj) <= 0
        def __ge__(self, other):
            return mycmp(self.obj, other.obj) >= 0
        def __ne__(self, other):
            return mycmp(self.obj, other.obj) != 0
    return K

key 関数を変換するには、古い比較関数をラップするだけです:

>>> sorted([5, 2, 4, 1, 3], key=cmp_to_key(reverse_numeric))
[5, 4, 3, 2, 1]

Python 3.2 には、標準ライブラリの functools モジュールに functools.cmp_to_key() 関数が追加されました。

残りいくつかとまとめ

  • ロケールに配慮したソートをするには、キー関数 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)]

  • ソートルーチンは二つのオブジェクトを比較するのに __lt__() を利用することを保証しています。そのため __lt__() メソッドを定義することで、標準のソート順序を追加できます:

    >>> Student.__lt__ = lambda self, other: self.age < other.age
>>> sorted(student_objects)
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

  • key 関数はソートするオブジェクトに依存する必要はありません。 key 関数は外部リソースにアクセスすることもできます。例えば学生の成績が辞書に保存されている場合、それを利用して別の学生の名前のリストをソートすることができます:

    >>> students = ['dave', 'john', 'jane']
>>> newgrades = {'john': 'F', 'jane':'A', 'dave': 'C'}
>>> sorted(students, key=newgrades.__getitem__)
['jane', 'dave', 'john']

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python HOWTO »


urllib パッケージを使ってインターネット上のリソースを取得するには

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

urllib パッケージを使ってインターネット上のリソースを取得するには

著者: Michael Foord

注釈

この HOWTO の前段階の版のフランス語訳が urllib2 - Le Manuel manquant で入手できます。

はじめに

Related Articles

同じように Python でインターネットリソースを取得するのに以下の記事が役に立ちます:

  • Basic Authentication

    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 です。この文書は技術文書なので簡単には読めません。この HOWTO の目的は urllib の利用法を例示することです、 HTTP についてはその助けになるのに十分に詳しく載せています。このドキュメントは urllib.request のドキュメントの代わりにはなりませんが、補完する役割を持っています。

URL を取得する

urllib.request を利用する最も簡単な方法は以下です:

import urllib.request
with urllib.request.urlopen('http://python.org/') as response:
   html = response.read()

If you wish to retrieve a resource via URL and store it in a temporary location, you can do so via the shutil.copyfileobj() and tempfile.NamedTemporaryFile() functions:

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://www.voidspace.org.uk')
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 を見て下さい)。

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 はレスポンスを処理できなかった場合、 URLError を送出します (ふつうの Python API では、組み込み例外の ValueError, TypeError などが送出されますが)。

HTTPError は URLError のサブクラスで 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

サーバーからの全ての HTTP レスポンスは「ステータスコード」の数値を持っています。多くの場合ステータスコードはサーバーがリクエストを実現できなかったことを意味します。デフォルトハンドラーはこれらのレスポンスのいくつかを処理してくれます(例えばレスポンスが「リダイレクション」、つまりクライアントが別の URL を取得するように要求する場合には urllib はこの処理を行ってくれます。) 処理できないものに対しては urlopen は HTTPError を送出します。典型的なエラーには '404' (page not found), '403' (request forbidden) と '401' (authentication required) が含まれます。

See section 10 of RFC 2616 for a reference on all the HTTP error codes.

送出された HTTPError インスタンスは整数の 'code' 属性を持っていて、サーバーによって送られた応答に対応しています。

エラーコード

デフォルトハンドラーはリダイレクト(コードは300番台にあります) を処理し、100--299番台のコードは成功を意味しているので、たいていの場合は400--599番台のエラーコードのみを見るだけですみます。

http.server.BaseHTTPRequestHandler.responses is a useful dictionary of response codes in that shows all the response codes used by RFC 2616. The dictionary is reproduced here for convenience

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

エラーをラップする

HTTPError または URLError が起きたときのために準備しておきたい場合には。二つの基本的なアプローチがあります。私は二つ目のアプローチを好みます。

その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

注釈

except HTTPError が 必ず 最初に来る必要があります、そうしないと except URLError も 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

レスポンスは urlopen (または HTTPError インスタンス) によって返され、 info() と geturl() の二つの便利なメソッドを持っていて、モジュール urllib.response で定義されています。

geturl - これは取得したページの実際の URL を返します。 urlopen (または利用される opener オブジェクト) はリダイレクトに追従するため、有用です。取得したページの URL は要求した URL と同じとは限りません。

info - これは取得したページ (特にサーバからヘッダ)を表す辞書風オブジェクトを返します。これは現在では http.client.HTTPMessage インスタンスです。

Typical headers include 'Content-length', 'Content-type', and so on. See the Quick Reference to HTTP Headers for a useful listing of HTTP headers with brief explanations of their meaning and use.

Openers と Handlers

URL を取得する場合、opener (混乱を招きやすい名前ですが、 urllib.request.OpenerDirector のインスタンス) を利用します。標準的にはデフォルトの opener を - urlopen を通して - 利用していますが、カスタムの opener を作成することもできます。 oppener は 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 認証

ハンドラの作成とインストールを例示するのに、 HTTPBasicAuthHandler を利用してみます。この話題についてのより詳しい議論は -- Basic 認証がどうやって動作するのかの説明も含んでいる Basic Authentication Tutorial を参照して下さい。

認証が必要な場合、サーバは認証を要求するヘッダ (401 のエラーコードとともに) を送ります。これによって認証スキームと 'realm' が指定されます。ヘッダはこのようになっています: WWW-Authenticate: SCHEME realm="REALM" 。

e.g.

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)

注釈

上の例では build_opener に HTTPBasicAuthHandler のみを与えました。デフォルトで opener は普通の状況に適用するためにいくつかのハンドラを備えています -- ProxyHandler (http_proxy 環境変数のようなプロキシ設定がセットされている場合), 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 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() のドキュメンテーションを参照してください。

ソケットとレイヤー

Python はレイヤー化された web 上からリソース取得もサポートしています。 urllib は http.client ライブラリを利用します、 httplib はさらに 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 を参照して下さい。
[5] 私の場合は仕事中にインターネットにアクセスするにはプロキシを利用する必要があります。localhost の URL に対してこのプロキシを経由してアクセスしようとすれば、ブロックされます。IE を proxy を利用するように設定すれば、urllib はその情報を利用します。localhost のサーバでスクリプトをテストしようとすると、urllib がプロキシを利用するのを止めなければいけません。
[6] urllib opener for SSL proxy (CONNECT method): ASPN Cookbook Recipe.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python HOWTO »


Argparse チュートリアル

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

Argparse チュートリアル

author: Tshepang Lekhonkhobe

このチュートリアルでは、argparse を丁寧に説明します。argparse は、Python 標準ライブラリの一部であり、おすすめのコマンドライン引数の解析モジュールです。

注釈

同じタスクを満足するモジュールとして、 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()

下記がこのコードを実行した結果です:

$ python3 prog.py
$ python3 prog.py --help
usage: prog.py [-h]

optional arguments:
  -h, --help  show this help message and exit
$ python3 prog.py --verbose
usage: prog.py [-h]
prog.py: error: unrecognized arguments: --verbose
$ python3 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)

このコードを実行してみましょう:

$ python3 prog.py
usage: prog.py [-h] echo
prog.py: error: the following arguments are required: echo
$ python3 prog.py --help
usage: prog.py [-h] echo

positional arguments:
  echo

optional arguments:
  -h, --help  show this help message and exit
$ python3 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)

修正した結果は以下のようになります:

$ python3 prog.py -h
usage: prog.py [-h] echo

positional arguments:
  echo        echo the string you use here

optional arguments:
  -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)

下記がこのコードを実行した結果です:

$ python3 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)

下記がこのコードを実行した結果です:

$ python3 prog.py 4
16
$ python3 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")

実行してみましょう:

$ python3 prog.py --verbosity 1
verbosity turned on
$ python3 prog.py
$ python3 prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]

optional arguments:
  -h, --help            show this help message and exit
  --verbosity VERBOSITY
                        increase output verbosity
$ python3 prog.py --verbosity
usage: prog.py [-h] [--verbosity VERBOSITY]
prog.py: error: argument --verbosity: expected one argument

こんなことが起こりました:

  • プログラムは、--verbosity が指定された場合はなにかしらを表示し、指定されなければ何も表示をしないように書かれています。
  • optional 引数を指定せずにプログラムを実行したときにエラーにならないことから、このオプションの指定が任意（optional)であることがわかります。注意すべき点として、デフォルトでは、optional 引数が使用されないときは、関連する変数（このケースでは、 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")

実行してみましょう:

$ python3 prog.py --verbose
verbosity turned on
$ python3 prog.py --verbose 1
usage: prog.py [-h] [--verbose]
prog.py: error: unrecognized arguments: 1
$ python3 prog.py --help
usage: prog.py [-h] [--verbose]

optional arguments:
  -h, --help  show this help message and exit
  --verbose   increase output verbosity

こんなことが起こりました:

  • いまや、このオプションは値をとるオプションというよりは、フラグになりました。オプションの名前をその意図に合うように変更しました。新しいキーワード引数 action に "store_true" を値として渡していることに注意してください。これはオプションが指定されると args.verbose に True を代入することを意味しています。もしオプションが指定されなければ代入される値は 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")

上記のプログラムを実行するとこうなります:

$ python3 prog.py -v
verbosity turned on
$ python3 prog.py --help
usage: prog.py [-h] [-v]

optional arguments:
  -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("the square of {} equals {}".format(args.square, answer))
else:
    print(answer)

出力は以下のようになります:

$ python3 prog.py
usage: prog.py [-h] [-v] square
prog.py: error: the following arguments are required: square
$ python3 prog.py 4
16
$ python3 prog.py 4 --verbose
the square of 4 equals 16
$ python3 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("the square of {} equals {}".format(args.square, answer))
elif args.verbosity == 1:
    print("{}^2 == {}".format(args.square, answer))
else:
    print(answer)

実行してみましょう:

$ python3 prog.py 4
16
$ python3 prog.py 4 -v
usage: prog.py [-h] [-v VERBOSITY] square
prog.py: error: argument -v/--verbosity: expected one argument
$ python3 prog.py 4 -v 1
4^2 == 16
$ python3 prog.py 4 -v 2
the square of 4 equals 16
$ python3 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("the square of {} equals {}".format(args.square, answer))
elif args.verbosity == 1:
    print("{}^2 == {}".format(args.square, answer))
else:
    print(answer)

実行してみましょう:

$ python3 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)
$ python3 prog.py 4 -h
usage: prog.py [-h] [-v {0,1,2}] square

positional arguments:
  square                display a square of a given number

optional arguments:
  -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("the square of {} equals {}".format(args.square, answer))
elif args.verbosity == 1:
    print("{}^2 == {}".format(args.square, answer))
else:
    print(answer)

もう一つの action である "count" を紹介します。これは指定されたオプションの出現回数をカウントします:

$ python3 prog.py 4
16
$ python3 prog.py 4 -v
4^2 == 16
$ python3 prog.py 4 -vv
the square of 4 equals 16
$ python3 prog.py 4 --verbosity --verbosity
the square of 4 equals 16
$ python3 prog.py 4 -v 1
usage: prog.py [-h] [-v] square
prog.py: error: unrecognized arguments: 1
$ python3 prog.py 4 -h
usage: prog.py [-h] [-v] square

positional arguments:
  square           display a square of a given number

optional arguments:
  -h, --help       show this help message and exit
  -v, --verbosity  increase output verbosity
$ python3 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("the square of {} equals {}".format(args.square, answer))
elif args.verbosity >= 1:
    print("{}^2 == {}".format(args.square, answer))
else:
    print(answer)

これが結果です:

$ python3 prog.py 4 -vvv
the square of 4 equals 16
$ python3 prog.py 4 -vvvv
the square of 4 equals 16
$ python3 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("the square of {} equals {}".format(args.square, answer))
elif args.verbosity >= 1:
    print("{}^2 == {}".format(args.square, answer))
else:
    print(answer)

もう一つのキーワード引数である default を導入しました。整数値と比較できるように、その値に 0 を設定しました。デフォルトでは、optional 引数が指定されていない場合 None となること、None が整数値と比較できない（よって TypeError 例外となる）ことを思い出してください。

こうなりました:

$ python3 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("{} to the power {} equals {}".format(args.x, args.y, answer))
elif args.verbosity >= 1:
    print("{}^{} == {}".format(args.x, args.y, answer))
else:
    print(answer)

出力:

$ python3 prog.py
usage: prog.py [-h] [-v] x y
prog.py: error: the following arguments are required: x, y
$ python3 prog.py -h
usage: prog.py [-h] [-v] x y

positional arguments:
  x                the base
  y                the exponent

optional arguments:
  -h, --help       show this help message and exit
  -v, --verbosity
$ python3 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("Running '{}'".format(__file__))
if args.verbosity >= 1:
    print("{}^{} == ".format(args.x, args.y), end="")
print(answer)

出力:

$ python3 prog.py 4 2
16
$ python3 prog.py 4 2 -v
4^2 == 16
$ python3 prog.py 4 2 -vv
Running 'prog.py'
4^2 == 16

競合するオプション

ここまでで、 argparse.ArgumentParser インスタンスの二つのメソッドについて学んできました。では三つ目のメソッド add_mutually_exclusive_group() を紹介しましょう。このメソッドでは、互いに競合するオプションを指定することができます。新しい機能がより意味をなすようにプログラムを変更しましょう: --verbose オプションと反対の --quiet オプションを導入します:

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("{} to the power {} equals {}".format(args.x, args.y, answer))
else:
    print("{}^{} == {}".format(args.x, args.y, answer))

プログラムはより簡潔になりましたが、デモのための機能が失われました。ともかく下記が実行結果です:

$ python3 prog.py 4 2
4^2 == 16
$ python3 prog.py 4 2 -q
16
$ python3 prog.py 4 2 -v
4 to the power 2 equals 16
$ python3 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
$ python3 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("{} to the power {} equals {}".format(args.x, args.y, answer))
else:
    print("{}^{} == {}".format(args.x, args.y, answer))

使用方法のテキストが少し変化しました。[-v | -q] は -v または -q のどちらかを使用できるが、同時に両方を使用できないことを意味します:

$ python3 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

optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose
  -q, --quiet

結び

argparse モジュールはここで学んだことより多くの機能を提供します。モジュールのドキュメントはとても詳細で、綿密で、そしてたくさんの例があります。このチュートリアルの体験したことで、気がめいることなくそれらの他の機能を会得できるに違いありません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python HOWTO »


ipaddressモジュールの紹介

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

ipaddressモジュールの紹介

author: | Peter Moody
author: | Nick Coghlan

概要

このドキュメントは ipaddress モジュールへのやさしい入門を提供するのが目的です。これは主にまだIPネットワーキングの用語に詳しくないユーザーを対象としていますが、ipaddress がどのようにIPネットワークアドレス処理の概念を表現しているかをざっと見るのにも役立つかもしれません。

アドレス/ネットワーク/インターフェースオブジェクトの作成

ipaddress はIPアドレスを検査したり操作したりするためのモジュールであるため、まずはオブジェクトを作成したほうが良いでしょう。文字列および整数を使用して ipaddress を使用してオブジェクトを作成できます。

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)

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python HOWTO »


Argument Clinic How-To

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

Argument Clinic How-To

著者: Larry Hastings

概要

Argument Clinic は CPython の C ファイルのプリプロセッサです。builtin の中の、退屈な引数解析のコードを自動化するのが目的です。このドキュメントでは、C関数を Argument Clinic 化する方法を示し、さらに高度な Argument Clinic の利用方法について説明します。

現在のところ、Argument Clinic は CPython の内部専用の扱いです。CPython の外にあるファイルはサポートしておらず、将来のバージョンでの後方互換性を保証しません。言い換えると、CPython の外の C 拡張をメンテナンスしている場合、Argument Clinic を試してみることはできますが、次のバージョンの CPython の Argument Clinic では互換性が無くなりそのコードが動かなくなる 可能性があります 。

Argument Clinic の目的

Argument Clinic の第一目標は、CPython の中の全ての引数解析のためのコードを引き継ぐことです。ある関数を Argument Clinic を使うように変更すると、その関数は一切の引数解析を行わなくなります。Argument Clinic が生成するコードがブラックボックスになり、CPython がそのブラックボックスの先頭を呼び出し、最後にその関数のコードが呼ばれます。引数の PyObject *args (と PyObject *kwargs) は暗黙的に、必要な型のC言語の変数に変換されます。

Argument Clinic の第一目標を達成するためには、使いやすくなければなりません。現在、CPython の引数解析ライブラリを利用するのは面倒で、とても多くの場所で冗長な情報のメンテナンスを必要とします。Argument Clinic を使うことで DRY を実現できます。

もちろん、新たな問題を持ち込むことなしに、自分の問題を解決してくれるのでなければ、誰も Argument Clinic を使いたいとは思わないでしょう。なので、正しいコードを生成することは Argument Clinic にとって最重要です。生成したコードによって速度が大きく低下することがあってはいけないし、速くなるならより良いです。(最終的には、Argument Clinic は大幅な高速化を可能にするはずです。Argument Clinic が、汎用的な CPython の引数解析ライブラリを呼び出す代わりに、オーダーメイドの引数解析コードを生成するようにできるからです。これにより可能な限り最速の引数解析が可能になるでしょう！)

加えて、Argument Clinic は全ての引数解析の方式に対応できるように柔軟でなければなりません。Python の幾つかの関数はとても特殊な引数の解釈を行います。Argument Clinic の目標はその全てをサポートすることです。

最後に、もともとの Argument Clinic の目的は CPython 組み込み関数に "シグネチャ" の introspection を提供することでした。今までは、組み込み関数に対して introspection する関数で問い合わせると例外が発生していました。Argument Clinic によってこれは過去の事になりました。

Argument Clinic を使うにあたって1つ覚えておかないといけないアイデアがあります: それは「より多くの情報を与えれば、より良い仕事ができるようになる」ということです。 Argument Clinic は今のところはまだ比較的シンプルです。 しかし、将来の進化により、与えられた情報を元により洗練された賢いことができるようになるでしょう。

基本的な概念と使用法

Argument Clinic は CPython とともに配布されています。その中の Tools/clinic/clinic.py を見つけることができるでしょう。 そのスクリプトを、引数にCファイルを指定して実行すると:

$ python3 Tools/clinic/clinic.py foo.c

Argument Clinic は指定されたファイルをスキャンし、次の行と全く同じ行を探します:

/*[clinic input]

その行を見つけたら、今度は正確に次のような行を見つけるまで、すべてを読み込みます:

[clinic start generated code]*/

これらの2つの行の間のすべての行が Argument Clinic への入力になります。これらのコメント行の開始と終了も含めたすべての行が、 Argument Clinic "ブロック" と呼ばれます。

Argument Clinic はその block をパースすると、出力を生成します。 その出力は、そのCソースファイルの該当する block の直後に挿入され、チェックサムを含むコメントで終了します。 その結果 Argument Clinick block は次のようになります:

/*[clinic input]
... clinic input goes here ...
[clinic start generated code]*/
... clinic output goes here ...
/*[clinic end generated code: checksum=...]*/

Argument Clinic を同じファイルに対して2度実行した場合、Argument Clinic は古い出力を新しい出力で上書きしてチェックサムも更新します。 しかし、入力が変更されていない場合、出力も変化しません。

Argument Clinick block の出力部分を修正してはいけません。 出力が望みどおりになるまで、入力を修正してください。 (出力部分に対する修正は、次に Argument Clinic が新しい出力を書いたときに失われてしまいます。 チェックサムの目的は出力部分に対する修正を検出するためです。)

混乱を避けるために、 Argument Clinic で利用する用語を定義しておきます。

  • コメントの最初の行 (/*[clinic input]) は スタートライン です。
  • Argument Clinic を実行する前の状態のコメントの最終行 ([clinic start generated code]*/) は エンドライン です。
  • 最後の行 (/*[clinic end generated code: checksum=...]*/) は チェックサムライン です。
  • スタートラインとエンドラインの間が インプット です。
  • エンドラインとチェックサムラインの間が アウトプット です。
  • スタートラインからエンドラインまで、その2行を含めた全体が ブロック です。 (Argument Clinic がまだ正常に処理を実行できてないブロックは、アウトプットとチェックサムラインをまだ持っていませんが、それもブロックとして扱います。)

関数を変換してみよう

Argument Clinic の動作について把握する一番の方法は、1つの関数で実際に試してみることです。 なのでここでは、1つの関数で試すための最小限の手順を説明します。 CPythonのコードにコミットする場合は、あとで出てくるもっと強力な機能 ("return converter" や "self converter" など) を使った変換をする必要があることに気をつけてください。 ここでは学習目的でシンプルな手順だけにとどめます。

飛び込もう！

  1. まずCPythonの最新版のチェックアウトを用意してください。

  2. Find a Python builtin that calls either PyArg_ParseTuple() or PyArg_ParseTupleAndKeywords(), and hasn't been converted to work with Argument Clinic yet. For my example I'm using _pickle.Pickler.dump().

  3. PyArg_Parse 関数が以下のいずれかのフォーマット単位を使っていた場合:

    O&
O!
es
es#
et
et#

    あるいは PyArg_ParseTuple() の呼び出しを複数持っていた場合、別の関数を選びましょう。Argument Clinic はこれらすべてのケースを サポートしています。 ですが、これは高度な話題になります。最初の関数にはシンプルなものを選びましょう。

    また、その関数が、同一の引数が複数の型を持つ場合に対応するために PyArg_ParseTuple() か PyArg_ParseTupleAndKeyword() の呼び出しを複数持っていたり、 PyArg_Parse 関数を利用していないようなら、その関数は Argument Clinic に向いていません。 Argument Clinic はジェネリック関数やポリモーフィックな引数をサポートしていません。

  4. その関数の上に次の定型文を追加し、ブロックを作ります:

    /*[clinic input]
[clinic start generated code]*/

  5. Cut the docstring and paste it in between the [clinic] lines, removing all the junk that makes it a properly quoted C string. When you're done you should have just the text, based at the left margin, with no line wider than 80 characters. (Argument Clinic will preserve indents inside the docstring.)

    If the old docstring had a first line that looked like a function signature, throw that line away. (The docstring doesn't need it anymore—when you use help() on your builtin in the future, the first line will be built automatically based on the function's signature.)

    例:

    /*[clinic input]
Write a pickled representation of obj to the open file.
[clinic start generated code]*/

  6. If your docstring doesn't have a "summary" line, Argument Clinic will complain. So let's make sure it has one. The "summary" line should be a paragraph consisting of a single 80-column line at the beginning of the docstring.

    (Our example docstring consists solely of a summary line, so the sample code doesn't have to change for this step.)

  7. Above the docstring, enter the name of the function, followed by a blank line. This should be the Python name of the function, and should be the full dotted path to the function—it should start with the name of the module, include any sub-modules, and if the function is a method on a class it should include the class name too.

    例:

    /*[clinic input]
_pickle.Pickler.dump

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

  8. If this is the first time that module or class has been used with Argument Clinic in this C file, you must declare the module and/or class. Proper Argument Clinic hygiene prefers declaring these in a separate block somewhere near the top of the C file, in the same way that include files and statics go at the top. (In our sample code we'll just show the two blocks next to each other.)

    The name of the class and module should be the same as the one seen by Python. Check the name defined in the PyModuleDef or PyTypeObject as appropriate.

    When you declare a class, you must also specify two aspects of its type in C: the type declaration you'd use for a pointer to an instance of this class, and a pointer to the PyTypeObject for this class.

    例:

    /*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/

/*[clinic input]
_pickle.Pickler.dump

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

  9. Declare each of the parameters to the function. Each parameter should get its own line. All the parameter lines should be indented from the function name and the docstring.

    The general form of these parameter lines is as follows:

    name_of_parameter: converter

    If the parameter has a default value, add that after the converter:

    name_of_parameter: converter = default_value

    Argument Clinic's support for "default values" is quite sophisticated; please see the section below on default values for more information.

    Add a blank line below the parameters.

    What's a "converter"? It establishes both the type of the variable used in C, and the method to convert the Python value into a C value at runtime. For now you're going to use what's called a "legacy converter"—a convenience syntax intended to make porting old code into Argument Clinic easier.

    For each parameter, copy the "format unit" for that parameter from the PyArg_Parse() format argument and specify that as its converter, as a quoted string. ("format unit" is the formal name for the one-to-three character substring of the format parameter that tells the argument parsing function what the type of the variable is and how to convert it. For more on format units please see 引数の解釈と値の構築.)

    For multicharacter format units like z#, use the entire two-or-three character string.

    例:

     /*[clinic input]
 module _pickle
 class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
 [clinic start generated code]*/

 /*[clinic input]
 _pickle.Pickler.dump

    obj: 'O'

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

  10. If your function has | in the format string, meaning some parameters have default values, you can ignore it. Argument Clinic infers which parameters are optional based on whether or not they have default values.

    If your function has $ in the format string, meaning it takes keyword-only arguments, specify * on a line by itself before the first keyword-only argument, indented the same as the parameter lines.

    (_pickle.Pickler.dump has neither, so our sample is unchanged.)

  11. If the existing C function calls PyArg_ParseTuple() (as opposed to PyArg_ParseTupleAndKeywords()), then all its arguments are positional-only.

    To mark all parameters as positional-only in Argument Clinic, add a / on a line by itself after the last parameter, indented the same as the parameter lines.

    Currently this is all-or-nothing; either all parameters are positional-only, or none of them are. (In the future Argument Clinic may relax this restriction.)

    例:

    /*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/

/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

  12. It's helpful to write a per-parameter docstring for each parameter. But per-parameter docstrings are optional; you can skip this step if you prefer.

    Here's how to add a per-parameter docstring. The first line of the per-parameter docstring must be indented further than the parameter definition. The left margin of this first line establishes the left margin for the whole per-parameter docstring; all the text you write will be outdented by this amount. You can write as much text as you like, across multiple lines if you wish.

    例:

    /*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/

/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

  13. Save and close the file, then run Tools/clinic/clinic.py on it. With luck everything worked---your block now has output, and a .c.h file has been generated! Reopen the file in your text editor to see:

    /*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

static PyObject *
_pickle_Pickler_dump(PicklerObject *self, PyObject *obj)
/*[clinic end generated code: output=87ecad1261e02ac7 input=552eb1c0f52260d9]*/

    Obviously, if Argument Clinic didn't produce any output, it's because it found an error in your input. Keep fixing your errors and retrying until Argument Clinic processes your file without complaint.

    For readability, most of the glue code has been generated to a .c.h file. You'll need to include that in your original .c file, typically right after the clinic module block:

    #include "clinic/_pickle.c.h"

  14. Double-check that the argument-parsing code Argument Clinic generated looks basically the same as the existing code.

    First, ensure both places use the same argument-parsing function. The existing code must call either PyArg_ParseTuple() or PyArg_ParseTupleAndKeywords(); ensure that the code generated by Argument Clinic calls the exact same function.

    Second, the format string passed in to PyArg_ParseTuple() or PyArg_ParseTupleAndKeywords() should be exactly the same as the hand-written one in the existing function, up to the colon or semi-colon.

    (Argument Clinic always generates its format strings with a : followed by the name of the function. If the existing code's format string ends with ;, to provide usage help, this change is harmless—don't worry about it.)

    Third, for parameters whose format units require two arguments (like a length variable, or an encoding string, or a pointer to a conversion function), ensure that the second argument is exactly the same between the two invocations.

    Fourth, inside the output portion of the block you'll find a preprocessor macro defining the appropriate static PyMethodDef structure for this builtin:

    #define __PICKLE_PICKLER_DUMP_METHODDEF    \
{"dump", (PyCFunction)__pickle_Pickler_dump, METH_O, __pickle_Pickler_dump__doc__},

    This static structure should be exactly the same as the existing static PyMethodDef structure for this builtin.

    If any of these items differ in any way, adjust your Argument Clinic function specification and rerun Tools/clinic/clinic.py until they are the same.

  15. Notice that the last line of its output is the declaration of your "impl" function. This is where the builtin's implementation goes. Delete the existing prototype of the function you're modifying, but leave the opening curly brace. Now delete its argument parsing code and the declarations of all the variables it dumps the arguments into. Notice how the Python arguments are now arguments to this impl function; if the implementation used different names for these variables, fix it.

    Let's reiterate, just because it's kind of weird. Your code should now look like this:

    static return_type
your_function_impl(...)
/*[clinic end generated code: checksum=...]*/
{
...

    Argument Clinic generated the checksum line and the function prototype just above it. You should write the opening (and closing) curly braces for the function, and the implementation inside.

    例:

    /*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/
/*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/

/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

PyDoc_STRVAR(__pickle_Pickler_dump__doc__,
"Write a pickled representation of obj to the open file.\n"
"\n"
...
static PyObject *
_pickle_Pickler_dump_impl(PicklerObject *self, PyObject *obj)
/*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/
{
    /* Check whether the Pickler was initialized correctly (issue3664).
       Developers often forget to call __init__() in their subclasses, which
       would trigger a segfault without this check. */
    if (self->write == NULL) {
        PyErr_Format(PicklingError,
                     "Pickler.__init__() was not called by %s.__init__()",
                     Py_TYPE(self)->tp_name);
        return NULL;
    }

    if (_Pickler_ClearBuffer(self) < 0)
        return NULL;

    ...

  16. Remember the macro with the PyMethodDef structure for this function? Find the existing PyMethodDef structure for this function and replace it with a reference to the macro. (If the builtin is at module scope, this will probably be very near the end of the file; if the builtin is a class method, this will probably be below but relatively near to the implementation.)

    Note that the body of the macro contains a trailing comma. So when you replace the existing static PyMethodDef structure with the macro, don't add a comma to the end.

    例:

    static struct PyMethodDef Pickler_methods[] = {
    __PICKLE_PICKLER_DUMP_METHODDEF
    __PICKLE_PICKLER_CLEAR_MEMO_METHODDEF
    {NULL, NULL}                /* sentinel */
};

  17. Compile, then run the relevant portions of the regression-test suite. This change should not introduce any new compile-time warnings or errors, and there should be no externally-visible change to Python's behavior.

    Well, except for one difference: inspect.signature() run on your function should now provide a valid signature!

    Congratulations, you've ported your first function to work with Argument Clinic!

高度なトピック

Now that you've had some experience working with Argument Clinic, it's time for some advanced topics.

シンボルのデフォルト値

The default value you provide for a parameter can't be any arbitrary expression. Currently the following are explicitly supported:

  • 数値定数 (整数と浮動小数)
  • 文字列定数
  • True、False、None
  • Simple symbolic constants like sys.maxsize, which must start with the name of the module

In case you're curious, this is implemented in from_builtin() in Lib/inspect.py.

(In the future, this may need to get even more elaborate, to allow full expressions like CONSTANT - 1.)

Argument Clinic が生成した関数と変数をリネームする

Argument Clinic automatically names the functions it generates for you. Occasionally this may cause a problem, if the generated name collides with the name of an existing C function. There's an easy solution: override the names used for the C functions. Just add the keyword "as" to your function declaration line, followed by the function name you wish to use. Argument Clinic will use that function name for the base (generated) function, then add "_impl" to the end and use that for the name of the impl function.

For example, if we wanted to rename the C function names generated for pickle.Pickler.dump, it'd look like this:

/*[clinic input]
pickle.Pickler.dump as pickler_dumper

...

The base function would now be named pickler_dumper(), and the impl function would now be named pickler_dumper_impl().

Similarly, you may have a problem where you want to give a parameter a specific Python name, but that name may be inconvenient in C. Argument Clinic allows you to give a parameter different names in Python and in C, using the same "as" syntax:

/*[clinic input]
pickle.Pickler.dump

    obj: object
    file as file_obj: object
    protocol: object = NULL
    *
    fix_imports: bool = True

Here, the name used in Python (in the signature and the keywords array) would be file, but the C variable would be named file_obj.

You can use this to rename the self parameter too!

PyArg_UnpackTuple による関数の変換

To convert a function parsing its arguments with PyArg_UnpackTuple(), simply write out all the arguments, specifying each as an object. You may specify the type argument to cast the type as appropriate. All arguments should be marked positional-only (add a / on a line by itself after the last argument).

Currently the generated code will use PyArg_ParseTuple(), but this will change soon.

オプション群

Some legacy functions have a tricky approach to parsing their arguments: they count the number of positional arguments, then use a switch statement to call one of several different PyArg_ParseTuple() calls depending on how many positional arguments there are. (These functions cannot accept keyword-only arguments.) This approach was used to simulate optional arguments back before PyArg_ParseTupleAndKeywords() was created.

While functions using this approach can often be converted to use PyArg_ParseTupleAndKeywords(), optional arguments, and default values, it's not always possible. Some of these legacy functions have behaviors PyArg_ParseTupleAndKeywords() doesn't directly support. The most obvious example is the builtin function range(), which has an optional argument on the left side of its required argument! Another example is curses.window.addch(), which has a group of two arguments that must always be specified together. (The arguments are called x and y; if you call the function passing in x, you must also pass in y—and if you don't pass in x you may not pass in y either.)

In any case, the goal of Argument Clinic is to support argument parsing for all existing CPython builtins without changing their semantics. Therefore Argument Clinic supports this alternate approach to parsing, using what are called optional groups. Optional groups are groups of arguments that must all be passed in together. They can be to the left or the right of the required arguments. They can only be used with positional-only parameters.

注釈

Optional groups are only intended for use when converting functions that make multiple calls to PyArg_ParseTuple()! Functions that use any other approach for parsing arguments should almost never be converted to Argument Clinic using optional groups. Functions using optional groups currently cannot have accurate signatures in Python, because Python just doesn't understand the concept. Please avoid using optional groups wherever possible.

To specify an optional group, add a [ on a line by itself before the parameters you wish to group together, and a ] on a line by itself after these parameters. As an example, here's how curses.window.addch uses optional groups to make the first two parameters and the last parameter optional:

/*[clinic input]

curses.window.addch

    [
    x: int
      X-coordinate.
    y: int
      Y-coordinate.
    ]

    ch: object
      Character to add.

    [
    attr: long
      Attributes for the character.
    ]
    /

...

注釈:

  • For every optional group, one additional parameter will be passed into the impl function representing the group. The parameter will be an int named group_{direction}_{number}, where {direction} is either right or left depending on whether the group is before or after the required parameters, and {number} is a monotonically increasing number (starting at 1) indicating how far away the group is from the required parameters. When the impl is called, this parameter will be set to zero if this group was unused, and set to non-zero if this group was used. (By used or unused, I mean whether or not the parameters received arguments in this invocation.)
  • If there are no required arguments, the optional groups will behave as if they're to the right of the required arguments.
  • In the case of ambiguity, the argument parsing code favors parameters on the left (before the required parameters).
  • Optional groups can only contain positional-only parameters.
  • Optional groups are only intended for legacy code. Please do not use optional groups for new code.

Using real Argument Clinic converters, instead of "legacy converters"

To save time, and to minimize how much you need to learn to achieve your first port to Argument Clinic, the walkthrough above tells you to use "legacy converters". "Legacy converters" are a convenience, designed explicitly to make porting existing code to Argument Clinic easier. And to be clear, their use is acceptable when porting code for Python 3.4.

However, in the long term we probably want all our blocks to use Argument Clinic's real syntax for converters. Why? A couple reasons:

  • The proper converters are far easier to read and clearer in their intent.
  • There are some format units that are unsupported as "legacy converters", because they require arguments, and the legacy converter syntax doesn't support specifying arguments.
  • In the future we may have a new argument parsing library that isn't restricted to what PyArg_ParseTuple() supports; this flexibility won't be available to parameters using legacy converters.

Therefore, if you don't mind a little extra effort, please use the normal converters instead of legacy converters.

In a nutshell, the syntax for Argument Clinic (non-legacy) converters looks like a Python function call. However, if there are no explicit arguments to the function (all functions take their default values), you may omit the parentheses. Thus bool and bool() are exactly the same converters.

All arguments to Argument Clinic converters are keyword-only. All Argument Clinic converters accept the following arguments:

c_default
The default value for this parameter when defined in C. Specifically, this will be the initializer for the variable declared in the "parse function". See the section on default values for how to use this. Specified as a string.
annotation
The annotation value for this parameter. Not currently supported, because PEP 8 mandates that the Python library may not use annotations.

In addition, some converters accept additional arguments. Here is a list of these arguments, along with their meanings:

accept

A set of Python types (and possibly pseudo-types); this restricts the allowable Python argument to values of these types. (This is not a general-purpose facility; as a rule it only supports specific lists of types as shown in the legacy converter table.)

To accept None, add NoneType to this set.

bitwise
Only supported for unsigned integers. The native integer value of this Python argument will be written to the parameter without any range checking, even for negative values.
converter
Only supported by the object converter. Specifies the name of a C "converter function" to use to convert this object to a native type.
encoding
Only supported for strings. Specifies the encoding to use when converting this string from a Python str (Unicode) value into a C char * value.
subclass_of
Only supported for the object converter. Requires that the Python value be a subclass of a Python type, as expressed in C.
type
Only supported for the object and self converters. Specifies the C type that will be used to declare the variable. Default value is "PyObject *".
zeroes
Only supported for strings. If true, embedded NUL bytes ('\\0') are permitted inside the value. The length of the string will be passed in to the impl function, just after the string parameter, as a parameter named <parameter_name>_length.

Please note, not every possible combination of arguments will work. Usually these arguments are implemented by specific PyArg_ParseTuple format units, with specific behavior. For example, currently you cannot call unsigned_short without also specifying bitwise=True. Although it's perfectly reasonable to think this would work, these semantics don't map to any existing format unit. So Argument Clinic doesn't support it. (Or, at least, not yet.)

Below is a table showing the mapping of legacy converters into real Argument Clinic converters. On the left is the legacy converter, on the right is the text you'd replace it with.

'B' | unsigned_char(bitwise=True)
'b' | unsigned_char
'c' | char
'C' | int(accept={str})
'd' | double
'D' | Py_complex
'es' | str(encoding='name_of_encoding')
'es#' | str(encoding='name_of_encoding', zeroes=True)
'et' | str(encoding='name_of_encoding', accept={bytes, bytearray, str})
'et#' | str(encoding='name_of_encoding', accept={bytes, bytearray, str}, zeroes=True)
'f' | float
'h' | short
'H' | unsigned_short(bitwise=True)
'i' | int
'I' | unsigned_int(bitwise=True)
'k' | unsigned_long(bitwise=True)
'K' | unsigned_long_long(bitwise=True)
'l' | long
'L' | long long
'n' | Py_ssize_t
'O' | object
'O!' | object(subclass_of='&PySomething_Type')
'O&' | object(converter='name_of_c_function')
'p' | bool
'S' | PyBytesObject
's' | str
's#' | str(zeroes=True)
's*' | Py_buffer(accept={buffer, str})
'U' | unicode
'u' | Py_UNICODE
'u#' | Py_UNICODE(zeroes=True)
'w*' | Py_buffer(accept={rwbuffer})
'Y' | PyByteArrayObject
'y' | str(accept={bytes})
'y#' | str(accept={robuffer}, zeroes=True)
'y*' | Py_buffer
'Z' | Py_UNICODE(accept={str, NoneType})
'Z#' | Py_UNICODE(accept={str, NoneType}, zeroes=True)
'z' | str(accept={str, NoneType})
'z#' | str(accept={str, NoneType}, zeroes=True)
'z*' | Py_buffer(accept={buffer, str, NoneType})

As an example, here's our sample pickle.Pickler.dump using the proper converter:

/*[clinic input]
pickle.Pickler.dump

    obj: object
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

Argument Clinic will show you all the converters it has available. For each converter it'll show you all the parameters it accepts, along with the default value for each parameter. Just run Tools/clinic/clinic.py --converters to see the full list.

Py_buffer

When using the Py_buffer converter (or the 's*', 'w*', '*y', or 'z*' legacy converters), you must not call PyBuffer_Release() on the provided buffer. Argument Clinic generates code that does it for you (in the parsing function).

Advanced converters

Remember those format units you skipped for your first time because they were advanced? Here's how to handle those too.

The trick is, all those format units take arguments—either conversion functions, or types, or strings specifying an encoding. (But "legacy converters" don't support arguments. That's why we skipped them for your first function.) The argument you specified to the format unit is now an argument to the converter; this argument is either converter (for O&), subclass_of (for O!), or encoding (for all the format units that start with e).

When using subclass_of, you may also want to use the other custom argument for object(): type, which lets you set the type actually used for the parameter. For example, if you want to ensure that the object is a subclass of PyUnicode_Type, you probably want to use the converter object(type='PyUnicodeObject *', subclass_of='&PyUnicode_Type').

One possible problem with using Argument Clinic: it takes away some possible flexibility for the format units starting with e. When writing a PyArg_Parse call by hand, you could theoretically decide at runtime what encoding string to pass in to PyArg_ParseTuple(). But now this string must be hard-coded at Argument-Clinic-preprocessing-time. This limitation is deliberate; it made supporting this format unit much easier, and may allow for future optimizations. This restriction doesn't seem unreasonable; CPython itself always passes in static hard-coded encoding strings for parameters whose format units start with e.

引数のデフォルト値

Default values for parameters can be any of a number of values. At their simplest, they can be string, int, or float literals:

foo: str = "abc"
bar: int = 123
bat: float = 45.6

They can also use any of Python's built-in constants:

yep:  bool = True
nope: bool = False
nada: object = None

There's also special support for a default value of NULL, and for simple expressions, documented in the following sections.

NULL デフォルト値

For string and object parameters, you can set them to None to indicate that there's no default. However, that means the C variable will be initialized to Py_None. For convenience's sakes, there's a special value called NULL for just this reason: from Python's perspective it behaves like a default value of None, but the C variable is initialized with NULL.

デフォルト値として指定された式

The default value for a parameter can be more than just a literal value. It can be an entire expression, using math operators and looking up attributes on objects. However, this support isn't exactly simple, because of some non-obvious semantics.

Consider the following example:

foo: Py_ssize_t = sys.maxsize - 1

sys.maxsize can have different values on different platforms. Therefore Argument Clinic can't simply evaluate that expression locally and hard-code it in C. So it stores the default in such a way that it will get evaluated at runtime, when the user asks for the function's signature.

What namespace is available when the expression is evaluated? It's evaluated in the context of the module the builtin came from. So, if your module has an attribute called "max_widgets", you may simply use it:

foo: Py_ssize_t = max_widgets

If the symbol isn't found in the current module, it fails over to looking in sys.modules. That's how it can find sys.maxsize for example. (Since you don't know in advance what modules the user will load into their interpreter, it's best to restrict yourself to modules that are preloaded by Python itself.)

Evaluating default values only at runtime means Argument Clinic can't compute the correct equivalent C default value. So you need to tell it explicitly. When you use an expression, you must also specify the equivalent expression in C, using the c_default parameter to the converter:

foo: Py_ssize_t(c_default="PY_SSIZE_T_MAX - 1") = sys.maxsize - 1

Another complication: Argument Clinic can't know in advance whether or not the expression you supply is valid. It parses it to make sure it looks legal, but it can't actually know. You must be very careful when using expressions to specify values that are guaranteed to be valid at runtime!

Finally, because expressions must be representable as static C values, there are many restrictions on legal expressions. Here's a list of Python features you're not permitted to use:

  • 関数呼び出し
  • インライン if 文 (3 if foo else 5).
  • シークエンスの自動アンパック (*[1, 2, 3]).
  • List/set/dict 内包表記とジェネレータ式
  • Tuple/list/set/dict literals.

Using a return converter

By default the impl function Argument Clinic generates for you returns PyObject *. But your C function often computes some C type, then converts it into the PyObject * at the last moment. Argument Clinic handles converting your inputs from Python types into native C types—why not have it convert your return value from a native C type into a Python type too?

That's what a "return converter" does. It changes your impl function to return some C type, then adds code to the generated (non-impl) function to handle converting that value into the appropriate PyObject *.

The syntax for return converters is similar to that of parameter converters. You specify the return converter like it was a return annotation on the function itself. Return converters behave much the same as parameter converters; they take arguments, the arguments are all keyword-only, and if you're not changing any of the default arguments you can omit the parentheses.

(If you use both "as" and a return converter for your function, the "as" should come before the return converter.)

There's one additional complication when using return converters: how do you indicate an error has occurred? Normally, a function returns a valid (non-NULL) pointer for success, and NULL for failure. But if you use an integer return converter, all integers are valid. How can Argument Clinic detect an error? Its solution: each return converter implicitly looks for a special value that indicates an error. If you return that value, and an error has been set (PyErr_Occurred() returns a true value), then the generated code will propagate the error. Otherwise it will encode the value you return like normal.

Currently Argument Clinic supports only a few return converters:

bool
int
unsigned int
long
unsigned int
size_t
Py_ssize_t
float
double
DecodeFSDefault

None of these take parameters. For the first three, return -1 to indicate error. For DecodeFSDefault, the return type is const char *; return a NULL pointer to indicate an error.

(There's also an experimental NoneType converter, which lets you return Py_None on success or NULL on failure, without having to increment the reference count on Py_None. I'm not sure it adds enough clarity to be worth using.)

To see all the return converters Argument Clinic supports, along with their parameters (if any), just run Tools/clinic/clinic.py --converters for the full list.

既存関数の複製

If you have a number of functions that look similar, you may be able to use Clinic's "clone" feature. When you clone an existing function, you reuse:

  • its parameters, including
    • 名前、
    • コンバータと全引数、
    • デフォルト値、
    • 引数ごとのドックストリング、
    • 種類 (位置専用、位置またはキーワード、キーワード専用)、
  • return コンバータ

The only thing not copied from the original function is its docstring; the syntax allows you to specify a new docstring.

Here's the syntax for cloning a function:

/*[clinic input]
module.class.new_function [as c_basename] = module.class.existing_function

Docstring for new_function goes here.
[clinic start generated code]*/

(The functions can be in different modules or classes. I wrote module.class in the sample just to illustrate that you must use the full path to both functions.)

Sorry, there's no syntax for partially-cloning a function, or cloning a function then modifying it. Cloning is an all-or nothing proposition.

Also, the function you are cloning from must have been previously defined in the current file.

Python コードの呼び出し

The rest of the advanced topics require you to write Python code which lives inside your C file and modifies Argument Clinic's runtime state. This is simple: you simply define a Python block.

A Python block uses different delimiter lines than an Argument Clinic function block. It looks like this:

/*[python input]
# python code goes here
[python start generated code]*/

All the code inside the Python block is executed at the time it's parsed. All text written to stdout inside the block is redirected into the "output" after the block.

As an example, here's a Python block that adds a static integer variable to the C code:

/*[python input]
print('static int __ignored_unused_variable__ = 0;')
[python start generated code]*/
static int __ignored_unused_variable__ = 0;
/*[python checksum:...]*/

"self converter" の利用

Argument Clinic automatically adds a "self" parameter for you using a default converter. It automatically sets the type of this parameter to the "pointer to an instance" you specified when you declared the type. However, you can override Argument Clinic's converter and specify one yourself. Just add your own self parameter as the first parameter in a block, and ensure that its converter is an instance of self_converter or a subclass thereof.

What's the point? This lets you override the type of self, or give it a different default name.

How do you specify the custom type you want to cast self to? If you only have one or two functions with the same type for self, you can directly use Argument Clinic's existing self converter, passing in the type you want to use as the type parameter:

/*[clinic input]

_pickle.Pickler.dump

  self: self(type="PicklerObject *")
  obj: object
  /

Write a pickled representation of the given object to the open file.
[clinic start generated code]*/

On the other hand, if you have a lot of functions that will use the same type for self, it's best to create your own converter, subclassing self_converter but overwriting the type member:

/*[python input]
class PicklerObject_converter(self_converter):
    type = "PicklerObject *"
[python start generated code]*/

/*[clinic input]

_pickle.Pickler.dump

  self: PicklerObject
  obj: object
  /

Write a pickled representation of the given object to the open file.
[clinic start generated code]*/

カスタムコンバータを書く

As we hinted at in the previous section... you can write your own converters! A converter is simply a Python class that inherits from CConverter. The main purpose of a custom converter is if you have a parameter using the O& format unit—parsing this parameter means calling a PyArg_ParseTuple() "converter function".

Your converter class should be named *something*_converter. If the name follows this convention, then your converter class will be automatically registered with Argument Clinic; its name will be the name of your class with the _converter suffix stripped off. (This is accomplished with a metaclass.)

You shouldn't subclass CConverter.__init__. Instead, you should write a converter_init() function. converter_init() always accepts a self parameter; after that, all additional parameters must be keyword-only. Any arguments passed in to the converter in Argument Clinic will be passed along to your converter_init().

There are some additional members of CConverter you may wish to specify in your subclass. Here's the current list:

type
The C type to use for this variable. type should be a Python string specifying the type, e.g. int. If this is a pointer type, the type string should end with ' *'.
default
The Python default value for this parameter, as a Python value. Or the magic value unspecified if there is no default.
py_default
default as it should appear in Python code, as a string. Or None if there is no default.
c_default
default as it should appear in C code, as a string. Or None if there is no default.
c_ignored_default
The default value used to initialize the C variable when there is no default, but not specifying a default may result in an "uninitialized variable" warning. This can easily happen when using option groups—although properly-written code will never actually use this value, the variable does get passed in to the impl, and the C compiler will complain about the "use" of the uninitialized value. This value should always be a non-empty string.
converter
The name of the C converter function, as a string.
impl_by_reference
A boolean value. If true, Argument Clinic will add a & in front of the name of the variable when passing it into the impl function.
parse_by_reference
A boolean value. If true, Argument Clinic will add a & in front of the name of the variable when passing it into PyArg_ParseTuple().

Here's the simplest example of a custom converter, from Modules/zlibmodule.c:

/*[python input]

class ssize_t_converter(CConverter):
    type = 'Py_ssize_t'
    converter = 'ssize_t_converter'

[python start generated code]*/
/*[python end generated code: output=da39a3ee5e6b4b0d input=35521e4e733823c7]*/

This block adds a converter to Argument Clinic named ssize_t. Parameters declared as ssize_t will be declared as type Py_ssize_t, and will be parsed by the 'O&' format unit, which will call the ssize_t_converter converter function. ssize_t variables automatically support default values.

More sophisticated custom converters can insert custom C code to handle initialization and cleanup. You can see more examples of custom converters in the CPython source tree; grep the C files for the string CConverter.

カスタム return コンバータを書く

Writing a custom return converter is much like writing a custom converter. Except it's somewhat simpler, because return converters are themselves much simpler.

Return converters must subclass CReturnConverter. There are no examples yet of custom return converters, because they are not widely used yet. If you wish to write your own return converter, please read Tools/clinic/clinic.py, specifically the implementation of CReturnConverter and all its subclasses.

METH_O と METH_NOARGS

To convert a function using METH_O, make sure the function's single argument is using the object converter, and mark the arguments as positional-only:

/*[clinic input]
meth_o_sample

     argument: object
     /
[clinic start generated code]*/

To convert a function using METH_NOARGS, just don't specify any arguments.

You can still use a self converter, a return converter, and specify a type argument to the object converter for METH_O.

tp_new と tp_init functions

You can convert tp_new and tp_init functions. Just name them __new__ or __init__ as appropriate. Notes:

  • The function name generated for __new__ doesn't end in __new__ like it would by default. It's just the name of the class, converted into a valid C identifier.
  • No PyMethodDef #define is generated for these functions.
  • __init__ functions return int, not PyObject *.
  • Use the docstring as the class docstring.
  • Although __new__ and __init__ functions must always accept both the args and kwargs objects, when converting you may specify any signature for these functions that you like. (If your function doesn't support keywords, the parsing function generated will throw an exception if it receives any.)

Clinic 出力の変更とリダイレクト

It can be inconvenient to have Clinic's output interspersed with your conventional hand-edited C code. Luckily, Clinic is configurable: you can buffer up its output for printing later (or earlier!), or write its output to a separate file. You can also add a prefix or suffix to every line of Clinic's generated output.

While changing Clinic's output in this manner can be a boon to readability, it may result in Clinic code using types before they are defined, or your code attempting to use Clinic-generated code before it is defined. These problems can be easily solved by rearranging the declarations in your file, or moving where Clinic's generated code goes. (This is why the default behavior of Clinic is to output everything into the current block; while many people consider this hampers readability, it will never require rearranging your code to fix definition-before-use problems.)

Let's start with defining some terminology:

field

A field, in this context, is a subsection of Clinic's output. For example, the #define for the PyMethodDef structure is a field, called methoddef_define. Clinic has seven different fields it can output per function definition:

docstring_prototype
docstring_definition
methoddef_define
impl_prototype
parser_prototype
parser_definition
impl_definition

All the names are of the form "<a>_<b>", where "<a>" is the semantic object represented (the parsing function, the impl function, the docstring, or the methoddef structure) and "<b>" represents what kind of statement the field is. Field names that end in "_prototype" represent forward declarations of that thing, without the actual body/data of the thing; field names that end in "_definition" represent the actual definition of the thing, with the body/data of the thing. ("methoddef" is special, it's the only one that ends with "_define", representing that it's a preprocessor #define.)

destination

A destination is a place Clinic can write output to. There are five built-in destinations:

block
The default destination: printed in the output section of the current Clinic block.
buffer
A text buffer where you can save text for later. Text sent here is appended to the end of any existing text. It's an error to have any text left in the buffer when Clinic finishes processing a file.
file

A separate "clinic file" that will be created automatically by Clinic. The filename chosen for the file is {basename}.clinic{extension}, where basename and extension were assigned the output from os.path.splitext() run on the current file. (Example: the file destination for _pickle.c would be written to _pickle.clinic.c.)

Important: When using a file destination, you must check in the generated file!

two-pass
A buffer like buffer. However, a two-pass buffer can only be dumped once, and it prints out all text sent to it during all processing, even from Clinic blocks after the dumping point.
suppress
The text is suppressed—thrown away.

Clinic defines five new directives that let you reconfigure its output.

The first new directive is dump:

dump <destination>

This dumps the current contents of the named destination into the output of the current block, and empties it. This only works with buffer and two-pass destinations.

The second new directive is output. The most basic form of output is like this:

output <field> <destination>

This tells Clinic to output field to destination. output also supports a special meta-destination, called everything, which tells Clinic to output all fields to that destination.

output has a number of other functions:

output push
output pop
output preset <preset>

output push and output pop allow you to push and pop configurations on an internal configuration stack, so that you can temporarily modify the output configuration, then easily restore the previous configuration. Simply push before your change to save the current configuration, then pop when you wish to restore the previous configuration.

output preset sets Clinic's output to one of several built-in preset configurations, as follows:

block

Clinic's original starting configuration. Writes everything immediately after the input block.

Suppress the parser_prototype and docstring_prototype, write everything else to block.

file

Designed to write everything to the "clinic file" that it can. You then #include this file near the top of your file. You may need to rearrange your file to make this work, though usually this just means creating forward declarations for various typedef and PyTypeObject definitions.

Suppress the parser_prototype and docstring_prototype, write the impl_definition to block, and write everything else to file.

The default filename is "{dirname}/clinic/{basename}.h".

buffer

Save up most of the output from Clinic, to be written into your file near the end. For Python files implementing modules or builtin types, it's recommended that you dump the buffer just above the static structures for your module or builtin type; these are normally very near the end. Using buffer may require even more editing than file, if your file has static PyMethodDef arrays defined in the middle of the file.

Suppress the parser_prototype, impl_prototype, and docstring_prototype, write the impl_definition to block, and write everything else to file.

two-pass

Similar to the buffer preset, but writes forward declarations to the two-pass buffer, and definitions to the buffer. This is similar to the buffer preset, but may require less editing than buffer. Dump the two-pass buffer near the top of your file, and dump the buffer near the end just like you would when using the buffer preset.

Suppresses the impl_prototype, write the impl_definition to block, write docstring_prototype, methoddef_define, and parser_prototype to two-pass, write everything else to buffer.

partial-buffer

Similar to the buffer preset, but writes more things to block, only writing the really big chunks of generated code to buffer. This avoids the definition-before-use problem of buffer completely, at the small cost of having slightly more stuff in the block's output. Dump the buffer near the end, just like you would when using the buffer preset.

Suppresses the impl_prototype, write the docstring_definition and parser_definition to buffer, write everything else to block.

The third new directive is destination:

destination <name> <command> [...]

This performs an operation on the destination named name.

There are two defined subcommands: new and clear.

The new subcommand works like this:

destination <name> new <type>

This creates a new destination with name <name> and type <type>.

There are five destination types:

suppress
Throws the text away.
block
Writes the text to the current block. This is what Clinic originally did.
buffer
A simple text buffer, like the "buffer" builtin destination above.
file

A text file. The file destination takes an extra argument, a template to use for building the filename, like so:

destination <name> new <type> <file_template>

The template can use three strings internally that will be replaced by bits of the filename:

{path}
The full path to the file, including directory and full filename.
{dirname}
The name of the directory the file is in.
{basename}
Just the name of the file, not including the directory.
{basename_root}
Basename with the extension clipped off (everything up to but not including the last '.').
{basename_extension}
The last '.' and everything after it. If the basename does not contain a period, this will be the empty string.

If there are no periods in the filename, {basename} and {filename} are the same, and {extension} is empty. "{basename}{extension}" is always exactly the same as "{filename}"."

two-pass
A two-pass buffer, like the "two-pass" builtin destination above.

The clear subcommand works like this:

destination <name> clear

It removes all the accumulated text up to this point in the destination. (I don't know what you'd need this for, but I thought maybe it'd be useful while someone's experimenting.)

The fourth new directive is set:

set line_prefix "string"
set line_suffix "string"

set lets you set two internal variables in Clinic. line_prefix is a string that will be prepended to every line of Clinic's output; line_suffix is a string that will be appended to every line of Clinic's output.

以下はいずれも書式文字列をサポートします:

{block comment start}
Turns into the string /*, the start-comment text sequence for C files.
{block comment end}
Turns into the string */, the end-comment text sequence for C files.

The final new directive is one you shouldn't need to use directly, called preserve:

preserve

This tells Clinic that the current contents of the output should be kept, unmodified. This is used internally by Clinic when dumping output into file files; wrapping it in a Clinic block lets Clinic use its existing checksum functionality to ensure the file was not modified by hand before it gets overwritten.

#ifdef トリック

If you're converting a function that isn't available on all platforms, there's a trick you can use to make life a little easier. The existing code probably looks like this:

#ifdef HAVE_FUNCTIONNAME
static module_functionname(...)
{
...
}
#endif /* HAVE_FUNCTIONNAME */

And then in the PyMethodDef structure at the bottom the existing code will have:

#ifdef HAVE_FUNCTIONNAME
{'functionname', ... },
#endif /* HAVE_FUNCTIONNAME */

In this scenario, you should enclose the body of your impl function inside the #ifdef, like so:

#ifdef HAVE_FUNCTIONNAME
/*[clinic input]
module.functionname
...
[clinic start generated code]*/
static module_functionname(...)
{
...
}
#endif /* HAVE_FUNCTIONNAME */

Then, remove those three lines from the PyMethodDef structure, replacing them with the macro Argument Clinic generated:

MODULE_FUNCTIONNAME_METHODDEF

(You can find the real name for this macro inside the generated code. Or you can calculate it yourself: it's the name of your function as defined on the first line of your block, but with periods changed to underscores, uppercased, and "_METHODDEF" added to the end.)

Perhaps you're wondering: what if HAVE_FUNCTIONNAME isn't defined? The MODULE_FUNCTIONNAME_METHODDEF macro won't be defined either!

Here's where Argument Clinic gets very clever. It actually detects that the Argument Clinic block might be deactivated by the #ifdef. When that happens, it generates a little extra code that looks like this:

#ifndef MODULE_FUNCTIONNAME_METHODDEF
    #define MODULE_FUNCTIONNAME_METHODDEF
#endif /* !defined(MODULE_FUNCTIONNAME_METHODDEF) */

That means the macro always works. If the function is defined, this turns into the correct structure, including the trailing comma. If the function is undefined, this turns into nothing.

However, this causes one ticklish problem: where should Argument Clinic put this extra code when using the "block" output preset? It can't go in the output block, because that could be deactivated by the #ifdef. (That's the whole point!)

In this situation, Argument Clinic writes the extra code to the "buffer" destination. This may mean that you get a complaint from Argument Clinic:

Warning in file "Modules/posixmodule.c" on line 12357:
Destination buffer 'buffer' not empty at end of file, emptying.

When this happens, just open your file, find the dump buffer block that Argument Clinic added to your file (it'll be at the very bottom), then move it above the PyMethodDef structure where that macro is used.

Python ファイル内での Argument Clinic の利用

It's actually possible to use Argument Clinic to preprocess Python files. There's no point to using Argument Clinic blocks, of course, as the output wouldn't make any sense to the Python interpreter. But using Argument Clinic to run Python blocks lets you use Python as a Python preprocessor!

Since Python comments are different from C comments, Argument Clinic blocks embedded in Python files look slightly different. They look like this:

#/*[python input]
#print("def foo(): pass")
#[python start generated code]*/
def foo(): pass
#/*[python checksum:...]*/

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python HOWTO »


DTrace と SystemTap で CPython を測定する

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python HOWTO »

DTrace と SystemTap で CPython を測定する

author: | David Malcolm
author: | Łukasz Langa

Dtrace と SystemTap はモニタリングツールで、コンピュータシステムのプロセスが何をしているかを調べる方法を提供します。 どちらもドメイン固有言語 (domain-specific language) を使用して、次のことができるスクリプトをユーザが書けます:

  • 観測対象のプロセスを絞り込む
  • 関心のあるプロセスからデータを収集する
  • 収集したデータからレポートを生成する

Python 3.6 では、 CPython は "プローブ" としても知られる "マーカー" を埋め込んだビルドが行えます。 マーカーは DTrace や SystemTap のスクリプトから観測でき、システムの CPython プロセスが何をしているかを観察するのが簡単になります。

CPython implementation detail: 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 のビルドでは --with-dtrace を設定しなければなりません:

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

Python を (--enable-shared を指定して) 共有ライブラリとしてビルドした場合は、代わりにその共有ライブラリの中を覗く必要があります。 例えば次のようにします:

$ 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") {

(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)

このマーカーは function__entry() の反対で、 Python 関数の実行が (return もしくは例外によって) 終了したことを示しています。 このマーカーは、ピュア Python (バイトコード) の関数でしか起動されません。

引数は function__entry() と同じです。

line(str filename, str funcname, int lineno)

このマーカーは、これから実行される Python の行を示しています。 これは Python プロファイラによる行ごとのトレースと同等です。 このマーカーは C 関数の内部では起動されません。

引数は 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.

バージョン 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.

バージョン 3.7 で追加.

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 HOWTO »


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

Python よくある質問

  • 一般 Python FAQ
  • プログラミング FAQ
  • デザインと歴史 FAQ
  • ライブラリと拡張 FAQ
  • 拡張と埋め込み FAQ
  • Windows 上の Python FAQ
  • グラフィックユーザインタフェース FAQ
  • "なぜ Python が私のコンピュータにインストールされているのですか？" FAQ

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


拡張と埋め込み FAQ

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • 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 で実装されたオブジェクトクラスを (継承などで) 作ることはできますか？

C で独自の関数を作ることはできますか？

はい。関数、変数、例外、そして新しいタイプまで含んだビルトインモジュールを C で作れます。これはドキュメント Python インタプリタの拡張と埋め込み で説明されています。

ほとんどの中級から上級の Python 本もこの話題を扱っています。

C++ で独自の関数を作ることはできますか？

はい。C++ 内にある C 互換機能を使ってできます。 extern "C" { ... } で Python のインクルードファイルを囲み、 extern "C" を Python インタプリタから呼ぶ各関数の前に置いてください。グローバルや静的な C++ オブジェクトの構造体を持つものは良くないでしょう。

C を書くのは大変です。他の方法はありませんか？

独自の C 拡張を書くための別のやり方は、目的によっていくつかあります。

Cython とその親戚 Pyrex は、わずかに変形した Python を受け取り、対応する C コードを生成します。Cython や Pyrex を使えば Python の C API を習得することなく拡張を書けます。

今のところ Python 拡張が存在しないような C や C++ ライブラリへのインターフェイスが必要な場合、SWIG のようなツールで、そのライブラリのデータ型のラッピングを図れます。 SIP、CXX、Boost、Weave でも C++ ライブラリをラッピングできます。

C から任意の Python 文を実行するにはどうしますか？

The highest-level function to do this is PyRun_SimpleString() which takes a single string argument to be executed in the context of the module __main__ and returns 0 for success and -1 when an exception occurred (including SyntaxError). If you want more control, use PyRun_String(); see the source for PyRun_SimpleString() in Python/pythonrun.c.

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 を参照してください。

However sometimes you have to run the embedded Python interpreter in the same thread as your rest application and you can't allow the PyRun_InteractiveLoop() to stop while waiting for user input. The one solution then is to call PyParser_ParseString() and test for e.error equal to E_EOF, which means the input is incomplete. Here's a sample code fragment, untested, inspired by code from Alex Farber:

#include <Python.h>
#include <node.h>
#include <errcode.h>
#include <grammar.h>
#include <parsetok.h>
#include <compile.h>

int testcomplete(char *code)
  /* code should end in \n */
  /* return -1 for error, 0 for incomplete, 1 for complete */
{
  node *n;
  perrdetail e;

  n = PyParser_ParseString(code, &_PyParser_Grammar,
                           Py_file_input, &e);
  if (n == NULL) {
    if (e.error == E_EOF)
      return 0;
    return -1;
  }

  PyNode_Free(n);
  return 1;
}

別の解決策は、受け取られた文字列を Py_CompileString() でコンパイルすることを試みることです。エラー無くコンパイルされたら、返されたコードオブジェクトを PyEval_EvalCode() を呼んで実行することを試みてください。そうでなければ、入力を後のために保存してください。コンパイルが失敗したなら、それがエラーなのか入力の続きが求められているだけなのか調べてください。そのためには、例外タプルからメッセージ文字列を展開し、それを文字列 "unexpected EOF while parsing" と比較します。ここに GNU readline library を使った完全な例があります (readline() を読んでいる間は SIGINT を無視したいかもしれません):

#include <stdio.h>
#include <readline.h>

#include <Python.h>
#include <object.h>
#include <compile.h>
#include <eval.h>

int main (int argc, char* argv[])
{
  int i, j, done = 0;                          /* lengths of line, code */
  char ps1[] = ">>> ";
  char ps2[] = "... ";
  char *prompt = ps1;
  char *msg, *line, *code = NULL;
  PyObject *src, *glb, *loc;
  PyObject *exc, *val, *trb, *obj, *dum;

  Py_Initialize ();
  loc = PyDict_New ();
  glb = PyDict_New ();
  PyDict_SetItemString (glb, "__builtins__", PyEval_GetBuiltins ());

  while (!done)
  {
    line = readline (prompt);

    if (NULL == line)                          /* Ctrl-D pressed */
    {
      done = 1;
    }
    else
    {
      i = strlen (line);

      if (i > 0)
        add_history (line);                    /* save non-empty lines */

      if (NULL == code)                        /* nothing in code yet */
        j = 0;
      else
        j = strlen (code);

      code = realloc (code, i + j + 2);
      if (NULL == code)                        /* out of memory */
        exit (1);

      if (0 == j)                              /* code was empty, so */
        code[0] = '\0';                        /* keep strncat happy */

      strncat (code, line, i);                 /* append line to code */
      code[i + j] = '\n';                      /* append '\n' to code */
      code[i + j + 1] = '\0';

      src = Py_CompileString (code, "<stdin>", Py_single_input);

      if (NULL != src)                         /* compiled just fine - */
      {
        if (ps1  == prompt ||                  /* ">>> " or */
            '\n' == code[i + j - 1])           /* "... " and double '\n' */
        {                                               /* so execute it */
          dum = PyEval_EvalCode (src, glb, loc);
          Py_XDECREF (dum);
          Py_XDECREF (src);
          free (code);
          code = NULL;
          if (PyErr_Occurred ())
            PyErr_Print ();
          prompt = ps1;
        }
      }                                        /* syntax error or E_EOF? */
      else if (PyErr_ExceptionMatches (PyExc_SyntaxError))
      {
        PyErr_Fetch (&exc, &val, &trb);        /* clears exception! */

        if (PyArg_ParseTuple (val, "sO", &msg, &obj) &&
            !strcmp (msg, "unexpected EOF while parsing")) /* E_EOF */
        {
          Py_XDECREF (exc);
          Py_XDECREF (val);
          Py_XDECREF (trb);
          prompt = ps2;
        }
        else                                   /* some other syntax error */
        {
          PyErr_Restore (exc, val, trb);
          PyErr_Print ();
          free (code);
          code = NULL;
          prompt = ps1;
        }
      }
      else                                     /* some non-syntax error */
      {
        PyErr_Print ();
        free (code);
        code = NULL;
        prompt = ps1;
      }

      free (line);
    }
  }

  Py_XDECREF(glb);
  Py_XDECREF(loc);
  Py_Finalize();
  exit(0);
}

未定義の 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, http://www.boost.org/libs/python/doc/index.html) を使えば、これを C++ からできます。 (すなわち、BPL を使って C++ で書かれた拡張クラスを継承できます).

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python よくある質問 »


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

用語集

>>>
インタラクティブシェルにおけるデフォルトの Python プロンプトです。インタプリタでインタラクティブに実行されるコード例でよく出てきます。
...
インタラクティブシェルにおいて、インデントされたコードブロック、対応する左右の区切り文字の組 (丸括弧()、角括弧[]、波括弧{}、三重引用符) の内側、デコレーターの後に、コードを入力する際に表示されるデフォルトの Python プロンプトです。
2to3

Python 2.x のコードを Python 3.x のコードに変換するツールです。ソースコードを解析してその解析木を巡回 (traverse) することで検知できる、非互換性の大部分を処理します。

2to3 は標準ライブラリの lib2to3 として利用できます。単体のツールとしての使えるスクリプトが Tools/scripts/2to3 として提供されています。 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, PEP 526 を参照してください。

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 を参照してください。

asynchronous context manager
(非同期コンテクストマネージャ) __aenter__() と __aexit__() メソッドを定義することで async with 文内の環境を管理するオブジェクトです。 PEP 492 で導入されました。
asynchronous generator

(非同期ジェネレータ) asynchronous generator iterator を返す関数です。 async def で定義されたコルーチン関数に似ていますが、 yield 式を持つ点で異なります。 yield 式は async for ループで使用できる値の並びを生成するのに使用されます。

通常は非同期ジェネレータ関数を指しますが、文脈によっては 非同期ジェネレータイテレータ を指す場合があります。 意図された意味が明らかでない場合、 明瞭化のために完全な単語を使用します。

非同期ジェネレータ関数には、 async for 文や async with 文だけでなく await 式もあることがあります。

asynchronous generator iterator

(非同期ジェネレータイテレータ) asynchronous generator 関数で生成されるオブジェクトです。

This is an asynchronous iterator which when called using the __anext__() method returns an awaitable object which will execute the body of the asynchronous generator function until the next yield expression.

yield にくるたびに、その位置での実行状態 (ローカル変数と保留状態の try 文) 処理は一時停止されます。 __anext__() で返された他の awaitable によって 非同期ジェネレータイテレータ が実際に再開されたとき、中断した箇所を取得します。 PEP 492 および PEP 525 を参照してください。

asynchronous iterable
(非同期イテラブル) async for 文の中で使用できるオブジェクトです。 自身の __aiter__() メソッドから asynchronous iterator を返さなければなりません。 PEP 492 で導入されました。
asynchronous iterator
(非同期イテレータ) __aiter__() と __anext__() メソッドを実装したオブジェクトです。 __anext__ は awaitable オブジェクトを返さなければなりません。 async for は StopAsyncIteration 例外を送出するまで、非同期イテレータの __anext__() メソッドが返す awaitable を解決します。 PEP 492 で導入されました。
attribute
(属性) オブジェクトに関連付けられ、ドット表記式によって名前で参照される値です。例えば、オブジェクト o が属性 a を持っているとき、その属性は o.a で参照されます。
awaitable
(待機可能) await 式で使用することが出来るオブジェクトです。 coroutine か、 __await__() メソッドがあるオブジェクトです。 PEP 492 を参照してください。
BDFL
慈悲深き終身独裁者 (Benevolent Dictator For Life) の略です。Python の作者、Guido van Rossum のことです。
binary file

(バイナリファイル) bytes-like オブジェクト の読み込みおよび書き込みができる ファイルオブジェクト です。 バイナリファイルの例は、バイナリモード ('rb', 'wb' or 'rb+') で開かれたファイル、 sys.stdin.buffer 、 sys.stdout.buffer 、 io.BytesIO や gzip.GzipFile. のインスタンスです。

str オブジェクトの読み書きができるファイルオブジェクトについては、 text file も参照してください。

bytes-like object

バッファプロトコル (buffer Protocol) をサポートしていて、 C 言語レベルで 連続した (contiguous) バッファーを提供可能なオブジェクト。 bytes, bytearray, array.array や、多くの一般的な memoryview オブジェクトがこれに当たります。 bytes-like オブジェクトは、データ圧縮、バイナリファイルへの保存、ソケットを経由した送信など、バイナリデータを要求するいろいろな操作に利用することができます。

幾つかの操作ではバイナリデータを変更する必要があります。 その操作のドキュメントではよく "読み書き可能な bytes-like オブジェクト" に言及しています。 変更可能なバッファーオブジェクトには、 bytearray と bytearray の memoryview などが含まれます。 また、他の幾つかの操作では不変なオブジェクト内のバイナリデータ ("読み出し専用の bytes-like オブジェクト") を必要します。それには bytes と bytes の memoryview オブジェクトが含まれます。

bytecode

(バイトコード) Python のソースコードは、 Python プログラムの CPython インタプリタの内部表現であるバイトコードへとコンパイルされます。 バイトコードは .pyc ファイルにキャッシュされ、同じファイルが二度目に実行されるときはより高速になります (ソースコードからバイトコードへの再度のコンパイルは回避されます)。 この "中間言語 (intermediate language)" は、各々のバイトコードに対応する機械語を実行する仮想マシン (virtual machine) で動作するといえます。 重要な注意として、バイトコードは異なる Python 仮想マシン間で動作することや、Python リリース間で安定であることは期待されていません。

バイトコードの命令一覧は dis モジュール にあります。

class
(クラス) ユーザー定義オブジェクトを作成するためのテンプレートです。クラス定義は普通、そのクラスのインスタンス上の操作をするメソッドの定義を含みます。
class variable
(クラス変数) クラス上に定義され、クラスレベルで (つまり、クラスのインスタンス上ではなしに) 変更されることを目的としている変数です。
coercion
(型強制) 同じ型の 2 引数を伴う演算の最中に行われる、ある型のインスタンスの別の型への暗黙の変換です。 例えば、 int(3.15) は浮動小数点数を整数 3 に変換します。しかし 3+4.5 では、各引数は型が異なり(一つは整数、一つは浮動小数点数)、加算をする前に同じ型に変換できなければ TypeError 例外が投げられます。 型強制がなかったら、すべての引数は、たとえ互換な型であっても、単に 3+4.5 ではなく float(3)+4.5 というように、プログラマーが同じ型に正規化しなければいけません。
complex number
(複素数) よく知られている実数系を拡張したもので、すべての数は実部と虚部の和として表されます。虚数は虚数単位 (-1 の平方根) に実数を掛けたもので、一般に数学では i と書かれ、工学では j と書かれます。Python は複素数に組み込みで対応し、後者の表記を取っています。虚部は末尾に j をつけて書きます。例えば 3+1j です。 math モジュールの複素数版を利用するには、 cmath を使います。複素数の使用はかなり高度な数学の機能です。必要性を感じなければ、ほぼ間違いなく無視してしまってよいでしょう。
context manager
(コンテクストマネージャ) __enter__() と __exit__() メソッドを定義することで with 文内の環境を管理するオブジェクトです。 PEP 343 を参照してください。
contiguous

(隣接、連続) バッファが厳密に C-連続 または Fortran 連続 である場合に、そのバッファは連続しているとみなせます。 ゼロ次元バッファは C 連続であり Fortran 連続です。 一次元の配列では、その要素は必ずメモリ上で隣接するように配置され、添字がゼロから始まり増えていく順序で並びます。 多次元の C-連続な配列では、メモリアドレス順に要素を巡る際には最後の添え字が最初に変わるのに対し、 Fortran 連続な配列では最初の添え字が最初に動きます。

coroutine
(コルーチン) コルーチンはサブルーチンのより一般的な形式です。 サブルーチンにはある時に入り別の時に出ます。 コルーチンには多くの異なる時に入り、出て、再開することが出来ます。 コルーチンは async def 文で実装されます。 PEP 492 を参照してください。
coroutine function
(コルーチン関数) coroutine オブジェクトを返す関数です。 コルーチン関数は async def 文で実装され、await、async for、 および async with キーワードを持つことが出来ます。 これらは PEP 492 で導入されました。
CPython
python.org で配布されている、Python プログラミング言語の標準的な実装です。"CPython" という単語は、この実装を Jython や IronPython といった他の実装と区別する必要が有る場合に利用されます。
decorator

(デコレータ) 別の関数を返す関数で、通常、 @wrapper 構文で関数変換として適用されます。デコレータの一般的な利用例は、 classmethod() と staticmethod() です。

デコレータの文法はシンタックスシュガーです。次の2つの関数定義は意味的に同じものです:

def f(...):
    ...
f = staticmethod(f)

@staticmethod
def f(...):
    ...

同じ概念がクラスにも存在しますが、あまり使われません。デコレータについて詳しくは、 関数定義 および クラス定義 のドキュメントを参照してください。

descriptor

(デスクリプタ) メソッド __get__(), __set__(), あるいは __delete__() を定義しているオブジェクトです。あるクラス属性がデスクリプタであるとき、属性探索によって、束縛されている特別な動作が呼び出されます。通常、get,set,deleteのために a.b と書くと、 a のクラス辞書内でオブジェクト b を検索しますが、 b がデスクリプタであればそれぞれのデスクリプタメソッドが呼び出されます。デスクリプタの理解は、 Python を深く理解する上で鍵となります。というのは、デスクリプタこそが、関数、メソッド、プロパティ、クラスメソッド、静的メソッド、そしてスーパクラスの参照といった多くの機能の基盤だからです。

デスクリプタのメソッドに関して詳しくは、 デスクリプタ (descriptor) の実装 を参照してください。

dictionary
(辞書) 任意のキーを値に対応付ける連想配列です。 __hash__() メソッドと __eq__() メソッドを実装した任意のオブジェクトをキーにできます。 Perl ではハッシュ (hash) と呼ばれています。
dictionary view
(辞書ビュー) dict.keys()、dict.values()、dict.items() が返すオブジェクトです。 辞書の項目の動的なビューを提供します。 すなわち、辞書が変更されるとビューはそれを反映します。 辞書ビューを強制的に完全なリストにするには list(dictview) を使用してください。 辞書ビューオブジェクト を参照してください。
docstring
クラス、関数、モジュールの最初の式である文字列リテラルです。そのスイートの実行時には無視されますが、コンパイラによって識別され、そのクラス、関数、モジュールの __doc__ 属性として保存されます。イントロスペクションできる（訳注: 属性として参照できる）ので、オブジェクトのドキュメントを書く標準的な場所です。
duck-typing
あるオブジェクトが正しいインタフェースを持っているかを決定するのにオブジェクトの型を見ないプログラミングスタイルです。代わりに、単純にオブジェクトのメソッドや属性が呼ばれたり使われたりします。（「アヒルのように見えて、アヒルのように鳴けば、それはアヒルである。」）インタフェースを型より重視することで、上手くデザインされたコードは、ポリモーフィックな代替を許して柔軟性を向上させます。ダックタイピングは type() や isinstance() による判定を避けます。 (ただし、ダックタイピングを 抽象基底クラス で補完することもできます。) その代わり、典型的に hasattr() 判定や EAFP プログラミングを利用します。
EAFP
「認可をとるより許しを請う方が容易 (easier to ask for forgiveness than permission、マーフィーの法則)」の略です。この Python で広く使われているコーディングスタイルでは、通常は有効なキーや属性が存在するものと仮定し、その仮定が誤っていた場合に例外を捕捉します。この簡潔で手早く書けるコーディングスタイルには、 try 文および except 文がたくさんあるのが特徴です。このテクニックは、C のような言語でよく使われている LBYL スタイルと対照的なものです。
expression
A piece of syntax which can be evaluated to some value. In other words, an expression is an accumulation of expression elements like literals, names, attribute access, operators or function calls which all return a value. In contrast to many other languages, not all language constructs are expressions. There are also statements which cannot be used as expressions, such as if. Assignments are also statements, not expressions.
extension module
(拡張モジュール) C や C++ で書かれたモジュールで、Python の C API を利用して Python コアやユーザーコードとやりとりします。
f-string
'f' や 'F' が先頭に付いた文字列リテラルは "f-string" と呼ばれ、これは フォーマット済み文字列リテラル の短縮形の名称です。 PEP 498 も参照してください。
file object

(ファイルオブジェクト) 下位のリソースへのファイル志向 API (read() や write() メソッドを持つもの) を公開しているオブジェクトです。ファイルオブジェクトは、作成された手段によって、実際のディスク上のファイルや、その他のタイプのストレージや通信デバイス (例えば、標準入出力、インメモリバッファ、ソケット、パイプ、等) へのアクセスを媒介できます。ファイルオブジェクトは file-like objects や streams とも呼ばれます。

ファイルオブジェクトには実際には 3 種類あります: 生の バイナリーファイル、バッファされた バイナリーファイル、そして テキストファイル です。インターフェイスは io モジュールで定義されています。ファイルオブジェクトを作る標準的な方法は open() 関数を使うことです。

file-like object
file object と同義です。
finder

(ファインダ) インポートされているモジュールの loader の発見を試行するオブジェクトです。

Python 3.3 以降では 2 種類のファインダがあります。 sys.meta_path で使用される meta path finder と、 sys.path_hooks で使用される path entry finder です。

詳細については PEP 302、 PEP 420 および PEP 451 を参照してください。

floor division
一番近い小さい整数に丸める数学除算。floor division 演算子は // です。例えば、 11 // 4 は 2 になり、 float の true division の結果 2.75 と異なります。 (-11) // 4 は -2.75 を 小さい方に 丸めるので -3 になることに注意してください。 PEP 238 を参照してください。
function
(関数) 呼び出し側に値を返す一連の文のことです。関数には0以上の 実引数 を渡すことが出来ます。実体の実行時に引数を使用することが出来ます。 仮引数、メソッド、関数定義 を参照してください。
function annotation

(関数アノテーション) 関数のパラメータや返り値の annotation です。

関数アノテーションは、通常は 型ヒント のために使われます: 例えば、この関数は 2 つの int 型の引数を取ると期待され、また int 型の返り値を持つと期待されています。

def sum_two_numbers(a: int, b: int) -> int:
   return a + b

関数アノテーションの文法は 関数定義 の節で解説されています。

機能の説明がある variable annotation と PEP 484 を参照してください。

__future__

互換性のない新たな言語機能を現在のインタプリタで有効にするためにプログラマが利用できる擬似モジュールです。

__future__ モジュールを import してその変数を評価すれば、新たな機能が初めて追加されたのがいつで、いつ言語デフォルトの機能になるかわかります:

>>> import __future__
>>> __future__.division
_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
garbage collection
(ガベージコレクション) これ以降使われることのないメモリを解放する処理です。 Pythonは、参照カウントと、循環参照を検出し破壊する循環ガベージコレクタを使ってガベージコレクションを行います。 ガベージコレクタは gc モジュールを使って操作できます。
generator

(ジェネレータ) 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 expression defining a loop variable, range, and an optional if expression. 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 を参照してください。

GIL
global interpreter lock を参照してください。
global interpreter lock

(グローバルインタプリタロック) CPython インタプリタが利用している、一度に Python のバイトコード (bytecode) を実行するスレッドは一つだけであることを保証する仕組みです。これにより (dict などの重要な組み込み型を含む) オブジェクトモデルが同時アクセスに対して暗黙的に安全になるので、 CPython の実装がシンプルになります。インタプリタ全体をロックすることで、マルチプロセッサマシンが生じる並列化のコストと引き換えに、インタプリタを簡単にマルチスレッド化できるようになります。

ただし、標準あるいは外部のいくつかの拡張モジュールは、圧縮やハッシュ計算などの計算の重い処理をするときに GIL を解除するように設計されています。また、I/O 処理をする場合 GIL は常に解除されます。

過去に "自由なマルチスレッド化" したインタプリタ (供用されるデータを細かい粒度でロックする) が開発されましたが、一般的なシングルプロセッサの場合のパフォーマンスが悪かったので成功しませんでした。このパフォーマンスの問題を克服しようとすると、実装がより複雑になり保守コストが増加すると考えられています。

hash-based pyc
(ハッシュベース pyc ファイル) 正当性を判別するために、対応するソースファイルの最終更新時刻ではなくハッシュ値を使用するバイトコードのキャッシュファイルです。
hashable

(ハッシュ可能) ハッシュ可能 なオブジェクトとは、生存期間中変わらないハッシュ値を持ち (__hash__() メソッドが必要)、他のオブジェクトと比較ができる (__eq__() メソッドが必要) オブジェクトです。同値なハッシュ可能オブジェクトは必ず同じハッシュ値を持つ必要があります。

ハッシュ可能なオブジェクトは辞書のキーや集合のメンバーとして使えます。辞書や集合のデータ構造は内部でハッシュ値を使っているからです。

Python のイミュータブルな組み込みオブジェクトはハッシュ可能です; ミュータブルなコンテナ (例えばリストや辞書) はハッシュ不可能です。 ユーザー定義のクラスのインスタンスであるようなオブジェクトはデフォルトでハッシュ可能です。 それらは全て (自身を除いて) 比較結果は非等価であり、ハッシュ値は id() より得られます。

IDLE
Python の統合開発環境 (Integrated DeveLopment Environment) です。IDLE は Python の標準的な配布に同梱されている基本的な機能のエディタとインタプリタ環境です。
immutable
(イミュータブル) 固定の値を持ったオブジェクトです。イミュータブルなオブジェクトには、数値、文字列、およびタプルなどがあります。これらのオブジェクトは値を変えられません。別の値を記憶させる際には、新たなオブジェクトを作成しなければなりません。イミュータブルなオブジェクトは、固定のハッシュ値が必要となる状況で重要な役割を果たします。辞書のキーがその例です。
import path
path based finder が import するモジュールを検索する場所 (または path entry) のリスト。 import 中、このリストは通常 sys.path から来ますが、サブパッケージの場合は親パッケージの __path__ 属性からも来ます。
importing
あるモジュールの Python コードが別のモジュールの Python コードで使えるようにする処理です。
importer
モジュールを探してロードするオブジェクト。 finder と loader のどちらでもあるオブジェクト。
interactive
(対話的) Python には対話的インタプリタがあり、文や式をインタプリタのプロンプトに入力すると即座に実行されて結果を見ることができます。 python と何も引数を与えずに実行してください。(コンピュータのメインメニューから Pythonの対話的インタプリタを起動できるかもしれません。) 対話的インタプリタは、新しいアイデアを試してみたり、モジュールやパッケージの中を覗いてみる(help(x) を覚えておいてください) のに非常に便利なツールです。
interpreted
Python はインタプリタ形式の言語であり、コンパイラ言語の対極に位置します。 (バイトコードコンパイラがあるために、この区別は曖昧ですが。) ここでのインタプリタ言語とは、ソースコードのファイルを、まず実行可能形式にしてから実行させるといった操作なしに、直接実行できることを意味します。インタプリタ形式の言語は通常、コンパイラ形式の言語よりも開発／デバッグのサイクルは短いものの、プログラムの実行は一般に遅いです。対話的(interactive)も参照してください。
interpreter shutdown

Python インタープリターはシャットダウンを要請された時に、モジュールやすべてのクリティカルな内部構造をなどの、すべての確保したリソースを段階的に開放する、特別なフェーズに入ります。 このフェーズはガベージコレクター (garbage collector) を複数回呼び出します。 これによりユーザー定義のデストラクターや weakref コールバックが呼び出されることがあります。 シャットダウンフェーズ中に実行されるコードは、それが依存するリソースがすでに機能しない(よくある例はライブラリーモジュールや warning 機構です) ために様々な例外に直面します。

インタープリタがシャットダウンする主な理由は __main__ モジュールや実行されていたスクリプトの実行が終了したことです。

iterable

(反復可能オブジェクト) 要素を一度に 1 つずつ返せるオブジェクトです。 反復可能オブジェクトの例には、(list, str, tuple といった) 全てのシーケンス型や、 dict や ファイルオブジェクト といった幾つかの非シーケンス型、 あるいは Sequence 意味論を実装した __iter__() メソッドか __getitem__() メソッドを持つ任意のクラスのインスタンスが含まれます。

反復可能オブジェクトは for ループ内やその他多くのシーケンス (訳注: ここでのシーケンスとは、シーケンス型ではなくただの列という意味)が必要となる状況 (zip(), map(), ...) で利用できます。 反復可能オブジェクトを組み込み関数 iter() の引数として渡すと、 オブジェクトに対するイテレータを返します。 このイテレータは一連の値を引き渡す際に便利です。 通常は反復可能オブジェクトを使う際には、 iter() を呼んだりイテレータオブジェクトを自分で操作する必要はありません。 for 文ではこの操作を自動的に行い、一時的な無名の変数を作成してループを回している間イテレータを保持します。 イテレータ (iterator), シーケンス (sequence), ジェネレータ(generator) も参照してください。

iterator

(イテレータ) データの流れを表現するオブジェクトです。イテレータの __next__() メソッドを繰り返し呼び出す (または組み込み関数 next() に渡す) と、流れの中の要素を一つずつ返します。データがなくなると、代わりに StopIteration 例外を送出します。その時点で、イテレータオブジェクトは尽きており、それ以降は __next__() を何度呼んでも StopIteration を送出します。イテレータは、そのイテレータオブジェクト自体を返す __iter__() メソッドを実装しなければならないので、イテレータは他の iterable を受理するほとんどの場所で利用できます。はっきりとした例外は複数の反復を行うようなコードです。 (list のような) コンテナオブジェクトは、自身を iter() 関数にオブジェクトに渡したり for ループ内で使うたびに、新たな未使用のイテレータを生成します。これをイテレータで行おうとすると、前回のイテレーションで使用済みの同じイテレータオブジェクトを単純に返すため、空のコンテナのようになってしまします。

詳細な情報は イテレータ型 にあります。

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(), itemgetter(), methodcaller() という 3 つのキー関数コンストラクタを提供しています。 キー関数の作り方と使い方の例は Sorting HOW TO を参照してください。

keyword argument
実引数 を参照してください。
lambda
(ラムダ) 無名のインライン関数で、関数が呼び出されたときに評価される 1 つの式 (expression) を含みます。ラムダ関数を作る構文は lambda [parameters]: expression です。
LBYL

「ころばぬ先の杖 (look before you leap)」 の略です。このコーディングスタイルでは、呼び出しや検索を行う前に、明示的に前提条件 (pre-condition) 判定を行います。 EAFP アプローチと対照的で、 if 文がたくさん使われるのが特徴的です。

マルチスレッド化された環境では、LBYL アプローチは "見る" 過程と "飛ぶ" 過程の競合状態を引き起こすリスクがあります。例えば、if key in mapping: return mapping[key] というコードは、判定の後、別のスレッドが探索の前に mapping から key を取り除くと失敗します。この問題は、ロックするか EAFP アプローチを使うことで解決できます。

list
(リスト) Python の組み込みのシーケンス (sequence) です。リストという名前ですが、リンクリストではなく、他の言語で言う配列 (array) と同種のもので、要素へのアクセスは 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 を、 abstract base class については importlib.abc.Loader を参照してください。
mapping
(マッピング) 任意のキー探索をサポートしていて、 Mapping か 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 が特別なのはカスタムのメタクラスを作成できる点です。ほとんどのユーザーに取って、メタクラスは全く必要のないものです。しかし、一部の場面では、メタクラスは強力でエレガントな方法を提供します。たとえば属性アクセスのログを取ったり、スレッドセーフ性を追加したり、オブジェクトの生成を追跡したり、シングルトンを実装するなど、多くの場面で利用されます。

詳細は メタクラス を参照してください。

メソッド
(メソッド) クラス本体の中で定義された関数。そのクラスのインスタンスの属性として呼び出された場合、メソッドはインスタンスオブジェクトを第一引数 (argument) として受け取ります (この第一引数は通常 self と呼ばれます)。 関数 と ネストされたスコープ も参照してください。
method resolution order
(メソッド解決順序) 探索中に基底クラスが構成要素を検索される順番です。 2.3 以降の Python インタープリタが使用するアルゴリズムの詳細については The Python 2.3 Method Resolution Order を参照してください。
module

(モジュール) Python コードの組織単位としてはたらくオブジェクトです。モジュールは任意の Python オブジェクトを含む名前空間を持ちます。モジュールは importing の処理によって Python に読み込まれます。

パッケージ を参照してください。

module spec
モジュールをロードするのに使われるインポート関連の情報を含む名前空間です。 importlib.machinery.ModuleSpec のインスタンスです。
MRO
method resolution order を参照してください。
mutable
(ミュータブル) ミュータブルなオブジェクトは、 id() を変えることなく値を変更できます。イミュータブル (immutable) も参照してください。
named tuple

(名前付きタプル) タプルに似ていて、インデクス指定できる要素に名前付き属性でもアクセス出来るクラスです (例えば、 time.localtime() はタプルに似たオブジェクトを返し、その year には t[0] のようなインデクスによるアクセスと、 t.tm_year のような名前付き要素としてのアクセスが可能です)。

名前付きタプルには、 time.struct_time のような組み込み型もありますし、通常のクラス定義によって作成することもできます。名前付きタプルを collections.namedtuple() ファクトリ関数で作成することもできます。最後の方法で作った名前付きタプルには自動的に、 Employee(name='jones', title='programmer') のような自己ドキュメント表現 (self-documenting representation) などの機能が付いてきます。

namespace
(名前空間) 変数が格納される場所です。名前空間は辞書として実装されます。名前空間にはオブジェクトの (メソッドの) 入れ子になったものだけでなく、局所的なもの、大域的なもの、そして組み込みのものがあります。名前空間は名前の衝突を防ぐことによってモジュール性をサポートする。例えば関数 builtins.open と os.open() は名前空間で区別されています。また、どのモジュールが関数を実装しているか明示することによって名前空間は可読性と保守性を支援します。例えば、random.seed() や itertools.islice() と書くと、それぞれモジュール random や itertools で実装されていることが明らかです。
namespace package

(名前空間パッケージ) サブパッケージのコンテナとして提供される PEP 420 package 。Namespace package はおそらく物理表現を持たず、 __init__.py ファイルがないため、 regular package と異なります。

module を参照してください。

nested scope
(ネストされたスコープ) 外側で定義されている変数を参照する機能です。例えば、ある関数が別の関数の中で定義されている場合、内側の関数は外側の関数中の変数を参照できます。ネストされたスコープはデフォルトでは変数の参照だけができ、変数の代入はできないので注意してください。ローカル変数は、最も内側のスコープで変数を読み書きします。同様に、グローバル変数を使うとグローバル名前空間の値を読み書きします。 nonlocal で外側の変数に書き込めます。
new-style class
(新スタイルクラス) 今では全てのクラスオブジェクトに使われている味付けの古い名前です。以前の Python のバージョンでは、新スタイルクラスのみが __slots__ 、デスクリプタ、 __getattribute__() 、クラスメソッド、そして静的メソッド等の Python の新しい、多様な機能を利用できました。
object
(オブジェクト) 状態 (属性や値) と定義された振る舞い (メソッド) をもつ全てのデータ。もしくは、全ての新スタイルクラス (new-style class) の究極の基底クラスのこと。
package

(パッケージ) サブモジュールや再帰的にサブパッケージを含むことの出来る module のことです。専門的には、パッケージは __path__ 属性を持つ Python オブジェクトです。

regular package と namespace package を参照してください。

parameter

(仮引数) 名前付の実体で 関数 (や メソッド ) の定義において関数が受ける 実引数 を指定します。仮引数には5種類あります:

  • 位置またはキーワード: 位置 でまたは キーワード引数 として渡すことができる引数を指定します。これはたとえば以下の foo や bar のように、デフォルトの仮引数の種類です:

    def func(foo, bar=None): ...
  • 位置のみ: 位置によってのみ与えられる引数を指定します。Python に引数が位置のみであることを定義する文法はありませんが、組み込み関数には位置のみの引数を持つもの (例: abs()) があります。

  • キーワードのみ: キーワードによってのみ与えられる引数を指定します。キーワードのみの引数を定義できる場所は、例えば以下の kw_only1 や kw_only2 のように、関数定義の仮引数リストに含めた可変長位置引数または裸の * の後です:

    def func(arg, *, kw_only1, kw_only2): ...

  • 可変長位置: (他の仮引数で既に受けられた任意の位置引数に加えて) 任意の個数の位置引数が与えられることを指定します。このような仮引数は、以下の args のように仮引数名の前に * をつけることで定義できます:

    def func(*args, **kwargs): ...

  • 可変長キーワード: (他の仮引数で既に受けられた任意のキーワード引数に加えて) 任意の個数のキーワード引数が与えられることを指定します。このような仮引数は、上の例の kwargs のように仮引数名の前に ** をつけることで定義できます。

仮引数はオプションと必須の引数のどちらも指定でき、オプションの引数にはデフォルト値も指定できます。

仮引数 、FAQ の 実引数と仮引数の違いは何ですか? 、inspect.Parameter クラス、 関数定義 セクション、 PEP 362 を参照してください。

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
sys.path_hook リストにある callable で、指定された path entry にあるモジュールを見つける方法を知っている場合に path entry finder を返します。
path based finder
デフォルトの meta path finder の1つは、モジュールの import path を検索します。
path-like object
An object representing a file system path. A path-like object is either a str or bytes object representing a path, or an object implementing the os.PathLike protocol. An object that supports the os.PathLike protocol can be converted to a str or bytes file system path by calling the os.fspath() function; os.fsdecode() and os.fsencode() can be used to guarantee a str or bytes result instead, respectively. Introduced by PEP 519.
PEP

Python Enhancement Proposal. A PEP is a design document providing information to the Python community, or describing a new feature for Python or its processes or environment. PEPs should provide a concise technical specification and a rationale for proposed features.

PEPs are intended to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into Python. The PEP author is responsible for building consensus within the community and documenting dissenting opinions.

See PEP 1.

portion
PEP 420 で定義されている、namespace package に属する、複数のファイルが (zipファイルに格納されている場合もある) 1つのディレクトリに格納されたもの。
positional argument (位置引数)
実引数 を参照してください。
provisional API

(暫定 API) 標準ライブラリの後方互換性保証から計画的に除外されたものです。そのようなインタフェースへの大きな変更は、暫定であるとされている間は期待されていませんが、コア開発者によって必要とみなされれば、後方非互換な変更 (インタフェースの削除まで含まれる) が行われえます。このような変更はむやみに行われるものではありません -- これは API を組み込む前には見落とされていた重大な欠陥が露呈したときにのみ行われます。

暫定 API についても、後方互換性のない変更は「最終手段」とみなされています。問題点が判明した場合でも後方互換な解決策を探すべきです。

このプロセスにより、標準ライブラリは問題となるデザインエラーに長い間閉じ込められることなく、時代を超えて進化を続けられます。詳細は PEP 411 を参照してください。

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 で定義されています。トップレベルの関数やクラスでは、修飾名はオブジェクトの名前と同じです:

>>> 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
(参照カウント) あるオブジェクトに対する参照の数。参照カウントが0になったとき、そのオブジェクトは破棄されます。参照カウントは通常は Python のコード上には現れませんが、 CPython 実装の重要な要素です。 sys モジュールは、プログラマーが任意のオブジェクトの参照カウントを知るための getrefcount() 関数を提供しています。
regular package

伝統的な、 __init__.py ファイルを含むディレクトリとしての package。

namespace package を参照してください。

__slots__
クラス内での宣言で、インスタンス属性の領域をあらかじめ定義しておき、インスタンス辞書を排除することで、メモリを節約します。これはよく使われるテクニックですが、正しく扱うには少しトリッキーなので、稀なケース、例えばメモリが死活問題となるアプリケーションでインスタンスが大量に存在する、といったときを除き、使わないのがベストです。
sequence

(シーケンス) 整数インデクスによる効率的な要素アクセスを __getitem__() 特殊メソッドを通じてサポートし、長さを返す __len__() メソッドを定義した iterable です。組み込みシーケンス型には、 list, str, tuple, bytes などがあります。 dict は __getitem__() と __len__() もサポートしますが、検索の際に整数ではなく任意の immutable なキーを使うため、シーケンスではなくマッピング (mapping) とみなされているので注意してください。

collections.abc.Sequence 抽象基底クラスは __getitem__() や __len__() だけでなく count()、index(),、__contains__()、__reversed__() よりも 豊富なインターフェイスを定義しています。この拡張されたインターフェイスを実装している型は register() を使用することで明示的に登録することが出来ます。

single dispatch
generic function の一種で実装は一つの引数の型により選択されます。
slice
(スライス) 一般にシーケンス (sequence) の一部を含むオブジェクト。スライスは、添字表記 [] で与えられた複数の数の間にコロンを書くことで作られます。例えば、 variable_name[1:3:5] です。角括弧 (添字) 記号は slice オブジェクトを内部で利用しています。
special method
(特殊メソッド) ある型に特定の操作、例えば加算をするために Python から暗黙に呼び出されるメソッド。この種類のメソッドは、メソッド名の最初と最後にアンダースコア 2 つがついています。特殊メソッドについては 特殊メソッド名 で解説されています。
statement
(文) 文はスイート (コードの"ブロック") に不可欠な要素です。文は 式 かキーワードから構成されるもののどちらかです。後者には if、while、for があります。
struct sequence
A tuple with named elements. Struct sequences expose an interface similar to named tuple in that elements can be accessed either by index or as an attribute. However, they do not have any of the named tuple methods like _make() or _asdict(). Examples of struct sequences include sys.float_info and the return value of os.stat().
text encoding
ユニコード文字列をエンコードするコーデックです。
text file

A file object able to read and write str objects. Often, a text file actually accesses a byte-oriented datastream and handles the text encoding automatically. Examples of text files are files opened in text mode ('r' or 'w'), sys.stdin, sys.stdout, and instances of io.StringIO.

See also binary file for a file object able to read and write bytes-like objects.

triple-quoted string
(三重クォート文字列) 3つの連続したクォート記号(")かアポストロフィー(')で囲まれた文字列。通常の(一重)クォート文字列に比べて表現できる文字列に違いはありませんが、幾つかの理由で有用です。1つか2つの連続したクォート記号をエスケープ無しに書くことができますし、行継続文字(\)を使わなくても複数行にまたがることができるので、ドキュメンテーション文字列を書く時に特に便利です。
type
(型) Python オブジェクトの型はオブジェクトがどのようなものかを決めます。あらゆるオブジェクトは型を持っています。オブジェクトの型は __class__ 属性でアクセスしたり、type(obj) で取得したり出来ます。
type alias

(型エイリアス) 型の別名で、型を識別子に代入して作成します。

型エイリアスは 型ヒント を単純化するのに有用です。例えば:

from typing import List, Tuple

def remove_gray_shades(
        colors: List[Tuple[int, int, int]]) -> List[Tuple[int, int, int]]:
    pass

これは次のようにより読みやすくできます:

from typing import List, Tuple

Color = Tuple[int, int, int]

def remove_gray_shades(colors: List[Color]) -> List[Color]:
    pass

機能の説明がある typing と PEP 484 を参照してください。

type hint

(型ヒント) 変数、クラス属性、関数のパラメータや返り値の期待される型を指定する annotation です。

型ヒントは必須ではなく Python では強制ではありませんが、静的型解析ツールにとって有用であり、IDE のコード補完とリファクタリングの手助けになります。

Type hints of global variables, class attributes, and functions, but not local variables, can be accessed using typing.get_type_hints().

機能の説明がある typing と PEP 484 を参照してください。

universal newlines
テキストストリームの解釈法の一つで、以下のすべてを行末と認識します: Unix の行末規定 '\n'、Windows の規定 '\r\n'、古い Macintosh の規定 '\r'。利用法について詳しくは、 PEP 278 と PEP 3116 、さらに bytes.splitlines() も参照してください。
variable annotation

An annotation of a variable or a class attribute.

When annotating a variable or a class attribute, assignment is optional:

class C:
    field: 'annotation'

Variable annotations are usually used for type hints: for example this variable is expected to take int values:

count: int = 0

Variable annotation syntax is explained in section 注釈付き代入文 (annotated assignment statements).

See function annotation, PEP 484 and PEP 526, which describe this functionality.

virtual environment

（仮想環境）協調的に切り離された実行環境です。これにより Python ユーザとアプリケーションは同じシステム上で動いている他の Python アプリケーションの挙動に干渉することなく Python パッケージのインストールと更新を行うことができます。

venv を参照してください。

virtual machine
(仮想マシン) 完全にソフトウェアにより定義されたコンピュータ。 Python の仮想マシンは、バイトコードコンパイラが出力したバイトコード (bytecode) を実行します。
Zen of Python
(Pythonの悟り) Python を理解し利用する上での導きとなる、Python の設計原則と哲学をリストにしたものです。対話プロンプトで "import this" とするとこのリストを読めます。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

このドキュメントについて

このドキュメントは、 Python のドキュメントを主要な目的として作られた ドキュメントプロセッサの Sphinx を利用して、 reStructuredText 形式のソースから生成されました。

ドキュメントとそのツール群の開発は、Python 自身と同様に完全にボランティアの努力です。 もしあなたが貢献したいなら、どのようにすればよいかについて バグへの対処 ページをご覧下さい。 新しいボランティアはいつでも歓迎です! （訳注: 日本語訳の問題については、 GitHub 上の Issue Tracker で報告をお願いします。）

多大な感謝を:

  • Fred L. Drake, Jr., オリジナルの Python ドキュメントツールセットの作成者で、ドキュメントの多くを書きました。
  • Docutils プロジェクト. reStructuredText と docutils ツールセットを作成しました。
  • Fredrik Lundh の Alternative Python Reference プロジェクトから Sphinx は多くのアイデアを得ました。

Pythonドキュメント 貢献者

多くの方々が Python 言語、Python 標準ライブラリ、そして Python ドキュメンテーションに貢献してくれています。ソース配布物の Misc/ACKS に、それら貢献してくれた人々を部分的にではありますがリストアップしてあります。

Python コミュニティからの情報提供と貢献がなければこの素晴らしいドキュメンテーションは生まれませんでした -- ありがとう!

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

Copyright

Python and this documentation is:

Copyright © 2001-2018 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 »
  • 3.7.2 Documentation »

歴史とライセンス

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, http://www.zope.com/ 参照) に移りました。そして 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

PSF LICENSE AGREEMENT FOR PYTHON 3.7.2

1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and
   the Individual or Organization ("Licensee") accessing and otherwise using Python
   3.7.2 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.7.2 alone or in any derivative
   version, provided, however, that PSF's License Agreement and PSF's notice of
   copyright, i.e., "Copyright © 2001-2018 Python Software Foundation; All Rights
   Reserved" are retained in Python 3.7.2 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.7.2 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.7.2.

4. PSF is making Python 3.7.2 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.7.2 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 3.7.2
   FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
   MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 3.7.2, 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.7.2, 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.

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 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, http://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 asynchat and 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_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

The select module contains the following notice for the kqueue interface:

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. The 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 http://www.netlib.org/fp/. 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 Mac OS X installers for Python may include a copy of the OpenSSL libraries, so we include a copy of the OpenSSL license here:

 LICENSE ISSUES
 ==============

 The OpenSSL toolkit stays under a dual license, i.e. both the conditions of
 the OpenSSL License and the original SSLeay license apply to the toolkit.
 See below for the actual license texts. Actually both licenses are BSD-style
 Open Source licenses. In case of any license issues related to OpenSSL
 please contact openssl-core@openssl.org.

 OpenSSL License
 ---------------

   /* ====================================================================
    * Copyright (c) 1998-2008 The OpenSSL 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. All advertising materials mentioning features or use of this
    *    software must display the following acknowledgment:
    *    "This product includes software developed by the OpenSSL Project
    *    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
    *
    * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
    *    endorse or promote products derived from this software without
    *    prior written permission. For written permission, please contact
    *    openssl-core@openssl.org.
    *
    * 5. Products derived from this software may not be called "OpenSSL"
    *    nor may "OpenSSL" appear in their names without prior written
    *    permission of the OpenSSL Project.
    *
    * 6. Redistributions of any form whatsoever must retain the following
    *    acknowledgment:
    *    "This product includes software developed by the OpenSSL Project
    *    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
    *
    * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
    * EXPRESSED 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 OpenSSL PROJECT OR
    * ITS 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.
    * ====================================================================
    *
    * This product includes cryptographic software written by Eric Young
    * (eay@cryptsoft.com).  This product includes software written by Tim
    * Hudson (tjh@cryptsoft.com).
    *
    */

Original SSLeay License
-----------------------

   /* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
    * All rights reserved.
    *
    * This package is an SSL implementation written
    * by Eric Young (eay@cryptsoft.com).
    * The implementation was written so as to conform with Netscapes SSL.
    *
    * This library is free for commercial and non-commercial use as long as
    * the following conditions are aheared to.  The following conditions
    * apply to all code found in this distribution, be it the RC4, RSA,
    * lhash, DES, etc., code; not just the SSL code.  The SSL documentation
    * included with this distribution is covered by the same copyright terms
    * except that the holder is Tim Hudson (tjh@cryptsoft.com).
    *
    * Copyright remains Eric Young's, and as such any Copyright notices in
    * the code are not to be removed.
    * If this package is used in a product, Eric Young should be given attribution
    * as the author of the parts of the library used.
    * This can be in the form of a textual message at program startup or
    * in documentation (online or textual) provided with the package.
    *
    * 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 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. All advertising materials mentioning features or use of this software
    *    must display the following acknowledgement:
    *    "This product includes cryptographic software written by
    *     Eric Young (eay@cryptsoft.com)"
    *    The word 'cryptographic' can be left out if the rouines from the library
    *    being used are not cryptographic related :-).
    * 4. If you include any Windows specific code (or a derivative thereof) from
    *    the apps directory (application code) you must include an acknowledgement:
    *    "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
    *
    * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``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.
    *
    * The licence and distribution terms for any publically available version or
    * derivative of this code cannot be changed.  i.e. this code cannot simply be
    * copied and put under another distribution licence
    * [including the GNU Public Licence.]
    */

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 extension 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 is based on the cfuhash project:

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 module is built using an included copy of the libmpdec library unless the build is configured --with-system-libmpdec:

Copyright (c) 2008-2016 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.

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


Download

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

Download Python 3.7.2 Documentation

Last updated on: 02/21/2019.

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. The numbers in the table are the size of the download files in megabytes.

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.

HTML Help (.chm) files are made available in the "Windows" section on the Python download page.

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 InfoZIP 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 InfoZIP zip program.

Problems

If you have comments or suggestions for the Python documentation, please send email to docs@python.org.

ナビゲーション

  • 索引
  • モジュール |


  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引

頭文字別索引:

記号 | _ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z | オ | キ | コ | メ | モ | 例 | 文 | 演 | 環 | 組

総索引 (大きい場合があるので注意)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – _

  • _ (underscore)
    • gettext
    • in numeric literal, [1]
    • in string formatting
  • _, identifiers
  • __, identifiers
  • __abs__() (object のメソッド)
    • (operator モジュール)
  • __add__() (object のメソッド)
    • (operator モジュール)
  • __aenter__() (object のメソッド)
  • __aexit__() (object のメソッド)
  • __aiter__() (object のメソッド)
  • __all__
    • (optional module attribute)
    • (package variable)
  • __and__() (object のメソッド)
    • (operator モジュール)
  • __anext__() (agen のメソッド)
    • (object のメソッド)
  • __annotations__ (class attribute)
    • (function attribute)
    • (module attribute)
  • __await__() (object のメソッド)
  • __bases__ (class attribute)
    • (class の属性)
  • __bool__() (object method)
    • (object のメソッド)
  • __breakpointhook__ (sys モジュール)
  • __bytes__() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (object のメソッド)
  • __cached__
  • __call__() (email.headerregistry.HeaderRegistry のメソッド)
    • (object method)
    • (object のメソッド)
    • (weakref.finalize のメソッド)
  • __callback__ (weakref.ref の属性)
  • __cause__ (exception attribute)
    • (traceback.TracebackException の属性)
  • __ceil__() (fractions.Fraction のメソッド)
    • (object のメソッド)
  • __class__ (instance attribute)
    • (instance の属性)
    • (method cell)
    • (module attribute)
    • (unittest.mock.Mock の属性)
  • __class_getitem__() (object のクラスメソッド)
  • __classcell__ (class namespace entry)
  • __closure__ (function attribute)
  • __code__ (function attribute)
    • (function object attribute)
  • __complex__() (object のメソッド)
  • __concat__() (operator モジュール)
  • __contains__() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (object のメソッド)
    • (operator モジュール)
  • __context__ (exception attribute)
    • (traceback.TracebackException の属性)
  • __copy__() (copy protocol)
  • __debug__
    • (組み込み変数)
  • __deepcopy__() (copy protocol)
  • __defaults__ (function attribute)
  • __del__() (io.IOBase のメソッド)
    • (object のメソッド)
  • __delattr__() (object のメソッド)
  • __delete__() (object のメソッド)
  • __delitem__() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (object のメソッド)
    • (operator モジュール)
  • __dict__ (class attribute)
    • (function attribute)
    • (instance attribute)
    • (module attribute), [1]
    • (object の属性)
  • __dir__ (module attribute)
  • __dir__() (object のメソッド)
    • (unittest.mock.Mock のメソッド)
  • __displayhook__ (sys モジュール)
  • __divmod__() (object のメソッド)
  • __doc__ (class attribute)
    • (function attribute)
    • (method attribute)
    • (module attribute), [1]
    • (types.ModuleType の属性)
  • __enter__() (contextmanager のメソッド)
    • (object のメソッド)
    • (winreg.PyHKEY のメソッド)
  • __eq__() (email.charset.Charset のメソッド)
    • (email.header.Header のメソッド)
    • (instance method)
    • (memoryview のメソッド)
    • (object のメソッド)
    • (operator モジュール)
  • __excepthook__ (sys モジュール)
  • __exit__() (contextmanager のメソッド)
    • (object のメソッド)
    • (winreg.PyHKEY のメソッド)
  • __file__
    • (module attribute), [1], [2]
  • __float__() (object のメソッド)
  • __floor__() (fractions.Fraction のメソッド)
    • (object のメソッド)
  • __floordiv__() (object のメソッド)
    • (operator モジュール)
  • __format__
  • __format__() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (object のメソッド)
  • __fspath__() (os.PathLike のメソッド)
  • __func__ (method attribute)
  • __future__
    • future statement
  • __future__ (モジュール)
  • __ge__() (instance method)
    • (object のメソッド)
    • (operator モジュール)
  • __get__() (object のメソッド)
  • __getattr__ (module attribute)
  • __getattr__() (object のメソッド)
  • __getattribute__() (object のメソッド)
  • __getitem__() (email.headerregistry.HeaderRegistry のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mapping object method)
    • (object のメソッド)
    • (operator モジュール)
    • (re.Match のメソッド)
  • __getnewargs__() (object のメソッド)
  • __getnewargs_ex__() (object のメソッド)
  • __getstate__() (copy protocol)
    • (object のメソッド)
  • __globals__ (function attribute)
  • __gt__() (instance method)
    • (object のメソッド)
    • (operator モジュール)
  • __hash__() (object のメソッド)
  • __iadd__() (object のメソッド)
    • (operator モジュール)
  • __iand__() (object のメソッド)
    • (operator モジュール)
  • __iconcat__() (operator モジュール)
  • __ifloordiv__() (object のメソッド)
    • (operator モジュール)
  • __ilshift__() (object のメソッド)
    • (operator モジュール)
  • __imatmul__() (object のメソッド)
    • (operator モジュール)
  • __imod__() (object のメソッド)
    • (operator モジュール)
  • __import__
    • 組み込み関数
  • __import__() (importlib モジュール)
    • (組み込み関数)
  • __imul__() (object のメソッド)
    • (operator モジュール)
  • __index__() (object のメソッド)
    • (operator モジュール)
  • __init__() (difflib.HtmlDiff のメソッド)
    • (logging.Handler のメソッド)
    • (logging.logging.Formatter のメソッド)
    • (object のメソッド)
  • __init_subclass__() (object のクラスメソッド)
  • __instancecheck__() (class のメソッド)
  • __int__() (object のメソッド)
  • __interactivehook__ (sys モジュール)
  • __inv__() (operator モジュール)
  • __invert__() (object のメソッド)
    • (operator モジュール)
  • __ior__() (object のメソッド)
    • (operator モジュール)
  • __ipow__() (object のメソッド)
    • (operator モジュール)
  • __irshift__() (object のメソッド)
    • (operator モジュール)
  • __isub__() (object のメソッド)
    • (operator モジュール)
  • __iter__() (container のメソッド)
    • (iterator のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (object のメソッド)
    • (unittest.TestSuite のメソッド)
  • __itruediv__() (object のメソッド)
    • (operator モジュール)
  • __ixor__() (object のメソッド)
    • (operator モジュール)
  • __kwdefaults__ (function attribute)
  • __le__() (instance method)
    • (object のメソッド)
    • (operator モジュール)
  • __len__() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mapping object method)
    • (object のメソッド)
  • __length_hint__() (object のメソッド)
  • __loader__
    • (module attribute)
    • (types.ModuleType の属性)
  • __lshift__() (object のメソッド)
    • (operator モジュール)
  • __lt__() (instance method)
    • (object のメソッド)
    • (operator モジュール)
  • __main__
    • モジュール, [1], [2], [3], [4], [5], [6], [7]
  • __main__ (モジュール)
  • __matmul__() (object のメソッド)
    • (operator モジュール)
  • __missing__()
    • (collections.defaultdict のメソッド)
    • (object のメソッド)
  • __mod__() (object のメソッド)
    • (operator モジュール)
  • __module__ (class attribute)
    • (function attribute)
    • (method attribute)
  • __mro__ (class の属性)
  • __mul__() (object のメソッド)
    • (operator モジュール)
  • __name__
    • (class attribute)
    • (definition の属性)
    • (function attribute)
    • (method attribute)
    • (module attribute), [1], [2]
    • (types.ModuleType の属性)
  • __ne__() (email.charset.Charset のメソッド)
    • (email.header.Header のメソッド)
    • (instance method)
    • (object のメソッド)
    • (operator モジュール)
  • __neg__() (object のメソッド)
    • (operator モジュール)
  • __new__() (object のメソッド)
  • __next__() (csv.csvreader のメソッド)
    • (generator のメソッド)
    • (iterator のメソッド)
  • __not__() (operator モジュール)
  • __or__() (object のメソッド)
    • (operator モジュール)
  • __package__
    • (module attribute)
    • (types.ModuleType の属性)
  • __path__
  • __pos__() (object のメソッド)
    • (operator モジュール)
  • __pow__() (object のメソッド)
    • (operator モジュール)
  • __prepare__ (metaclass method)
  • __qualname__ (definition の属性)
  • __radd__() (object のメソッド)
  • __rand__() (object のメソッド)
  • __rdivmod__() (object のメソッド)
  • __reduce__() (object のメソッド)
  • __reduce_ex__() (object のメソッド)
  • __repr__() (multiprocessing.managers.BaseProxy のメソッド)
    • (netrc.netrc のメソッド)
    • (object のメソッド)
  • __reversed__() (object のメソッド)
  • __rfloordiv__() (object のメソッド)
  • __rlshift__() (object のメソッド)
  • __rmatmul__() (object のメソッド)
  • __rmod__() (object のメソッド)
  • __rmul__() (object のメソッド)
  • __ror__() (object のメソッド)
  • __round__() (fractions.Fraction のメソッド)
    • (object のメソッド)
  • __rpow__() (object のメソッド)
  • __rrshift__() (object のメソッド)
  • __rshift__() (object のメソッド)
    • (operator モジュール)
  • __rsub__() (object のメソッド)
  • __rtruediv__() (object のメソッド)
  • __rxor__() (object のメソッド)
  • __self__ (method attribute)
  • __set__() (object のメソッド)
  • __set_name__() (object のメソッド)
  • __setattr__() (object のメソッド)
  • __setitem__() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (object のメソッド)
    • (operator モジュール)
  • __setstate__() (copy protocol)
    • (object のメソッド)
  • __slots__
  • __spec__
  • __stderr__ (sys モジュール)
  • __stdin__ (sys モジュール)
  • __stdout__ (sys モジュール)
  • __str__() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (email.charset.Charset のメソッド)
    • (email.header.Header のメソッド)
    • (email.headerregistry.Address のメソッド)
    • (email.headerregistry.Group のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (multiprocessing.managers.BaseProxy のメソッド)
    • (object のメソッド)
  • __sub__() (object のメソッド)
    • (operator モジュール)
  • __subclasscheck__() (class のメソッド)
  • __subclasses__() (class のメソッド)
  • __subclasshook__() (abc.ABCMeta のメソッド)
  • __suppress_context__ (traceback.TracebackException の属性)
  • __traceback__ (exception attribute)
  • __truediv__() (object のメソッド)
    • (operator モジュール)
  • __trunc__() (object のメソッド)
  • __xor__() (object のメソッド)
    • (operator モジュール)
  • _anonymous_ (ctypes.Structure の属性)
  • _asdict() (collections.somenamedtuple のメソッド)
  • _b_base_ (ctypes._CData の属性)
  • _b_needsfree_ (ctypes._CData の属性)
  • _callmethod() (multiprocessing.managers.BaseProxy のメソッド)
  • _CData (ctypes のクラス)
  • _clear_type_cache() (sys モジュール)
  • _current_frames() (sys モジュール)
  • _debugmallocstats() (sys モジュール)
  • _dummy_thread (モジュール)
  • _enablelegacywindowsfsencoding() (sys モジュール)
  • _exit() (os モジュール)
  • _fields (ast.AST の属性)
    • (collections.somenamedtuple の属性)
  • _fields_ (ctypes.Structure の属性)
  • _fields_defaults (collections.somenamedtuple の属性)
  • _flush() (wsgiref.handlers.BaseHandler のメソッド)
  • _frozen (C のデータ型)
  • _FuncPtr (ctypes のクラス)
  • _get_child_mock() (unittest.mock.Mock のメソッド)
  • _getframe() (sys モジュール)
  • _getvalue() (multiprocessing.managers.BaseProxy のメソッド)
  • _handle (ctypes.PyDLL の属性)
  • _inittab (C のデータ型)
  • _length_ (ctypes.Array の属性)
  • _locale
    • モジュール
  • _make() (collections.somenamedtuple のクラスメソッド)
  • _makeResult() (unittest.TextTestRunner のメソッド)
  • _name (ctypes.PyDLL の属性)
  • _objects (ctypes._CData の属性)
  • _pack_ (ctypes.Structure の属性)
  • _parse() (gettext.NullTranslations のメソッド)
  • _Pointer (ctypes のクラス)
  • _Py_c_diff (C の関数)
  • _Py_c_neg (C の関数)
  • _Py_c_pow (C の関数)
  • _Py_c_prod (C の関数)
  • _Py_c_quot (C の関数)
  • _Py_c_sum (C の関数)
  • _Py_NoneStruct (C の変数)
  • _PyBytes_Resize (C の関数)
  • _PyImport_Fini (C の関数)
  • _PyImport_Init (C の関数)
  • _PyObject_GC_TRACK (C の関数)
  • _PyObject_GC_UNTRACK (C の関数)
  • _PyObject_New (C の関数)
  • _PyObject_NewVar (C の関数)
  • _PyTuple_Resize (C の関数)
  • _replace() (collections.somenamedtuple のメソッド)
  • _setroot() (xml.etree.ElementTree.ElementTree のメソッド)
  • _SimpleCData (ctypes のクラス)
  • _structure() (email.iterators モジュール)
  • _thread
    • モジュール
  • _thread (モジュール)
  • _type_ (ctypes._Pointer の属性)
    • (ctypes.Array の属性)
  • _write() (wsgiref.handlers.BaseHandler のメソッド)
  • _xoptions (sys モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – A

  • A (re モジュール)
  • A-LAW, [1]
  • a-LAW
  • a2b_base64() (binascii モジュール)
  • a2b_hex() (binascii モジュール)
  • a2b_hqx() (binascii モジュール)
  • a2b_qp() (binascii モジュール)
  • a2b_uu() (binascii モジュール)
  • a85decode() (base64 モジュール)
  • a85encode() (base64 モジュール)
  • ABC (abc のクラス)
  • abc (モジュール)
  • ABCMeta (abc のクラス)
  • abiflags (sys モジュール)
  • abort()
    • (asyncio.DatagramTransport のメソッド)
    • (asyncio.WriteTransport のメソッド)
    • (ftplib.FTP のメソッド)
    • (os モジュール)
    • (threading.Barrier のメソッド)
  • above() (curses.panel.Panel のメソッド)
  • ABOVE_NORMAL_PRIORITY_CLASS (subprocess モジュール)
  • abs
    • 組み込み関数, [1]
  • abs() (decimal.Context のメソッド)
    • (operator モジュール)
    • (組み込み関数)
  • abspath() (os.path モジュール)
  • abstract base class
  • AbstractAsyncContextManager (contextlib のクラス)
  • AbstractBasicAuthHandler (urllib.request のクラス)
  • AbstractChildWatcher (asyncio のクラス)
  • abstractclassmethod() (abc モジュール)
  • AbstractContextManager (contextlib のクラス)
  • AbstractDigestAuthHandler (urllib.request のクラス)
  • AbstractEventLoop (asyncio のクラス)
  • AbstractEventLoopPolicy (asyncio のクラス)
  • AbstractFormatter (formatter のクラス)
  • abstractmethod() (abc モジュール)
  • abstractproperty() (abc モジュール)
  • AbstractSet (typing のクラス)
  • abstractstaticmethod() (abc モジュール)
  • AbstractWriter (formatter のクラス)
  • accept() (asyncore.dispatcher のメソッド)
    • (multiprocessing.connection.Listener のメソッド)
    • (socket.socket のメソッド)
  • access() (os モジュール)
  • accumulate() (itertools モジュール)
  • aclose() (agen のメソッド)
    • (contextlib.AsyncExitStack のメソッド)
  • acos() (cmath モジュール)
    • (math モジュール)
  • acosh() (cmath モジュール)
    • (math モジュール)
  • acquire() (_thread.lock のメソッド)
    • (asyncio.Condition のメソッド)
    • (asyncio.Lock のメソッド)
    • (asyncio.Semaphore のメソッド)
    • (logging.Handler のメソッド)
    • (multiprocessing.Lock のメソッド)
    • (multiprocessing.RLock のメソッド)
    • (threading.Condition のメソッド)
    • (threading.Lock のメソッド)
    • (threading.RLock のメソッド)
    • (threading.Semaphore のメソッド)
  • acquire_lock() (imp モジュール)
  • Action (argparse のクラス)
  • action (optparse.Option の属性)
  • ACTIONS (optparse.Option の属性)
  • active_children() (multiprocessing モジュール)
  • active_count() (threading モジュール)
  • add() (audioop モジュール)
    • (decimal.Context のメソッド)
    • (frozenset のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (msilib.RadioButtonGroup のメソッド)
    • (operator モジュール)
    • (pstats.Stats のメソッド)
    • (tarfile.TarFile のメソッド)
    • (tkinter.ttk.Notebook のメソッド)
  • add_alias() (email.charset モジュール)
  • add_alternative() (email.message.EmailMessage のメソッド)
  • add_argument() (argparse.ArgumentParser のメソッド)
  • add_argument_group() (argparse.ArgumentParser のメソッド)
  • add_attachment() (email.message.EmailMessage のメソッド)
  • add_cgi_vars() (wsgiref.handlers.BaseHandler のメソッド)
  • add_charset() (email.charset モジュール)
  • add_child_handler() (asyncio.AbstractChildWatcher のメソッド)
  • add_codec() (email.charset モジュール)
  • add_cookie_header() (http.cookiejar.CookieJar のメソッド)
  • add_data() (msilib モジュール)
  • add_done_callback() (asyncio.Future のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
  • add_fallback() (gettext.NullTranslations のメソッド)
  • add_file() (msilib.Directory のメソッド)
  • add_flag() (mailbox.MaildirMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
    • (mailbox.mboxMessage のメソッド)
  • add_flowing_data() (formatter.formatter のメソッド)
  • add_folder() (mailbox.Maildir のメソッド)
    • (mailbox.MH のメソッド)
  • add_get_handler() (email.contentmanager.ContentManager のメソッド)
  • add_handler() (urllib.request.OpenerDirector のメソッド)
  • add_header() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (urllib.request.Request のメソッド)
    • (wsgiref.headers.Headers のメソッド)
  • add_history() (readline モジュール)
  • add_hor_rule() (formatter.formatter のメソッド)
  • add_include_dir() (distutils.ccompiler.CCompiler のメソッド)
  • add_label() (mailbox.BabylMessage のメソッド)
  • add_label_data() (formatter.formatter のメソッド)
  • add_library() (distutils.ccompiler.CCompiler のメソッド)
  • add_library_dir() (distutils.ccompiler.CCompiler のメソッド)
  • add_line_break() (formatter.formatter のメソッド)
  • add_link_object() (distutils.ccompiler.CCompiler のメソッド)
  • add_literal_data() (formatter.formatter のメソッド)
  • add_mutually_exclusive_group() (argparse.ArgumentParser のメソッド)
  • add_option() (optparse.OptionParser のメソッド)
  • add_parent() (urllib.request.BaseHandler のメソッド)
  • add_password() (urllib.request.HTTPPasswordMgr のメソッド)
    • (urllib.request.HTTPPasswordMgrWithPriorAuth のメソッド)
  • add_reader() (asyncio.loop のメソッド)
  • add_related() (email.message.EmailMessage のメソッド)
  • add_runtime_library_dir() (distutils.ccompiler.CCompiler のメソッド)
  • add_section() (configparser.ConfigParser のメソッド)
    • (configparser.RawConfigParser のメソッド)
  • add_sequence() (mailbox.MHMessage のメソッド)
  • add_set_handler() (email.contentmanager.ContentManager のメソッド)
  • add_signal_handler() (asyncio.loop のメソッド)
  • add_stream() (msilib モジュール)
  • add_subparsers() (argparse.ArgumentParser のメソッド)
  • add_tables() (msilib モジュール)
  • add_type() (mimetypes モジュール)
  • add_unredirected_header() (urllib.request.Request のメソッド)
  • add_writer() (asyncio.loop のメソッド)
  • addch() (curses.window のメソッド)
  • addCleanup() (unittest.TestCase のメソッド)
  • addcomponent() (turtle.Shape のメソッド)
  • addError() (unittest.TestResult のメソッド)
  • addExpectedFailure() (unittest.TestResult のメソッド)
  • addFailure() (unittest.TestResult のメソッド)
  • addfile() (tarfile.TarFile のメソッド)
  • addFilter() (logging.Handler のメソッド)
    • (logging.Logger のメソッド)
  • addHandler() (logging.Logger のメソッド)
  • addition
  • addLevelName() (logging モジュール)
  • addnstr() (curses.window のメソッド)
  • AddPackagePath() (modulefinder モジュール)
  • addr (smtpd.SMTPChannel の属性)
  • addr_spec (email.headerregistry.Address の属性)
  • Address (email.headerregistry のクラス)
  • address (email.headerregistry.SingleAddressHeader の属性)
    • (multiprocessing.connection.Listener の属性)
    • (multiprocessing.managers.BaseManager の属性)
  • address_exclude() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • address_family (socketserver.BaseServer の属性)
  • address_string() (http.server.BaseHTTPRequestHandler のメソッド)
  • addresses (email.headerregistry.AddressHeader の属性)
    • (email.headerregistry.Group の属性)
  • AddressHeader (email.headerregistry のクラス)
  • addressof() (ctypes モジュール)
  • AddressValueError
  • addshape() (turtle モジュール)
  • addsitedir() (site モジュール)
  • addSkip() (unittest.TestResult のメソッド)
  • addstr() (curses.window のメソッド)
  • addSubTest() (unittest.TestResult のメソッド)
  • addSuccess() (unittest.TestResult のメソッド)
  • addTest() (unittest.TestSuite のメソッド)
  • addTests() (unittest.TestSuite のメソッド)
  • addTypeEqualityFunc() (unittest.TestCase のメソッド)
  • addUnexpectedSuccess() (unittest.TestResult のメソッド)
  • adjusted() (decimal.Decimal のメソッド)
  • adler32() (zlib モジュール)
  • ADPCM, Intel/DVI
  • adpcm2lin() (audioop モジュール)
  • AF_ALG (socket モジュール)
  • AF_CAN (socket モジュール)
  • AF_INET (socket モジュール)
  • AF_INET6 (socket モジュール)
  • AF_LINK (socket モジュール)
  • AF_PACKET (socket モジュール)
  • AF_RDS (socket モジュール)
  • AF_UNIX (socket モジュール)
  • AF_VSOCK (socket モジュール)
  • aifc (モジュール)
  • aifc() (aifc.aifc のメソッド)
  • AIFF, [1]
  • aiff() (aifc.aifc のメソッド)
  • AIFF-C, [1]
  • alarm() (signal モジュール)
  • alaw2lin() (audioop モジュール)
  • ALERT_DESCRIPTION_HANDSHAKE_FAILURE (ssl モジュール)
  • ALERT_DESCRIPTION_INTERNAL_ERROR (ssl モジュール)
  • AlertDescription (ssl のクラス)
  • algorithms_available (hashlib モジュール)
  • algorithms_guaranteed (hashlib モジュール)
  • alias (pdb command)
  • alignment() (ctypes モジュール)
  • alive (weakref.finalize の属性)
  • all() (組み込み関数)
  • all_errors (ftplib モジュール)
  • all_features (xml.sax.handler モジュール)
  • all_frames (tracemalloc.Filter の属性)
  • all_properties (xml.sax.handler モジュール)
  • all_suffixes() (importlib.machinery モジュール)
  • all_tasks() (asyncio モジュール)
    • (asyncio.Task のクラスメソッド)
  • allocate_lock() (_thread モジュール)
  • allow_reuse_address (socketserver.BaseServer の属性)
  • allowed_domains() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • alt() (curses.ascii モジュール)
  • ALT_DIGITS (locale モジュール)
  • altsep (os モジュール)
  • altzone (time モジュール)
  • ALWAYS_TYPED_ACTIONS (optparse.Option の属性)
  • AMPER (token モジュール)
  • AMPEREQUAL (token モジュール)
  • and
    • bitwise
    • 演算子, [1], [2]
  • and_() (operator モジュール)
  • annotated
    • assignment
  • annotation
    • (inspect.Parameter の属性)
  • annotations
    • function, [1]
  • announce() (distutils.ccompiler.CCompiler のメソッド)
  • anonymous
    • function
  • answer_challenge() (multiprocessing.connection モジュール)
  • anticipate_failure() (test.support モジュール)
  • Any (typing モジュール)
  • ANY (unittest.mock モジュール)
  • any() (組み込み関数)
  • AnyStr (typing モジュール)
  • api_version (sys モジュール)
  • apop() (poplib.POP3 のメソッド)
  • APPDATA
  • append() (array.array のメソッド)
    • (collections.deque のメソッド)
    • (email.header.Header のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (msilib.CAB のメソッド)
    • (pipes.Template のメソッド)
    • (sequence method)
    • (xml.etree.ElementTree.Element のメソッド)
  • append_history_file() (readline モジュール)
  • appendChild() (xml.dom.Node のメソッド)
  • appendleft() (collections.deque のメソッド)
  • application_uri() (wsgiref.util モジュール)
  • apply (2to3 fixer)
  • apply() (multiprocessing.pool.Pool のメソッド)
  • apply_async() (multiprocessing.pool.Pool のメソッド)
  • apply_defaults() (inspect.BoundArguments のメソッド)
  • architecture() (platform モジュール)
  • archive (zipimport.zipimporter の属性)
  • aRepr (reprlib モジュール)
  • argparse (モジュール)
  • args (BaseException の属性)
    • (functools.partial の属性)
    • (inspect.BoundArguments の属性)
    • (pdb command)
    • (subprocess.CompletedProcess の属性)
    • (subprocess.Popen の属性)
  • args_from_interpreter_flags() (test.support モジュール)
  • argtypes (ctypes._FuncPtr の属性)
  • argument
    • call semantics
    • difference from parameter
    • function
    • function definition
  • ArgumentDefaultsHelpFormatter (argparse のクラス)
  • ArgumentError
  • ArgumentParser (argparse のクラス)
  • arguments (inspect.BoundArguments の属性)
  • argv (in module sys)
    • (sys モジュール)
  • arithmetic
    • conversion
    • operation, binary
    • operation, unary
  • ArithmeticError
  • array
    • モジュール, [1]
  • array (array のクラス)
  • Array (ctypes のクラス)
  • array (モジュール)
  • Array() (multiprocessing モジュール)
    • (multiprocessing.managers.SyncManager のメソッド)
    • (multiprocessing.sharedctypes モジュール)
  • arrays
  • arraysize (sqlite3.Cursor の属性)
  • article() (nntplib.NNTP のメソッド)
  • as
    • except clause
    • import statement
    • with statement
    • キーワード, [1], [2]
  • as_bytes() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • as_completed() (asyncio モジュール)
    • (concurrent.futures モジュール)
  • as_integer_ratio() (decimal.Decimal のメソッド)
    • (float のメソッド)
  • AS_IS (formatter モジュール)
  • as_posix() (pathlib.PurePath のメソッド)
  • as_string() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • as_tuple() (decimal.Decimal のメソッド)
  • as_uri() (pathlib.PurePath のメソッド)
  • ASCII, [1]
  • ascii
    • (re モジュール)
    • 組み込み関数
  • ascii() (curses.ascii モジュール)
    • (組み込み関数)
  • ascii_letters (string モジュール)
  • ascii_lowercase (string モジュール)
  • ascii_uppercase (string モジュール)
  • asctime() (time モジュール)
  • asdict() (dataclasses モジュール)
  • asend() (agen のメソッド)
  • asin() (cmath モジュール)
    • (math モジュール)
  • asinh() (cmath モジュール)
    • (math モジュール)
  • assert
    • 文, [1]
  • assert_any_call() (unittest.mock.Mock のメソッド)
  • assert_called() (unittest.mock.Mock のメソッド)
  • assert_called_once() (unittest.mock.Mock のメソッド)
  • assert_called_once_with() (unittest.mock.Mock のメソッド)
  • assert_called_with() (unittest.mock.Mock のメソッド)
  • assert_has_calls() (unittest.mock.Mock のメソッド)
  • assert_line_data() (formatter.formatter のメソッド)
  • assert_not_called() (unittest.mock.Mock のメソッド)
  • assert_python_failure() (test.support.script_helper モジュール)
  • assert_python_ok() (test.support.script_helper モジュール)
  • assertAlmostEqual() (unittest.TestCase のメソッド)
  • assertCountEqual() (unittest.TestCase のメソッド)
  • assertDictEqual() (unittest.TestCase のメソッド)
  • assertEqual() (unittest.TestCase のメソッド)
  • assertFalse() (unittest.TestCase のメソッド)
  • assertGreater() (unittest.TestCase のメソッド)
  • assertGreaterEqual() (unittest.TestCase のメソッド)
  • assertIn() (unittest.TestCase のメソッド)
  • AssertionError
    • 例外
  • assertions
    • debugging
  • assertIs() (unittest.TestCase のメソッド)
  • assertIsInstance() (unittest.TestCase のメソッド)
  • assertIsNone() (unittest.TestCase のメソッド)
  • assertIsNot() (unittest.TestCase のメソッド)
  • assertIsNotNone() (unittest.TestCase のメソッド)
  • assertLess() (unittest.TestCase のメソッド)
  • assertLessEqual() (unittest.TestCase のメソッド)
  • assertListEqual() (unittest.TestCase のメソッド)
  • assertLogs() (unittest.TestCase のメソッド)
  • assertMultiLineEqual() (unittest.TestCase のメソッド)
  • assertNotAlmostEqual() (unittest.TestCase のメソッド)
  • assertNotEqual() (unittest.TestCase のメソッド)
  • assertNotIn() (unittest.TestCase のメソッド)
  • assertNotIsInstance() (unittest.TestCase のメソッド)
  • assertNotRegex() (unittest.TestCase のメソッド)
  • assertRaises() (unittest.TestCase のメソッド)
  • assertRaisesRegex() (unittest.TestCase のメソッド)
  • assertRegex() (unittest.TestCase のメソッド)
  • asserts (2to3 fixer)
  • assertSequenceEqual() (unittest.TestCase のメソッド)
  • assertSetEqual() (unittest.TestCase のメソッド)
  • assertTrue() (unittest.TestCase のメソッド)
  • assertTupleEqual() (unittest.TestCase のメソッド)
  • assertWarns() (unittest.TestCase のメソッド)
  • assertWarnsRegex() (unittest.TestCase のメソッド)
  • assignment
    • annotated
    • attribute, [1]
    • augmented
    • class attribute
    • class instance attribute
    • slice
    • slicing
    • statement, [1]
    • subscript
    • subscription
    • target list
  • AST (ast のクラス)
  • ast (モジュール)
  • astimezone() (datetime.datetime のメソッド)
  • astuple() (dataclasses モジュール)
  • async
    • キーワード
  • async def
    • 文
  • async for
    • in comprehensions
    • 文
  • async with
    • 文
  • async_chat (asynchat のクラス)
  • async_chat.ac_in_buffer_size (asynchat モジュール)
  • async_chat.ac_out_buffer_size (asynchat モジュール)
  • AsyncContextManager (typing のクラス)
  • asynccontextmanager() (contextlib モジュール)
  • AsyncExitStack (contextlib のクラス)
  • AsyncGenerator (collections.abc のクラス)
    • (typing のクラス)
  • AsyncGeneratorType (types モジュール)
  • asynchat (モジュール)
  • asynchronous context manager
  • asynchronous generator
    • asynchronous iterator
    • function
  • asynchronous generator iterator
  • asynchronous iterable
  • asynchronous iterator
  • asynchronous-generator
    • オブジェクト
  • asyncio (モジュール)
  • asyncio.subprocess.DEVNULL (asyncio モジュール)
  • asyncio.subprocess.PIPE (asyncio モジュール)
  • asyncio.subprocess.Process (asyncio のクラス)
  • asyncio.subprocess.STDOUT (asyncio モジュール)
  • AsyncIterable (collections.abc のクラス)
    • (typing のクラス)
  • AsyncIterator (collections.abc のクラス)
    • (typing のクラス)
  • asyncore (モジュール)
  • AsyncResult (multiprocessing.pool のクラス)
  • AT (token モジュール)
  • at_eof() (asyncio.StreamReader のメソッド)
  • atan() (cmath モジュール)
    • (math モジュール)
  • atan2() (math モジュール)
  • atanh() (cmath モジュール)
    • (math モジュール)
  • ATEQUAL (token モジュール)
  • atexit (weakref.finalize の属性)
    • (モジュール)
  • athrow() (agen のメソッド)
  • atof() (locale モジュール)
  • atoi() (locale モジュール)
  • atom
  • attach() (email.message.Message のメソッド)
  • attach_loop() (asyncio.AbstractChildWatcher のメソッド)
  • attach_mock() (unittest.mock.Mock のメソッド)
  • AttlistDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • attrgetter() (operator モジュール)
  • attrib (xml.etree.ElementTree.Element の属性)
  • attribute, [1]
    • assignment, [1]
    • assignment, class
    • assignment, class instance
    • class
    • class instance
    • deletion
    • generic special
    • reference
    • special
  • AttributeError
    • 例外
  • attributes (xml.dom.Node の属性)
  • AttributesImpl (xml.sax.xmlreader のクラス)
  • AttributesNSImpl (xml.sax.xmlreader のクラス)
  • attroff() (curses.window のメソッド)
  • attron() (curses.window のメソッド)
  • attrset() (curses.window のメソッド)
  • Audio Interchange File Format, [1]
  • 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 (sunau モジュール)
  • AUDIO_FILE_ENCODING_ALAW_8 (sunau モジュール)
  • AUDIO_FILE_ENCODING_DOUBLE (sunau モジュール)
  • AUDIO_FILE_ENCODING_FLOAT (sunau モジュール)
  • AUDIO_FILE_ENCODING_LINEAR_16 (sunau モジュール)
  • AUDIO_FILE_ENCODING_LINEAR_24 (sunau モジュール)
  • AUDIO_FILE_ENCODING_LINEAR_32 (sunau モジュール)
  • AUDIO_FILE_ENCODING_LINEAR_8 (sunau モジュール)
  • AUDIO_FILE_ENCODING_MULAW_8 (sunau モジュール)
  • AUDIO_FILE_MAGIC (sunau モジュール)
  • AUDIODEV
  • audioop (モジュール)
  • augmented
    • assignment
  • auth() (ftplib.FTP_TLS のメソッド)
    • (smtplib.SMTP のメソッド)
  • authenticate() (imaplib.IMAP4 のメソッド)
  • AuthenticationError
  • authenticators() (netrc.netrc のメソッド)
  • authkey (multiprocessing.Process の属性)
  • auto (enum のクラス)
  • autorange() (timeit.Timer のメソッド)
  • avg() (audioop モジュール)
  • avgpp() (audioop モジュール)
  • avoids_symlink_attacks (shutil.rmtree の属性)
  • await
    • in comprehensions
    • キーワード, [1]
  • awaitable
  • Awaitable (collections.abc のクラス)
    • (typing のクラス)

ナビゲーション

  • 索引
  • モジュール |


  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引

記号 | _ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z | オ | キ | コ | メ | モ | 例 | 文 | 演 | 環 | 組

記号

  • ! (exclamation)
    • in a command interpreter
    • in curses module
    • in formatted string literal
    • in glob-style wildcards, [1]
    • in string formatting
    • in struct format strings
  • ! (pdb command)
  • !=
    • 演算子, [1]
  • " (double quote)
    • string literal
  • """
    • string literal
  • # (hash)
    • comment, [1], [2]
    • in doctests
    • in printf-style formatting, [1]
    • in regular expressions
    • in string formatting
    • source encoding declaration
  • $ (dollar)
    • environment variables expansion
    • in regular expressions
    • in template strings
    • interpolation in configuration files
  • % (percent)
    • datetime format, [1], [2]
    • environment variables expansion (Windows), [1]
    • interpolation in configuration files
    • printf-style formatting, [1]
    • 演算子, [1]
  • %=
    • augmented assignment
  • & (ampersand)
    • 演算子, [1]
  • &=
    • augmented assignment
  • ' (single quote)
    • string literal
  • '''
    • string literal
  • () (parentheses)
    • call
    • class definition
    • function definition
    • generator expression
    • in assignment target list
    • in printf-style formatting, [1]
    • in regular expressions
    • tuple display
  • (?
    • in regular expressions
  • (?!
    • in regular expressions
  • (?#
    • in regular expressions
  • (?:
    • in regular expressions
  • (?<!
    • in regular expressions
  • (?<=
    • in regular expressions
  • (?P<
    • in regular expressions
  • (?P=
    • in regular expressions
  • * (asterisk)
    • function definition
    • import statement
    • in AST grammar
    • in argparse module
    • in assignment target list
    • in expression lists
    • in function calls, [1]
    • in glob-style wildcards, [1]
    • in printf-style formatting, [1]
    • in regular expressions
    • 演算子, [1]
  • **
    • function definition
    • in dictionary displays
    • in function calls, [1]
    • in glob-style wildcards
    • 演算子, [1]
  • **=
    • augmented assignment
  • *=
    • augmented assignment
  • *?
    • in regular expressions
  • + (plus)
    • binary operator, [1]
    • in argparse module
    • in doctests
    • in printf-style formatting, [1]
    • in regular expressions
    • in string formatting
    • unary operator, [1]
  • +=
    • augmented assignment
  • +?
    • in regular expressions
  • , (comma)
    • argument list
    • expression list, [1], [2], [3], [4]
    • identifier list, [1]
    • import statement
    • in dictionary displays
    • in string formatting
    • in target list
    • parameter list
    • slicing
    • tuple display
    • with statement
  • - (minus)
    • binary operator, [1]
    • in doctests
    • in glob-style wildcards, [1]
    • in printf-style formatting, [1]
    • in regular expressions
    • in string formatting
    • unary operator, [1]
  • --check-hash-based-pycs default|always|never
    • コマンドラインオプション
  • --create <tarfile> <source1> ... <sourceN>
    • tarfile コマンドラインオプション
  • --create <zipfile> <source1> ... <sourceN>
    • zipfile コマンドラインオプション
  • --details
    • inspect コマンドラインオプション
  • --extract <tarfile> [<output_dir>]
    • tarfile コマンドラインオプション
  • --extract <zipfile> <output_dir>
    • zipfile コマンドラインオプション
  • --help
    • trace コマンドラインオプション
    • コマンドラインオプション
  • --ignore-dir=<dir>
    • trace コマンドラインオプション
  • --ignore-module=<mod>
    • trace コマンドラインオプション
  • --info
    • zipapp コマンドラインオプション
  • --invalidation-mode [timestamp|checked-hash|unchecked-hash]
    • compileall コマンドラインオプション
  • --list <tarfile>
    • tarfile コマンドラインオプション
  • --list <zipfile>
    • zipfile コマンドラインオプション
  • --locals
    • unittest コマンドラインオプション
  • --sort-keys
    • json.tool コマンドラインオプション
  • --test <tarfile>
    • tarfile コマンドラインオプション
  • --test <zipfile>
    • zipfile コマンドラインオプション
  • --user-base
    • site コマンドラインオプション
  • --user-site
    • site コマンドラインオプション
  • --version
    • trace コマンドラインオプション
    • コマンドラインオプション
  • -=
    • augmented assignment
  • ->
    • function annotations, [1]
  • -?
    • コマンドラインオプション
  • -a, --annotate
    • pickletools コマンドラインオプション
  • -B
    • コマンドラインオプション
  • -b
    • compileall コマンドラインオプション
    • コマンドラインオプション
  • -b, --buffer
    • unittest コマンドラインオプション
  • -c <command>
    • コマンドラインオプション
  • -c <tarfile> <source1> ... <sourceN>
    • tarfile コマンドラインオプション
  • -c <zipfile> <source1> ... <sourceN>
    • zipfile コマンドラインオプション
  • -c, --catch
    • unittest コマンドラインオプション
  • -c, --compress
    • zipapp コマンドラインオプション
  • -c, --count
    • trace コマンドラインオプション
  • -C, --coverdir=<dir>
    • trace コマンドラインオプション
  • -d
    • コマンドラインオプション
  • -d destdir
    • compileall コマンドラインオプション
  • -E
    • コマンドラインオプション
  • -e <tarfile> [<output_dir>]
    • tarfile コマンドラインオプション
  • -e <zipfile> <output_dir>
    • zipfile コマンドラインオプション
  • -e, --exact
    • tokenize コマンドラインオプション
  • -f
    • compileall コマンドラインオプション
  • -f, --failfast
    • unittest コマンドラインオプション
  • -f, --file=<file>
    • trace コマンドラインオプション
  • -g, --timing
    • trace コマンドラインオプション
  • -h
    • コマンドラインオプション
  • -h, --help
    • json.tool コマンドラインオプション
    • timeit コマンドラインオプション
    • tokenize コマンドラインオプション
    • zipapp コマンドラインオプション
  • -I
    • コマンドラインオプション
  • -i
    • コマンドラインオプション
  • -i list
    • compileall コマンドラインオプション
  • -J
    • コマンドラインオプション
  • -j N
    • compileall コマンドラインオプション
  • -k
    • unittest コマンドラインオプション
  • -l
    • compileall コマンドラインオプション
  • -l <tarfile>
    • tarfile コマンドラインオプション
  • -l <zipfile>
    • zipfile コマンドラインオプション
  • -l, --indentlevel=<num>
    • pickletools コマンドラインオプション
  • -l, --listfuncs
    • trace コマンドラインオプション
  • -m <mainfn>, --main=<mainfn>
    • zipapp コマンドラインオプション
  • -m <module-name>
    • コマンドラインオプション
  • -m, --memo
    • pickletools コマンドラインオプション
  • -m, --missing
    • trace コマンドラインオプション
  • -n N, --number=N
    • timeit コマンドラインオプション
  • -O
    • コマンドラインオプション
  • -o <output>, --output=<output>
    • zipapp コマンドラインオプション
  • -o, --output=<file>
    • pickletools コマンドラインオプション
  • -OO
    • コマンドラインオプション
  • -p <interpreter>, --python=<interpreter>
    • zipapp コマンドラインオプション
  • -p, --pattern pattern
    • unittest-discover コマンドラインオプション
  • -p, --preamble=<preamble>
    • pickletools コマンドラインオプション
  • -p, --process
    • timeit コマンドラインオプション
  • -q
    • compileall コマンドラインオプション
    • コマンドラインオプション
  • -R
    • コマンドラインオプション
  • -r
    • compileall コマンドラインオプション
  • -r N, --repeat=N
    • timeit コマンドラインオプション
  • -R, --no-report
    • trace コマンドラインオプション
  • -r, --report
    • trace コマンドラインオプション
  • -S
    • コマンドラインオプション
  • -s
    • コマンドラインオプション
  • -s S, --setup=S
    • timeit コマンドラインオプション
  • -s, --start-directory directory
    • unittest-discover コマンドラインオプション
  • -s, --summary
    • trace コマンドラインオプション
  • -t <tarfile>
    • tarfile コマンドラインオプション
  • -t <zipfile>
    • zipfile コマンドラインオプション
  • -t, --top-level-directory directory
    • unittest-discover コマンドラインオプション
  • -t, --trace
    • trace コマンドラインオプション
  • -T, --trackcalls
    • trace コマンドラインオプション
  • -u
    • コマンドラインオプション
  • -u, --unit=U
    • timeit コマンドラインオプション
  • -V
    • コマンドラインオプション
  • -v
    • コマンドラインオプション
  • -v, --verbose
    • tarfile コマンドラインオプション
    • timeit コマンドラインオプション
    • unittest-discover コマンドラインオプション
  • -W arg
    • コマンドラインオプション
  • -X
    • コマンドラインオプション
  • -x
    • コマンドラインオプション
  • -x regex
    • compileall コマンドラインオプション
  • . (dot)
    • attribute reference
    • in Tkinter
    • in glob-style wildcards
    • in numeric literal
    • in pathnames, [1]
    • in printf-style formatting, [1]
    • in regular expressions
    • in string formatting
  • ..
    • in pathnames
  • ...
    • ellipsis literal, [1], [2]
    • in doctests
    • interpreter prompt, [1]
    • placeholder, [1], [2]
  • .ini
    • file
  • .pdbrc
    • file
  • .pypirc file
  • / (slash)
    • in pathnames, [1]
    • 演算子, [1]
  • //
    • 演算子, [1]
  • //=
    • augmented assignment
  • /=
    • augmented assignment
  • 0b
    • integer literal
  • 0o
    • integer literal
  • 0x
    • integer literal
  • 2to3
  • : (colon)
    • annotated variable
    • compound statement, [1], [2], [3], [4], [5], [6]
    • function annotations, [1]
    • in SQL statements
    • in dictionary expressions
    • in formatted string literal
    • in string formatting
    • lambda expression
    • path separator (POSIX)
    • slicing
  • ; (semicolon), [1]
  • < (less)
    • in string formatting
    • in struct format strings
    • 演算子, [1]
  • <<
    • 演算子, [1]
  • <<=
    • augmented assignment
  • <=
    • 演算子, [1]
  • <BLANKLINE>
  • = (equals)
    • assignment statement
    • class definition
    • function definition
    • in function calls
    • in string formatting
    • in struct format strings
  • ==
    • 演算子, [1]
  • > (greater)
    • in string formatting
    • in struct format strings
    • 演算子, [1]
  • >=
    • 演算子, [1]
  • >>
    • 演算子, [1]
  • >>=
    • augmented assignment
  • >>>
    • interpreter prompt, [1]
  • ? (question mark)
    • in AST grammar
    • in SQL statements
    • in a command interpreter
    • in argparse module
    • in glob-style wildcards, [1]
    • in regular expressions
    • in struct format strings, [1]
    • replacement character
  • ??
    • in regular expressions
  • @ (at)
    • class definition
    • function definition
    • in struct format strings
    • 演算子
  • [] (square brackets)
    • in assignment target list
    • in glob-style wildcards, [1]
    • in regular expressions
    • in string formatting
    • list expression
    • subscription
  • \ (backslash)
    • escape sequence, [1]
    • in pathnames (Windows)
    • in regular expressions, [1], [2]
  • \\
    • escape sequence
    • in regular expressions
  • \A
    • in regular expressions
  • \a
    • escape sequence
    • in regular expressions
  • \B
    • in regular expressions
  • \b
    • escape sequence
    • in regular expressions, [1]
  • \D
    • in regular expressions
  • \d
    • in regular expressions
  • \f
    • escape sequence
    • in regular expressions
  • \g
    • in regular expressions
  • \N
    • escape sequence, [1]
    • in regular expressions
  • \n
    • escape sequence
    • in regular expressions
  • \r
    • escape sequence
    • in regular expressions
  • \S
    • in regular expressions
  • \s
    • in regular expressions
  • \t
    • escape sequence
    • in regular expressions
  • \U
    • escape sequence, [1]
    • in regular expressions
  • \u
    • escape sequence, [1]
    • in regular expressions
  • \v
    • escape sequence
    • in regular expressions
  • \W
    • in regular expressions
  • \w
    • in regular expressions
  • \x
    • escape sequence, [1]
    • in regular expressions
  • \Z
    • in regular expressions
  • ^ (caret)
    • in curses module
    • in regular expressions, [1]
    • in string formatting
    • marker, [1]
    • 演算子, [1]
  • ^=
    • augmented assignment
  • {} (curly brackets)
    • dictionary expression
    • in formatted string literal
    • in regular expressions
    • in string formatting
    • set expression
  • | (vertical bar)
    • in regular expressions
    • 演算子, [1]
  • |=
    • augmented assignment
  • ~ (tilde)
    • home directory expansion
    • 演算子, [1]

_

  • _ (underscore)
    • gettext
    • in numeric literal, [1]
    • in string formatting
  • _, identifiers
  • __, identifiers
  • __abs__() (object のメソッド)
    • (operator モジュール)
  • __add__() (object のメソッド)
    • (operator モジュール)
  • __aenter__() (object のメソッド)
  • __aexit__() (object のメソッド)
  • __aiter__() (object のメソッド)
  • __all__
    • (optional module attribute)
    • (package variable)
  • __and__() (object のメソッド)
    • (operator モジュール)
  • __anext__() (agen のメソッド)
    • (object のメソッド)
  • __annotations__ (class attribute)
    • (function attribute)
    • (module attribute)
  • __await__() (object のメソッド)
  • __bases__ (class attribute)
    • (class の属性)
  • __bool__() (object method)
    • (object のメソッド)
  • __breakpointhook__ (sys モジュール)
  • __bytes__() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (object のメソッド)
  • __cached__
  • __call__() (email.headerregistry.HeaderRegistry のメソッド)
    • (object method)
    • (object のメソッド)
    • (weakref.finalize のメソッド)
  • __callback__ (weakref.ref の属性)
  • __cause__ (exception attribute)
    • (traceback.TracebackException の属性)
  • __ceil__() (fractions.Fraction のメソッド)
    • (object のメソッド)
  • __class__ (instance attribute)
    • (instance の属性)
    • (method cell)
    • (module attribute)
    • (unittest.mock.Mock の属性)
  • __class_getitem__() (object のクラスメソッド)
  • __classcell__ (class namespace entry)
  • __closure__ (function attribute)
  • __code__ (function attribute)
    • (function object attribute)
  • __complex__() (object のメソッド)
  • __concat__() (operator モジュール)
  • __contains__() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (object のメソッド)
    • (operator モジュール)
  • __context__ (exception attribute)
    • (traceback.TracebackException の属性)
  • __copy__() (copy protocol)
  • __debug__
    • (組み込み変数)
  • __deepcopy__() (copy protocol)
  • __defaults__ (function attribute)
  • __del__() (io.IOBase のメソッド)
    • (object のメソッド)
  • __delattr__() (object のメソッド)
  • __delete__() (object のメソッド)
  • __delitem__() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (object のメソッド)
    • (operator モジュール)
  • __dict__ (class attribute)
    • (function attribute)
    • (instance attribute)
    • (module attribute), [1]
    • (object の属性)
  • __dir__ (module attribute)
  • __dir__() (object のメソッド)
    • (unittest.mock.Mock のメソッド)
  • __displayhook__ (sys モジュール)
  • __divmod__() (object のメソッド)
  • __doc__ (class attribute)
    • (function attribute)
    • (method attribute)
    • (module attribute), [1]
    • (types.ModuleType の属性)
  • __enter__() (contextmanager のメソッド)
    • (object のメソッド)
    • (winreg.PyHKEY のメソッド)
  • __eq__() (email.charset.Charset のメソッド)
    • (email.header.Header のメソッド)
    • (instance method)
    • (memoryview のメソッド)
    • (object のメソッド)
    • (operator モジュール)
  • __excepthook__ (sys モジュール)
  • __exit__() (contextmanager のメソッド)
    • (object のメソッド)
    • (winreg.PyHKEY のメソッド)
  • __file__
    • (module attribute), [1], [2]
  • __float__() (object のメソッド)
  • __floor__() (fractions.Fraction のメソッド)
    • (object のメソッド)
  • __floordiv__() (object のメソッド)
    • (operator モジュール)
  • __format__
  • __format__() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (object のメソッド)
  • __fspath__() (os.PathLike のメソッド)
  • __func__ (method attribute)
  • __future__
    • future statement
  • __future__ (モジュール)
  • __ge__() (instance method)
    • (object のメソッド)
    • (operator モジュール)
  • __get__() (object のメソッド)
  • __getattr__ (module attribute)
  • __getattr__() (object のメソッド)
  • __getattribute__() (object のメソッド)
  • __getitem__() (email.headerregistry.HeaderRegistry のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mapping object method)
    • (object のメソッド)
    • (operator モジュール)
    • (re.Match のメソッド)
  • __getnewargs__() (object のメソッド)
  • __getnewargs_ex__() (object のメソッド)
  • __getstate__() (copy protocol)
    • (object のメソッド)
  • __globals__ (function attribute)
  • __gt__() (instance method)
    • (object のメソッド)
    • (operator モジュール)
  • __hash__() (object のメソッド)
  • __iadd__() (object のメソッド)
    • (operator モジュール)
  • __iand__() (object のメソッド)
    • (operator モジュール)
  • __iconcat__() (operator モジュール)
  • __ifloordiv__() (object のメソッド)
    • (operator モジュール)
  • __ilshift__() (object のメソッド)
    • (operator モジュール)
  • __imatmul__() (object のメソッド)
    • (operator モジュール)
  • __imod__() (object のメソッド)
    • (operator モジュール)
  • __import__
    • 組み込み関数
  • __import__() (importlib モジュール)
    • (組み込み関数)
  • __imul__() (object のメソッド)
    • (operator モジュール)
  • __index__() (object のメソッド)
    • (operator モジュール)
  • __init__() (difflib.HtmlDiff のメソッド)
    • (logging.Handler のメソッド)
    • (logging.logging.Formatter のメソッド)
    • (object のメソッド)
  • __init_subclass__() (object のクラスメソッド)
  • __instancecheck__() (class のメソッド)
  • __int__() (object のメソッド)
  • __interactivehook__ (sys モジュール)
  • __inv__() (operator モジュール)
  • __invert__() (object のメソッド)
    • (operator モジュール)
  • __ior__() (object のメソッド)
    • (operator モジュール)
  • __ipow__() (object のメソッド)
    • (operator モジュール)
  • __irshift__() (object のメソッド)
    • (operator モジュール)
  • __isub__() (object のメソッド)
    • (operator モジュール)
  • __iter__() (container のメソッド)
    • (iterator のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (object のメソッド)
    • (unittest.TestSuite のメソッド)
  • __itruediv__() (object のメソッド)
    • (operator モジュール)
  • __ixor__() (object のメソッド)
    • (operator モジュール)
  • __kwdefaults__ (function attribute)
  • __le__() (instance method)
    • (object のメソッド)
    • (operator モジュール)
  • __len__() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mapping object method)
    • (object のメソッド)
  • __length_hint__() (object のメソッド)
  • __loader__
    • (module attribute)
    • (types.ModuleType の属性)
  • __lshift__() (object のメソッド)
    • (operator モジュール)
  • __lt__() (instance method)
    • (object のメソッド)
    • (operator モジュール)
  • __main__
    • モジュール, [1], [2], [3], [4], [5], [6], [7]
  • __main__ (モジュール)
  • __matmul__() (object のメソッド)
    • (operator モジュール)
  • __missing__()
    • (collections.defaultdict のメソッド)
    • (object のメソッド)
  • __mod__() (object のメソッド)
    • (operator モジュール)
  • __module__ (class attribute)
    • (function attribute)
    • (method attribute)
  • __mro__ (class の属性)
  • __mul__() (object のメソッド)
    • (operator モジュール)
  • __name__
    • (class attribute)
    • (definition の属性)
    • (function attribute)
    • (method attribute)
    • (module attribute), [1], [2]
    • (types.ModuleType の属性)
  • __ne__() (email.charset.Charset のメソッド)
    • (email.header.Header のメソッド)
    • (instance method)
    • (object のメソッド)
    • (operator モジュール)
  • __neg__() (object のメソッド)
    • (operator モジュール)
  • __new__() (object のメソッド)
  • __next__() (csv.csvreader のメソッド)
    • (generator のメソッド)
    • (iterator のメソッド)
  • __not__() (operator モジュール)
  • __or__() (object のメソッド)
    • (operator モジュール)
  • __package__
    • (module attribute)
    • (types.ModuleType の属性)
  • __path__
  • __pos__() (object のメソッド)
    • (operator モジュール)
  • __pow__() (object のメソッド)
    • (operator モジュール)
  • __prepare__ (metaclass method)
  • __qualname__ (definition の属性)
  • __radd__() (object のメソッド)
  • __rand__() (object のメソッド)
  • __rdivmod__() (object のメソッド)
  • __reduce__() (object のメソッド)
  • __reduce_ex__() (object のメソッド)
  • __repr__() (multiprocessing.managers.BaseProxy のメソッド)
    • (netrc.netrc のメソッド)
    • (object のメソッド)
  • __reversed__() (object のメソッド)
  • __rfloordiv__() (object のメソッド)
  • __rlshift__() (object のメソッド)
  • __rmatmul__() (object のメソッド)
  • __rmod__() (object のメソッド)
  • __rmul__() (object のメソッド)
  • __ror__() (object のメソッド)
  • __round__() (fractions.Fraction のメソッド)
    • (object のメソッド)
  • __rpow__() (object のメソッド)
  • __rrshift__() (object のメソッド)
  • __rshift__() (object のメソッド)
    • (operator モジュール)
  • __rsub__() (object のメソッド)
  • __rtruediv__() (object のメソッド)
  • __rxor__() (object のメソッド)
  • __self__ (method attribute)
  • __set__() (object のメソッド)
  • __set_name__() (object のメソッド)
  • __setattr__() (object のメソッド)
  • __setitem__() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (object のメソッド)
    • (operator モジュール)
  • __setstate__() (copy protocol)
    • (object のメソッド)
  • __slots__
  • __spec__
  • __stderr__ (sys モジュール)
  • __stdin__ (sys モジュール)
  • __stdout__ (sys モジュール)
  • __str__() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (email.charset.Charset のメソッド)
    • (email.header.Header のメソッド)
    • (email.headerregistry.Address のメソッド)
    • (email.headerregistry.Group のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (multiprocessing.managers.BaseProxy のメソッド)
    • (object のメソッド)
  • __sub__() (object のメソッド)
    • (operator モジュール)
  • __subclasscheck__() (class のメソッド)
  • __subclasses__() (class のメソッド)
  • __subclasshook__() (abc.ABCMeta のメソッド)
  • __suppress_context__ (traceback.TracebackException の属性)
  • __traceback__ (exception attribute)
  • __truediv__() (object のメソッド)
    • (operator モジュール)
  • __trunc__() (object のメソッド)
  • __xor__() (object のメソッド)
    • (operator モジュール)
  • _anonymous_ (ctypes.Structure の属性)
  • _asdict() (collections.somenamedtuple のメソッド)
  • _b_base_ (ctypes._CData の属性)
  • _b_needsfree_ (ctypes._CData の属性)
  • _callmethod() (multiprocessing.managers.BaseProxy のメソッド)
  • _CData (ctypes のクラス)
  • _clear_type_cache() (sys モジュール)
  • _current_frames() (sys モジュール)
  • _debugmallocstats() (sys モジュール)
  • _dummy_thread (モジュール)
  • _enablelegacywindowsfsencoding() (sys モジュール)
  • _exit() (os モジュール)
  • _fields (ast.AST の属性)
    • (collections.somenamedtuple の属性)
  • _fields_ (ctypes.Structure の属性)
  • _fields_defaults (collections.somenamedtuple の属性)
  • _flush() (wsgiref.handlers.BaseHandler のメソッド)
  • _frozen (C のデータ型)
  • _FuncPtr (ctypes のクラス)
  • _get_child_mock() (unittest.mock.Mock のメソッド)
  • _getframe() (sys モジュール)
  • _getvalue() (multiprocessing.managers.BaseProxy のメソッド)
  • _handle (ctypes.PyDLL の属性)
  • _inittab (C のデータ型)
  • _length_ (ctypes.Array の属性)
  • _locale
    • モジュール
  • _make() (collections.somenamedtuple のクラスメソッド)
  • _makeResult() (unittest.TextTestRunner のメソッド)
  • _name (ctypes.PyDLL の属性)
  • _objects (ctypes._CData の属性)
  • _pack_ (ctypes.Structure の属性)
  • _parse() (gettext.NullTranslations のメソッド)
  • _Pointer (ctypes のクラス)
  • _Py_c_diff (C の関数)
  • _Py_c_neg (C の関数)
  • _Py_c_pow (C の関数)
  • _Py_c_prod (C の関数)
  • _Py_c_quot (C の関数)
  • _Py_c_sum (C の関数)
  • _Py_NoneStruct (C の変数)
  • _PyBytes_Resize (C の関数)
  • _PyImport_Fini (C の関数)
  • _PyImport_Init (C の関数)
  • _PyObject_GC_TRACK (C の関数)
  • _PyObject_GC_UNTRACK (C の関数)
  • _PyObject_New (C の関数)
  • _PyObject_NewVar (C の関数)
  • _PyTuple_Resize (C の関数)
  • _replace() (collections.somenamedtuple のメソッド)
  • _setroot() (xml.etree.ElementTree.ElementTree のメソッド)
  • _SimpleCData (ctypes のクラス)
  • _structure() (email.iterators モジュール)
  • _thread
    • モジュール
  • _thread (モジュール)
  • _type_ (ctypes._Pointer の属性)
    • (ctypes.Array の属性)
  • _write() (wsgiref.handlers.BaseHandler のメソッド)
  • _xoptions (sys モジュール)

A

  • A (re モジュール)
  • A-LAW, [1]
  • a-LAW
  • a2b_base64() (binascii モジュール)
  • a2b_hex() (binascii モジュール)
  • a2b_hqx() (binascii モジュール)
  • a2b_qp() (binascii モジュール)
  • a2b_uu() (binascii モジュール)
  • a85decode() (base64 モジュール)
  • a85encode() (base64 モジュール)
  • ABC (abc のクラス)
  • abc (モジュール)
  • ABCMeta (abc のクラス)
  • abiflags (sys モジュール)
  • abort()
    • (asyncio.DatagramTransport のメソッド)
    • (asyncio.WriteTransport のメソッド)
    • (ftplib.FTP のメソッド)
    • (os モジュール)
    • (threading.Barrier のメソッド)
  • above() (curses.panel.Panel のメソッド)
  • ABOVE_NORMAL_PRIORITY_CLASS (subprocess モジュール)
  • abs
    • 組み込み関数, [1]
  • abs() (decimal.Context のメソッド)
    • (operator モジュール)
    • (組み込み関数)
  • abspath() (os.path モジュール)
  • abstract base class
  • AbstractAsyncContextManager (contextlib のクラス)
  • AbstractBasicAuthHandler (urllib.request のクラス)
  • AbstractChildWatcher (asyncio のクラス)
  • abstractclassmethod() (abc モジュール)
  • AbstractContextManager (contextlib のクラス)
  • AbstractDigestAuthHandler (urllib.request のクラス)
  • AbstractEventLoop (asyncio のクラス)
  • AbstractEventLoopPolicy (asyncio のクラス)
  • AbstractFormatter (formatter のクラス)
  • abstractmethod() (abc モジュール)
  • abstractproperty() (abc モジュール)
  • AbstractSet (typing のクラス)
  • abstractstaticmethod() (abc モジュール)
  • AbstractWriter (formatter のクラス)
  • accept() (asyncore.dispatcher のメソッド)
    • (multiprocessing.connection.Listener のメソッド)
    • (socket.socket のメソッド)
  • access() (os モジュール)
  • accumulate() (itertools モジュール)
  • aclose() (agen のメソッド)
    • (contextlib.AsyncExitStack のメソッド)
  • acos() (cmath モジュール)
    • (math モジュール)
  • acosh() (cmath モジュール)
    • (math モジュール)
  • acquire() (_thread.lock のメソッド)
    • (asyncio.Condition のメソッド)
    • (asyncio.Lock のメソッド)
    • (asyncio.Semaphore のメソッド)
    • (logging.Handler のメソッド)
    • (multiprocessing.Lock のメソッド)
    • (multiprocessing.RLock のメソッド)
    • (threading.Condition のメソッド)
    • (threading.Lock のメソッド)
    • (threading.RLock のメソッド)
    • (threading.Semaphore のメソッド)
  • acquire_lock() (imp モジュール)
  • Action (argparse のクラス)
  • action (optparse.Option の属性)
  • ACTIONS (optparse.Option の属性)
  • active_children() (multiprocessing モジュール)
  • active_count() (threading モジュール)
  • add() (audioop モジュール)
    • (decimal.Context のメソッド)
    • (frozenset のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (msilib.RadioButtonGroup のメソッド)
    • (operator モジュール)
    • (pstats.Stats のメソッド)
    • (tarfile.TarFile のメソッド)
    • (tkinter.ttk.Notebook のメソッド)
  • add_alias() (email.charset モジュール)
  • add_alternative() (email.message.EmailMessage のメソッド)
  • add_argument() (argparse.ArgumentParser のメソッド)
  • add_argument_group() (argparse.ArgumentParser のメソッド)
  • add_attachment() (email.message.EmailMessage のメソッド)
  • add_cgi_vars() (wsgiref.handlers.BaseHandler のメソッド)
  • add_charset() (email.charset モジュール)
  • add_child_handler() (asyncio.AbstractChildWatcher のメソッド)
  • add_codec() (email.charset モジュール)
  • add_cookie_header() (http.cookiejar.CookieJar のメソッド)
  • add_data() (msilib モジュール)
  • add_done_callback() (asyncio.Future のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
  • add_fallback() (gettext.NullTranslations のメソッド)
  • add_file() (msilib.Directory のメソッド)
  • add_flag() (mailbox.MaildirMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
    • (mailbox.mboxMessage のメソッド)
  • add_flowing_data() (formatter.formatter のメソッド)
  • add_folder() (mailbox.Maildir のメソッド)
    • (mailbox.MH のメソッド)
  • add_get_handler() (email.contentmanager.ContentManager のメソッド)
  • add_handler() (urllib.request.OpenerDirector のメソッド)
  • add_header() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (urllib.request.Request のメソッド)
    • (wsgiref.headers.Headers のメソッド)
  • add_history() (readline モジュール)
  • add_hor_rule() (formatter.formatter のメソッド)
  • add_include_dir() (distutils.ccompiler.CCompiler のメソッド)
  • add_label() (mailbox.BabylMessage のメソッド)
  • add_label_data() (formatter.formatter のメソッド)
  • add_library() (distutils.ccompiler.CCompiler のメソッド)
  • add_library_dir() (distutils.ccompiler.CCompiler のメソッド)
  • add_line_break() (formatter.formatter のメソッド)
  • add_link_object() (distutils.ccompiler.CCompiler のメソッド)
  • add_literal_data() (formatter.formatter のメソッド)
  • add_mutually_exclusive_group() (argparse.ArgumentParser のメソッド)
  • add_option() (optparse.OptionParser のメソッド)
  • add_parent() (urllib.request.BaseHandler のメソッド)
  • add_password() (urllib.request.HTTPPasswordMgr のメソッド)
    • (urllib.request.HTTPPasswordMgrWithPriorAuth のメソッド)
  • add_reader() (asyncio.loop のメソッド)
  • add_related() (email.message.EmailMessage のメソッド)
  • add_runtime_library_dir() (distutils.ccompiler.CCompiler のメソッド)
  • add_section() (configparser.ConfigParser のメソッド)
    • (configparser.RawConfigParser のメソッド)
  • add_sequence() (mailbox.MHMessage のメソッド)
  • add_set_handler() (email.contentmanager.ContentManager のメソッド)
  • add_signal_handler() (asyncio.loop のメソッド)
  • add_stream() (msilib モジュール)
  • add_subparsers() (argparse.ArgumentParser のメソッド)
  • add_tables() (msilib モジュール)
  • add_type() (mimetypes モジュール)
  • add_unredirected_header() (urllib.request.Request のメソッド)
  • add_writer() (asyncio.loop のメソッド)
  • addch() (curses.window のメソッド)
  • addCleanup() (unittest.TestCase のメソッド)
  • addcomponent() (turtle.Shape のメソッド)
  • addError() (unittest.TestResult のメソッド)
  • addExpectedFailure() (unittest.TestResult のメソッド)
  • addFailure() (unittest.TestResult のメソッド)
  • addfile() (tarfile.TarFile のメソッド)
  • addFilter() (logging.Handler のメソッド)
    • (logging.Logger のメソッド)
  • addHandler() (logging.Logger のメソッド)
  • addition
  • addLevelName() (logging モジュール)
  • addnstr() (curses.window のメソッド)
  • AddPackagePath() (modulefinder モジュール)
  • addr (smtpd.SMTPChannel の属性)
  • addr_spec (email.headerregistry.Address の属性)
  • Address (email.headerregistry のクラス)
  • address (email.headerregistry.SingleAddressHeader の属性)
    • (multiprocessing.connection.Listener の属性)
    • (multiprocessing.managers.BaseManager の属性)
  • address_exclude() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • address_family (socketserver.BaseServer の属性)
  • address_string() (http.server.BaseHTTPRequestHandler のメソッド)
  • addresses (email.headerregistry.AddressHeader の属性)
    • (email.headerregistry.Group の属性)
  • AddressHeader (email.headerregistry のクラス)
  • addressof() (ctypes モジュール)
  • AddressValueError
  • addshape() (turtle モジュール)
  • addsitedir() (site モジュール)
  • addSkip() (unittest.TestResult のメソッド)
  • addstr() (curses.window のメソッド)
  • addSubTest() (unittest.TestResult のメソッド)
  • addSuccess() (unittest.TestResult のメソッド)
  • addTest() (unittest.TestSuite のメソッド)
  • addTests() (unittest.TestSuite のメソッド)
  • addTypeEqualityFunc() (unittest.TestCase のメソッド)
  • addUnexpectedSuccess() (unittest.TestResult のメソッド)
  • adjusted() (decimal.Decimal のメソッド)
  • adler32() (zlib モジュール)
  • ADPCM, Intel/DVI
  • adpcm2lin() (audioop モジュール)
  • AF_ALG (socket モジュール)
  • AF_CAN (socket モジュール)
  • AF_INET (socket モジュール)
  • AF_INET6 (socket モジュール)
  • AF_LINK (socket モジュール)
  • AF_PACKET (socket モジュール)
  • AF_RDS (socket モジュール)
  • AF_UNIX (socket モジュール)
  • AF_VSOCK (socket モジュール)
  • aifc (モジュール)
  • aifc() (aifc.aifc のメソッド)
  • AIFF, [1]
  • aiff() (aifc.aifc のメソッド)
  • AIFF-C, [1]
  • alarm() (signal モジュール)
  • alaw2lin() (audioop モジュール)
  • ALERT_DESCRIPTION_HANDSHAKE_FAILURE (ssl モジュール)
  • ALERT_DESCRIPTION_INTERNAL_ERROR (ssl モジュール)
  • AlertDescription (ssl のクラス)
  • algorithms_available (hashlib モジュール)
  • algorithms_guaranteed (hashlib モジュール)
  • alias (pdb command)
  • alignment() (ctypes モジュール)
  • alive (weakref.finalize の属性)
  • all() (組み込み関数)
  • all_errors (ftplib モジュール)
  • all_features (xml.sax.handler モジュール)
  • all_frames (tracemalloc.Filter の属性)
  • all_properties (xml.sax.handler モジュール)
  • all_suffixes() (importlib.machinery モジュール)
  • all_tasks() (asyncio モジュール)
    • (asyncio.Task のクラスメソッド)
  • allocate_lock() (_thread モジュール)
  • allow_reuse_address (socketserver.BaseServer の属性)
  • allowed_domains() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • alt() (curses.ascii モジュール)
  • ALT_DIGITS (locale モジュール)
  • altsep (os モジュール)
  • altzone (time モジュール)
  • ALWAYS_TYPED_ACTIONS (optparse.Option の属性)
  • AMPER (token モジュール)
  • AMPEREQUAL (token モジュール)
  • and
    • bitwise
    • 演算子, [1], [2]
  • and_() (operator モジュール)
  • annotated
    • assignment
  • annotation
    • (inspect.Parameter の属性)
  • annotations
    • function, [1]
  • announce() (distutils.ccompiler.CCompiler のメソッド)
  • anonymous
    • function
  • answer_challenge() (multiprocessing.connection モジュール)
  • anticipate_failure() (test.support モジュール)
  • Any (typing モジュール)
  • ANY (unittest.mock モジュール)
  • any() (組み込み関数)
  • AnyStr (typing モジュール)
  • api_version (sys モジュール)
  • apop() (poplib.POP3 のメソッド)
  • APPDATA
  • append() (array.array のメソッド)
    • (collections.deque のメソッド)
    • (email.header.Header のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (msilib.CAB のメソッド)
    • (pipes.Template のメソッド)
    • (sequence method)
    • (xml.etree.ElementTree.Element のメソッド)
  • append_history_file() (readline モジュール)
  • appendChild() (xml.dom.Node のメソッド)
  • appendleft() (collections.deque のメソッド)
  • application_uri() (wsgiref.util モジュール)
  • apply (2to3 fixer)
  • apply() (multiprocessing.pool.Pool のメソッド)
  • apply_async() (multiprocessing.pool.Pool のメソッド)
  • apply_defaults() (inspect.BoundArguments のメソッド)
  • architecture() (platform モジュール)
  • archive (zipimport.zipimporter の属性)
  • aRepr (reprlib モジュール)
  • argparse (モジュール)
  • args (BaseException の属性)
    • (functools.partial の属性)
    • (inspect.BoundArguments の属性)
    • (pdb command)
    • (subprocess.CompletedProcess の属性)
    • (subprocess.Popen の属性)
  • args_from_interpreter_flags() (test.support モジュール)
  • argtypes (ctypes._FuncPtr の属性)
  • argument
    • call semantics
    • difference from parameter
    • function
    • function definition
  • ArgumentDefaultsHelpFormatter (argparse のクラス)
  • ArgumentError
  • ArgumentParser (argparse のクラス)
  • arguments (inspect.BoundArguments の属性)
  • argv (in module sys)
    • (sys モジュール)
  • arithmetic
    • conversion
    • operation, binary
    • operation, unary
  • ArithmeticError
  • array
    • モジュール, [1]
  • array (array のクラス)
  • Array (ctypes のクラス)
  • array (モジュール)
  • Array() (multiprocessing モジュール)
    • (multiprocessing.managers.SyncManager のメソッド)
    • (multiprocessing.sharedctypes モジュール)
  • arrays
  • arraysize (sqlite3.Cursor の属性)
  • article() (nntplib.NNTP のメソッド)
  • as
    • except clause
    • import statement
    • with statement
    • キーワード, [1], [2]
  • as_bytes() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • as_completed() (asyncio モジュール)
    • (concurrent.futures モジュール)
  • as_integer_ratio() (decimal.Decimal のメソッド)
    • (float のメソッド)
  • AS_IS (formatter モジュール)
  • as_posix() (pathlib.PurePath のメソッド)
  • as_string() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • as_tuple() (decimal.Decimal のメソッド)
  • as_uri() (pathlib.PurePath のメソッド)
  • ASCII, [1]
  • ascii
    • (re モジュール)
    • 組み込み関数
  • ascii() (curses.ascii モジュール)
    • (組み込み関数)
  • ascii_letters (string モジュール)
  • ascii_lowercase (string モジュール)
  • ascii_uppercase (string モジュール)
  • asctime() (time モジュール)
  • asdict() (dataclasses モジュール)
  • asend() (agen のメソッド)
  • asin() (cmath モジュール)
    • (math モジュール)
  • asinh() (cmath モジュール)
    • (math モジュール)
  • assert
    • 文, [1]
  • assert_any_call() (unittest.mock.Mock のメソッド)
  • assert_called() (unittest.mock.Mock のメソッド)
  • assert_called_once() (unittest.mock.Mock のメソッド)
  • assert_called_once_with() (unittest.mock.Mock のメソッド)
  • assert_called_with() (unittest.mock.Mock のメソッド)
  • assert_has_calls() (unittest.mock.Mock のメソッド)
  • assert_line_data() (formatter.formatter のメソッド)
  • assert_not_called() (unittest.mock.Mock のメソッド)
  • assert_python_failure() (test.support.script_helper モジュール)
  • assert_python_ok() (test.support.script_helper モジュール)
  • assertAlmostEqual() (unittest.TestCase のメソッド)
  • assertCountEqual() (unittest.TestCase のメソッド)
  • assertDictEqual() (unittest.TestCase のメソッド)
  • assertEqual() (unittest.TestCase のメソッド)
  • assertFalse() (unittest.TestCase のメソッド)
  • assertGreater() (unittest.TestCase のメソッド)
  • assertGreaterEqual() (unittest.TestCase のメソッド)
  • assertIn() (unittest.TestCase のメソッド)
  • AssertionError
    • 例外
  • assertions
    • debugging
  • assertIs() (unittest.TestCase のメソッド)
  • assertIsInstance() (unittest.TestCase のメソッド)
  • assertIsNone() (unittest.TestCase のメソッド)
  • assertIsNot() (unittest.TestCase のメソッド)
  • assertIsNotNone() (unittest.TestCase のメソッド)
  • assertLess() (unittest.TestCase のメソッド)
  • assertLessEqual() (unittest.TestCase のメソッド)
  • assertListEqual() (unittest.TestCase のメソッド)
  • assertLogs() (unittest.TestCase のメソッド)
  • assertMultiLineEqual() (unittest.TestCase のメソッド)
  • assertNotAlmostEqual() (unittest.TestCase のメソッド)
  • assertNotEqual() (unittest.TestCase のメソッド)
  • assertNotIn() (unittest.TestCase のメソッド)
  • assertNotIsInstance() (unittest.TestCase のメソッド)
  • assertNotRegex() (unittest.TestCase のメソッド)
  • assertRaises() (unittest.TestCase のメソッド)
  • assertRaisesRegex() (unittest.TestCase のメソッド)
  • assertRegex() (unittest.TestCase のメソッド)
  • asserts (2to3 fixer)
  • assertSequenceEqual() (unittest.TestCase のメソッド)
  • assertSetEqual() (unittest.TestCase のメソッド)
  • assertTrue() (unittest.TestCase のメソッド)
  • assertTupleEqual() (unittest.TestCase のメソッド)
  • assertWarns() (unittest.TestCase のメソッド)
  • assertWarnsRegex() (unittest.TestCase のメソッド)
  • assignment
    • annotated
    • attribute, [1]
    • augmented
    • class attribute
    • class instance attribute
    • slice
    • slicing
    • statement, [1]
    • subscript
    • subscription
    • target list
  • AST (ast のクラス)
  • ast (モジュール)
  • astimezone() (datetime.datetime のメソッド)
  • astuple() (dataclasses モジュール)
  • async
    • キーワード
  • async def
    • 文
  • async for
    • in comprehensions
    • 文
  • async with
    • 文
  • async_chat (asynchat のクラス)
  • async_chat.ac_in_buffer_size (asynchat モジュール)
  • async_chat.ac_out_buffer_size (asynchat モジュール)
  • AsyncContextManager (typing のクラス)
  • asynccontextmanager() (contextlib モジュール)
  • AsyncExitStack (contextlib のクラス)
  • AsyncGenerator (collections.abc のクラス)
    • (typing のクラス)
  • AsyncGeneratorType (types モジュール)
  • asynchat (モジュール)
  • asynchronous context manager
  • asynchronous generator
    • asynchronous iterator
    • function
  • asynchronous generator iterator
  • asynchronous iterable
  • asynchronous iterator
  • asynchronous-generator
    • オブジェクト
  • asyncio (モジュール)
  • asyncio.subprocess.DEVNULL (asyncio モジュール)
  • asyncio.subprocess.PIPE (asyncio モジュール)
  • asyncio.subprocess.Process (asyncio のクラス)
  • asyncio.subprocess.STDOUT (asyncio モジュール)
  • AsyncIterable (collections.abc のクラス)
    • (typing のクラス)
  • AsyncIterator (collections.abc のクラス)
    • (typing のクラス)
  • asyncore (モジュール)
  • AsyncResult (multiprocessing.pool のクラス)
  • AT (token モジュール)
  • at_eof() (asyncio.StreamReader のメソッド)
  • atan() (cmath モジュール)
    • (math モジュール)
  • atan2() (math モジュール)
  • atanh() (cmath モジュール)
    • (math モジュール)
  • ATEQUAL (token モジュール)
  • atexit (weakref.finalize の属性)
    • (モジュール)
  • athrow() (agen のメソッド)
  • atof() (locale モジュール)
  • atoi() (locale モジュール)
  • atom
  • attach() (email.message.Message のメソッド)
  • attach_loop() (asyncio.AbstractChildWatcher のメソッド)
  • attach_mock() (unittest.mock.Mock のメソッド)
  • AttlistDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • attrgetter() (operator モジュール)
  • attrib (xml.etree.ElementTree.Element の属性)
  • attribute, [1]
    • assignment, [1]
    • assignment, class
    • assignment, class instance
    • class
    • class instance
    • deletion
    • generic special
    • reference
    • special
  • AttributeError
    • 例外
  • attributes (xml.dom.Node の属性)
  • AttributesImpl (xml.sax.xmlreader のクラス)
  • AttributesNSImpl (xml.sax.xmlreader のクラス)
  • attroff() (curses.window のメソッド)
  • attron() (curses.window のメソッド)
  • attrset() (curses.window のメソッド)
  • Audio Interchange File Format, [1]
  • 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 (sunau モジュール)
  • AUDIO_FILE_ENCODING_ALAW_8 (sunau モジュール)
  • AUDIO_FILE_ENCODING_DOUBLE (sunau モジュール)
  • AUDIO_FILE_ENCODING_FLOAT (sunau モジュール)
  • AUDIO_FILE_ENCODING_LINEAR_16 (sunau モジュール)
  • AUDIO_FILE_ENCODING_LINEAR_24 (sunau モジュール)
  • AUDIO_FILE_ENCODING_LINEAR_32 (sunau モジュール)
  • AUDIO_FILE_ENCODING_LINEAR_8 (sunau モジュール)
  • AUDIO_FILE_ENCODING_MULAW_8 (sunau モジュール)
  • AUDIO_FILE_MAGIC (sunau モジュール)
  • AUDIODEV
  • audioop (モジュール)
  • augmented
    • assignment
  • auth() (ftplib.FTP_TLS のメソッド)
    • (smtplib.SMTP のメソッド)
  • authenticate() (imaplib.IMAP4 のメソッド)
  • AuthenticationError
  • authenticators() (netrc.netrc のメソッド)
  • authkey (multiprocessing.Process の属性)
  • auto (enum のクラス)
  • autorange() (timeit.Timer のメソッド)
  • avg() (audioop モジュール)
  • avgpp() (audioop モジュール)
  • avoids_symlink_attacks (shutil.rmtree の属性)
  • await
    • in comprehensions
    • キーワード, [1]
  • awaitable
  • Awaitable (collections.abc のクラス)
    • (typing のクラス)

B

  • b"
    • bytes literal
  • b'
    • bytes literal
  • b16decode() (base64 モジュール)
  • b16encode() (base64 モジュール)
  • b2a_base64() (binascii モジュール)
  • b2a_hex() (binascii モジュール)
  • b2a_hqx() (binascii モジュール)
  • b2a_qp() (binascii モジュール)
  • b2a_uu() (binascii モジュール)
  • b32decode() (base64 モジュール)
  • b32encode() (base64 モジュール)
  • b64decode() (base64 モジュール)
  • b64encode() (base64 モジュール)
  • b85decode() (base64 モジュール)
  • b85encode() (base64 モジュール)
  • Babyl (mailbox のクラス)
  • BabylMessage (mailbox のクラス)
  • back() (turtle モジュール)
  • backslash character
  • backslashreplace_errors() (codecs モジュール)
  • backup() (sqlite3.Connection のメソッド)
  • backward() (turtle モジュール)
  • BadStatusLine
  • BadZipFile
  • BadZipfile
  • Balloon (tkinter.tix のクラス)
  • Barrier (multiprocessing のクラス)
    • (threading のクラス)
  • Barrier() (multiprocessing.managers.SyncManager のメソッド)
  • base64
    • encoding
    • モジュール
  • base64 (モジュール)
  • base_exec_prefix (sys モジュール)
  • base_prefix (sys モジュール)
  • BaseCGIHandler (wsgiref.handlers のクラス)
  • BaseCookie (http.cookies のクラス)
  • BaseException
  • BaseHandler (urllib.request のクラス)
    • (wsgiref.handlers のクラス)
  • BaseHeader (email.headerregistry のクラス)
  • BaseHTTPRequestHandler (http.server のクラス)
  • BaseManager (multiprocessing.managers のクラス)
  • basename() (os.path モジュール)
  • BaseProtocol (asyncio のクラス)
  • BaseProxy (multiprocessing.managers のクラス)
  • BaseRequestHandler (socketserver のクラス)
  • BaseRotatingHandler (logging.handlers のクラス)
  • BaseSelector (selectors のクラス)
  • BaseServer (socketserver のクラス)
  • basestring (2to3 fixer)
  • BaseTransport (asyncio のクラス)
  • basicConfig() (logging モジュール)
  • BasicContext (decimal のクラス)
  • BasicInterpolation (configparser のクラス)
  • BasicTestRunner (test.support のクラス)
  • baudrate() (curses モジュール)
  • bbox() (tkinter.ttk.Treeview のメソッド)
  • BDADDR_ANY (socket モジュール)
  • BDADDR_LOCAL (socket モジュール)
  • bdb
    • モジュール
  • Bdb (bdb のクラス)
  • bdb (モジュール)
  • BdbQuit
  • BDFL
  • bdist_msi (distutils.command.bdist_msi のクラス)
  • beep() (curses モジュール)
  • Beep() (winsound モジュール)
  • BEFORE_ASYNC_WITH (opcode)
  • begin_fill() (turtle モジュール)
  • begin_poly() (turtle モジュール)
  • below() (curses.panel.Panel のメソッド)
  • BELOW_NORMAL_PRIORITY_CLASS (subprocess モジュール)
  • Benchmarking
  • benchmarking, [1], [2], [3]
  • betavariate() (random モジュール)
  • bgcolor() (turtle モジュール)
  • bgpic() (turtle モジュール)
  • bias() (audioop モジュール)
  • bidirectional() (unicodedata モジュール)
  • bigaddrspacetest() (test.support モジュール)
  • BigEndianStructure (ctypes のクラス)
  • bigmemtest() (test.support モジュール)
  • bin() (組み込み関数)
  • binary
    • arithmetic operation
    • bitwise operation
    • data, packing
    • literals
  • Binary (msilib のクラス)
    • (xmlrpc.client のクラス)
  • binary file
  • binary literal
  • binary mode
  • binary semaphores
  • BINARY_ADD (opcode)
  • BINARY_AND (opcode)
  • BINARY_FLOOR_DIVIDE (opcode)
  • BINARY_LSHIFT (opcode)
  • BINARY_MATRIX_MULTIPLY (opcode)
  • BINARY_MODULO (opcode)
  • BINARY_MULTIPLY (opcode)
  • BINARY_OR (opcode)
  • BINARY_POWER (opcode)
  • BINARY_RSHIFT (opcode)
  • BINARY_SUBSCR (opcode)
  • BINARY_SUBTRACT (opcode)
  • BINARY_TRUE_DIVIDE (opcode)
  • BINARY_XOR (opcode)
  • BinaryIO (typing のクラス)
  • binascii (モジュール)
  • bind (widgets)
  • bind() (asyncore.dispatcher のメソッド)
    • (inspect.Signature のメソッド)
    • (socket.socket のメソッド)
  • bind_partial() (inspect.Signature のメソッド)
  • bind_port() (test.support モジュール)
  • bind_textdomain_codeset() (gettext モジュール)
  • bind_unix_socket() (test.support モジュール)
  • binding
    • global name
    • name, [1], [2], [3], [4], [5], [6]
  • bindtextdomain() (gettext モジュール)
    • (locale モジュール)
  • binhex
    • モジュール
  • binhex (モジュール)
  • binhex() (binhex モジュール)
  • bisect (モジュール)
  • bisect() (bisect モジュール)
  • bisect_left() (bisect モジュール)
  • bisect_right() (bisect モジュール)
  • bit_length() (int のメソッド)
  • bitmap() (msilib.Dialog のメソッド)
  • bitwise
    • and
    • operation, binary
    • operation, unary
    • operations
    • or
    • xor
  • bk() (turtle モジュール)
  • bkgd() (curses.window のメソッド)
  • bkgdset() (curses.window のメソッド)
  • blake2b() (hashlib モジュール)
  • blake2b, blake2s
  • blake2b.MAX_DIGEST_SIZE (hashlib モジュール)
  • blake2b.MAX_KEY_SIZE (hashlib モジュール)
  • blake2b.PERSON_SIZE (hashlib モジュール)
  • blake2b.SALT_SIZE (hashlib モジュール)
  • blake2s() (hashlib モジュール)
  • blake2s.MAX_DIGEST_SIZE (hashlib モジュール)
  • blake2s.MAX_KEY_SIZE (hashlib モジュール)
  • blake2s.PERSON_SIZE (hashlib モジュール)
  • blake2s.SALT_SIZE (hashlib モジュール)
  • blank line
  • block
    • code
  • block_size (hmac.HMAC の属性)
  • blocked_domains() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • BlockingIOError, [1]
  • blocksize (http.client.HTTPConnection の属性)
  • BNF, [1]
  • body() (nntplib.NNTP のメソッド)
  • body_encode() (email.charset.Charset のメソッド)
  • body_encoding (email.charset.Charset の属性)
  • body_line_iterator() (email.iterators モジュール)
  • BOM (codecs モジュール)
  • BOM_BE (codecs モジュール)
  • BOM_LE (codecs モジュール)
  • BOM_UTF16 (codecs モジュール)
  • BOM_UTF16_BE (codecs モジュール)
  • BOM_UTF16_LE (codecs モジュール)
  • BOM_UTF32 (codecs モジュール)
  • BOM_UTF32_BE (codecs モジュール)
  • BOM_UTF32_LE (codecs モジュール)
  • BOM_UTF8 (codecs モジュール)
  • bool (組み込みクラス)
  • Boolean
    • operation
    • operations, [1]
    • type
    • values
    • オブジェクト, [1]
  • BOOLEAN_STATES (configparser.ConfigParser の属性)
  • bootstrap() (ensurepip モジュール)
  • border() (curses.window のメソッド)
  • bottom() (curses.panel.Panel のメソッド)
  • bottom_panel() (curses.panel モジュール)
  • BoundArguments (inspect のクラス)
  • BoundaryError
  • BoundedSemaphore (asyncio のクラス)
    • (multiprocessing のクラス)
    • (threading のクラス)
  • BoundedSemaphore() (multiprocessing.managers.SyncManager のメソッド)
  • box() (curses.window のメソッド)
  • bpformat() (bdb.Breakpoint のメソッド)
  • bpprint() (bdb.Breakpoint のメソッド)
  • break
    • 文, [1], [2], [3], [4]
  • break (pdb command)
  • break_anywhere() (bdb.Bdb のメソッド)
  • break_here() (bdb.Bdb のメソッド)
  • break_long_words (textwrap.TextWrapper の属性)
  • BREAK_LOOP (opcode)
  • break_on_hyphens (textwrap.TextWrapper の属性)
  • Breakpoint (bdb のクラス)
  • breakpoint() (組み込み関数)
  • breakpointhook() (sys モジュール)
  • breakpoints
  • broadcast_address (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • broken (threading.Barrier の属性)
  • BrokenBarrierError
  • BrokenExecutor
  • BrokenPipeError
  • BrokenProcessPool
  • BrokenThreadPool
  • BROWSER, [1]
  • BsdDbShelf (shelve のクラス)
  • buffer (2to3 fixer)
    • (io.TextIOBase の属性)
    • (unittest.TestResult の属性)
  • buffer interface
    • (see buffer protocol)
  • buffer object
    • (see buffer protocol)
  • buffer protocol
    • binary sequence types
    • str (built-in class)
  • buffer size, I/O
  • buffer_info() (array.array のメソッド)
  • buffer_size (xml.parsers.expat.xmlparser の属性)
  • buffer_text (xml.parsers.expat.xmlparser の属性)
  • buffer_updated() (asyncio.BufferedProtocol のメソッド)
  • buffer_used (xml.parsers.expat.xmlparser の属性)
  • BufferedIOBase (io のクラス)
  • BufferedProtocol (asyncio のクラス)
  • BufferedRandom (io のクラス)
  • BufferedReader (io のクラス)
  • BufferedRWPair (io のクラス)
  • BufferedWriter (io のクラス)
  • BufferError
  • BufferingHandler (logging.handlers のクラス)
  • BufferTooShort
  • bufsize() (ossaudiodev.oss_audio_device のメソッド)
  • BUILD_CONST_KEY_MAP (opcode)
  • BUILD_LIST (opcode)
  • BUILD_LIST_UNPACK (opcode)
  • BUILD_MAP (opcode)
  • BUILD_MAP_UNPACK (opcode)
  • BUILD_MAP_UNPACK_WITH_CALL (opcode)
  • build_opener() (urllib.request モジュール)
  • build_py (distutils.command.build_py のクラス)
  • build_py_2to3 (distutils.command.build_py のクラス)
  • BUILD_SET (opcode)
  • BUILD_SET_UNPACK (opcode)
  • BUILD_SLICE (opcode)
  • BUILD_STRING (opcode)
  • BUILD_TUPLE (opcode)
  • BUILD_TUPLE_UNPACK (opcode)
  • BUILD_TUPLE_UNPACK_WITH_CALL (opcode)
  • built-in
    • method
    • types
  • built-in function
    • call
    • オブジェクト, [1]
  • built-in method
    • call
    • オブジェクト, [1]
  • builtin_module_names (sys モジュール)
  • BuiltinFunctionType (types モジュール)
  • BuiltinImporter (importlib.machinery のクラス)
  • BuiltinMethodType (types モジュール)
  • builtins
    • モジュール, [1], [2], [3], [4]
  • builtins (モジュール)
  • ButtonBox (tkinter.tix のクラス)
  • bye() (turtle モジュール)
  • byref() (ctypes モジュール)
  • byte
  • byte-code
    • file, [1]
  • byte_compile() (distutils.util モジュール)
  • bytearray
    • formatting
    • interpolation
    • methods
    • オブジェクト, [1], [2], [3]
  • bytearray (組み込みクラス)
  • bytecode, [1]
  • Bytecode (dis のクラス)
  • Bytecode.codeobj (dis モジュール)
  • Bytecode.first_line (dis モジュール)
  • BYTECODE_SUFFIXES (importlib.machinery モジュール)
  • byteorder (sys モジュール)
  • bytes
    • formatting
    • interpolation
    • methods
    • str (built-in class)
    • オブジェクト, [1], [2]
    • 組み込み関数, [1]
  • bytes (uuid.UUID の属性)
    • (組み込みクラス)
  • bytes literal
  • bytes-like object
  • bytes_le (uuid.UUID の属性)
  • BytesFeedParser (email.parser のクラス)
  • BytesGenerator (email.generator のクラス)
  • BytesHeaderParser (email.parser のクラス)
  • BytesIO (io のクラス)
  • BytesParser (email.parser のクラス)
  • ByteString (collections.abc のクラス)
    • (typing のクラス)
  • byteswap() (array.array のメソッド)
    • (audioop モジュール)
  • BytesWarning
  • bz2 (モジュール)
  • BZ2Compressor (bz2 のクラス)
  • BZ2Decompressor (bz2 のクラス)
  • BZ2File (bz2 のクラス)

C

  • C
    • language, [1], [2], [3], [4], [5]
    • structures
  • C-contiguous, [1]
  • c_bool (ctypes のクラス)
  • C_BUILTIN (imp モジュール)
  • c_byte (ctypes のクラス)
  • c_char (ctypes のクラス)
  • c_char_p (ctypes のクラス)
  • c_contiguous (memoryview の属性)
  • c_double (ctypes のクラス)
  • C_EXTENSION (imp モジュール)
  • c_float (ctypes のクラス)
  • c_int (ctypes のクラス)
  • c_int16 (ctypes のクラス)
  • c_int32 (ctypes のクラス)
  • c_int64 (ctypes のクラス)
  • c_int8 (ctypes のクラス)
  • c_long (ctypes のクラス)
  • c_longdouble (ctypes のクラス)
  • c_longlong (ctypes のクラス)
  • c_short (ctypes のクラス)
  • c_size_t (ctypes のクラス)
  • c_ssize_t (ctypes のクラス)
  • c_ubyte (ctypes のクラス)
  • c_uint (ctypes のクラス)
  • c_uint16 (ctypes のクラス)
  • c_uint32 (ctypes のクラス)
  • c_uint64 (ctypes のクラス)
  • c_uint8 (ctypes のクラス)
  • c_ulong (ctypes のクラス)
  • c_ulonglong (ctypes のクラス)
  • c_ushort (ctypes のクラス)
  • c_void_p (ctypes のクラス)
  • c_wchar (ctypes のクラス)
  • c_wchar_p (ctypes のクラス)
  • CAB (msilib のクラス)
  • cache_from_source() (imp モジュール)
    • (importlib.util モジュール)
  • cached (importlib.machinery.ModuleSpec の属性)
  • CacheFTPHandler (urllib.request のクラス)
  • calcobjsize() (test.support モジュール)
  • calcsize() (struct モジュール)
  • calcvobjsize() (test.support モジュール)
  • Calendar (calendar のクラス)
  • calendar (モジュール)
  • calendar() (calendar モジュール)
  • call
    • built-in function
    • built-in method
    • class instance
    • class object, [1], [2]
    • function, [1], [2]
    • instance, [1]
    • method
    • procedure
    • user-defined function
  • call() (subprocess モジュール)
    • (unittest.mock モジュール)
  • call_args (unittest.mock.Mock の属性)
  • call_args_list (unittest.mock.Mock の属性)
  • call_at() (asyncio.loop のメソッド)
  • call_count (unittest.mock.Mock の属性)
  • call_exception_handler() (asyncio.loop のメソッド)
  • CALL_FUNCTION (opcode)
  • CALL_FUNCTION_EX (opcode)
  • CALL_FUNCTION_KW (opcode)
  • call_later() (asyncio.loop のメソッド)
  • call_list() (unittest.mock.call のメソッド)
  • CALL_METHOD (opcode)
  • call_soon() (asyncio.loop のメソッド)
  • call_soon_threadsafe() (asyncio.loop のメソッド)
  • call_tracing() (sys モジュール)
  • callable
    • オブジェクト, [1]
  • Callable (collections.abc のクラス)
    • (typing モジュール)
  • callable() (組み込み関数)
  • CallableProxyType (weakref モジュール)
  • callback (optparse.Option の属性)
  • callback() (contextlib.ExitStack のメソッド)
  • callback_args (optparse.Option の属性)
  • callback_kwargs (optparse.Option の属性)
  • callbacks (gc モジュール)
  • called (unittest.mock.Mock の属性)
  • CalledProcessError
  • calloc()
  • CAN_BCM (socket モジュール)
  • can_change_color() (curses モジュール)
  • can_fetch() (urllib.robotparser.RobotFileParser のメソッド)
  • CAN_ISOTP (socket モジュール)
  • CAN_RAW_FD_FRAMES (socket モジュール)
  • can_symlink() (test.support モジュール)
  • can_write_eof() (asyncio.StreamWriter のメソッド)
    • (asyncio.WriteTransport のメソッド)
  • can_xattr() (test.support モジュール)
  • cancel() (asyncio.Future のメソッド)
    • (asyncio.Handle のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
    • (sched.scheduler のメソッド)
    • (threading.Timer のメソッド)
  • cancel_dump_traceback_later() (faulthandler モジュール)
  • cancel_join_thread() (multiprocessing.Queue のメソッド)
  • cancelled() (asyncio.Future のメソッド)
    • (asyncio.Handle のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
  • CancelledError, [1]
  • CannotSendHeader
  • CannotSendRequest
  • canonic() (bdb.Bdb のメソッド)
  • canonical() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • capa() (poplib.POP3 のメソッド)
  • capitalize() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • Capsule
    • オブジェクト
  • captured_stderr() (test.support モジュール)
  • captured_stdin() (test.support モジュール)
  • captured_stdout() (test.support モジュール)
  • captureWarnings() (logging モジュール)
  • capwords() (string モジュール)
  • casefold() (str のメソッド)
  • cast() (ctypes モジュール)
    • (memoryview のメソッド)
    • (typing モジュール)
  • cat() (nis モジュール)
  • catch_warnings (warnings のクラス)
  • category() (unicodedata モジュール)
  • cbreak() (curses モジュール)
  • CC
  • ccc() (ftplib.FTP_TLS のメソッド)
  • CCompiler (distutils.ccompiler のクラス)
  • CDLL (ctypes のクラス)
  • ceil() (in module math)
    • (math モジュール)
  • center() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • CERT_NONE (ssl モジュール)
  • CERT_OPTIONAL (ssl モジュール)
  • CERT_REQUIRED (ssl モジュール)
  • cert_store_stats() (ssl.SSLContext のメソッド)
  • cert_time_to_seconds() (ssl モジュール)
  • CertificateError
  • certificates
  • CFLAGS, [1], [2], [3]
  • CFUNCTYPE() (ctypes モジュール)
  • CGI
    • debugging
    • exceptions
    • protocol
    • security
    • tracebacks
  • cgi (モジュール)
  • cgi_directories (http.server.CGIHTTPRequestHandler の属性)
  • CGIHandler (wsgiref.handlers のクラス)
  • CGIHTTPRequestHandler (http.server のクラス)
  • cgitb (モジュール)
  • CGIXMLRPCRequestHandler (xmlrpc.server のクラス)
  • chain() (itertools モジュール)
  • chaining
    • comparisons, [1]
    • exception
  • ChainMap (collections のクラス)
    • (typing のクラス)
  • change_cwd() (test.support モジュール)
  • change_root() (distutils.util モジュール)
  • CHANNEL_BINDING_TYPES (ssl モジュール)
  • channel_class (smtpd.SMTPServer の属性)
  • channels() (ossaudiodev.oss_audio_device のメソッド)
  • CHAR_MAX (locale モジュール)
  • character, [1], [2]
  • CharacterDataHandler() (xml.parsers.expat.xmlparser のメソッド)
  • characters() (xml.sax.handler.ContentHandler のメソッド)
  • characters_written (BlockingIOError の属性)
  • Charset (email.charset のクラス)
  • charset() (gettext.NullTranslations のメソッド)
  • chdir() (os モジュール)
  • check (lzma.LZMADecompressor の属性)
  • check() (imaplib.IMAP4 のメソッド)
    • (tabnanny モジュール)
  • check__all__() (test.support モジュール)
  • check_call() (subprocess モジュール)
  • check_environ() (distutils.util モジュール)
  • check_free_after_iterating() (test.support モジュール)
  • check_hostname (ssl.SSLContext の属性)
  • check_impl_detail() (test.support モジュール)
  • check_no_resource_warning() (test.support モジュール)
  • check_output() (doctest.OutputChecker のメソッド)
    • (subprocess モジュール)
  • check_returncode() (subprocess.CompletedProcess のメソッド)
  • check_syntax_error() (test.support モジュール)
  • check_unused_args() (string.Formatter のメソッド)
  • check_warnings() (test.support モジュール)
  • checkbox() (msilib.Dialog のメソッド)
  • checkcache() (linecache モジュール)
  • CHECKED_HASH (py_compile.PycInvalidationMode の属性)
  • checkfuncname() (bdb モジュール)
  • CheckList (tkinter.tix のクラス)
  • checksizeof() (test.support モジュール)
  • checksum
    • Cyclic Redundancy Check
  • chflags() (os モジュール)
  • chgat() (curses.window のメソッド)
  • childNodes (xml.dom.Node の属性)
  • ChildProcessError
  • children (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
  • chmod() (os モジュール)
    • (pathlib.Path のメソッド)
  • choice() (random モジュール)
    • (secrets モジュール)
  • choices (optparse.Option の属性)
  • choices() (random モジュール)
  • chown() (os モジュール)
    • (shutil モジュール)
  • chr
    • 組み込み関数
  • chr() (組み込み関数)
  • chroot() (os モジュール)
  • Chunk (chunk のクラス)
  • chunk (モジュール)
  • cipher
    • DES
  • cipher() (ssl.SSLSocket のメソッド)
  • circle() (turtle モジュール)
  • CIRCUMFLEX (token モジュール)
  • CIRCUMFLEXEQUAL (token モジュール)
  • Clamped (decimal のクラス)
  • class
    • attribute
    • attribute assignment
    • body
    • constructor
    • definition, [1]
    • instance
    • name
    • オブジェクト, [1], [2]
    • 文
  • Class (symtable のクラス)
  • Class browser
  • class instance
    • attribute
    • attribute assignment
    • call
    • オブジェクト, [1], [2]
  • class object
    • call, [1], [2]
  • class variable
  • classmethod
    • 組み込み関数
  • classmethod() (組み込み関数)
  • ClassMethodDescriptorType (types モジュール)
  • ClassVar (typing モジュール)
  • clause
  • CLD_CONTINUED (os モジュール)
  • CLD_DUMPED (os モジュール)
  • CLD_EXITED (os モジュール)
  • CLD_TRAPPED (os モジュール)
  • clean() (mailbox.Maildir のメソッド)
  • cleandoc() (inspect モジュール)
  • CleanImport (test.support のクラス)
  • cleanup functions
  • clear (pdb command)
  • Clear Breakpoint
  • clear() (asyncio.Event のメソッド)
    • (collections.deque のメソッド)
    • (curses.window のメソッド)
    • (dict のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (frame のメソッド)
    • (frozenset のメソッド)
    • (http.cookiejar.CookieJar のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (sequence method)
    • (threading.Event のメソッド)
    • (turtle モジュール), [1]
    • (xml.etree.ElementTree.Element のメソッド)
  • clear_all_breaks() (bdb.Bdb のメソッド)
  • clear_all_file_breaks() (bdb.Bdb のメソッド)
  • clear_bpbynumber() (bdb.Bdb のメソッド)
  • clear_break() (bdb.Bdb のメソッド)
  • clear_cache() (filecmp モジュール)
  • clear_content() (email.message.EmailMessage のメソッド)
  • clear_flags() (decimal.Context のメソッド)
  • clear_frames() (traceback モジュール)
  • clear_history() (readline モジュール)
  • clear_session_cookies() (http.cookiejar.CookieJar のメソッド)
  • clear_traces() (tracemalloc モジュール)
  • clear_traps() (decimal.Context のメソッド)
  • clearcache() (linecache モジュール)
  • ClearData() (msilib.Record のメソッド)
  • clearok() (curses.window のメソッド)
  • clearscreen() (turtle モジュール)
  • clearstamp() (turtle モジュール)
  • clearstamps() (turtle モジュール)
  • Client() (multiprocessing.connection モジュール)
  • client_address (http.server.BaseHTTPRequestHandler の属性)
  • clock() (time モジュール)
  • CLOCK_BOOTTIME (time モジュール)
  • clock_getres() (time モジュール)
  • clock_gettime() (time モジュール)
  • clock_gettime_ns() (time モジュール)
  • CLOCK_HIGHRES (time モジュール)
  • CLOCK_MONOTONIC (time モジュール)
  • CLOCK_MONOTONIC_RAW (time モジュール)
  • CLOCK_PROCESS_CPUTIME_ID (time モジュール)
  • CLOCK_PROF (time モジュール)
  • CLOCK_REALTIME (time モジュール)
  • clock_settime() (time モジュール)
  • clock_settime_ns() (time モジュール)
  • CLOCK_THREAD_CPUTIME_ID (time モジュール)
  • CLOCK_UPTIME (time モジュール)
  • clone() (email.generator.BytesGenerator のメソッド)
    • (email.generator.Generator のメソッド)
    • (email.policy.Policy のメソッド)
    • (pipes.Template のメソッド)
    • (turtle モジュール)
  • cloneNode() (xml.dom.Node のメソッド)
  • close() (aifc.aifc のメソッド), [1]
    • (asyncio.AbstractChildWatcher のメソッド)
    • (asyncio.BaseTransport のメソッド)
    • (asyncio.Server のメソッド)
    • (asyncio.StreamWriter のメソッド)
    • (asyncio.SubprocessTransport のメソッド)
    • (asyncio.loop のメソッド)
    • (asyncore.dispatcher のメソッド)
    • (chunk.Chunk のメソッド)
    • (contextlib.ExitStack のメソッド)
    • (coroutine のメソッド)
    • (dbm.dumb.dumbdbm のメソッド)
    • (dbm.gnu.gdbm のメソッド)
    • (dbm.ndbm.ndbm のメソッド)
    • (distutils.text_file.TextFile のメソッド)
    • (email.parser.BytesFeedParser のメソッド)
    • (fileinput モジュール)
    • (ftplib.FTP のメソッド)
    • (generator のメソッド)
    • (html.parser.HTMLParser のメソッド)
    • (http.client.HTTPConnection のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (in module os)
    • (io.IOBase のメソッド)
    • (logging.FileHandler のメソッド)
    • (logging.Handler のメソッド)
    • (logging.handlers.MemoryHandler のメソッド)
    • (logging.handlers.NTEventLogHandler のメソッド)
    • (logging.handlers.SocketHandler のメソッド)
    • (logging.handlers.SysLogHandler のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (mmap.mmap のメソッド)
  • Close() (msilib.Database のメソッド)
    • (msilib.View のメソッド)
  • close() (multiprocessing.connection.Connection のメソッド)
    • (multiprocessing.Process のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (multiprocessing.connection.Listener のメソッド)
    • (multiprocessing.pool.Pool のメソッド)
    • (os モジュール)
    • (os.scandir のメソッド)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (ossaudiodev.oss_mixer_device のメソッド)
    • (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.kqueue のメソッド)
    • (selectors.BaseSelector のメソッド)
    • (shelve.Shelf のメソッド)
    • (socket モジュール)
    • (socket.socket のメソッド)
    • (sqlite3.Connection のメソッド)
    • (sqlite3.Cursor のメソッド)
    • (sunau.AU_read のメソッド)
    • (sunau.AU_write のメソッド)
    • (tarfile.TarFile のメソッド)
    • (telnetlib.Telnet のメソッド)
    • (urllib.request.BaseHandler のメソッド)
    • (wave.Wave_read のメソッド)
    • (wave.Wave_write のメソッド)
  • Close() (winreg.PyHKEY のメソッド)
  • close() (xml.etree.ElementTree.TreeBuilder のメソッド)
    • (xml.etree.ElementTree.XMLParser のメソッド)
    • (xml.etree.ElementTree.XMLPullParser のメソッド)
    • (xml.sax.xmlreader.IncrementalParser のメソッド)
    • (zipfile.ZipFile のメソッド)
  • close_connection (http.server.BaseHTTPRequestHandler の属性)
  • close_when_done() (asynchat.async_chat のメソッド)
  • closed (http.client.HTTPResponse の属性)
    • (io.IOBase の属性)
    • (mmap.mmap の属性)
    • (ossaudiodev.oss_audio_device の属性)
    • (select.devpoll の属性)
    • (select.epoll の属性)
    • (select.kqueue の属性)
  • CloseKey() (winreg モジュール)
  • closelog() (syslog モジュール)
  • closerange() (os モジュール)
  • closing() (contextlib モジュール)
  • clrtobot() (curses.window のメソッド)
  • clrtoeol() (curses.window のメソッド)
  • cmath (モジュール)
  • cmd
    • モジュール
  • Cmd (cmd のクラス)
  • cmd (subprocess.CalledProcessError の属性)
    • (subprocess.TimeoutExpired の属性)
    • (モジュール)
  • cmdloop() (cmd.Cmd のメソッド)
  • cmdqueue (cmd.Cmd の属性)
  • cmp() (filecmp モジュール)
  • cmp_op (dis モジュール)
  • cmp_to_key() (functools モジュール)
  • cmpfiles() (filecmp モジュール)
  • CMSG_LEN() (socket モジュール)
  • CMSG_SPACE() (socket モジュール)
  • co_argcount (code object attribute)
  • CO_ASYNC_GENERATOR (inspect モジュール)
  • co_cellvars (code object attribute)
  • co_code (code object attribute)
  • co_consts (code object attribute)
  • CO_COROUTINE (inspect モジュール)
  • co_filename (code object attribute)
  • co_firstlineno (code object attribute)
  • co_flags (code object attribute)
  • co_freevars (code object attribute)
  • CO_FUTURE_DIVISION (C の変数)
  • CO_GENERATOR (inspect モジュール)
  • CO_ITERABLE_COROUTINE (inspect モジュール)
  • co_lnotab (code object attribute)
  • co_name (code object attribute)
  • co_names (code object attribute)
  • CO_NESTED (inspect モジュール)
  • CO_NEWLOCALS (inspect モジュール)
  • co_nlocals (code object attribute)
  • CO_NOFREE (inspect モジュール)
  • CO_OPTIMIZED (inspect モジュール)
  • co_stacksize (code object attribute)
  • CO_VARARGS (inspect モジュール)
  • CO_VARKEYWORDS (inspect モジュール)
  • co_varnames (code object attribute)
  • code
    • block
  • code (SystemExit の属性)
    • (urllib.error.HTTPError の属性)
    • (xml.etree.ElementTree.ParseError の属性)
    • (xml.parsers.expat.ExpatError の属性)
    • (モジュール)
  • code object, [1], [2], [3]
  • code_info() (dis モジュール)
  • CodecInfo (codecs のクラス)
  • Codecs
    • decode
    • encode
  • codecs (モジュール)
  • coded_value (http.cookies.Morsel の属性)
  • codeop (モジュール)
  • codepoint2name (html.entities モジュール)
  • codes (xml.parsers.expat.errors モジュール)
  • CODESET (locale モジュール)
  • CodeType (types モジュール)
  • coding
    • style
  • coercion
  • col_offset (ast.AST の属性)
  • collapse_addresses() (ipaddress モジュール)
  • collapse_rfc2231_value() (email.utils モジュール)
  • collect() (gc モジュール)
  • collect_incoming_data() (asynchat.async_chat のメソッド)
  • Collection (collections.abc のクラス)
    • (typing のクラス)
  • collections (モジュール)
  • collections.abc (モジュール)
  • colno (json.JSONDecodeError の属性)
    • (re.error の属性)
  • COLON (token モジュール)
  • color() (turtle モジュール)
  • color_content() (curses モジュール)
  • color_pair() (curses モジュール)
  • colormode() (turtle モジュール)
  • colorsys (モジュール)
  • COLS, [1]
  • column() (tkinter.ttk.Treeview のメソッド)
  • COLUMNS, [1]
  • columns (os.terminal_size の属性)
  • combinations() (itertools モジュール)
  • combinations_with_replacement() (itertools モジュール)
  • combine() (datetime.datetime のクラスメソッド)
  • combining() (unicodedata モジュール)
  • ComboBox (tkinter.tix のクラス)
  • Combobox (tkinter.ttk のクラス)
  • comma
    • trailing
    • tuple display
  • COMMA (token モジュール)
  • Command (distutils.cmd のクラス)
    • (distutils.core のクラス)
  • command (http.server.BaseHTTPRequestHandler の属性)
  • command line
  • CommandCompiler (codeop のクラス)
  • commands (pdb command)
  • comment
    • (http.cookiejar.Cookie の属性)
  • COMMENT (token モジュール)
  • comment (zipfile.ZipFile の属性)
    • (zipfile.ZipInfo の属性)
  • Comment() (xml.etree.ElementTree モジュール)
  • comment_url (http.cookiejar.Cookie の属性)
  • commenters (shlex.shlex の属性)
  • CommentHandler() (xml.parsers.expat.xmlparser のメソッド)
  • commit() (msilib.CAB のメソッド)
  • Commit() (msilib.Database のメソッド)
  • commit() (sqlite3.Connection のメソッド)
  • common (filecmp.dircmp の属性)
  • Common Gateway Interface
  • common_dirs (filecmp.dircmp の属性)
  • common_files (filecmp.dircmp の属性)
  • common_funny (filecmp.dircmp の属性)
  • common_types (mimetypes モジュール)
  • commonpath() (os.path モジュール)
  • commonprefix() (os.path モジュール)
  • communicate() (asyncio.asyncio.subprocess.Process のメソッド)
    • (subprocess.Popen のメソッド)
  • compare() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (difflib.Differ のメソッド)
  • compare_digest() (hmac モジュール)
    • (secrets モジュール)
  • compare_networks() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • COMPARE_OP (opcode)
  • compare_signal() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • compare_to() (tracemalloc.Snapshot のメソッド)
  • compare_total() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • compare_total_mag() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • comparing
    • objects
  • comparison
    • operator
  • COMPARISON_FLAGS (doctest モジュール)
  • comparisons
    • chaining, [1]
  • Compat32 (email.policy のクラス)
  • compat32 (email.policy モジュール)
  • compile
    • 組み込み関数, [1], [2], [3], [4]
  • Compile (codeop のクラス)
  • compile() (distutils.ccompiler.CCompiler のメソッド)
    • (parser.ST のメソッド)
    • (py_compile モジュール)
    • (re モジュール)
    • (組み込み関数)
  • compile_command() (code モジュール)
    • (codeop モジュール)
  • compile_dir() (compileall モジュール)
  • compile_file() (compileall モジュール)
  • compile_path() (compileall モジュール)
  • compileall (モジュール)
  • compileall コマンドラインオプション
    • --invalidation-mode [timestamp|checked-hash|unchecked-hash]
    • -b
    • -d destdir
    • -f
    • -i list
    • -j N
    • -l
    • -q
    • -r
    • -x regex
    • directory ...
    • file ...
  • compilest() (parser モジュール)
  • complete() (rlcompleter.Completer のメソッド)
  • complete_statement() (sqlite3 モジュール)
  • completedefault() (cmd.Cmd のメソッド)
  • CompletedProcess (subprocess のクラス)
  • complex
    • number
    • オブジェクト
    • 組み込み関数, [1]
  • Complex (numbers のクラス)
  • complex (組み込みクラス)
  • complex literal
  • complex number
    • literals
    • オブジェクト, [1]
  • compound
    • statement
  • comprehensions
    • list
  • compress() (bz2 モジュール)
    • (bz2.BZ2Compressor のメソッド)
    • (gzip モジュール)
    • (itertools モジュール)
    • (lzma モジュール)
    • (lzma.LZMACompressor のメソッド)
    • (zlib モジュール)
    • (zlib.Compress のメソッド)
  • compress_size (zipfile.ZipInfo の属性)
  • compress_type (zipfile.ZipInfo の属性)
  • compressed (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • compression() (ssl.SSLSocket のメソッド)
  • CompressionError
  • compressobj() (zlib モジュール)
  • COMSPEC, [1]
  • concat() (operator モジュール)
  • concatenation
    • operation
  • concurrent.futures (モジュール)
  • Condition (asyncio のクラス)
    • (multiprocessing のクラス)
  • condition (pdb command)
  • Condition (threading のクラス)
  • condition() (msilib.Control のメソッド)
  • Condition() (multiprocessing.managers.SyncManager のメソッド)
  • Conditional
    • expression
  • conditional
    • expression
  • ConfigParser (configparser のクラス)
  • configparser (モジュール)
  • configuration
    • file
    • file, debugger
    • file, path
  • configuration information
  • configure() (tkinter.ttk.Style のメソッド)
  • configure_mock() (unittest.mock.Mock のメソッド)
  • confstr() (os モジュール)
  • confstr_names (os モジュール)
  • conjugate() (complex number method)
    • (decimal.Decimal のメソッド)
    • (numbers.Complex のメソッド)
  • conn (smtpd.SMTPChannel の属性)
  • connect() (asyncore.dispatcher のメソッド)
    • (ftplib.FTP のメソッド)
    • (http.client.HTTPConnection のメソッド)
    • (multiprocessing.managers.BaseManager のメソッド)
    • (smtplib.SMTP のメソッド)
    • (socket.socket のメソッド)
    • (sqlite3 モジュール)
  • connect_accepted_socket() (asyncio.loop のメソッド)
  • connect_ex() (socket.socket のメソッド)
  • connect_read_pipe() (asyncio.loop のメソッド)
  • connect_write_pipe() (asyncio.loop のメソッド)
  • Connection (multiprocessing.connection のクラス)
    • (sqlite3 のクラス)
  • connection (sqlite3.Cursor の属性)
  • connection_lost() (asyncio.BaseProtocol のメソッド)
  • connection_made() (asyncio.BaseProtocol のメソッド)
  • ConnectionAbortedError
  • ConnectionError
  • ConnectionRefusedError
  • ConnectionResetError
  • ConnectRegistry() (winreg モジュール)
  • const (optparse.Option の属性)
  • constant
  • constructor
    • class
  • constructor() (copyreg モジュール)
  • consumed (asyncio.LimitOverrunError の属性)
  • container, [1]
    • iteration over
  • Container (collections.abc のクラス)
    • (typing のクラス)
  • contains() (operator モジュール)
  • content type
    • MIME
  • content_manager (email.policy.EmailPolicy の属性)
  • content_type (email.headerregistry.ContentTypeHeader の属性)
  • ContentDispositionHeader (email.headerregistry のクラス)
  • ContentHandler (xml.sax.handler のクラス)
  • ContentManager (email.contentmanager のクラス)
  • contents (ctypes._Pointer の属性)
  • contents() (importlib.abc.ResourceReader のメソッド)
    • (importlib.resources モジュール)
  • ContentTooShortError
  • ContentTransferEncoding (email.headerregistry のクラス)
  • ContentTypeHeader (email.headerregistry のクラス)
  • Context (contextvars のクラス)
    • (decimal のクラス)
  • context (ssl.SSLSocket の属性)
  • context management protocol
  • context manager, [1], [2]
  • context_diff() (difflib モジュール)
  • ContextDecorator (contextlib のクラス)
  • contextlib (モジュール)
  • ContextManager (typing のクラス)
  • contextmanager() (contextlib モジュール)
  • ContextVar (contextvars のクラス)
  • contextvars (モジュール)
  • contextvars.Token (contextvars のクラス)
  • contiguous, [1]
    • (memoryview の属性)
  • continue
    • 文, [1], [2], [3], [4]
  • continue (pdb command)
  • CONTINUE_LOOP (opcode)
  • Control (msilib のクラス)
    • (tkinter.tix のクラス)
  • control() (msilib.Dialog のメソッド)
    • (select.kqueue のメソッド)
  • controlnames (curses.ascii モジュール)
  • controls() (ossaudiodev.oss_mixer_device のメソッド)
  • conversion
    • arithmetic
    • string, [1]
  • ConversionError
  • conversions
    • numeric
  • convert_arg_line_to_args() (argparse.ArgumentParser のメソッド)
  • convert_field() (string.Formatter のメソッド)
  • convert_path() (distutils.util モジュール)
  • Cookie (http.cookiejar のクラス)
  • CookieError
  • CookieJar (http.cookiejar のクラス)
  • cookiejar (urllib.request.HTTPCookieProcessor の属性)
  • CookiePolicy (http.cookiejar のクラス)
  • Coordinated Universal Time
  • Copy
  • copy
    • protocol
    • モジュール
  • copy (モジュール)
  • copy() (collections.deque のメソッド)
    • (contextvars.Context のメソッド)
    • (copy モジュール)
    • (decimal.Context のメソッド)
    • (dict のメソッド)
    • (frozenset のメソッド)
    • (hashlib.hash のメソッド)
    • (hmac.HMAC のメソッド)
    • (http.cookies.Morsel のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (multiprocessing.sharedctypes モジュール)
    • (pipes.Template のメソッド)
    • (sequence method)
    • (shutil モジュール)
    • (types.MappingProxyType のメソッド)
    • (zlib.Compress のメソッド)
    • (zlib.Decompress のメソッド)
  • copy2() (shutil モジュール)
  • copy_abs() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • copy_context() (contextvars モジュール)
  • copy_decimal() (decimal.Context のメソッド)
  • copy_file() (distutils.file_util モジュール)
  • copy_location() (ast モジュール)
  • copy_negate() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • copy_sign() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • copy_tree() (distutils.dir_util モジュール)
  • copyfile() (shutil モジュール)
  • copyfileobj() (shutil モジュール)
  • copying files
  • copymode() (shutil モジュール)
  • copyreg (モジュール)
  • copyright (in module sys)
    • (sys モジュール)
    • (組み込み変数)
  • copysign() (math モジュール)
  • copystat() (shutil モジュール)
  • copytree() (shutil モジュール)
  • coroutine, [1], [2]
    • function
  • Coroutine (collections.abc のクラス)
    • (typing のクラス)
  • coroutine function
  • coroutine() (asyncio モジュール)
    • (types モジュール)
  • CoroutineType (types モジュール)
  • cos() (cmath モジュール)
    • (math モジュール)
  • cosh() (cmath モジュール)
    • (math モジュール)
  • count (tracemalloc.Statistic の属性)
    • (tracemalloc.StatisticDiff の属性)
  • count() (array.array のメソッド)
    • (bytearray のメソッド)
    • (bytes のメソッド)
    • (collections.deque のメソッド)
    • (itertools モジュール)
    • (sequence method)
    • (str のメソッド)
  • count_diff (tracemalloc.StatisticDiff の属性)
  • Counter (collections のクラス)
    • (typing のクラス)
  • countOf() (operator モジュール)
  • countTestCases() (unittest.TestCase のメソッド)
    • (unittest.TestSuite のメソッド)
  • CoverageResults (trace のクラス)
  • CPP
  • CPPFLAGS
  • cProfile (モジュール)
  • CPU time, [1], [2]
  • cpu_count() (multiprocessing モジュール)
    • (os モジュール)
  • CPython
  • cpython_only() (test.support モジュール)
  • crawl_delay() (urllib.robotparser.RobotFileParser のメソッド)
  • CRC (zipfile.ZipInfo の属性)
  • crc32() (binascii モジュール)
    • (zlib モジュール)
  • crc_hqx() (binascii モジュール)
  • create() (imaplib.IMAP4 のメソッド)
    • (venv モジュール)
    • (venv.EnvBuilder のメソッド)
  • create_aggregate() (sqlite3.Connection のメソッド)
  • create_archive() (zipapp モジュール)
  • create_autospec() (unittest.mock モジュール)
  • CREATE_BREAKAWAY_FROM_JOB (subprocess モジュール)
  • create_collation() (sqlite3.Connection のメソッド)
  • create_configuration() (venv.EnvBuilder のメソッド)
  • create_connection() (asyncio.loop のメソッド)
    • (socket モジュール)
  • create_datagram_endpoint() (asyncio.loop のメソッド)
  • create_decimal() (decimal.Context のメソッド)
  • create_decimal_from_float() (decimal.Context のメソッド)
  • create_default_context() (ssl モジュール)
  • CREATE_DEFAULT_ERROR_MODE (subprocess モジュール)
  • create_empty_file() (test.support モジュール)
  • create_function() (sqlite3.Connection のメソッド)
  • create_future() (asyncio.loop のメソッド)
  • create_module (C の関数)
  • create_module() (importlib.abc.Loader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
  • CREATE_NEW_CONSOLE (subprocess モジュール)
  • CREATE_NEW_PROCESS_GROUP (subprocess モジュール)
  • CREATE_NO_WINDOW (subprocess モジュール)
  • create_server() (asyncio.loop のメソッド)
  • create_shortcut() (組み込み関数)
  • create_socket() (asyncore.dispatcher のメソッド)
  • create_static_lib() (distutils.ccompiler.CCompiler のメソッド)
  • create_stats() (profile.Profile のメソッド)
  • create_string_buffer() (ctypes モジュール)
  • create_subprocess_exec() (asyncio モジュール)
  • create_subprocess_shell() (asyncio モジュール)
  • create_system (zipfile.ZipInfo の属性)
  • create_task() (asyncio モジュール)
    • (asyncio.loop のメソッド)
  • create_tree() (distutils.dir_util モジュール)
  • create_unicode_buffer() (ctypes モジュール)
  • create_unix_connection() (asyncio.loop のメソッド)
  • create_unix_server() (asyncio.loop のメソッド)
  • create_version (zipfile.ZipInfo の属性)
  • createAttribute() (xml.dom.Document のメソッド)
  • createAttributeNS() (xml.dom.Document のメソッド)
  • createComment() (xml.dom.Document のメソッド)
  • createDocument() (xml.dom.DOMImplementation のメソッド)
  • createDocumentType() (xml.dom.DOMImplementation のメソッド)
  • createElement() (xml.dom.Document のメソッド)
  • createElementNS() (xml.dom.Document のメソッド)
  • createfilehandler() (tkinter.Widget.tk のメソッド)
  • CreateKey() (winreg モジュール)
  • CreateKeyEx() (winreg モジュール)
  • createLock() (logging.Handler のメソッド)
    • (logging.NullHandler のメソッド)
  • createProcessingInstruction() (xml.dom.Document のメソッド)
  • CreateRecord() (msilib モジュール)
  • createSocket() (logging.handlers.SocketHandler のメソッド)
  • createTextNode() (xml.dom.Document のメソッド)
  • credits (組み込み変数)
  • critical() (logging モジュール)
    • (logging.Logger のメソッド)
  • CRNCYSTR (locale モジュール)
  • cross() (audioop モジュール)
  • crypt
    • モジュール
  • crypt (モジュール)
  • crypt() (crypt モジュール)
  • crypt(3), [1], [2]
  • cryptography
  • cssclass_month (calendar.HTMLCalendar の属性)
  • cssclass_month_head (calendar.HTMLCalendar の属性)
  • cssclass_noday (calendar.HTMLCalendar の属性)
  • cssclass_year (calendar.HTMLCalendar の属性)
  • cssclass_year_head (calendar.HTMLCalendar の属性)
  • cssclasses (calendar.HTMLCalendar の属性)
  • cssclasses_weekday_head (calendar.HTMLCalendar の属性)
  • csv
    • (モジュール)
  • cte (email.headerregistry.ContentTransferEncoding の属性)
  • cte_type (email.policy.Policy の属性)
  • ctermid() (os モジュール)
  • ctime() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (time モジュール)
  • ctrl() (curses.ascii モジュール)
  • CTRL_BREAK_EVENT (signal モジュール)
  • CTRL_C_EVENT (signal モジュール)
  • ctypes (モジュール)
  • curdir (os モジュール)
  • currency() (locale モジュール)
  • current() (tkinter.ttk.Combobox のメソッド)
  • current_process() (multiprocessing モジュール)
  • current_task() (asyncio モジュール)
    • (asyncio.Task のクラスメソッド)
  • current_thread() (threading モジュール)
  • CurrentByteIndex (xml.parsers.expat.xmlparser の属性)
  • CurrentColumnNumber (xml.parsers.expat.xmlparser の属性)
  • currentframe() (inspect モジュール)
  • CurrentLineNumber (xml.parsers.expat.xmlparser の属性)
  • curs_set() (curses モジュール)
  • curses (モジュール)
  • curses.ascii (モジュール)
  • curses.panel (モジュール)
  • curses.textpad (モジュール)
  • Cursor (sqlite3 のクラス)
  • cursor() (sqlite3.Connection のメソッド)
  • cursyncup() (curses.window のメソッド)
  • customize_compiler() (distutils.sysconfig モジュール)
  • Cut
  • cwd() (ftplib.FTP のメソッド)
    • (pathlib.Path のクラスメソッド)
  • cycle() (itertools モジュール)
  • Cyclic Redundancy Check

D

  • D_FMT (locale モジュール)
  • D_T_FMT (locale モジュール)
  • daemon (multiprocessing.Process の属性)
    • (threading.Thread の属性)
  • dangling
    • else
  • data
    • packing binary
    • tabular
    • type
    • type, immutable
  • data (collections.UserDict の属性)
    • (collections.UserList の属性)
    • (collections.UserString の属性)
  • Data (plistlib のクラス)
  • data (select.kevent の属性)
    • (selectors.SelectorKey の属性)
    • (urllib.request.Request の属性)
    • (xml.dom.Comment の属性)
    • (xml.dom.ProcessingInstruction の属性)
    • (xml.dom.Text の属性)
    • (xmlrpc.client.Binary の属性)
  • data() (xml.etree.ElementTree.TreeBuilder のメソッド)
  • data_open() (urllib.request.DataHandler のメソッド)
  • data_received() (asyncio.Protocol のメソッド)
  • database
    • Unicode
  • DatabaseError
  • databases
  • dataclass() (dataclasses モジュール)
  • dataclasses (モジュール)
  • datagram_received() (asyncio.DatagramProtocol のメソッド)
  • DatagramHandler (logging.handlers のクラス)
  • DatagramProtocol (asyncio のクラス)
  • DatagramRequestHandler (socketserver のクラス)
  • DatagramTransport (asyncio のクラス)
  • DataHandler (urllib.request のクラス)
  • date (datetime のクラス)
  • date() (datetime.datetime のメソッド)
    • (nntplib.NNTP のメソッド)
  • date_time (zipfile.ZipInfo の属性)
  • date_time_string() (http.server.BaseHTTPRequestHandler のメソッド)
  • DateHeader (email.headerregistry のクラス)
  • datetime (datetime のクラス)
    • (email.headerregistry.DateHeader の属性)
  • DateTime (xmlrpc.client のクラス)
  • datetime (モジュール)
  • datum
  • day (datetime.date の属性)
    • (datetime.datetime の属性)
  • day_abbr (calendar モジュール)
  • day_name (calendar モジュール)
  • daylight (time モジュール)
  • Daylight Saving Time
  • DbfilenameShelf (shelve のクラス)
  • dbm (モジュール)
  • dbm.dumb (モジュール)
  • dbm.gnu
    • モジュール, [1]
  • dbm.gnu (モジュール)
  • dbm.ndbm
    • モジュール, [1]
  • dbm.ndbm (モジュール)
  • dcgettext() (locale モジュール)
  • deallocation, object
  • debug (imaplib.IMAP4 の属性)
  • DEBUG (re モジュール)
  • debug (shlex.shlex の属性)
    • (zipfile.ZipFile の属性)
  • debug() (doctest モジュール)
    • (logging モジュール)
    • (logging.Logger のメソッド)
    • (pipes.Template のメソッド)
    • (unittest.TestCase のメソッド)
    • (unittest.TestSuite のメソッド)
  • DEBUG_BYTECODE_SUFFIXES (importlib.machinery モジュール)
  • DEBUG_COLLECTABLE (gc モジュール)
  • DEBUG_LEAK (gc モジュール)
  • debug_print() (distutils.ccompiler.CCompiler のメソッド)
  • DEBUG_SAVEALL (gc モジュール)
  • debug_src() (doctest モジュール)
  • DEBUG_STATS (gc モジュール)
  • DEBUG_UNCOLLECTABLE (gc モジュール)
  • debugger, [1], [2]
    • configuration file
  • debugging
    • CGI
    • assertions
  • DebuggingServer (smtpd のクラス)
  • debuglevel (http.client.HTTPResponse の属性)
  • DebugRunner (doctest のクラス)
  • Decimal (decimal のクラス)
  • decimal (モジュール)
  • decimal literal
  • decimal() (unicodedata モジュール)
  • DecimalException (decimal のクラス)
  • decode
    • Codecs
  • decode (codecs.CodecInfo の属性)
  • decode() (base64 モジュール)
    • (bytearray のメソッド)
    • (bytes のメソッド)
    • (codecs モジュール)
    • (codecs.Codec のメソッド)
    • (codecs.IncrementalDecoder のメソッド)
    • (json.JSONDecoder のメソッド)
    • (quopri モジュール)
    • (uu モジュール)
    • (xmlrpc.client.Binary のメソッド)
    • (xmlrpc.client.DateTime のメソッド)
  • decode_header() (email.header モジュール)
    • (nntplib モジュール)
  • decode_params() (email.utils モジュール)
  • decode_rfc2231() (email.utils モジュール)
  • decode_source() (importlib.util モジュール)
  • decodebytes() (base64 モジュール)
  • DecodedGenerator (email.generator のクラス)
  • decodestring() (base64 モジュール)
    • (quopri モジュール)
  • decomposition() (unicodedata モジュール)
  • decompress() (bz2 モジュール)
    • (bz2.BZ2Decompressor のメソッド)
    • (gzip モジュール)
    • (lzma モジュール)
    • (lzma.LZMADecompressor のメソッド)
    • (zlib モジュール)
    • (zlib.Decompress のメソッド)
  • decompressobj() (zlib モジュール)
  • decorator
  • DEDENT (token モジュール)
  • DEDENT token, [1]
  • dedent() (textwrap モジュール)
  • deepcopy() (copy モジュール)
  • def
    • 文
  • def_prog_mode() (curses モジュール)
  • def_shell_mode() (curses モジュール)
  • default
    • parameter value
  • default (email.policy モジュール)
    • (inspect.Parameter の属性)
    • (optparse.Option の属性)
  • DEFAULT (unittest.mock モジュール)
  • default() (cmd.Cmd のメソッド)
    • (json.JSONEncoder のメソッド)
  • DEFAULT_BUFFER_SIZE (io モジュール)
  • default_bufsize (xml.dom.pulldom モジュール)
  • default_exception_handler() (asyncio.loop のメソッド)
  • default_factory (collections.defaultdict の属性)
  • DEFAULT_FORMAT (tarfile モジュール)
  • DEFAULT_IGNORES (filecmp モジュール)
  • default_open() (urllib.request.BaseHandler のメソッド)
  • DEFAULT_PROTOCOL (pickle モジュール)
  • default_timer() (timeit モジュール)
  • DefaultContext (decimal のクラス)
  • DefaultCookiePolicy (http.cookiejar のクラス)
  • defaultdict (collections のクラス)
  • DefaultDict (typing のクラス)
  • DefaultEventLoopPolicy (asyncio のクラス)
  • DefaultHandler() (xml.parsers.expat.xmlparser のメソッド)
  • DefaultHandlerExpand() (xml.parsers.expat.xmlparser のメソッド)
  • defaults() (configparser.ConfigParser のメソッド)
  • DefaultSelector (selectors のクラス)
  • defaultTestLoader (unittest モジュール)
  • defaultTestResult() (unittest.TestCase のメソッド)
  • defects (email.headerregistry.BaseHeader の属性)
    • (email.message.EmailMessage の属性)
    • (email.message.Message の属性)
  • define_macro() (distutils.ccompiler.CCompiler のメソッド)
  • definition
    • class, [1]
    • function, [1]
  • defpath (os モジュール)
  • DefragResult (urllib.parse のクラス)
  • DefragResultBytes (urllib.parse のクラス)
  • degrees() (math モジュール)
    • (turtle モジュール)
  • del
    • 文, [1], [2], [3]
  • del_param() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • delattr() (組み込み関数)
  • delay() (turtle モジュール)
  • delay_output() (curses モジュール)
  • delayload (http.cookiejar.FileCookieJar の属性)
  • delch() (curses.window のメソッド)
  • dele() (poplib.POP3 のメソッド)
  • delete() (ftplib.FTP のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
  • DELETE_ATTR (opcode)
  • DELETE_DEREF (opcode)
  • DELETE_FAST (opcode)
  • DELETE_GLOBAL (opcode)
  • DELETE_NAME (opcode)
  • DELETE_SUBSCR (opcode)
  • deleteacl() (imaplib.IMAP4 のメソッド)
  • deletefilehandler() (tkinter.Widget.tk のメソッド)
  • DeleteKey() (winreg モジュール)
  • DeleteKeyEx() (winreg モジュール)
  • deleteln() (curses.window のメソッド)
  • deleteMe() (bdb.Breakpoint のメソッド)
  • DeleteValue() (winreg モジュール)
  • deletion
    • attribute
    • target
    • target list
  • delimiter (csv.Dialect の属性)
  • delimiters
  • delitem() (operator モジュール)
  • deliver_challenge() (multiprocessing.connection モジュール)
  • delocalize() (locale モジュール)
  • demo_app() (wsgiref.simple_server モジュール)
  • denominator (fractions.Fraction の属性)
    • (numbers.Rational の属性)
  • DeprecationWarning
  • deque (collections のクラス)
  • Deque (typing のクラス)
  • dequeue() (logging.handlers.QueueListener のメソッド)
  • DER_cert_to_PEM_cert() (ssl モジュール)
  • derwin() (curses.window のメソッド)
  • DES
    • cipher
  • description (sqlite3.Cursor の属性)
  • description() (nntplib.NNTP のメソッド)
  • descriptions() (nntplib.NNTP のメソッド)
  • descriptor
  • dest (optparse.Option の属性)
  • destructor, [1]
  • detach() (io.BufferedIOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (socket.socket のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
    • (weakref.finalize のメソッド)
  • Detach() (winreg.PyHKEY のメソッド)
  • DETACHED_PROCESS (subprocess モジュール)
  • detect_api_mismatch() (test.support モジュール)
  • detect_encoding() (tokenize モジュール)
  • detect_language() (distutils.ccompiler.CCompiler のメソッド)
  • deterministic profiling
  • device_encoding() (os モジュール)
  • devnull (os モジュール)
  • DEVNULL (subprocess モジュール)
  • devpoll() (select モジュール)
  • DevpollSelector (selectors のクラス)
  • dgettext() (gettext モジュール)
    • (locale モジュール)
  • Dialect (csv のクラス)
  • dialect (csv.csvreader の属性)
    • (csv.csvwriter の属性)
  • Dialog (msilib のクラス)
  • dict (2to3 fixer)
  • Dict (typing のクラス)
  • dict (組み込みクラス)
  • dict() (multiprocessing.managers.SyncManager のメソッド)
  • dictConfig() (logging.config モジュール)
  • dictionary
    • display
    • type, operations on
    • オブジェクト, [1], [2], [3], [4], [5], [6], [7]
  • dictionary view
  • DictReader (csv のクラス)
  • DictWriter (csv のクラス)
  • diff_bytes() (difflib モジュール)
  • diff_files (filecmp.dircmp の属性)
  • Differ (difflib のクラス), [1]
  • difference() (frozenset のメソッド)
  • difference_update() (frozenset のメソッド)
  • difflib (モジュール)
  • digest() (hashlib.hash のメソッド)
    • (hashlib.shake のメソッド)
    • (hmac モジュール)
    • (hmac.HMAC のメソッド)
  • digest_size (hmac.HMAC の属性)
  • digit() (unicodedata モジュール)
  • digits (string モジュール)
  • dir() (ftplib.FTP のメソッド)
    • (組み込み関数)
  • dircmp (filecmp のクラス)
  • directory
    • changing
    • creating
    • deleting, [1]
    • site-packages
    • traversal, [1]
    • walking, [1]
  • directory (http.server.SimpleHTTPRequestHandler の属性)
  • Directory (msilib のクラス)
  • directory ...
    • compileall コマンドラインオプション
  • directory_created() (組み込み関数)
  • DirEntry (os のクラス)
  • DirList (tkinter.tix のクラス)
  • dirname() (os.path モジュール)
  • DirSelectBox (tkinter.tix のクラス)
  • DirSelectDialog (tkinter.tix のクラス)
  • DirsOnSysPath (test.support のクラス)
  • DirTree (tkinter.tix のクラス)
  • dis (モジュール)
  • dis() (dis モジュール)
    • (dis.Bytecode のメソッド)
    • (pickletools モジュール)
  • disable (pdb command)
  • disable() (bdb.Breakpoint のメソッド)
    • (faulthandler モジュール)
    • (gc モジュール)
    • (logging モジュール)
    • (profile.Profile のメソッド)
  • disable_faulthandler() (test.support モジュール)
  • disable_gc() (test.support モジュール)
  • disable_interspersed_args() (optparse.OptionParser のメソッド)
  • DisableReflectionKey() (winreg モジュール)
  • disassemble() (dis モジュール)
  • discard (http.cookiejar.Cookie の属性)
  • discard() (frozenset のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.Mailbox のメソッド)
  • discard_buffers() (asynchat.async_chat のメソッド)
  • disco() (dis モジュール)
  • discover() (unittest.TestLoader のメソッド)
  • disk_usage() (shutil モジュール)
  • dispatch_call() (bdb.Bdb のメソッド)
  • dispatch_exception() (bdb.Bdb のメソッド)
  • dispatch_line() (bdb.Bdb のメソッド)
  • dispatch_return() (bdb.Bdb のメソッド)
  • dispatch_table (pickle.Pickler の属性)
  • dispatcher (asyncore のクラス)
  • dispatcher_with_send (asyncore のクラス)
  • display
    • dictionary
    • list
    • set
    • tuple
  • display (pdb command)
  • display_name (email.headerregistry.Address の属性)
    • (email.headerregistry.Group の属性)
  • displayhook() (sys モジュール)
  • dist() (platform モジュール)
  • distance() (turtle モジュール)
  • distb() (dis モジュール)
  • Distribution (distutils.core のクラス)
  • distutils (モジュール)
  • distutils.archive_util (モジュール)
  • distutils.bcppcompiler (モジュール)
  • distutils.ccompiler (モジュール)
  • distutils.cmd (モジュール)
  • distutils.command (モジュール)
  • distutils.command.bdist (モジュール)
  • distutils.command.bdist_dumb (モジュール)
  • distutils.command.bdist_msi (モジュール)
  • distutils.command.bdist_packager (モジュール)
  • distutils.command.bdist_rpm (モジュール)
  • distutils.command.bdist_wininst (モジュール)
  • distutils.command.build (モジュール)
  • distutils.command.build_clib (モジュール)
  • distutils.command.build_ext (モジュール)
  • distutils.command.build_py (モジュール)
  • distutils.command.build_scripts (モジュール)
  • distutils.command.check (モジュール)
  • distutils.command.clean (モジュール)
  • distutils.command.config (モジュール)
  • distutils.command.install (モジュール)
  • distutils.command.install_data (モジュール)
  • distutils.command.install_headers (モジュール)
  • distutils.command.install_lib (モジュール)
  • distutils.command.install_scripts (モジュール)
  • distutils.command.register (モジュール)
  • distutils.command.sdist (モジュール)
  • distutils.core (モジュール)
  • distutils.cygwinccompiler (モジュール)
  • distutils.debug (モジュール)
  • distutils.dep_util (モジュール)
  • distutils.dir_util (モジュール)
  • distutils.dist (モジュール)
  • distutils.errors (モジュール)
  • distutils.extension (モジュール)
  • distutils.fancy_getopt (モジュール)
  • distutils.file_util (モジュール)
  • distutils.filelist (モジュール)
  • distutils.log (モジュール)
  • distutils.msvccompiler (モジュール)
  • distutils.spawn (モジュール)
  • distutils.sysconfig (モジュール)
  • distutils.text_file (モジュール)
  • distutils.unixccompiler (モジュール)
  • distutils.util (モジュール)
  • distutils.version (モジュール)
  • DISTUTILS_DEBUG
  • divide() (decimal.Context のメソッド)
  • divide_int() (decimal.Context のメソッド)
  • division
  • DivisionByZero (decimal のクラス)
  • divmod
    • 組み込み関数, [1], [2]
  • divmod() (decimal.Context のメソッド)
    • (組み込み関数)
  • DllCanUnloadNow() (ctypes モジュール)
  • DllGetClassObject() (ctypes モジュール)
  • dllhandle (sys モジュール)
  • dngettext() (gettext モジュール)
  • do_clear() (bdb.Bdb のメソッド)
  • do_command() (curses.textpad.Textbox のメソッド)
  • do_GET() (http.server.SimpleHTTPRequestHandler のメソッド)
  • do_handshake() (ssl.SSLSocket のメソッド)
  • do_HEAD() (http.server.SimpleHTTPRequestHandler のメソッド)
  • do_POST() (http.server.CGIHTTPRequestHandler のメソッド)
  • doc (json.JSONDecodeError の属性)
  • doc_header (cmd.Cmd の属性)
  • DocCGIXMLRPCRequestHandler (xmlrpc.server のクラス)
  • DocFileSuite() (doctest モジュール)
  • doCleanups() (unittest.TestCase のメソッド)
  • docmd() (smtplib.SMTP のメソッド)
  • docstring, [1]
    • (doctest.DocTest の属性)
  • docstrings, [1]
  • DocTest (doctest のクラス)
  • doctest (モジュール)
  • DocTestFailure
  • DocTestFinder (doctest のクラス)
  • DocTestParser (doctest のクラス)
  • DocTestRunner (doctest のクラス)
  • DocTestSuite() (doctest モジュール)
  • doctype() (xml.etree.ElementTree.TreeBuilder のメソッド)
    • (xml.etree.ElementTree.XMLParser のメソッド)
  • documentation
    • generation
    • online
  • documentation string
  • documentation strings, [1]
  • documentElement (xml.dom.Document の属性)
  • DocXMLRPCRequestHandler (xmlrpc.server のクラス)
  • DocXMLRPCServer (xmlrpc.server のクラス)
  • domain (email.headerregistry.Address の属性)
    • (tracemalloc.DomainFilter の属性)
    • (tracemalloc.Filter の属性)
    • (tracemalloc.Trace の属性)
  • domain_initial_dot (http.cookiejar.Cookie の属性)
  • domain_return_ok() (http.cookiejar.CookiePolicy のメソッド)
  • domain_specified (http.cookiejar.Cookie の属性)
  • DomainFilter (tracemalloc のクラス)
  • DomainLiberal (http.cookiejar.DefaultCookiePolicy の属性)
  • DomainRFC2965Match (http.cookiejar.DefaultCookiePolicy の属性)
  • DomainStrict (http.cookiejar.DefaultCookiePolicy の属性)
  • DomainStrictNoDots (http.cookiejar.DefaultCookiePolicy の属性)
  • DomainStrictNonDomain (http.cookiejar.DefaultCookiePolicy の属性)
  • DOMEventStream (xml.dom.pulldom のクラス)
  • DOMException
  • DomstringSizeErr
  • done() (asyncio.Future のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
    • (turtle モジュール)
    • (xdrlib.Unpacker のメソッド)
  • DONT_ACCEPT_BLANKLINE (doctest モジュール)
  • DONT_ACCEPT_TRUE_FOR_1 (doctest モジュール)
  • dont_write_bytecode (sys モジュール)
  • doRollover() (logging.handlers.RotatingFileHandler のメソッド)
    • (logging.handlers.TimedRotatingFileHandler のメソッド)
  • DOT (token モジュール)
  • dot() (turtle モジュール)
  • DOTALL (re モジュール)
  • doublequote (csv.Dialect の属性)
  • DOUBLESLASH (token モジュール)
  • DOUBLESLASHEQUAL (token モジュール)
  • DOUBLESTAR (token モジュール)
  • DOUBLESTAREQUAL (token モジュール)
  • doupdate() (curses モジュール)
  • down (pdb command)
  • down() (turtle モジュール)
  • drain() (asyncio.StreamWriter のメソッド)
  • drop_whitespace (textwrap.TextWrapper の属性)
  • dropwhile() (itertools モジュール)
  • dst() (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (datetime.timezone のメソッド)
    • (datetime.tzinfo のメソッド)
  • DTDHandler (xml.sax.handler のクラス)
  • duck-typing
  • DumbWriter (formatter のクラス)
  • dummy_threading (モジュール)
  • dump() (ast モジュール)
    • (json モジュール)
    • (marshal モジュール)
    • (pickle モジュール)
    • (pickle.Pickler のメソッド)
    • (plistlib モジュール)
    • (tracemalloc.Snapshot のメソッド)
    • (xml.etree.ElementTree モジュール)
  • dump_stats() (profile.Profile のメソッド)
    • (pstats.Stats のメソッド)
  • dump_traceback() (faulthandler モジュール)
  • dump_traceback_later() (faulthandler モジュール)
  • dumps() (json モジュール)
    • (marshal モジュール)
    • (pickle モジュール)
    • (plistlib モジュール)
    • (xmlrpc.client モジュール)
  • dup() (os モジュール)
    • (socket.socket のメソッド)
  • dup2() (os モジュール)
  • DUP_TOP (opcode)
  • DUP_TOP_TWO (opcode)
  • DuplicateOptionError
  • DuplicateSectionError
  • dwFlags (subprocess.STARTUPINFO の属性)
  • DynamicClassAttribute() (types モジュール)

E

  • e
    • in numeric literal
  • e (cmath モジュール)
    • (math モジュール)
  • E2BIG (errno モジュール)
  • EACCES (errno モジュール)
  • EADDRINUSE (errno モジュール)
  • EADDRNOTAVAIL (errno モジュール)
  • EADV (errno モジュール)
  • EAFNOSUPPORT (errno モジュール)
  • EAFP
  • EAGAIN (errno モジュール)
  • EALREADY (errno モジュール)
  • east_asian_width() (unicodedata モジュール)
  • EBADE (errno モジュール)
  • EBADF (errno モジュール)
  • EBADFD (errno モジュール)
  • EBADMSG (errno モジュール)
  • EBADR (errno モジュール)
  • EBADRQC (errno モジュール)
  • EBADSLT (errno モジュール)
  • EBFONT (errno モジュール)
  • EBUSY (errno モジュール)
  • ECHILD (errno モジュール)
  • echo() (curses モジュール)
  • echochar() (curses.window のメソッド)
  • ECHRNG (errno モジュール)
  • ECOMM (errno モジュール)
  • ECONNABORTED (errno モジュール)
  • ECONNREFUSED (errno モジュール)
  • ECONNRESET (errno モジュール)
  • EDEADLK (errno モジュール)
  • EDEADLOCK (errno モジュール)
  • EDESTADDRREQ (errno モジュール)
  • edit() (curses.textpad.Textbox のメソッド)
  • EDOM (errno モジュール)
  • EDOTDOT (errno モジュール)
  • EDQUOT (errno モジュール)
  • EEXIST (errno モジュール)
  • EFAULT (errno モジュール)
  • EFBIG (errno モジュール)
  • effective() (bdb モジュール)
  • ehlo() (smtplib.SMTP のメソッド)
  • ehlo_or_helo_if_needed() (smtplib.SMTP のメソッド)
  • EHOSTDOWN (errno モジュール)
  • EHOSTUNREACH (errno モジュール)
  • EIDRM (errno モジュール)
  • EILSEQ (errno モジュール)
  • EINPROGRESS (errno モジュール)
  • EINTR (errno モジュール)
  • EINVAL (errno モジュール)
  • EIO (errno モジュール)
  • EISCONN (errno モジュール)
  • EISDIR (errno モジュール)
  • EISNAM (errno モジュール)
  • EL2HLT (errno モジュール)
  • EL2NSYNC (errno モジュール)
  • EL3HLT (errno モジュール)
  • EL3RST (errno モジュール)
  • Element (xml.etree.ElementTree のクラス)
  • element_create() (tkinter.ttk.Style のメソッド)
  • element_names() (tkinter.ttk.Style のメソッド)
  • element_options() (tkinter.ttk.Style のメソッド)
  • ElementDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • elements() (collections.Counter のメソッド)
  • ElementTree (xml.etree.ElementTree のクラス)
  • ELIBACC (errno モジュール)
  • ELIBBAD (errno モジュール)
  • ELIBEXEC (errno モジュール)
  • ELIBMAX (errno モジュール)
  • ELIBSCN (errno モジュール)
  • elif
    • キーワード
  • Ellinghouse, Lance
  • Ellipsis
    • オブジェクト
  • ELLIPSIS (doctest モジュール)
    • (token モジュール)
  • Ellipsis (組み込み変数)
  • ELNRNG (errno モジュール)
  • ELOOP (errno モジュール)
  • else
    • conditional expression
    • dangling
    • キーワード, [1], [2], [3], [4], [5], [6], [7]
  • email (モジュール)
  • email.charset (モジュール)
  • email.contentmanager (モジュール)
  • email.encoders (モジュール)
  • email.errors (モジュール)
  • email.generator (モジュール)
  • email.header (モジュール)
  • email.headerregistry (モジュール)
  • email.iterators (モジュール)
  • email.message (モジュール), [1]
  • email.mime (モジュール)
  • email.parser (モジュール)
  • email.policy (モジュール)
  • email.utils (モジュール)
  • EmailMessage (email.message のクラス)
  • EmailPolicy (email.policy のクラス)
  • EMFILE (errno モジュール)
  • emit() (logging.FileHandler のメソッド)
    • (logging.Handler のメソッド)
    • (logging.NullHandler のメソッド)
    • (logging.StreamHandler のメソッド)
    • (logging.handlers.BufferingHandler のメソッド)
    • (logging.handlers.DatagramHandler のメソッド)
    • (logging.handlers.HTTPHandler のメソッド)
    • (logging.handlers.NTEventLogHandler のメソッド)
    • (logging.handlers.QueueHandler のメソッド)
    • (logging.handlers.RotatingFileHandler のメソッド)
    • (logging.handlers.SMTPHandler のメソッド)
    • (logging.handlers.SocketHandler のメソッド)
    • (logging.handlers.SysLogHandler のメソッド)
    • (logging.handlers.TimedRotatingFileHandler のメソッド)
    • (logging.handlers.WatchedFileHandler のメソッド)
  • EMLINK (errno モジュール)
  • Empty
  • empty
    • list
    • tuple, [1]
  • empty (inspect.Parameter の属性)
    • (inspect.Signature の属性)
  • empty() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (multiprocessing.SimpleQueue のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
    • (sched.scheduler のメソッド)
  • EMPTY_NAMESPACE (xml.dom モジュール)
  • emptyline() (cmd.Cmd のメソッド)
  • EMSGSIZE (errno モジュール)
  • EMULTIHOP (errno モジュール)
  • enable (pdb command)
  • enable() (bdb.Breakpoint のメソッド)
    • (cgitb モジュール)
    • (faulthandler モジュール)
    • (gc モジュール)
    • (imaplib.IMAP4 のメソッド)
    • (profile.Profile のメソッド)
  • enable_callback_tracebacks() (sqlite3 モジュール)
  • enable_interspersed_args() (optparse.OptionParser のメソッド)
  • enable_load_extension() (sqlite3.Connection のメソッド)
  • enable_traversal() (tkinter.ttk.Notebook のメソッド)
  • ENABLE_USER_SITE (site モジュール)
  • EnableReflectionKey() (winreg モジュール)
  • ENAMETOOLONG (errno モジュール)
  • ENAVAIL (errno モジュール)
  • enclose() (curses.window のメソッド)
  • encode
    • Codecs
  • encode (codecs.CodecInfo の属性)
  • encode() (base64 モジュール)
    • (codecs モジュール)
    • (codecs.Codec のメソッド)
    • (codecs.IncrementalEncoder のメソッド)
    • (email.header.Header のメソッド)
    • (json.JSONEncoder のメソッド)
    • (quopri モジュール)
    • (str のメソッド)
    • (uu モジュール)
    • (xmlrpc.client.Binary のメソッド)
    • (xmlrpc.client.DateTime のメソッド)
  • encode_7or8bit() (email.encoders モジュール)
  • encode_base64() (email.encoders モジュール)
  • encode_noop() (email.encoders モジュール)
  • encode_quopri() (email.encoders モジュール)
  • encode_rfc2231() (email.utils モジュール)
  • encodebytes() (base64 モジュール)
  • EncodedFile() (codecs モジュール)
  • encodePriority() (logging.handlers.SysLogHandler のメソッド)
  • encodestring() (base64 モジュール)
    • (quopri モジュール)
  • encoding
    • base64
    • quoted-printable
  • encoding (curses.window の属性)
    • (io.TextIOBase の属性)
  • ENCODING (tarfile モジュール)
    • (token モジュール)
  • encoding (UnicodeError の属性)
  • encoding declarations (source file)
  • encodings.idna (モジュール)
  • encodings.mbcs (モジュール)
  • encodings.utf_8_sig (モジュール)
  • encodings_map (mimetypes モジュール)
    • (mimetypes.MimeTypes の属性)
  • end (UnicodeError の属性)
  • end() (re.Match のメソッド)
    • (xml.etree.ElementTree.TreeBuilder のメソッド)
  • end_fill() (turtle モジュール)
  • END_FINALLY (opcode)
  • end_headers() (http.server.BaseHTTPRequestHandler のメソッド)
  • end_paragraph() (formatter.formatter のメソッド)
  • end_poly() (turtle モジュール)
  • EndCdataSectionHandler() (xml.parsers.expat.xmlparser のメソッド)
  • EndDoctypeDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • endDocument() (xml.sax.handler.ContentHandler のメソッド)
  • endElement() (xml.sax.handler.ContentHandler のメソッド)
  • EndElementHandler() (xml.parsers.expat.xmlparser のメソッド)
  • endElementNS() (xml.sax.handler.ContentHandler のメソッド)
  • endheaders() (http.client.HTTPConnection のメソッド)
  • ENDMARKER (token モジュール)
  • EndNamespaceDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • endpos (re.Match の属性)
  • endPrefixMapping() (xml.sax.handler.ContentHandler のメソッド)
  • endswith() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • endwin() (curses モジュール)
  • ENETDOWN (errno モジュール)
  • ENETRESET (errno モジュール)
  • ENETUNREACH (errno モジュール)
  • ENFILE (errno モジュール)
  • ENOANO (errno モジュール)
  • ENOBUFS (errno モジュール)
  • ENOCSI (errno モジュール)
  • ENODATA (errno モジュール)
  • ENODEV (errno モジュール)
  • ENOENT (errno モジュール)
  • ENOEXEC (errno モジュール)
  • ENOLCK (errno モジュール)
  • ENOLINK (errno モジュール)
  • ENOMEM (errno モジュール)
  • ENOMSG (errno モジュール)
  • ENONET (errno モジュール)
  • ENOPKG (errno モジュール)
  • ENOPROTOOPT (errno モジュール)
  • ENOSPC (errno モジュール)
  • ENOSR (errno モジュール)
  • ENOSTR (errno モジュール)
  • ENOSYS (errno モジュール)
  • ENOTBLK (errno モジュール)
  • ENOTCONN (errno モジュール)
  • ENOTDIR (errno モジュール)
  • ENOTEMPTY (errno モジュール)
  • ENOTNAM (errno モジュール)
  • ENOTSOCK (errno モジュール)
  • ENOTTY (errno モジュール)
  • ENOTUNIQ (errno モジュール)
  • enqueue() (logging.handlers.QueueHandler のメソッド)
  • enqueue_sentinel() (logging.handlers.QueueListener のメソッド)
  • ensure_directories() (venv.EnvBuilder のメソッド)
  • ensure_future() (asyncio モジュール)
  • ensurepip (モジュール)
  • enter() (sched.scheduler のメソッド)
  • enter_async_context() (contextlib.AsyncExitStack のメソッド)
  • enter_context() (contextlib.ExitStack のメソッド)
  • enterabs() (sched.scheduler のメソッド)
  • entities (xml.dom.DocumentType の属性)
  • EntityDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • entitydefs (html.entities モジュール)
  • EntityResolver (xml.sax.handler のクラス)
  • Enum (enum のクラス)
  • enum (モジュール)
  • enum_certificates() (ssl モジュール)
  • enum_crls() (ssl モジュール)
  • enumerate() (threading モジュール)
    • (組み込み関数)
  • EnumKey() (winreg モジュール)
  • EnumValue() (winreg モジュール)
  • EnvBuilder (venv のクラス)
  • environ (os モジュール)
    • (posix モジュール)
  • environb (os モジュール)
  • environment
  • environment variables
    • deleting
    • setting
  • EnvironmentError
  • Environments
    • virtual
  • EnvironmentVarGuard (test.support のクラス)
  • ENXIO (errno モジュール)
  • eof (bz2.BZ2Decompressor の属性)
    • (lzma.LZMADecompressor の属性)
    • (shlex.shlex の属性)
    • (ssl.MemoryBIO の属性)
    • (zlib.Decompress の属性)
  • eof_received() (asyncio.BufferedProtocol のメソッド)
    • (asyncio.Protocol のメソッド)
  • EOFError
    • (built-in exception)
  • EOPNOTSUPP (errno モジュール)
  • EOVERFLOW (errno モジュール)
  • EPERM (errno モジュール)
  • EPFNOSUPPORT (errno モジュール)
  • epilogue (email.message.EmailMessage の属性)
    • (email.message.Message の属性)
  • EPIPE (errno モジュール)
  • epoch
  • epoll() (select モジュール)
  • EpollSelector (selectors のクラス)
  • EPROTO (errno モジュール)
  • EPROTONOSUPPORT (errno モジュール)
  • EPROTOTYPE (errno モジュール)
  • eq() (operator モジュール)
  • EQEQUAL (token モジュール)
  • EQUAL (token モジュール)
  • ERA (locale モジュール)
  • ERA_D_FMT (locale モジュール)
  • ERA_D_T_FMT (locale モジュール)
  • ERA_T_FMT (locale モジュール)
  • ERANGE (errno モジュール)
  • erase() (curses.window のメソッド)
  • erasechar() (curses モジュール)
  • EREMCHG (errno モジュール)
  • EREMOTE (errno モジュール)
  • EREMOTEIO (errno モジュール)
  • ERESTART (errno モジュール)
  • erf() (math モジュール)
  • erfc() (math モジュール)
  • EROFS (errno モジュール)
  • ERR (curses モジュール)
  • errcheck (ctypes._FuncPtr の属性)
  • errcode (xmlrpc.client.ProtocolError の属性)
  • errmsg (xmlrpc.client.ProtocolError の属性)
  • errno
    • モジュール
  • errno (OSError の属性)
    • (モジュール)
  • Error, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]
  • error, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17]
  • error handling
  • error() (argparse.ArgumentParser のメソッド)
    • (logging モジュール)
    • (logging.Logger のメソッド)
    • (urllib.request.OpenerDirector のメソッド)
    • (xml.sax.handler.ErrorHandler のメソッド)
  • error_body (wsgiref.handlers.BaseHandler の属性)
  • error_content_type (http.server.BaseHTTPRequestHandler の属性)
  • error_headers (wsgiref.handlers.BaseHandler の属性)
  • error_leader() (shlex.shlex のメソッド)
  • error_message_format (http.server.BaseHTTPRequestHandler の属性)
  • error_output() (wsgiref.handlers.BaseHandler のメソッド)
  • error_perm
  • error_proto, [1]
  • error_received() (asyncio.DatagramProtocol のメソッド)
  • error_reply
  • error_status (wsgiref.handlers.BaseHandler の属性)
  • error_temp
  • ErrorByteIndex (xml.parsers.expat.xmlparser の属性)
  • errorcode (errno モジュール)
  • ErrorCode (xml.parsers.expat.xmlparser の属性)
  • ErrorColumnNumber (xml.parsers.expat.xmlparser の属性)
  • ErrorHandler (xml.sax.handler のクラス)
  • ErrorLineNumber (xml.parsers.expat.xmlparser の属性)
  • Errors
    • logging
  • errors
    • (io.TextIOBase の属性)
    • (unittest.TestLoader の属性)
    • (unittest.TestResult の属性)
  • ErrorString() (xml.parsers.expat モジュール)
  • ERRORTOKEN (token モジュール)
  • escape (shlex.shlex の属性)
  • escape sequence
  • escape() (cgi モジュール)
    • (glob モジュール)
    • (html モジュール)
    • (re モジュール)
    • (xml.sax.saxutils モジュール)
  • escapechar (csv.Dialect の属性)
  • escapedquotes (shlex.shlex の属性)
  • ESHUTDOWN (errno モジュール)
  • ESOCKTNOSUPPORT (errno モジュール)
  • ESPIPE (errno モジュール)
  • ESRCH (errno モジュール)
  • ESRMNT (errno モジュール)
  • ESTALE (errno モジュール)
  • ESTRPIPE (errno モジュール)
  • ETIME (errno モジュール)
  • ETIMEDOUT (errno モジュール)
  • Etiny() (decimal.Context のメソッド)
  • ETOOMANYREFS (errno モジュール)
  • Etop() (decimal.Context のメソッド)
  • ETXTBSY (errno モジュール)
  • EUCLEAN (errno モジュール)
  • EUNATCH (errno モジュール)
  • EUSERS (errno モジュール)
  • eval
    • 組み込み関数, [1], [2], [3], [4], [5]
  • eval() (組み込み関数)
  • evaluation
    • order
  • Event (asyncio のクラス)
    • (multiprocessing のクラス)
    • (threading のクラス)
  • event scheduling
  • event() (msilib.Control のメソッド)
  • Event() (multiprocessing.managers.SyncManager のメソッド)
  • events (selectors.SelectorKey の属性)
    • (widgets)
  • EWOULDBLOCK (errno モジュール)
  • EX_CANTCREAT (os モジュール)
  • EX_CONFIG (os モジュール)
  • EX_DATAERR (os モジュール)
  • EX_IOERR (os モジュール)
  • EX_NOHOST (os モジュール)
  • EX_NOINPUT (os モジュール)
  • EX_NOPERM (os モジュール)
  • EX_NOTFOUND (os モジュール)
  • EX_NOUSER (os モジュール)
  • EX_OK (os モジュール)
  • EX_OSERR (os モジュール)
  • EX_OSFILE (os モジュール)
  • EX_PROTOCOL (os モジュール)
  • EX_SOFTWARE (os モジュール)
  • EX_TEMPFAIL (os モジュール)
  • EX_UNAVAILABLE (os モジュール)
  • EX_USAGE (os モジュール)
  • Example (doctest のクラス)
  • example (doctest.DocTestFailure の属性)
    • (doctest.UnexpectedException の属性)
  • examples (doctest.DocTest の属性)
  • exc_info (doctest.UnexpectedException の属性)
    • (in module sys)
  • exc_info() (in module sys)
    • (sys モジュール)
  • exc_msg (doctest.Example の属性)
  • exc_type (traceback.TracebackException の属性)
  • excel (csv のクラス)
  • excel_tab (csv のクラス)
  • except
    • キーワード
    • 文
  • except (2to3 fixer)
  • excepthook() (in module sys)
    • (sys モジュール)
  • Exception
  • exception, [1]
    • chaining
    • handler
    • raising
  • EXCEPTION (tkinter モジュール)
  • exception handler
  • exception() (asyncio.Future のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
    • (logging モジュール)
    • (logging.Logger のメソッド)
  • exceptions
    • in CGI scripts
  • exclusive
    • or
  • EXDEV (errno モジュール)
  • exec
    • 組み込み関数, [1], [2], [3]
  • exec (2to3 fixer)
  • exec() (組み込み関数)
  • exec_module (C の関数)
  • exec_module() (importlib.abc.InspectLoader のメソッド)
    • (importlib.abc.Loader のメソッド)
    • (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
  • exec_prefix, [1], [2]
  • EXEC_PREFIX (distutils.sysconfig モジュール)
  • exec_prefix (sys モジュール)
  • execfile (2to3 fixer)
  • execl() (os モジュール)
  • execle() (os モジュール)
  • execlp() (os モジュール)
  • execlpe() (os モジュール)
  • executable (in module sys)
    • (sys モジュール)
  • Executable Zip Files
  • executable_filename() (distutils.ccompiler.CCompiler のメソッド)
  • execute() (distutils.ccompiler.CCompiler のメソッド)
    • (distutils.util モジュール)
  • Execute() (msilib.View のメソッド)
  • execute() (sqlite3.Connection のメソッド)
    • (sqlite3.Cursor のメソッド)
  • executemany() (sqlite3.Connection のメソッド)
    • (sqlite3.Cursor のメソッド)
  • executescript() (sqlite3.Connection のメソッド)
    • (sqlite3.Cursor のメソッド)
  • execution
    • frame, [1]
    • restricted
    • stack
  • execution model
  • ExecutionLoader (importlib.abc のクラス)
  • Executor (concurrent.futures のクラス)
  • execv() (os モジュール)
  • execve() (os モジュール)
  • execvp() (os モジュール)
  • execvpe() (os モジュール)
  • ExFileSelectBox (tkinter.tix のクラス)
  • EXFULL (errno モジュール)
  • exists() (os.path モジュール)
    • (pathlib.Path のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
  • exit (組み込み変数)
  • exit()
    • (_thread モジュール)
    • (argparse.ArgumentParser のメソッド)
    • (sys モジュール)
  • exitcode (multiprocessing.Process の属性)
  • exitfunc (2to3 fixer)
  • exitonclick() (turtle モジュール)
  • ExitStack (contextlib のクラス)
  • exp() (cmath モジュール)
    • (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (math モジュール)
  • expand() (re.Match のメソッド)
  • expand_tabs (textwrap.TextWrapper の属性)
  • ExpandEnvironmentStrings() (winreg モジュール)
  • expandNode() (xml.dom.pulldom.DOMEventStream のメソッド)
  • expandtabs() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • expanduser() (os.path モジュール)
    • (pathlib.Path のメソッド)
  • expandvars() (os.path モジュール)
  • Expat
  • ExpatError
  • expect() (telnetlib.Telnet のメソッド)
  • expected (asyncio.IncompleteReadError の属性)
  • expectedFailure() (unittest モジュール)
  • expectedFailures (unittest.TestResult の属性)
  • expires (http.cookiejar.Cookie の属性)
  • exploded (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • expm1() (math モジュール)
  • expovariate() (random モジュール)
  • expr() (parser モジュール)
  • expression, [1]
    • Conditional
    • conditional
    • generator
    • lambda, [1]
    • list, [1], [2]
    • statement
    • yield
  • expunge() (imaplib.IMAP4 のメソッド)
  • extend() (array.array のメソッド)
    • (collections.deque のメソッド)
    • (sequence method)
    • (xml.etree.ElementTree.Element のメソッド)
  • extend_path() (pkgutil モジュール)
  • EXTENDED_ARG (opcode)
  • ExtendedContext (decimal のクラス)
  • ExtendedInterpolation (configparser のクラス)
  • extendleft() (collections.deque のメソッド)
  • extension
    • module
  • Extension (distutils.core のクラス)
  • extension module
  • EXTENSION_SUFFIXES (importlib.machinery モジュール)
  • ExtensionFileLoader (importlib.machinery のクラス)
  • extensions_map (http.server.SimpleHTTPRequestHandler の属性)
  • External Data Representation, [1]
  • external_attr (zipfile.ZipInfo の属性)
  • ExternalClashError
  • ExternalEntityParserCreate() (xml.parsers.expat.xmlparser のメソッド)
  • ExternalEntityRefHandler() (xml.parsers.expat.xmlparser のメソッド)
  • extra (zipfile.ZipInfo の属性)
  • extract() (tarfile.TarFile のメソッド)
    • (traceback.StackSummary のクラスメソッド)
    • (zipfile.ZipFile のメソッド)
  • extract_cookies() (http.cookiejar.CookieJar のメソッド)
  • extract_stack() (traceback モジュール)
  • extract_tb() (traceback モジュール)
  • extract_version (zipfile.ZipInfo の属性)
  • extractall() (tarfile.TarFile のメソッド)
    • (zipfile.ZipFile のメソッド)
  • ExtractError
  • extractfile() (tarfile.TarFile のメソッド)
  • extsep (os モジュール)

F

  • f"
    • formatted string literal
  • f'
    • formatted string literal
  • f-string, [1]
  • f_back (frame attribute)
  • f_builtins (frame attribute)
  • f_code (frame attribute)
  • f_contiguous (memoryview の属性)
  • f_globals (frame attribute)
  • f_lasti (frame attribute)
  • f_lineno (frame attribute)
  • f_locals (frame attribute)
  • F_LOCK (os モジュール)
  • F_OK (os モジュール)
  • F_TEST (os モジュール)
  • F_TLOCK (os モジュール)
  • f_trace (frame attribute)
  • f_trace_lines (frame attribute)
  • f_trace_opcodes (frame attribute)
  • F_ULOCK (os モジュール)
  • fabs() (math モジュール)
  • factorial() (math モジュール)
  • factory() (importlib.util.LazyLoader のクラスメソッド)
  • fail() (unittest.TestCase のメソッド)
  • FAIL_FAST (doctest モジュール)
  • failfast (unittest.TestResult の属性)
  • failureException (unittest.TestCase の属性)
  • failures (unittest.TestResult の属性)
  • FakePath (test.support のクラス)
  • False, [1], [2]
  • false
  • False (Built-in object)
    • (組み込み変数)
  • family (socket.socket の属性)
  • fancy_getopt() (distutils.fancy_getopt モジュール)
  • FancyGetopt (distutils.fancy_getopt のクラス)
  • FancyURLopener (urllib.request のクラス)
  • fast (pickle.Pickler の属性)
  • FastChildWatcher (asyncio のクラス)
  • fatalError() (xml.sax.handler.ErrorHandler のメソッド)
  • Fault (xmlrpc.client のクラス)
  • faultCode (xmlrpc.client.Fault の属性)
  • faulthandler (モジュール)
  • faultString (xmlrpc.client.Fault の属性)
  • fchdir() (os モジュール)
  • fchmod() (os モジュール)
  • fchown() (os モジュール)
  • FCICreate() (msilib モジュール)
  • fcntl (モジュール)
  • fcntl() (fcntl モジュール)
  • fd (selectors.SelectorKey の属性)
  • fd() (turtle モジュール)
  • fd_count() (test.support モジュール)
  • fdatasync() (os モジュール)
  • fdopen() (os モジュール)
  • Feature (msilib のクラス)
  • feature_external_ges (xml.sax.handler モジュール)
  • feature_external_pes (xml.sax.handler モジュール)
  • feature_namespace_prefixes (xml.sax.handler モジュール)
  • feature_namespaces (xml.sax.handler モジュール)
  • feature_string_interning (xml.sax.handler モジュール)
  • feature_validation (xml.sax.handler モジュール)
  • feed() (email.parser.BytesFeedParser のメソッド)
    • (html.parser.HTMLParser のメソッド)
    • (xml.etree.ElementTree.XMLParser のメソッド)
    • (xml.etree.ElementTree.XMLPullParser のメソッド)
    • (xml.sax.xmlreader.IncrementalParser のメソッド)
  • FeedParser (email.parser のクラス)
  • fetch() (imaplib.IMAP4 のメソッド)
  • Fetch() (msilib.View のメソッド)
  • fetchall() (sqlite3.Cursor のメソッド)
  • fetchmany() (sqlite3.Cursor のメソッド)
  • fetchone() (sqlite3.Cursor のメソッド)
  • fflags (select.kevent の属性)
  • Field (dataclasses のクラス)
  • field() (dataclasses モジュール)
  • field_size_limit() (csv モジュール)
  • fieldnames (csv.csvreader の属性)
  • fields (uuid.UUID の属性)
  • fields() (dataclasses モジュール)
  • file
    • .ini
    • .pdbrc
    • byte-code, [1]
    • configuration
    • copying
    • debugger configuration
    • large files
    • mime.types
    • modes
    • path configuration
    • plist
    • temporary
    • オブジェクト, [1]
  • file (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
  • file ...
    • compileall コマンドラインオプション
  • file control
    • UNIX
  • file name
    • temporary
  • file object
    • io module
    • open() built-in function
  • file-like object
  • 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_NO_SCRUB_DATA (stat モジュール)
  • FILE_ATTRIBUTE_NORMAL (stat モジュール)
  • FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (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 (stat モジュール)
  • file_created() (組み込み関数)
  • file_dispatcher (asyncore のクラス)
  • file_open() (urllib.request.FileHandler のメソッド)
  • file_size (zipfile.ZipInfo の属性)
  • file_wrapper (asyncore のクラス)
  • filecmp (モジュール)
  • fileConfig() (logging.config モジュール)
  • FileCookieJar (http.cookiejar のクラス)
  • FileEntry (tkinter.tix のクラス)
  • FileExistsError
  • FileFinder (importlib.machinery のクラス)
  • FileHandler (logging のクラス)
    • (urllib.request のクラス)
  • FileInput (fileinput のクラス)
  • fileinput (モジュール)
  • FileIO (io のクラス)
  • filelineno() (fileinput モジュール)
  • FileLoader (importlib.abc のクラス)
  • filemode() (stat モジュール)
  • filename (doctest.DocTest の属性)
    • (OSError の属性)
    • (http.cookiejar.FileCookieJar の属性)
    • (traceback.TracebackException の属性)
    • (tracemalloc.Frame の属性)
    • (zipfile.ZipFile の属性)
    • (zipfile.ZipInfo の属性)
  • filename() (fileinput モジュール)
  • filename2 (OSError の属性)
  • filename_only (tabnanny モジュール)
  • filename_pattern (tracemalloc.Filter の属性)
  • filenames
    • pathname expansion
    • wildcard expansion
  • fileno() (fileinput モジュール)
    • (http.client.HTTPResponse のメソッド)
    • (io.IOBase のメソッド)
    • (multiprocessing.connection.Connection のメソッド)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (ossaudiodev.oss_mixer_device のメソッド)
    • (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.kqueue のメソッド)
    • (selectors.DevpollSelector のメソッド)
    • (selectors.EpollSelector のメソッド)
    • (selectors.KqueueSelector のメソッド)
    • (socket.socket のメソッド)
    • (socketserver.BaseServer のメソッド)
    • (telnetlib.Telnet のメソッド)
  • FileNotFoundError
  • fileobj (selectors.SelectorKey の属性)
  • FileSelectBox (tkinter.tix のクラス)
  • FileType (argparse のクラス)
  • FileWrapper (wsgiref.util のクラス)
  • fill() (textwrap モジュール)
    • (textwrap.TextWrapper のメソッド)
  • fillcolor() (turtle モジュール)
  • filling() (turtle モジュール)
  • filter (2to3 fixer)
  • Filter (logging のクラス)
  • filter (select.kevent の属性)
  • Filter (tracemalloc のクラス)
  • filter() (curses モジュール)
    • (fnmatch モジュール)
    • (logging.Filter のメソッド)
    • (logging.Handler のメソッド)
    • (logging.Logger のメソッド)
    • (組み込み関数)
  • FILTER_DIR (unittest.mock モジュール)
  • filter_traces() (tracemalloc.Snapshot のメソッド)
  • filterfalse() (itertools モジュール)
  • filterwarnings() (warnings モジュール)
  • finalization, of objects
  • finalize (weakref のクラス)
  • finalize_options() (distutils.cmd.Command のメソッド)
  • finalizer
  • finally
    • キーワード, [1], [2], [3], [4]
  • find() (bytearray のメソッド)
    • (bytes のメソッド)
    • (doctest.DocTestFinder のメソッド)
    • (gettext モジュール)
    • (mmap.mmap のメソッド)
    • (str のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • find_class() (pickle protocol)
    • (pickle.Unpickler のメソッド)
  • find_library() (ctypes.util モジュール)
  • find_library_file() (distutils.ccompiler.CCompiler のメソッド)
  • find_loader() (importlib モジュール)
    • (importlib.abc.PathEntryFinder のメソッド)
    • (importlib.machinery.FileFinder のメソッド)
    • (pkgutil モジュール)
  • find_longest_match() (difflib.SequenceMatcher のメソッド)
  • find_module() (imp モジュール)
    • (imp.NullImporter のメソッド)
    • (importlib.abc.Finder のメソッド)
    • (importlib.abc.MetaPathFinder のメソッド)
    • (importlib.abc.PathEntryFinder のメソッド)
    • (importlib.machinery.PathFinder のクラスメソッド)
    • (zipimport.zipimporter のメソッド)
  • find_msvcrt() (ctypes.util モジュール)
  • find_spec
    • finder
  • find_spec() (importlib.abc.MetaPathFinder のメソッド)
    • (importlib.abc.PathEntryFinder のメソッド)
    • (importlib.machinery.FileFinder のメソッド)
    • (importlib.machinery.PathFinder のクラスメソッド)
    • (importlib.util モジュール)
  • find_unused_port() (test.support モジュール)
  • find_user_password() (urllib.request.HTTPPasswordMgr のメソッド), [1]
  • findall() (re モジュール)
    • (re.Pattern のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • findCaller() (logging.Logger のメソッド)
  • finder, [1]
    • find_spec
  • Finder (importlib.abc のクラス)
  • findfactor() (audioop モジュール)
  • findfile() (test.support モジュール)
  • findfit() (audioop モジュール)
  • finditer() (re モジュール)
    • (re.Pattern のメソッド)
  • findlabels() (dis モジュール)
  • findlinestarts() (dis モジュール)
  • findmatch() (mailcap モジュール)
  • findmax() (audioop モジュール)
  • findtext() (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • finish() (socketserver.BaseRequestHandler のメソッド)
  • finish_request() (socketserver.BaseServer のメソッド)
  • firstChild (xml.dom.Node の属性)
  • firstkey() (dbm.gnu.gdbm のメソッド)
  • firstweekday() (calendar モジュール)
  • fix_missing_locations() (ast モジュール)
  • fix_sentence_endings (textwrap.TextWrapper の属性)
  • Flag (enum のクラス)
  • flag_bits (zipfile.ZipInfo の属性)
  • flags (re.Pattern の属性)
    • (select.kevent の属性)
    • (sys モジュール)
  • flash() (curses モジュール)
  • flatten() (email.generator.BytesGenerator のメソッド)
    • (email.generator.Generator のメソッド)
  • flattening
    • objects
  • float
    • 組み込み関数, [1], [2]
  • float (組み込みクラス)
  • float_info (sys モジュール)
  • float_repr_style (sys モジュール)
  • floating point
    • literals
    • number
    • オブジェクト, [1], [2]
  • floating point literal
  • FloatingPointError
  • FloatOperation (decimal のクラス)
  • flock() (fcntl モジュール)
  • floor division
  • floor() (in module math)
    • (math モジュール)
  • floordiv() (operator モジュール)
  • flush() (bz2.BZ2Compressor のメソッド)
    • (formatter.writer のメソッド)
    • (io.BufferedWriter のメソッド)
    • (io.IOBase のメソッド)
    • (logging.Handler のメソッド)
    • (logging.StreamHandler のメソッド)
    • (logging.handlers.BufferingHandler のメソッド)
    • (logging.handlers.MemoryHandler のメソッド)
    • (lzma.LZMACompressor のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (mmap.mmap のメソッド)
    • (zlib.Compress のメソッド)
    • (zlib.Decompress のメソッド)
  • flush_headers() (http.server.BaseHTTPRequestHandler のメソッド)
  • flush_softspace() (formatter.formatter のメソッド)
  • flushinp() (curses モジュール)
  • FlushKey() (winreg モジュール)
  • fma() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • fmod() (math モジュール)
  • FMT_BINARY (plistlib モジュール)
  • FMT_XML (plistlib モジュール)
  • fnmatch (モジュール)
  • fnmatch() (fnmatch モジュール)
  • fnmatchcase() (fnmatch モジュール)
  • focus() (tkinter.ttk.Treeview のメソッド)
  • fold (datetime.datetime の属性)
    • (datetime.time の属性)
  • fold() (email.headerregistry.BaseHeader のメソッド)
    • (email.policy.Compat32 のメソッド)
    • (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • fold_binary() (email.policy.Compat32 のメソッド)
    • (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • for
    • in comprehensions
    • 文, [1], [2], [3]
  • FOR_ITER (opcode)
  • forget() (test.support モジュール)
    • (tkinter.ttk.Notebook のメソッド)
  • fork() (os モジュール)
    • (pty モジュール)
  • ForkingMixIn (socketserver のクラス)
  • ForkingTCPServer (socketserver のクラス)
  • ForkingUDPServer (socketserver のクラス)
  • forkpty() (os モジュール)
  • form
    • lambda
  • Form (tkinter.tix のクラス)
  • format (memoryview の属性)
    • (struct.Struct の属性)
  • format() (built-in function)
    • __str__() (object method)
  • format() (locale モジュール)
    • (logging.Formatter のメソッド)
    • (logging.Handler のメソッド)
    • (pprint.PrettyPrinter のメソッド)
    • (str のメソッド)
    • (string.Formatter のメソッド)
    • (traceback.StackSummary のメソッド)
    • (traceback.TracebackException のメソッド)
    • (tracemalloc.Traceback のメソッド)
    • (組み込み関数)
  • format_datetime() (email.utils モジュール)
  • format_exc() (traceback モジュール)
  • format_exception() (traceback モジュール)
  • format_exception_only() (traceback モジュール)
    • (traceback.TracebackException のメソッド)
  • format_field() (string.Formatter のメソッド)
  • format_help() (argparse.ArgumentParser のメソッド)
  • format_list() (traceback モジュール)
  • format_map() (str のメソッド)
  • format_stack() (traceback モジュール)
  • format_stack_entry() (bdb.Bdb のメソッド)
  • format_string() (locale モジュール)
  • format_tb() (traceback モジュール)
  • format_usage() (argparse.ArgumentParser のメソッド)
  • FORMAT_VALUE (opcode)
  • formataddr() (email.utils モジュール)
  • formatargspec() (inspect モジュール)
  • formatargvalues() (inspect モジュール)
  • formatdate() (email.utils モジュール)
  • FormatError
  • FormatError() (ctypes モジュール)
  • formatException() (logging.Formatter のメソッド)
  • formatmonth() (calendar.HTMLCalendar のメソッド)
    • (calendar.TextCalendar のメソッド)
  • formatStack() (logging.Formatter のメソッド)
  • formatted string literal
  • Formatter (logging のクラス)
    • (string のクラス)
  • formatter (モジュール)
  • formatTime() (logging.Formatter のメソッド)
  • formatting
    • bytearray (%)
    • bytes (%)
  • formatting, string (%)
  • formatwarning() (warnings モジュール)
  • formatyear() (calendar.HTMLCalendar のメソッド)
    • (calendar.TextCalendar のメソッド)
  • formatyearpage() (calendar.HTMLCalendar のメソッド)
  • Fortran contiguous, [1]
  • forward() (turtle モジュール)
  • found_terminator() (asynchat.async_chat のメソッド)
  • fpathconf() (os モジュール)
  • fqdn (smtpd.SMTPChannel の属性)
  • Fraction (fractions のクラス)
  • fractions (モジュール)
  • frame
    • execution, [1]
    • オブジェクト
  • frame (tkinter.scrolledtext.ScrolledText の属性)
  • Frame (tracemalloc のクラス)
  • FrameSummary (traceback のクラス)
  • FrameType (types モジュール)
  • free
    • variable
  • free()
  • freeze utility
  • freeze() (gc モジュール)
  • freeze_support() (multiprocessing モジュール)
  • frexp() (math モジュール)
  • from
    • import statement, [1]
    • yield from expression
    • キーワード, [1]
  • from_address() (ctypes._CData のメソッド)
  • from_buffer() (ctypes._CData のメソッド)
  • from_buffer_copy() (ctypes._CData のメソッド)
  • from_bytes() (int のクラスメソッド)
  • from_callable() (inspect.Signature のクラスメソッド)
  • from_decimal() (fractions.Fraction のメソッド)
  • from_exception() (traceback.TracebackException のクラスメソッド)
  • from_file() (zipfile.ZipInfo のクラスメソッド)
  • from_float() (decimal.Decimal のメソッド)
    • (fractions.Fraction のメソッド)
  • from_iterable() (itertools.chain のクラスメソッド)
  • from_list() (traceback.StackSummary のクラスメソッド)
  • from_param() (ctypes._CData のメソッド)
  • from_traceback() (dis.Bytecode のクラスメソッド)
  • frombuf() (tarfile.TarInfo のクラスメソッド)
  • frombytes() (array.array のメソッド)
  • fromfd() (select.epoll のメソッド)
    • (select.kqueue のメソッド)
    • (socket モジュール)
  • fromfile() (array.array のメソッド)
  • fromhex() (bytearray のクラスメソッド)
    • (bytes のクラスメソッド)
    • (float のクラスメソッド)
  • fromisoformat() (datetime.date のクラスメソッド)
    • (datetime.datetime のクラスメソッド)
    • (datetime.time のクラスメソッド)
  • fromkeys() (collections.Counter のメソッド)
    • (dict のクラスメソッド)
  • fromlist() (array.array のメソッド)
  • fromordinal() (datetime.date のクラスメソッド)
    • (datetime.datetime のクラスメソッド)
  • fromshare() (socket モジュール)
  • fromstring() (array.array のメソッド)
    • (xml.etree.ElementTree モジュール)
  • fromstringlist() (xml.etree.ElementTree モジュール)
  • fromtarfile() (tarfile.TarInfo のクラスメソッド)
  • fromtimestamp() (datetime.date のクラスメソッド)
    • (datetime.datetime のクラスメソッド)
  • fromunicode() (array.array のメソッド)
  • fromutc() (datetime.timezone のメソッド)
    • (datetime.tzinfo のメソッド)
  • FrozenImporter (importlib.machinery のクラス)
  • FrozenInstanceError
  • frozenset
    • オブジェクト, [1]
  • FrozenSet (typing のクラス)
  • frozenset (組み込みクラス)
  • fs_is_case_insensitive() (test.support モジュール)
  • FS_NONASCII (test.support モジュール)
  • fsdecode() (os モジュール)
  • fsencode() (os モジュール)
  • fspath() (os モジュール)
  • fstat() (os モジュール)
  • fstatvfs() (os モジュール)
  • fsum() (math モジュール)
  • fsync() (os モジュール)
  • FTP
    • ftplib (standard module)
    • protocol, [1]
  • FTP (ftplib のクラス)
  • ftp_open() (urllib.request.FTPHandler のメソッド)
  • FTP_TLS (ftplib のクラス)
  • FTPHandler (urllib.request のクラス)
  • ftplib (モジュール)
  • ftruncate() (os モジュール)
  • Full
  • full() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (queue.Queue のメソッド)
  • full_url (urllib.request.Request の属性)
  • fullmatch() (re モジュール)
    • (re.Pattern のメソッド)
  • func (functools.partial の属性)
  • funcattrs (2to3 fixer)
  • function
    • annotations, [1]
    • anonymous
    • argument
    • call, [1], [2]
    • call, user-defined
    • definition, [1]
    • generator, [1]
    • name, [1]
    • user-defined
    • オブジェクト, [1], [2], [3], [4], [5]
  • Function (symtable のクラス)
  • function annotation
  • function__entry (C の関数)
  • function__return (C の関数)
  • FunctionTestCase (unittest のクラス)
  • FunctionType (types モジュール)
  • functools (モジュール)
  • funny_files (filecmp.dircmp の属性)
  • future
    • statement
  • future (2to3 fixer)
  • Future (asyncio のクラス)
    • (concurrent.futures のクラス)
  • FutureWarning
  • fwalk() (os モジュール)

G

  • G.722
  • gaierror
  • gamma() (math モジュール)
  • gammavariate() (random モジュール)
  • garbage (gc モジュール)
  • garbage collection, [1]
  • gather() (curses.textpad.Textbox のメソッド)
  • gauss() (random モジュール)
  • gc (モジュール)
  • gc__done (C の関数)
  • gc__start (C の関数)
  • gc_collect() (test.support モジュール)
  • gcd() (fractions モジュール)
    • (math モジュール)
  • ge() (operator モジュール)
  • gen_lib_options() (distutils.ccompiler モジュール)
  • gen_preprocess_options() (distutils.ccompiler モジュール)
  • gen_uuid() (msilib モジュール)
  • generate_help() (distutils.fancy_getopt.FancyGetopt のメソッド)
  • generator, [1]
    • expression
    • function, [1], [2]
    • iterator, [1]
    • オブジェクト, [1], [2]
  • Generator (collections.abc のクラス)
    • (email.generator のクラス)
    • (typing のクラス)
  • generator expression, [1]
  • generator iterator
  • GeneratorExit
    • 例外, [1]
  • GeneratorType (types モジュール)
  • generic
    • special attribute
  • Generic (typing のクラス)
  • generic function
  • generic_visit() (ast.NodeVisitor のメソッド)
  • genops() (pickletools モジュール)
  • get() (asyncio.Queue のメソッド)
    • (configparser.ConfigParser のメソッド)
    • (contextvars.Context のメソッド)
    • (contextvars.ContextVar のメソッド)
    • (dict のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (multiprocessing.SimpleQueue のメソッド)
    • (multiprocessing.pool.AsyncResult のメソッド)
    • (ossaudiodev.oss_mixer_device のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
    • (tkinter.ttk.Combobox のメソッド)
    • (tkinter.ttk.Spinbox のメソッド)
    • (types.MappingProxyType のメソッド)
    • (webbrowser モジュール)
    • (xml.etree.ElementTree.Element のメソッド)
  • GET_AITER (opcode)
  • get_all() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (wsgiref.headers.Headers のメソッド)
  • get_all_breaks() (bdb.Bdb のメソッド)
  • get_all_start_methods() (multiprocessing モジュール)
  • GET_ANEXT (opcode)
  • get_app() (wsgiref.simple_server.WSGIServer のメソッド)
  • get_archive_formats() (shutil モジュール)
  • get_asyncgen_hooks() (sys モジュール)
  • get_attribute() (test.support モジュール)
  • GET_AWAITABLE (opcode)
  • get_begidx() (readline モジュール)
  • get_blocking() (os モジュール)
  • get_body() (email.message.EmailMessage のメソッド)
  • get_body_encoding() (email.charset.Charset のメソッド)
  • get_boundary() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_bpbynumber() (bdb.Bdb のメソッド)
  • get_break() (bdb.Bdb のメソッド)
  • get_breaks() (bdb.Bdb のメソッド)
  • get_buffer() (asyncio.BufferedProtocol のメソッド)
    • (xdrlib.Packer のメソッド)
    • (xdrlib.Unpacker のメソッド)
  • get_bytes() (mailbox.Mailbox のメソッド)
  • get_ca_certs() (ssl.SSLContext のメソッド)
  • get_cache_token() (abc モジュール)
  • get_channel_binding() (ssl.SSLSocket のメソッド)
  • get_charset() (email.message.Message のメソッド)
  • get_charsets() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_child_watcher() (asyncio モジュール)
    • (asyncio.AbstractEventLoopPolicy のメソッド)
  • get_children() (symtable.SymbolTable のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
  • get_ciphers() (ssl.SSLContext のメソッド)
  • get_clock_info() (time モジュール)
  • get_close_matches() (difflib モジュール)
  • get_code() (importlib.abc.InspectLoader のメソッド)
    • (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
    • (importlib.machinery.SourcelessFileLoader のメソッド)
    • (zipimport.zipimporter のメソッド)
  • get_completer() (readline モジュール)
  • get_completer_delims() (readline モジュール)
  • get_completion_type() (readline モジュール)
  • get_config_h_filename() (distutils.sysconfig モジュール)
    • (sysconfig モジュール)
  • get_config_var() (distutils.sysconfig モジュール)
    • (sysconfig モジュール)
  • get_config_vars() (distutils.sysconfig モジュール)
    • (sysconfig モジュール)
  • get_content() (email.contentmanager モジュール)
    • (email.contentmanager.ContentManager のメソッド)
    • (email.message.EmailMessage のメソッド)
  • get_content_charset() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_content_disposition() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_content_maintype() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_content_subtype() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_content_type() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_context() (multiprocessing モジュール)
  • get_coroutine_origin_tracking_depth() (sys モジュール)
  • get_coroutine_wrapper() (sys モジュール)
  • get_count() (gc モジュール)
  • get_current_history_length() (readline モジュール)
  • get_data() (importlib.abc.FileLoader のメソッド)
    • (importlib.abc.ResourceLoader のメソッド)
    • (pkgutil モジュール)
    • (zipimport.zipimporter のメソッド)
  • get_date() (mailbox.MaildirMessage のメソッド)
  • get_debug() (asyncio.loop のメソッド)
    • (gc モジュール)
  • get_default() (argparse.ArgumentParser のメソッド)
  • get_default_compiler() (distutils.ccompiler モジュール)
  • get_default_domain() (nis モジュール)
  • get_default_type() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_default_verify_paths() (ssl モジュール)
  • get_dialect() (csv モジュール)
  • get_docstring() (ast モジュール)
  • get_doctest() (doctest.DocTestParser のメソッド)
  • get_endidx() (readline モジュール)
  • get_environ() (wsgiref.simple_server.WSGIRequestHandler のメソッド)
  • get_errno() (ctypes モジュール)
  • get_event_loop() (asyncio モジュール)
    • (asyncio.AbstractEventLoopPolicy のメソッド)
  • get_event_loop_policy() (asyncio モジュール)
  • get_examples() (doctest.DocTestParser のメソッド)
  • get_exception_handler() (asyncio.loop のメソッド)
  • get_exec_path() (os モジュール)
  • get_extra_info() (asyncio.BaseTransport のメソッド)
    • (asyncio.StreamWriter のメソッド)
  • get_field() (string.Formatter のメソッド)
  • get_file() (mailbox.Babyl のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.MMDF のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (mailbox.mbox のメソッド)
  • get_file_breaks() (bdb.Bdb のメソッド)
  • get_filename() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (importlib.abc.ExecutionLoader のメソッド)
    • (importlib.abc.FileLoader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
    • (zipimport.zipimporter のメソッド)
  • get_flags() (mailbox.MaildirMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
    • (mailbox.mboxMessage のメソッド)
  • get_folder() (mailbox.Maildir のメソッド)
    • (mailbox.MH のメソッド)
  • get_frees() (symtable.Function のメソッド)
  • get_freeze_count() (gc モジュール)
  • get_from() (mailbox.mboxMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
  • get_full_url() (urllib.request.Request のメソッド)
  • get_globals() (symtable.Function のメソッド)
  • get_grouped_opcodes() (difflib.SequenceMatcher のメソッド)
  • get_handle_inheritable() (os モジュール)
  • get_header() (urllib.request.Request のメソッド)
  • get_history_item() (readline モジュール)
  • get_history_length() (readline モジュール)
  • get_id() (symtable.SymbolTable のメソッド)
  • get_ident() (_thread モジュール)
    • (threading モジュール)
  • get_identifiers() (symtable.SymbolTable のメソッド)
  • get_importer() (pkgutil モジュール)
  • get_info() (mailbox.MaildirMessage のメソッド)
  • get_inheritable() (os モジュール)
    • (socket.socket のメソッド)
  • get_instructions() (dis モジュール)
  • get_interpreter() (zipapp モジュール)
  • GET_ITER (opcode)
  • get_key() (selectors.BaseSelector のメソッド)
  • get_labels() (mailbox.Babyl のメソッド)
    • (mailbox.BabylMessage のメソッド)
  • get_last_error() (ctypes モジュール)
  • get_line_buffer() (readline モジュール)
  • get_lineno() (symtable.SymbolTable のメソッド)
  • get_loader() (pkgutil モジュール)
  • get_locals() (symtable.Function のメソッド)
  • get_logger() (multiprocessing モジュール)
  • get_loop() (asyncio.Future のメソッド)
    • (asyncio.Server のメソッド)
  • get_magic() (imp モジュール)
  • get_makefile_filename() (distutils.sysconfig モジュール)
    • (sysconfig モジュール)
  • get_map() (selectors.BaseSelector のメソッド)
  • get_matching_blocks() (difflib.SequenceMatcher のメソッド)
  • get_message() (mailbox.Mailbox のメソッド)
  • get_method() (urllib.request.Request のメソッド)
  • get_methods() (symtable.Class のメソッド)
  • get_mixed_type_key() (ipaddress モジュール)
  • get_name() (symtable.Symbol のメソッド)
    • (symtable.SymbolTable のメソッド)
  • get_namespace() (symtable.Symbol のメソッド)
  • get_namespaces() (symtable.Symbol のメソッド)
  • get_nonstandard_attr() (http.cookiejar.Cookie のメソッド)
  • get_nowait() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
  • get_object_traceback() (tracemalloc モジュール)
  • get_objects() (gc モジュール)
  • get_opcodes() (difflib.SequenceMatcher のメソッド)
  • get_option() (optparse.OptionParser のメソッド)
  • get_option_group() (optparse.OptionParser のメソッド)
  • get_option_order() (distutils.fancy_getopt.FancyGetopt のメソッド)
  • get_original_stdout() (test.support モジュール)
  • get_osfhandle() (msvcrt モジュール)
  • get_output_charset() (email.charset.Charset のメソッド)
  • get_param() (email.message.Message のメソッド)
  • get_parameters() (symtable.Function のメソッド)
  • get_params() (email.message.Message のメソッド)
  • get_path() (sysconfig モジュール)
  • get_path_names() (sysconfig モジュール)
  • get_paths() (sysconfig モジュール)
  • get_payload() (email.message.Message のメソッド)
  • get_pid() (asyncio.SubprocessTransport のメソッド)
  • get_pipe_transport() (asyncio.SubprocessTransport のメソッド)
  • get_platform() (distutils.util モジュール)
    • (sysconfig モジュール)
  • get_poly() (turtle モジュール)
  • get_position() (xdrlib.Unpacker のメソッド)
  • get_protocol() (asyncio.BaseTransport のメソッド)
  • get_python_inc() (distutils.sysconfig モジュール)
  • get_python_lib() (distutils.sysconfig モジュール)
  • get_python_version() (sysconfig モジュール)
  • get_recsrc() (ossaudiodev.oss_mixer_device のメソッド)
  • get_referents() (gc モジュール)
  • get_referrers() (gc モジュール)
  • get_request() (socketserver.BaseServer のメソッド)
  • get_returncode() (asyncio.SubprocessTransport のメソッド)
  • get_running_loop() (asyncio モジュール)
  • get_scheme() (wsgiref.handlers.BaseHandler のメソッド)
  • get_scheme_names() (sysconfig モジュール)
  • get_sequences() (mailbox.MH のメソッド)
    • (mailbox.MHMessage のメソッド)
  • get_server() (multiprocessing.managers.BaseManager のメソッド)
  • get_server_certificate() (ssl モジュール)
  • get_shapepoly() (turtle モジュール)
  • get_socket() (telnetlib.Telnet のメソッド)
  • get_source() (importlib.abc.InspectLoader のメソッド)
    • (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
    • (importlib.machinery.SourcelessFileLoader のメソッド)
    • (zipimport.zipimporter のメソッド)
  • get_special_folder_path() (組み込み関数)
  • get_stack() (asyncio.Task のメソッド)
    • (bdb.Bdb のメソッド)
  • get_start_method() (multiprocessing モジュール)
  • get_starttag_text() (html.parser.HTMLParser のメソッド)
  • get_stats() (gc モジュール)
  • get_stderr() (wsgiref.handlers.BaseHandler のメソッド)
    • (wsgiref.simple_server.WSGIRequestHandler のメソッド)
  • get_stdin() (wsgiref.handlers.BaseHandler のメソッド)
  • get_string() (mailbox.Mailbox のメソッド)
  • get_subdir() (mailbox.MaildirMessage のメソッド)
  • get_suffixes() (imp モジュール)
  • get_symbols() (symtable.SymbolTable のメソッド)
  • get_tag() (imp モジュール)
  • get_task_factory() (asyncio.loop のメソッド)
  • get_terminal_size() (os モジュール)
    • (shutil モジュール)
  • get_terminator() (asynchat.async_chat のメソッド)
  • get_threshold() (gc モジュール)
  • get_token() (shlex.shlex のメソッド)
  • get_traceback_limit() (tracemalloc モジュール)
  • get_traced_memory() (tracemalloc モジュール)
  • get_tracemalloc_memory() (tracemalloc モジュール)
  • get_type() (symtable.SymbolTable のメソッド)
  • get_type_hints() (typing モジュール)
  • get_unixfrom() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_unpack_formats() (shutil モジュール)
  • get_usage() (optparse.OptionParser のメソッド)
  • get_value() (string.Formatter のメソッド)
  • get_version() (optparse.OptionParser のメソッド)
  • get_visible() (mailbox.BabylMessage のメソッド)
  • get_wch() (curses.window のメソッド)
  • get_write_buffer_limits() (asyncio.WriteTransport のメソッド)
  • get_write_buffer_size() (asyncio.WriteTransport のメソッド)
  • GET_YIELD_FROM_ITER (opcode)
  • getacl() (imaplib.IMAP4 のメソッド)
  • getaddresses() (email.utils モジュール)
  • getaddrinfo() (asyncio.loop のメソッド)
    • (socket モジュール)
  • getallocatedblocks() (sys モジュール)
  • getandroidapilevel() (sys モジュール)
  • getannotation() (imaplib.IMAP4 のメソッド)
  • getargspec() (inspect モジュール)
  • getargvalues() (inspect モジュール)
  • getatime() (os.path モジュール)
  • getattr() (組み込み関数)
  • getattr_static() (inspect モジュール)
  • getAttribute() (xml.dom.Element のメソッド)
  • getAttributeNode() (xml.dom.Element のメソッド)
  • getAttributeNodeNS() (xml.dom.Element のメソッド)
  • getAttributeNS() (xml.dom.Element のメソッド)
  • GetBase() (xml.parsers.expat.xmlparser のメソッド)
  • getbegyx() (curses.window のメソッド)
  • getbkgd() (curses.window のメソッド)
  • getblocking() (socket.socket のメソッド)
  • getboolean() (configparser.ConfigParser のメソッド)
  • getbuffer() (io.BytesIO のメソッド)
  • getByteStream() (xml.sax.xmlreader.InputSource のメソッド)
  • getcallargs() (inspect モジュール)
  • getcanvas() (turtle モジュール)
  • getcapabilities() (nntplib.NNTP のメソッド)
  • getcaps() (mailcap モジュール)
  • getch() (curses.window のメソッド)
    • (msvcrt モジュール)
  • getCharacterStream() (xml.sax.xmlreader.InputSource のメソッド)
  • getche() (msvcrt モジュール)
  • getcheckinterval() (sys モジュール)
  • getChild() (logging.Logger のメソッド)
  • getchildren() (xml.etree.ElementTree.Element のメソッド)
  • getclasstree() (inspect モジュール)
  • getclosurevars() (inspect モジュール)
  • GetColumnInfo() (msilib.View のメソッド)
  • getColumnNumber() (xml.sax.xmlreader.Locator のメソッド)
  • getcomments() (inspect モジュール)
  • getcompname() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getcomptype() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getContentHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • getcontext() (decimal モジュール)
  • getcoroutinelocals() (inspect モジュール)
  • getcoroutinestate() (inspect モジュール)
  • getctime() (os.path モジュール)
  • getcwd() (os モジュール)
  • getcwdb() (os モジュール)
  • getcwdu (2to3 fixer)
  • getdecoder() (codecs モジュール)
  • getdefaultencoding() (sys モジュール)
  • getdefaultlocale() (locale モジュール)
  • getdefaulttimeout() (socket モジュール)
  • getdlopenflags() (sys モジュール)
  • getdoc() (inspect モジュール)
  • getDOMImplementation() (xml.dom モジュール)
  • getDTDHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • getEffectiveLevel() (logging.Logger のメソッド)
  • getegid() (os モジュール)
  • getElementsByTagName() (xml.dom.Document のメソッド)
    • (xml.dom.Element のメソッド)
  • getElementsByTagNameNS() (xml.dom.Document のメソッド)
    • (xml.dom.Element のメソッド)
  • getencoder() (codecs モジュール)
  • getEncoding() (xml.sax.xmlreader.InputSource のメソッド)
  • getEntityResolver() (xml.sax.xmlreader.XMLReader のメソッド)
  • getenv() (os モジュール)
  • getenvb() (os モジュール)
  • getErrorHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • geteuid() (os モジュール)
  • getEvent() (xml.dom.pulldom.DOMEventStream のメソッド)
  • getEventCategory() (logging.handlers.NTEventLogHandler のメソッド)
  • getEventType() (logging.handlers.NTEventLogHandler のメソッド)
  • getException() (xml.sax.SAXException のメソッド)
  • getFeature() (xml.sax.xmlreader.XMLReader のメソッド)
  • GetFieldCount() (msilib.Record のメソッド)
  • getfile() (inspect モジュール)
  • getfilesystemencodeerrors() (sys モジュール)
  • getfilesystemencoding() (sys モジュール)
  • getfirst() (cgi.FieldStorage のメソッド)
  • getfloat() (configparser.ConfigParser のメソッド)
  • getfmts() (ossaudiodev.oss_audio_device のメソッド)
  • getfqdn() (socket モジュール)
  • getframeinfo() (inspect モジュール)
  • getframerate() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getfullargspec() (inspect モジュール)
  • getgeneratorlocals() (inspect モジュール)
  • getgeneratorstate() (inspect モジュール)
  • getgid() (os モジュール)
  • getgrall() (grp モジュール)
  • getgrgid() (grp モジュール)
  • getgrnam() (grp モジュール)
  • getgrouplist() (os モジュール)
  • getgroups() (os モジュール)
  • getheader() (http.client.HTTPResponse のメソッド)
  • getheaders() (http.client.HTTPResponse のメソッド)
  • gethostbyaddr() (in module socket)
    • (socket モジュール)
  • gethostbyname() (socket モジュール)
  • gethostbyname_ex() (socket モジュール)
  • gethostname() (in module socket)
    • (socket モジュール)
  • getincrementaldecoder() (codecs モジュール)
  • getincrementalencoder() (codecs モジュール)
  • getinfo() (zipfile.ZipFile のメソッド)
  • getinnerframes() (inspect モジュール)
  • GetInputContext() (xml.parsers.expat.xmlparser のメソッド)
  • getint() (configparser.ConfigParser のメソッド)
  • GetInteger() (msilib.Record のメソッド)
  • getitem() (operator モジュール)
  • getiterator() (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • getitimer() (signal モジュール)
  • getkey() (curses.window のメソッド)
  • GetLastError() (ctypes モジュール)
  • getLength() (xml.sax.xmlreader.Attributes のメソッド)
  • getLevelName() (logging モジュール)
  • getline() (linecache モジュール)
  • getLineNumber() (xml.sax.xmlreader.Locator のメソッド)
  • getlist() (cgi.FieldStorage のメソッド)
  • getloadavg() (os モジュール)
  • getlocale() (locale モジュール)
  • getLogger() (logging モジュール)
  • getLoggerClass() (logging モジュール)
  • getlogin() (os モジュール)
  • getLogRecordFactory() (logging モジュール)
  • getmark() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getmarkers() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getmaxyx() (curses.window のメソッド)
  • getmember() (tarfile.TarFile のメソッド)
  • getmembers() (inspect モジュール)
    • (tarfile.TarFile のメソッド)
  • getMessage() (logging.LogRecord のメソッド)
    • (xml.sax.SAXException のメソッド)
  • getMessageID() (logging.handlers.NTEventLogHandler のメソッド)
  • getmodule() (inspect モジュール)
  • getmodulename() (inspect モジュール)
  • getmouse() (curses モジュール)
  • getmro() (inspect モジュール)
  • getmtime() (os.path モジュール)
  • getname() (chunk.Chunk のメソッド)
  • getName() (threading.Thread のメソッド)
  • getNameByQName() (xml.sax.xmlreader.AttributesNS のメソッド)
  • getnameinfo() (asyncio.loop のメソッド)
    • (socket モジュール)
  • getnames() (tarfile.TarFile のメソッド)
  • getNames() (xml.sax.xmlreader.Attributes のメソッド)
  • getnchannels() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getnframes() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getnode
  • getnode() (uuid モジュール)
  • getopt (モジュール)
  • getopt() (distutils.fancy_getopt.FancyGetopt のメソッド)
    • (getopt モジュール)
  • GetoptError
  • getouterframes() (inspect モジュール)
  • getoutput() (subprocess モジュール)
  • getpagesize() (resource モジュール)
  • getparams() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getparyx() (curses.window のメソッド)
  • getpass (モジュール)
  • getpass() (getpass モジュール)
  • GetPassWarning
  • getpeercert() (ssl.SSLSocket のメソッド)
  • getpeername() (socket.socket のメソッド)
  • getpen() (turtle モジュール)
  • getpgid() (os モジュール)
  • getpgrp() (os モジュール)
  • getpid() (os モジュール)
  • getpos() (html.parser.HTMLParser のメソッド)
  • getppid() (os モジュール)
  • getpreferredencoding() (locale モジュール)
  • getpriority() (os モジュール)
  • getprofile() (sys モジュール)
  • GetProperty() (msilib.SummaryInformation のメソッド)
  • getProperty() (xml.sax.xmlreader.XMLReader のメソッド)
  • GetPropertyCount() (msilib.SummaryInformation のメソッド)
  • getprotobyname() (socket モジュール)
  • getproxies() (urllib.request モジュール)
  • getPublicId() (xml.sax.xmlreader.InputSource のメソッド)
    • (xml.sax.xmlreader.Locator のメソッド)
  • getpwall() (pwd モジュール)
  • getpwnam() (pwd モジュール)
  • getpwuid() (pwd モジュール)
  • getQNameByName() (xml.sax.xmlreader.AttributesNS のメソッド)
  • getQNames() (xml.sax.xmlreader.AttributesNS のメソッド)
  • getquota() (imaplib.IMAP4 のメソッド)
  • getquotaroot() (imaplib.IMAP4 のメソッド)
  • getrandbits() (random モジュール)
  • getrandom() (os モジュール)
  • getreader() (codecs モジュール)
  • getrecursionlimit() (sys モジュール)
  • getrefcount() (sys モジュール)
  • getresgid() (os モジュール)
  • getresponse() (http.client.HTTPConnection のメソッド)
  • getresuid() (os モジュール)
  • getrlimit() (resource モジュール)
  • getroot() (xml.etree.ElementTree.ElementTree のメソッド)
  • getrusage() (resource モジュール)
  • getsample() (audioop モジュール)
  • getsampwidth() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getscreen() (turtle モジュール)
  • getservbyname() (socket モジュール)
  • getservbyport() (socket モジュール)
  • GetSetDescriptorType (types モジュール)
  • getshapes() (turtle モジュール)
  • getsid() (os モジュール)
  • getsignal() (signal モジュール)
  • getsitepackages() (site モジュール)
  • getsize() (chunk.Chunk のメソッド)
    • (os.path モジュール)
  • getsizeof() (sys モジュール)
  • getsockname() (socket.socket のメソッド)
  • getsockopt() (socket.socket のメソッド)
  • getsource() (inspect モジュール)
  • getsourcefile() (inspect モジュール)
  • getsourcelines() (inspect モジュール)
  • getspall() (spwd モジュール)
  • getspnam() (spwd モジュール)
  • getstate() (codecs.IncrementalDecoder のメソッド)
    • (codecs.IncrementalEncoder のメソッド)
    • (random モジュール)
  • getstatusoutput() (subprocess モジュール)
  • getstr() (curses.window のメソッド)
  • GetString() (msilib.Record のメソッド)
  • getSubject() (logging.handlers.SMTPHandler のメソッド)
  • GetSummaryInformation() (msilib.Database のメソッド)
  • getswitchinterval() (sys モジュール)
  • getSystemId() (xml.sax.xmlreader.InputSource のメソッド)
    • (xml.sax.xmlreader.Locator のメソッド)
  • getsyx() (curses モジュール)
  • gettarinfo() (tarfile.TarFile のメソッド)
  • gettempdir() (tempfile モジュール)
  • gettempdirb() (tempfile モジュール)
  • gettempprefix() (tempfile モジュール)
  • gettempprefixb() (tempfile モジュール)
  • getTestCaseNames() (unittest.TestLoader のメソッド)
  • gettext (モジュール)
  • gettext() (gettext モジュール)
    • (gettext.GNUTranslations のメソッド)
    • (gettext.NullTranslations のメソッド)
    • (locale モジュール)
  • gettimeout() (socket.socket のメソッド)
  • gettrace() (sys モジュール)
  • getturtle() (turtle モジュール)
  • getType() (xml.sax.xmlreader.Attributes のメソッド)
  • getuid() (os モジュール)
  • geturl() (urllib.parse.urllib.parse.SplitResult のメソッド)
  • getuser() (getpass モジュール)
  • getuserbase() (site モジュール)
  • getusersitepackages() (site モジュール)
  • getvalue() (io.BytesIO のメソッド)
    • (io.StringIO のメソッド)
  • getValue() (xml.sax.xmlreader.Attributes のメソッド)
  • getValueByQName() (xml.sax.xmlreader.AttributesNS のメソッド)
  • getwch() (msvcrt モジュール)
  • getwche() (msvcrt モジュール)
  • getweakrefcount() (weakref モジュール)
  • getweakrefs() (weakref モジュール)
  • getwelcome() (ftplib.FTP のメソッド)
    • (nntplib.NNTP のメソッド)
    • (poplib.POP3 のメソッド)
  • getwin() (curses モジュール)
  • getwindowsversion() (sys モジュール)
  • getwriter() (codecs モジュール)
  • getxattr() (os モジュール)
  • getyx() (curses.window のメソッド)
  • gid (tarfile.TarInfo の属性)
  • GIL
  • glob
    • モジュール
  • glob (モジュール)
  • glob() (glob モジュール)
    • (msilib.Directory のメソッド)
    • (pathlib.Path のメソッド)
  • global
    • name binding
    • namespace
    • 文, [1]
  • global interpreter lock, [1]
  • globals() (組み込み関数)
  • globs (doctest.DocTest の属性)
  • gmtime() (time モジュール)
  • gname (tarfile.TarInfo の属性)
  • GNOME
  • GNU_FORMAT (tarfile モジュール)
  • gnu_getopt() (getopt モジュール)
  • GNUTranslations (gettext のクラス)
  • got (doctest.DocTestFailure の属性)
  • goto() (turtle モジュール)
  • grammar
  • Graphical User Interface
  • GREATER (token モジュール)
  • GREATEREQUAL (token モジュール)
  • Greenwich Mean Time
  • GRND_NONBLOCK (os モジュール)
  • GRND_RANDOM (os モジュール)
  • Group (email.headerregistry のクラス)
  • group() (nntplib.NNTP のメソッド)
    • (pathlib.Path のメソッド)
    • (re.Match のメソッド)
  • groupby() (itertools モジュール)
  • groupdict() (re.Match のメソッド)
  • groupindex (re.Pattern の属性)
  • grouping
  • groups (email.headerregistry.AddressHeader の属性)
    • (re.Pattern の属性)
  • groups() (re.Match のメソッド)
  • grp (モジュール)
  • gt() (operator モジュール)
  • guess_all_extensions() (mimetypes モジュール)
    • (mimetypes.MimeTypes のメソッド)
  • guess_extension() (mimetypes モジュール)
    • (mimetypes.MimeTypes のメソッド)
  • guess_scheme() (wsgiref.util モジュール)
  • guess_type() (mimetypes モジュール)
    • (mimetypes.MimeTypes のメソッド)
  • GUI
  • gzip (モジュール)
  • GzipFile (gzip のクラス)

H

  • halfdelay() (curses モジュール)
  • Handle (asyncio のクラス)
  • handle an exception
  • handle() (http.server.BaseHTTPRequestHandler のメソッド)
    • (logging.Handler のメソッド)
    • (logging.Logger のメソッド)
    • (logging.NullHandler のメソッド)
    • (logging.handlers.QueueListener のメソッド)
    • (socketserver.BaseRequestHandler のメソッド)
    • (wsgiref.simple_server.WSGIRequestHandler のメソッド)
  • handle_accept() (asyncore.dispatcher のメソッド)
  • handle_accepted() (asyncore.dispatcher のメソッド)
  • handle_charref() (html.parser.HTMLParser のメソッド)
  • handle_close() (asyncore.dispatcher のメソッド)
  • handle_comment() (html.parser.HTMLParser のメソッド)
  • handle_connect() (asyncore.dispatcher のメソッド)
  • handle_data() (html.parser.HTMLParser のメソッド)
  • handle_decl() (html.parser.HTMLParser のメソッド)
  • handle_defect() (email.policy.Policy のメソッド)
  • handle_endtag() (html.parser.HTMLParser のメソッド)
  • handle_entityref() (html.parser.HTMLParser のメソッド)
  • handle_error() (asyncore.dispatcher のメソッド)
    • (socketserver.BaseServer のメソッド)
  • handle_expect_100() (http.server.BaseHTTPRequestHandler のメソッド)
  • handle_expt() (asyncore.dispatcher のメソッド)
  • handle_one_request() (http.server.BaseHTTPRequestHandler のメソッド)
  • handle_pi() (html.parser.HTMLParser のメソッド)
  • handle_read() (asyncore.dispatcher のメソッド)
  • handle_request() (socketserver.BaseServer のメソッド)
    • (xmlrpc.server.CGIXMLRPCRequestHandler のメソッド)
  • handle_startendtag() (html.parser.HTMLParser のメソッド)
  • handle_starttag() (html.parser.HTMLParser のメソッド)
  • handle_timeout() (socketserver.BaseServer のメソッド)
  • handle_write() (asyncore.dispatcher のメソッド)
  • handleError() (logging.Handler のメソッド)
    • (logging.handlers.SocketHandler のメソッド)
  • handler
    • exception
  • Handler (logging のクラス)
  • handler() (cgitb モジュール)
  • harmonic_mean() (statistics モジュール)
  • HAS_ALPN (ssl モジュール)
  • has_children() (symtable.SymbolTable のメソッド)
  • has_colors() (curses モジュール)
  • HAS_ECDH (ssl モジュール)
  • has_exec() (symtable.SymbolTable のメソッド)
  • has_extn() (smtplib.SMTP のメソッド)
  • has_function() (distutils.ccompiler.CCompiler のメソッド)
  • has_header() (csv.Sniffer のメソッド)
    • (urllib.request.Request のメソッド)
  • has_ic() (curses モジュール)
  • has_il() (curses モジュール)
  • has_ipv6 (socket モジュール)
  • has_key (2to3 fixer)
  • has_key() (curses モジュール)
  • has_location (importlib.machinery.ModuleSpec の属性)
  • HAS_NEVER_CHECK_COMMON_NAME (ssl モジュール)
  • has_nonstandard_attr() (http.cookiejar.Cookie のメソッド)
  • HAS_NPN (ssl モジュール)
  • has_option() (configparser.ConfigParser のメソッド)
    • (optparse.OptionParser のメソッド)
  • has_section() (configparser.ConfigParser のメソッド)
  • HAS_SNI (ssl モジュール)
  • HAS_SSLv2 (ssl モジュール)
  • HAS_SSLv3 (ssl モジュール)
  • has_ticket (ssl.SSLSession の属性)
  • HAS_TLSv1 (ssl モジュール)
  • HAS_TLSv1_1 (ssl モジュール)
  • HAS_TLSv1_2 (ssl モジュール)
  • HAS_TLSv1_3 (ssl モジュール)
  • hasattr() (組み込み関数)
  • hasAttribute() (xml.dom.Element のメソッド)
  • hasAttributeNS() (xml.dom.Element のメソッド)
  • hasAttributes() (xml.dom.Node のメソッド)
  • hasChildNodes() (xml.dom.Node のメソッド)
  • hascompare (dis モジュール)
  • hasconst (dis モジュール)
  • hasFeature() (xml.dom.DOMImplementation のメソッド)
  • hasfree (dis モジュール)
  • hash
    • 組み込み関数, [1], [2], [3]
  • hash character
  • hash() (組み込み関数)
  • hash-based pyc
  • hash.block_size (hashlib モジュール)
  • hash.digest_size (hashlib モジュール)
  • hash_info (sys モジュール)
  • hashable, [1]
  • Hashable (collections.abc のクラス)
    • (typing のクラス)
  • hasHandlers() (logging.Logger のメソッド)
  • hashlib (モジュール)
  • hasjabs (dis モジュール)
  • hasjrel (dis モジュール)
  • haslocal (dis モジュール)
  • hasname (dis モジュール)
  • HAVE_ARGUMENT (opcode)
  • HAVE_DOCSTRINGS (test.support モジュール)
  • HAVE_THREADS (decimal モジュール)
  • HCI_DATA_DIR (socket モジュール)
  • HCI_FILTER (socket モジュール)
  • HCI_TIME_STAMP (socket モジュール)
  • head() (nntplib.NNTP のメソッド)
  • Header (email.header のクラス)
  • header_encode() (email.charset.Charset のメソッド)
  • header_encode_lines() (email.charset.Charset のメソッド)
  • header_encoding (email.charset.Charset の属性)
  • header_factory (email.policy.EmailPolicy の属性)
  • header_fetch_parse() (email.policy.Compat32 のメソッド)
    • (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • header_items() (urllib.request.Request のメソッド)
  • header_max_count() (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • header_offset (zipfile.ZipInfo の属性)
  • header_source_parse() (email.policy.Compat32 のメソッド)
    • (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • header_store_parse() (email.policy.Compat32 のメソッド)
    • (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • HeaderError
  • HeaderParseError
  • HeaderParser (email.parser のクラス)
  • HeaderRegistry (email.headerregistry のクラス)
  • headers
    • MIME, [1]
  • headers (http.server.BaseHTTPRequestHandler の属性)
    • (urllib.error.HTTPError の属性)
  • Headers (wsgiref.headers のクラス)
  • headers (xmlrpc.client.ProtocolError の属性)
  • heading() (tkinter.ttk.Treeview のメソッド)
    • (turtle モジュール)
  • heapify() (heapq モジュール)
  • heapmin() (msvcrt モジュール)
  • heappop() (heapq モジュール)
  • heappush() (heapq モジュール)
  • heappushpop() (heapq モジュール)
  • heapq (モジュール)
  • heapreplace() (heapq モジュール)
  • helo() (smtplib.SMTP のメソッド)
  • help
    • online
    • 組み込み関数
  • help (optparse.Option の属性)
    • (pdb command)
  • help() (nntplib.NNTP のメソッド)
    • (組み込み関数)
  • herror
  • hex (uuid.UUID の属性)
  • hex() (bytearray のメソッド)
    • (bytes のメソッド)
    • (float のメソッド)
    • (memoryview のメソッド)
    • (組み込み関数)
  • hexadecimal
    • literals
  • hexadecimal literal
  • hexbin() (binhex モジュール)
  • hexdigest() (hashlib.hash のメソッド)
    • (hashlib.shake のメソッド)
    • (hmac.HMAC のメソッド)
  • hexdigits (string モジュール)
  • hexlify() (binascii モジュール)
  • hexversion (sys モジュール)
  • hidden() (curses.panel.Panel のメソッド)
  • hide() (curses.panel.Panel のメソッド)
    • (tkinter.ttk.Notebook のメソッド)
  • hide_cookie2 (http.cookiejar.CookiePolicy の属性)
  • hideturtle() (turtle モジュール)
  • hierarchy
    • type
  • HierarchyRequestErr
  • HIGH_PRIORITY_CLASS (subprocess モジュール)
  • HIGHEST_PROTOCOL (pickle モジュール)
  • HKEY_CLASSES_ROOT (winreg モジュール)
  • HKEY_CURRENT_CONFIG (winreg モジュール)
  • HKEY_CURRENT_USER (winreg モジュール)
  • HKEY_DYN_DATA (winreg モジュール)
  • HKEY_LOCAL_MACHINE (winreg モジュール)
  • HKEY_PERFORMANCE_DATA (winreg モジュール)
  • HKEY_USERS (winreg モジュール)
  • hline() (curses.window のメソッド)
  • HList (tkinter.tix のクラス)
  • hls_to_rgb() (colorsys モジュール)
  • hmac (モジュール)
  • HOME, [1], [2], [3], [4]
  • home() (pathlib.Path のクラスメソッド)
    • (turtle モジュール)
  • HOMEDRIVE, [1]
  • HOMEPATH, [1]
  • hook_compressed() (fileinput モジュール)
  • hook_encoded() (fileinput モジュール)
  • hooks
    • import
    • meta
    • path
  • host (urllib.request.Request の属性)
  • hostmask (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • hostname_checks_common_name (ssl.SSLContext の属性)
  • hosts (netrc.netrc の属性)
  • hosts() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • hour (datetime.datetime の属性)
    • (datetime.time の属性)
  • HRESULT (ctypes のクラス)
  • hStdError (subprocess.STARTUPINFO の属性)
  • hStdInput (subprocess.STARTUPINFO の属性)
  • hStdOutput (subprocess.STARTUPINFO の属性)
  • hsv_to_rgb() (colorsys モジュール)
  • ht() (turtle モジュール)
  • HTML, [1]
  • html (モジュール)
  • html() (cgitb モジュール)
  • html.entities (モジュール)
  • html.parser (モジュール)
  • html5 (html.entities モジュール)
  • HTMLCalendar (calendar のクラス)
  • HtmlDiff (difflib のクラス)
  • HTMLParser (html.parser のクラス)
  • htonl() (socket モジュール)
  • htons() (socket モジュール)
  • HTTP
    • http (standard module)
    • http.client (standard module)
    • protocol, [1], [2], [3], [4], [5]
  • HTTP (email.policy モジュール)
  • http (モジュール)
  • http.client (モジュール)
  • http.cookiejar (モジュール)
  • http.cookies (モジュール)
  • http.server (モジュール)
  • http_error_301() (urllib.request.HTTPRedirectHandler のメソッド)
  • http_error_302() (urllib.request.HTTPRedirectHandler のメソッド)
  • http_error_303() (urllib.request.HTTPRedirectHandler のメソッド)
  • http_error_307() (urllib.request.HTTPRedirectHandler のメソッド)
  • http_error_401() (urllib.request.HTTPBasicAuthHandler のメソッド)
    • (urllib.request.HTTPDigestAuthHandler のメソッド)
  • http_error_407() (urllib.request.ProxyBasicAuthHandler のメソッド)
    • (urllib.request.ProxyDigestAuthHandler のメソッド)
  • http_error_auth_reqed() (urllib.request.AbstractBasicAuthHandler のメソッド)
    • (urllib.request.AbstractDigestAuthHandler のメソッド)
  • http_error_default() (urllib.request.BaseHandler のメソッド)
  • http_error_nnn() (urllib.request.BaseHandler のメソッド)
  • http_open() (urllib.request.HTTPHandler のメソッド)
  • HTTP_PORT (http.client モジュール)
  • http_proxy, [1], [2]
  • http_response() (urllib.request.HTTPErrorProcessor のメソッド)
  • http_version (wsgiref.handlers.BaseHandler の属性)
  • HTTPBasicAuthHandler (urllib.request のクラス)
  • HTTPConnection (http.client のクラス)
  • HTTPCookieProcessor (urllib.request のクラス)
  • httpd
  • HTTPDefaultErrorHandler (urllib.request のクラス)
  • HTTPDigestAuthHandler (urllib.request のクラス)
  • HTTPError
  • HTTPErrorProcessor (urllib.request のクラス)
  • HTTPException
  • HTTPHandler (logging.handlers のクラス)
    • (urllib.request のクラス)
  • HTTPPasswordMgr (urllib.request のクラス)
  • HTTPPasswordMgrWithDefaultRealm (urllib.request のクラス)
  • HTTPPasswordMgrWithPriorAuth (urllib.request のクラス)
  • HTTPRedirectHandler (urllib.request のクラス)
  • HTTPResponse (http.client のクラス)
  • https_open() (urllib.request.HTTPSHandler のメソッド)
  • HTTPS_PORT (http.client モジュール)
  • https_response() (urllib.request.HTTPErrorProcessor のメソッド)
  • HTTPSConnection (http.client のクラス)
  • HTTPServer (http.server のクラス)
  • HTTPSHandler (urllib.request のクラス)
  • HTTPStatus (http のクラス)
  • hypot() (math モジュール)

I

  • I (re モジュール)
  • I/O control
    • POSIX
    • UNIX
    • buffering, [1]
    • tty
  • iadd() (operator モジュール)
  • iand() (operator モジュール)
  • iconcat() (operator モジュール)
  • id
    • 組み込み関数
  • id (ssl.SSLSession の属性)
  • id() (unittest.TestCase のメソッド)
    • (組み込み関数)
  • idcok() (curses.window のメソッド)
  • ident (select.kevent の属性)
    • (threading.Thread の属性)
  • identchars (cmd.Cmd の属性)
  • identifier, [1]
  • identify() (tkinter.ttk.Notebook のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
    • (tkinter.ttk.Widget のメソッド)
  • identify_column() (tkinter.ttk.Treeview のメソッド)
  • identify_element() (tkinter.ttk.Treeview のメソッド)
  • identify_region() (tkinter.ttk.Treeview のメソッド)
  • identify_row() (tkinter.ttk.Treeview のメソッド)
  • identity
    • test
  • identity of an object
  • idioms (2to3 fixer)
  • IDLE, [1]
  • IDLE_PRIORITY_CLASS (subprocess モジュール)
  • IDLESTARTUP, [1], [2]
  • idlok() (curses.window のメソッド)
  • if
    • conditional expression
    • in comprehensions
    • 文, [1]
  • if_indextoname() (socket モジュール)
  • if_nameindex() (socket モジュール)
  • if_nametoindex() (socket モジュール)
  • ifloordiv() (operator モジュール)
  • iglob() (glob モジュール)
  • ignorableWhitespace() (xml.sax.handler.ContentHandler のメソッド)
  • ignore (pdb command)
  • ignore_errors() (codecs モジュール)
  • IGNORE_EXCEPTION_DETAIL (doctest モジュール)
  • ignore_patterns() (shutil モジュール)
  • IGNORECASE (re モジュール)
  • ihave() (nntplib.NNTP のメソッド)
  • IISCGIHandler (wsgiref.handlers のクラス)
  • ilshift() (operator モジュール)
  • imag (numbers.Complex の属性)
  • imaginary literal
  • imap() (multiprocessing.pool.Pool のメソッド)
  • IMAP4
    • protocol
  • IMAP4 (imaplib のクラス)
  • IMAP4.abort
  • IMAP4.error
  • IMAP4.readonly
  • IMAP4_SSL
    • protocol
  • IMAP4_SSL (imaplib のクラス)
  • IMAP4_stream
    • protocol
  • IMAP4_stream (imaplib のクラス)
  • imap_unordered() (multiprocessing.pool.Pool のメソッド)
  • imaplib (モジュール)
  • imatmul() (operator モジュール)
  • imghdr (モジュール)
  • immedok() (curses.window のメソッド)
  • immutable
    • data type
    • object, [1]
    • sequence types
    • オブジェクト
  • immutable object
  • immutable sequence
    • オブジェクト
  • immutable types
    • subclassing
  • imod() (operator モジュール)
  • imp
    • モジュール
  • imp (モジュール)
  • ImpImporter (pkgutil のクラス)
  • impl_detail() (test.support モジュール)
  • implementation (sys モジュール)
  • ImpLoader (pkgutil のクラス)
  • import
    • hooks
    • 文, [1], [2], [3], [4]
  • import (2to3 fixer)
  • import hooks
  • import machinery
  • import path
  • import__find__load__done (C の関数)
  • import__find__load__start (C の関数)
  • import_fresh_module() (test.support モジュール)
  • IMPORT_FROM (opcode)
  • import_module() (importlib モジュール)
    • (test.support モジュール)
  • IMPORT_NAME (opcode)
  • IMPORT_STAR (opcode)
  • importer
  • ImportError
    • 例外
  • importing
  • importlib (モジュール)
  • importlib.abc (モジュール)
  • importlib.machinery (モジュール)
  • importlib.resources (モジュール)
  • importlib.util (モジュール)
  • imports (2to3 fixer)
  • imports2 (2to3 fixer)
  • ImportWarning
  • ImproperConnectionState
  • imul() (operator モジュール)
  • in
    • キーワード, [1]
    • 演算子, [1], [2]
  • in_dll() (ctypes._CData のメソッド)
  • in_table_a1() (stringprep モジュール)
  • in_table_b1() (stringprep モジュール)
  • in_table_c11() (stringprep モジュール)
  • in_table_c11_c12() (stringprep モジュール)
  • in_table_c12() (stringprep モジュール)
  • in_table_c21() (stringprep モジュール)
  • in_table_c21_c22() (stringprep モジュール)
  • in_table_c22() (stringprep モジュール)
  • in_table_c3() (stringprep モジュール)
  • in_table_c4() (stringprep モジュール)
  • in_table_c5() (stringprep モジュール)
  • in_table_c6() (stringprep モジュール)
  • in_table_c7() (stringprep モジュール)
  • in_table_c8() (stringprep モジュール)
  • in_table_c9() (stringprep モジュール)
  • in_table_d1() (stringprep モジュール)
  • in_table_d2() (stringprep モジュール)
  • in_transaction (sqlite3.Connection の属性)
  • inch() (curses.window のメソッド)
  • inclusive
    • or
  • inclusive (tracemalloc.DomainFilter の属性)
    • (tracemalloc.Filter の属性)
  • Incomplete
  • IncompleteRead
  • IncompleteReadError
  • incr_item(), [1]
  • increment_lineno() (ast モジュール)
  • IncrementalDecoder (codecs のクラス)
  • incrementaldecoder (codecs.CodecInfo の属性)
  • IncrementalEncoder (codecs のクラス)
  • incrementalencoder (codecs.CodecInfo の属性)
  • IncrementalNewlineDecoder (io のクラス)
  • IncrementalParser (xml.sax.xmlreader のクラス)
  • indent (doctest.Example の属性)
  • INDENT (token モジュール)
  • INDENT token
  • indent() (textwrap モジュール)
  • indentation
  • IndentationError
  • index operation
  • index() (array.array のメソッド)
    • (bytearray のメソッド)
    • (bytes のメソッド)
    • (collections.deque のメソッド)
    • (operator モジュール)
    • (sequence method)
    • (str のメソッド)
    • (tkinter.ttk.Notebook のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
  • IndexError
  • indexOf() (operator モジュール)
  • IndexSizeErr
  • indices() (slice のメソッド)
  • inet_aton() (socket モジュール)
  • inet_ntoa() (socket モジュール)
  • inet_ntop() (socket モジュール)
  • inet_pton() (socket モジュール)
  • Inexact (decimal のクラス)
  • inf (cmath モジュール)
    • (math モジュール)
  • infile
    • json.tool コマンドラインオプション
  • infile (shlex.shlex の属性)
  • Infinity
  • infj (cmath モジュール)
  • info() (dis.Bytecode のメソッド)
    • (gettext.NullTranslations のメソッド)
    • (logging モジュール)
    • (logging.Logger のメソッド)
  • infolist() (zipfile.ZipFile のメソッド)
  • inheritance
  • ini file
  • init() (mimetypes モジュール)
  • init_color() (curses モジュール)
  • init_database() (msilib モジュール)
  • init_pair() (curses モジュール)
  • inited (mimetypes モジュール)
  • initgroups() (os モジュール)
  • initial_indent (textwrap.TextWrapper の属性)
  • initialize_options() (distutils.cmd.Command のメソッド)
  • initscr() (curses モジュール)
  • inode() (os.DirEntry のメソッド)
  • INPLACE_ADD (opcode)
  • INPLACE_AND (opcode)
  • INPLACE_FLOOR_DIVIDE (opcode)
  • INPLACE_LSHIFT (opcode)
  • INPLACE_MATRIX_MULTIPLY (opcode)
  • INPLACE_MODULO (opcode)
  • INPLACE_MULTIPLY (opcode)
  • INPLACE_OR (opcode)
  • INPLACE_POWER (opcode)
  • INPLACE_RSHIFT (opcode)
  • INPLACE_SUBTRACT (opcode)
  • INPLACE_TRUE_DIVIDE (opcode)
  • INPLACE_XOR (opcode)
  • input
    • (2to3 fixer)
  • input() (fileinput モジュール)
    • (組み込み関数)
  • input_charset (email.charset.Charset の属性)
  • input_codec (email.charset.Charset の属性)
  • InputOnly (tkinter.tix のクラス)
  • InputSource (xml.sax.xmlreader のクラス)
  • inquiry (C のデータ型)
  • insch() (curses.window のメソッド)
  • insdelln() (curses.window のメソッド)
  • insert() (array.array のメソッド)
    • (collections.deque のメソッド)
    • (sequence method)
    • (tkinter.ttk.Notebook のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
  • insert_text() (readline モジュール)
  • insertBefore() (xml.dom.Node のメソッド)
  • insertln() (curses.window のメソッド)
  • insnstr() (curses.window のメソッド)
  • insort() (bisect モジュール)
  • insort_left() (bisect モジュール)
  • insort_right() (bisect モジュール)
  • inspect (モジュール)
  • inspect コマンドラインオプション
    • --details
  • InspectLoader (importlib.abc のクラス)
  • insstr() (curses.window のメソッド)
  • install() (gettext モジュール)
    • (gettext.NullTranslations のメソッド)
  • install_opener() (urllib.request モジュール)
  • install_scripts() (venv.EnvBuilder のメソッド)
  • installHandler() (unittest モジュール)
  • instance
    • call, [1]
    • class
    • オブジェクト, [1], [2]
  • instancemethod
    • オブジェクト
  • instate() (tkinter.ttk.Widget のメソッド)
  • instr() (curses.window のメソッド)
  • instream (shlex.shlex の属性)
  • Instruction (dis のクラス)
  • Instruction.arg (dis モジュール)
  • Instruction.argrepr (dis モジュール)
  • Instruction.argval (dis モジュール)
  • Instruction.is_jump_target (dis モジュール)
  • Instruction.offset (dis モジュール)
  • Instruction.opcode (dis モジュール)
  • Instruction.opname (dis モジュール)
  • Instruction.starts_line (dis モジュール)
  • int
    • 組み込み関数, [1], [2]
  • int (uuid.UUID の属性)
    • (組み込みクラス)
  • Int2AP() (imaplib モジュール)
  • int_info (sys モジュール)
  • integer
    • literals
    • representation
    • types, operations on
    • オブジェクト, [1], [2]
  • integer literal
  • Integral (numbers のクラス)
  • Integrated Development Environment
  • IntegrityError
  • Intel/DVI ADPCM
  • IntEnum (enum のクラス)
  • interact (pdb command)
  • interact() (code モジュール)
    • (code.InteractiveConsole のメソッド)
    • (telnetlib.Telnet のメソッド)
  • interactive
  • interactive mode
  • InteractiveConsole (code のクラス)
  • InteractiveInterpreter (code のクラス)
  • intern (2to3 fixer)
  • intern() (sys モジュール)
  • internal type
  • internal_attr (zipfile.ZipInfo の属性)
  • Internaldate2tuple() (imaplib モジュール)
  • internalSubset (xml.dom.DocumentType の属性)
  • Internet
  • interpolated string literal
  • interpolation
    • bytearray (%)
    • bytes (%)
  • interpolation, string (%)
  • InterpolationDepthError
  • InterpolationError
  • InterpolationMissingOptionError
  • InterpolationSyntaxError
  • interpreted
  • interpreter
  • interpreter lock
  • interpreter prompts
  • interpreter shutdown
  • interpreter_requires_environment() (test.support.script_helper モジュール)
  • interrupt() (sqlite3.Connection のメソッド)
  • interrupt_main() (_thread モジュール)
  • InterruptedError
  • intersection() (frozenset のメソッド)
  • intersection_update() (frozenset のメソッド)
  • IntFlag (enum のクラス)
  • intro (cmd.Cmd の属性)
  • InuseAttributeErr
  • inv() (operator モジュール)
  • InvalidAccessErr
  • invalidate_caches() (importlib モジュール)
    • (importlib.abc.MetaPathFinder のメソッド)
    • (importlib.abc.PathEntryFinder のメソッド)
    • (importlib.machinery.FileFinder のメソッド)
    • (importlib.machinery.PathFinder のクラスメソッド)
  • InvalidCharacterErr
  • InvalidModificationErr
  • InvalidOperation (decimal のクラス)
  • InvalidStateErr
  • InvalidStateError
  • InvalidURL
  • inversion
  • invert() (operator モジュール)
  • invocation
  • io
    • モジュール
  • IO (typing のクラス)
  • io (モジュール)
  • io.StringIO
    • オブジェクト
  • IOBase (io のクラス)
  • ioctl() (fcntl モジュール)
    • (socket.socket のメソッド)
  • IOCTL_VM_SOCKETS_GET_LOCAL_CID (socket モジュール)
  • IOError
  • ior() (operator モジュール)
  • ip (ipaddress.IPv4Interface の属性)
    • (ipaddress.IPv6Interface の属性)
  • ip_address() (ipaddress モジュール)
  • ip_interface() (ipaddress モジュール)
  • ip_network() (ipaddress モジュール)
  • ipaddress (モジュール)
  • ipow() (operator モジュール)
  • ipv4_mapped (ipaddress.IPv6Address の属性)
  • IPv4Address (ipaddress のクラス)
  • IPv4Interface (ipaddress のクラス)
  • IPv4Network (ipaddress のクラス)
  • IPV6_ENABLED (test.support モジュール)
  • IPv6Address (ipaddress のクラス)
  • IPv6Interface (ipaddress のクラス)
  • IPv6Network (ipaddress のクラス)
  • irshift() (operator モジュール)
  • is
    • 演算子, [1]
  • is not
    • 演算子, [1]
  • is_() (operator モジュール)
  • is_absolute() (pathlib.PurePath のメソッド)
  • is_alive() (multiprocessing.Process のメソッド)
    • (threading.Thread のメソッド)
  • is_android (test.support モジュール)
  • is_assigned() (symtable.Symbol のメソッド)
  • is_attachment() (email.message.EmailMessage のメソッド)
  • is_authenticated() (urllib.request.HTTPPasswordMgrWithPriorAuth のメソッド)
  • is_block_device() (pathlib.Path のメソッド)
  • is_blocked() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • is_canonical() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_char_device() (pathlib.Path のメソッド)
  • IS_CHARACTER_JUNK() (difflib モジュール)
  • is_check_supported() (lzma モジュール)
  • is_closed() (asyncio.loop のメソッド)
  • is_closing() (asyncio.BaseTransport のメソッド)
    • (asyncio.StreamWriter のメソッド)
  • is_dataclass() (dataclasses モジュール)
  • is_declared_global() (symtable.Symbol のメソッド)
  • is_dir() (os.DirEntry のメソッド)
    • (pathlib.Path のメソッド)
    • (zipfile.ZipInfo のメソッド)
  • is_enabled() (faulthandler モジュール)
  • is_expired() (http.cookiejar.Cookie のメソッド)
  • is_fifo() (pathlib.Path のメソッド)
  • is_file() (os.DirEntry のメソッド)
    • (pathlib.Path のメソッド)
  • is_finalizing() (sys モジュール)
  • is_finite() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_free() (symtable.Symbol のメソッド)
  • is_global (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv6Address の属性)
  • is_global() (symtable.Symbol のメソッド)
  • is_hop_by_hop() (wsgiref.util モジュール)
  • is_imported() (symtable.Symbol のメソッド)
  • is_infinite() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_integer() (float のメソッド)
  • is_jython (test.support モジュール)
  • IS_LINE_JUNK() (difflib モジュール)
  • is_linetouched() (curses.window のメソッド)
  • is_link_local (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_local() (symtable.Symbol のメソッド)
  • is_loopback (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_mount() (pathlib.Path のメソッド)
  • is_multicast (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_multipart() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • is_namespace() (symtable.Symbol のメソッド)
  • is_nan() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_nested() (symtable.SymbolTable のメソッド)
  • is_normal() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_not() (operator モジュール)
  • is_not_allowed() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • is_optimized() (symtable.SymbolTable のメソッド)
  • is_package() (importlib.abc.InspectLoader のメソッド)
    • (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
    • (importlib.machinery.SourceFileLoader のメソッド)
    • (importlib.machinery.SourcelessFileLoader のメソッド)
    • (zipimport.zipimporter のメソッド)
  • is_parameter() (symtable.Symbol のメソッド)
  • is_private (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_python_build() (sysconfig モジュール)
  • is_qnan() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_reading() (asyncio.ReadTransport のメソッド)
  • is_referenced() (symtable.Symbol のメソッド)
  • is_reserved (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_reserved() (pathlib.PurePath のメソッド)
  • is_resource() (importlib.abc.ResourceReader のメソッド)
    • (importlib.resources モジュール)
  • is_resource_enabled() (test.support モジュール)
  • is_running() (asyncio.loop のメソッド)
  • is_safe (uuid.UUID の属性)
  • is_serving() (asyncio.Server のメソッド)
  • is_set() (asyncio.Event のメソッド)
    • (threading.Event のメソッド)
  • is_signed() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_site_local (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_snan() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_socket() (pathlib.Path のメソッド)
  • is_subnormal() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_symlink() (os.DirEntry のメソッド)
    • (pathlib.Path のメソッド)
  • is_tarfile() (tarfile モジュール)
  • is_term_resized() (curses モジュール)
  • is_tracing() (tracemalloc モジュール)
  • is_tracked() (gc モジュール)
  • is_unspecified (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_wintouched() (curses.window のメソッド)
  • is_zero() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_zipfile() (zipfile モジュール)
  • isabs() (os.path モジュール)
  • isabstract() (inspect モジュール)
  • IsADirectoryError
  • isalnum() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isalpha() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isascii() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isasyncgen() (inspect モジュール)
  • isasyncgenfunction() (inspect モジュール)
  • isatty() (chunk.Chunk のメソッド)
    • (io.IOBase のメソッド)
    • (os モジュール)
  • isawaitable() (inspect モジュール)
  • isblank() (curses.ascii モジュール)
  • isblk() (tarfile.TarInfo のメソッド)
  • isbuiltin() (inspect モジュール)
  • ischr() (tarfile.TarInfo のメソッド)
  • isclass() (inspect モジュール)
  • isclose() (cmath モジュール)
    • (math モジュール)
  • iscntrl() (curses.ascii モジュール)
  • iscode() (inspect モジュール)
  • iscoroutine() (asyncio モジュール)
    • (inspect モジュール)
  • iscoroutinefunction() (asyncio モジュール)
    • (inspect モジュール)
  • isctrl() (curses.ascii モジュール)
  • isDaemon() (threading.Thread のメソッド)
  • isdatadescriptor() (inspect モジュール)
  • isdecimal() (str のメソッド)
  • isdev() (tarfile.TarInfo のメソッド)
  • isdigit() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isdir() (os.path モジュール)
    • (tarfile.TarInfo のメソッド)
  • isdisjoint() (frozenset のメソッド)
  • isdown() (turtle モジュール)
  • iselement() (xml.etree.ElementTree モジュール)
  • isenabled() (gc モジュール)
  • isEnabledFor() (logging.Logger のメソッド)
  • isendwin() (curses モジュール)
  • ISEOF() (token モジュール)
  • isexpr() (parser モジュール)
    • (parser.ST のメソッド)
  • isfifo() (tarfile.TarInfo のメソッド)
  • isfile() (os.path モジュール)
    • (tarfile.TarInfo のメソッド)
  • isfinite() (cmath モジュール)
    • (math モジュール)
  • isfirstline() (fileinput モジュール)
  • isframe() (inspect モジュール)
  • isfunction() (inspect モジュール)
  • isfuture() (asyncio モジュール)
  • isgenerator() (inspect モジュール)
  • isgeneratorfunction() (inspect モジュール)
  • isgetsetdescriptor() (inspect モジュール)
  • isgraph() (curses.ascii モジュール)
  • isidentifier() (str のメソッド)
  • isinf() (cmath モジュール)
    • (math モジュール)
  • isinstance (2to3 fixer)
  • isinstance() (組み込み関数)
  • iskeyword() (keyword モジュール)
  • isleap() (calendar モジュール)
  • islice() (itertools モジュール)
  • islink() (os.path モジュール)
  • islnk() (tarfile.TarInfo のメソッド)
  • islower() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • ismemberdescriptor() (inspect モジュール)
  • ismeta() (curses.ascii モジュール)
  • ismethod() (inspect モジュール)
  • ismethoddescriptor() (inspect モジュール)
  • ismodule() (inspect モジュール)
  • ismount() (os.path モジュール)
  • isnan() (cmath モジュール)
    • (math モジュール)
  • ISNONTERMINAL() (token モジュール)
  • isnumeric() (str のメソッド)
  • isocalendar() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
  • isoformat() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
  • isolation_level (sqlite3.Connection の属性)
  • isoweekday() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
  • isprint() (curses.ascii モジュール)
  • isprintable() (str のメソッド)
  • ispunct() (curses.ascii モジュール)
  • isreadable() (pprint モジュール)
    • (pprint.PrettyPrinter のメソッド)
  • isrecursive() (pprint モジュール)
    • (pprint.PrettyPrinter のメソッド)
  • isreg() (tarfile.TarInfo のメソッド)
  • isReservedKey() (http.cookies.Morsel のメソッド)
  • isroutine() (inspect モジュール)
  • isSameNode() (xml.dom.Node のメソッド)
  • isspace() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isstdin() (fileinput モジュール)
  • issubclass() (組み込み関数)
  • issubset() (frozenset のメソッド)
  • issuite() (parser モジュール)
    • (parser.ST のメソッド)
  • issuperset() (frozenset のメソッド)
  • issym() (tarfile.TarInfo のメソッド)
  • ISTERMINAL() (token モジュール)
  • istitle() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • istraceback() (inspect モジュール)
  • isub() (operator モジュール)
  • isupper() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isvisible() (turtle モジュール)
  • isxdigit() (curses.ascii モジュール)
  • item
    • sequence
    • string
  • item selection
  • item() (tkinter.ttk.Treeview のメソッド)
    • (xml.dom.NamedNodeMap のメソッド)
    • (xml.dom.NodeList のメソッド)
  • itemgetter() (operator モジュール)
  • items() (configparser.ConfigParser のメソッド)
    • (contextvars.Context のメソッド)
    • (dict のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (types.MappingProxyType のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
  • itemsize (array.array の属性)
    • (memoryview の属性)
  • ItemsView (collections.abc のクラス)
    • (typing のクラス)
  • iter() (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
    • (組み込み関数)
  • iter_attachments() (email.message.EmailMessage のメソッド)
  • iter_child_nodes() (ast モジュール)
  • iter_fields() (ast モジュール)
  • iter_importers() (pkgutil モジュール)
  • iter_modules() (pkgutil モジュール)
  • iter_parts() (email.message.EmailMessage のメソッド)
  • iter_unpack() (struct モジュール)
    • (struct.Struct のメソッド)
  • iterable
    • unpacking
  • Iterable (collections.abc のクラス)
    • (typing のクラス)
  • iterator
  • Iterator (collections.abc のクラス)
    • (typing のクラス)
  • iterator protocol
  • iterdecode() (codecs モジュール)
  • iterdir() (pathlib.Path のメソッド)
  • iterdump() (sqlite3.Connection のメソッド)
  • iterencode() (codecs モジュール)
    • (json.JSONEncoder のメソッド)
  • iterfind() (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • iteritems() (mailbox.Mailbox のメソッド)
  • iterkeys() (mailbox.Mailbox のメソッド)
  • itermonthdates() (calendar.Calendar のメソッド)
  • itermonthdays() (calendar.Calendar のメソッド)
  • itermonthdays2() (calendar.Calendar のメソッド)
  • itermonthdays3() (calendar.Calendar のメソッド)
  • itermonthdays4() (calendar.Calendar のメソッド)
  • iterparse() (xml.etree.ElementTree モジュール)
  • itertext() (xml.etree.ElementTree.Element のメソッド)
  • itertools (2to3 fixer)
    • (モジュール)
  • itertools_imports (2to3 fixer)
  • itervalues() (mailbox.Mailbox のメソッド)
  • iterweekdays() (calendar.Calendar のメソッド)
  • ITIMER_PROF (signal モジュール)
  • ITIMER_REAL (signal モジュール)
  • ITIMER_VIRTUAL (signal モジュール)
  • ItimerError
  • itruediv() (operator モジュール)
  • ixor() (operator モジュール)

J

  • j
    • in numeric literal
  • Jansen, Jack
  • Java
    • language
  • java_ver() (platform モジュール)
  • join() (asyncio.Queue のメソッド)
    • (bytearray のメソッド)
    • (bytes のメソッド)
    • (multiprocessing.JoinableQueue のメソッド)
    • (multiprocessing.Process のメソッド)
    • (multiprocessing.pool.Pool のメソッド)
    • (os.path モジュール)
    • (queue.Queue のメソッド)
    • (str のメソッド)
    • (threading.Thread のメソッド)
  • join_thread() (multiprocessing.Queue のメソッド)
    • (test.support モジュール)
  • JoinableQueue (multiprocessing のクラス)
  • joinpath() (pathlib.PurePath のメソッド)
  • js_output() (http.cookies.BaseCookie のメソッド)
    • (http.cookies.Morsel のメソッド)
  • json
    • モジュール
  • json (モジュール)
  • json.tool (モジュール)
  • json.tool コマンドラインオプション
    • --sort-keys
    • -h, --help
    • infile
    • outfile
  • JSONDecodeError
  • JSONDecoder (json のクラス)
  • JSONEncoder (json のクラス)
  • jump (pdb command)
  • JUMP_ABSOLUTE (opcode)
  • JUMP_FORWARD (opcode)
  • JUMP_IF_FALSE_OR_POP (opcode)
  • JUMP_IF_TRUE_OR_POP (opcode)

K

  • kbhit() (msvcrt モジュール)
  • KDEDIR
  • kevent() (select モジュール)
  • key
    • (http.cookies.Morsel の属性)
  • key function
  • key/datum pair
  • KEY_ALL_ACCESS (winreg モジュール)
  • KEY_CREATE_LINK (winreg モジュール)
  • KEY_CREATE_SUB_KEY (winreg モジュール)
  • KEY_ENUMERATE_SUB_KEYS (winreg モジュール)
  • KEY_EXECUTE (winreg モジュール)
  • KEY_NOTIFY (winreg モジュール)
  • KEY_QUERY_VALUE (winreg モジュール)
  • KEY_READ (winreg モジュール)
  • KEY_SET_VALUE (winreg モジュール)
  • KEY_WOW64_32KEY (winreg モジュール)
  • KEY_WOW64_64KEY (winreg モジュール)
  • KEY_WRITE (winreg モジュール)
  • KeyboardInterrupt
    • (built-in exception), [1]
  • KeyError
  • keyname() (curses モジュール)
  • keypad() (curses.window のメソッド)
  • keyrefs() (weakref.WeakKeyDictionary のメソッド)
  • keys() (contextvars.Context のメソッド)
    • (dict のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (sqlite3.Row のメソッド)
    • (types.MappingProxyType のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
  • KeysView (collections.abc のクラス)
    • (typing のクラス)
  • keyword
    • (モジュール)
  • keyword argument
  • keywords (functools.partial の属性)
  • kill() (asyncio.asyncio.subprocess.Process のメソッド)
    • (asyncio.SubprocessTransport のメソッド)
    • (multiprocessing.Process のメソッド)
    • (os モジュール)
    • (subprocess.Popen のメソッド)
  • kill_python() (test.support.script_helper モジュール)
  • killchar() (curses モジュール)
  • killpg() (os モジュール)
  • kind (inspect.Parameter の属性)
  • knownfiles (mimetypes モジュール)
  • kqueue() (select モジュール)
  • KqueueSelector (selectors のクラス)
  • kwargs (inspect.BoundArguments の属性)
  • kwlist (keyword モジュール)

L

  • L (re モジュール)
  • LabelEntry (tkinter.tix のクラス)
  • LabelFrame (tkinter.tix のクラス)
  • lambda
    • expression, [1]
    • form
  • LambdaType (types モジュール)
  • LANG, [1], [2], [3], [4]
  • LANGUAGE, [1]
  • language
    • C, [1], [2], [3], [4], [5]
    • Java
  • large files
  • LargeZipFile
  • last() (nntplib.NNTP のメソッド)
  • last_accepted (multiprocessing.connection.Listener の属性)
  • last_traceback (in module sys)
    • (sys モジュール)
  • last_type (sys モジュール)
  • last_value (sys モジュール)
  • lastChild (xml.dom.Node の属性)
  • lastcmd (cmd.Cmd の属性)
  • lastgroup (re.Match の属性)
  • lastindex (re.Match の属性)
  • lastResort (logging モジュール)
  • lastrowid (sqlite3.Cursor の属性)
  • layout() (tkinter.ttk.Style のメソッド)
  • lazycache() (linecache モジュール)
  • LazyLoader (importlib.util のクラス)
  • LBRACE (token モジュール)
  • LBYL
  • LC_ALL, [1]
    • (locale モジュール)
  • LC_COLLATE (locale モジュール)
  • LC_CTYPE (locale モジュール)
  • LC_MESSAGES, [1]
    • (locale モジュール)
  • LC_MONETARY (locale モジュール)
  • LC_NUMERIC (locale モジュール)
  • LC_TIME (locale モジュール)
  • lchflags() (os モジュール)
  • lchmod() (os モジュール)
    • (pathlib.Path のメソッド)
  • lchown() (os モジュール)
  • LDCXXSHARED
  • ldexp() (math モジュール)
  • LDFLAGS
  • ldgettext() (gettext モジュール)
  • ldngettext() (gettext モジュール)
  • le() (operator モジュール)
  • leading whitespace
  • leapdays() (calendar モジュール)
  • leaveok() (curses.window のメソッド)
  • left (filecmp.dircmp の属性)
  • left() (turtle モジュール)
  • left_list (filecmp.dircmp の属性)
  • left_only (filecmp.dircmp の属性)
  • LEFTSHIFT (token モジュール)
  • LEFTSHIFTEQUAL (token モジュール)
  • len
    • 組み込み関数, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]
  • len() (組み込み関数)
  • length (xml.dom.NamedNodeMap の属性)
    • (xml.dom.NodeList の属性)
  • length_hint() (operator モジュール)
  • LESS (token モジュール)
  • LESSEQUAL (token モジュール)
  • lexical analysis
  • lexical definitions
  • lexists() (os.path モジュール)
  • lgamma() (math モジュール)
  • lgettext() (gettext モジュール)
    • (gettext.GNUTranslations のメソッド)
    • (gettext.NullTranslations のメソッド)
  • lib2to3 (モジュール)
  • libc_ver() (platform モジュール)
  • library (dbm.ndbm モジュール)
    • (ssl.SSLError の属性)
  • library_dir_option() (distutils.ccompiler.CCompiler のメソッド)
  • library_filename() (distutils.ccompiler.CCompiler のメソッド)
  • library_option() (distutils.ccompiler.CCompiler のメソッド)
  • LibraryLoader (ctypes のクラス)
  • license (組み込み変数)
  • LifoQueue (asyncio のクラス)
    • (queue のクラス)
  • light-weight processes
  • limit_denominator() (fractions.Fraction のメソッド)
  • LimitOverrunError
  • lin2adpcm() (audioop モジュール)
  • lin2alaw() (audioop モジュール)
  • lin2lin() (audioop モジュール)
  • lin2ulaw() (audioop モジュール)
  • line (C の関数)
  • line continuation
  • line joining, [1]
  • line structure
  • line() (msilib.Dialog のメソッド)
  • line-buffered I/O
  • line_buffering (io.TextIOWrapper の属性)
  • line_num (csv.csvreader の属性)
  • linecache (モジュール)
  • lineno (ast.AST の属性)
    • (doctest.DocTest の属性)
    • (doctest.Example の属性)
    • (json.JSONDecodeError の属性)
    • (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
    • (re.error の属性)
    • (shlex.shlex の属性)
    • (traceback.TracebackException の属性)
    • (tracemalloc.Filter の属性)
    • (tracemalloc.Frame の属性)
    • (xml.parsers.expat.ExpatError の属性)
  • lineno() (fileinput モジュール)
  • LINES, [1], [2], [3], [4]
  • lines (os.terminal_size の属性)
  • linesep (email.policy.Policy の属性)
    • (os モジュール)
  • lineterminator (csv.Dialect の属性)
  • LineTooLong
  • link() (distutils.ccompiler.CCompiler のメソッド)
    • (os モジュール)
  • link_executable() (distutils.ccompiler.CCompiler のメソッド)
  • link_shared_lib() (distutils.ccompiler.CCompiler のメソッド)
  • link_shared_object() (distutils.ccompiler.CCompiler のメソッド)
  • linkname (tarfile.TarInfo の属性)
  • linux_distribution() (platform モジュール)
  • list
    • assignment, target
    • comprehensions
    • deletion target
    • display
    • empty
    • expression, [1], [2]
    • target, [1], [2]
    • type, operations on
    • オブジェクト, [1], [2], [3], [4], [5], [6], [7], [8]
  • list (pdb command)
  • List (typing のクラス)
  • list (組み込みクラス)
  • list comprehension
  • list() (imaplib.IMAP4 のメソッド)
    • (multiprocessing.managers.SyncManager のメソッド)
    • (nntplib.NNTP のメソッド)
    • (poplib.POP3 のメソッド)
    • (tarfile.TarFile のメソッド)
  • LIST_APPEND (opcode)
  • list_dialects() (csv モジュール)
  • list_folders() (mailbox.Maildir のメソッド)
    • (mailbox.MH のメソッド)
  • listdir() (os モジュール)
  • listen() (asyncore.dispatcher のメソッド)
    • (logging.config モジュール)
    • (socket.socket のメソッド)
    • (turtle モジュール)
  • Listener (multiprocessing.connection のクラス)
  • listMethods() (xmlrpc.client.ServerProxy.system のメソッド)
  • ListNoteBook (tkinter.tix のクラス)
  • listxattr() (os モジュール)
  • literal, [1]
  • literal_eval() (ast モジュール)
  • literals
    • binary
    • complex number
    • floating point
    • hexadecimal
    • integer
    • numeric
    • octal
  • LittleEndianStructure (ctypes のクラス)
  • ljust() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • LK_LOCK (msvcrt モジュール)
  • LK_NBLCK (msvcrt モジュール)
  • LK_NBRLCK (msvcrt モジュール)
  • LK_RLCK (msvcrt モジュール)
  • LK_UNLCK (msvcrt モジュール)
  • ll (pdb command)
  • LMTP (smtplib のクラス)
  • ln() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • LNAME
  • lngettext() (gettext モジュール)
    • (gettext.GNUTranslations のメソッド)
    • (gettext.NullTranslations のメソッド)
  • load() (http.cookiejar.FileCookieJar のメソッド)
    • (http.cookies.BaseCookie のメソッド)
    • (json モジュール)
    • (marshal モジュール)
    • (pickle モジュール)
    • (pickle.Unpickler のメソッド)
    • (plistlib モジュール)
    • (tracemalloc.Snapshot のクラスメソッド)
  • LOAD_ATTR (opcode)
  • LOAD_BUILD_CLASS (opcode)
  • load_cert_chain() (ssl.SSLContext のメソッド)
  • LOAD_CLASSDEREF (opcode)
  • LOAD_CLOSURE (opcode)
  • LOAD_CONST (opcode)
  • load_default_certs() (ssl.SSLContext のメソッド)
  • LOAD_DEREF (opcode)
  • load_dh_params() (ssl.SSLContext のメソッド)
  • load_extension() (sqlite3.Connection のメソッド)
  • LOAD_FAST (opcode)
  • LOAD_GLOBAL (opcode)
  • LOAD_METHOD (opcode)
  • load_module() (imp モジュール)
    • (importlib.abc.FileLoader のメソッド)
    • (importlib.abc.InspectLoader のメソッド)
    • (importlib.abc.Loader のメソッド)
    • (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.SourceFileLoader のメソッド)
    • (importlib.machinery.SourcelessFileLoader のメソッド)
    • (zipimport.zipimporter のメソッド)
  • LOAD_NAME (opcode)
  • load_package_tests() (test.support モジュール)
  • load_verify_locations() (ssl.SSLContext のメソッド)
  • loader, [1]
  • Loader (importlib.abc のクラス)
  • loader (importlib.machinery.ModuleSpec の属性)
  • loader_state (importlib.machinery.ModuleSpec の属性)
  • LoadError
  • LoadKey() (winreg モジュール)
  • LoadLibrary() (ctypes.LibraryLoader のメソッド)
  • loads() (json モジュール)
    • (marshal モジュール)
    • (pickle モジュール)
    • (plistlib モジュール)
    • (xmlrpc.client モジュール)
  • loadTestsFromModule() (unittest.TestLoader のメソッド)
  • loadTestsFromName() (unittest.TestLoader のメソッド)
  • loadTestsFromNames() (unittest.TestLoader のメソッド)
  • loadTestsFromTestCase() (unittest.TestLoader のメソッド)
  • local (threading のクラス)
  • localcontext() (decimal モジュール)
  • LOCALE (re モジュール)
  • locale (モジュール)
  • localeconv() (locale モジュール)
  • LocaleHTMLCalendar (calendar のクラス)
  • LocaleTextCalendar (calendar のクラス)
  • localName (xml.dom.Attr の属性)
    • (xml.dom.Node の属性)
  • locals() (組み込み関数)
  • localtime() (email.utils モジュール)
    • (time モジュール)
  • Locator (xml.sax.xmlreader のクラス)
  • Lock (asyncio のクラス)
    • (multiprocessing のクラス)
    • (threading のクラス)
  • lock() (mailbox.Babyl のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.MMDF のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (mailbox.mbox のメソッド)
  • Lock() (multiprocessing.managers.SyncManager のメソッド)
  • lock, interpreter
  • lock_held() (imp モジュール)
  • locked() (_thread.lock のメソッド)
    • (asyncio.Condition のメソッド)
    • (asyncio.Lock のメソッド)
    • (asyncio.Semaphore のメソッド)
  • lockf() (fcntl モジュール)
    • (os モジュール)
  • locking() (msvcrt モジュール)
  • LockType (_thread モジュール)
  • log() (cmath モジュール)
    • (logging モジュール)
    • (logging.Logger のメソッド)
    • (math モジュール)
  • log10() (cmath モジュール)
    • (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (math モジュール)
  • log1p() (math モジュール)
  • log2() (math モジュール)
  • log_date_time_string() (http.server.BaseHTTPRequestHandler のメソッド)
  • log_error() (http.server.BaseHTTPRequestHandler のメソッド)
  • log_exception() (wsgiref.handlers.BaseHandler のメソッド)
  • log_message() (http.server.BaseHTTPRequestHandler のメソッド)
  • log_request() (http.server.BaseHTTPRequestHandler のメソッド)
  • log_to_stderr() (multiprocessing モジュール)
  • logb() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • Logger (logging のクラス)
  • LoggerAdapter (logging のクラス)
  • logging
    • Errors
  • logging (モジュール)
  • logging.config (モジュール)
  • logging.handlers (モジュール)
  • logical line
  • logical_and() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • logical_invert() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • logical_or() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • logical_xor() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • login() (ftplib.FTP のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (nntplib.NNTP のメソッド)
    • (smtplib.SMTP のメソッド)
  • login_cram_md5() (imaplib.IMAP4 のメソッド)
  • LOGNAME, [1]
  • lognormvariate() (random モジュール)
  • logout() (imaplib.IMAP4 のメソッド)
  • LogRecord (logging のクラス)
  • long (2to3 fixer)
  • long integer
    • オブジェクト
  • LONG_MAX
  • longMessage (unittest.TestCase の属性)
  • longname() (curses モジュール)
  • lookup() (codecs モジュール)
    • (symtable.SymbolTable のメソッド)
    • (tkinter.ttk.Style のメソッド)
    • (unicodedata モジュール)
  • lookup_error() (codecs モジュール)
  • LookupError
  • loop
    • over mutable sequence
    • statement, [1], [2], [3]
  • loop control
    • target
  • loop() (asyncore モジュール)
  • lower() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • LPAR (token モジュール)
  • lpAttributeList (subprocess.STARTUPINFO の属性)
  • lru_cache() (functools モジュール)
  • lseek() (os モジュール)
  • lshift() (operator モジュール)
  • LSQB (token モジュール)
  • lstat() (os モジュール)
    • (pathlib.Path のメソッド)
  • lstrip() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • lsub() (imaplib.IMAP4 のメソッド)
  • lt() (operator モジュール)
    • (turtle モジュール)
  • LWPCookieJar (http.cookiejar のクラス)
  • lzma (モジュール)
  • LZMACompressor (lzma のクラス)
  • LZMADecompressor (lzma のクラス)
  • LZMAError
  • LZMAFile (lzma のクラス)

M

  • M (re モジュール)
  • mac_ver() (platform モジュール)
  • machine() (platform モジュール)
  • macpath (モジュール)
  • macros (netrc.netrc の属性)
  • MAGIC_NUMBER (importlib.util モジュール)
  • MagicMock (unittest.mock のクラス)
  • Mailbox (mailbox のクラス)
  • mailbox (モジュール)
  • mailcap (モジュール)
  • Maildir (mailbox のクラス)
  • MaildirMessage (mailbox のクラス)
  • mailfrom (smtpd.SMTPChannel の属性)
  • MailmanProxy (smtpd のクラス)
  • main(), [1], [2]
    • (py_compile モジュール)
    • (site モジュール)
    • (unittest モジュール)
  • main_thread() (threading モジュール)
  • mainloop() (turtle モジュール)
  • maintype (email.headerregistry.ContentTypeHeader の属性)
  • major (email.headerregistry.MIMEVersionHeader の属性)
  • major() (os モジュール)
  • make_alternative() (email.message.EmailMessage のメソッド)
  • make_archive() (distutils.archive_util モジュール)
    • (shutil モジュール)
  • make_bad_fd() (test.support モジュール)
  • make_cookies() (http.cookiejar.CookieJar のメソッド)
  • make_dataclass() (dataclasses モジュール)
  • make_file() (difflib.HtmlDiff のメソッド)
  • MAKE_FUNCTION (opcode)
  • make_header() (email.header モジュール)
  • make_legacy_pyc() (test.support モジュール)
  • make_mixed() (email.message.EmailMessage のメソッド)
  • make_msgid() (email.utils モジュール)
  • make_parser() (xml.sax モジュール)
  • make_pkg() (test.support.script_helper モジュール)
  • make_related() (email.message.EmailMessage のメソッド)
  • make_script() (test.support.script_helper モジュール)
  • make_server() (wsgiref.simple_server モジュール)
  • make_table() (difflib.HtmlDiff のメソッド)
  • make_tarball() (distutils.archive_util モジュール)
  • make_zip_pkg() (test.support.script_helper モジュール)
  • make_zip_script() (test.support.script_helper モジュール)
  • make_zipfile() (distutils.archive_util モジュール)
  • makedev() (os モジュール)
  • makedirs() (os モジュール)
  • makeelement() (xml.etree.ElementTree.Element のメソッド)
  • makefile() (socket method)
    • (socket.socket のメソッド)
  • makeLogRecord() (logging モジュール)
  • makePickle() (logging.handlers.SocketHandler のメソッド)
  • makeRecord() (logging.Logger のメソッド)
  • makeSocket() (logging.handlers.DatagramHandler のメソッド)
    • (logging.handlers.SocketHandler のメソッド)
  • maketrans() (bytearray の静的メソッド)
    • (bytes の静的メソッド)
    • (str の静的メソッド)
  • malloc()
  • mangle_from_ (email.policy.Compat32 の属性)
    • (email.policy.Policy の属性)
  • mangling
    • name, [1]
  • map (2to3 fixer)
  • map() (concurrent.futures.Executor のメソッド)
    • (multiprocessing.pool.Pool のメソッド)
    • (tkinter.ttk.Style のメソッド)
    • (組み込み関数)
  • MAP_ADD (opcode)
  • map_async() (multiprocessing.pool.Pool のメソッド)
  • map_table_b2() (stringprep モジュール)
  • map_table_b3() (stringprep モジュール)
  • map_to_type() (email.headerregistry.HeaderRegistry のメソッド)
  • mapLogRecord() (logging.handlers.HTTPHandler のメソッド)
  • mapping
    • types, operations on
    • オブジェクト, [1], [2], [3], [4], [5]
  • Mapping (collections.abc のクラス)
    • (typing のクラス)
  • mapping() (msilib.Control のメソッド)
  • MappingProxyType (types のクラス)
  • MappingView (collections.abc のクラス)
    • (typing のクラス)
  • mapPriority() (logging.handlers.SysLogHandler のメソッド)
  • maps (collections.ChainMap の属性)
  • maps() (nis モジュール)
  • marshal (モジュール)
  • marshalling
    • objects
  • masking
    • operations
  • Match (typing のクラス)
  • match() (nis モジュール)
    • (pathlib.PurePath のメソッド)
    • (re モジュール)
    • (re.Pattern のメソッド)
  • match_hostname() (ssl モジュール)
  • match_test() (test.support モジュール)
  • match_value() (test.support.Matcher のメソッド)
  • Matcher (test.support のクラス)
  • matches() (test.support.Matcher のメソッド)
  • math
    • モジュール, [1]
  • math (モジュール)
  • matmul() (operator モジュール)
  • matrix multiplication
  • max
    • 組み込み関数
  • max (datetime.date の属性)
    • (datetime.datetime の属性)
    • (datetime.time の属性)
    • (datetime.timedelta の属性)
  • max() (audioop モジュール)
    • (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (組み込み関数)
  • max_count (email.headerregistry.BaseHeader の属性)
  • MAX_EMAX (decimal モジュール)
  • MAX_INTERPOLATION_DEPTH (configparser モジュール)
  • max_line_length (email.policy.Policy の属性)
  • max_lines (textwrap.TextWrapper の属性)
  • max_mag() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • max_memuse (test.support モジュール)
  • MAX_PREC (decimal モジュール)
  • max_prefixlen (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • MAX_Py_ssize_t (test.support モジュール)
  • maxarray (reprlib.Repr の属性)
  • maxdeque (reprlib.Repr の属性)
  • maxdict (reprlib.Repr の属性)
  • maxDiff (unittest.TestCase の属性)
  • maxfrozenset (reprlib.Repr の属性)
  • MAXIMUM_SUPPORTED (ssl.TLSVersion の属性)
  • maximum_version (ssl.SSLContext の属性)
  • maxlen (collections.deque の属性)
  • maxlevel (reprlib.Repr の属性)
  • maxlist (reprlib.Repr の属性)
  • maxlong (reprlib.Repr の属性)
  • maxother (reprlib.Repr の属性)
  • maxpp() (audioop モジュール)
  • maxset (reprlib.Repr の属性)
  • maxsize (asyncio.Queue の属性)
    • (sys モジュール)
  • maxstring (reprlib.Repr の属性)
  • maxtuple (reprlib.Repr の属性)
  • maxunicode (sys モジュール)
  • MAXYEAR (datetime モジュール)
  • MB_ICONASTERISK (winsound モジュール)
  • MB_ICONEXCLAMATION (winsound モジュール)
  • MB_ICONHAND (winsound モジュール)
  • MB_ICONQUESTION (winsound モジュール)
  • MB_OK (winsound モジュール)
  • mbox (mailbox のクラス)
  • mboxMessage (mailbox のクラス)
  • mean() (statistics モジュール)
  • median() (statistics モジュール)
  • median_grouped() (statistics モジュール)
  • median_high() (statistics モジュール)
  • median_low() (statistics モジュール)
  • MemberDescriptorType (types モジュール)
  • membership
    • test
  • memmove() (ctypes モジュール)
  • MemoryBIO (ssl のクラス)
  • MemoryError
  • MemoryHandler (logging.handlers のクラス)
  • memoryview
    • オブジェクト, [1]
  • memoryview (組み込みクラス)
  • memset() (ctypes モジュール)
  • merge() (heapq モジュール)
  • Message (email.message のクラス)
    • (mailbox のクラス)
  • message digest, MD5
  • message_factory (email.policy.Policy の属性)
  • message_from_binary_file() (email モジュール)
  • message_from_bytes() (email モジュール)
  • message_from_file() (email モジュール)
  • message_from_string() (email モジュール)
  • MessageBeep() (winsound モジュール)
  • MessageClass (http.server.BaseHTTPRequestHandler の属性)
  • MessageError
  • MessageParseError
  • messages (xml.parsers.expat.errors モジュール)
  • meta
    • hooks
  • meta hooks
  • meta path finder
  • meta() (curses モジュール)
  • meta_path (sys モジュール)
  • metaclass, [1]
    • (2to3 fixer)
  • metaclass hint
  • MetaPathFinder (importlib.abc のクラス)
  • metavar (optparse.Option の属性)
  • MetavarTypeHelpFormatter (argparse のクラス)
  • Meter (tkinter.tix のクラス)
  • METH_CLASS (組み込み変数)
  • METH_COEXIST (組み込み変数)
  • METH_KEYWORDS (組み込み変数)
  • METH_NOARGS (組み込み変数)
  • METH_O (組み込み変数)
  • METH_STATIC (組み込み変数)
  • METH_VARARGS (組み込み変数)
  • method
    • built-in
    • call
    • user-defined
    • オブジェクト, [1], [2], [3], [4], [5]
  • method (urllib.request.Request の属性)
  • method resolution order
  • METHOD_BLOWFISH (crypt モジュール)
  • method_calls (unittest.mock.Mock の属性)
  • METHOD_CRYPT (crypt モジュール)
  • METHOD_MD5 (crypt モジュール)
  • METHOD_SHA256 (crypt モジュール)
  • METHOD_SHA512 (crypt モジュール)
  • methodattrs (2to3 fixer)
  • methodcaller() (operator モジュール)
  • MethodDescriptorType (types モジュール)
  • methodHelp() (xmlrpc.client.ServerProxy.system のメソッド)
  • methods
    • bytearray
    • bytes
    • string
  • methods (crypt モジュール)
    • (pyclbr.Class の属性)
  • methodSignature() (xmlrpc.client.ServerProxy.system のメソッド)
  • MethodType (in module types), [1]
    • (types モジュール)
  • MethodWrapperType (types モジュール)
  • MH (mailbox のクラス)
  • MHMessage (mailbox のクラス)
  • microsecond (datetime.datetime の属性)
    • (datetime.time の属性)
  • MIME
    • base64 encoding
    • content type
    • headers, [1]
    • quoted-printable encoding
  • MIMEApplication (email.mime.application のクラス)
  • MIMEAudio (email.mime.audio のクラス)
  • MIMEBase (email.mime.base のクラス)
  • MIMEImage (email.mime.image のクラス)
  • MIMEMessage (email.mime.message のクラス)
  • MIMEMultipart (email.mime.multipart のクラス)
  • MIMENonMultipart (email.mime.nonmultipart のクラス)
  • MIMEPart (email.message のクラス)
  • MIMEText (email.mime.text のクラス)
  • MimeTypes (mimetypes のクラス)
  • mimetypes (モジュール)
  • MIMEVersionHeader (email.headerregistry のクラス)
  • min
    • 組み込み関数
  • min (datetime.date の属性)
    • (datetime.datetime の属性)
    • (datetime.time の属性)
    • (datetime.timedelta の属性)
  • min() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (組み込み関数)
  • MIN_EMIN (decimal モジュール)
  • MIN_ETINY (decimal モジュール)
  • min_mag() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • MINEQUAL (token モジュール)
  • MINIMUM_SUPPORTED (ssl.TLSVersion の属性)
  • minimum_version (ssl.SSLContext の属性)
  • minmax() (audioop モジュール)
  • minor (email.headerregistry.MIMEVersionHeader の属性)
  • minor() (os モジュール)
  • minus
  • MINUS (token モジュール)
  • minus() (decimal.Context のメソッド)
  • minute (datetime.datetime の属性)
    • (datetime.time の属性)
  • MINYEAR (datetime モジュール)
  • mirrored() (unicodedata モジュール)
  • misc_header (cmd.Cmd の属性)
  • MISSING (contextvars.contextvars.Token.Token の属性)
  • MISSING_C_DOCSTRINGS (test.support モジュール)
  • missing_compiler_executable() (test.support モジュール)
  • MissingSectionHeaderError
  • MIXERDEV
  • mkd() (ftplib.FTP のメソッド)
  • mkdir() (os モジュール)
    • (pathlib.Path のメソッド)
  • mkdtemp() (tempfile モジュール)
  • mkfifo() (os モジュール)
  • mknod() (os モジュール)
  • mkpath() (distutils.ccompiler.CCompiler のメソッド)
    • (distutils.dir_util モジュール)
  • mksalt() (crypt モジュール)
  • mkstemp() (tempfile モジュール)
  • mktemp() (tempfile モジュール)
  • mktime() (time モジュール)
  • mktime_tz() (email.utils モジュール)
  • mlsd() (ftplib.FTP のメソッド)
  • mmap (mmap のクラス)
    • (モジュール)
  • MMDF (mailbox のクラス)
  • MMDFMessage (mailbox のクラス)
  • Mock (unittest.mock のクラス)
  • mock_add_spec() (unittest.mock.Mock のメソッド)
  • mock_calls (unittest.mock.Mock の属性)
  • mock_open() (unittest.mock モジュール)
  • mod() (operator モジュール)
  • mode (io.FileIO の属性)
    • (ossaudiodev.oss_audio_device の属性)
    • (tarfile.TarInfo の属性)
  • mode() (statistics モジュール)
    • (turtle モジュール)
  • modes
    • file
  • modf() (math モジュール)
  • modified() (urllib.robotparser.RobotFileParser のメソッド)
  • Modify() (msilib.View のメソッド)
  • modify() (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.poll のメソッド)
    • (selectors.BaseSelector のメソッド)
  • module
    • extension
    • importing
    • namespace
    • search path, [1], [2], [3], [4], [5], [6], [7]
    • オブジェクト, [1], [2]
  • module (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
  • module spec, [1]
  • module_for_loader() (importlib.util モジュール)
  • module_from_spec() (importlib.util モジュール)
  • module_repr() (importlib.abc.Loader のメソッド)
  • ModuleFinder (modulefinder のクラス)
  • modulefinder (モジュール)
  • ModuleInfo (pkgutil のクラス)
  • ModuleNotFoundError
  • modules (in module sys), [1]
    • (modulefinder.ModuleFinder の属性)
    • (sys モジュール)
  • modules_cleanup() (test.support モジュール)
  • modules_setup() (test.support モジュール)
  • ModuleSpec (importlib.machinery のクラス)
  • ModuleType (in module types)
    • (types のクラス)
  • modulo
  • monotonic() (time モジュール)
  • monotonic_ns() (time モジュール)
  • month (datetime.date の属性)
    • (datetime.datetime の属性)
  • month() (calendar モジュール)
  • month_abbr (calendar モジュール)
  • month_name (calendar モジュール)
  • monthcalendar() (calendar モジュール)
  • monthdatescalendar() (calendar.Calendar のメソッド)
  • monthdays2calendar() (calendar.Calendar のメソッド)
  • monthdayscalendar() (calendar.Calendar のメソッド)
  • monthrange() (calendar モジュール)
  • Morsel (http.cookies のクラス)
  • most_common() (collections.Counter のメソッド)
  • mouseinterval() (curses モジュール)
  • mousemask() (curses モジュール)
  • move() (curses.panel.Panel のメソッド)
    • (curses.window のメソッド)
    • (mmap.mmap のメソッド)
    • (shutil モジュール)
    • (tkinter.ttk.Treeview のメソッド)
  • move_file() (distutils.ccompiler.CCompiler のメソッド)
    • (distutils.file_util モジュール)
  • move_to_end() (collections.OrderedDict のメソッド)
  • MozillaCookieJar (http.cookiejar のクラス)
  • MRO
  • mro() (class のメソッド)
  • msg (http.client.HTTPResponse の属性)
    • (json.JSONDecodeError の属性)
    • (re.error の属性)
    • (traceback.TracebackException の属性)
  • msg() (telnetlib.Telnet のメソッド)
  • msi
  • msilib (モジュール)
  • msvcrt (モジュール)
  • mt_interact() (telnetlib.Telnet のメソッド)
  • mtime (gzip.GzipFile の属性)
    • (tarfile.TarInfo の属性)
  • mtime() (urllib.robotparser.RobotFileParser のメソッド)
  • mul() (audioop モジュール)
    • (operator モジュール)
  • MultiCall (xmlrpc.client のクラス)
  • MULTILINE (re モジュール)
  • MultipartConversionError
  • multiplication
  • multiply() (decimal.Context のメソッド)
  • multiprocessing (モジュール)
  • multiprocessing.connection (モジュール)
  • multiprocessing.dummy (モジュール)
  • multiprocessing.Manager() (multiprocessing.sharedctypes モジュール)
  • multiprocessing.managers (モジュール)
  • multiprocessing.pool (モジュール)
  • multiprocessing.sharedctypes (モジュール)
  • mutable
    • sequence types
    • オブジェクト, [1], [2]
  • mutable object
  • mutable sequence
    • loop over
    • オブジェクト
  • MutableMapping (collections.abc のクラス)
    • (typing のクラス)
  • MutableSequence (collections.abc のクラス)
    • (typing のクラス)
  • MutableSet (collections.abc のクラス)
    • (typing のクラス)
  • mvderwin() (curses.window のメソッド)
  • mvwin() (curses.window のメソッド)
  • myrights() (imaplib.IMAP4 のメソッド)

N

  • N_TOKENS (token モジュール)
  • n_waiting (threading.Barrier の属性)
  • name, [1], [2]
    • binding, [1], [2], [3], [4], [5], [6]
    • binding, global
    • class
    • function, [1]
    • mangling, [1]
    • rebinding
    • unbinding
  • name (codecs.CodecInfo の属性)
    • (contextvars.ContextVar の属性)
    • (doctest.DocTest の属性)
    • (email.headerregistry.BaseHeader の属性)
    • (hashlib.hash の属性)
    • (hmac.HMAC の属性)
    • (http.cookiejar.Cookie の属性)
    • (importlib.abc.FileLoader の属性)
    • (importlib.machinery.ExtensionFileLoader の属性)
    • (importlib.machinery.ModuleSpec の属性)
    • (importlib.machinery.SourceFileLoader の属性)
    • (importlib.machinery.SourcelessFileLoader の属性)
    • (inspect.Parameter の属性)
    • (io.FileIO の属性)
    • (multiprocessing.Process の属性)
    • (os モジュール)
    • (os.DirEntry の属性)
    • (ossaudiodev.oss_audio_device の属性)
    • (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
    • (tarfile.TarInfo の属性)
    • (threading.Thread の属性)
  • NAME (token モジュール)
  • name (xml.dom.Attr の属性)
    • (xml.dom.DocumentType の属性)
  • name() (unicodedata モジュール)
  • name2codepoint (html.entities モジュール)
  • named tuple
  • NamedTemporaryFile() (tempfile モジュール)
  • NamedTuple (typing のクラス)
  • namedtuple() (collections モジュール)
  • NameError
    • 例外
  • NameError (built-in exception)
  • namelist() (zipfile.ZipFile のメソッド)
  • nameprep() (encodings.idna モジュール)
  • namer (logging.handlers.BaseRotatingHandler の属性)
  • namereplace_errors() (codecs モジュール)
  • names
    • private
  • namespace, [1]
    • global
    • module
    • package
  • Namespace (argparse のクラス)
    • (multiprocessing.managers のクラス)
  • namespace package
  • namespace() (imaplib.IMAP4 のメソッド)
  • Namespace() (multiprocessing.managers.SyncManager のメソッド)
  • NAMESPACE_DNS (uuid モジュール)
  • NAMESPACE_OID (uuid モジュール)
  • NAMESPACE_URL (uuid モジュール)
  • NAMESPACE_X500 (uuid モジュール)
  • NamespaceErr
  • namespaceURI (xml.dom.Node の属性)
  • NaN
  • nan (cmath モジュール)
    • (math モジュール)
  • nanj (cmath モジュール)
  • NannyNag
  • napms() (curses モジュール)
  • nargs (optparse.Option の属性)
  • nbytes (memoryview の属性)
  • ndiff() (difflib モジュール)
  • ndim (memoryview の属性)
  • ne (2to3 fixer)
  • ne() (operator モジュール)
  • needs_input (bz2.BZ2Decompressor の属性)
    • (lzma.LZMADecompressor の属性)
  • neg() (operator モジュール)
  • negation
  • nested scope
  • netmask (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • NetmaskValueError
  • netrc (netrc のクラス)
    • (モジュール)
  • NetrcParseError
  • netscape (http.cookiejar.CookiePolicy の属性)
  • network (ipaddress.IPv4Interface の属性)
    • (ipaddress.IPv6Interface の属性)
  • Network News Transfer Protocol
  • network_address (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • new() (hashlib モジュール)
    • (hmac モジュール)
  • new-style class
  • new_alignment() (formatter.writer のメソッド)
  • new_child() (collections.ChainMap のメソッド)
  • new_class() (types モジュール)
  • new_compiler() (distutils.ccompiler モジュール)
  • new_event_loop() (asyncio モジュール)
    • (asyncio.AbstractEventLoopPolicy のメソッド)
  • new_font() (formatter.writer のメソッド)
  • new_margin() (formatter.writer のメソッド)
  • new_module() (imp モジュール)
  • new_panel() (curses.panel モジュール)
  • new_spacing() (formatter.writer のメソッド)
  • new_styles() (formatter.writer のメソッド)
  • newer() (distutils.dep_util モジュール)
  • newer_group() (distutils.dep_util モジュール)
  • newer_pairwise() (distutils.dep_util モジュール)
  • newgroups() (nntplib.NNTP のメソッド)
  • NEWLINE (token モジュール)
  • NEWLINE token, [1]
  • newlines (io.TextIOBase の属性)
  • newnews() (nntplib.NNTP のメソッド)
  • newpad() (curses モジュール)
  • NewType() (typing モジュール)
  • newwin() (curses モジュール)
  • next (2to3 fixer)
    • (pdb command)
  • next() (nntplib.NNTP のメソッド)
    • (tarfile.TarFile のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
    • (組み込み関数)
  • next_minus() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • next_plus() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • next_toward() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • nextfile() (fileinput モジュール)
  • nextkey() (dbm.gnu.gdbm のメソッド)
  • nextSibling (xml.dom.Node の属性)
  • ngettext() (gettext モジュール)
    • (gettext.GNUTranslations のメソッド)
    • (gettext.NullTranslations のメソッド)
  • nice() (os モジュール)
  • nis (モジュール)
  • NL (token モジュール)
  • nl() (curses モジュール)
  • nl_langinfo() (locale モジュール)
  • nlargest() (heapq モジュール)
  • nlst() (ftplib.FTP のメソッド)
  • NNTP
    • protocol
  • NNTP (nntplib のクラス)
  • nntp_implementation (nntplib.NNTP の属性)
  • NNTP_SSL (nntplib のクラス)
  • nntp_version (nntplib.NNTP の属性)
  • NNTPDataError
  • NNTPError
  • nntplib (モジュール)
  • NNTPPermanentError
  • NNTPProtocolError
  • NNTPReplyError
  • NNTPTemporaryError
  • no_proxy
  • no_tracing() (test.support モジュール)
  • no_type_check() (typing モジュール)
  • no_type_check_decorator() (typing モジュール)
  • nocbreak() (curses モジュール)
  • NoDataAllowedErr
  • node() (platform モジュール)
  • nodelay() (curses.window のメソッド)
  • nodeName (xml.dom.Node の属性)
  • NodeTransformer (ast のクラス)
  • nodeType (xml.dom.Node の属性)
  • nodeValue (xml.dom.Node の属性)
  • NodeVisitor (ast のクラス)
  • noecho() (curses モジュール)
  • NOEXPR (locale モジュール)
  • NoModificationAllowedErr
  • nonblock() (ossaudiodev.oss_audio_device のメソッド)
  • NonCallableMagicMock (unittest.mock のクラス)
  • NonCallableMock (unittest.mock のクラス)
  • None
    • オブジェクト, [1], [2]
  • None (Built-in object)
    • (組み込み変数)
  • nonl() (curses モジュール)
  • nonlocal
    • 文
  • nonzero (2to3 fixer)
  • noop() (imaplib.IMAP4 のメソッド)
    • (poplib.POP3 のメソッド)
  • NoOptionError
  • NOP (opcode)
  • noqiflush() (curses モジュール)
  • noraw() (curses モジュール)
  • NoReturn (typing モジュール)
  • NORMAL_PRIORITY_CLASS (subprocess モジュール)
  • normalize() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (locale モジュール)
    • (unicodedata モジュール)
    • (xml.dom.Node のメソッド)
  • NORMALIZE_WHITESPACE (doctest モジュール)
  • normalvariate() (random モジュール)
  • normcase() (os.path モジュール)
  • normpath() (os.path モジュール)
  • NoSectionError
  • NoSuchMailboxError
  • not
    • 演算子, [1]
  • not in
    • 演算子, [1], [2]
  • not_() (operator モジュール)
  • NotADirectoryError
  • notation
  • notationDecl() (xml.sax.handler.DTDHandler のメソッド)
  • NotationDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • notations (xml.dom.DocumentType の属性)
  • NotConnected
  • NoteBook (tkinter.tix のクラス)
  • Notebook (tkinter.ttk のクラス)
  • NotEmptyError
  • NOTEQUAL (token モジュール)
  • NotFoundErr
  • notify() (asyncio.Condition のメソッド)
    • (threading.Condition のメソッド)
  • notify_all() (asyncio.Condition のメソッド)
    • (threading.Condition のメソッド)
  • notimeout() (curses.window のメソッド)
  • NotImplemented
    • オブジェクト
  • NotImplemented (組み込み変数)
  • NotImplementedError
  • NotStandaloneHandler() (xml.parsers.expat.xmlparser のメソッド)
  • NotSupportedErr
  • NotSupportedError
  • noutrefresh() (curses.window のメソッド)
  • now() (datetime.datetime のクラスメソッド)
  • NSIG (signal モジュール)
  • nsmallest() (heapq モジュール)
  • NT_OFFSET (token モジュール)
  • NTEventLogHandler (logging.handlers のクラス)
  • ntohl() (socket モジュール)
  • ntohs() (socket モジュール)
  • ntransfercmd() (ftplib.FTP のメソッド)
  • null
    • operation, [1]
  • nullcontext() (contextlib モジュール)
  • NullFormatter (formatter のクラス)
  • NullHandler (logging のクラス)
  • NullImporter (imp のクラス)
  • NullTranslations (gettext のクラス)
  • NullWriter (formatter のクラス)
  • num_addresses (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • number
    • complex
    • floating point
  • Number (numbers のクラス)
  • NUMBER (token モジュール)
  • number_class() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • numbers (モジュール)
  • numerator (fractions.Fraction の属性)
    • (numbers.Rational の属性)
  • numeric
    • conversions
    • literals
    • object
    • types, operations on
    • オブジェクト, [1], [2], [3]
  • numeric literal
  • numeric() (unicodedata モジュール)
  • Numerical Python
  • numinput() (turtle モジュール)
  • numliterals (2to3 fixer)

O

  • O_APPEND (os モジュール)
  • O_ASYNC (os モジュール)
  • O_BINARY (os モジュール)
  • O_CLOEXEC (os モジュール)
  • O_CREAT (os モジュール)
  • O_DIRECT (os モジュール)
  • O_DIRECTORY (os モジュール)
  • O_DSYNC (os モジュール)
  • O_EXCL (os モジュール)
  • O_EXLOCK (os モジュール)
  • O_NDELAY (os モジュール)
  • O_NOATIME (os モジュール)
  • O_NOCTTY (os モジュール)
  • O_NOFOLLOW (os モジュール)
  • O_NOINHERIT (os モジュール)
  • O_NONBLOCK (os モジュール)
  • O_PATH (os モジュール)
  • O_RANDOM (os モジュール)
  • O_RDONLY (os モジュール)
  • O_RDWR (os モジュール)
  • O_RSYNC (os モジュール)
  • O_SEQUENTIAL (os モジュール)
  • O_SHLOCK (os モジュール)
  • O_SHORT_LIVED (os モジュール)
  • O_SYNC (os モジュール)
  • O_TEMPORARY (os モジュール)
  • O_TEXT (os モジュール)
  • O_TMPFILE (os モジュール)
  • O_TRUNC (os モジュール)
  • O_WRONLY (os モジュール)
  • obj (memoryview の属性)
  • object, [1]
    • code, [1], [2], [3]
    • deallocation
    • finalization
    • immutable, [1]
    • numeric
  • object (UnicodeError の属性)
    • (組み込みクラス)
  • object.__slots__ (組み込み変数)
  • object_filenames() (distutils.ccompiler.CCompiler のメソッド)
  • objects
    • comparing
    • flattening
    • marshalling
    • persistent
    • pickling
    • serializing
  • obufcount() (ossaudiodev.oss_audio_device のメソッド)
  • obuffree() (ossaudiodev.oss_audio_device のメソッド)
  • oct() (組み込み関数)
  • octal
    • literals
  • octal literal
  • octdigits (string モジュール)
  • offset (traceback.TracebackException の属性)
    • (xml.parsers.expat.ExpatError の属性)
  • OK (curses モジュール)
  • old_value (contextvars.contextvars.Token.Token の属性)
  • OleDLL (ctypes のクラス)
  • onclick() (turtle モジュール), [1]
  • ondrag() (turtle モジュール)
  • onecmd() (cmd.Cmd のメソッド)
  • onkey() (turtle モジュール)
  • onkeypress() (turtle モジュール)
  • onkeyrelease() (turtle モジュール)
  • onrelease() (turtle モジュール)
  • onscreenclick() (turtle モジュール)
  • ontimer() (turtle モジュール)
  • OP (token モジュール)
  • OP_ALL (ssl モジュール)
  • OP_CIPHER_SERVER_PREFERENCE (ssl モジュール)
  • OP_ENABLE_MIDDLEBOX_COMPAT (ssl モジュール)
  • OP_NO_COMPRESSION (ssl モジュール)
  • OP_NO_RENEGOTIATION (ssl モジュール)
  • OP_NO_SSLv2 (ssl モジュール)
  • OP_NO_SSLv3 (ssl モジュール)
  • OP_NO_TICKET (ssl モジュール)
  • OP_NO_TLSv1 (ssl モジュール)
  • OP_NO_TLSv1_1 (ssl モジュール)
  • OP_NO_TLSv1_2 (ssl モジュール)
  • OP_NO_TLSv1_3 (ssl モジュール)
  • OP_SINGLE_DH_USE (ssl モジュール)
  • OP_SINGLE_ECDH_USE (ssl モジュール)
  • open
    • 組み込み関数, [1]
  • open() (aifc モジュール)
    • (bz2 モジュール)
    • (codecs モジュール)
    • (dbm モジュール)
    • (dbm.dumb モジュール)
    • (dbm.gnu モジュール)
    • (dbm.ndbm モジュール)
    • (distutils.text_file.TextFile のメソッド)
    • (gzip モジュール)
    • (imaplib.IMAP4 のメソッド)
    • (io モジュール)
    • (lzma モジュール)
    • (os モジュール)
    • (ossaudiodev モジュール)
    • (pathlib.Path のメソッド)
    • (pipes.Template のメソッド)
    • (shelve モジュール)
    • (sunau モジュール)
    • (tarfile モジュール)
    • (tarfile.TarFile のクラスメソッド)
    • (telnetlib.Telnet のメソッド)
    • (tokenize モジュール)
    • (urllib.request.OpenerDirector のメソッド)
    • (urllib.request.URLopener のメソッド)
    • (wave モジュール)
    • (webbrowser モジュール)
    • (webbrowser.controller のメソッド)
    • (zipfile.ZipFile のメソッド)
    • (組み込み関数)
  • open_binary() (importlib.resources モジュール)
  • open_connection() (asyncio モジュール)
  • open_new() (webbrowser モジュール)
    • (webbrowser.controller のメソッド)
  • open_new_tab() (webbrowser モジュール)
    • (webbrowser.controller のメソッド)
  • open_osfhandle() (msvcrt モジュール)
  • open_resource() (importlib.abc.ResourceReader のメソッド)
  • open_text() (importlib.resources モジュール)
  • open_unix_connection() (asyncio モジュール)
  • open_unknown() (urllib.request.URLopener のメソッド)
  • open_urlresource() (test.support モジュール)
  • OpenDatabase() (msilib モジュール)
  • OpenerDirector (urllib.request のクラス)
  • openfp() (sunau モジュール)
    • (wave モジュール)
  • OpenKey() (winreg モジュール)
  • OpenKeyEx() (winreg モジュール)
  • openlog() (syslog モジュール)
  • openmixer() (ossaudiodev モジュール)
  • openpty() (os モジュール)
    • (pty モジュール)
  • OpenSSL
    • (use in module hashlib)
    • (use in module ssl)
  • OPENSSL_VERSION (ssl モジュール)
  • OPENSSL_VERSION_INFO (ssl モジュール)
  • OPENSSL_VERSION_NUMBER (ssl モジュール)
  • OpenView() (msilib.Database のメソッド)
  • operation
    • Boolean
    • binary arithmetic
    • binary bitwise
    • concatenation
    • null, [1]
    • power
    • repetition
    • shifting
    • slice
    • subscript
    • unary arithmetic
    • unary bitwise
  • OperationalError
  • operations
    • Boolean, [1]
    • bitwise
    • masking
    • shifting
  • operations on
    • dictionary type
    • integer types
    • list type
    • mapping types
    • numeric types
    • sequence types, [1]
  • operator
    • + (plus), [1], [2]
    • - (minus), [1], [2]
    • comparison
    • overloading
    • precedence
    • ternary
  • operator (2to3 fixer)
    • (モジュール)
  • operators
  • opmap (dis モジュール)
  • opname (dis モジュール)
  • optim_args_from_interpreter_flags() (test.support モジュール)
  • optimize() (pickletools モジュール)
  • OPTIMIZED_BYTECODE_SUFFIXES (importlib.machinery モジュール)
  • Optional (typing モジュール)
  • OptionGroup (optparse のクラス)
  • OptionMenu (tkinter.tix のクラス)
  • OptionParser (optparse のクラス)
  • options (doctest.Example の属性)
  • Options (ssl のクラス)
  • options (ssl.SSLContext の属性)
  • options() (configparser.ConfigParser のメソッド)
  • optionxform() (configparser.ConfigParser のメソッド), [1]
  • optparse (モジュール)
  • or
    • bitwise
    • exclusive
    • inclusive
    • 演算子, [1], [2]
  • or_() (operator モジュール)
  • ord
    • 組み込み関数
  • ord() (組み込み関数)
  • order
    • evaluation
  • ordered_attributes (xml.parsers.expat.xmlparser の属性)
  • OrderedDict (collections のクラス)
    • (typing のクラス)
  • origin (importlib.machinery.ModuleSpec の属性)
  • origin_req_host (urllib.request.Request の属性)
  • origin_server (wsgiref.handlers.BaseHandler の属性)
  • os
    • モジュール
  • os (モジュール)
  • os.path (モジュール)
  • os_environ (wsgiref.handlers.BaseHandler の属性)
  • OSError
  • ossaudiodev (モジュール)
  • OSSAudioError
  • outfile
    • json.tool コマンドラインオプション
  • output
    • standard
  • output (subprocess.CalledProcessError の属性)
    • (subprocess.TimeoutExpired の属性)
    • (unittest.TestCase の属性)
  • output() (http.cookies.BaseCookie のメソッド)
    • (http.cookies.Morsel のメソッド)
  • output_charset (email.charset.Charset の属性)
  • output_charset() (gettext.NullTranslations のメソッド)
  • output_codec (email.charset.Charset の属性)
  • output_difference() (doctest.OutputChecker のメソッド)
  • OutputChecker (doctest のクラス)
  • OutputString() (http.cookies.Morsel のメソッド)
  • over() (nntplib.NNTP のメソッド)
  • Overflow (decimal のクラス)
  • OverflowError
    • (built-in exception), [1], [2], [3], [4], [5]
  • overlaps() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • overlay() (curses.window のメソッド)
  • overload() (typing モジュール)
  • overloading
    • operator
  • overwrite() (curses.window のメソッド)
  • owner() (pathlib.Path のメソッド)

P

  • p (pdb command)
  • P_ALL (os モジュール)
  • P_DETACH (os モジュール)
  • P_NOWAIT (os モジュール)
  • P_NOWAITO (os モジュール)
  • P_OVERLAY (os モジュール)
  • P_PGID (os モジュール)
  • P_PID (os モジュール)
  • P_WAIT (os モジュール)
  • pack() (mailbox.MH のメソッド)
    • (struct モジュール)
    • (struct.Struct のメソッド)
  • pack_array() (xdrlib.Packer のメソッド)
  • pack_bytes() (xdrlib.Packer のメソッド)
  • pack_double() (xdrlib.Packer のメソッド)
  • pack_farray() (xdrlib.Packer のメソッド)
  • pack_float() (xdrlib.Packer のメソッド)
  • pack_fopaque() (xdrlib.Packer のメソッド)
  • pack_fstring() (xdrlib.Packer のメソッド)
  • pack_into() (struct モジュール)
    • (struct.Struct のメソッド)
  • pack_list() (xdrlib.Packer のメソッド)
  • pack_opaque() (xdrlib.Packer のメソッド)
  • pack_string() (xdrlib.Packer のメソッド)
  • package, [1], [2]
    • namespace
    • portion
    • regular
  • Package (importlib.resources モジュール)
  • package variable
    • __all__
  • packed (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv6Address の属性)
  • Packer (xdrlib のクラス)
  • packing
    • binary data
  • packing (widgets)
  • PAGER
  • pair_content() (curses モジュール)
  • pair_number() (curses モジュール)
  • PanedWindow (tkinter.tix のクラス)
  • parameter
    • call semantics
    • difference from argument
    • function definition
    • value, default
  • Parameter (inspect のクラス)
  • ParameterizedMIMEHeader (email.headerregistry のクラス)
  • parameters (inspect.Signature の属性)
  • params (email.headerregistry.ParameterizedMIMEHeader の属性)
  • pardir (os モジュール)
  • paren (2to3 fixer)
  • parent (importlib.machinery.ModuleSpec の属性)
    • (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
    • (urllib.request.BaseHandler の属性)
  • parent() (tkinter.ttk.Treeview のメソッド)
  • parenthesized form
  • parentNode (xml.dom.Node の属性)
  • parents (collections.ChainMap の属性)
  • paretovariate() (random モジュール)
  • parse() (ast モジュール)
    • (cgi モジュール)
    • (doctest.DocTestParser のメソッド)
    • (email.parser.BytesParser のメソッド)
    • (email.parser.Parser のメソッド)
    • (string.Formatter のメソッド)
    • (urllib.robotparser.RobotFileParser のメソッド)
    • (xml.dom.minidom モジュール)
    • (xml.dom.pulldom モジュール)
    • (xml.etree.ElementTree モジュール)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • Parse() (xml.parsers.expat.xmlparser のメソッド)
  • parse() (xml.sax モジュール)
    • (xml.sax.xmlreader.XMLReader のメソッド)
  • parse_and_bind() (readline モジュール)
  • parse_args() (argparse.ArgumentParser のメソッド)
  • PARSE_COLNAMES (sqlite3 モジュール)
  • parse_config_h() (sysconfig モジュール)
  • PARSE_DECLTYPES (sqlite3 モジュール)
  • parse_header() (cgi モジュール)
  • parse_intermixed_args() (argparse.ArgumentParser のメソッド)
  • parse_known_args() (argparse.ArgumentParser のメソッド)
  • parse_known_intermixed_args() (argparse.ArgumentParser のメソッド)
  • parse_multipart() (cgi モジュール)
  • parse_qs() (cgi モジュール)
    • (urllib.parse モジュール)
  • parse_qsl() (cgi モジュール)
    • (urllib.parse モジュール)
  • parseaddr() (email.utils モジュール)
  • parsebytes() (email.parser.BytesParser のメソッド)
  • parsedate() (email.utils モジュール)
  • parsedate_to_datetime() (email.utils モジュール)
  • parsedate_tz() (email.utils モジュール)
  • ParseError (xml.etree.ElementTree のクラス)
  • ParseFile() (xml.parsers.expat.xmlparser のメソッド)
  • ParseFlags() (imaplib モジュール)
  • parser
  • Parser (email.parser のクラス)
  • parser (モジュール)
  • ParserCreate() (xml.parsers.expat モジュール)
  • ParserError
  • ParseResult (urllib.parse のクラス)
  • ParseResultBytes (urllib.parse のクラス)
  • parsestr() (email.parser.Parser のメソッド)
  • parseString() (xml.dom.minidom モジュール)
    • (xml.dom.pulldom モジュール)
    • (xml.sax モジュール)
  • parsing
    • Python source code
    • URL
  • ParsingError
  • partial (asyncio.IncompleteReadError の属性)
  • partial() (functools モジュール)
    • (imaplib.IMAP4 のメソッド)
  • partialmethod (functools のクラス)
  • parties (threading.Barrier の属性)
  • partition() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • pass
    • 文
  • pass_() (poplib.POP3 のメソッド)
  • Paste
  • patch() (test.support モジュール)
    • (unittest.mock モジュール)
  • patch.dict() (unittest.mock モジュール)
  • patch.multiple() (unittest.mock モジュール)
  • patch.object() (unittest.mock モジュール)
  • patch.stopall() (unittest.mock モジュール)
  • PATH, [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], [31], [32], [33], [34], [35]
  • path
    • configuration file
    • hooks
    • module search, [1], [2], [3], [4], [5], [6], [7]
    • operations, [1]
  • path (http.cookiejar.Cookie の属性)
    • (http.server.BaseHTTPRequestHandler の属性)
    • (importlib.abc.FileLoader の属性)
    • (importlib.machinery.ExtensionFileLoader の属性)
    • (importlib.machinery.FileFinder の属性)
    • (importlib.machinery.SourceFileLoader の属性)
    • (importlib.machinery.SourcelessFileLoader の属性)
    • (in module sys), [1], [2], [3]
    • (os.DirEntry の属性)
  • Path (pathlib のクラス)
  • path (sys モジュール)
  • path based finder, [1]
  • Path browser
  • path entry
  • path entry finder
  • path entry hook
  • path hooks
  • path() (importlib.resources モジュール)
  • path-like object
  • path_hook() (importlib.machinery.FileFinder のクラスメソッド)
  • path_hooks (sys モジュール)
  • path_importer_cache (sys モジュール)
  • path_mtime() (importlib.abc.SourceLoader のメソッド)
  • path_return_ok() (http.cookiejar.CookiePolicy のメソッド)
  • path_stats() (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.SourceFileLoader のメソッド)
  • pathconf() (os モジュール)
  • pathconf_names (os モジュール)
  • PathEntryFinder (importlib.abc のクラス)
  • PATHEXT, [1], [2]
  • PathFinder (importlib.machinery のクラス)
  • pathlib (モジュール)
  • PathLike (os のクラス)
  • pathname2url() (urllib.request モジュール)
  • pathsep (os モジュール)
  • pattern (re.error の属性)
    • (re.Pattern の属性)
  • Pattern (typing のクラス)
  • pause() (signal モジュール)
  • pause_reading() (asyncio.ReadTransport のメソッド)
  • pause_writing() (asyncio.BaseProtocol のメソッド)
  • PAX_FORMAT (tarfile モジュール)
  • pax_headers (tarfile.TarFile の属性)
    • (tarfile.TarInfo の属性)
  • pbkdf2_hmac() (hashlib モジュール)
  • pd() (turtle モジュール)
  • Pdb (class in pdb)
    • (pdb のクラス)
  • pdb (モジュール)
  • peek() (bz2.BZ2File のメソッド)
    • (gzip.GzipFile のメソッド)
    • (io.BufferedReader のメソッド)
    • (lzma.LZMAFile のメソッド)
    • (weakref.finalize のメソッド)
  • peer (smtpd.SMTPChannel の属性)
  • PEM_cert_to_DER_cert() (ssl モジュール)
  • pen() (turtle モジュール)
  • pencolor() (turtle モジュール)
  • pending (ssl.MemoryBIO の属性)
  • pending() (ssl.SSLSocket のメソッド)
  • PendingDeprecationWarning
  • pendown() (turtle モジュール)
  • pensize() (turtle モジュール)
  • penup() (turtle モジュール)
  • PEP
  • PERCENT (token モジュール)
  • PERCENTEQUAL (token モジュール)
  • perf_counter() (time モジュール)
  • perf_counter_ns() (time モジュール)
  • Performance
  • PermissionError
  • permutations() (itertools モジュール)
  • Persist() (msilib.SummaryInformation のメソッド)
  • persistence
  • persistent
    • objects
  • persistent_id (pickle protocol)
  • persistent_id() (pickle.Pickler のメソッド)
  • persistent_load (pickle protocol)
  • persistent_load() (pickle.Unpickler のメソッド)
  • PF_CAN (socket モジュール)
  • PF_PACKET (socket モジュール)
  • PF_RDS (socket モジュール)
  • pformat() (pprint モジュール)
    • (pprint.PrettyPrinter のメソッド)
  • PGO (test.support モジュール)
  • phase() (cmath モジュール)
  • Philbrick, Geoff
  • physical line, [1], [2]
  • pi (cmath モジュール)
    • (math モジュール)
  • pickle
    • モジュール, [1], [2], [3]
  • pickle (モジュール)
  • pickle() (copyreg モジュール)
  • PickleError
  • Pickler (pickle のクラス)
  • pickletools (モジュール)
  • pickletools コマンドラインオプション
    • -a, --annotate
    • -l, --indentlevel=<num>
    • -m, --memo
    • -o, --output=<file>
    • -p, --preamble=<preamble>
  • pickling
    • objects
  • PicklingError
  • pid (asyncio.asyncio.subprocess.Process の属性)
    • (multiprocessing.Process の属性)
    • (subprocess.Popen の属性)
  • PIPE (subprocess モジュール)
  • Pipe() (multiprocessing モジュール)
  • pipe() (os モジュール)
  • pipe2() (os モジュール)
  • PIPE_BUF (select モジュール)
  • pipe_connection_lost() (asyncio.SubprocessProtocol のメソッド)
  • pipe_data_received() (asyncio.SubprocessProtocol のメソッド)
  • PIPE_MAX_SIZE (test.support モジュール)
  • pipes (モジュール)
  • PKG_DIRECTORY (imp モジュール)
  • pkgutil (モジュール)
  • placeholder (textwrap.TextWrapper の属性)
  • PLAT
  • platform (in module sys)
    • (sys モジュール)
    • (モジュール)
  • platform() (platform モジュール)
  • PlaySound() (winsound モジュール)
  • plist
    • file
  • plistlib (モジュール)
  • plock() (os モジュール)
  • plus
  • PLUS (token モジュール)
  • plus() (decimal.Context のメソッド)
  • PLUSEQUAL (token モジュール)
  • pm() (pdb モジュール)
  • POINTER() (ctypes モジュール)
  • pointer() (ctypes モジュール)
  • polar() (cmath モジュール)
  • Policy (email.policy のクラス)
  • poll() (multiprocessing.connection.Connection のメソッド)
    • (select モジュール)
    • (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.poll のメソッド)
    • (subprocess.Popen のメソッド)
  • PollSelector (selectors のクラス)
  • Pool (multiprocessing.pool のクラス)
  • pop() (array.array のメソッド)
    • (collections.deque のメソッド)
    • (dict のメソッド)
    • (frozenset のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (sequence method)
  • POP3
    • protocol
  • POP3 (poplib のクラス)
  • POP3_SSL (poplib のクラス)
  • pop_alignment() (formatter.formatter のメソッド)
  • pop_all() (contextlib.ExitStack のメソッド)
  • POP_BLOCK (opcode)
  • POP_EXCEPT (opcode)
  • pop_font() (formatter.formatter のメソッド)
  • POP_JUMP_IF_FALSE (opcode)
  • POP_JUMP_IF_TRUE (opcode)
  • pop_margin() (formatter.formatter のメソッド)
  • pop_source() (shlex.shlex のメソッド)
  • pop_style() (formatter.formatter のメソッド)
  • POP_TOP (opcode)
  • Popen (subprocess のクラス)
  • popen() (in module os), [1]
    • (os モジュール)
    • (platform モジュール)
  • popitem() (collections.OrderedDict のメソッド)
    • (dict のメソッド)
    • (mailbox.Mailbox のメソッド)
  • popleft() (collections.deque のメソッド)
  • poplib (モジュール)
  • PopupMenu (tkinter.tix のクラス)
  • port (http.cookiejar.Cookie の属性)
  • port_specified (http.cookiejar.Cookie の属性)
  • portion
    • package
  • pos (json.JSONDecodeError の属性)
    • (re.Match の属性)
    • (re.error の属性)
  • pos() (operator モジュール)
    • (turtle モジュール)
  • position (xml.etree.ElementTree.ParseError の属性)
  • position() (turtle モジュール)
  • positional argument (位置引数)
  • POSIX
    • I/O control
    • threads
  • posix (モジュール)
  • POSIX_FADV_DONTNEED (os モジュール)
  • POSIX_FADV_NOREUSE (os モジュール)
  • POSIX_FADV_NORMAL (os モジュール)
  • POSIX_FADV_RANDOM (os モジュール)
  • POSIX_FADV_SEQUENTIAL (os モジュール)
  • POSIX_FADV_WILLNEED (os モジュール)
  • posix_fadvise() (os モジュール)
  • posix_fallocate() (os モジュール)
  • POSIXLY_CORRECT
  • PosixPath (pathlib のクラス)
  • post() (nntplib.NNTP のメソッド)
    • (ossaudiodev.oss_audio_device のメソッド)
  • post_handshake_auth (ssl.SSLContext の属性)
  • post_mortem() (pdb モジュール)
  • post_setup() (venv.EnvBuilder のメソッド)
  • postcmd() (cmd.Cmd のメソッド)
  • postloop() (cmd.Cmd のメソッド)
  • pow
    • 組み込み関数, [1], [2], [3], [4], [5]
  • pow() (math モジュール)
    • (operator モジュール)
    • (組み込み関数)
  • power
    • operation
  • power() (decimal.Context のメソッド)
  • pp (pdb command)
  • pprint (モジュール)
  • pprint() (pprint モジュール)
    • (pprint.PrettyPrinter のメソッド)
  • prcal() (calendar モジュール)
  • pread() (os モジュール)
  • preadv() (os モジュール)
  • preamble (email.message.EmailMessage の属性)
    • (email.message.Message の属性)
  • precedence
    • operator
  • precmd() (cmd.Cmd のメソッド)
  • prefix, [1], [2], [3]
  • PREFIX (distutils.sysconfig モジュール)
  • prefix (sys モジュール)
    • (xml.dom.Attr の属性)
    • (xml.dom.Node の属性)
    • (zipimport.zipimporter の属性)
  • PREFIXES (site モジュール)
  • prefixlen (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • preloop() (cmd.Cmd のメソッド)
  • prepare() (logging.handlers.QueueHandler のメソッド)
    • (logging.handlers.QueueListener のメソッド)
  • prepare_class() (types モジュール)
  • prepare_input_source() (xml.sax.saxutils モジュール)
  • prepend() (pipes.Template のメソッド)
  • preprocess() (distutils.ccompiler.CCompiler のメソッド)
  • PrettyPrinter (pprint のクラス)
  • prev() (tkinter.ttk.Treeview のメソッド)
  • previousSibling (xml.dom.Node の属性)
  • primary
  • print
    • 組み込み関数
  • print (2to3 fixer)
  • print() (built-in function)
    • __str__() (object method)
  • print() (組み込み関数)
  • print_callees() (pstats.Stats のメソッド)
  • print_callers() (pstats.Stats のメソッド)
  • print_directory() (cgi モジュール)
  • print_environ() (cgi モジュール)
  • print_environ_usage() (cgi モジュール)
  • print_exc() (timeit.Timer のメソッド)
    • (traceback モジュール)
  • print_exception() (traceback モジュール)
  • PRINT_EXPR (opcode)
  • print_form() (cgi モジュール)
  • print_help() (argparse.ArgumentParser のメソッド)
  • print_last() (traceback モジュール)
  • print_stack() (asyncio.Task のメソッド)
    • (traceback モジュール)
  • print_stats() (profile.Profile のメソッド)
    • (pstats.Stats のメソッド)
  • print_tb() (traceback モジュール)
  • print_usage() (argparse.ArgumentParser のメソッド)
    • (optparse.OptionParser のメソッド)
  • print_version() (optparse.OptionParser のメソッド)
  • printable (string モジュール)
  • printdir() (zipfile.ZipFile のメソッド)
  • printf-style formatting, [1]
  • PRIO_PGRP (os モジュール)
  • PRIO_PROCESS (os モジュール)
  • PRIO_USER (os モジュール)
  • PriorityQueue (asyncio のクラス)
    • (queue のクラス)
  • private
    • names
  • prlimit() (resource モジュール)
  • prmonth() (calendar モジュール)
    • (calendar.TextCalendar のメソッド)
  • ProactorEventLoop (asyncio のクラス)
  • procedure
    • call
  • process
    • group, [1]
    • id
    • id of parent
    • killing, [1]
    • scheduling priority, [1]
    • signalling, [1]
  • Process (multiprocessing のクラス)
  • process() (logging.LoggerAdapter のメソッド)
  • process_exited() (asyncio.SubprocessProtocol のメソッド)
  • process_message() (smtpd.SMTPServer のメソッド)
  • process_request() (socketserver.BaseServer のメソッド)
  • process_time() (time モジュール)
  • process_time_ns() (time モジュール)
  • process_tokens() (tabnanny モジュール)
  • ProcessError
  • processes, light-weight
  • ProcessingInstruction() (xml.etree.ElementTree モジュール)
  • processingInstruction() (xml.sax.handler.ContentHandler のメソッド)
  • ProcessingInstructionHandler() (xml.parsers.expat.xmlparser のメソッド)
  • ProcessLookupError
  • processor time, [1], [2]
  • processor() (platform モジュール)
  • ProcessPoolExecutor (concurrent.futures のクラス)
  • product() (itertools モジュール)
  • Profile (profile のクラス)
  • profile (モジュール)
  • profile function, [1], [2]
  • profiler, [1]
  • profiling, deterministic
  • program
  • ProgrammingError
  • Progressbar (tkinter.ttk のクラス)
  • prompt (cmd.Cmd の属性)
  • prompt_user_passwd() (urllib.request.FancyURLopener のメソッド)
  • prompts, interpreter
  • propagate (logging.Logger の属性)
  • property (組み込みクラス)
  • property list
  • property_declaration_handler (xml.sax.handler モジュール)
  • property_dom_node (xml.sax.handler モジュール)
  • property_lexical_handler (xml.sax.handler モジュール)
  • property_xml_string (xml.sax.handler モジュール)
  • PropertyMock (unittest.mock のクラス)
  • prot_c() (ftplib.FTP_TLS のメソッド)
  • prot_p() (ftplib.FTP_TLS のメソッド)
  • proto (socket.socket の属性)
  • protocol
    • CGI
    • FTP, [1]
    • HTTP, [1], [2], [3], [4], [5]
    • IMAP4
    • IMAP4_SSL
    • IMAP4_stream
    • NNTP
    • POP3
    • SMTP
    • Telnet
    • context management
    • copy
    • iterator
  • Protocol (asyncio のクラス)
  • protocol (ssl.SSLContext の属性)
  • PROTOCOL_SSLv2 (ssl モジュール)
  • PROTOCOL_SSLv23 (ssl モジュール)
  • PROTOCOL_SSLv3 (ssl モジュール)
  • PROTOCOL_TLS (ssl モジュール)
  • PROTOCOL_TLS_CLIENT (ssl モジュール)
  • PROTOCOL_TLS_SERVER (ssl モジュール)
  • PROTOCOL_TLSv1 (ssl モジュール)
  • PROTOCOL_TLSv1_1 (ssl モジュール)
  • PROTOCOL_TLSv1_2 (ssl モジュール)
  • protocol_version (http.server.BaseHTTPRequestHandler の属性)
  • PROTOCOL_VERSION (imaplib.IMAP4 の属性)
  • ProtocolError (xmlrpc.client のクラス)
  • provisional API
  • provisional package
  • proxy() (weakref モジュール)
  • proxyauth() (imaplib.IMAP4 のメソッド)
  • ProxyBasicAuthHandler (urllib.request のクラス)
  • ProxyDigestAuthHandler (urllib.request のクラス)
  • ProxyHandler (urllib.request のクラス)
  • ProxyType (weakref モジュール)
  • ProxyTypes (weakref モジュール)
  • pryear() (calendar.TextCalendar のメソッド)
  • ps1 (sys モジュール)
  • ps2 (sys モジュール)
  • pstats (モジュール)
  • pstdev() (statistics モジュール)
  • pthread_getcpuclockid() (time モジュール)
  • pthread_kill() (signal モジュール)
  • pthread_sigmask() (signal モジュール)
  • pthreads
  • pty
    • モジュール
  • pty (モジュール)
  • pu() (turtle モジュール)
  • publicId (xml.dom.DocumentType の属性)
  • PullDom (xml.dom.pulldom のクラス)
  • punctuation (string モジュール)
  • punctuation_chars (shlex.shlex の属性)
  • PurePath (pathlib のクラス)
  • PurePath.anchor (pathlib モジュール)
  • PurePath.drive (pathlib モジュール)
  • PurePath.name (pathlib モジュール)
  • PurePath.parent (pathlib モジュール)
  • PurePath.parents (pathlib モジュール)
  • PurePath.parts (pathlib モジュール)
  • PurePath.root (pathlib モジュール)
  • PurePath.stem (pathlib モジュール)
  • PurePath.suffix (pathlib モジュール)
  • PurePath.suffixes (pathlib モジュール)
  • PurePosixPath (pathlib のクラス)
  • PureProxy (smtpd のクラス)
  • PureWindowsPath (pathlib のクラス)
  • purge() (re モジュール)
  • Purpose.CLIENT_AUTH (ssl モジュール)
  • Purpose.SERVER_AUTH (ssl モジュール)
  • push() (asynchat.async_chat のメソッド)
    • (code.InteractiveConsole のメソッド)
    • (contextlib.ExitStack のメソッド)
  • push_alignment() (formatter.formatter のメソッド)
  • push_async_callback() (contextlib.AsyncExitStack のメソッド)
  • push_async_exit() (contextlib.AsyncExitStack のメソッド)
  • push_font() (formatter.formatter のメソッド)
  • push_margin() (formatter.formatter のメソッド)
  • push_source() (shlex.shlex のメソッド)
  • push_style() (formatter.formatter のメソッド)
  • push_token() (shlex.shlex のメソッド)
  • push_with_producer() (asynchat.async_chat のメソッド)
  • pushbutton() (msilib.Dialog のメソッド)
  • put() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (multiprocessing.SimpleQueue のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
  • put_nowait() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
  • putch() (msvcrt モジュール)
  • putenv() (os モジュール)
  • putheader() (http.client.HTTPConnection のメソッド)
  • putp() (curses モジュール)
  • putrequest() (http.client.HTTPConnection のメソッド)
  • putwch() (msvcrt モジュール)
  • putwin() (curses.window のメソッド)
  • pvariance() (statistics モジュール)
  • pwd
    • モジュール
  • pwd (モジュール)
  • pwd() (ftplib.FTP のメソッド)
  • pwrite() (os モジュール)
  • pwritev() (os モジュール)
  • Py_ABS (C のマクロ)
  • Py_AddPendingCall (C の関数)
  • Py_AddPendingCall()
  • Py_AtExit (C の関数)
  • Py_BEGIN_ALLOW_THREADS
    • (C のマクロ)
  • Py_BLOCK_THREADS (C のマクロ)
  • Py_buffer (C のデータ型)
  • Py_buffer.buf (C のメンバ変数)
  • Py_buffer.format (C のメンバ変数)
  • Py_buffer.internal (C のメンバ変数)
  • Py_buffer.itemsize (C のメンバ変数)
  • Py_buffer.len (C のメンバ変数)
  • Py_buffer.ndim (C のメンバ変数)
  • Py_buffer.obj (C のメンバ変数)
  • Py_buffer.readonly (C のメンバ変数)
  • Py_buffer.shape (C のメンバ変数)
  • Py_buffer.strides (C のメンバ変数)
  • Py_buffer.suboffsets (C のメンバ変数)
  • Py_BuildValue (C の関数)
  • Py_BytesWarningFlag (C の変数)
  • Py_CHARMASK (C のマクロ)
  • Py_CLEAR (C の関数)
  • py_compile (モジュール)
  • PY_COMPILED (imp モジュール)
  • Py_CompileString (C の関数)
  • Py_CompileString(), [1], [2]
  • Py_CompileStringExFlags (C の関数)
  • Py_CompileStringFlags (C の関数)
  • Py_CompileStringObject (C の関数)
  • Py_complex (C のデータ型)
  • Py_DebugFlag (C の変数)
  • Py_DecodeLocale (C の関数)
  • Py_DECREF (C の関数)
  • Py_DECREF()
  • Py_DontWriteBytecodeFlag (C の変数)
  • Py_Ellipsis (C の変数)
  • Py_EncodeLocale (C の関数)
  • Py_END_ALLOW_THREADS
    • (C のマクロ)
  • Py_EndInterpreter (C の関数)
  • Py_EnterRecursiveCall (C の関数)
  • Py_eval_input (C の変数)
  • Py_Exit (C の関数)
  • Py_False (C の変数)
  • Py_FatalError (C の関数)
  • Py_FatalError()
  • Py_FdIsInteractive (C の関数)
  • Py_file_input (C の変数)
  • Py_Finalize (C の関数)
  • Py_FinalizeEx (C の関数)
  • Py_FinalizeEx(), [1], [2], [3], [4]
  • PY_FROZEN (imp モジュール)
  • Py_FrozenFlag (C の変数)
  • Py_GetBuildInfo (C の関数)
  • Py_GetCompiler (C の関数)
  • Py_GetCopyright (C の関数)
  • Py_GETENV (C のマクロ)
  • Py_GetExecPrefix (C の関数)
  • Py_GetExecPrefix()
  • Py_GetPath (C の関数)
  • Py_GetPath(), [1], [2]
  • Py_GetPlatform (C の関数)
  • Py_GetPrefix (C の関数)
  • Py_GetPrefix()
  • Py_GetProgramFullPath (C の関数)
  • Py_GetProgramFullPath()
  • Py_GetProgramName (C の関数)
  • Py_GetPythonHome (C の関数)
  • Py_GetVersion (C の関数)
  • Py_HashRandomizationFlag (C の変数)
  • Py_IgnoreEnvironmentFlag (C の変数)
  • Py_INCREF (C の関数)
  • Py_INCREF()
  • Py_Initialize (C の関数)
  • Py_Initialize(), [1], [2], [3]
  • Py_InitializeEx (C の関数)
  • Py_InspectFlag (C の変数)
  • Py_InteractiveFlag (C の変数)
  • Py_IsInitialized (C の関数)
  • Py_IsInitialized()
  • Py_IsolatedFlag (C の変数)
  • Py_LeaveRecursiveCall (C の関数)
  • Py_LegacyWindowsFSEncodingFlag (C の変数)
  • Py_LegacyWindowsStdioFlag (C の変数)
  • Py_Main (C の関数)
  • Py_MAX (C のマクロ)
  • Py_MEMBER_SIZE (C のマクロ)
  • Py_MIN (C のマクロ)
  • Py_mod_create (C の変数)
  • Py_mod_exec (C の変数)
  • Py_NewInterpreter (C の関数)
  • Py_None (C の変数)
  • Py_NoSiteFlag (C の変数)
  • Py_NotImplemented (C の変数)
  • Py_NoUserSiteDirectory (C の変数)
  • py_object (ctypes のクラス)
  • Py_OptimizeFlag (C の変数)
  • Py_PRINT_RAW
  • Py_QuietFlag (C の変数)
  • Py_REFCNT (C のマクロ)
  • Py_ReprEnter (C の関数)
  • Py_ReprLeave (C の関数)
  • Py_RETURN_FALSE (C のマクロ)
  • Py_RETURN_NONE (C のマクロ)
  • Py_RETURN_NOTIMPLEMENTED (C のマクロ)
  • Py_RETURN_RICHCOMPARE (C の関数)
  • Py_RETURN_TRUE (C のマクロ)
  • Py_SetPath (C の関数)
  • Py_SetPath()
  • Py_SetProgramName (C の関数)
  • Py_SetProgramName(), [1], [2], [3]
  • Py_SetPythonHome (C の関数)
  • Py_SetStandardStreamEncoding (C の関数)
  • Py_single_input (C の変数)
  • Py_SIZE (C のマクロ)
  • PY_SOURCE (imp モジュール)
  • PY_SSIZE_T_MAX
  • Py_STRINGIFY (C のマクロ)
  • Py_TPFLAGS_BASE_EXC_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_BASETYPE (組み込み変数)
  • Py_TPFLAGS_BYTES_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_DEFAULT (組み込み変数)
  • Py_TPFLAGS_DICT_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_HAVE_FINALIZE (組み込み変数)
  • Py_TPFLAGS_HAVE_GC (組み込み変数)
  • Py_TPFLAGS_HEAPTYPE (組み込み変数)
  • Py_TPFLAGS_LIST_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_LONG_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_READY (組み込み変数)
  • Py_TPFLAGS_READYING (組み込み変数)
  • Py_TPFLAGS_TUPLE_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_TYPE_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_UNICODE_SUBCLASS (組み込み変数)
  • Py_tracefunc (C のデータ型)
  • Py_True (C の変数)
  • Py_tss_NEEDS_INIT (C のマクロ)
  • Py_tss_t (C のデータ型)
  • Py_TYPE (C のマクロ)
  • Py_UCS1 (C のデータ型)
  • Py_UCS2 (C のデータ型)
  • Py_UCS4 (C のデータ型)
  • Py_UNBLOCK_THREADS (C のマクロ)
  • Py_UnbufferedStdioFlag (C の変数)
  • Py_UNICODE (C のデータ型)
  • Py_UNICODE_IS_HIGH_SURROGATE (C のマクロ)
  • Py_UNICODE_IS_LOW_SURROGATE (C のマクロ)
  • Py_UNICODE_IS_SURROGATE (C のマクロ)
  • Py_UNICODE_ISALNUM (C の関数)
  • Py_UNICODE_ISALPHA (C の関数)
  • Py_UNICODE_ISDECIMAL (C の関数)
  • Py_UNICODE_ISDIGIT (C の関数)
  • Py_UNICODE_ISLINEBREAK (C の関数)
  • Py_UNICODE_ISLOWER (C の関数)
  • Py_UNICODE_ISNUMERIC (C の関数)
  • Py_UNICODE_ISPRINTABLE (C の関数)
  • Py_UNICODE_ISSPACE (C の関数)
  • Py_UNICODE_ISTITLE (C の関数)
  • Py_UNICODE_ISUPPER (C の関数)
  • Py_UNICODE_JOIN_SURROGATES (C のマクロ)
  • Py_UNICODE_TODECIMAL (C の関数)
  • Py_UNICODE_TODIGIT (C の関数)
  • Py_UNICODE_TOLOWER (C の関数)
  • Py_UNICODE_TONUMERIC (C の関数)
  • Py_UNICODE_TOTITLE (C の関数)
  • Py_UNICODE_TOUPPER (C の関数)
  • Py_UNREACHABLE (C のマクロ)
  • Py_UNUSED (C のマクロ)
  • Py_VaBuildValue (C の関数)
  • Py_VerboseFlag (C の変数)
  • Py_VISIT (C の関数)
  • Py_XDECREF (C の関数)
  • Py_XDECREF()
  • Py_XINCREF (C の関数)
  • PyAnySet_Check (C の関数)
  • PyAnySet_CheckExact (C の関数)
  • PyArg_Parse (C の関数)
  • PyArg_ParseTuple (C の関数)
  • PyArg_ParseTuple()
  • PyArg_ParseTupleAndKeywords (C の関数)
  • PyArg_ParseTupleAndKeywords()
  • PyArg_UnpackTuple (C の関数)
  • PyArg_ValidateKeywordArguments (C の関数)
  • PyArg_VaParse (C の関数)
  • PyArg_VaParseTupleAndKeywords (C の関数)
  • PyASCIIObject (C のデータ型)
  • PyAsyncMethods (C のデータ型)
  • PyAsyncMethods.am_aiter (C のメンバ変数)
  • PyAsyncMethods.am_anext (C のメンバ変数)
  • PyAsyncMethods.am_await (C のメンバ変数)
  • PyBool_Check (C の関数)
  • PyBool_FromLong (C の関数)
  • PyBUF_ANY_CONTIGUOUS (C のマクロ)
  • PyBUF_C_CONTIGUOUS (C のマクロ)
  • PyBUF_CONTIG (C のマクロ)
  • PyBUF_CONTIG_RO (C のマクロ)
  • PyBUF_F_CONTIGUOUS (C のマクロ)
  • PyBUF_FORMAT (C のマクロ)
  • PyBUF_FULL (C のマクロ)
  • PyBUF_FULL_RO (C のマクロ)
  • PyBUF_INDIRECT (C のマクロ)
  • PyBUF_ND (C のマクロ), [1]
  • PyBUF_RECORDS (C のマクロ)
  • PyBUF_RECORDS_RO (C のマクロ)
  • PyBUF_SIMPLE (C のマクロ)
  • PyBUF_STRIDED (C のマクロ)
  • PyBUF_STRIDED_RO (C のマクロ)
  • PyBUF_STRIDES (C のマクロ)
  • PyBUF_WRITABLE (C のマクロ)
  • PyBuffer_FillContiguousStrides (C の関数)
  • PyBuffer_FillInfo (C の関数)
  • PyBuffer_IsContiguous (C の関数)
  • PyBuffer_Release (C の関数)
  • PyBuffer_SizeFromFormat (C の関数)
  • PyBuffer_ToContiguous (C の関数)
  • PyBufferProcs
    • (C のデータ型)
  • PyBufferProcs.bf_getbuffer (C のメンバ変数)
  • PyBufferProcs.bf_releasebuffer (C のメンバ変数)
  • PyByteArray_AS_STRING (C の関数)
  • PyByteArray_AsString (C の関数)
  • PyByteArray_Check (C の関数)
  • PyByteArray_CheckExact (C の関数)
  • PyByteArray_Concat (C の関数)
  • PyByteArray_FromObject (C の関数)
  • PyByteArray_FromStringAndSize (C の関数)
  • PyByteArray_GET_SIZE (C の関数)
  • PyByteArray_Resize (C の関数)
  • PyByteArray_Size (C の関数)
  • PyByteArray_Type (C の変数)
  • PyByteArrayObject (C のデータ型)
  • PyBytes_AS_STRING (C の関数)
  • PyBytes_AsString (C の関数)
  • PyBytes_AsStringAndSize (C の関数)
  • PyBytes_Check (C の関数)
  • PyBytes_CheckExact (C の関数)
  • PyBytes_Concat (C の関数)
  • PyBytes_ConcatAndDel (C の関数)
  • PyBytes_FromFormat (C の関数)
  • PyBytes_FromFormatV (C の関数)
  • PyBytes_FromObject (C の関数)
  • PyBytes_FromString (C の関数)
  • PyBytes_FromStringAndSize (C の関数)
  • PyBytes_GET_SIZE (C の関数)
  • PyBytes_Size (C の関数)
  • PyBytes_Type (C の変数)
  • PyBytesObject (C のデータ型)
  • PyCallable_Check (C の関数)
  • PyCallIter_Check (C の関数)
  • PyCallIter_New (C の関数)
  • PyCallIter_Type (C の変数)
  • PyCapsule (C のデータ型)
  • PyCapsule_CheckExact (C の関数)
  • PyCapsule_Destructor (C のデータ型)
  • PyCapsule_GetContext (C の関数)
  • PyCapsule_GetDestructor (C の関数)
  • PyCapsule_GetName (C の関数)
  • PyCapsule_GetPointer (C の関数)
  • PyCapsule_Import (C の関数)
  • PyCapsule_IsValid (C の関数)
  • PyCapsule_New (C の関数)
  • PyCapsule_SetContext (C の関数)
  • PyCapsule_SetDestructor (C の関数)
  • PyCapsule_SetName (C の関数)
  • PyCapsule_SetPointer (C の関数)
  • PyCell_Check (C の関数)
  • PyCell_GET (C の関数)
  • PyCell_Get (C の関数)
  • PyCell_New (C の関数)
  • PyCell_SET (C の関数)
  • PyCell_Set (C の関数)
  • PyCell_Type (C の変数)
  • PyCellObject (C のデータ型)
  • PyCFunction (C のデータ型)
  • PyCFunctionWithKeywords (C のデータ型)
  • PycInvalidationMode (py_compile のクラス)
  • pyclbr (モジュール)
  • PyCode_Check (C の関数)
  • PyCode_GetNumFree (C の関数)
  • PyCode_New (C の関数)
  • PyCode_NewEmpty (C の関数)
  • PyCode_Type (C の変数)
  • PyCodec_BackslashReplaceErrors (C の関数)
  • PyCodec_Decode (C の関数)
  • PyCodec_Decoder (C の関数)
  • PyCodec_Encode (C の関数)
  • PyCodec_Encoder (C の関数)
  • PyCodec_IgnoreErrors (C の関数)
  • PyCodec_IncrementalDecoder (C の関数)
  • PyCodec_IncrementalEncoder (C の関数)
  • PyCodec_KnownEncoding (C の関数)
  • PyCodec_LookupError (C の関数)
  • PyCodec_NameReplaceErrors (C の関数)
  • PyCodec_Register (C の関数)
  • PyCodec_RegisterError (C の関数)
  • PyCodec_ReplaceErrors (C の関数)
  • PyCodec_StreamReader (C の関数)
  • PyCodec_StreamWriter (C の関数)
  • PyCodec_StrictErrors (C の関数)
  • PyCodec_XMLCharRefReplaceErrors (C の関数)
  • PyCodeObject (C のデータ型)
  • PyCompactUnicodeObject (C のデータ型)
  • PyCompileError
  • PyCompilerFlags (C のデータ型)
  • PyComplex_AsCComplex (C の関数)
  • PyComplex_Check (C の関数)
  • PyComplex_CheckExact (C の関数)
  • PyComplex_FromCComplex (C の関数)
  • PyComplex_FromDoubles (C の関数)
  • PyComplex_ImagAsDouble (C の関数)
  • PyComplex_RealAsDouble (C の関数)
  • PyComplex_Type (C の変数)
  • PyComplexObject (C のデータ型)
  • PyContext (C のデータ型)
  • PyContext_CheckExact (C の関数)
  • PyContext_ClearFreeList (C の関数)
  • PyContext_Copy (C の関数)
  • PyContext_CopyCurrent (C の関数)
  • PyContext_Enter (C の関数)
  • PyContext_Exit (C の関数)
  • PyContext_New (C の関数)
  • PyContext_Type (C の変数)
  • PyContextToken (C のデータ型)
  • PyContextToken_CheckExact (C の関数)
  • PyContextToken_Type (C の変数)
  • PyContextVar (C のデータ型)
  • PyContextVar_CheckExact (C の関数)
  • PyContextVar_Get (C の関数)
  • PyContextVar_New (C の関数)
  • PyContextVar_Reset (C の関数)
  • PyContextVar_Set (C の関数)
  • PyContextVar_Type (C の変数)
  • PyCoro_CheckExact (C の関数)
  • PyCoro_New (C の関数)
  • PyCoro_Type (C の変数)
  • PyCoroObject (C のデータ型)
  • PyDate_Check (C の関数)
  • PyDate_CheckExact (C の関数)
  • PyDate_FromDate (C の関数)
  • PyDate_FromTimestamp (C の関数)
  • PyDateTime_Check (C の関数)
  • PyDateTime_CheckExact (C の関数)
  • PyDateTime_DATE_GET_HOUR (C の関数)
  • PyDateTime_DATE_GET_MICROSECOND (C の関数)
  • PyDateTime_DATE_GET_MINUTE (C の関数)
  • PyDateTime_DATE_GET_SECOND (C の関数)
  • PyDateTime_DELTA_GET_DAYS (C の関数)
  • PyDateTime_DELTA_GET_MICROSECONDS (C の関数)
  • PyDateTime_DELTA_GET_SECONDS (C の関数)
  • PyDateTime_FromDateAndTime (C の関数)
  • PyDateTime_FromTimestamp (C の関数)
  • PyDateTime_GET_DAY (C の関数)
  • PyDateTime_GET_MONTH (C の関数)
  • PyDateTime_GET_YEAR (C の関数)
  • PyDateTime_TIME_GET_HOUR (C の関数)
  • PyDateTime_TIME_GET_MICROSECOND (C の関数)
  • PyDateTime_TIME_GET_MINUTE (C の関数)
  • PyDateTime_TIME_GET_SECOND (C の関数)
  • PyDateTime_TimeZone_UTC (C の変数)
  • PyDelta_Check (C の関数)
  • PyDelta_CheckExact (C の関数)
  • PyDelta_FromDSU (C の関数)
  • PyDescr_IsData (C の関数)
  • PyDescr_NewClassMethod (C の関数)
  • PyDescr_NewGetSet (C の関数)
  • PyDescr_NewMember (C の関数)
  • PyDescr_NewMethod (C の関数)
  • PyDescr_NewWrapper (C の関数)
  • PyDict_Check (C の関数)
  • PyDict_CheckExact (C の関数)
  • PyDict_Clear (C の関数)
  • PyDict_ClearFreeList (C の関数)
  • PyDict_Contains (C の関数)
  • PyDict_Copy (C の関数)
  • PyDict_DelItem (C の関数)
  • PyDict_DelItemString (C の関数)
  • PyDict_GetItem (C の関数)
  • PyDict_GetItemString (C の関数)
  • PyDict_GetItemWithError (C の関数)
  • PyDict_Items (C の関数)
  • PyDict_Keys (C の関数)
  • PyDict_Merge (C の関数)
  • PyDict_MergeFromSeq2 (C の関数)
  • PyDict_New (C の関数)
  • PyDict_Next (C の関数)
  • PyDict_SetDefault (C の関数)
  • PyDict_SetItem (C の関数)
  • PyDict_SetItemString (C の関数)
  • PyDict_Size (C の関数)
  • PyDict_Type (C の変数)
  • PyDict_Update (C の関数)
  • PyDict_Values (C の関数)
  • PyDictObject (C のデータ型)
  • PyDictProxy_New (C の関数)
  • PyDLL (ctypes のクラス)
  • pydoc (モジュール)
  • PyErr_BadArgument (C の関数)
  • PyErr_BadInternalCall (C の関数)
  • PyErr_CheckSignals (C の関数)
  • PyErr_Clear (C の関数)
  • PyErr_Clear(), [1]
  • PyErr_ExceptionMatches (C の関数)
  • PyErr_ExceptionMatches()
  • PyErr_Fetch (C の関数)
  • PyErr_Fetch()
  • PyErr_Format (C の関数)
  • PyErr_FormatV (C の関数)
  • PyErr_GetExcInfo (C の関数)
  • PyErr_GivenExceptionMatches (C の関数)
  • PyErr_NewException (C の関数)
  • PyErr_NewExceptionWithDoc (C の関数)
  • PyErr_NoMemory (C の関数)
  • PyErr_NormalizeException (C の関数)
  • PyErr_Occurred (C の関数)
  • PyErr_Occurred()
  • PyErr_Print (C の関数)
  • PyErr_PrintEx (C の関数)
  • PyErr_ResourceWarning (C の関数)
  • PyErr_Restore (C の関数)
  • PyErr_Restore()
  • PyErr_SetExcFromWindowsErr (C の関数)
  • PyErr_SetExcFromWindowsErrWithFilename (C の関数)
  • PyErr_SetExcFromWindowsErrWithFilenameObject (C の関数)
  • PyErr_SetExcFromWindowsErrWithFilenameObjects (C の関数)
  • PyErr_SetExcInfo (C の関数)
  • PyErr_SetFromErrno (C の関数)
  • PyErr_SetFromErrnoWithFilename (C の関数)
  • PyErr_SetFromErrnoWithFilenameObject (C の関数)
  • PyErr_SetFromErrnoWithFilenameObjects (C の関数)
  • PyErr_SetFromWindowsErr (C の関数)
  • PyErr_SetFromWindowsErrWithFilename (C の関数)
  • PyErr_SetImportError (C の関数)
  • PyErr_SetImportErrorSubclass (C の関数)
  • PyErr_SetInterrupt (C の関数)
  • PyErr_SetNone (C の関数)
  • PyErr_SetObject (C の関数)
  • PyErr_SetString (C の関数)
  • PyErr_SetString()
  • PyErr_SyntaxLocation (C の関数)
  • PyErr_SyntaxLocationEx (C の関数)
  • PyErr_SyntaxLocationObject (C の関数)
  • PyErr_WarnEx (C の関数)
  • PyErr_WarnExplicit (C の関数)
  • PyErr_WarnExplicitObject (C の関数)
  • PyErr_WarnFormat (C の関数)
  • PyErr_WriteUnraisable (C の関数)
  • PyEval_AcquireLock (C の関数)
  • PyEval_AcquireThread (C の関数)
  • PyEval_AcquireThread()
  • PyEval_EvalCode (C の関数)
  • PyEval_EvalCodeEx (C の関数)
  • PyEval_EvalFrame (C の関数)
  • PyEval_EvalFrameEx (C の関数)
  • PyEval_GetBuiltins (C の関数)
  • PyEval_GetFrame (C の関数)
  • PyEval_GetFuncDesc (C の関数)
  • PyEval_GetFuncName (C の関数)
  • PyEval_GetGlobals (C の関数)
  • PyEval_GetLocals (C の関数)
  • PyEval_InitThreads (C の関数)
  • PyEval_InitThreads()
  • PyEval_MergeCompilerFlags (C の関数)
  • PyEval_ReInitThreads (C の関数)
  • PyEval_ReleaseLock (C の関数)
  • PyEval_ReleaseThread (C の関数)
  • PyEval_ReleaseThread()
  • PyEval_RestoreThread (C の関数)
  • PyEval_RestoreThread(), [1]
  • PyEval_SaveThread (C の関数)
  • PyEval_SaveThread(), [1]
  • PyEval_SetProfile (C の関数)
  • PyEval_SetTrace (C の関数)
  • PyEval_ThreadsInitialized (C の関数)
  • PyExc_ArithmeticError
  • PyExc_AssertionError
  • PyExc_AttributeError
  • PyExc_BaseException
  • PyExc_BlockingIOError
  • PyExc_BrokenPipeError
  • PyExc_BufferError
  • PyExc_BytesWarning
  • PyExc_ChildProcessError
  • PyExc_ConnectionAbortedError
  • PyExc_ConnectionError
  • PyExc_ConnectionRefusedError
  • PyExc_ConnectionResetError
  • PyExc_DeprecationWarning
  • PyExc_EnvironmentError
  • PyExc_EOFError
  • PyExc_Exception
  • PyExc_FileExistsError
  • PyExc_FileNotFoundError
  • PyExc_FloatingPointError
  • PyExc_FutureWarning
  • PyExc_GeneratorExit
  • PyExc_ImportError
  • PyExc_ImportWarning
  • PyExc_IndentationError
  • PyExc_IndexError
  • PyExc_InterruptedError
  • PyExc_IOError
  • PyExc_IsADirectoryError
  • PyExc_KeyboardInterrupt
  • PyExc_KeyError
  • 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
  • PyException_GetCause (C の関数)
  • PyException_GetContext (C の関数)
  • PyException_GetTraceback (C の関数)
  • PyException_SetCause (C の関数)
  • PyException_SetContext (C の関数)
  • PyException_SetTraceback (C の関数)
  • pyexpat
    • モジュール
  • PyFile_FromFd (C の関数)
  • PyFile_GetLine (C の関数)
  • PyFile_WriteObject (C の関数)
  • PyFile_WriteString (C の関数)
  • PyFloat_AS_DOUBLE (C の関数)
  • PyFloat_AsDouble (C の関数)
  • PyFloat_Check (C の関数)
  • PyFloat_CheckExact (C の関数)
  • PyFloat_ClearFreeList (C の関数)
  • PyFloat_FromDouble (C の関数)
  • PyFloat_FromString (C の関数)
  • PyFloat_GetInfo (C の関数)
  • PyFloat_GetMax (C の関数)
  • PyFloat_GetMin (C の関数)
  • PyFloat_Type (C の変数)
  • PyFloatObject (C のデータ型)
  • PyFrame_GetLineNumber (C の関数)
  • PyFrameObject (C のデータ型)
  • PyFrozenSet_Check (C の関数)
  • PyFrozenSet_CheckExact (C の関数)
  • PyFrozenSet_New (C の関数)
  • PyFrozenSet_Type (C の変数)
  • PyFunction_Check (C の関数)
  • PyFunction_GetAnnotations (C の関数)
  • PyFunction_GetClosure (C の関数)
  • PyFunction_GetCode (C の関数)
  • PyFunction_GetDefaults (C の関数)
  • PyFunction_GetGlobals (C の関数)
  • PyFunction_GetModule (C の関数)
  • PyFunction_New (C の関数)
  • PyFunction_NewWithQualName (C の関数)
  • PyFunction_SetAnnotations (C の関数)
  • PyFunction_SetClosure (C の関数)
  • PyFunction_SetDefaults (C の関数)
  • PyFunction_Type (C の変数)
  • PyFunctionObject (C のデータ型)
  • PYFUNCTYPE() (ctypes モジュール)
  • PyGen_Check (C の関数)
  • PyGen_CheckExact (C の関数)
  • PyGen_New (C の関数)
  • PyGen_NewWithQualName (C の関数)
  • PyGen_Type (C の変数)
  • PyGenObject (C のデータ型)
  • PyGetSetDef (C のデータ型)
  • PyGILState_Check (C の関数)
  • PyGILState_Ensure (C の関数)
  • PyGILState_GetThisThreadState (C の関数)
  • PyGILState_Release (C の関数)
  • PyImport_AddModule (C の関数)
  • PyImport_AddModuleObject (C の関数)
  • PyImport_AppendInittab (C の関数)
  • PyImport_Cleanup (C の関数)
  • PyImport_ExecCodeModule (C の関数)
  • PyImport_ExecCodeModuleEx (C の関数)
  • PyImport_ExecCodeModuleObject (C の関数)
  • PyImport_ExecCodeModuleWithPathnames (C の関数)
  • PyImport_ExtendInittab (C の関数)
  • PyImport_FrozenModules (C の変数)
  • PyImport_GetImporter (C の関数)
  • PyImport_GetMagicNumber (C の関数)
  • PyImport_GetMagicTag (C の関数)
  • PyImport_GetModule (C の関数)
  • PyImport_GetModuleDict (C の関数)
  • PyImport_Import (C の関数)
  • PyImport_ImportFrozenModule (C の関数)
  • PyImport_ImportFrozenModuleObject (C の関数)
  • PyImport_ImportModule (C の関数)
  • PyImport_ImportModuleEx (C の関数)
  • PyImport_ImportModuleLevel (C の関数)
  • PyImport_ImportModuleLevelObject (C の関数)
  • PyImport_ImportModuleNoBlock (C の関数)
  • PyImport_ReloadModule (C の関数)
  • PyIndex_Check (C の関数)
  • PyInit_modulename (C の関数)
  • PyInstanceMethod_Check (C の関数)
  • PyInstanceMethod_Function (C の関数)
  • PyInstanceMethod_GET_FUNCTION (C の関数)
  • PyInstanceMethod_New (C の関数)
  • PyInstanceMethod_Type (C の変数)
  • PyInterpreterState (C のデータ型)
  • PyInterpreterState_Clear (C の関数)
  • PyInterpreterState_Delete (C の関数)
  • PyInterpreterState_GetID (C の関数)
  • PyInterpreterState_Head (C の関数)
  • PyInterpreterState_New (C の関数)
  • PyInterpreterState_Next (C の関数)
  • PyInterpreterState_ThreadHead (C の関数)
  • PyIter_Check (C の関数)
  • PyIter_Next (C の関数)
  • PyList_Append (C の関数)
  • PyList_AsTuple (C の関数)
  • PyList_Check (C の関数)
  • PyList_CheckExact (C の関数)
  • PyList_ClearFreeList (C の関数)
  • PyList_GET_ITEM (C の関数)
  • PyList_GET_SIZE (C の関数)
  • PyList_GetItem (C の関数)
  • PyList_GetItem()
  • PyList_GetSlice (C の関数)
  • PyList_Insert (C の関数)
  • PyList_New (C の関数)
  • PyList_Reverse (C の関数)
  • PyList_SET_ITEM (C の関数)
  • PyList_SetItem (C の関数)
  • PyList_SetItem()
  • PyList_SetSlice (C の関数)
  • PyList_Size (C の関数)
  • PyList_Sort (C の関数)
  • PyList_Type (C の変数)
  • PyListObject (C のデータ型)
  • PyLong_AsDouble (C の関数)
  • PyLong_AsLong (C の関数)
  • PyLong_AsLongAndOverflow (C の関数)
  • PyLong_AsLongLong (C の関数)
  • PyLong_AsLongLongAndOverflow (C の関数)
  • PyLong_AsSize_t (C の関数)
  • PyLong_AsSsize_t (C の関数)
  • PyLong_AsUnsignedLong (C の関数)
  • PyLong_AsUnsignedLongLong (C の関数)
  • PyLong_AsUnsignedLongLongMask (C の関数)
  • PyLong_AsUnsignedLongMask (C の関数)
  • PyLong_AsVoidPtr (C の関数)
  • PyLong_Check (C の関数)
  • PyLong_CheckExact (C の関数)
  • PyLong_FromDouble (C の関数)
  • PyLong_FromLong (C の関数)
  • PyLong_FromLongLong (C の関数)
  • PyLong_FromSize_t (C の関数)
  • PyLong_FromSsize_t (C の関数)
  • PyLong_FromString (C の関数)
  • PyLong_FromUnicode (C の関数)
  • PyLong_FromUnicodeObject (C の関数)
  • PyLong_FromUnsignedLong (C の関数)
  • PyLong_FromUnsignedLongLong (C の関数)
  • PyLong_FromVoidPtr (C の関数)
  • PyLong_Type (C の変数)
  • PyLongObject (C のデータ型)
  • PyMapping_Check (C の関数)
  • PyMapping_DelItem (C の関数)
  • PyMapping_DelItemString (C の関数)
  • PyMapping_GetItemString (C の関数)
  • PyMapping_HasKey (C の関数)
  • PyMapping_HasKeyString (C の関数)
  • PyMapping_Items (C の関数)
  • PyMapping_Keys (C の関数)
  • PyMapping_Length (C の関数)
  • PyMapping_SetItemString (C の関数)
  • PyMapping_Size (C の関数)
  • PyMapping_Values (C の関数)
  • PyMappingMethods (C のデータ型)
  • PyMappingMethods.mp_ass_subscript (C のメンバ変数)
  • PyMappingMethods.mp_length (C のメンバ変数)
  • PyMappingMethods.mp_subscript (C のメンバ変数)
  • PyMarshal_ReadLastObjectFromFile (C の関数)
  • PyMarshal_ReadLongFromFile (C の関数)
  • PyMarshal_ReadObjectFromFile (C の関数)
  • PyMarshal_ReadObjectFromString (C の関数)
  • PyMarshal_ReadShortFromFile (C の関数)
  • PyMarshal_WriteLongToFile (C の関数)
  • PyMarshal_WriteObjectToFile (C の関数)
  • PyMarshal_WriteObjectToString (C の関数)
  • PyMem_Calloc (C の関数)
  • PyMem_Del (C の関数)
  • PYMEM_DOMAIN_MEM (C の変数)
  • PYMEM_DOMAIN_OBJ (C の変数)
  • PYMEM_DOMAIN_RAW (C の変数)
  • PyMem_Free (C の関数)
  • PyMem_GetAllocator (C の関数)
  • PyMem_Malloc (C の関数)
  • PyMem_New (C の関数)
  • PyMem_RawCalloc (C の関数)
  • PyMem_RawFree (C の関数)
  • PyMem_RawMalloc (C の関数)
  • PyMem_RawRealloc (C の関数)
  • PyMem_Realloc (C の関数)
  • PyMem_Resize (C の関数)
  • PyMem_SetAllocator (C の関数)
  • PyMem_SetupDebugHooks (C の関数)
  • PyMemAllocatorDomain (C のデータ型)
  • PyMemAllocatorEx (C のデータ型)
  • PyMemberDef (C のデータ型)
  • PyMemoryView_Check (C の関数)
  • PyMemoryView_FromBuffer (C の関数)
  • PyMemoryView_FromMemory (C の関数)
  • PyMemoryView_FromObject (C の関数)
  • PyMemoryView_GET_BASE (C の関数)
  • PyMemoryView_GET_BUFFER (C の関数)
  • PyMemoryView_GetContiguous (C の関数)
  • PyMethod_Check (C の関数)
  • PyMethod_ClearFreeList (C の関数)
  • PyMethod_Function (C の関数)
  • PyMethod_GET_FUNCTION (C の関数)
  • PyMethod_GET_SELF (C の関数)
  • PyMethod_New (C の関数)
  • PyMethod_Self (C の関数)
  • PyMethod_Type (C の変数)
  • PyMethodDef (C のデータ型)
  • PyModule_AddFunctions (C の関数)
  • PyModule_AddIntConstant (C の関数)
  • PyModule_AddIntMacro (C の関数)
  • PyModule_AddObject (C の関数)
  • PyModule_AddStringConstant (C の関数)
  • PyModule_AddStringMacro (C の関数)
  • PyModule_Check (C の関数)
  • PyModule_CheckExact (C の関数)
  • PyModule_Create (C の関数)
  • PyModule_Create2 (C の関数)
  • PyModule_ExecDef (C の関数)
  • PyModule_FromDefAndSpec (C の関数)
  • PyModule_FromDefAndSpec2 (C の関数)
  • PyModule_GetDef (C の関数)
  • PyModule_GetDict (C の関数)
  • PyModule_GetFilename (C の関数)
  • PyModule_GetFilenameObject (C の関数)
  • PyModule_GetName (C の関数)
  • PyModule_GetNameObject (C の関数)
  • PyModule_GetState (C の関数)
  • PyModule_New (C の関数)
  • PyModule_NewObject (C の関数)
  • PyModule_SetDocString (C の関数)
  • PyModule_Type (C の変数)
  • PyModuleDef (C のデータ型)
  • PyModuleDef.m_base (C のメンバ変数)
  • PyModuleDef.m_clear (C のメンバ変数)
  • PyModuleDef.m_doc (C のメンバ変数)
  • PyModuleDef.m_free (C のメンバ変数)
  • PyModuleDef.m_methods (C のメンバ変数)
  • PyModuleDef.m_name (C のメンバ変数)
  • PyModuleDef.m_reload (C のメンバ変数)
  • PyModuleDef.m_size (C のメンバ変数)
  • PyModuleDef.m_slots (C のメンバ変数)
  • PyModuleDef.m_traverse (C のメンバ変数)
  • PyModuleDef_Init (C の関数)
  • PyModuleDef_Slot (C のデータ型)
  • PyModuleDef_Slot.slot (C のメンバ変数)
  • PyModuleDef_Slot.value (C のメンバ変数)
  • PyNumber_Absolute (C の関数)
  • PyNumber_Add (C の関数)
  • PyNumber_And (C の関数)
  • PyNumber_AsSsize_t (C の関数)
  • PyNumber_Check (C の関数)
  • PyNumber_Divmod (C の関数)
  • PyNumber_Float (C の関数)
  • PyNumber_FloorDivide (C の関数)
  • PyNumber_Index (C の関数)
  • PyNumber_InPlaceAdd (C の関数)
  • PyNumber_InPlaceAnd (C の関数)
  • PyNumber_InPlaceFloorDivide (C の関数)
  • PyNumber_InPlaceLshift (C の関数)
  • PyNumber_InPlaceMatrixMultiply (C の関数)
  • PyNumber_InPlaceMultiply (C の関数)
  • PyNumber_InPlaceOr (C の関数)
  • PyNumber_InPlacePower (C の関数)
  • PyNumber_InPlaceRemainder (C の関数)
  • PyNumber_InPlaceRshift (C の関数)
  • PyNumber_InPlaceSubtract (C の関数)
  • PyNumber_InPlaceTrueDivide (C の関数)
  • PyNumber_InPlaceXor (C の関数)
  • PyNumber_Invert (C の関数)
  • PyNumber_Long (C の関数)
  • PyNumber_Lshift (C の関数)
  • PyNumber_MatrixMultiply (C の関数)
  • PyNumber_Multiply (C の関数)
  • PyNumber_Negative (C の関数)
  • PyNumber_Or (C の関数)
  • PyNumber_Positive (C の関数)
  • PyNumber_Power (C の関数)
  • PyNumber_Remainder (C の関数)
  • PyNumber_Rshift (C の関数)
  • PyNumber_Subtract (C の関数)
  • PyNumber_ToBase (C の関数)
  • PyNumber_TrueDivide (C の関数)
  • PyNumber_Xor (C の関数)
  • PyNumberMethods (C のデータ型)
  • PyObject (C のデータ型)
  • PyObject._ob_next (C のメンバ変数)
  • PyObject._ob_prev (C のメンバ変数)
  • PyObject.ob_refcnt (C のメンバ変数)
  • PyObject.ob_type (C のメンバ変数)
  • PyObject_AsCharBuffer (C の関数)
  • PyObject_ASCII (C の関数)
  • PyObject_AsFileDescriptor (C の関数)
  • PyObject_AsReadBuffer (C の関数)
  • PyObject_AsWriteBuffer (C の関数)
  • PyObject_Bytes (C の関数)
  • PyObject_Call (C の関数)
  • PyObject_CallFunction (C の関数)
  • PyObject_CallFunctionObjArgs (C の関数)
  • PyObject_CallMethod (C の関数)
  • PyObject_CallMethodObjArgs (C の関数)
  • PyObject_CallObject (C の関数)
  • PyObject_CallObject()
  • PyObject_Calloc (C の関数)
  • PyObject_CheckBuffer (C の関数)
  • PyObject_CheckReadBuffer (C の関数)
  • PyObject_Del (C の関数)
  • PyObject_DelAttr (C の関数)
  • PyObject_DelAttrString (C の関数)
  • PyObject_DelItem (C の関数)
  • PyObject_Dir (C の関数)
  • PyObject_Free (C の関数)
  • PyObject_GC_Del (C の関数)
  • PyObject_GC_New (C の関数)
  • PyObject_GC_NewVar (C の関数)
  • PyObject_GC_Resize (C の関数)
  • PyObject_GC_Track (C の関数)
  • PyObject_GC_UnTrack (C の関数)
  • PyObject_GenericGetAttr (C の関数)
  • PyObject_GenericGetDict (C の関数)
  • PyObject_GenericSetAttr (C の関数)
  • PyObject_GenericSetDict (C の関数)
  • PyObject_GetArenaAllocator (C の関数)
  • PyObject_GetAttr (C の関数)
  • PyObject_GetAttrString (C の関数)
  • PyObject_GetBuffer (C の関数)
  • PyObject_GetItem (C の関数)
  • PyObject_GetIter (C の関数)
  • PyObject_HasAttr (C の関数)
  • PyObject_HasAttrString (C の関数)
  • PyObject_Hash (C の関数)
  • PyObject_HashNotImplemented (C の関数)
  • PyObject_HEAD (C のマクロ)
  • PyObject_HEAD_INIT (C のマクロ)
  • PyObject_Init (C の関数)
  • PyObject_InitVar (C の関数)
  • PyObject_IsInstance (C の関数)
  • PyObject_IsSubclass (C の関数)
  • PyObject_IsTrue (C の関数)
  • PyObject_Length (C の関数)
  • PyObject_LengthHint (C の関数)
  • PyObject_Malloc (C の関数)
  • PyObject_New (C の関数)
  • PyObject_NewVar (C の関数)
  • PyObject_Not (C の関数)
  • PyObject_Print (C の関数)
  • PyObject_Realloc (C の関数)
  • PyObject_Repr (C の関数)
  • PyObject_RichCompare (C の関数)
  • PyObject_RichCompareBool (C の関数)
  • PyObject_SetArenaAllocator (C の関数)
  • PyObject_SetAttr (C の関数)
  • PyObject_SetAttrString (C の関数)
  • PyObject_SetItem (C の関数)
  • PyObject_Size (C の関数)
  • PyObject_Str (C の関数)
  • PyObject_Type (C の関数)
  • PyObject_TypeCheck (C の関数)
  • PyObject_VAR_HEAD (C のマクロ)
  • PyObjectArenaAllocator (C のデータ型)
  • PyOS_AfterFork (C の関数)
  • PyOS_AfterFork_Child (C の関数)
  • PyOS_AfterFork_Parent (C の関数)
  • PyOS_BeforeFork (C の関数)
  • PyOS_CheckStack (C の関数)
  • PyOS_double_to_string (C の関数)
  • PyOS_FSPath (C の関数)
  • PyOS_getsig (C の関数)
  • PyOS_InputHook (C の変数)
  • PyOS_ReadlineFunctionPointer (C の変数)
  • PyOS_setsig (C の関数)
  • PyOS_snprintf (C の関数)
  • PyOS_stricmp (C の関数)
  • PyOS_string_to_double (C の関数)
  • PyOS_strnicmp (C の関数)
  • PyOS_vsnprintf (C の関数)
  • PyParser_SimpleParseFile (C の関数)
  • PyParser_SimpleParseFileFlags (C の関数)
  • PyParser_SimpleParseString (C の関数)
  • PyParser_SimpleParseStringFlags (C の関数)
  • PyParser_SimpleParseStringFlagsFilename (C の関数)
  • PyPI
    • (see Python Package Index (PyPI))
  • PyProperty_Type (C の変数)
  • PyRun_AnyFile (C の関数)
  • PyRun_AnyFileEx (C の関数)
  • PyRun_AnyFileExFlags (C の関数)
  • PyRun_AnyFileFlags (C の関数)
  • PyRun_File (C の関数)
  • PyRun_FileEx (C の関数)
  • PyRun_FileExFlags (C の関数)
  • PyRun_FileFlags (C の関数)
  • PyRun_InteractiveLoop (C の関数)
  • PyRun_InteractiveLoopFlags (C の関数)
  • PyRun_InteractiveOne (C の関数)
  • PyRun_InteractiveOneFlags (C の関数)
  • PyRun_SimpleFile (C の関数)
  • PyRun_SimpleFileEx (C の関数)
  • PyRun_SimpleFileExFlags (C の関数)
  • PyRun_SimpleString (C の関数)
  • PyRun_SimpleStringFlags (C の関数)
  • PyRun_String (C の関数)
  • PyRun_StringFlags (C の関数)
  • PySeqIter_Check (C の関数)
  • PySeqIter_New (C の関数)
  • PySeqIter_Type (C の変数)
  • PySequence_Check (C の関数)
  • PySequence_Concat (C の関数)
  • PySequence_Contains (C の関数)
  • PySequence_Count (C の関数)
  • PySequence_DelItem (C の関数)
  • PySequence_DelSlice (C の関数)
  • PySequence_Fast (C の関数)
  • PySequence_Fast_GET_ITEM (C の関数)
  • PySequence_Fast_GET_SIZE (C の関数)
  • PySequence_Fast_ITEMS (C の関数)
  • PySequence_GetItem (C の関数)
  • PySequence_GetItem()
  • PySequence_GetSlice (C の関数)
  • PySequence_Index (C の関数)
  • PySequence_InPlaceConcat (C の関数)
  • PySequence_InPlaceRepeat (C の関数)
  • PySequence_ITEM (C の関数)
  • PySequence_Length (C の関数)
  • PySequence_List (C の関数)
  • PySequence_Repeat (C の関数)
  • PySequence_SetItem (C の関数)
  • PySequence_SetSlice (C の関数)
  • PySequence_Size (C の関数)
  • PySequence_Tuple (C の関数)
  • PySequenceMethods (C のデータ型)
  • PySequenceMethods.sq_ass_item (C のメンバ変数)
  • PySequenceMethods.sq_concat (C のメンバ変数)
  • PySequenceMethods.sq_contains (C のメンバ変数)
  • PySequenceMethods.sq_inplace_concat (C のメンバ変数)
  • PySequenceMethods.sq_inplace_repeat (C のメンバ変数)
  • PySequenceMethods.sq_item (C のメンバ変数)
  • PySequenceMethods.sq_length (C のメンバ変数)
  • PySequenceMethods.sq_repeat (C のメンバ変数)
  • PySet_Add (C の関数)
  • PySet_Check (C の関数)
  • PySet_Clear (C の関数)
  • PySet_ClearFreeList (C の関数)
  • PySet_Contains (C の関数)
  • PySet_Discard (C の関数)
  • PySet_GET_SIZE (C の関数)
  • PySet_New (C の関数)
  • PySet_Pop (C の関数)
  • PySet_Size (C の関数)
  • PySet_Type (C の変数)
  • PySetObject (C のデータ型)
  • PySignal_SetWakeupFd (C の関数)
  • PySlice_AdjustIndices (C の関数)
  • PySlice_Check (C の関数)
  • PySlice_GetIndices (C の関数)
  • PySlice_GetIndicesEx (C の関数)
  • PySlice_New (C の関数)
  • PySlice_Type (C の変数)
  • PySlice_Unpack (C の関数)
  • PyState_AddModule (C の関数)
  • PyState_FindModule (C の関数)
  • PyState_RemoveModule (C の関数)
  • PyStructSequence_Desc (C のデータ型)
  • PyStructSequence_Field (C のデータ型)
  • PyStructSequence_GET_ITEM (C の関数)
  • PyStructSequence_GetItem (C の関数)
  • PyStructSequence_InitType (C の関数)
  • PyStructSequence_InitType2 (C の関数)
  • PyStructSequence_New (C の関数)
  • PyStructSequence_NewType (C の関数)
  • PyStructSequence_SET_ITEM (C の関数)
  • PyStructSequence_SetItem (C の関数)
  • PyStructSequence_UnnamedField (C の変数)
  • PySys_AddWarnOption (C の関数)
  • PySys_AddWarnOptionUnicode (C の関数)
  • PySys_AddXOption (C の関数)
  • PySys_FormatStderr (C の関数)
  • PySys_FormatStdout (C の関数)
  • PySys_GetObject (C の関数)
  • PySys_GetXOptions (C の関数)
  • PySys_ResetWarnOptions (C の関数)
  • PySys_SetArgv (C の関数)
  • PySys_SetArgv()
  • PySys_SetArgvEx (C の関数)
  • PySys_SetArgvEx(), [1]
  • PySys_SetObject (C の関数)
  • PySys_SetPath (C の関数)
  • PySys_WriteStderr (C の関数)
  • PySys_WriteStdout (C の関数)
  • Python 3000
  • Python Editor
  • Python Enhancement Proposals
    • PEP 0342, [1]
    • PEP 1
    • PEP 100
    • PEP 11, [1], [2], [3], [4]
    • PEP 205, [1]
    • PEP 207
    • PEP 208
    • PEP 217
    • PEP 218, [1], [2]
    • PEP 227, [1], [2]
    • PEP 229, [1]
    • PEP 230
    • PEP 232
    • PEP 234
    • PEP 235
    • PEP 236, [1]
    • PEP 237, [1], [2], [3], [4], [5], [6]
    • PEP 238, [1], [2], [3], [4], [5], [6]
    • PEP 241
    • PEP 243
    • PEP 247
    • PEP 249, [1], [2], [3]
    • PEP 252, [1]
    • PEP 253, [1], [2], [3], [4]
    • PEP 255, [1], [2], [3], [4], [5]
    • PEP 261, [1]
    • PEP 263, [1], [2], [3], [4], [5]
    • PEP 264
    • PEP 273, [1], [2]
    • PEP 274
    • PEP 275
    • PEP 277
    • PEP 278, [1]
    • PEP 279
    • PEP 282, [1], [2], [3]
    • PEP 285, [1]
    • PEP 288
    • PEP 289, [1], [2]
    • PEP 292, [1]
    • PEP 293
    • PEP 3000
    • PEP 301, [1]
    • PEP 302, [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]
    • PEP 305, [1]
    • PEP 307, [1], [2], [3]
    • PEP 308, [1], [2]
    • PEP 309
    • PEP 3100
    • PEP 3101, [1], [2], [3], [4], [5]
    • PEP 3102
    • PEP 3104, [1]
    • PEP 3105, [1], [2], [3]
    • PEP 3106
    • PEP 3107, [1], [2], [3], [4]
    • PEP 3108, [1], [2]
    • PEP 3109, [1]
    • PEP 3110, [1], [2]
    • PEP 3111
    • PEP 3112, [1]
    • PEP 3113
    • PEP 3114
    • PEP 3115, [1], [2], [3], [4]
    • PEP 3116, [1], [2]
    • PEP 3118, [1], [2], [3], [4], [5]
    • PEP 3119, [1], [2], [3], [4], [5]
    • PEP 3120, [1], [2]
    • PEP 3121, [1], [2]
    • PEP 3123
    • PEP 3127
    • PEP 3129, [1]
    • PEP 3131, [1], [2]
    • PEP 3132, [1]
    • PEP 3134, [1], [2]
    • PEP 3135, [1]
    • PEP 3137
    • PEP 3138
    • PEP 314, [1]
    • PEP 3141, [1], [2]
    • PEP 3144
    • PEP 3147, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21]
    • PEP 3148, [1]
    • PEP 3149, [1]
    • PEP 3151, [1], [2], [3], [4], [5]
    • PEP 3153
    • PEP 3154, [1], [2]
    • PEP 3155, [1]
    • PEP 3156, [1], [2], [3], [4]
    • PEP 318, [1], [2], [3]
    • PEP 322, [1]
    • PEP 324, [1]
    • PEP 325
    • PEP 327
    • PEP 328, [1], [2], [3], [4], [5], [6], [7], [8], [9]
    • PEP 331
    • PEP 333, [1]
    • PEP 3333, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]
    • PEP 338, [1], [2], [3]
    • PEP 339
    • PEP 341
    • PEP 342, [1], [2], [3], [4]
    • PEP 343, [1], [2], [3], [4], [5], [6]
    • PEP 347
    • PEP 352, [1], [2]
    • PEP 353, [1], [2]
    • PEP 356
    • PEP 357
    • PEP 361
    • PEP 362, [1], [2], [3]
    • PEP 366, [1], [2], [3], [4], [5], [6]
    • PEP 370, [1], [2], [3], [4]
    • PEP 371
    • PEP 372, [1]
    • PEP 373
    • PEP 378, [1], [2]
    • PEP 380, [1]
    • PEP 383, [1], [2], [3], [4]
    • PEP 384, [1], [2]
    • PEP 385
    • PEP 389, [1]
    • PEP 391, [1]
    • PEP 392
    • PEP 393, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]
    • PEP 395
    • PEP 397, [1], [2], [3]
    • PEP 398
    • PEP 4
    • PEP 405, [1]
    • PEP 409
    • PEP 411, [1], [2], [3], [4], [5], [6]
    • PEP 412
    • PEP 414, [1]
    • PEP 418
    • PEP 420, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13]
    • PEP 421, [1]
    • PEP 424, [1]
    • PEP 427
    • PEP 428, [1], [2]
    • PEP 429
    • PEP 432
    • PEP 434
    • PEP 435, [1], [2]
    • PEP 436, [1], [2]
    • PEP 441, [1]
    • PEP 442, [1], [2], [3], [4], [5], [6]
    • PEP 443, [1], [2]
    • PEP 445, [1], [2], [3]
    • PEP 446, [1], [2], [3]
    • PEP 448, [1], [2], [3], [4]
    • PEP 450, [1], [2]
    • PEP 451, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]
    • PEP 453, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]
    • PEP 454, [1], [2]
    • PEP 456, [1]
    • PEP 461, [1], [2]
    • PEP 465, [1], [2]
    • PEP 466, [1], [2], [3]
    • PEP 468, [1]
    • PEP 471, [1]
    • PEP 475, [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]
    • PEP 476
    • PEP 477
    • PEP 478
    • PEP 479, [1], [2], [3], [4], [5], [6]
    • PEP 483, [1]
    • PEP 484, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19]
    • PEP 485, [1], [2], [3]
    • PEP 486, [1]
    • PEP 487, [1], [2], [3]
    • PEP 488, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]
    • PEP 489, [1], [2], [3], [4], [5], [6], [7], [8], [9]
    • PEP 492, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20]
    • PEP 493
    • PEP 494
    • PEP 495, [1]
    • PEP 498, [1], [2], [3]
    • PEP 5, [1]
    • PEP 506, [1]
    • PEP 511
    • PEP 515, [1], [2]
    • PEP 519, [1]
    • PEP 520
    • PEP 523, [1]
    • PEP 524, [1], [2], [3], [4], [5]
    • PEP 525, [1], [2], [3], [4], [5], [6]
    • PEP 526, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]
    • PEP 528, [1]
    • PEP 529, [1], [2], [3], [4], [5]
    • PEP 530, [1], [2]
    • PEP 538, [1], [2], [3], [4]
    • PEP 539, [1], [2]
    • PEP 540, [1], [2], [3]
    • PEP 545, [1]
    • PEP 552, [1], [2], [3], [4], [5]
    • PEP 553, [1]
    • PEP 557, [1]
    • PEP 560, [1], [2], [3], [4], [5], [6]
    • PEP 562, [1], [2], [3]
    • PEP 563, [1], [2]
    • PEP 564, [1], [2], [3]
    • PEP 565
    • PEP 567, [1], [2], [3], [4], [5], [6], [7]
    • PEP 6
    • PEP 628, [1]
    • PEP 7, [1]
    • PEP 8, [1], [2], [3], [4]
  • Python Package Index (PyPI)
    • .pypirc file
  • PYTHON*, [1], [2], [3]
  • python.function.entry (C の関数)
  • python.function.return (C の関数)
  • python_branch() (platform モジュール)
  • python_build() (platform モジュール)
  • python_compiler() (platform モジュール)
  • PYTHON_DOM
  • python_implementation() (platform モジュール)
  • python_is_optimized() (test.support モジュール)
  • python_revision() (platform モジュール)
  • python_version() (platform モジュール)
  • python_version_tuple() (platform モジュール)
  • PYTHONASYNCIODEBUG, [1]
  • PYTHONBREAKPOINT, [1], [2], [3]
  • PYTHONCASEOK
  • PYTHONCOERCECLOCALE, [1]
  • PYTHONDEBUG, [1]
  • PYTHONDEVMODE, [1]
  • PYTHONDOCS
  • PYTHONDONTWRITEBYTECODE, [1], [2], [3], [4], [5]
  • PYTHONDUMPREFS
  • PYTHONFAULTHANDLER, [1]
  • PYTHONHASHSEED, [1], [2], [3], [4], [5], [6], [7], [8]
  • PYTHONHOME, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15]
  • Pythonic
  • PYTHONINSPECT, [1], [2]
  • PYTHONIOENCODING, [1], [2], [3], [4], [5], [6]
  • PYTHONLEGACYWINDOWSFSENCODING, [1], [2]
  • PYTHONLEGACYWINDOWSSTDIO, [1], [2]
  • PYTHONMALLOC, [1], [2], [3], [4], [5], [6]
  • PYTHONMALLOCSTATS, [1]
  • PYTHONNOUSERSITE, [1], [2], [3], [4]
  • PYTHONOPTIMIZE, [1]
  • PYTHONPATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24]
  • PYTHONPROFILEIMPORTTIME, [1], [2]
  • PYTHONSHOWALLOCCOUNT
  • PYTHONSHOWREFCOUNT
  • PYTHONSTARTUP, [1], [2], [3], [4], [5], [6], [7], [8], [9]
  • PYTHONTRACEMALLOC, [1], [2]
  • PYTHONUNBUFFERED, [1]
  • PYTHONUSERBASE, [1], [2]
  • PYTHONUSERSITE
  • PYTHONUTF8, [1], [2]
  • PYTHONVERBOSE, [1]
  • PYTHONWARNINGS, [1], [2], [3], [4], [5], [6], [7]
  • PyThread_create_key (C の関数)
  • PyThread_delete_key (C の関数)
  • PyThread_delete_key_value (C の関数)
  • PyThread_get_key_value (C の関数)
  • PyThread_ReInitTLS (C の関数)
  • PyThread_set_key_value (C の関数)
  • PyThread_tss_alloc (C の関数)
  • PyThread_tss_create (C の関数)
  • PyThread_tss_delete (C の関数)
  • PyThread_tss_free (C の関数)
  • PyThread_tss_get (C の関数)
  • PyThread_tss_is_created (C の関数)
  • PyThread_tss_set (C の関数)
  • PyThreadState, [1]
    • (C のデータ型)
  • PyThreadState_Clear (C の関数)
  • PyThreadState_Delete (C の関数)
  • PyThreadState_Get (C の関数)
  • PyThreadState_GetDict (C の関数)
  • PyThreadState_New (C の関数)
  • PyThreadState_Next (C の関数)
  • PyThreadState_SetAsyncExc (C の関数)
  • PyThreadState_Swap (C の関数)
  • PyTime_Check (C の関数)
  • PyTime_CheckExact (C の関数)
  • PyTime_FromTime (C の関数)
  • PyTimeZone_FromOffset (C の関数)
  • PyTimeZone_FromOffsetAndName (C の関数)
  • PyTrace_C_CALL (C の変数)
  • PyTrace_C_EXCEPTION (C の変数)
  • PyTrace_C_RETURN (C の変数)
  • PyTrace_CALL (C の変数)
  • PyTrace_EXCEPTION (C の変数)
  • PyTrace_LINE (C の変数)
  • PyTrace_OPCODE (C の変数)
  • PyTrace_RETURN (C の変数)
  • PyTuple_Check (C の関数)
  • PyTuple_CheckExact (C の関数)
  • PyTuple_ClearFreeList (C の関数)
  • PyTuple_GET_ITEM (C の関数)
  • PyTuple_GET_SIZE (C の関数)
  • PyTuple_GetItem (C の関数)
  • PyTuple_GetSlice (C の関数)
  • PyTuple_New (C の関数)
  • PyTuple_Pack (C の関数)
  • PyTuple_SET_ITEM (C の関数)
  • PyTuple_SetItem (C の関数)
  • PyTuple_SetItem()
  • PyTuple_Size (C の関数)
  • PyTuple_Type (C の変数)
  • PyTupleObject (C のデータ型)
  • PyType_Check (C の関数)
  • PyType_CheckExact (C の関数)
  • PyType_ClearCache (C の関数)
  • PyType_FromSpec (C の関数)
  • PyType_FromSpecWithBases (C の関数)
  • PyType_GenericAlloc (C の関数)
  • PyType_GenericNew (C の関数)
  • PyType_GetFlags (C の関数)
  • PyType_GetSlot (C の関数)
  • PyType_HasFeature (C の関数)
  • PyType_IS_GC (C の関数)
  • PyType_IsSubtype (C の関数)
  • PyType_Modified (C の関数)
  • PyType_Ready (C の関数)
  • PyType_Type (C の変数)
  • PyTypeObject (C のデータ型)
  • PyTypeObject.tp_alloc (C のメンバ変数)
  • PyTypeObject.tp_allocs (C のメンバ変数)
  • PyTypeObject.tp_as_buffer (C のメンバ変数)
  • PyTypeObject.tp_base (C のメンバ変数)
  • PyTypeObject.tp_bases (C のメンバ変数)
  • PyTypeObject.tp_basicsize (C のメンバ変数)
  • PyTypeObject.tp_cache (C のメンバ変数)
  • PyTypeObject.tp_call (C のメンバ変数)
  • PyTypeObject.tp_clear (C のメンバ変数)
  • PyTypeObject.tp_dealloc (C のメンバ変数)
  • PyTypeObject.tp_descr_get (C のメンバ変数)
  • PyTypeObject.tp_descr_set (C のメンバ変数)
  • PyTypeObject.tp_dict (C のメンバ変数)
  • PyTypeObject.tp_dictoffset (C のメンバ変数)
  • PyTypeObject.tp_doc (C のメンバ変数)
  • PyTypeObject.tp_finalize (C のメンバ変数)
  • PyTypeObject.tp_flags (C のメンバ変数)
  • PyTypeObject.tp_free (C のメンバ変数)
  • PyTypeObject.tp_frees (C のメンバ変数)
  • PyTypeObject.tp_getattr (C のメンバ変数)
  • PyTypeObject.tp_getattro (C のメンバ変数)
  • PyTypeObject.tp_getset (C のメンバ変数)
  • PyTypeObject.tp_hash (C のメンバ変数)
  • PyTypeObject.tp_init (C のメンバ変数)
  • PyTypeObject.tp_is_gc (C のメンバ変数)
  • PyTypeObject.tp_itemsize (C のメンバ変数)
  • PyTypeObject.tp_iter (C のメンバ変数)
  • PyTypeObject.tp_iternext (C のメンバ変数)
  • PyTypeObject.tp_maxalloc (C のメンバ変数)
  • PyTypeObject.tp_members (C のメンバ変数)
  • PyTypeObject.tp_methods (C のメンバ変数)
  • PyTypeObject.tp_mro (C のメンバ変数)
  • PyTypeObject.tp_name (C のメンバ変数)
  • PyTypeObject.tp_new (C のメンバ変数)
  • PyTypeObject.tp_next (C のメンバ変数)
  • PyTypeObject.tp_print (C のメンバ変数)
  • PyTypeObject.tp_repr (C のメンバ変数)
  • PyTypeObject.tp_richcompare (C のメンバ変数)
  • PyTypeObject.tp_setattr (C のメンバ変数)
  • PyTypeObject.tp_setattro (C のメンバ変数)
  • PyTypeObject.tp_str (C のメンバ変数)
  • PyTypeObject.tp_subclasses (C のメンバ変数)
  • PyTypeObject.tp_traverse (C のメンバ変数)
  • PyTypeObject.tp_weaklist (C のメンバ変数)
  • PyTypeObject.tp_weaklistoffset (C のメンバ変数)
  • PyTZInfo_Check (C の関数)
  • PyTZInfo_CheckExact (C の関数)
  • PyUnicode_1BYTE_DATA (C の関数)
  • PyUnicode_1BYTE_KIND (C のマクロ)
  • PyUnicode_2BYTE_DATA (C の関数)
  • PyUnicode_2BYTE_KIND (C のマクロ)
  • PyUnicode_4BYTE_DATA (C の関数)
  • PyUnicode_4BYTE_KIND (C のマクロ)
  • PyUnicode_AS_DATA (C の関数)
  • PyUnicode_AS_UNICODE (C の関数)
  • PyUnicode_AsASCIIString (C の関数)
  • PyUnicode_AsCharmapString (C の関数)
  • PyUnicode_AsEncodedString (C の関数)
  • PyUnicode_AsLatin1String (C の関数)
  • PyUnicode_AsMBCSString (C の関数)
  • PyUnicode_AsRawUnicodeEscapeString (C の関数)
  • PyUnicode_AsUCS4 (C の関数)
  • PyUnicode_AsUCS4Copy (C の関数)
  • PyUnicode_AsUnicode (C の関数)
  • PyUnicode_AsUnicodeAndSize (C の関数)
  • PyUnicode_AsUnicodeCopy (C の関数)
  • PyUnicode_AsUnicodeEscapeString (C の関数)
  • PyUnicode_AsUTF16String (C の関数)
  • PyUnicode_AsUTF32String (C の関数)
  • PyUnicode_AsUTF8 (C の関数)
  • PyUnicode_AsUTF8AndSize (C の関数)
  • PyUnicode_AsUTF8String (C の関数)
  • PyUnicode_AsWideChar (C の関数)
  • PyUnicode_AsWideCharString (C の関数)
  • PyUnicode_Check (C の関数)
  • PyUnicode_CheckExact (C の関数)
  • PyUnicode_ClearFreeList (C の関数)
  • PyUnicode_Compare (C の関数)
  • PyUnicode_CompareWithASCIIString (C の関数)
  • PyUnicode_Concat (C の関数)
  • PyUnicode_Contains (C の関数)
  • PyUnicode_CopyCharacters (C の関数)
  • PyUnicode_Count (C の関数)
  • PyUnicode_DATA (C の関数)
  • PyUnicode_Decode (C の関数)
  • PyUnicode_DecodeASCII (C の関数)
  • PyUnicode_DecodeCharmap (C の関数)
  • PyUnicode_DecodeFSDefault (C の関数)
  • PyUnicode_DecodeFSDefaultAndSize (C の関数)
  • PyUnicode_DecodeLatin1 (C の関数)
  • PyUnicode_DecodeLocale (C の関数)
  • PyUnicode_DecodeLocaleAndSize (C の関数)
  • PyUnicode_DecodeMBCS (C の関数)
  • PyUnicode_DecodeMBCSStateful (C の関数)
  • PyUnicode_DecodeRawUnicodeEscape (C の関数)
  • PyUnicode_DecodeUnicodeEscape (C の関数)
  • PyUnicode_DecodeUTF16 (C の関数)
  • PyUnicode_DecodeUTF16Stateful (C の関数)
  • PyUnicode_DecodeUTF32 (C の関数)
  • PyUnicode_DecodeUTF32Stateful (C の関数)
  • PyUnicode_DecodeUTF7 (C の関数)
  • PyUnicode_DecodeUTF7Stateful (C の関数)
  • PyUnicode_DecodeUTF8 (C の関数)
  • PyUnicode_DecodeUTF8Stateful (C の関数)
  • PyUnicode_Encode (C の関数)
  • PyUnicode_EncodeASCII (C の関数)
  • PyUnicode_EncodeCharmap (C の関数)
  • PyUnicode_EncodeCodePage (C の関数)
  • PyUnicode_EncodeFSDefault (C の関数)
  • PyUnicode_EncodeLatin1 (C の関数)
  • PyUnicode_EncodeLocale (C の関数)
  • PyUnicode_EncodeMBCS (C の関数)
  • PyUnicode_EncodeRawUnicodeEscape (C の関数)
  • PyUnicode_EncodeUnicodeEscape (C の関数)
  • PyUnicode_EncodeUTF16 (C の関数)
  • PyUnicode_EncodeUTF32 (C の関数)
  • PyUnicode_EncodeUTF7 (C の関数)
  • PyUnicode_EncodeUTF8 (C の関数)
  • PyUnicode_Fill (C の関数)
  • PyUnicode_Find (C の関数)
  • PyUnicode_FindChar (C の関数)
  • PyUnicode_Format (C の関数)
  • PyUnicode_FromEncodedObject (C の関数)
  • PyUnicode_FromFormat (C の関数)
  • PyUnicode_FromFormatV (C の関数)
  • PyUnicode_FromKindAndData (C の関数)
  • PyUnicode_FromObject (C の関数)
  • PyUnicode_FromString (C の関数)
  • PyUnicode_FromString()
  • PyUnicode_FromStringAndSize (C の関数)
  • PyUnicode_FromUnicode (C の関数)
  • PyUnicode_FromWideChar (C の関数)
  • PyUnicode_FSConverter (C の関数)
  • PyUnicode_FSDecoder (C の関数)
  • PyUnicode_GET_DATA_SIZE (C の関数)
  • PyUnicode_GET_LENGTH (C の関数)
  • PyUnicode_GET_SIZE (C の関数)
  • PyUnicode_GetLength (C の関数)
  • PyUnicode_GetSize (C の関数)
  • PyUnicode_InternFromString (C の関数)
  • PyUnicode_InternInPlace (C の関数)
  • PyUnicode_Join (C の関数)
  • PyUnicode_KIND (C の関数)
  • PyUnicode_MAX_CHAR_VALUE (C の関数)
  • PyUnicode_New (C の関数)
  • PyUnicode_READ (C の関数)
  • PyUnicode_READ_CHAR (C の関数)
  • PyUnicode_ReadChar (C の関数)
  • PyUnicode_READY (C の関数)
  • PyUnicode_Replace (C の関数)
  • PyUnicode_RichCompare (C の関数)
  • PyUnicode_Split (C の関数)
  • PyUnicode_Splitlines (C の関数)
  • PyUnicode_Substring (C の関数)
  • PyUnicode_Tailmatch (C の関数)
  • PyUnicode_TransformDecimalToASCII (C の関数)
  • PyUnicode_Translate (C の関数), [1]
  • PyUnicode_TranslateCharmap (C の関数)
  • PyUnicode_Type (C の変数)
  • PyUnicode_WCHAR_KIND (C のマクロ)
  • PyUnicode_WRITE (C の関数)
  • PyUnicode_WriteChar (C の関数)
  • PyUnicodeDecodeError_Create (C の関数)
  • PyUnicodeDecodeError_GetEncoding (C の関数)
  • PyUnicodeDecodeError_GetEnd (C の関数)
  • PyUnicodeDecodeError_GetObject (C の関数)
  • PyUnicodeDecodeError_GetReason (C の関数)
  • PyUnicodeDecodeError_GetStart (C の関数)
  • PyUnicodeDecodeError_SetEnd (C の関数)
  • PyUnicodeDecodeError_SetReason (C の関数)
  • PyUnicodeDecodeError_SetStart (C の関数)
  • PyUnicodeEncodeError_Create (C の関数)
  • PyUnicodeEncodeError_GetEncoding (C の関数)
  • PyUnicodeEncodeError_GetEnd (C の関数)
  • PyUnicodeEncodeError_GetObject (C の関数)
  • PyUnicodeEncodeError_GetReason (C の関数)
  • PyUnicodeEncodeError_GetStart (C の関数)
  • PyUnicodeEncodeError_SetEnd (C の関数)
  • PyUnicodeEncodeError_SetReason (C の関数)
  • PyUnicodeEncodeError_SetStart (C の関数)
  • PyUnicodeObject (C のデータ型)
  • PyUnicodeTranslateError_Create (C の関数)
  • PyUnicodeTranslateError_GetEnd (C の関数)
  • PyUnicodeTranslateError_GetObject (C の関数)
  • PyUnicodeTranslateError_GetReason (C の関数)
  • PyUnicodeTranslateError_GetStart (C の関数)
  • PyUnicodeTranslateError_SetEnd (C の関数)
  • PyUnicodeTranslateError_SetReason (C の関数)
  • PyUnicodeTranslateError_SetStart (C の関数)
  • PyVarObject (C のデータ型)
  • PyVarObject.ob_size (C のメンバ変数)
  • PyVarObject_HEAD_INIT (C のマクロ)
  • PyWeakref_Check (C の関数)
  • PyWeakref_CheckProxy (C の関数)
  • PyWeakref_CheckRef (C の関数)
  • PyWeakref_GET_OBJECT (C の関数)
  • PyWeakref_GetObject (C の関数)
  • PyWeakref_NewProxy (C の関数)
  • PyWeakref_NewRef (C の関数)
  • PyWrapper_New (C の関数)
  • PyZipFile (zipfile のクラス)

Q

  • qiflush() (curses モジュール)
  • QName (xml.etree.ElementTree のクラス)
  • qsize() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
  • qualified name
  • quantize() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • QueryInfoKey() (winreg モジュール)
  • QueryReflectionKey() (winreg モジュール)
  • QueryValue() (winreg モジュール)
  • QueryValueEx() (winreg モジュール)
  • Queue (asyncio のクラス)
    • (multiprocessing のクラス)
    • (queue のクラス)
  • queue (sched.scheduler の属性)
    • (モジュール)
  • Queue() (multiprocessing.managers.SyncManager のメソッド)
  • QueueEmpty
  • QueueFull
  • QueueHandler (logging.handlers のクラス)
  • QueueListener (logging.handlers のクラス)
  • quick_ratio() (difflib.SequenceMatcher のメソッド)
  • quit (pdb command)
    • (組み込み変数)
  • quit() (ftplib.FTP のメソッド)
    • (nntplib.NNTP のメソッド)
    • (poplib.POP3 のメソッド)
    • (smtplib.SMTP のメソッド)
  • quopri (モジュール)
  • quote() (email.utils モジュール)
    • (shlex モジュール)
    • (urllib.parse モジュール)
  • QUOTE_ALL (csv モジュール)
  • quote_from_bytes() (urllib.parse モジュール)
  • QUOTE_MINIMAL (csv モジュール)
  • QUOTE_NONE (csv モジュール)
  • QUOTE_NONNUMERIC (csv モジュール)
  • quote_plus() (urllib.parse モジュール)
  • quoteattr() (xml.sax.saxutils モジュール)
  • quotechar (csv.Dialect の属性)
  • quoted-printable
    • encoding
  • quotes (shlex.shlex の属性)
  • quoting (csv.Dialect の属性)

R

  • r"
    • raw string literal
  • r'
    • raw string literal
  • R_OK (os モジュール)
  • radians() (math モジュール)
    • (turtle モジュール)
  • RadioButtonGroup (msilib のクラス)
  • radiogroup() (msilib.Dialog のメソッド)
  • radix() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • RADIXCHAR (locale モジュール)
  • raise
    • 文, [1]
  • raise (2to3 fixer)
  • raise an exception
  • raise_on_defect (email.policy.Policy の属性)
  • RAISE_VARARGS (opcode)
  • raising
    • exception
  • RAND_add() (ssl モジュール)
  • RAND_bytes() (ssl モジュール)
  • RAND_egd() (ssl モジュール)
  • RAND_pseudo_bytes() (ssl モジュール)
  • RAND_status() (ssl モジュール)
  • randbelow() (secrets モジュール)
  • randbits() (secrets モジュール)
  • randint() (random モジュール)
  • random (モジュール)
  • random() (random モジュール)
  • randrange() (random モジュール)
  • range
    • オブジェクト
    • 組み込み関数
  • range (組み込みクラス)
  • RARROW (token モジュール)
  • ratecv() (audioop モジュール)
  • ratio() (difflib.SequenceMatcher のメソッド)
  • Rational (numbers のクラス)
  • raw (io.BufferedIOBase の属性)
  • raw string
  • raw() (curses モジュール)
  • raw_data_manager (email.contentmanager モジュール)
  • raw_decode() (json.JSONDecoder のメソッド)
  • raw_input (2to3 fixer)
  • raw_input() (code.InteractiveConsole のメソッド)
  • RawArray() (multiprocessing.sharedctypes モジュール)
  • RawConfigParser (configparser のクラス)
  • RawDescriptionHelpFormatter (argparse のクラス)
  • RawIOBase (io のクラス)
  • RawPen (turtle のクラス)
  • RawTextHelpFormatter (argparse のクラス)
  • RawTurtle (turtle のクラス)
  • RawValue() (multiprocessing.sharedctypes モジュール)
  • RBRACE (token モジュール)
  • rcpttos (smtpd.SMTPChannel の属性)
  • re
    • モジュール, [1]
  • re (re.Match の属性)
    • (モジュール)
  • read() (asyncio.StreamReader のメソッド)
    • (chunk.Chunk のメソッド)
    • (codecs.StreamReader のメソッド)
    • (configparser.ConfigParser のメソッド)
    • (http.client.HTTPResponse のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (io.BufferedIOBase のメソッド)
    • (io.BufferedReader のメソッド)
    • (io.RawIOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (mimetypes.MimeTypes のメソッド)
    • (mmap.mmap のメソッド)
    • (os モジュール)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (ssl.MemoryBIO のメソッド)
    • (ssl.SSLSocket のメソッド)
    • (urllib.robotparser.RobotFileParser のメソッド)
    • (zipfile.ZipFile のメソッド)
  • read1() (io.BufferedIOBase のメソッド)
    • (io.BufferedReader のメソッド)
    • (io.BytesIO のメソッド)
  • read_all() (telnetlib.Telnet のメソッド)
  • read_binary() (importlib.resources モジュール)
  • read_byte() (mmap.mmap のメソッド)
  • read_bytes() (pathlib.Path のメソッド)
  • read_dict() (configparser.ConfigParser のメソッド)
  • read_eager() (telnetlib.Telnet のメソッド)
  • read_environ() (wsgiref.handlers モジュール)
  • read_events() (xml.etree.ElementTree.XMLPullParser のメソッド)
  • read_file() (configparser.ConfigParser のメソッド)
  • read_history_file() (readline モジュール)
  • read_init_file() (readline モジュール)
  • read_lazy() (telnetlib.Telnet のメソッド)
  • read_mime_types() (mimetypes モジュール)
  • READ_RESTRICTED
  • read_sb_data() (telnetlib.Telnet のメソッド)
  • read_some() (telnetlib.Telnet のメソッド)
  • read_string() (configparser.ConfigParser のメソッド)
  • read_text() (importlib.resources モジュール)
    • (pathlib.Path のメソッド)
  • read_token() (shlex.shlex のメソッド)
  • read_until() (telnetlib.Telnet のメソッド)
  • read_very_eager() (telnetlib.Telnet のメソッド)
  • read_very_lazy() (telnetlib.Telnet のメソッド)
  • read_windows_registry() (mimetypes.MimeTypes のメソッド)
  • READABLE (tkinter モジュール)
  • readable() (asyncore.dispatcher のメソッド)
    • (io.IOBase のメソッド)
  • readall() (io.RawIOBase のメソッド)
  • reader() (csv モジュール)
  • ReadError
  • readexactly() (asyncio.StreamReader のメソッド)
  • readfp() (configparser.ConfigParser のメソッド)
    • (mimetypes.MimeTypes のメソッド)
  • readframes() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • readinto() (http.client.HTTPResponse のメソッド)
    • (io.BufferedIOBase のメソッド)
    • (io.RawIOBase のメソッド)
  • readinto1() (io.BufferedIOBase のメソッド)
    • (io.BytesIO のメソッド)
  • readline (モジュール)
  • readline() (asyncio.StreamReader のメソッド)
    • (codecs.StreamReader のメソッド)
    • (distutils.text_file.TextFile のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (io.IOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (mmap.mmap のメソッド)
  • readlines() (codecs.StreamReader のメソッド)
    • (distutils.text_file.TextFile のメソッド)
    • (io.IOBase のメソッド)
  • readlink() (os モジュール)
  • readmodule() (pyclbr モジュール)
  • readmodule_ex() (pyclbr モジュール)
  • READONLY
  • readonly (memoryview の属性)
  • readPlist() (plistlib モジュール)
  • readPlistFromBytes() (plistlib モジュール)
  • ReadTransport (asyncio のクラス)
  • readuntil() (asyncio.StreamReader のメソッド)
  • readv() (os モジュール)
  • ready() (multiprocessing.pool.AsyncResult のメソッド)
  • Real (numbers のクラス)
  • real (numbers.Complex の属性)
  • Real Media File Format
  • real_max_memuse (test.support モジュール)
  • real_quick_ratio() (difflib.SequenceMatcher のメソッド)
  • realloc()
  • realpath() (os.path モジュール)
  • REALTIME_PRIORITY_CLASS (subprocess モジュール)
  • reap_children() (test.support モジュール)
  • reap_threads() (test.support モジュール)
  • reason (http.client.HTTPResponse の属性)
    • (UnicodeError の属性)
    • (ssl.SSLError の属性)
    • (urllib.error.HTTPError の属性)
    • (urllib.error.URLError の属性)
  • reattach() (tkinter.ttk.Treeview のメソッド)
  • rebinding
    • name
  • reccontrols() (ossaudiodev.oss_mixer_device のメソッド)
  • received_data (smtpd.SMTPChannel の属性)
  • received_lines (smtpd.SMTPChannel の属性)
  • recent() (imaplib.IMAP4 のメソッド)
  • reconfigure() (io.TextIOWrapper のメソッド)
  • record_original_stdout() (test.support モジュール)
  • records (unittest.TestCase の属性)
  • rect() (cmath モジュール)
  • rectangle() (curses.textpad モジュール)
  • RecursionError
  • recursive_repr() (reprlib モジュール)
  • recv() (asyncore.dispatcher のメソッド)
    • (multiprocessing.connection.Connection のメソッド)
    • (socket.socket のメソッド)
  • recv_bytes() (multiprocessing.connection.Connection のメソッド)
  • recv_bytes_into() (multiprocessing.connection.Connection のメソッド)
  • recv_into() (socket.socket のメソッド)
  • recvfrom() (socket.socket のメソッド)
  • recvfrom_into() (socket.socket のメソッド)
  • recvmsg() (socket.socket のメソッド)
  • recvmsg_into() (socket.socket のメソッド)
  • redirect_request() (urllib.request.HTTPRedirectHandler のメソッド)
  • redirect_stderr() (contextlib モジュール)
  • redirect_stdout() (contextlib モジュール)
  • redisplay() (readline モジュール)
  • redrawln() (curses.window のメソッド)
  • redrawwin() (curses.window のメソッド)
  • reduce (2to3 fixer)
  • reduce() (functools モジュール)
  • ref (weakref のクラス)
  • refcount_test() (test.support モジュール)
  • reference
    • attribute
  • reference count
  • reference counting
  • ReferenceError, [1]
  • ReferenceType (weakref モジュール)
  • refold_source (email.policy.EmailPolicy の属性)
  • refresh() (curses.window のメソッド)
  • REG_BINARY (winreg モジュール)
  • REG_DWORD (winreg モジュール)
  • REG_DWORD_BIG_ENDIAN (winreg モジュール)
  • REG_DWORD_LITTLE_ENDIAN (winreg モジュール)
  • REG_EXPAND_SZ (winreg モジュール)
  • REG_FULL_RESOURCE_DESCRIPTOR (winreg モジュール)
  • REG_LINK (winreg モジュール)
  • REG_MULTI_SZ (winreg モジュール)
  • REG_NONE (winreg モジュール)
  • REG_QWORD (winreg モジュール)
  • REG_QWORD_LITTLE_ENDIAN (winreg モジュール)
  • REG_RESOURCE_LIST (winreg モジュール)
  • REG_RESOURCE_REQUIREMENTS_LIST (winreg モジュール)
  • REG_SZ (winreg モジュール)
  • register() (abc.ABCMeta のメソッド)
    • (atexit モジュール)
    • (codecs モジュール)
    • (faulthandler モジュール)
    • (multiprocessing.managers.BaseManager のメソッド)
    • (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.poll のメソッド)
    • (selectors.BaseSelector のメソッド)
    • (webbrowser モジュール)
  • register_adapter() (sqlite3 モジュール)
  • register_archive_format() (shutil モジュール)
  • register_at_fork() (os モジュール)
  • register_converter() (sqlite3 モジュール)
  • register_defect() (email.policy.Policy のメソッド)
  • register_dialect() (csv モジュール)
  • register_error() (codecs モジュール)
  • register_function() (xmlrpc.server.CGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.SimpleXMLRPCServer のメソッド)
  • register_instance() (xmlrpc.server.CGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.SimpleXMLRPCServer のメソッド)
  • register_introspection_functions() (xmlrpc.server.CGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.SimpleXMLRPCServer のメソッド)
  • register_multicall_functions() (xmlrpc.server.CGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.SimpleXMLRPCServer のメソッド)
  • register_namespace() (xml.etree.ElementTree モジュール)
  • register_optionflag() (doctest モジュール)
  • register_shape() (turtle モジュール)
  • register_unpack_format() (shutil モジュール)
  • registerDOMImplementation() (xml.dom モジュール)
  • registerResult() (unittest モジュール)
  • regular
    • package
  • regular package
  • relative
    • URL
    • import
  • relative_to() (pathlib.PurePath のメソッド)
  • release() (_thread.lock のメソッド)
    • (asyncio.Condition のメソッド)
    • (asyncio.Lock のメソッド)
    • (asyncio.Semaphore のメソッド)
    • (logging.Handler のメソッド)
    • (memoryview のメソッド)
    • (multiprocessing.Lock のメソッド)
    • (multiprocessing.RLock のメソッド)
    • (platform モジュール)
    • (threading.Condition のメソッド)
    • (threading.Lock のメソッド)
    • (threading.RLock のメソッド)
    • (threading.Semaphore のメソッド)
  • release_lock() (imp モジュール)
  • reload (2to3 fixer)
  • reload() (imp モジュール)
    • (importlib モジュール)
  • relpath() (os.path モジュール)
  • remainder() (decimal.Context のメソッド)
    • (math モジュール)
  • remainder_near() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • RemoteDisconnected
  • remove() (array.array のメソッド)
    • (collections.deque のメソッド)
    • (frozenset のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (os モジュール)
    • (sequence method)
    • (xml.etree.ElementTree.Element のメソッド)
  • remove_child_handler() (asyncio.AbstractChildWatcher のメソッド)
  • remove_done_callback() (asyncio.Future のメソッド)
    • (asyncio.Task のメソッド)
  • remove_flag() (mailbox.MaildirMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
    • (mailbox.mboxMessage のメソッド)
  • remove_folder() (mailbox.Maildir のメソッド)
    • (mailbox.MH のメソッド)
  • remove_header() (urllib.request.Request のメソッド)
  • remove_history_item() (readline モジュール)
  • remove_label() (mailbox.BabylMessage のメソッド)
  • remove_option() (configparser.ConfigParser のメソッド)
    • (optparse.OptionParser のメソッド)
  • remove_pyc() (msilib.Directory のメソッド)
  • remove_reader() (asyncio.loop のメソッド)
  • remove_section() (configparser.ConfigParser のメソッド)
  • remove_sequence() (mailbox.MHMessage のメソッド)
  • remove_signal_handler() (asyncio.loop のメソッド)
  • remove_tree() (distutils.dir_util モジュール)
  • remove_writer() (asyncio.loop のメソッド)
  • removeAttribute() (xml.dom.Element のメソッド)
  • removeAttributeNode() (xml.dom.Element のメソッド)
  • removeAttributeNS() (xml.dom.Element のメソッド)
  • removeChild() (xml.dom.Node のメソッド)
  • removedirs() (os モジュール)
  • removeFilter() (logging.Handler のメソッド)
    • (logging.Logger のメソッド)
  • removeHandler() (logging.Logger のメソッド)
    • (unittest モジュール)
  • removeResult() (unittest モジュール)
  • removexattr() (os モジュール)
  • rename() (ftplib.FTP のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (os モジュール)
    • (pathlib.Path のメソッド)
  • renames (2to3 fixer)
  • renames() (os モジュール)
  • reopenIfNeeded() (logging.handlers.WatchedFileHandler のメソッド)
  • reorganize() (dbm.gnu.gdbm のメソッド)
  • repeat() (itertools モジュール)
    • (timeit モジュール)
    • (timeit.Timer のメソッド)
  • repetition
    • operation
  • replace() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.panel.Panel のメソッド)
    • (dataclasses モジュール)
    • (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (inspect.Parameter のメソッド)
    • (inspect.Signature のメソッド)
    • (os モジュール)
    • (pathlib.Path のメソッド)
    • (str のメソッド)
  • replace_errors() (codecs モジュール)
  • replace_header() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • replace_history_item() (readline モジュール)
  • replace_whitespace (textwrap.TextWrapper の属性)
  • replaceChild() (xml.dom.Node のメソッド)
  • ReplacePackage() (modulefinder モジュール)
  • report() (filecmp.dircmp のメソッド)
    • (modulefinder.ModuleFinder のメソッド)
  • REPORT_CDIFF (doctest モジュール)
  • report_failure() (doctest.DocTestRunner のメソッド)
  • report_full_closure() (filecmp.dircmp のメソッド)
  • REPORT_NDIFF (doctest モジュール)
  • REPORT_ONLY_FIRST_FAILURE (doctest モジュール)
  • report_partial_closure() (filecmp.dircmp のメソッド)
  • report_start() (doctest.DocTestRunner のメソッド)
  • report_success() (doctest.DocTestRunner のメソッド)
  • REPORT_UDIFF (doctest モジュール)
  • report_unexpected_exception() (doctest.DocTestRunner のメソッド)
  • REPORTING_FLAGS (doctest モジュール)
  • repr
    • 組み込み関数, [1], [2], [3]
  • repr (2to3 fixer)
  • Repr (reprlib のクラス)
  • repr() (built-in function)
    • __repr__() (object method)
  • repr() (reprlib モジュール)
    • (reprlib.Repr のメソッド)
    • (組み込み関数)
  • repr1() (reprlib.Repr のメソッド)
  • representation
    • integer
  • reprlib (モジュール)
  • Request (urllib.request のクラス)
  • request() (http.client.HTTPConnection のメソッド)
  • request_queue_size (socketserver.BaseServer の属性)
  • request_rate() (urllib.robotparser.RobotFileParser のメソッド)
  • request_uri() (wsgiref.util モジュール)
  • request_version (http.server.BaseHTTPRequestHandler の属性)
  • RequestHandlerClass (socketserver.BaseServer の属性)
  • requestline (http.server.BaseHTTPRequestHandler の属性)
  • requires() (test.support モジュール)
  • requires_bz2() (test.support モジュール)
  • requires_docstrings() (test.support モジュール)
  • requires_freebsd_version() (test.support モジュール)
  • requires_gzip() (test.support モジュール)
  • requires_IEEE_754() (test.support モジュール)
  • requires_linux_version() (test.support モジュール)
  • requires_lzma() (test.support モジュール)
  • requires_mac_version() (test.support モジュール)
  • requires_resource() (test.support モジュール)
  • requires_zlib() (test.support モジュール)
  • reserved (zipfile.ZipInfo の属性)
  • reserved word
  • RESERVED_FUTURE (uuid モジュール)
  • RESERVED_MICROSOFT (uuid モジュール)
  • RESERVED_NCS (uuid モジュール)
  • reset() (bdb.Bdb のメソッド)
    • (codecs.IncrementalDecoder のメソッド)
    • (codecs.IncrementalEncoder のメソッド)
    • (codecs.StreamReader のメソッド)
    • (codecs.StreamWriter のメソッド)
    • (contextvars.ContextVar のメソッド)
    • (html.parser.HTMLParser のメソッド)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (pipes.Template のメソッド)
    • (threading.Barrier のメソッド)
    • (turtle モジュール), [1]
    • (xdrlib.Packer のメソッド)
    • (xdrlib.Unpacker のメソッド)
    • (xml.dom.pulldom.DOMEventStream のメソッド)
    • (xml.sax.xmlreader.IncrementalParser のメソッド)
  • reset_mock() (unittest.mock.Mock のメソッド)
  • reset_prog_mode() (curses モジュール)
  • reset_shell_mode() (curses モジュール)
  • resetbuffer() (code.InteractiveConsole のメソッド)
  • resetlocale() (locale モジュール)
  • resetscreen() (turtle モジュール)
  • resetty() (curses モジュール)
  • resetwarnings() (warnings モジュール)
  • resize() (ctypes モジュール)
    • (curses.window のメソッド)
    • (mmap.mmap のメソッド)
  • resize_term() (curses モジュール)
  • resizemode() (turtle モジュール)
  • resizeterm() (curses モジュール)
  • resolution (datetime.date の属性)
    • (datetime.datetime の属性)
    • (datetime.time の属性)
    • (datetime.timedelta の属性)
  • resolve() (pathlib.Path のメソッド)
  • resolve_bases() (types モジュール)
  • resolve_name() (importlib.util モジュール)
  • resolveEntity() (xml.sax.handler.EntityResolver のメソッド)
  • Resource (importlib.resources モジュール)
  • resource (モジュール)
  • resource_path() (importlib.abc.ResourceReader のメソッド)
  • ResourceDenied
  • ResourceLoader (importlib.abc のクラス)
  • ResourceReader (importlib.abc のクラス)
  • ResourceWarning
  • response (nntplib.NNTPError の属性)
  • response() (imaplib.IMAP4 のメソッド)
  • ResponseNotReady
  • responses (http.client モジュール)
    • (http.server.BaseHTTPRequestHandler の属性)
  • restart (pdb command)
  • restore() (difflib モジュール)
  • RESTRICTED
  • restricted
    • execution
  • restype (ctypes._FuncPtr の属性)
  • result() (asyncio.Future のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
  • results() (trace.Trace のメソッド)
  • resume_reading() (asyncio.ReadTransport のメソッド)
  • resume_writing() (asyncio.BaseProtocol のメソッド)
  • retr() (poplib.POP3 のメソッド)
  • retrbinary() (ftplib.FTP のメソッド)
  • retrieve() (urllib.request.URLopener のメソッド)
  • retrlines() (ftplib.FTP のメソッド)
  • return
    • 文, [1], [2]
  • return (pdb command)
  • return_annotation (inspect.Signature の属性)
  • return_ok() (http.cookiejar.CookiePolicy のメソッド)
  • RETURN_VALUE (opcode)
  • return_value (unittest.mock.Mock の属性)
  • returncode (asyncio.asyncio.subprocess.Process の属性)
    • (subprocess.CalledProcessError の属性)
    • (subprocess.CompletedProcess の属性)
    • (subprocess.Popen の属性)
  • reverse() (array.array のメソッド)
    • (audioop モジュール)
    • (collections.deque のメソッド)
    • (sequence method)
  • reverse_order() (pstats.Stats のメソッド)
  • reverse_pointer (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv6Address の属性)
  • reversed() (組み込み関数)
  • Reversible (collections.abc のクラス)
    • (typing のクラス)
  • revert() (http.cookiejar.FileCookieJar のメソッド)
  • rewind() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • RFC
    • RFC 1014, [1]
    • RFC 1123
    • RFC 1321
    • RFC 1422, [1]
    • RFC 1521, [1], [2]
    • RFC 1522, [1], [2]
    • RFC 1524, [1]
    • RFC 1730
    • RFC 1738
    • RFC 1750
    • RFC 1766, [1]
    • RFC 1808, [1], [2]
    • RFC 1832, [1]
    • RFC 1869, [1]
    • RFC 1870, [1], [2]
    • RFC 1939, [1]
    • RFC 2033
    • RFC 2045, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]
    • RFC 2045#section-6.8
    • RFC 2046, [1], [2]
    • RFC 2047, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]
    • RFC 2060, [1]
    • RFC 2068
    • RFC 2087, [1], [2]
    • RFC 2104, [1]
    • RFC 2109, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15]
    • RFC 2183, [1], [2]
    • RFC 2231, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]
    • RFC 2295
    • RFC 2342, [1]
    • RFC 2368
    • RFC 2373, [1], [2]
    • RFC 2396, [1], [2], [3], [4]
    • RFC 2397
    • RFC 2449
    • RFC 2487
    • RFC 2518
    • RFC 2595, [1]
    • RFC 2616, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]
    • RFC 2732, [1], [2]
    • RFC 2774
    • RFC 2818, [1]
    • RFC 2822, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17]
    • RFC 2964
    • RFC 2965, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19]
    • RFC 2980, [1]
    • RFC 3056
    • RFC 3171
    • RFC 3207
    • RFC 3229
    • RFC 3280
    • RFC 3330
    • RFC 3454, [1]
    • RFC 3490, [1], [2], [3]
    • RFC 3490#section-3.1
    • RFC 3492, [1]
    • RFC 3493
    • RFC 3501
    • RFC 3542, [1]
    • RFC 3548, [1], [2], [3], [4], [5]
    • RFC 3659
    • RFC 3879
    • RFC 3927
    • RFC 3977, [1], [2], [3], [4]
    • RFC 3986, [1], [2], [3], [4], [5], [6], [7]
    • RFC 4086
    • RFC 4122, [1], [2], [3], [4], [5], [6], [7], [8]
    • RFC 4180
    • RFC 4193
    • RFC 4217
    • RFC 4291
    • RFC 4366
    • RFC 4380
    • RFC 4627, [1]
    • RFC 4642
    • RFC 4918, [1], [2], [3], [4]
    • RFC 4954, [1]
    • RFC 5161, [1]
    • RFC 5233
    • RFC 5246, [1]
    • RFC 5280, [1], [2], [3], [4]
    • RFC 5321, [1], [2], [3], [4]
    • RFC 5322, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21]
    • RFC 5424, [1], [2], [3]
    • RFC 5424#section-6
    • RFC 5735
    • RFC 5802
    • RFC 5842, [1]
    • RFC 5929
    • RFC 6066, [1], [2]
    • RFC 6125, [1]
    • RFC 6152, [1]
    • RFC 6531, [1], [2], [3], [4], [5], [6], [7], [8]
    • RFC 6532, [1], [2], [3]
    • RFC 6585, [1], [2], [3]
    • RFC 6855, [1], [2], [3]
    • RFC 6856, [1]
    • RFC 7159, [1], [2]
    • RFC 7230, [1]
    • RFC 7231, [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], [31], [32], [33], [34]
    • RFC 7232, [1]
    • RFC 7233, [1]
    • RFC 7235, [1]
    • RFC 7238
    • RFC 7301, [1], [2]
    • RFC 7525
    • RFC 7540
    • RFC 7693
    • RFC 7914
    • RFC 821, [1]
    • RFC 822, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]
    • RFC 854, [1]
    • RFC 959, [1]
    • RFC 977
  • rfc2109 (http.cookiejar.Cookie の属性)
  • rfc2109_as_netscape (http.cookiejar.DefaultCookiePolicy の属性)
  • rfc2965 (http.cookiejar.CookiePolicy の属性)
  • rfc822_escape() (distutils.util モジュール)
  • RFC_4122 (uuid モジュール)
  • rfile (http.server.BaseHTTPRequestHandler の属性)
  • rfind() (bytearray のメソッド)
    • (bytes のメソッド)
    • (mmap.mmap のメソッド)
    • (str のメソッド)
  • rgb_to_hls() (colorsys モジュール)
  • rgb_to_hsv() (colorsys モジュール)
  • rgb_to_yiq() (colorsys モジュール)
  • rglob() (pathlib.Path のメソッド)
  • right (filecmp.dircmp の属性)
  • right() (turtle モジュール)
  • right_list (filecmp.dircmp の属性)
  • right_only (filecmp.dircmp の属性)
  • RIGHTSHIFT (token モジュール)
  • RIGHTSHIFTEQUAL (token モジュール)
  • rindex() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • rjust() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • rlcompleter (モジュール)
  • rlecode_hqx() (binascii モジュール)
  • rledecode_hqx() (binascii モジュール)
  • RLIM_INFINITY (resource モジュール)
  • RLIMIT_AS (resource モジュール)
  • RLIMIT_CORE (resource モジュール)
  • RLIMIT_CPU (resource モジュール)
  • RLIMIT_DATA (resource モジュール)
  • RLIMIT_FSIZE (resource モジュール)
  • RLIMIT_MEMLOCK (resource モジュール)
  • RLIMIT_MSGQUEUE (resource モジュール)
  • RLIMIT_NICE (resource モジュール)
  • RLIMIT_NOFILE (resource モジュール)
  • RLIMIT_NPROC (resource モジュール)
  • RLIMIT_NPTS (resource モジュール)
  • RLIMIT_OFILE (resource モジュール)
  • RLIMIT_RSS (resource モジュール)
  • RLIMIT_RTPRIO (resource モジュール)
  • RLIMIT_RTTIME (resource モジュール)
  • RLIMIT_SBSIZE (resource モジュール)
  • RLIMIT_SIGPENDING (resource モジュール)
  • RLIMIT_STACK (resource モジュール)
  • RLIMIT_SWAP (resource モジュール)
  • RLIMIT_VMEM (resource モジュール)
  • RLock (multiprocessing のクラス)
    • (threading のクラス)
  • RLock() (multiprocessing.managers.SyncManager のメソッド)
  • rmd() (ftplib.FTP のメソッド)
  • rmdir() (os モジュール)
    • (pathlib.Path のメソッド)
    • (test.support モジュール)
  • RMFF
  • rms() (audioop モジュール)
  • rmtree() (shutil モジュール)
    • (test.support モジュール)
  • RobotFileParser (urllib.robotparser のクラス)
  • robots.txt
  • rollback() (sqlite3.Connection のメソッド)
  • ROT_THREE (opcode)
  • ROT_TWO (opcode)
  • rotate() (collections.deque のメソッド)
    • (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (logging.handlers.BaseRotatingHandler のメソッド)
  • RotatingFileHandler (logging.handlers のクラス)
  • rotation_filename() (logging.handlers.BaseRotatingHandler のメソッド)
  • rotator (logging.handlers.BaseRotatingHandler の属性)
  • round
    • 組み込み関数
  • round() (組み込み関数)
  • ROUND_05UP (decimal モジュール)
  • ROUND_CEILING (decimal モジュール)
  • ROUND_DOWN (decimal モジュール)
  • ROUND_FLOOR (decimal モジュール)
  • ROUND_HALF_DOWN (decimal モジュール)
  • ROUND_HALF_EVEN (decimal モジュール)
  • ROUND_HALF_UP (decimal モジュール)
  • ROUND_UP (decimal モジュール)
  • Rounded (decimal のクラス)
  • Row (sqlite3 のクラス)
  • row_factory (sqlite3.Connection の属性)
  • rowcount (sqlite3.Cursor の属性)
  • RPAR (token モジュール)
  • rpartition() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • rpc_paths (xmlrpc.server.SimpleXMLRPCRequestHandler の属性)
  • rpop() (poplib.POP3 のメソッド)
  • rset() (poplib.POP3 のメソッド)
  • rshift() (operator モジュール)
  • rsplit() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • RSQB (token モジュール)
  • rstrip() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • rt() (turtle モジュール)
  • RTLD_DEEPBIND (os モジュール)
  • RTLD_GLOBAL (os モジュール)
  • RTLD_LAZY (os モジュール)
  • RTLD_LOCAL (os モジュール)
  • RTLD_NODELETE (os モジュール)
  • RTLD_NOLOAD (os モジュール)
  • RTLD_NOW (os モジュール)
  • ruler (cmd.Cmd の属性)
  • run (pdb command)
  • Run script
  • run() (asyncio モジュール)
    • (bdb.Bdb のメソッド)
    • (contextvars.Context のメソッド)
    • (distutils.cmd.Command のメソッド)
    • (doctest.DocTestRunner のメソッド)
    • (multiprocessing.Process のメソッド)
    • (pdb モジュール)
    • (pdb.Pdb のメソッド)
    • (profile モジュール)
    • (profile.Profile のメソッド)
    • (sched.scheduler のメソッド)
    • (subprocess モジュール)
    • (test.support.BasicTestRunner のメソッド)
    • (threading.Thread のメソッド)
    • (trace.Trace のメソッド)
    • (unittest.TestCase のメソッド)
    • (unittest.TestSuite のメソッド)
    • (unittest.TextTestRunner のメソッド)
    • (wsgiref.handlers.BaseHandler のメソッド)
  • run_coroutine_threadsafe() (asyncio モジュール)
  • run_docstring_examples() (doctest モジュール)
  • run_doctest() (test.support モジュール)
  • run_forever() (asyncio.loop のメソッド)
  • run_in_executor() (asyncio.loop のメソッド)
  • run_in_subinterp() (test.support モジュール)
  • run_module() (runpy モジュール)
  • run_path() (runpy モジュール)
  • run_python_until_end() (test.support.script_helper モジュール)
  • run_script() (modulefinder.ModuleFinder のメソッド)
  • run_setup() (distutils.core モジュール)
  • run_unittest() (test.support モジュール)
  • run_until_complete() (asyncio.loop のメソッド)
  • run_with_locale() (test.support モジュール)
  • run_with_tz() (test.support モジュール)
  • runcall() (bdb.Bdb のメソッド)
    • (pdb モジュール)
    • (pdb.Pdb のメソッド)
    • (profile.Profile のメソッド)
  • runcode() (code.InteractiveInterpreter のメソッド)
  • runctx() (bdb.Bdb のメソッド)
    • (profile モジュール)
    • (profile.Profile のメソッド)
    • (trace.Trace のメソッド)
  • runeval() (bdb.Bdb のメソッド)
    • (pdb モジュール)
    • (pdb.Pdb のメソッド)
  • runfunc() (trace.Trace のメソッド)
  • running() (concurrent.futures.Future のメソッド)
  • runpy (モジュール)
  • runsource() (code.InteractiveInterpreter のメソッド)
  • runtime_library_dir_option() (distutils.ccompiler.CCompiler のメソッド)
  • RuntimeError
  • RuntimeWarning
  • RUSAGE_BOTH (resource モジュール)
  • RUSAGE_CHILDREN (resource モジュール)
  • RUSAGE_SELF (resource モジュール)
  • RUSAGE_THREAD (resource モジュール)
  • RWF_DSYNC (os モジュール)
  • RWF_HIPRI (os モジュール)
  • RWF_NOWAIT (os モジュール)
  • RWF_SYNC (os モジュール)

S

  • S (re モジュール)
  • S_ENFMT (stat モジュール)
  • S_IEXEC (stat モジュール)
  • S_IFBLK (stat モジュール)
  • S_IFCHR (stat モジュール)
  • S_IFDIR (stat モジュール)
  • S_IFDOOR (stat モジュール)
  • S_IFIFO (stat モジュール)
  • S_IFLNK (stat モジュール)
  • S_IFMT() (stat モジュール)
  • S_IFPORT (stat モジュール)
  • S_IFREG (stat モジュール)
  • S_IFSOCK (stat モジュール)
  • S_IFWHT (stat モジュール)
  • S_IMODE() (stat モジュール)
  • S_IREAD (stat モジュール)
  • S_IRGRP (stat モジュール)
  • S_IROTH (stat モジュール)
  • S_IRUSR (stat モジュール)
  • S_IRWXG (stat モジュール)
  • S_IRWXO (stat モジュール)
  • S_IRWXU (stat モジュール)
  • S_ISBLK() (stat モジュール)
  • S_ISCHR() (stat モジュール)
  • S_ISDIR() (stat モジュール)
  • S_ISDOOR() (stat モジュール)
  • S_ISFIFO() (stat モジュール)
  • S_ISGID (stat モジュール)
  • S_ISLNK() (stat モジュール)
  • S_ISPORT() (stat モジュール)
  • S_ISREG() (stat モジュール)
  • S_ISSOCK() (stat モジュール)
  • S_ISUID (stat モジュール)
  • S_ISVTX (stat モジュール)
  • S_ISWHT() (stat モジュール)
  • S_IWGRP (stat モジュール)
  • S_IWOTH (stat モジュール)
  • S_IWRITE (stat モジュール)
  • S_IWUSR (stat モジュール)
  • S_IXGRP (stat モジュール)
  • S_IXOTH (stat モジュール)
  • S_IXUSR (stat モジュール)
  • safe (uuid.SafeUUID の属性)
  • safe_substitute() (string.Template のメソッド)
  • SafeChildWatcher (asyncio のクラス)
  • saferepr() (pprint モジュール)
  • SafeUUID (uuid のクラス)
  • same_files (filecmp.dircmp の属性)
  • same_quantum() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • samefile() (os.path モジュール)
    • (pathlib.Path のメソッド)
  • SameFileError
  • sameopenfile() (os.path モジュール)
  • samestat() (os.path モジュール)
  • sample() (random モジュール)
  • save() (http.cookiejar.FileCookieJar のメソッド)
  • SAVEDCWD (test.support モジュール)
  • SaveKey() (winreg モジュール)
  • SaveSignals (test.support のクラス)
  • savetty() (curses モジュール)
  • SAX2DOM (xml.dom.pulldom のクラス)
  • SAXException
  • SAXNotRecognizedException
  • SAXNotSupportedException
  • SAXParseException
  • scaleb() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • scandir() (os モジュール)
  • scanf()
  • sched (モジュール)
  • SCHED_BATCH (os モジュール)
  • SCHED_FIFO (os モジュール)
  • sched_get_priority_max() (os モジュール)
  • sched_get_priority_min() (os モジュール)
  • sched_getaffinity() (os モジュール)
  • sched_getparam() (os モジュール)
  • sched_getscheduler() (os モジュール)
  • SCHED_IDLE (os モジュール)
  • SCHED_OTHER (os モジュール)
  • sched_param (os のクラス)
  • sched_priority (os.sched_param の属性)
  • SCHED_RESET_ON_FORK (os モジュール)
  • SCHED_RR (os モジュール)
  • sched_rr_get_interval() (os モジュール)
  • sched_setaffinity() (os モジュール)
  • sched_setparam() (os モジュール)
  • sched_setscheduler() (os モジュール)
  • SCHED_SPORADIC (os モジュール)
  • sched_yield() (os モジュール)
  • scheduler (sched のクラス)
  • schema (msilib モジュール)
  • scope, [1]
  • Screen (turtle のクラス)
  • screensize() (turtle モジュール)
  • script_from_examples() (doctest モジュール)
  • scroll() (curses.window のメソッド)
  • ScrolledCanvas (turtle のクラス)
  • scrollok() (curses.window のメソッド)
  • scrypt() (hashlib モジュール)
  • sdterr
    • stdin stdout
  • seal() (unittest.mock モジュール)
  • search
    • path, module, [1], [2], [3], [4], [5], [6], [7]
  • search() (imaplib.IMAP4 のメソッド)
    • (re モジュール)
    • (re.Pattern のメソッド)
  • second (datetime.datetime の属性)
    • (datetime.time の属性)
  • seconds since the epoch
  • secrets (モジュール)
  • SECTCRE (configparser.ConfigParser の属性)
  • sections() (configparser.ConfigParser のメソッド)
  • secure (http.cookiejar.Cookie の属性)
  • secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
  • Secure Sockets Layer
  • security
    • CGI
  • see() (tkinter.ttk.Treeview のメソッド)
  • seed() (random モジュール)
  • seek() (chunk.Chunk のメソッド)
    • (io.IOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (mmap.mmap のメソッド)
  • SEEK_CUR (os モジュール)
  • SEEK_END (os モジュール)
  • SEEK_SET (os モジュール)
  • seekable() (io.IOBase のメソッド)
  • seen_greeting (smtpd.SMTPChannel の属性)
  • Select (tkinter.tix のクラス)
  • select (モジュール)
  • select() (imaplib.IMAP4 のメソッド)
    • (select モジュール)
    • (selectors.BaseSelector のメソッド)
    • (tkinter.ttk.Notebook のメソッド)
  • selected_alpn_protocol() (ssl.SSLSocket のメソッド)
  • selected_npn_protocol() (ssl.SSLSocket のメソッド)
  • selection() (tkinter.ttk.Treeview のメソッド)
  • selection_add() (tkinter.ttk.Treeview のメソッド)
  • selection_remove() (tkinter.ttk.Treeview のメソッド)
  • selection_set() (tkinter.ttk.Treeview のメソッド)
  • selection_toggle() (tkinter.ttk.Treeview のメソッド)
  • selector (urllib.request.Request の属性)
  • SelectorEventLoop (asyncio のクラス)
  • SelectorKey (selectors のクラス)
  • selectors (モジュール)
  • SelectSelector (selectors のクラス)
  • Semaphore (asyncio のクラス)
    • (multiprocessing のクラス)
    • (threading のクラス)
  • Semaphore() (multiprocessing.managers.SyncManager のメソッド)
  • semaphores, binary
  • SEMI (token モジュール)
  • send() (asyncore.dispatcher のメソッド)
    • (coroutine のメソッド)
    • (generator のメソッド)
    • (http.client.HTTPConnection のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (logging.handlers.DatagramHandler のメソッド)
    • (logging.handlers.SocketHandler のメソッド)
    • (multiprocessing.connection.Connection のメソッド)
    • (socket.socket のメソッド)
  • send_bytes() (multiprocessing.connection.Connection のメソッド)
  • send_error() (http.server.BaseHTTPRequestHandler のメソッド)
  • send_flowing_data() (formatter.writer のメソッド)
  • send_header() (http.server.BaseHTTPRequestHandler のメソッド)
  • send_hor_rule() (formatter.writer のメソッド)
  • send_label_data() (formatter.writer のメソッド)
  • send_line_break() (formatter.writer のメソッド)
  • send_literal_data() (formatter.writer のメソッド)
  • send_message() (smtplib.SMTP のメソッド)
  • send_paragraph() (formatter.writer のメソッド)
  • send_response() (http.server.BaseHTTPRequestHandler のメソッド)
  • send_response_only() (http.server.BaseHTTPRequestHandler のメソッド)
  • send_signal() (asyncio.asyncio.subprocess.Process のメソッド)
    • (asyncio.SubprocessTransport のメソッド)
    • (subprocess.Popen のメソッド)
  • sendall() (socket.socket のメソッド)
  • sendcmd() (ftplib.FTP のメソッド)
  • sendfile() (asyncio.loop のメソッド)
    • (os モジュール)
    • (socket.socket のメソッド)
    • (wsgiref.handlers.BaseHandler のメソッド)
  • SendfileNotAvailableError
  • sendmail() (smtplib.SMTP のメソッド)
  • sendmsg() (socket.socket のメソッド)
  • sendmsg_afalg() (socket.socket のメソッド)
  • sendto() (asyncio.DatagramTransport のメソッド)
    • (socket.socket のメソッド)
  • sentinel (multiprocessing.Process の属性)
    • (unittest.mock モジュール)
  • sep (os モジュール)
  • sequence
    • item
    • iteration
    • types, immutable
    • types, mutable
    • types, operations on, [1]
    • オブジェクト, [1], [2], [3], [4], [5], [6], [7], [8]
  • Sequence (collections.abc のクラス)
  • sequence (msilib モジュール)
  • Sequence (typing のクラス)
  • sequence2st() (parser モジュール)
  • SequenceMatcher (difflib のクラス), [1]
  • serializing
    • objects
  • serve_forever() (asyncio.Server のメソッド)
    • (socketserver.BaseServer のメソッド)
  • server
    • WWW, [1]
  • Server (asyncio のクラス)
  • server (http.server.BaseHTTPRequestHandler の属性)
  • server_activate() (socketserver.BaseServer のメソッド)
  • server_address (socketserver.BaseServer の属性)
  • server_bind() (socketserver.BaseServer のメソッド)
  • server_close() (socketserver.BaseServer のメソッド)
  • server_hostname (ssl.SSLSocket の属性)
  • server_side (ssl.SSLSocket の属性)
  • server_software (wsgiref.handlers.BaseHandler の属性)
  • server_version (http.server.BaseHTTPRequestHandler の属性)
    • (http.server.SimpleHTTPRequestHandler の属性)
  • ServerProxy (xmlrpc.client のクラス)
  • service_actions() (socketserver.BaseServer のメソッド)
  • session (ssl.SSLSocket の属性)
  • session_reused (ssl.SSLSocket の属性)
  • session_stats() (ssl.SSLContext のメソッド)
  • set
    • display
    • オブジェクト, [1], [2], [3]
  • Set (collections.abc のクラス)
    • (typing のクラス)
  • set (組み込みクラス)
  • Set Breakpoint
  • set type
    • オブジェクト
  • set() (asyncio.Event のメソッド)
    • (configparser.ConfigParser のメソッド)
    • (configparser.RawConfigParser のメソッド)
    • (contextvars.ContextVar のメソッド)
    • (http.cookies.Morsel のメソッド)
    • (ossaudiodev.oss_mixer_device のメソッド)
    • (test.support.EnvironmentVarGuard のメソッド)
    • (threading.Event のメソッド)
    • (tkinter.ttk.Combobox のメソッド)
    • (tkinter.ttk.Spinbox のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
  • SET_ADD (opcode)
  • set_all()
  • set_allowed_domains() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • set_alpn_protocols() (ssl.SSLContext のメソッド)
  • set_app() (wsgiref.simple_server.WSGIServer のメソッド)
  • set_asyncgen_hooks() (sys モジュール)
  • set_authorizer() (sqlite3.Connection のメソッド)
  • set_auto_history() (readline モジュール)
  • set_blocked_domains() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • set_blocking() (os モジュール)
  • set_boundary() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • set_break() (bdb.Bdb のメソッド)
  • set_charset() (email.message.Message のメソッド)
  • set_child_watcher() (asyncio モジュール)
    • (asyncio.AbstractEventLoopPolicy のメソッド)
  • set_children() (tkinter.ttk.Treeview のメソッド)
  • set_ciphers() (ssl.SSLContext のメソッド)
  • set_completer() (readline モジュール)
  • set_completer_delims() (readline モジュール)
  • set_completion_display_matches_hook() (readline モジュール)
  • set_content() (email.contentmanager モジュール)
    • (email.contentmanager.ContentManager のメソッド)
    • (email.message.EmailMessage のメソッド)
  • set_continue() (bdb.Bdb のメソッド)
  • set_cookie() (http.cookiejar.CookieJar のメソッド)
  • set_cookie_if_ok() (http.cookiejar.CookieJar のメソッド)
  • set_coroutine_origin_tracking_depth() (sys モジュール)
  • set_coroutine_wrapper() (sys モジュール)
  • set_current() (msilib.Feature のメソッド)
  • set_data() (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.SourceFileLoader のメソッド)
  • set_date() (mailbox.MaildirMessage のメソッド)
  • set_debug() (asyncio.loop のメソッド)
    • (gc モジュール)
  • set_debuglevel() (ftplib.FTP のメソッド)
    • (http.client.HTTPConnection のメソッド)
    • (nntplib.NNTP のメソッド)
    • (poplib.POP3 のメソッド)
    • (smtplib.SMTP のメソッド)
    • (telnetlib.Telnet のメソッド)
  • set_default_executor() (asyncio.loop のメソッド)
  • set_default_type() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • set_default_verify_paths() (ssl.SSLContext のメソッド)
  • set_defaults() (argparse.ArgumentParser のメソッド)
    • (optparse.OptionParser のメソッド)
  • set_ecdh_curve() (ssl.SSLContext のメソッド)
  • set_errno() (ctypes モジュール)
  • set_event_loop() (asyncio モジュール)
    • (asyncio.AbstractEventLoopPolicy のメソッド)
  • set_event_loop_policy() (asyncio モジュール)
  • set_exception() (asyncio.Future のメソッド)
    • (concurrent.futures.Future のメソッド)
  • set_exception_handler() (asyncio.loop のメソッド)
  • set_executable() (multiprocessing モジュール)
  • set_executables() (distutils.ccompiler.CCompiler のメソッド)
  • set_flags() (mailbox.MaildirMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
    • (mailbox.mboxMessage のメソッド)
  • set_from() (mailbox.mboxMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
  • set_handle_inheritable() (os モジュール)
  • set_history_length() (readline モジュール)
  • set_include_dirs() (distutils.ccompiler.CCompiler のメソッド)
  • set_info() (mailbox.MaildirMessage のメソッド)
  • set_inheritable() (os モジュール)
    • (socket.socket のメソッド)
  • set_labels() (mailbox.BabylMessage のメソッド)
  • set_last_error() (ctypes モジュール)
  • set_libraries() (distutils.ccompiler.CCompiler のメソッド)
  • set_library_dirs() (distutils.ccompiler.CCompiler のメソッド)
  • set_link_objects() (distutils.ccompiler.CCompiler のメソッド)
  • set_literal (2to3 fixer)
  • set_loader() (importlib.util モジュール)
  • set_match_tests() (test.support モジュール)
  • set_memlimit() (test.support モジュール)
  • set_next() (bdb.Bdb のメソッド)
  • set_nonstandard_attr() (http.cookiejar.Cookie のメソッド)
  • set_npn_protocols() (ssl.SSLContext のメソッド)
  • set_ok() (http.cookiejar.CookiePolicy のメソッド)
  • set_option_negotiation_callback() (telnetlib.Telnet のメソッド)
  • set_output_charset() (gettext.NullTranslations のメソッド)
  • set_package() (importlib.util モジュール)
  • set_param() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • set_pasv() (ftplib.FTP のメソッド)
  • set_payload() (email.message.Message のメソッド)
  • set_policy() (http.cookiejar.CookieJar のメソッド)
  • set_position() (xdrlib.Unpacker のメソッド)
  • set_pre_input_hook() (readline モジュール)
  • set_progress_handler() (sqlite3.Connection のメソッド)
  • set_protocol() (asyncio.BaseTransport のメソッド)
  • set_proxy() (urllib.request.Request のメソッド)
  • set_python_build() (distutils.sysconfig モジュール)
  • set_quit() (bdb.Bdb のメソッド)
  • set_recsrc() (ossaudiodev.oss_mixer_device のメソッド)
  • set_result() (asyncio.Future のメソッド)
    • (concurrent.futures.Future のメソッド)
  • set_return() (bdb.Bdb のメソッド)
  • set_running_or_notify_cancel() (concurrent.futures.Future のメソッド)
  • set_runtime_library_dirs() (distutils.ccompiler.CCompiler のメソッド)
  • set_seq1() (difflib.SequenceMatcher のメソッド)
  • set_seq2() (difflib.SequenceMatcher のメソッド)
  • set_seqs() (difflib.SequenceMatcher のメソッド)
  • set_sequences() (mailbox.MH のメソッド)
    • (mailbox.MHMessage のメソッド)
  • set_server_documentation() (xmlrpc.server.DocCGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.DocXMLRPCServer のメソッド)
  • set_server_name() (xmlrpc.server.DocCGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.DocXMLRPCServer のメソッド)
  • set_server_title() (xmlrpc.server.DocCGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.DocXMLRPCServer のメソッド)
  • set_servername_callback (ssl.SSLContext の属性)
  • set_spacing() (formatter.formatter のメソッド)
  • set_start_method() (multiprocessing モジュール)
  • set_startup_hook() (readline モジュール)
  • set_step() (bdb.Bdb のメソッド)
  • set_subdir() (mailbox.MaildirMessage のメソッド)
  • set_task_factory() (asyncio.loop のメソッド)
  • set_terminator() (asynchat.async_chat のメソッド)
  • set_threshold() (gc モジュール)
  • set_trace() (bdb モジュール)
    • (bdb.Bdb のメソッド)
    • (pdb モジュール)
    • (pdb.Pdb のメソッド)
  • set_trace_callback() (sqlite3.Connection のメソッド)
  • set_tunnel() (http.client.HTTPConnection のメソッド)
  • set_type() (email.message.Message のメソッド)
  • set_unittest_reportflags() (doctest モジュール)
  • set_unixfrom() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • set_until() (bdb.Bdb のメソッド)
  • set_url() (urllib.robotparser.RobotFileParser のメソッド)
  • set_usage() (optparse.OptionParser のメソッド)
  • set_userptr() (curses.panel.Panel のメソッド)
  • set_visible() (mailbox.BabylMessage のメソッド)
  • set_wakeup_fd() (signal モジュール)
  • set_write_buffer_limits() (asyncio.WriteTransport のメソッド)
  • setacl() (imaplib.IMAP4 のメソッド)
  • setannotation() (imaplib.IMAP4 のメソッド)
  • setattr() (組み込み関数)
  • setAttribute() (xml.dom.Element のメソッド)
  • setAttributeNode() (xml.dom.Element のメソッド)
  • setAttributeNodeNS() (xml.dom.Element のメソッド)
  • setAttributeNS() (xml.dom.Element のメソッド)
  • SetBase() (xml.parsers.expat.xmlparser のメソッド)
  • setblocking() (socket.socket のメソッド)
  • setByteStream() (xml.sax.xmlreader.InputSource のメソッド)
  • setcbreak() (tty モジュール)
  • setCharacterStream() (xml.sax.xmlreader.InputSource のメソッド)
  • setcheckinterval() (sys モジュール)
  • setcomptype() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • setContentHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • setcontext() (decimal モジュール)
  • setDaemon() (threading.Thread のメソッド)
  • setdefault() (dict のメソッド)
    • (http.cookies.Morsel のメソッド)
  • setdefaulttimeout() (socket モジュール)
  • setdlopenflags() (sys モジュール)
  • setDocumentLocator() (xml.sax.handler.ContentHandler のメソッド)
  • setDTDHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • setegid() (os モジュール)
  • setEncoding() (xml.sax.xmlreader.InputSource のメソッド)
  • setEntityResolver() (xml.sax.xmlreader.XMLReader のメソッド)
  • setErrorHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • seteuid() (os モジュール)
  • setFeature() (xml.sax.xmlreader.XMLReader のメソッド)
  • setfirstweekday() (calendar モジュール)
  • setfmt() (ossaudiodev.oss_audio_device のメソッド)
  • setFormatter() (logging.Handler のメソッド)
  • setframerate() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • setgid() (os モジュール)
  • setgroups() (os モジュール)
  • seth() (turtle モジュール)
  • setheading() (turtle モジュール)
  • sethostname() (socket モジュール)
  • SetInteger() (msilib.Record のメソッド)
  • setitem() (operator モジュール)
  • setitimer() (signal モジュール)
  • setLevel() (logging.Handler のメソッド)
    • (logging.Logger のメソッド)
  • setlocale() (locale モジュール)
  • setLocale() (xml.sax.xmlreader.XMLReader のメソッド)
  • setLoggerClass() (logging モジュール)
  • setlogmask() (syslog モジュール)
  • setLogRecordFactory() (logging モジュール)
  • setmark() (aifc.aifc のメソッド)
  • setMaxConns() (urllib.request.CacheFTPHandler のメソッド)
  • setmode() (msvcrt モジュール)
  • setName() (threading.Thread のメソッド)
  • setnchannels() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • setnframes() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • SetParamEntityParsing() (xml.parsers.expat.xmlparser のメソッド)
  • setparameters() (ossaudiodev.oss_audio_device のメソッド)
  • setparams() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • setpassword() (zipfile.ZipFile のメソッド)
  • setpgid() (os モジュール)
  • setpgrp() (os モジュール)
  • setpos() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (turtle モジュール)
    • (wave.Wave_read のメソッド)
  • setposition() (turtle モジュール)
  • setpriority() (os モジュール)
  • setprofile() (sys モジュール)
    • (threading モジュール)
  • SetProperty() (msilib.SummaryInformation のメソッド)
  • setProperty() (xml.sax.xmlreader.XMLReader のメソッド)
  • setPublicId() (xml.sax.xmlreader.InputSource のメソッド)
  • setquota() (imaplib.IMAP4 のメソッド)
  • setraw() (tty モジュール)
  • setrecursionlimit() (sys モジュール)
  • setregid() (os モジュール)
  • setresgid() (os モジュール)
  • setresuid() (os モジュール)
  • setreuid() (os モジュール)
  • setrlimit() (resource モジュール)
  • setsampwidth() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • setscrreg() (curses.window のメソッド)
  • setsid() (os モジュール)
  • setsockopt() (socket.socket のメソッド), [1], [2]
  • setstate() (codecs.IncrementalDecoder のメソッド)
    • (codecs.IncrementalEncoder のメソッド)
    • (random モジュール)
  • setStream() (logging.StreamHandler のメソッド)
  • SetStream() (msilib.Record のメソッド)
  • SetString() (msilib.Record のメソッド)
  • setswitchinterval() (in module sys)
    • (sys モジュール)
    • (test.support モジュール)
  • setSystemId() (xml.sax.xmlreader.InputSource のメソッド)
  • setsyx() (curses モジュール)
  • setTarget() (logging.handlers.MemoryHandler のメソッド)
  • settiltangle() (turtle モジュール)
  • settimeout() (socket.socket のメソッド)
  • setTimeout() (urllib.request.CacheFTPHandler のメソッド)
  • settrace() (sys モジュール)
    • (threading モジュール)
  • setuid() (os モジュール)
  • setundobuffer() (turtle モジュール)
  • setup() (distutils.core モジュール)
    • (socketserver.BaseRequestHandler のメソッド)
    • (turtle モジュール)
  • setUp() (unittest.TestCase のメソッド)
  • SETUP_ANNOTATIONS (opcode)
  • SETUP_ASYNC_WITH (opcode)
  • setup_environ() (wsgiref.handlers.BaseHandler のメソッド)
  • SETUP_EXCEPT (opcode)
  • SETUP_FINALLY (opcode)
  • SETUP_LOOP (opcode)
  • setup_python() (venv.EnvBuilder のメソッド)
  • setup_scripts() (venv.EnvBuilder のメソッド)
  • setup_testing_defaults() (wsgiref.util モジュール)
  • SETUP_WITH (opcode)
  • setUpClass() (unittest.TestCase のメソッド)
  • setupterm() (curses モジュール)
  • SetValue() (winreg モジュール)
  • SetValueEx() (winreg モジュール)
  • setworldcoordinates() (turtle モジュール)
  • setx() (turtle モジュール)
  • setxattr() (os モジュール)
  • sety() (turtle モジュール)
  • SF_APPEND (stat モジュール)
  • SF_ARCHIVED (stat モジュール)
  • SF_IMMUTABLE (stat モジュール)
  • SF_MNOWAIT (os モジュール)
  • SF_NODISKIO (os モジュール)
  • SF_NOUNLINK (stat モジュール)
  • SF_SNAPSHOT (stat モジュール)
  • SF_SYNC (os モジュール)
  • shape (memoryview の属性)
  • Shape (turtle のクラス)
  • shape() (turtle モジュール)
  • shapesize() (turtle モジュール)
  • shapetransform() (turtle モジュール)
  • share() (socket.socket のメソッド)
  • shared_ciphers() (ssl.SSLSocket のメソッド)
  • shared_object_filename() (distutils.ccompiler.CCompiler のメソッド)
  • shearfactor() (turtle モジュール)
  • Shelf (shelve のクラス)
  • shelve
    • モジュール
  • shelve (モジュール)
  • shift() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • shift_path_info() (wsgiref.util モジュール)
  • shifting
    • operation
    • operations
  • shlex (shlex のクラス)
    • (モジュール)
  • shortDescription() (unittest.TestCase のメソッド)
  • shorten() (textwrap モジュール)
  • shouldFlush() (logging.handlers.BufferingHandler のメソッド)
    • (logging.handlers.MemoryHandler のメソッド)
  • shouldStop (unittest.TestResult の属性)
  • show() (curses.panel.Panel のメソッド)
  • show_code() (dis モジュール)
  • show_compilers() (distutils.ccompiler モジュール)
  • showsyntaxerror() (code.InteractiveInterpreter のメソッド)
  • showtraceback() (code.InteractiveInterpreter のメソッド)
  • showturtle() (turtle モジュール)
  • showwarning() (warnings モジュール)
  • shuffle() (random モジュール)
  • shutdown() (concurrent.futures.Executor のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (logging モジュール)
    • (multiprocessing.managers.BaseManager のメソッド)
    • (socket.socket のメソッド)
    • (socketserver.BaseServer のメソッド)
  • shutdown_asyncgens() (asyncio.loop のメソッド)
  • shutil (モジュール)
  • side_effect (unittest.mock.Mock の属性)
  • SIG_BLOCK (signal モジュール)
  • SIG_DFL (signal モジュール)
  • SIG_IGN (signal モジュール)
  • SIG_SETMASK (signal モジュール)
  • SIG_UNBLOCK (signal モジュール)
  • SIGINT, [1]
  • siginterrupt() (signal モジュール)
  • signal
    • モジュール, [1]
  • signal (モジュール)
  • signal() (signal モジュール)
  • Signature (inspect のクラス)
  • signature (inspect.BoundArguments の属性)
  • signature() (inspect モジュール)
  • sigpending() (signal モジュール)
  • sigtimedwait() (signal モジュール)
  • sigwait() (signal モジュール)
  • sigwaitinfo() (signal モジュール)
  • simple
    • statement
  • Simple Mail Transfer Protocol
  • SimpleCookie (http.cookies のクラス)
  • simplefilter() (warnings モジュール)
  • SimpleHandler (wsgiref.handlers のクラス)
  • SimpleHTTPRequestHandler (http.server のクラス)
  • SimpleNamespace (types のクラス)
  • SimpleQueue (multiprocessing のクラス)
    • (queue のクラス)
  • SimpleXMLRPCRequestHandler (xmlrpc.server のクラス)
  • SimpleXMLRPCServer (xmlrpc.server のクラス)
  • sin() (cmath モジュール)
    • (math モジュール)
  • single dispatch
  • SingleAddressHeader (email.headerregistry のクラス)
  • singledispatch() (functools モジュール)
  • singleton
    • tuple
  • sinh() (cmath モジュール)
    • (math モジュール)
  • SIO_KEEPALIVE_VALS (socket モジュール)
  • SIO_LOOPBACK_FAST_PATH (socket モジュール)
  • SIO_RCVALL (socket モジュール)
  • site (モジュール)
  • site コマンドラインオプション
    • --user-base
    • --user-site
  • site-packages
    • directory
  • sitecustomize
    • モジュール
  • sixtofour (ipaddress.IPv6Address の属性)
  • size (struct.Struct の属性)
    • (tarfile.TarInfo の属性)
    • (tracemalloc.Statistic の属性)
    • (tracemalloc.StatisticDiff の属性)
    • (tracemalloc.Trace の属性)
  • size() (ftplib.FTP のメソッド)
    • (mmap.mmap のメソッド)
  • size_diff (tracemalloc.StatisticDiff の属性)
  • SIZE_MAX
  • Sized (collections.abc のクラス)
    • (typing のクラス)
  • sizeof() (ctypes モジュール)
  • SKIP (doctest モジュール)
  • skip() (chunk.Chunk のメソッド)
    • (unittest モジュール)
  • skip_unless_bind_unix_socket() (test.support モジュール)
  • skip_unless_symlink() (test.support モジュール)
  • skip_unless_xattr() (test.support モジュール)
  • skipIf() (unittest モジュール)
  • skipinitialspace (csv.Dialect の属性)
  • skipped (unittest.TestResult の属性)
  • skippedEntity() (xml.sax.handler.ContentHandler のメソッド)
  • SkipTest
  • skipTest() (unittest.TestCase のメソッド)
  • skipUnless() (unittest モジュール)
  • SLASH (token モジュール)
  • SLASHEQUAL (token モジュール)
  • slave() (nntplib.NNTP のメソッド)
  • sleep() (asyncio モジュール)
    • (time モジュール)
  • slice, [1]
    • assignment
    • operation
    • オブジェクト
    • 組み込み関数, [1]
  • slice (組み込みクラス)
  • slicing, [1], [2]
    • assignment
  • SMTP
    • protocol
  • SMTP (email.policy モジュール)
    • (smtplib のクラス)
  • smtp_server (smtpd.SMTPChannel の属性)
  • SMTP_SSL (smtplib のクラス)
  • smtp_state (smtpd.SMTPChannel の属性)
  • SMTPAuthenticationError
  • SMTPChannel (smtpd のクラス)
  • SMTPConnectError
  • smtpd (モジュール)
  • SMTPDataError
  • SMTPException
  • SMTPHandler (logging.handlers のクラス)
  • SMTPHeloError
  • smtplib (モジュール)
  • SMTPNotSupportedError
  • SMTPRecipientsRefused
  • SMTPResponseException
  • SMTPSenderRefused
  • SMTPServer (smtpd のクラス)
  • SMTPServerDisconnected
  • SMTPUTF8 (email.policy モジュール)
  • Snapshot (tracemalloc のクラス)
  • SND_ALIAS (winsound モジュール)
  • SND_ASYNC (winsound モジュール)
  • SND_FILENAME (winsound モジュール)
  • SND_LOOP (winsound モジュール)
  • SND_MEMORY (winsound モジュール)
  • SND_NODEFAULT (winsound モジュール)
  • SND_NOSTOP (winsound モジュール)
  • SND_NOWAIT (winsound モジュール)
  • SND_PURGE (winsound モジュール)
  • sndhdr (モジュール)
  • sni_callback (ssl.SSLContext の属性)
  • sniff() (csv.Sniffer のメソッド)
  • Sniffer (csv のクラス)
  • sock_accept() (asyncio.loop のメソッド)
  • SOCK_CLOEXEC (socket モジュール)
  • sock_connect() (asyncio.loop のメソッド)
  • SOCK_DGRAM (socket モジュール)
  • SOCK_MAX_SIZE (test.support モジュール)
  • SOCK_NONBLOCK (socket モジュール)
  • SOCK_RAW (socket モジュール)
  • SOCK_RDM (socket モジュール)
  • sock_recv() (asyncio.loop のメソッド)
  • sock_recv_into() (asyncio.loop のメソッド)
  • sock_sendall() (asyncio.loop のメソッド)
  • sock_sendfile() (asyncio.loop のメソッド)
  • SOCK_SEQPACKET (socket モジュール)
  • SOCK_STREAM (socket モジュール)
  • socket
    • オブジェクト
    • モジュール
  • socket (socketserver.BaseServer の属性)
    • (モジュール)
  • socket() (imaplib.IMAP4 のメソッド)
    • (in module socket)
    • (socket モジュール)
  • socket_type (socketserver.BaseServer の属性)
  • SocketHandler (logging.handlers のクラス)
  • socketpair() (socket モジュール)
  • sockets (asyncio.Server の属性)
  • socketserver (モジュール)
  • SocketType (socket モジュール)
  • SOL_ALG (socket モジュール)
  • SOL_RDS (socket モジュール)
  • SOMAXCONN (socket モジュール)
  • sort() (imaplib.IMAP4 のメソッド)
    • (list のメソッド)
  • sort_stats() (pstats.Stats のメソッド)
  • sortdict() (test.support モジュール)
  • sorted() (組み込み関数)
  • sortTestMethodsUsing (unittest.TestLoader の属性)
  • source (doctest.Example の属性)
    • (pdb command)
    • (shlex.shlex の属性)
  • source character set
  • SOURCE_DATE_EPOCH, [1], [2], [3], [4], [5], [6]
  • source_from_cache() (imp モジュール)
    • (importlib.util モジュール)
  • source_hash() (importlib.util モジュール)
  • SOURCE_SUFFIXES (importlib.machinery モジュール)
  • source_to_code() (importlib.abc.InspectLoader の静的メソッド)
  • SourceFileLoader (importlib.machinery のクラス)
  • sourcehook() (shlex.shlex のメソッド)
  • SourcelessFileLoader (importlib.machinery のクラス)
  • SourceLoader (importlib.abc のクラス)
  • space
    • in printf-style formatting, [1]
    • in string formatting
  • span() (re.Match のメソッド)
  • spawn() (distutils.ccompiler.CCompiler のメソッド)
    • (pty モジュール)
  • spawn_python() (test.support.script_helper モジュール)
  • spawnl() (os モジュール)
  • spawnle() (os モジュール)
  • spawnlp() (os モジュール)
  • spawnlpe() (os モジュール)
  • spawnv() (os モジュール)
  • spawnve() (os モジュール)
  • spawnvp() (os モジュール)
  • spawnvpe() (os モジュール)
  • spec_from_file_location() (importlib.util モジュール)
  • spec_from_loader() (importlib.util モジュール)
  • special
    • attribute
    • attribute, generic
  • special method
  • specified_attributes (xml.parsers.expat.xmlparser の属性)
  • speed() (ossaudiodev.oss_audio_device のメソッド)
    • (turtle モジュール)
  • Spinbox (tkinter.ttk のクラス)
  • split() (bytearray のメソッド)
    • (bytes のメソッド)
    • (os.path モジュール)
    • (re モジュール)
    • (re.Pattern のメソッド)
    • (shlex モジュール)
    • (str のメソッド)
  • split_quoted() (distutils.util モジュール)
  • splitdrive() (os.path モジュール)
  • splitext() (os.path モジュール)
  • splitlines() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • SplitResult (urllib.parse のクラス)
  • SplitResultBytes (urllib.parse のクラス)
  • SpooledTemporaryFile() (tempfile モジュール)
  • sprintf-style formatting, [1]
  • spwd (モジュール)
  • sqlite3 (モジュール)
  • sqlite_version (sqlite3 モジュール)
  • sqlite_version_info (sqlite3 モジュール)
  • sqrt() (cmath モジュール)
    • (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (math モジュール)
  • SSL
  • ssl (モジュール)
  • SSL_CERT_FILE
  • SSL_CERT_PATH
  • ssl_version (ftplib.FTP_TLS の属性)
  • SSLCertVerificationError
  • SSLContext (ssl のクラス)
  • SSLEOFError
  • SSLError
  • SSLErrorNumber (ssl のクラス)
  • SSLObject (ssl のクラス)
  • sslobject_class (ssl.SSLContext の属性)
  • SSLSession (ssl のクラス)
  • SSLSocket (ssl のクラス)
  • sslsocket_class (ssl.SSLContext の属性)
  • SSLSyscallError
  • SSLv3 (ssl.TLSVersion の属性)
  • SSLWantReadError
  • SSLWantWriteError
  • SSLZeroReturnError
  • st() (turtle モジュール)
  • st2list() (parser モジュール)
  • st2tuple() (parser モジュール)
  • st_atime (os.stat_result の属性)
  • ST_ATIME (stat モジュール)
  • st_atime_ns (os.stat_result の属性)
  • st_birthtime (os.stat_result の属性)
  • st_blksize (os.stat_result の属性)
  • st_blocks (os.stat_result の属性)
  • st_creator (os.stat_result の属性)
  • st_ctime (os.stat_result の属性)
  • ST_CTIME (stat モジュール)
  • st_ctime_ns (os.stat_result の属性)
  • st_dev (os.stat_result の属性)
  • ST_DEV (stat モジュール)
  • st_file_attributes (os.stat_result の属性)
  • st_flags (os.stat_result の属性)
  • st_fstype (os.stat_result の属性)
  • st_gen (os.stat_result の属性)
  • st_gid (os.stat_result の属性)
  • ST_GID (stat モジュール)
  • st_ino (os.stat_result の属性)
  • ST_INO (stat モジュール)
  • st_mode (os.stat_result の属性)
  • ST_MODE (stat モジュール)
  • st_mtime (os.stat_result の属性)
  • ST_MTIME (stat モジュール)
  • st_mtime_ns (os.stat_result の属性)
  • st_nlink (os.stat_result の属性)
  • ST_NLINK (stat モジュール)
  • st_rdev (os.stat_result の属性)
  • st_rsize (os.stat_result の属性)
  • st_size (os.stat_result の属性)
  • ST_SIZE (stat モジュール)
  • st_type (os.stat_result の属性)
  • st_uid (os.stat_result の属性)
  • ST_UID (stat モジュール)
  • stack
    • execution
    • trace
  • stack (traceback.TracebackException の属性)
  • stack viewer
  • stack() (inspect モジュール)
  • stack_effect() (dis モジュール)
  • stack_size() (_thread モジュール)
    • (threading モジュール)
  • stackable
    • streams
  • StackSummary (traceback のクラス)
  • stamp() (turtle モジュール)
  • standard
    • output
  • Standard C
  • standard input
  • standard_b64decode() (base64 モジュール)
  • standard_b64encode() (base64 モジュール)
  • standarderror (2to3 fixer)
  • standend() (curses.window のメソッド)
  • standout() (curses.window のメソッド)
  • STAR (token モジュール)
  • STAREQUAL (token モジュール)
  • starmap() (itertools モジュール)
    • (multiprocessing.pool.Pool のメソッド)
  • starmap_async() (multiprocessing.pool.Pool のメソッド)
  • start (range の属性)
    • (UnicodeError の属性)
    • (slice object attribute), [1]
  • start() (logging.handlers.QueueListener のメソッド)
    • (multiprocessing.Process のメソッド)
    • (multiprocessing.managers.BaseManager のメソッド)
    • (re.Match のメソッド)
    • (threading.Thread のメソッド)
    • (tkinter.ttk.Progressbar のメソッド)
    • (tracemalloc モジュール)
    • (xml.etree.ElementTree.TreeBuilder のメソッド)
  • start_color() (curses モジュール)
  • start_component() (msilib.Directory のメソッド)
  • start_new_thread() (_thread モジュール)
  • start_server() (asyncio モジュール)
  • start_serving() (asyncio.Server のメソッド)
  • start_threads() (test.support モジュール)
  • start_tls() (asyncio.loop のメソッド)
  • start_unix_server() (asyncio モジュール)
  • StartCdataSectionHandler() (xml.parsers.expat.xmlparser のメソッド)
  • StartDoctypeDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • startDocument() (xml.sax.handler.ContentHandler のメソッド)
  • startElement() (xml.sax.handler.ContentHandler のメソッド)
  • StartElementHandler() (xml.parsers.expat.xmlparser のメソッド)
  • startElementNS() (xml.sax.handler.ContentHandler のメソッド)
  • STARTF_USESHOWWINDOW (subprocess モジュール)
  • STARTF_USESTDHANDLES (subprocess モジュール)
  • startfile() (os モジュール)
  • StartNamespaceDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • startPrefixMapping() (xml.sax.handler.ContentHandler のメソッド)
  • startswith() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • startTest() (unittest.TestResult のメソッド)
  • startTestRun() (unittest.TestResult のメソッド)
  • starttls() (imaplib.IMAP4 のメソッド)
    • (nntplib.NNTP のメソッド)
    • (smtplib.SMTP のメソッド)
  • STARTUPINFO (subprocess のクラス)
  • stat
    • モジュール
  • stat (モジュール)
  • stat() (nntplib.NNTP のメソッド)
    • (os モジュール)
    • (os.DirEntry のメソッド)
    • (pathlib.Path のメソッド)
    • (poplib.POP3 のメソッド)
  • stat_result (os のクラス)
  • state() (tkinter.ttk.Widget のメソッド)
  • statement
    • assignment, [1]
    • assignment, annotated
    • assignment, augmented
    • compound
    • expression
    • future
    • loop, [1], [2], [3]
    • simple
  • statement grouping
  • staticmethod
    • 組み込み関数
  • staticmethod() (組み込み関数)
  • Statistic (tracemalloc のクラス)
  • StatisticDiff (tracemalloc のクラス)
  • statistics (モジュール)
  • statistics() (tracemalloc.Snapshot のメソッド)
  • StatisticsError
  • Stats (pstats のクラス)
  • status (http.client.HTTPResponse の属性)
  • status() (imaplib.IMAP4 のメソッド)
  • statvfs() (os モジュール)
  • STD_ERROR_HANDLE (subprocess モジュール)
  • STD_INPUT_HANDLE (subprocess モジュール)
  • STD_OUTPUT_HANDLE (subprocess モジュール)
  • StdButtonBox (tkinter.tix のクラス)
  • stderr (asyncio.asyncio.subprocess.Process の属性)
    • (in module sys), [1]
    • (subprocess.CalledProcessError の属性)
    • (subprocess.CompletedProcess の属性)
    • (subprocess.Popen の属性)
    • (subprocess.TimeoutExpired の属性)
    • (sys モジュール)
  • stdev() (statistics モジュール)
  • stdin
    • stdout sdterr
  • stdin (asyncio.asyncio.subprocess.Process の属性)
    • (in module sys), [1]
    • (subprocess.Popen の属性)
    • (sys モジュール)
  • stdio
  • stdout
    • sdterr, stdin
  • stdout (asyncio.asyncio.subprocess.Process の属性)
    • (in module sys), [1]
  • STDOUT (subprocess モジュール)
  • stdout (subprocess.CalledProcessError の属性)
    • (subprocess.CompletedProcess の属性)
    • (subprocess.Popen の属性)
    • (subprocess.TimeoutExpired の属性)
    • (sys モジュール)
  • step (pdb command)
    • (range の属性)
    • (slice object attribute), [1]
  • step() (tkinter.ttk.Progressbar のメソッド)
  • stereocontrols() (ossaudiodev.oss_mixer_device のメソッド)
  • stls() (poplib.POP3 のメソッド)
  • stop (range の属性)
    • (slice object attribute), [1]
  • stop() (asyncio.loop のメソッド)
    • (logging.handlers.QueueListener のメソッド)
    • (tkinter.ttk.Progressbar のメソッド)
    • (tracemalloc モジュール)
    • (unittest.TestResult のメソッド)
  • stop_here() (bdb.Bdb のメソッド)
  • StopAsyncIteration
    • 例外
  • StopIteration
    • 例外, [1]
  • stopListening() (logging.config モジュール)
  • stopTest() (unittest.TestResult のメソッド)
  • stopTestRun() (unittest.TestResult のメソッド)
  • storbinary() (ftplib.FTP のメソッド)
  • store() (imaplib.IMAP4 のメソッド)
  • STORE_ACTIONS (optparse.Option の属性)
  • STORE_ATTR (opcode)
  • STORE_DEREF (opcode)
  • STORE_FAST (opcode)
  • STORE_GLOBAL (opcode)
  • STORE_NAME (opcode)
  • STORE_SUBSCR (opcode)
  • storlines() (ftplib.FTP のメソッド)
  • str (built-in class)
    • (see also string)
  • str (組み込みクラス)
  • str() (locale モジュール)
  • strcoll() (locale モジュール)
  • StreamError
  • StreamHandler (logging のクラス)
  • StreamReader (asyncio のクラス)
    • (codecs のクラス)
  • streamreader (codecs.CodecInfo の属性)
  • StreamReaderWriter (codecs のクラス)
  • StreamRecoder (codecs のクラス)
  • StreamRequestHandler (socketserver のクラス)
  • streams
    • stackable
  • StreamWriter (asyncio のクラス)
    • (codecs のクラス)
  • streamwriter (codecs.CodecInfo の属性)
  • strerror (OSError の属性)
  • strerror()
    • (os モジュール)
  • strftime() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (time モジュール)
  • strict (csv.Dialect の属性)
    • (email.policy モジュール)
  • strict_domain (http.cookiejar.DefaultCookiePolicy の属性)
  • strict_errors() (codecs モジュール)
  • strict_ns_domain (http.cookiejar.DefaultCookiePolicy の属性)
  • strict_ns_set_initial_dollar (http.cookiejar.DefaultCookiePolicy の属性)
  • strict_ns_set_path (http.cookiejar.DefaultCookiePolicy の属性)
  • strict_ns_unverifiable (http.cookiejar.DefaultCookiePolicy の属性)
  • strict_rfc2965_unverifiable (http.cookiejar.DefaultCookiePolicy の属性)
  • strides (memoryview の属性)
  • string
    • PyObject_Str (C function)
    • __format__() (object method)
    • __str__() (object method)
    • conversion, [1]
    • format() (built-in function)
    • formatted literal
    • formatting, printf
    • immutable sequences
    • interpolated literal
    • interpolation, printf
    • item
    • methods
    • object representation
    • str (built-in class)
    • str() (built-in function)
    • text sequence type
    • オブジェクト, [1], [2]
    • モジュール
  • string (re.Match の属性)
  • STRING (token モジュール)
  • string (モジュール)
  • string literal
  • string_at() (ctypes モジュール)
  • StringIO (io のクラス)
  • stringprep (モジュール)
  • strings, documentation, [1]
  • strip() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • strip_dirs() (pstats.Stats のメソッド)
  • strip_python_strerr() (test.support モジュール)
  • stripspaces (curses.textpad.Textbox の属性)
  • strptime() (datetime.datetime のクラスメソッド)
    • (time モジュール)
  • strtobool() (distutils.util モジュール)
  • struct
    • モジュール
  • Struct (struct のクラス)
  • struct (モジュール)
  • struct sequence
  • struct_time (time のクラス)
  • Structure (ctypes のクラス)
  • structures
    • C
  • strxfrm() (locale モジュール)
  • STType (parser モジュール)
  • style
    • coding
  • Style (tkinter.ttk のクラス)
  • sub() (operator モジュール)
    • (re モジュール)
    • (re.Pattern のメソッド)
  • sub_commands (distutils.cmd.Command の属性)
  • subclassing
    • immutable types
  • subdirs (filecmp.dircmp の属性)
  • SubElement() (xml.etree.ElementTree モジュール)
  • submit() (concurrent.futures.Executor のメソッド)
  • submodule_search_locations (importlib.machinery.ModuleSpec の属性)
  • subn() (re モジュール)
    • (re.Pattern のメソッド)
  • subnet_of() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • subnets() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • Subnormal (decimal のクラス)
  • suboffsets (memoryview の属性)
  • subpad() (curses.window のメソッド)
  • subprocess (モジュール)
  • subprocess_exec() (asyncio.loop のメソッド)
  • subprocess_shell() (asyncio.loop のメソッド)
  • SubprocessError
  • SubprocessProtocol (asyncio のクラス)
  • SubprocessTransport (asyncio のクラス)
  • subscribe() (imaplib.IMAP4 のメソッド)
  • subscript
    • assignment
    • operation
  • subscription, [1], [2], [3]
    • assignment
  • subsequent_indent (textwrap.TextWrapper の属性)
  • subst_vars() (distutils.util モジュール)
  • substitute() (string.Template のメソッド)
  • subTest() (unittest.TestCase のメソッド)
  • subtract() (collections.Counter のメソッド)
    • (decimal.Context のメソッド)
  • subtraction
  • subtype (email.headerregistry.ContentTypeHeader の属性)
  • subwin() (curses.window のメソッド)
  • successful() (multiprocessing.pool.AsyncResult のメソッド)
  • suffix_map (mimetypes モジュール)
    • (mimetypes.MimeTypes の属性)
  • suite
  • suite() (parser モジュール)
  • suiteClass (unittest.TestLoader の属性)
  • sum() (組み込み関数)
  • sum_list()
  • sum_sequence(), [1]
  • summarize() (doctest.DocTestRunner のメソッド)
  • summarize_address_range() (ipaddress モジュール)
  • sunau (モジュール)
  • super (pyclbr.Class の属性)
  • super() (組み込み関数)
  • supernet() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • supernet_of() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • supports_bytes_environ (os モジュール)
  • supports_dir_fd (os モジュール)
  • supports_effective_ids (os モジュール)
  • supports_fd (os モジュール)
  • supports_follow_symlinks (os モジュール)
  • supports_unicode_filenames (os.path モジュール)
  • SupportsAbs (typing のクラス)
  • SupportsBytes (typing のクラス)
  • SupportsComplex (typing のクラス)
  • SupportsFloat (typing のクラス)
  • SupportsInt (typing のクラス)
  • SupportsRound (typing のクラス)
  • suppress() (contextlib モジュール)
  • SuppressCrashReport (test.support のクラス)
  • SW_HIDE (subprocess モジュール)
  • swap_attr() (test.support モジュール)
  • swap_item() (test.support モジュール)
  • swapcase() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • sym_name (symbol モジュール)
  • Symbol (symtable のクラス)
  • symbol (モジュール)
  • SymbolTable (symtable のクラス)
  • symlink() (os モジュール)
  • symlink_to() (pathlib.Path のメソッド)
  • symmetric_difference() (frozenset のメソッド)
  • symmetric_difference_update() (frozenset のメソッド)
  • symtable (モジュール)
  • symtable() (symtable モジュール)
  • sync() (dbm.dumb.dumbdbm のメソッド)
    • (dbm.gnu.gdbm のメソッド)
    • (os モジュール)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (shelve.Shelf のメソッド)
  • syncdown() (curses.window のメソッド)
  • synchronized() (multiprocessing.sharedctypes モジュール)
  • SyncManager (multiprocessing.managers のクラス)
  • syncok() (curses.window のメソッド)
  • syncup() (curses.window のメソッド)
  • syntax
  • SyntaxErr
  • SyntaxError
  • SyntaxWarning
  • sys
    • モジュール, [1], [2], [3], [4], [5], [6]
  • sys (モジュール)
  • sys.exc_info
  • sys.last_traceback
  • sys.meta_path
  • sys.modules
  • sys.path
  • sys.path_hooks
  • sys.path_importer_cache
  • sys.stderr
  • sys.stdin
  • sys.stdout
  • sys_exc (2to3 fixer)
  • sys_version (http.server.BaseHTTPRequestHandler の属性)
  • sysconf() (os モジュール)
  • sysconf_names (os モジュール)
  • sysconfig (モジュール)
  • syslog (モジュール)
  • syslog() (syslog モジュール)
  • SysLogHandler (logging.handlers のクラス)
  • system() (os モジュール)
    • (platform モジュール)
  • system_alias() (platform モジュール)
  • system_must_validate_cert() (test.support モジュール)
  • SystemError
    • (built-in exception), [1]
  • SystemExit
    • (built-in exception)
  • systemId (xml.dom.DocumentType の属性)
  • SystemRandom (random のクラス)
    • (secrets のクラス)
  • SystemRoot

T

  • T_FMT (locale モジュール)
  • T_FMT_AMPM (locale モジュール)
  • tab
  • tab() (tkinter.ttk.Notebook のメソッド)
  • TabError
  • tabnanny (モジュール)
  • tabs() (tkinter.ttk.Notebook のメソッド)
  • tabsize (textwrap.TextWrapper の属性)
  • tabular
    • data
  • tag (xml.etree.ElementTree.Element の属性)
  • tag_bind() (tkinter.ttk.Treeview のメソッド)
  • tag_configure() (tkinter.ttk.Treeview のメソッド)
  • tag_has() (tkinter.ttk.Treeview のメソッド)
  • tagName (xml.dom.Element の属性)
  • tail (xml.etree.ElementTree.Element の属性)
  • take_snapshot() (tracemalloc モジュール)
  • takewhile() (itertools モジュール)
  • tan() (cmath モジュール)
    • (math モジュール)
  • tanh() (cmath モジュール)
    • (math モジュール)
  • TarError
  • TarFile (tarfile のクラス), [1]
  • tarfile (モジュール)
  • tarfile コマンドラインオプション
    • --create <tarfile> <source1> ... <sourceN>
    • --extract <tarfile> [<output_dir>]
    • --list <tarfile>
    • --test <tarfile>
    • -c <tarfile> <source1> ... <sourceN>
    • -e <tarfile> [<output_dir>]
    • -l <tarfile>
    • -t <tarfile>
    • -v, --verbose
  • target
    • deletion
    • list, [1], [2]
    • list assignment
    • list, deletion
    • loop control
  • target (xml.dom.ProcessingInstruction の属性)
  • TarInfo (tarfile のクラス)
  • Task (asyncio のクラス)
  • task_done() (asyncio.Queue のメソッド)
    • (multiprocessing.JoinableQueue のメソッド)
    • (queue.Queue のメソッド)
  • tau (cmath モジュール)
    • (math モジュール)
  • tb_frame (traceback attribute)
  • tb_lasti (traceback attribute)
  • tb_lineno (traceback attribute)
  • tb_locals (unittest.TestResult の属性)
  • tb_next (traceback attribute)
  • tbreak (pdb command)
  • tcdrain() (termios モジュール)
  • tcflow() (termios モジュール)
  • tcflush() (termios モジュール)
  • tcgetattr() (termios モジュール)
  • tcgetpgrp() (os モジュール)
  • Tcl() (tkinter モジュール)
  • TCL_LIBRARY
  • TCPServer (socketserver のクラス)
  • tcsendbreak() (termios モジュール)
  • tcsetattr() (termios モジュール)
  • tcsetpgrp() (os モジュール)
  • tearDown() (unittest.TestCase のメソッド)
  • tearDownClass() (unittest.TestCase のメソッド)
  • tee() (itertools モジュール)
  • tell() (aifc.aifc のメソッド), [1]
    • (chunk.Chunk のメソッド)
    • (io.IOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (mmap.mmap のメソッド)
    • (sunau.AU_read のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_read のメソッド)
    • (wave.Wave_write のメソッド)
  • Telnet (telnetlib のクラス)
  • telnetlib (モジュール)
  • TEMP
  • temp_cwd() (test.support モジュール)
  • temp_dir() (test.support モジュール)
  • temp_umask() (test.support モジュール)
  • tempdir (tempfile モジュール)
  • tempfile (モジュール)
  • Template (pipes のクラス)
    • (string のクラス)
  • template (string.Template の属性)
  • temporary
    • file
    • file name
  • TemporaryDirectory() (tempfile モジュール)
  • TemporaryFile() (tempfile モジュール)
  • teredo (ipaddress.IPv6Address の属性)
  • TERM, [1]
  • termattrs() (curses モジュール)
  • terminal_size (os のクラス)
  • terminate() (asyncio.asyncio.subprocess.Process のメソッド)
    • (asyncio.SubprocessTransport のメソッド)
    • (multiprocessing.Process のメソッド)
    • (multiprocessing.pool.Pool のメソッド)
    • (subprocess.Popen のメソッド)
  • termination model
  • termios (モジュール)
  • termname() (curses モジュール)
  • ternary
    • operator
  • test
    • identity
    • membership
  • test (doctest.DocTestFailure の属性)
    • (doctest.UnexpectedException の属性)
    • (モジュール)
  • test() (cgi モジュール)
  • test.support (モジュール)
  • test.support.script_helper (モジュール)
  • TEST_DATA_DIR (test.support モジュール)
  • TEST_HOME_DIR (test.support モジュール)
  • TEST_SUPPORT_DIR (test.support モジュール)
  • TestCase (unittest のクラス)
  • TestFailed
  • testfile() (doctest モジュール)
  • TESTFN (test.support モジュール)
  • TESTFN_ENCODING (test.support モジュール)
  • TESTFN_NONASCII (test.support モジュール)
  • TESTFN_UNDECODABLE (test.support モジュール)
  • TESTFN_UNENCODABLE (test.support モジュール)
  • TESTFN_UNICODE (test.support モジュール)
  • TestHandler (test.support のクラス)
  • TestLoader (unittest のクラス)
  • testMethodPrefix (unittest.TestLoader の属性)
  • testmod() (doctest モジュール)
  • testNamePatterns (unittest.TestLoader の属性)
  • TestResult (unittest のクラス)
  • tests (imghdr モジュール)
  • testsource() (doctest モジュール)
  • testsRun (unittest.TestResult の属性)
  • TestSuite (unittest のクラス)
  • testzip() (zipfile.ZipFile のメソッド)
  • text (msilib モジュール)
    • (traceback.TracebackException の属性)
  • Text (typing のクラス)
  • text (xml.etree.ElementTree.Element の属性)
  • text encoding
  • text file
  • text mode
  • text() (cgitb モジュール)
    • (msilib.Dialog のメソッド)
  • text_factory (sqlite3.Connection の属性)
  • Textbox (curses.textpad のクラス)
  • TextCalendar (calendar のクラス)
  • textdomain() (gettext モジュール)
    • (locale モジュール)
  • TextFile (distutils.text_file のクラス)
  • textinput() (turtle モジュール)
  • TextIO (typing のクラス)
  • TextIOBase (io のクラス)
  • TextIOWrapper (io のクラス)
  • TextTestResult (unittest のクラス)
  • TextTestRunner (unittest のクラス)
  • textwrap (モジュール)
  • TextWrapper (textwrap のクラス)
  • theme_create() (tkinter.ttk.Style のメソッド)
  • theme_names() (tkinter.ttk.Style のメソッド)
  • theme_settings() (tkinter.ttk.Style のメソッド)
  • theme_use() (tkinter.ttk.Style のメソッド)
  • THOUSEP (locale モジュール)
  • Thread (threading のクラス)
  • thread() (imaplib.IMAP4 のメソッド)
  • thread_info (sys モジュール)
  • thread_time() (time モジュール)
  • thread_time_ns() (time モジュール)
  • threading (モジュール)
  • threading_cleanup() (test.support モジュール)
  • threading_setup() (test.support モジュール)
  • ThreadingHTTPServer (http.server のクラス)
  • ThreadingMixIn (socketserver のクラス)
  • ThreadingTCPServer (socketserver のクラス)
  • ThreadingUDPServer (socketserver のクラス)
  • ThreadPoolExecutor (concurrent.futures のクラス)
  • threads
    • POSIX
  • throw (2to3 fixer)
  • throw() (coroutine のメソッド)
    • (generator のメソッド)
  • ticket_lifetime_hint (ssl.SSLSession の属性)
  • tigetflag() (curses モジュール)
  • tigetnum() (curses モジュール)
  • tigetstr() (curses モジュール)
  • TILDE (token モジュール)
  • tilt() (turtle モジュール)
  • tiltangle() (turtle モジュール)
  • time (datetime のクラス)
    • (ssl.SSLSession の属性)
    • (モジュール)
  • time() (asyncio.loop のメソッド)
    • (datetime.datetime のメソッド)
    • (time モジュール)
  • Time2Internaldate() (imaplib モジュール)
  • time_ns() (time モジュール)
  • timedelta (datetime のクラス)
  • TimedRotatingFileHandler (logging.handlers のクラス)
  • timegm() (calendar モジュール)
  • timeit (モジュール)
  • timeit コマンドラインオプション
    • -h, --help
    • -n N, --number=N
    • -p, --process
    • -r N, --repeat=N
    • -s S, --setup=S
    • -u, --unit=U
    • -v, --verbose
  • timeit() (timeit モジュール)
    • (timeit.Timer のメソッド)
  • timeout
    • (socketserver.BaseServer の属性)
    • (ssl.SSLSession の属性)
    • (subprocess.TimeoutExpired の属性)
  • timeout() (curses.window のメソッド)
  • TIMEOUT_MAX (_thread モジュール)
    • (threading モジュール)
  • TimeoutError, [1], [2], [3]
  • TimeoutExpired
  • Timer (threading のクラス)
    • (timeit のクラス)
  • TimerHandle (asyncio のクラス)
  • times() (os モジュール)
  • TIMESTAMP (py_compile.PycInvalidationMode の属性)
  • timestamp() (datetime.datetime のメソッド)
  • timetuple() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
  • timetz() (datetime.datetime のメソッド)
  • timezone (datetime のクラス)
    • (time モジュール)
  • title() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
    • (turtle モジュール)
  • Tix
  • tix_addbitmapdir() (tkinter.tix.tixCommand のメソッド)
  • tix_cget() (tkinter.tix.tixCommand のメソッド)
  • tix_configure() (tkinter.tix.tixCommand のメソッド)
  • tix_filedialog() (tkinter.tix.tixCommand のメソッド)
  • tix_getbitmap() (tkinter.tix.tixCommand のメソッド)
  • tix_getimage() (tkinter.tix.tixCommand のメソッド)
  • TIX_LIBRARY
  • tix_option_get() (tkinter.tix.tixCommand のメソッド)
  • tix_resetoptions() (tkinter.tix.tixCommand のメソッド)
  • tixCommand (tkinter.tix のクラス)
  • Tk
    • (tkinter のクラス)
    • (tkinter.tix のクラス)
  • Tk Option Data Types
  • TK_LIBRARY
  • Tkinter
  • tkinter (モジュール)
  • tkinter.scrolledtext (モジュール)
  • tkinter.tix (モジュール)
  • tkinter.ttk (モジュール)
  • TList (tkinter.tix のクラス)
  • TLS
  • TLSv1 (ssl.TLSVersion の属性)
  • TLSv1_1 (ssl.TLSVersion の属性)
  • TLSv1_2 (ssl.TLSVersion の属性)
  • TLSv1_3 (ssl.TLSVersion の属性)
  • TLSVersion (ssl のクラス)
  • TMP
  • TMPDIR
  • to_bytes() (int のメソッド)
  • to_eng_string() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • to_integral() (decimal.Decimal のメソッド)
  • to_integral_exact() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • to_integral_value() (decimal.Decimal のメソッド)
  • to_sci_string() (decimal.Context のメソッド)
  • ToASCII() (encodings.idna モジュール)
  • tobuf() (tarfile.TarInfo のメソッド)
  • tobytes() (array.array のメソッド)
    • (memoryview のメソッド)
  • today() (datetime.date のクラスメソッド)
    • (datetime.datetime のクラスメソッド)
  • tofile() (array.array のメソッド)
  • tok_name (token モジュール)
  • token
    • (shlex.shlex の属性)
    • (モジュール)
  • token_bytes() (secrets モジュール)
  • token_hex() (secrets モジュール)
  • token_urlsafe() (secrets モジュール)
  • TokenError
  • tokenize (モジュール)
  • tokenize コマンドラインオプション
    • -e, --exact
    • -h, --help
  • tokenize() (tokenize モジュール)
  • tolist() (array.array のメソッド)
    • (memoryview のメソッド)
    • (parser.ST のメソッド)
  • tomono() (audioop モジュール)
  • toordinal() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
  • top() (curses.panel.Panel のメソッド)
    • (poplib.POP3 のメソッド)
  • top_panel() (curses.panel モジュール)
  • toprettyxml() (xml.dom.minidom.Node のメソッド)
  • tostereo() (audioop モジュール)
  • tostring() (array.array のメソッド)
    • (xml.etree.ElementTree モジュール)
  • tostringlist() (xml.etree.ElementTree モジュール)
  • total_changes (sqlite3.Connection の属性)
  • total_ordering() (functools モジュール)
  • total_seconds() (datetime.timedelta のメソッド)
  • totuple() (parser.ST のメソッド)
  • touch() (pathlib.Path のメソッド)
  • touchline() (curses.window のメソッド)
  • touchwin() (curses.window のメソッド)
  • tounicode() (array.array のメソッド)
  • ToUnicode() (encodings.idna モジュール)
  • towards() (turtle モジュール)
  • toxml() (xml.dom.minidom.Node のメソッド)
  • tp_as_async (C のメンバ変数)
  • tp_as_mapping (C のメンバ変数)
  • tp_as_number (C のメンバ変数)
  • tp_as_sequence (C のメンバ変数)
  • tparm() (curses モジュール)
  • trace
    • stack
  • Trace (trace のクラス)
    • (tracemalloc のクラス)
  • trace (モジュール)
  • trace function, [1], [2]
  • trace コマンドラインオプション
    • --help
    • --ignore-dir=<dir>
    • --ignore-module=<mod>
    • --version
    • -C, --coverdir=<dir>
    • -R, --no-report
    • -T, --trackcalls
    • -c, --count
    • -f, --file=<file>
    • -g, --timing
    • -l, --listfuncs
    • -m, --missing
    • -r, --report
    • -s, --summary
    • -t, --trace
  • trace() (inspect モジュール)
  • trace_dispatch() (bdb.Bdb のメソッド)
  • traceback
    • オブジェクト, [1], [2], [3], [4]
  • Traceback (tracemalloc のクラス)
  • traceback (tracemalloc.Statistic の属性)
    • (tracemalloc.StatisticDiff の属性)
    • (tracemalloc.Trace の属性)
    • (モジュール)
  • traceback_limit (tracemalloc.Snapshot の属性)
    • (wsgiref.handlers.BaseHandler の属性)
  • TracebackException (traceback のクラス)
  • tracebacklimit (sys モジュール)
  • tracebacks
    • in CGI scripts
  • TracebackType (types のクラス)
  • tracemalloc (モジュール)
  • tracer() (turtle モジュール)
  • traces (tracemalloc.Snapshot の属性)
  • trailing
    • comma
  • transfercmd() (ftplib.FTP のメソッド)
  • transient_internet() (test.support モジュール)
  • TransientResource (test.support のクラス)
  • translate() (bytearray のメソッド)
    • (bytes のメソッド)
    • (fnmatch モジュール)
    • (str のメソッド)
  • translation() (gettext モジュール)
  • Transport (asyncio のクラス)
  • transport (asyncio.StreamWriter の属性)
  • Transport Layer Security
  • traverseproc (C のデータ型)
  • Tree (tkinter.tix のクラス)
  • TreeBuilder (xml.etree.ElementTree のクラス)
  • Treeview (tkinter.ttk のクラス)
  • triangular() (random モジュール)
  • triple-quoted string, [1]
  • True, [1], [2]
  • true
  • True (組み込み変数)
  • truediv() (operator モジュール)
  • trunc() (in module math)
    • (math モジュール)
  • truncate() (io.IOBase のメソッド)
    • (os モジュール)
  • truth
    • value
  • truth() (operator モジュール)
  • try
    • 文, [1], [2]
  • ttk
  • tty
    • I/O control
  • tty (モジュール)
  • ttyname() (os モジュール)
  • tuple
    • display
    • empty, [1]
    • singleton
    • オブジェクト, [1], [2], [3], [4], [5], [6]
    • 組み込み関数, [1]
  • Tuple (typing モジュール)
  • tuple (組み込みクラス)
  • tuple2st() (parser モジュール)
  • tuple_params (2to3 fixer)
  • Turtle (turtle のクラス)
  • turtle (モジュール)
  • turtledemo (モジュール)
  • turtles() (turtle モジュール)
  • TurtleScreen (turtle のクラス)
  • turtlesize() (turtle モジュール)
  • type, [1]
    • Boolean
    • data
    • hierarchy
    • immutable data
    • operations on dictionary
    • operations on list
    • オブジェクト, [1], [2]
    • 組み込み関数, [1], [2], [3]
  • type (optparse.Option の属性)
    • (socket.socket の属性)
    • (tarfile.TarInfo の属性)
  • Type (typing のクラス)
  • type (urllib.request.Request の属性)
    • (組み込みクラス)
  • type alias
  • type hint
  • type of an object
  • TYPE_CHECKER (optparse.Option の属性)
  • TYPE_CHECKING (typing モジュール)
  • typeahead() (curses モジュール)
  • typecode (array.array の属性)
  • typecodes (array モジュール)
  • TYPED_ACTIONS (optparse.Option の属性)
  • typed_subpart_iterator() (email.iterators モジュール)
  • TypeError
    • 例外
  • types
    • built-in
    • immutable sequence
    • mutable sequence
    • operations on integer
    • operations on mapping
    • operations on numeric
    • operations on sequence, [1]
    • モジュール
  • types (2to3 fixer)
  • TYPES (optparse.Option の属性)
  • types (モジュール)
  • types, internal
  • types_map (mimetypes モジュール)
    • (mimetypes.MimeTypes の属性)
  • types_map_inv (mimetypes.MimeTypes の属性)
  • TypeVar (typing のクラス)
  • typing (モジュール)
  • TZ, [1], [2], [3], [4], [5]
  • tzinfo (datetime のクラス)
    • (datetime.datetime の属性)
    • (datetime.time の属性)
  • tzname (time モジュール)
  • tzname() (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (datetime.timezone のメソッド)
    • (datetime.tzinfo のメソッド)
  • tzset() (time モジュール)

U

  • u"
    • string literal
  • u'
    • string literal
  • u-LAW, [1], [2]
  • ucd_3_2_0 (unicodedata モジュール)
  • udata (select.kevent の属性)
  • UDPServer (socketserver のクラス)
  • UF_APPEND (stat モジュール)
  • UF_COMPRESSED (stat モジュール)
  • UF_HIDDEN (stat モジュール)
  • UF_IMMUTABLE (stat モジュール)
  • UF_NODUMP (stat モジュール)
  • UF_NOUNLINK (stat モジュール)
  • UF_OPAQUE (stat モジュール)
  • uid (tarfile.TarInfo の属性)
  • uid() (imaplib.IMAP4 のメソッド)
  • uidl() (poplib.POP3 のメソッド)
  • ulaw2lin() (audioop モジュール)
  • ULONG_MAX
  • umask() (os モジュール)
  • unalias (pdb command)
  • uname (tarfile.TarInfo の属性)
  • uname() (os モジュール)
    • (platform モジュール)
  • unary
    • arithmetic operation
    • bitwise operation
  • UNARY_INVERT (opcode)
  • UNARY_NEGATIVE (opcode)
  • UNARY_NOT (opcode)
  • UNARY_POSITIVE (opcode)
  • unbinding
    • name
  • UnboundLocalError, [1]
  • unbuffered I/O
  • UNC paths
    • and os.makedirs()
  • UNCHECKED_HASH (py_compile.PycInvalidationMode の属性)
  • unconsumed_tail (zlib.Decompress の属性)
  • unctrl() (curses モジュール)
    • (curses.ascii モジュール)
  • undefine_macro() (distutils.ccompiler.CCompiler のメソッド)
  • Underflow (decimal のクラス)
  • undisplay (pdb command)
  • undo() (turtle モジュール)
  • undobufferentries() (turtle モジュール)
  • undoc_header (cmd.Cmd の属性)
  • unescape() (html モジュール)
    • (xml.sax.saxutils モジュール)
  • UnexpectedException
  • unexpectedSuccesses (unittest.TestResult の属性)
  • unfreeze() (gc モジュール)
  • unget_wch() (curses モジュール)
  • ungetch() (curses モジュール)
    • (msvcrt モジュール)
  • ungetmouse() (curses モジュール)
  • ungetwch() (msvcrt モジュール)
  • unhexlify() (binascii モジュール)
  • Unicode, [1], [2]
    • database
  • unicode (2to3 fixer)
  • Unicode Consortium
  • unicodedata (モジュール)
  • UnicodeDecodeError
  • UnicodeEncodeError
  • UnicodeError
  • UnicodeTranslateError
  • UnicodeWarning
  • unidata_version (unicodedata モジュール)
  • unified_diff() (difflib モジュール)
  • uniform() (random モジュール)
  • UnimplementedFileMode
  • Union (ctypes のクラス)
    • (typing モジュール)
  • union() (frozenset のメソッド)
  • unique() (enum モジュール), [1]
  • unittest (モジュール)
  • unittest コマンドラインオプション
    • --locals
    • -b, --buffer
    • -c, --catch
    • -f, --failfast
    • -k
  • unittest-discover コマンドラインオプション
    • -p, --pattern pattern
    • -s, --start-directory directory
    • -t, --top-level-directory directory
    • -v, --verbose
  • unittest.mock (モジュール)
  • universal newlines
    • What's new, [1], [2], [3]
    • bytearray.splitlines method
    • bytes.splitlines method
    • csv.reader function
    • importlib.abc.InspectLoader.get_source method
    • io.IncrementalNewlineDecoder class
    • io.TextIOWrapper class
    • open() built-in function
    • str.splitlines method
    • subprocess module
  • UNIX
    • I/O control
    • file control
  • unix_dialect (csv のクラス)
  • unix_shell (test.support モジュール)
  • UnixDatagramServer (socketserver のクラス)
  • UnixStreamServer (socketserver のクラス)
  • unknown (uuid.SafeUUID の属性)
  • unknown_decl() (html.parser.HTMLParser のメソッド)
  • unknown_open() (urllib.request.BaseHandler のメソッド)
    • (urllib.request.UnknownHandler のメソッド)
  • UnknownHandler (urllib.request のクラス)
  • UnknownProtocol
  • UnknownTransferEncoding
  • unlink() (os モジュール)
    • (pathlib.Path のメソッド)
    • (test.support モジュール)
    • (xml.dom.minidom.Node のメソッド)
  • unload() (test.support モジュール)
  • unlock() (mailbox.Babyl のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.MMDF のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (mailbox.mbox のメソッド)
  • unpack() (struct モジュール)
    • (struct.Struct のメソッド)
  • unpack_archive() (shutil モジュール)
  • unpack_array() (xdrlib.Unpacker のメソッド)
  • unpack_bytes() (xdrlib.Unpacker のメソッド)
  • unpack_double() (xdrlib.Unpacker のメソッド)
  • UNPACK_EX (opcode)
  • unpack_farray() (xdrlib.Unpacker のメソッド)
  • unpack_float() (xdrlib.Unpacker のメソッド)
  • unpack_fopaque() (xdrlib.Unpacker のメソッド)
  • unpack_from() (struct モジュール)
    • (struct.Struct のメソッド)
  • unpack_fstring() (xdrlib.Unpacker のメソッド)
  • unpack_list() (xdrlib.Unpacker のメソッド)
  • unpack_opaque() (xdrlib.Unpacker のメソッド)
  • UNPACK_SEQUENCE (opcode)
  • unpack_string() (xdrlib.Unpacker のメソッド)
  • Unpacker (xdrlib のクラス)
  • unpacking
    • dictionary
    • in function calls
    • iterable
  • unparsedEntityDecl() (xml.sax.handler.DTDHandler のメソッド)
  • UnparsedEntityDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • Unpickler (pickle のクラス)
  • UnpicklingError
  • unquote() (email.utils モジュール)
    • (urllib.parse モジュール)
  • unquote_plus() (urllib.parse モジュール)
  • unquote_to_bytes() (urllib.parse モジュール)
  • unreachable object
  • unreadline() (distutils.text_file.TextFile のメソッド)
  • unrecognized escape sequence
  • unregister() (atexit モジュール)
    • (faulthandler モジュール)
    • (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.poll のメソッド)
    • (selectors.BaseSelector のメソッド)
  • unregister_archive_format() (shutil モジュール)
  • unregister_dialect() (csv モジュール)
  • unregister_unpack_format() (shutil モジュール)
  • unsafe (uuid.SafeUUID の属性)
  • unset() (test.support.EnvironmentVarGuard のメソッド)
  • unsetenv() (os モジュール)
  • UnstructuredHeader (email.headerregistry のクラス)
  • unsubscribe() (imaplib.IMAP4 のメソッド)
  • UnsupportedOperation
  • until (pdb command)
  • untokenize() (tokenize モジュール)
  • untouchwin() (curses.window のメソッド)
  • unused_data (bz2.BZ2Decompressor の属性)
    • (lzma.LZMADecompressor の属性)
    • (zlib.Decompress の属性)
  • unverifiable (urllib.request.Request の属性)
  • unwrap() (inspect モジュール)
    • (ssl.SSLSocket のメソッド)
  • up (pdb command)
  • up() (turtle モジュール)
  • update() (collections.Counter のメソッド)
    • (dict のメソッド)
    • (frozenset のメソッド)
    • (hashlib.hash のメソッド)
    • (hmac.HMAC のメソッド)
    • (http.cookies.Morsel のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (trace.CoverageResults のメソッド)
    • (turtle モジュール)
  • update_authenticated() (urllib.request.HTTPPasswordMgrWithPriorAuth のメソッド)
  • update_lines_cols() (curses モジュール)
  • update_panels() (curses.panel モジュール)
  • update_visible() (mailbox.BabylMessage のメソッド)
  • update_wrapper() (functools モジュール)
  • upper() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • urandom() (os モジュール)
  • URL, [1], [2], [3]
    • parsing
    • relative
  • url (xmlrpc.client.ProtocolError の属性)
  • url2pathname() (urllib.request モジュール)
  • urlcleanup() (urllib.request モジュール)
  • urldefrag() (urllib.parse モジュール)
  • urlencode() (urllib.parse モジュール)
  • URLError
  • urljoin() (urllib.parse モジュール)
  • urllib (2to3 fixer)
    • (モジュール)
  • urllib.error (モジュール)
  • urllib.parse (モジュール)
  • urllib.request
    • モジュール
  • urllib.request (モジュール)
  • urllib.response (モジュール)
  • urllib.robotparser (モジュール)
  • urlopen() (urllib.request モジュール)
  • URLopener (urllib.request のクラス)
  • urlparse() (urllib.parse モジュール)
  • urlretrieve() (urllib.request モジュール)
  • urlsafe_b64decode() (base64 モジュール)
  • urlsafe_b64encode() (base64 モジュール)
  • urlsplit() (urllib.parse モジュール)
  • urlunparse() (urllib.parse モジュール)
  • urlunsplit() (urllib.parse モジュール)
  • urn (uuid.UUID の属性)
  • use_default_colors() (curses モジュール)
  • use_env() (curses モジュール)
  • use_rawinput (cmd.Cmd の属性)
  • UseForeignDTD() (xml.parsers.expat.xmlparser のメソッド)
  • USER
  • user
    • effective id
    • id
    • id, setting
  • user() (poplib.POP3 のメソッド)
  • user-defined
    • function
    • function call
    • method
  • user-defined function
    • オブジェクト, [1], [2]
  • user-defined method
    • オブジェクト
  • USER_BASE
    • (site モジュール)
  • user_call() (bdb.Bdb のメソッド)
  • user_exception() (bdb.Bdb のメソッド)
  • user_line() (bdb.Bdb のメソッド)
  • user_return() (bdb.Bdb のメソッド)
  • USER_SITE (site モジュール)
  • usercustomize
    • モジュール
  • UserDict (collections のクラス)
  • UserList (collections のクラス)
  • USERNAME, [1]
  • username (email.headerregistry.Address の属性)
  • USERPROFILE, [1]
  • userptr() (curses.panel.Panel のメソッド)
  • UserString (collections のクラス)
  • UserWarning
  • USTAR_FORMAT (tarfile モジュール)
  • UTC
  • utc (datetime.timezone の属性)
  • utcfromtimestamp() (datetime.datetime のクラスメソッド)
  • utcnow() (datetime.datetime のクラスメソッド)
  • utcoffset() (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (datetime.timezone のメソッド)
    • (datetime.tzinfo のメソッド)
  • utctimetuple() (datetime.datetime のメソッド)
  • utf8 (email.policy.EmailPolicy の属性)
  • utf8() (poplib.POP3 のメソッド)
  • utf8_enabled (imaplib.IMAP4 の属性)
  • utime() (os モジュール)
  • uu
    • モジュール
  • uu (モジュール)
  • UUID (uuid のクラス)
  • uuid (モジュール)
  • uuid1
  • uuid1() (uuid モジュール)
  • uuid3
  • uuid3() (uuid モジュール)
  • uuid4
  • uuid4() (uuid モジュール)
  • uuid5
  • uuid5() (uuid モジュール)
  • UuidCreate() (msilib モジュール)

V

  • v4_int_to_packed() (ipaddress モジュール)
  • v6_int_to_packed() (ipaddress モジュール)
  • validator() (wsgiref.validate モジュール)
  • value
    • default parameter
    • truth
  • value (ctypes._SimpleCData の属性)
    • (http.cookiejar.Cookie の属性)
    • (http.cookies.Morsel の属性)
    • (xml.dom.Attr の属性)
  • value of an object
  • Value() (multiprocessing モジュール)
    • (multiprocessing.managers.SyncManager のメソッド)
    • (multiprocessing.sharedctypes モジュール)
  • value_decode() (http.cookies.BaseCookie のメソッド)
  • value_encode() (http.cookies.BaseCookie のメソッド)
  • ValueError
    • 例外
  • valuerefs() (weakref.WeakValueDictionary のメソッド)
  • values
    • Boolean
    • writing
  • values() (contextvars.Context のメソッド)
    • (dict のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (types.MappingProxyType のメソッド)
  • ValuesView (collections.abc のクラス)
    • (typing のクラス)
  • var (contextvars.contextvars.Token.Token の属性)
  • variable
    • free
  • variable annotation
  • variance() (statistics モジュール)
  • variant (uuid.UUID の属性)
  • vars() (組み込み関数)
  • vbar (tkinter.scrolledtext.ScrolledText の属性)
  • VBAR (token モジュール)
  • VBAREQUAL (token モジュール)
  • Vec2D (turtle のクラス)
  • venv (モジュール)
  • VERBOSE (re モジュール)
  • verbose (tabnanny モジュール)
    • (test.support モジュール)
  • verify() (smtplib.SMTP のメソッド)
  • verify_client_post_handshake() (ssl.SSLSocket のメソッド)
  • verify_code (ssl.SSLCertVerificationError の属性)
  • VERIFY_CRL_CHECK_CHAIN (ssl モジュール)
  • VERIFY_CRL_CHECK_LEAF (ssl モジュール)
  • VERIFY_DEFAULT (ssl モジュール)
  • verify_flags (ssl.SSLContext の属性)
  • verify_message (ssl.SSLCertVerificationError の属性)
  • verify_mode (ssl.SSLContext の属性)
  • verify_request() (socketserver.BaseServer のメソッド)
  • VERIFY_X509_STRICT (ssl モジュール)
  • VERIFY_X509_TRUSTED_FIRST (ssl モジュール)
  • VerifyFlags (ssl のクラス)
  • VerifyMode (ssl のクラス)
  • version (curses モジュール)
    • (email.headerregistry.MIMEVersionHeader の属性)
    • (http.client.HTTPResponse の属性)
    • (http.cookiejar.Cookie の属性)
    • (in module sys), [1], [2]
    • (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
    • (marshal モジュール)
    • (sqlite3 モジュール)
    • (sys モジュール)
    • (urllib.request.URLopener の属性)
    • (uuid.UUID の属性)
  • version() (ensurepip モジュール)
    • (platform モジュール)
    • (ssl.SSLSocket のメソッド)
  • version_info (sqlite3 モジュール)
    • (sys モジュール)
  • version_string() (http.server.BaseHTTPRequestHandler のメソッド)
  • vformat() (string.Formatter のメソッド)
  • virtual
    • Environments
  • virtual environment
  • virtual machine
  • visit() (ast.NodeVisitor のメソッド)
  • visitproc (C のデータ型)
  • vline() (curses.window のメソッド)
  • voidcmd() (ftplib.FTP のメソッド)
  • volume (zipfile.ZipInfo の属性)
  • vonmisesvariate() (random モジュール)

W

  • W_OK (os モジュール)
  • wait() (asyncio モジュール)
    • (asyncio.Condition のメソッド)
    • (asyncio.Event のメソッド)
    • (asyncio.asyncio.subprocess.Process のメソッド)
    • (concurrent.futures モジュール)
    • (multiprocessing.connection モジュール)
    • (multiprocessing.pool.AsyncResult のメソッド)
    • (os モジュール)
    • (subprocess.Popen のメソッド)
    • (threading.Barrier のメソッド)
    • (threading.Condition のメソッド)
    • (threading.Event のメソッド)
  • wait3() (os モジュール)
  • wait4() (os モジュール)
  • wait_closed() (asyncio.Server のメソッド)
    • (asyncio.StreamWriter のメソッド)
  • wait_for() (asyncio モジュール)
    • (asyncio.Condition のメソッド)
    • (threading.Condition のメソッド)
  • wait_threads_exit() (test.support モジュール)
  • waitid() (os モジュール)
  • waitpid() (os モジュール)
  • walk() (ast モジュール)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (os モジュール)
  • walk_packages() (pkgutil モジュール)
  • walk_stack() (traceback モジュール)
  • walk_tb() (traceback モジュール)
  • want (doctest.Example の属性)
  • warn() (distutils.ccompiler.CCompiler のメソッド)
    • (distutils.text_file.TextFile のメソッド)
    • (warnings モジュール)
  • warn_explicit() (warnings モジュール)
  • Warning, [1]
  • warning() (logging モジュール)
    • (logging.Logger のメソッド)
    • (xml.sax.handler.ErrorHandler のメソッド)
  • warnings
    • (モジュール)
  • WarningsRecorder (test.support のクラス)
  • warnoptions (sys モジュール)
  • wasSuccessful() (unittest.TestResult のメソッド)
  • WatchedFileHandler (logging.handlers のクラス)
  • wave (モジュール)
  • WCONTINUED (os モジュール)
  • WCOREDUMP() (os モジュール)
  • WeakKeyDictionary (weakref のクラス)
  • WeakMethod (weakref のクラス)
  • weakref (モジュール)
  • WeakSet (weakref のクラス)
  • WeakValueDictionary (weakref のクラス)
  • webbrowser (モジュール)
  • weekday() (calendar モジュール)
    • (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
  • weekheader() (calendar モジュール)
  • weibullvariate() (random モジュール)
  • WEXITED (os モジュール)
  • WEXITSTATUS() (os モジュール)
  • wfile (http.server.BaseHTTPRequestHandler の属性)
  • what() (imghdr モジュール)
    • (sndhdr モジュール)
  • whathdr() (sndhdr モジュール)
  • whatis (pdb command)
  • when() (asyncio.TimerHandle のメソッド)
  • where (pdb command)
  • which() (shutil モジュール)
  • whichdb() (dbm モジュール)
  • while
    • 文, [1], [2], [3]
  • whitespace (shlex.shlex の属性)
    • (string モジュール)
  • whitespace_split (shlex.shlex の属性)
  • Widget (tkinter.ttk のクラス)
  • width (textwrap.TextWrapper の属性)
  • width() (turtle モジュール)
  • WIFCONTINUED() (os モジュール)
  • WIFEXITED() (os モジュール)
  • WIFSIGNALED() (os モジュール)
  • WIFSTOPPED() (os モジュール)
  • win32_ver() (platform モジュール)
  • WinDLL (ctypes のクラス)
  • window manager (widgets)
  • window() (curses.panel.Panel のメソッド)
  • window_height() (turtle モジュール)
  • window_width() (turtle モジュール)
  • Windows
  • Windows ini file
  • WindowsError
  • WindowsPath (pathlib のクラス)
  • WindowsProactorEventLoopPolicy (asyncio のクラス)
  • WindowsRegistryFinder (importlib.machinery のクラス)
  • winerror (OSError の属性)
  • WinError() (ctypes モジュール)
  • WINFUNCTYPE() (ctypes モジュール)
  • winreg (モジュール)
  • WinSock
  • winsound (モジュール)
  • winver (sys モジュール)
  • with
    • 文, [1]
  • WITH_CLEANUP_FINISH (opcode)
  • WITH_CLEANUP_START (opcode)
  • with_hostmask (ipaddress.IPv4Interface の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Interface の属性)
    • (ipaddress.IPv6Network の属性)
  • with_name() (pathlib.PurePath のメソッド)
  • with_netmask (ipaddress.IPv4Interface の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Interface の属性)
    • (ipaddress.IPv6Network の属性)
  • with_prefixlen (ipaddress.IPv4Interface の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Interface の属性)
    • (ipaddress.IPv6Network の属性)
  • with_pymalloc() (test.support モジュール)
  • with_suffix() (pathlib.PurePath のメソッド)
  • with_traceback() (BaseException のメソッド)
  • WNOHANG (os モジュール)
  • WNOWAIT (os モジュール)
  • wordchars (shlex.shlex の属性)
  • World Wide Web, [1], [2]
  • wrap() (textwrap モジュール)
    • (textwrap.TextWrapper のメソッド)
  • wrap_bio() (ssl.SSLContext のメソッド)
  • wrap_future() (asyncio モジュール)
  • wrap_socket() (ssl モジュール)
    • (ssl.SSLContext のメソッド)
  • wrap_text() (distutils.fancy_getopt モジュール)
  • wrapper() (curses モジュール)
  • WrapperDescriptorType (types モジュール)
  • wraps() (functools モジュール)
  • WRITABLE (tkinter モジュール)
  • writable() (asyncore.dispatcher のメソッド)
    • (io.IOBase のメソッド)
  • write() (asyncio.StreamWriter のメソッド)
    • (asyncio.WriteTransport のメソッド)
    • (code.InteractiveInterpreter のメソッド)
    • (codecs.StreamWriter のメソッド)
    • (configparser.ConfigParser のメソッド)
    • (email.generator.BytesGenerator のメソッド)
    • (email.generator.Generator のメソッド)
    • (io.BufferedIOBase のメソッド)
    • (io.BufferedWriter のメソッド)
    • (io.RawIOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (mmap.mmap のメソッド)
    • (os モジュール)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (ssl.MemoryBIO のメソッド)
    • (ssl.SSLSocket のメソッド)
    • (telnetlib.Telnet のメソッド)
    • (turtle モジュール)
    • (xml.etree.ElementTree.ElementTree のメソッド)
    • (zipfile.ZipFile のメソッド)
  • write_byte() (mmap.mmap のメソッド)
  • write_bytes() (pathlib.Path のメソッド)
  • write_docstringdict() (turtle モジュール)
  • write_eof() (asyncio.StreamWriter のメソッド)
    • (asyncio.WriteTransport のメソッド)
    • (ssl.MemoryBIO のメソッド)
  • write_file() (distutils.file_util モジュール)
  • write_history_file() (readline モジュール)
  • WRITE_RESTRICTED
  • write_results() (trace.CoverageResults のメソッド)
  • write_text() (pathlib.Path のメソッド)
  • write_through (io.TextIOWrapper の属性)
  • writeall() (ossaudiodev.oss_audio_device のメソッド)
  • writeframes() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • writeframesraw() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • writeheader() (csv.DictWriter のメソッド)
  • writelines() (asyncio.StreamWriter のメソッド)
    • (asyncio.WriteTransport のメソッド)
    • (codecs.StreamWriter のメソッド)
    • (io.IOBase のメソッド)
  • writePlist() (plistlib モジュール)
  • writePlistToBytes() (plistlib モジュール)
  • writepy() (zipfile.PyZipFile のメソッド)
  • writer (formatter.formatter の属性)
  • writer() (csv モジュール)
  • writerow() (csv.csvwriter のメソッド)
  • writerows() (csv.csvwriter のメソッド)
  • writestr() (zipfile.ZipFile のメソッド)
  • WriteTransport (asyncio のクラス)
  • writev() (os モジュール)
  • writexml() (xml.dom.minidom.Node のメソッド)
  • writing
    • values
  • WrongDocumentErr
  • ws_comma (2to3 fixer)
  • wsgi_file_wrapper (wsgiref.handlers.BaseHandler の属性)
  • wsgi_multiprocess (wsgiref.handlers.BaseHandler の属性)
  • wsgi_multithread (wsgiref.handlers.BaseHandler の属性)
  • wsgi_run_once (wsgiref.handlers.BaseHandler の属性)
  • wsgiref (モジュール)
  • wsgiref.handlers (モジュール)
  • wsgiref.headers (モジュール)
  • wsgiref.simple_server (モジュール)
  • wsgiref.util (モジュール)
  • wsgiref.validate (モジュール)
  • WSGIRequestHandler (wsgiref.simple_server のクラス)
  • WSGIServer (wsgiref.simple_server のクラス)
  • wShowWindow (subprocess.STARTUPINFO の属性)
  • WSTOPPED (os モジュール)
  • WSTOPSIG() (os モジュール)
  • wstring_at() (ctypes モジュール)
  • WTERMSIG() (os モジュール)
  • WUNTRACED (os モジュール)
  • WWW, [1], [2]
    • server, [1]

X

  • X (re モジュール)
  • X509 certificate
  • X_OK (os モジュール)
  • xatom() (imaplib.IMAP4 のメソッド)
  • XATTR_CREATE (os モジュール)
  • XATTR_REPLACE (os モジュール)
  • XATTR_SIZE_MAX (os モジュール)
  • xcor() (turtle モジュール)
  • XDR
  • xdrlib (モジュール)
  • xhdr() (nntplib.NNTP のメソッド)
  • XHTML
  • XHTML_NAMESPACE (xml.dom モジュール)
  • xml (モジュール)
  • XML() (xml.etree.ElementTree モジュール)
  • xml.dom (モジュール)
  • xml.dom.minidom (モジュール)
  • xml.dom.pulldom (モジュール)
  • xml.etree.ElementTree (モジュール)
  • xml.parsers.expat (モジュール)
  • xml.parsers.expat.errors (モジュール)
  • xml.parsers.expat.model (モジュール)
  • xml.sax (モジュール)
  • xml.sax.handler (モジュール)
  • xml.sax.saxutils (モジュール)
  • xml.sax.xmlreader (モジュール)
  • XML_ERROR_ABORTED (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.parsers.expat.errors モジュール)
  • XML_ERROR_BINARY_ENTITY_REF (xml.parsers.expat.errors モジュール)
  • XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING (xml.parsers.expat.errors モジュール)
  • XML_ERROR_DUPLICATE_ATTRIBUTE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_ENTITY_DECLARED_IN_PE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_EXTERNAL_ENTITY_HANDLING (xml.parsers.expat.errors モジュール)
  • XML_ERROR_FEATURE_REQUIRES_XML_DTD (xml.parsers.expat.errors モジュール)
  • XML_ERROR_FINISHED (xml.parsers.expat.errors モジュール)
  • XML_ERROR_INCOMPLETE_PE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_INCORRECT_ENCODING (xml.parsers.expat.errors モジュール)
  • XML_ERROR_INVALID_TOKEN (xml.parsers.expat.errors モジュール)
  • XML_ERROR_JUNK_AFTER_DOC_ELEMENT (xml.parsers.expat.errors モジュール)
  • XML_ERROR_MISPLACED_XML_PI (xml.parsers.expat.errors モジュール)
  • XML_ERROR_NO_ELEMENTS (xml.parsers.expat.errors モジュール)
  • XML_ERROR_NO_MEMORY (xml.parsers.expat.errors モジュール)
  • XML_ERROR_NOT_STANDALONE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_NOT_SUSPENDED (xml.parsers.expat.errors モジュール)
  • XML_ERROR_PARAM_ENTITY_REF (xml.parsers.expat.errors モジュール)
  • XML_ERROR_PARTIAL_CHAR (xml.parsers.expat.errors モジュール)
  • XML_ERROR_PUBLICID (xml.parsers.expat.errors モジュール)
  • XML_ERROR_RECURSIVE_ENTITY_REF (xml.parsers.expat.errors モジュール)
  • XML_ERROR_SUSPEND_PE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_SUSPENDED (xml.parsers.expat.errors モジュール)
  • XML_ERROR_SYNTAX (xml.parsers.expat.errors モジュール)
  • XML_ERROR_TAG_MISMATCH (xml.parsers.expat.errors モジュール)
  • XML_ERROR_TEXT_DECL (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNBOUND_PREFIX (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNCLOSED_CDATA_SECTION (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNCLOSED_TOKEN (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNDECLARING_PREFIX (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNDEFINED_ENTITY (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNEXPECTED_STATE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNKNOWN_ENCODING (xml.parsers.expat.errors モジュール)
  • XML_ERROR_XML_DECL (xml.parsers.expat.errors モジュール)
  • XML_NAMESPACE (xml.dom モジュール)
  • xmlcharrefreplace_errors() (codecs モジュール)
  • XmlDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • XMLFilterBase (xml.sax.saxutils のクラス)
  • XMLGenerator (xml.sax.saxutils のクラス)
  • XMLID() (xml.etree.ElementTree モジュール)
  • XMLNS_NAMESPACE (xml.dom モジュール)
  • XMLParser (xml.etree.ElementTree のクラス)
  • XMLParserType (xml.parsers.expat モジュール)
  • XMLPullParser (xml.etree.ElementTree のクラス)
  • XMLReader (xml.sax.xmlreader のクラス)
  • xmlrpc.client (モジュール)
  • xmlrpc.server (モジュール)
  • xor
    • bitwise
  • xor() (operator モジュール)
  • xover() (nntplib.NNTP のメソッド)
  • xpath() (nntplib.NNTP のメソッド)
  • xrange (2to3 fixer)
  • xreadlines (2to3 fixer)
  • xview() (tkinter.ttk.Treeview のメソッド)

Y

  • Y2K
  • ycor() (turtle モジュール)
  • year (datetime.date の属性)
    • (datetime.datetime の属性)
  • Year 2000
  • Year 2038
  • yeardatescalendar() (calendar.Calendar のメソッド)
  • yeardays2calendar() (calendar.Calendar のメソッド)
  • yeardayscalendar() (calendar.Calendar のメソッド)
  • YESEXPR (locale モジュール)
  • yield
    • examples
    • expression
    • yield from (in What's New)
    • キーワード
    • 文
  • YIELD_FROM (opcode)
  • YIELD_VALUE (opcode)
  • yiq_to_rgb() (colorsys モジュール)
  • yview() (tkinter.ttk.Treeview のメソッド)

Z

  • Zen of Python
  • ZeroDivisionError
    • 例外
  • zfill() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • zip (2to3 fixer)
  • zip() (組み込み関数)
  • ZIP_BZIP2 (zipfile モジュール)
  • ZIP_DEFLATED (zipfile モジュール)
  • zip_longest() (itertools モジュール)
  • ZIP_LZMA (zipfile モジュール)
  • ZIP_STORED (zipfile モジュール)
  • zipapp (モジュール)
  • zipapp コマンドラインオプション
    • --info
    • -c, --compress
    • -h, --help
    • -m <mainfn>, --main=<mainfn>
    • -o <output>, --output=<output>
    • -p <interpreter>, --python=<interpreter>
  • ZipFile (zipfile のクラス)
  • zipfile (モジュール)
  • zipfile コマンドラインオプション
    • --create <zipfile> <source1> ... <sourceN>
    • --extract <zipfile> <output_dir>
    • --list <zipfile>
    • --test <zipfile>
    • -c <zipfile> <source1> ... <sourceN>
    • -e <zipfile> <output_dir>
    • -l <zipfile>
    • -t <zipfile>
  • zipimport (モジュール)
  • zipimporter (zipimport のクラス)
  • ZipImportError
  • ZipInfo (zipfile のクラス)
  • zlib (モジュール)
  • ZLIB_RUNTIME_VERSION (zlib モジュール)
  • ZLIB_VERSION (zlib モジュール)

オ

  • オブジェクト
    • Boolean, [1]
    • Capsule
    • Ellipsis
    • None, [1], [2]
    • NotImplemented
    • asynchronous-generator
    • built-in function, [1]
    • built-in method, [1]
    • bytearray, [1], [2], [3]
    • bytes, [1], [2]
    • callable, [1]
    • class, [1], [2]
    • class instance, [1], [2]
    • complex
    • complex number, [1]
    • dictionary, [1], [2], [3], [4], [5], [6], [7]
    • file, [1]
    • floating point, [1], [2]
    • frame
    • frozenset, [1]
    • function, [1], [2], [3], [4], [5]
    • generator, [1], [2]
    • immutable
    • immutable sequence
    • instance, [1], [2]
    • instancemethod
    • integer, [1], [2]
    • io.StringIO
    • list, [1], [2], [3], [4], [5], [6], [7], [8]
    • long integer
    • mapping, [1], [2], [3], [4], [5]
    • memoryview, [1]
    • method, [1], [2], [3], [4], [5]
    • module, [1], [2]
    • mutable, [1], [2]
    • mutable sequence
    • numeric, [1], [2], [3]
    • range
    • sequence, [1], [2], [3], [4], [5], [6], [7], [8]
    • set, [1], [2], [3]
    • set type
    • slice
    • socket
    • string, [1], [2]
    • traceback, [1], [2], [3], [4]
    • tuple, [1], [2], [3], [4], [5], [6]
    • type, [1], [2]
    • user-defined function, [1], [2]
    • user-defined method

キ

  • キーワード
    • as, [1], [2]
    • async
    • await, [1]
    • elif
    • else, [1], [2], [3], [4], [5], [6], [7]
    • except
    • finally, [1], [2], [3], [4]
    • from, [1]
    • in, [1]
    • yield

コ

  • コマンドラインオプション
    • --check-hash-based-pycs default|always|never
    • --help
    • --version
    • -?
    • -B
    • -E
    • -I
    • -J
    • -O
    • -OO
    • -R
    • -S
    • -V
    • -W arg
    • -X
    • -b
    • -c <command>
    • -d
    • -h
    • -i
    • -m <module-name>
    • -q
    • -s
    • -u
    • -v
    • -x

メ

  • メソッド

モ

  • モジュール
    • __main__, [1], [2], [3], [4], [5], [6], [7]
    • _locale
    • _thread
    • array, [1]
    • base64
    • bdb
    • binhex
    • builtins, [1], [2], [3], [4]
    • cmd
    • copy
    • crypt
    • dbm.gnu, [1]
    • dbm.ndbm, [1]
    • errno
    • glob
    • imp
    • io
    • json
    • math, [1]
    • os
    • pickle, [1], [2], [3]
    • pty
    • pwd
    • pyexpat
    • re, [1]
    • shelve
    • signal, [1]
    • sitecustomize
    • socket
    • stat
    • string
    • struct
    • sys, [1], [2], [3], [4], [5], [6]
    • types
    • urllib.request
    • usercustomize
    • uu

例

  • 例外
    • AssertionError
    • AttributeError
    • GeneratorExit, [1]
    • ImportError
    • NameError
    • StopAsyncIteration
    • StopIteration, [1]
    • TypeError
    • ValueError
    • ZeroDivisionError

文

  • 文
    • assert, [1]
    • async def
    • async for
    • async with
    • break, [1], [2], [3], [4]
    • class
    • continue, [1], [2], [3], [4]
    • def
    • del, [1], [2], [3]
    • except
    • for, [1], [2], [3]
    • global, [1]
    • if, [1]
    • import, [1], [2], [3], [4]
    • nonlocal
    • pass
    • raise, [1]
    • return, [1], [2]
    • try, [1], [2]
    • while, [1], [2], [3]
    • with, [1]
    • yield

演

  • 演算子
    • !=, [1]
    • % (percent), [1]
    • & (ampersand), [1]
    • * (asterisk), [1]
    • **, [1]
    • / (slash), [1]
    • //, [1]
    • < (less), [1]
    • <<, [1]
    • <=, [1]
    • ==, [1]
    • > (greater), [1]
    • >=, [1]
    • >>, [1]
    • @ (at)
    • ^ (caret), [1]
    • and, [1], [2]
    • in, [1], [2]
    • is, [1]
    • is not, [1]
    • not, [1]
    • not in, [1], [2]
    • or, [1], [2]
    • | (vertical bar), [1]
    • ~ (tilde), [1]

環

  • 環境変数
    • APPDATA
    • AUDIODEV
    • BROWSER, [1]
    • CC
    • CFLAGS, [1], [2], [3]
    • COLS, [1]
    • COLUMNS, [1]
    • COMSPEC, [1]
    • CPP
    • CPPFLAGS
    • DISTUTILS_DEBUG
    • HOME, [1], [2], [3], [4]
    • HOMEDRIVE, [1]
    • HOMEPATH, [1]
    • IDLESTARTUP, [1], [2]
    • KDEDIR
    • LANG, [1], [2], [3], [4]
    • LANGUAGE, [1]
    • LC_ALL, [1]
    • LC_MESSAGES, [1]
    • LDCXXSHARED
    • LDFLAGS
    • LINES, [1], [2], [3], [4]
    • LNAME
    • LOGNAME, [1]
    • MIXERDEV
    • PAGER
    • PATH, [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], [31], [32], [33], [34], [35]
    • PATHEXT, [1], [2]
    • PLAT
    • POSIXLY_CORRECT
    • PYTHON*, [1], [2], [3]
    • PYTHONASYNCIODEBUG, [1], [2]
    • PYTHONBREAKPOINT, [1], [2], [3], [4]
    • PYTHONCASEOK, [1]
    • PYTHONCOERCECLOCALE, [1], [2]
    • PYTHONDEBUG, [1], [2]
    • PYTHONDEVMODE, [1], [2]
    • PYTHONDOCS
    • PYTHONDONTWRITEBYTECODE, [1], [2], [3], [4], [5], [6]
    • PYTHONDUMPREFS, [1]
    • PYTHONEXECUTABLE
    • PYTHONFAULTHANDLER, [1], [2]
    • PYTHONHASHSEED, [1], [2], [3], [4], [5], [6], [7], [8], [9]
    • PYTHONHOME, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16]
    • PYTHONINSPECT, [1], [2], [3]
    • PYTHONIOENCODING, [1], [2], [3], [4], [5], [6], [7]
    • PYTHONLEGACYWINDOWSFSENCODING, [1], [2], [3]
    • PYTHONLEGACYWINDOWSSTDIO, [1], [2], [3]
    • PYTHONMALLOC, [1], [2], [3], [4], [5], [6], [7]
    • PYTHONMALLOCSTATS, [1], [2]
    • PYTHONNOUSERSITE, [1], [2], [3], [4], [5]
    • PYTHONOPTIMIZE, [1], [2]
    • PYTHONPATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24]
    • PYTHONPROFILEIMPORTTIME, [1], [2], [3]
    • PYTHONSHOWALLOCCOUNT
    • PYTHONSHOWREFCOUNT
    • PYTHONSTARTUP, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]
    • PYTHONTHREADDEBUG
    • PYTHONTRACEMALLOC, [1], [2], [3]
    • PYTHONUNBUFFERED, [1], [2]
    • PYTHONUSERBASE, [1], [2], [3]
    • PYTHONUSERSITE
    • PYTHONUTF8, [1], [2], [3]
    • PYTHONVERBOSE, [1], [2]
    • PYTHONWARNINGS, [1], [2], [3], [4], [5], [6], [7], [8]
    • PYTHON_DOM
    • SOURCE_DATE_EPOCH, [1], [2], [3], [4], [5], [6]
    • SSL_CERT_FILE
    • SSL_CERT_PATH
    • SystemRoot
    • TCL_LIBRARY
    • TEMP
    • TERM, [1]
    • TIX_LIBRARY
    • TK_LIBRARY
    • TMP
    • TMPDIR
    • TZ, [1], [2], [3], [4], [5]
    • USER
    • USERNAME, [1]
    • USERPROFILE, [1]
    • USER_BASE
    • exec_prefix, [1], [2]
    • http_proxy, [1], [2]
    • no_proxy
    • prefix, [1], [2], [3]

組

  • 組み込み関数
    • __import__
    • abs, [1]
    • ascii
    • bytes, [1]
    • chr
    • classmethod
    • compile, [1], [2], [3], [4]
    • complex, [1]
    • divmod, [1], [2]
    • eval, [1], [2], [3], [4], [5]
    • exec, [1], [2], [3]
    • float, [1], [2]
    • hash, [1], [2], [3]
    • help
    • id
    • int, [1], [2]
    • len, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]
    • max
    • min
    • open, [1]
    • ord
    • pow, [1], [2], [3], [4], [5]
    • print
    • range
    • repr, [1], [2], [3]
    • round
    • slice, [1]
    • staticmethod
    • tuple, [1]
    • type, [1], [2], [3]

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – B

  • b"
    • bytes literal
  • b'
    • bytes literal
  • b16decode() (base64 モジュール)
  • b16encode() (base64 モジュール)
  • b2a_base64() (binascii モジュール)
  • b2a_hex() (binascii モジュール)
  • b2a_hqx() (binascii モジュール)
  • b2a_qp() (binascii モジュール)
  • b2a_uu() (binascii モジュール)
  • b32decode() (base64 モジュール)
  • b32encode() (base64 モジュール)
  • b64decode() (base64 モジュール)
  • b64encode() (base64 モジュール)
  • b85decode() (base64 モジュール)
  • b85encode() (base64 モジュール)
  • Babyl (mailbox のクラス)
  • BabylMessage (mailbox のクラス)
  • back() (turtle モジュール)
  • backslash character
  • backslashreplace_errors() (codecs モジュール)
  • backup() (sqlite3.Connection のメソッド)
  • backward() (turtle モジュール)
  • BadStatusLine
  • BadZipFile
  • BadZipfile
  • Balloon (tkinter.tix のクラス)
  • Barrier (multiprocessing のクラス)
    • (threading のクラス)
  • Barrier() (multiprocessing.managers.SyncManager のメソッド)
  • base64
    • encoding
    • モジュール
  • base64 (モジュール)
  • base_exec_prefix (sys モジュール)
  • base_prefix (sys モジュール)
  • BaseCGIHandler (wsgiref.handlers のクラス)
  • BaseCookie (http.cookies のクラス)
  • BaseException
  • BaseHandler (urllib.request のクラス)
    • (wsgiref.handlers のクラス)
  • BaseHeader (email.headerregistry のクラス)
  • BaseHTTPRequestHandler (http.server のクラス)
  • BaseManager (multiprocessing.managers のクラス)
  • basename() (os.path モジュール)
  • BaseProtocol (asyncio のクラス)
  • BaseProxy (multiprocessing.managers のクラス)
  • BaseRequestHandler (socketserver のクラス)
  • BaseRotatingHandler (logging.handlers のクラス)
  • BaseSelector (selectors のクラス)
  • BaseServer (socketserver のクラス)
  • basestring (2to3 fixer)
  • BaseTransport (asyncio のクラス)
  • basicConfig() (logging モジュール)
  • BasicContext (decimal のクラス)
  • BasicInterpolation (configparser のクラス)
  • BasicTestRunner (test.support のクラス)
  • baudrate() (curses モジュール)
  • bbox() (tkinter.ttk.Treeview のメソッド)
  • BDADDR_ANY (socket モジュール)
  • BDADDR_LOCAL (socket モジュール)
  • bdb
    • モジュール
  • Bdb (bdb のクラス)
  • bdb (モジュール)
  • BdbQuit
  • BDFL
  • bdist_msi (distutils.command.bdist_msi のクラス)
  • beep() (curses モジュール)
  • Beep() (winsound モジュール)
  • BEFORE_ASYNC_WITH (opcode)
  • begin_fill() (turtle モジュール)
  • begin_poly() (turtle モジュール)
  • below() (curses.panel.Panel のメソッド)
  • BELOW_NORMAL_PRIORITY_CLASS (subprocess モジュール)
  • Benchmarking
  • benchmarking, [1], [2], [3]
  • betavariate() (random モジュール)
  • bgcolor() (turtle モジュール)
  • bgpic() (turtle モジュール)
  • bias() (audioop モジュール)
  • bidirectional() (unicodedata モジュール)
  • bigaddrspacetest() (test.support モジュール)
  • BigEndianStructure (ctypes のクラス)
  • bigmemtest() (test.support モジュール)
  • bin() (組み込み関数)
  • binary
    • arithmetic operation
    • bitwise operation
    • data, packing
    • literals
  • Binary (msilib のクラス)
    • (xmlrpc.client のクラス)
  • binary file
  • binary literal
  • binary mode
  • binary semaphores
  • BINARY_ADD (opcode)
  • BINARY_AND (opcode)
  • BINARY_FLOOR_DIVIDE (opcode)
  • BINARY_LSHIFT (opcode)
  • BINARY_MATRIX_MULTIPLY (opcode)
  • BINARY_MODULO (opcode)
  • BINARY_MULTIPLY (opcode)
  • BINARY_OR (opcode)
  • BINARY_POWER (opcode)
  • BINARY_RSHIFT (opcode)
  • BINARY_SUBSCR (opcode)
  • BINARY_SUBTRACT (opcode)
  • BINARY_TRUE_DIVIDE (opcode)
  • BINARY_XOR (opcode)
  • BinaryIO (typing のクラス)
  • binascii (モジュール)
  • bind (widgets)
  • bind() (asyncore.dispatcher のメソッド)
    • (inspect.Signature のメソッド)
    • (socket.socket のメソッド)
  • bind_partial() (inspect.Signature のメソッド)
  • bind_port() (test.support モジュール)
  • bind_textdomain_codeset() (gettext モジュール)
  • bind_unix_socket() (test.support モジュール)
  • binding
    • global name
    • name, [1], [2], [3], [4], [5], [6]
  • bindtextdomain() (gettext モジュール)
    • (locale モジュール)
  • binhex
    • モジュール
  • binhex (モジュール)
  • binhex() (binhex モジュール)
  • bisect (モジュール)
  • bisect() (bisect モジュール)
  • bisect_left() (bisect モジュール)
  • bisect_right() (bisect モジュール)
  • bit_length() (int のメソッド)
  • bitmap() (msilib.Dialog のメソッド)
  • bitwise
    • and
    • operation, binary
    • operation, unary
    • operations
    • or
    • xor
  • bk() (turtle モジュール)
  • bkgd() (curses.window のメソッド)
  • bkgdset() (curses.window のメソッド)
  • blake2b() (hashlib モジュール)
  • blake2b, blake2s
  • blake2b.MAX_DIGEST_SIZE (hashlib モジュール)
  • blake2b.MAX_KEY_SIZE (hashlib モジュール)
  • blake2b.PERSON_SIZE (hashlib モジュール)
  • blake2b.SALT_SIZE (hashlib モジュール)
  • blake2s() (hashlib モジュール)
  • blake2s.MAX_DIGEST_SIZE (hashlib モジュール)
  • blake2s.MAX_KEY_SIZE (hashlib モジュール)
  • blake2s.PERSON_SIZE (hashlib モジュール)
  • blake2s.SALT_SIZE (hashlib モジュール)
  • blank line
  • block
    • code
  • block_size (hmac.HMAC の属性)
  • blocked_domains() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • BlockingIOError, [1]
  • blocksize (http.client.HTTPConnection の属性)
  • BNF, [1]
  • body() (nntplib.NNTP のメソッド)
  • body_encode() (email.charset.Charset のメソッド)
  • body_encoding (email.charset.Charset の属性)
  • body_line_iterator() (email.iterators モジュール)
  • BOM (codecs モジュール)
  • BOM_BE (codecs モジュール)
  • BOM_LE (codecs モジュール)
  • BOM_UTF16 (codecs モジュール)
  • BOM_UTF16_BE (codecs モジュール)
  • BOM_UTF16_LE (codecs モジュール)
  • BOM_UTF32 (codecs モジュール)
  • BOM_UTF32_BE (codecs モジュール)
  • BOM_UTF32_LE (codecs モジュール)
  • BOM_UTF8 (codecs モジュール)
  • bool (組み込みクラス)
  • Boolean
    • operation
    • operations, [1]
    • type
    • values
    • オブジェクト, [1]
  • BOOLEAN_STATES (configparser.ConfigParser の属性)
  • bootstrap() (ensurepip モジュール)
  • border() (curses.window のメソッド)
  • bottom() (curses.panel.Panel のメソッド)
  • bottom_panel() (curses.panel モジュール)
  • BoundArguments (inspect のクラス)
  • BoundaryError
  • BoundedSemaphore (asyncio のクラス)
    • (multiprocessing のクラス)
    • (threading のクラス)
  • BoundedSemaphore() (multiprocessing.managers.SyncManager のメソッド)
  • box() (curses.window のメソッド)
  • bpformat() (bdb.Breakpoint のメソッド)
  • bpprint() (bdb.Breakpoint のメソッド)
  • break
    • 文, [1], [2], [3], [4]
  • break (pdb command)
  • break_anywhere() (bdb.Bdb のメソッド)
  • break_here() (bdb.Bdb のメソッド)
  • break_long_words (textwrap.TextWrapper の属性)
  • BREAK_LOOP (opcode)
  • break_on_hyphens (textwrap.TextWrapper の属性)
  • Breakpoint (bdb のクラス)
  • breakpoint() (組み込み関数)
  • breakpointhook() (sys モジュール)
  • breakpoints
  • broadcast_address (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • broken (threading.Barrier の属性)
  • BrokenBarrierError
  • BrokenExecutor
  • BrokenPipeError
  • BrokenProcessPool
  • BrokenThreadPool
  • BROWSER, [1]
  • BsdDbShelf (shelve のクラス)
  • buffer (2to3 fixer)
    • (io.TextIOBase の属性)
    • (unittest.TestResult の属性)
  • buffer interface
    • (see buffer protocol)
  • buffer object
    • (see buffer protocol)
  • buffer protocol
    • binary sequence types
    • str (built-in class)
  • buffer size, I/O
  • buffer_info() (array.array のメソッド)
  • buffer_size (xml.parsers.expat.xmlparser の属性)
  • buffer_text (xml.parsers.expat.xmlparser の属性)
  • buffer_updated() (asyncio.BufferedProtocol のメソッド)
  • buffer_used (xml.parsers.expat.xmlparser の属性)
  • BufferedIOBase (io のクラス)
  • BufferedProtocol (asyncio のクラス)
  • BufferedRandom (io のクラス)
  • BufferedReader (io のクラス)
  • BufferedRWPair (io のクラス)
  • BufferedWriter (io のクラス)
  • BufferError
  • BufferingHandler (logging.handlers のクラス)
  • BufferTooShort
  • bufsize() (ossaudiodev.oss_audio_device のメソッド)
  • BUILD_CONST_KEY_MAP (opcode)
  • BUILD_LIST (opcode)
  • BUILD_LIST_UNPACK (opcode)
  • BUILD_MAP (opcode)
  • BUILD_MAP_UNPACK (opcode)
  • BUILD_MAP_UNPACK_WITH_CALL (opcode)
  • build_opener() (urllib.request モジュール)
  • build_py (distutils.command.build_py のクラス)
  • build_py_2to3 (distutils.command.build_py のクラス)
  • BUILD_SET (opcode)
  • BUILD_SET_UNPACK (opcode)
  • BUILD_SLICE (opcode)
  • BUILD_STRING (opcode)
  • BUILD_TUPLE (opcode)
  • BUILD_TUPLE_UNPACK (opcode)
  • BUILD_TUPLE_UNPACK_WITH_CALL (opcode)
  • built-in
    • method
    • types
  • built-in function
    • call
    • オブジェクト, [1]
  • built-in method
    • call
    • オブジェクト, [1]
  • builtin_module_names (sys モジュール)
  • BuiltinFunctionType (types モジュール)
  • BuiltinImporter (importlib.machinery のクラス)
  • BuiltinMethodType (types モジュール)
  • builtins
    • モジュール, [1], [2], [3], [4]
  • builtins (モジュール)
  • ButtonBox (tkinter.tix のクラス)
  • bye() (turtle モジュール)
  • byref() (ctypes モジュール)
  • byte
  • byte-code
    • file, [1]
  • byte_compile() (distutils.util モジュール)
  • bytearray
    • formatting
    • interpolation
    • methods
    • オブジェクト, [1], [2], [3]
  • bytearray (組み込みクラス)
  • bytecode, [1]
  • Bytecode (dis のクラス)
  • Bytecode.codeobj (dis モジュール)
  • Bytecode.first_line (dis モジュール)
  • BYTECODE_SUFFIXES (importlib.machinery モジュール)
  • byteorder (sys モジュール)
  • bytes
    • formatting
    • interpolation
    • methods
    • str (built-in class)
    • オブジェクト, [1], [2]
    • 組み込み関数, [1]
  • bytes (uuid.UUID の属性)
    • (組み込みクラス)
  • bytes literal
  • bytes-like object
  • bytes_le (uuid.UUID の属性)
  • BytesFeedParser (email.parser のクラス)
  • BytesGenerator (email.generator のクラス)
  • BytesHeaderParser (email.parser のクラス)
  • BytesIO (io のクラス)
  • BytesParser (email.parser のクラス)
  • ByteString (collections.abc のクラス)
    • (typing のクラス)
  • byteswap() (array.array のメソッド)
    • (audioop モジュール)
  • BytesWarning
  • bz2 (モジュール)
  • BZ2Compressor (bz2 のクラス)
  • BZ2Decompressor (bz2 のクラス)
  • BZ2File (bz2 のクラス)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – C

  • C
    • language, [1], [2], [3], [4], [5]
    • structures
  • C-contiguous, [1]
  • c_bool (ctypes のクラス)
  • C_BUILTIN (imp モジュール)
  • c_byte (ctypes のクラス)
  • c_char (ctypes のクラス)
  • c_char_p (ctypes のクラス)
  • c_contiguous (memoryview の属性)
  • c_double (ctypes のクラス)
  • C_EXTENSION (imp モジュール)
  • c_float (ctypes のクラス)
  • c_int (ctypes のクラス)
  • c_int16 (ctypes のクラス)
  • c_int32 (ctypes のクラス)
  • c_int64 (ctypes のクラス)
  • c_int8 (ctypes のクラス)
  • c_long (ctypes のクラス)
  • c_longdouble (ctypes のクラス)
  • c_longlong (ctypes のクラス)
  • c_short (ctypes のクラス)
  • c_size_t (ctypes のクラス)
  • c_ssize_t (ctypes のクラス)
  • c_ubyte (ctypes のクラス)
  • c_uint (ctypes のクラス)
  • c_uint16 (ctypes のクラス)
  • c_uint32 (ctypes のクラス)
  • c_uint64 (ctypes のクラス)
  • c_uint8 (ctypes のクラス)
  • c_ulong (ctypes のクラス)
  • c_ulonglong (ctypes のクラス)
  • c_ushort (ctypes のクラス)
  • c_void_p (ctypes のクラス)
  • c_wchar (ctypes のクラス)
  • c_wchar_p (ctypes のクラス)
  • CAB (msilib のクラス)
  • cache_from_source() (imp モジュール)
    • (importlib.util モジュール)
  • cached (importlib.machinery.ModuleSpec の属性)
  • CacheFTPHandler (urllib.request のクラス)
  • calcobjsize() (test.support モジュール)
  • calcsize() (struct モジュール)
  • calcvobjsize() (test.support モジュール)
  • Calendar (calendar のクラス)
  • calendar (モジュール)
  • calendar() (calendar モジュール)
  • call
    • built-in function
    • built-in method
    • class instance
    • class object, [1], [2]
    • function, [1], [2]
    • instance, [1]
    • method
    • procedure
    • user-defined function
  • call() (subprocess モジュール)
    • (unittest.mock モジュール)
  • call_args (unittest.mock.Mock の属性)
  • call_args_list (unittest.mock.Mock の属性)
  • call_at() (asyncio.loop のメソッド)
  • call_count (unittest.mock.Mock の属性)
  • call_exception_handler() (asyncio.loop のメソッド)
  • CALL_FUNCTION (opcode)
  • CALL_FUNCTION_EX (opcode)
  • CALL_FUNCTION_KW (opcode)
  • call_later() (asyncio.loop のメソッド)
  • call_list() (unittest.mock.call のメソッド)
  • CALL_METHOD (opcode)
  • call_soon() (asyncio.loop のメソッド)
  • call_soon_threadsafe() (asyncio.loop のメソッド)
  • call_tracing() (sys モジュール)
  • callable
    • オブジェクト, [1]
  • Callable (collections.abc のクラス)
    • (typing モジュール)
  • callable() (組み込み関数)
  • CallableProxyType (weakref モジュール)
  • callback (optparse.Option の属性)
  • callback() (contextlib.ExitStack のメソッド)
  • callback_args (optparse.Option の属性)
  • callback_kwargs (optparse.Option の属性)
  • callbacks (gc モジュール)
  • called (unittest.mock.Mock の属性)
  • CalledProcessError
  • calloc()
  • CAN_BCM (socket モジュール)
  • can_change_color() (curses モジュール)
  • can_fetch() (urllib.robotparser.RobotFileParser のメソッド)
  • CAN_ISOTP (socket モジュール)
  • CAN_RAW_FD_FRAMES (socket モジュール)
  • can_symlink() (test.support モジュール)
  • can_write_eof() (asyncio.StreamWriter のメソッド)
    • (asyncio.WriteTransport のメソッド)
  • can_xattr() (test.support モジュール)
  • cancel() (asyncio.Future のメソッド)
    • (asyncio.Handle のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
    • (sched.scheduler のメソッド)
    • (threading.Timer のメソッド)
  • cancel_dump_traceback_later() (faulthandler モジュール)
  • cancel_join_thread() (multiprocessing.Queue のメソッド)
  • cancelled() (asyncio.Future のメソッド)
    • (asyncio.Handle のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
  • CancelledError, [1]
  • CannotSendHeader
  • CannotSendRequest
  • canonic() (bdb.Bdb のメソッド)
  • canonical() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • capa() (poplib.POP3 のメソッド)
  • capitalize() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • Capsule
    • オブジェクト
  • captured_stderr() (test.support モジュール)
  • captured_stdin() (test.support モジュール)
  • captured_stdout() (test.support モジュール)
  • captureWarnings() (logging モジュール)
  • capwords() (string モジュール)
  • casefold() (str のメソッド)
  • cast() (ctypes モジュール)
    • (memoryview のメソッド)
    • (typing モジュール)
  • cat() (nis モジュール)
  • catch_warnings (warnings のクラス)
  • category() (unicodedata モジュール)
  • cbreak() (curses モジュール)
  • CC
  • ccc() (ftplib.FTP_TLS のメソッド)
  • CCompiler (distutils.ccompiler のクラス)
  • CDLL (ctypes のクラス)
  • ceil() (in module math)
    • (math モジュール)
  • center() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • CERT_NONE (ssl モジュール)
  • CERT_OPTIONAL (ssl モジュール)
  • CERT_REQUIRED (ssl モジュール)
  • cert_store_stats() (ssl.SSLContext のメソッド)
  • cert_time_to_seconds() (ssl モジュール)
  • CertificateError
  • certificates
  • CFLAGS, [1], [2], [3]
  • CFUNCTYPE() (ctypes モジュール)
  • CGI
    • debugging
    • exceptions
    • protocol
    • security
    • tracebacks
  • cgi (モジュール)
  • cgi_directories (http.server.CGIHTTPRequestHandler の属性)
  • CGIHandler (wsgiref.handlers のクラス)
  • CGIHTTPRequestHandler (http.server のクラス)
  • cgitb (モジュール)
  • CGIXMLRPCRequestHandler (xmlrpc.server のクラス)
  • chain() (itertools モジュール)
  • chaining
    • comparisons, [1]
    • exception
  • ChainMap (collections のクラス)
    • (typing のクラス)
  • change_cwd() (test.support モジュール)
  • change_root() (distutils.util モジュール)
  • CHANNEL_BINDING_TYPES (ssl モジュール)
  • channel_class (smtpd.SMTPServer の属性)
  • channels() (ossaudiodev.oss_audio_device のメソッド)
  • CHAR_MAX (locale モジュール)
  • character, [1], [2]
  • CharacterDataHandler() (xml.parsers.expat.xmlparser のメソッド)
  • characters() (xml.sax.handler.ContentHandler のメソッド)
  • characters_written (BlockingIOError の属性)
  • Charset (email.charset のクラス)
  • charset() (gettext.NullTranslations のメソッド)
  • chdir() (os モジュール)
  • check (lzma.LZMADecompressor の属性)
  • check() (imaplib.IMAP4 のメソッド)
    • (tabnanny モジュール)
  • check__all__() (test.support モジュール)
  • check_call() (subprocess モジュール)
  • check_environ() (distutils.util モジュール)
  • check_free_after_iterating() (test.support モジュール)
  • check_hostname (ssl.SSLContext の属性)
  • check_impl_detail() (test.support モジュール)
  • check_no_resource_warning() (test.support モジュール)
  • check_output() (doctest.OutputChecker のメソッド)
    • (subprocess モジュール)
  • check_returncode() (subprocess.CompletedProcess のメソッド)
  • check_syntax_error() (test.support モジュール)
  • check_unused_args() (string.Formatter のメソッド)
  • check_warnings() (test.support モジュール)
  • checkbox() (msilib.Dialog のメソッド)
  • checkcache() (linecache モジュール)
  • CHECKED_HASH (py_compile.PycInvalidationMode の属性)
  • checkfuncname() (bdb モジュール)
  • CheckList (tkinter.tix のクラス)
  • checksizeof() (test.support モジュール)
  • checksum
    • Cyclic Redundancy Check
  • chflags() (os モジュール)
  • chgat() (curses.window のメソッド)
  • childNodes (xml.dom.Node の属性)
  • ChildProcessError
  • children (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
  • chmod() (os モジュール)
    • (pathlib.Path のメソッド)
  • choice() (random モジュール)
    • (secrets モジュール)
  • choices (optparse.Option の属性)
  • choices() (random モジュール)
  • chown() (os モジュール)
    • (shutil モジュール)
  • chr
    • 組み込み関数
  • chr() (組み込み関数)
  • chroot() (os モジュール)
  • Chunk (chunk のクラス)
  • chunk (モジュール)
  • cipher
    • DES
  • cipher() (ssl.SSLSocket のメソッド)
  • circle() (turtle モジュール)
  • CIRCUMFLEX (token モジュール)
  • CIRCUMFLEXEQUAL (token モジュール)
  • Clamped (decimal のクラス)
  • class
    • attribute
    • attribute assignment
    • body
    • constructor
    • definition, [1]
    • instance
    • name
    • オブジェクト, [1], [2]
    • 文
  • Class (symtable のクラス)
  • Class browser
  • class instance
    • attribute
    • attribute assignment
    • call
    • オブジェクト, [1], [2]
  • class object
    • call, [1], [2]
  • class variable
  • classmethod
    • 組み込み関数
  • classmethod() (組み込み関数)
  • ClassMethodDescriptorType (types モジュール)
  • ClassVar (typing モジュール)
  • clause
  • CLD_CONTINUED (os モジュール)
  • CLD_DUMPED (os モジュール)
  • CLD_EXITED (os モジュール)
  • CLD_TRAPPED (os モジュール)
  • clean() (mailbox.Maildir のメソッド)
  • cleandoc() (inspect モジュール)
  • CleanImport (test.support のクラス)
  • cleanup functions
  • clear (pdb command)
  • Clear Breakpoint
  • clear() (asyncio.Event のメソッド)
    • (collections.deque のメソッド)
    • (curses.window のメソッド)
    • (dict のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (frame のメソッド)
    • (frozenset のメソッド)
    • (http.cookiejar.CookieJar のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (sequence method)
    • (threading.Event のメソッド)
    • (turtle モジュール), [1]
    • (xml.etree.ElementTree.Element のメソッド)
  • clear_all_breaks() (bdb.Bdb のメソッド)
  • clear_all_file_breaks() (bdb.Bdb のメソッド)
  • clear_bpbynumber() (bdb.Bdb のメソッド)
  • clear_break() (bdb.Bdb のメソッド)
  • clear_cache() (filecmp モジュール)
  • clear_content() (email.message.EmailMessage のメソッド)
  • clear_flags() (decimal.Context のメソッド)
  • clear_frames() (traceback モジュール)
  • clear_history() (readline モジュール)
  • clear_session_cookies() (http.cookiejar.CookieJar のメソッド)
  • clear_traces() (tracemalloc モジュール)
  • clear_traps() (decimal.Context のメソッド)
  • clearcache() (linecache モジュール)
  • ClearData() (msilib.Record のメソッド)
  • clearok() (curses.window のメソッド)
  • clearscreen() (turtle モジュール)
  • clearstamp() (turtle モジュール)
  • clearstamps() (turtle モジュール)
  • Client() (multiprocessing.connection モジュール)
  • client_address (http.server.BaseHTTPRequestHandler の属性)
  • clock() (time モジュール)
  • CLOCK_BOOTTIME (time モジュール)
  • clock_getres() (time モジュール)
  • clock_gettime() (time モジュール)
  • clock_gettime_ns() (time モジュール)
  • CLOCK_HIGHRES (time モジュール)
  • CLOCK_MONOTONIC (time モジュール)
  • CLOCK_MONOTONIC_RAW (time モジュール)
  • CLOCK_PROCESS_CPUTIME_ID (time モジュール)
  • CLOCK_PROF (time モジュール)
  • CLOCK_REALTIME (time モジュール)
  • clock_settime() (time モジュール)
  • clock_settime_ns() (time モジュール)
  • CLOCK_THREAD_CPUTIME_ID (time モジュール)
  • CLOCK_UPTIME (time モジュール)
  • clone() (email.generator.BytesGenerator のメソッド)
    • (email.generator.Generator のメソッド)
    • (email.policy.Policy のメソッド)
    • (pipes.Template のメソッド)
    • (turtle モジュール)
  • cloneNode() (xml.dom.Node のメソッド)
  • close() (aifc.aifc のメソッド), [1]
    • (asyncio.AbstractChildWatcher のメソッド)
    • (asyncio.BaseTransport のメソッド)
    • (asyncio.Server のメソッド)
    • (asyncio.StreamWriter のメソッド)
    • (asyncio.SubprocessTransport のメソッド)
    • (asyncio.loop のメソッド)
    • (asyncore.dispatcher のメソッド)
    • (chunk.Chunk のメソッド)
    • (contextlib.ExitStack のメソッド)
    • (coroutine のメソッド)
    • (dbm.dumb.dumbdbm のメソッド)
    • (dbm.gnu.gdbm のメソッド)
    • (dbm.ndbm.ndbm のメソッド)
    • (distutils.text_file.TextFile のメソッド)
    • (email.parser.BytesFeedParser のメソッド)
    • (fileinput モジュール)
    • (ftplib.FTP のメソッド)
    • (generator のメソッド)
    • (html.parser.HTMLParser のメソッド)
    • (http.client.HTTPConnection のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (in module os)
    • (io.IOBase のメソッド)
    • (logging.FileHandler のメソッド)
    • (logging.Handler のメソッド)
    • (logging.handlers.MemoryHandler のメソッド)
    • (logging.handlers.NTEventLogHandler のメソッド)
    • (logging.handlers.SocketHandler のメソッド)
    • (logging.handlers.SysLogHandler のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (mmap.mmap のメソッド)
  • Close() (msilib.Database のメソッド)
    • (msilib.View のメソッド)
  • close() (multiprocessing.connection.Connection のメソッド)
    • (multiprocessing.Process のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (multiprocessing.connection.Listener のメソッド)
    • (multiprocessing.pool.Pool のメソッド)
    • (os モジュール)
    • (os.scandir のメソッド)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (ossaudiodev.oss_mixer_device のメソッド)
    • (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.kqueue のメソッド)
    • (selectors.BaseSelector のメソッド)
    • (shelve.Shelf のメソッド)
    • (socket モジュール)
    • (socket.socket のメソッド)
    • (sqlite3.Connection のメソッド)
    • (sqlite3.Cursor のメソッド)
    • (sunau.AU_read のメソッド)
    • (sunau.AU_write のメソッド)
    • (tarfile.TarFile のメソッド)
    • (telnetlib.Telnet のメソッド)
    • (urllib.request.BaseHandler のメソッド)
    • (wave.Wave_read のメソッド)
    • (wave.Wave_write のメソッド)
  • Close() (winreg.PyHKEY のメソッド)
  • close() (xml.etree.ElementTree.TreeBuilder のメソッド)
    • (xml.etree.ElementTree.XMLParser のメソッド)
    • (xml.etree.ElementTree.XMLPullParser のメソッド)
    • (xml.sax.xmlreader.IncrementalParser のメソッド)
    • (zipfile.ZipFile のメソッド)
  • close_connection (http.server.BaseHTTPRequestHandler の属性)
  • close_when_done() (asynchat.async_chat のメソッド)
  • closed (http.client.HTTPResponse の属性)
    • (io.IOBase の属性)
    • (mmap.mmap の属性)
    • (ossaudiodev.oss_audio_device の属性)
    • (select.devpoll の属性)
    • (select.epoll の属性)
    • (select.kqueue の属性)
  • CloseKey() (winreg モジュール)
  • closelog() (syslog モジュール)
  • closerange() (os モジュール)
  • closing() (contextlib モジュール)
  • clrtobot() (curses.window のメソッド)
  • clrtoeol() (curses.window のメソッド)
  • cmath (モジュール)
  • cmd
    • モジュール
  • Cmd (cmd のクラス)
  • cmd (subprocess.CalledProcessError の属性)
    • (subprocess.TimeoutExpired の属性)
    • (モジュール)
  • cmdloop() (cmd.Cmd のメソッド)
  • cmdqueue (cmd.Cmd の属性)
  • cmp() (filecmp モジュール)
  • cmp_op (dis モジュール)
  • cmp_to_key() (functools モジュール)
  • cmpfiles() (filecmp モジュール)
  • CMSG_LEN() (socket モジュール)
  • CMSG_SPACE() (socket モジュール)
  • co_argcount (code object attribute)
  • CO_ASYNC_GENERATOR (inspect モジュール)
  • co_cellvars (code object attribute)
  • co_code (code object attribute)
  • co_consts (code object attribute)
  • CO_COROUTINE (inspect モジュール)
  • co_filename (code object attribute)
  • co_firstlineno (code object attribute)
  • co_flags (code object attribute)
  • co_freevars (code object attribute)
  • CO_FUTURE_DIVISION (C の変数)
  • CO_GENERATOR (inspect モジュール)
  • CO_ITERABLE_COROUTINE (inspect モジュール)
  • co_lnotab (code object attribute)
  • co_name (code object attribute)
  • co_names (code object attribute)
  • CO_NESTED (inspect モジュール)
  • CO_NEWLOCALS (inspect モジュール)
  • co_nlocals (code object attribute)
  • CO_NOFREE (inspect モジュール)
  • CO_OPTIMIZED (inspect モジュール)
  • co_stacksize (code object attribute)
  • CO_VARARGS (inspect モジュール)
  • CO_VARKEYWORDS (inspect モジュール)
  • co_varnames (code object attribute)
  • code
    • block
  • code (SystemExit の属性)
    • (urllib.error.HTTPError の属性)
    • (xml.etree.ElementTree.ParseError の属性)
    • (xml.parsers.expat.ExpatError の属性)
    • (モジュール)
  • code object, [1], [2], [3]
  • code_info() (dis モジュール)
  • CodecInfo (codecs のクラス)
  • Codecs
    • decode
    • encode
  • codecs (モジュール)
  • coded_value (http.cookies.Morsel の属性)
  • codeop (モジュール)
  • codepoint2name (html.entities モジュール)
  • codes (xml.parsers.expat.errors モジュール)
  • CODESET (locale モジュール)
  • CodeType (types モジュール)
  • coding
    • style
  • coercion
  • col_offset (ast.AST の属性)
  • collapse_addresses() (ipaddress モジュール)
  • collapse_rfc2231_value() (email.utils モジュール)
  • collect() (gc モジュール)
  • collect_incoming_data() (asynchat.async_chat のメソッド)
  • Collection (collections.abc のクラス)
    • (typing のクラス)
  • collections (モジュール)
  • collections.abc (モジュール)
  • colno (json.JSONDecodeError の属性)
    • (re.error の属性)
  • COLON (token モジュール)
  • color() (turtle モジュール)
  • color_content() (curses モジュール)
  • color_pair() (curses モジュール)
  • colormode() (turtle モジュール)
  • colorsys (モジュール)
  • COLS, [1]
  • column() (tkinter.ttk.Treeview のメソッド)
  • COLUMNS, [1]
  • columns (os.terminal_size の属性)
  • combinations() (itertools モジュール)
  • combinations_with_replacement() (itertools モジュール)
  • combine() (datetime.datetime のクラスメソッド)
  • combining() (unicodedata モジュール)
  • ComboBox (tkinter.tix のクラス)
  • Combobox (tkinter.ttk のクラス)
  • comma
    • trailing
    • tuple display
  • COMMA (token モジュール)
  • Command (distutils.cmd のクラス)
    • (distutils.core のクラス)
  • command (http.server.BaseHTTPRequestHandler の属性)
  • command line
  • CommandCompiler (codeop のクラス)
  • commands (pdb command)
  • comment
    • (http.cookiejar.Cookie の属性)
  • COMMENT (token モジュール)
  • comment (zipfile.ZipFile の属性)
    • (zipfile.ZipInfo の属性)
  • Comment() (xml.etree.ElementTree モジュール)
  • comment_url (http.cookiejar.Cookie の属性)
  • commenters (shlex.shlex の属性)
  • CommentHandler() (xml.parsers.expat.xmlparser のメソッド)
  • commit() (msilib.CAB のメソッド)
  • Commit() (msilib.Database のメソッド)
  • commit() (sqlite3.Connection のメソッド)
  • common (filecmp.dircmp の属性)
  • Common Gateway Interface
  • common_dirs (filecmp.dircmp の属性)
  • common_files (filecmp.dircmp の属性)
  • common_funny (filecmp.dircmp の属性)
  • common_types (mimetypes モジュール)
  • commonpath() (os.path モジュール)
  • commonprefix() (os.path モジュール)
  • communicate() (asyncio.asyncio.subprocess.Process のメソッド)
    • (subprocess.Popen のメソッド)
  • compare() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (difflib.Differ のメソッド)
  • compare_digest() (hmac モジュール)
    • (secrets モジュール)
  • compare_networks() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • COMPARE_OP (opcode)
  • compare_signal() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • compare_to() (tracemalloc.Snapshot のメソッド)
  • compare_total() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • compare_total_mag() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • comparing
    • objects
  • comparison
    • operator
  • COMPARISON_FLAGS (doctest モジュール)
  • comparisons
    • chaining, [1]
  • Compat32 (email.policy のクラス)
  • compat32 (email.policy モジュール)
  • compile
    • 組み込み関数, [1], [2], [3], [4]
  • Compile (codeop のクラス)
  • compile() (distutils.ccompiler.CCompiler のメソッド)
    • (parser.ST のメソッド)
    • (py_compile モジュール)
    • (re モジュール)
    • (組み込み関数)
  • compile_command() (code モジュール)
    • (codeop モジュール)
  • compile_dir() (compileall モジュール)
  • compile_file() (compileall モジュール)
  • compile_path() (compileall モジュール)
  • compileall (モジュール)
  • compileall コマンドラインオプション
    • --invalidation-mode [timestamp|checked-hash|unchecked-hash]
    • -b
    • -d destdir
    • -f
    • -i list
    • -j N
    • -l
    • -q
    • -r
    • -x regex
    • directory ...
    • file ...
  • compilest() (parser モジュール)
  • complete() (rlcompleter.Completer のメソッド)
  • complete_statement() (sqlite3 モジュール)
  • completedefault() (cmd.Cmd のメソッド)
  • CompletedProcess (subprocess のクラス)
  • complex
    • number
    • オブジェクト
    • 組み込み関数, [1]
  • Complex (numbers のクラス)
  • complex (組み込みクラス)
  • complex literal
  • complex number
    • literals
    • オブジェクト, [1]
  • compound
    • statement
  • comprehensions
    • list
  • compress() (bz2 モジュール)
    • (bz2.BZ2Compressor のメソッド)
    • (gzip モジュール)
    • (itertools モジュール)
    • (lzma モジュール)
    • (lzma.LZMACompressor のメソッド)
    • (zlib モジュール)
    • (zlib.Compress のメソッド)
  • compress_size (zipfile.ZipInfo の属性)
  • compress_type (zipfile.ZipInfo の属性)
  • compressed (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • compression() (ssl.SSLSocket のメソッド)
  • CompressionError
  • compressobj() (zlib モジュール)
  • COMSPEC, [1]
  • concat() (operator モジュール)
  • concatenation
    • operation
  • concurrent.futures (モジュール)
  • Condition (asyncio のクラス)
    • (multiprocessing のクラス)
  • condition (pdb command)
  • Condition (threading のクラス)
  • condition() (msilib.Control のメソッド)
  • Condition() (multiprocessing.managers.SyncManager のメソッド)
  • Conditional
    • expression
  • conditional
    • expression
  • ConfigParser (configparser のクラス)
  • configparser (モジュール)
  • configuration
    • file
    • file, debugger
    • file, path
  • configuration information
  • configure() (tkinter.ttk.Style のメソッド)
  • configure_mock() (unittest.mock.Mock のメソッド)
  • confstr() (os モジュール)
  • confstr_names (os モジュール)
  • conjugate() (complex number method)
    • (decimal.Decimal のメソッド)
    • (numbers.Complex のメソッド)
  • conn (smtpd.SMTPChannel の属性)
  • connect() (asyncore.dispatcher のメソッド)
    • (ftplib.FTP のメソッド)
    • (http.client.HTTPConnection のメソッド)
    • (multiprocessing.managers.BaseManager のメソッド)
    • (smtplib.SMTP のメソッド)
    • (socket.socket のメソッド)
    • (sqlite3 モジュール)
  • connect_accepted_socket() (asyncio.loop のメソッド)
  • connect_ex() (socket.socket のメソッド)
  • connect_read_pipe() (asyncio.loop のメソッド)
  • connect_write_pipe() (asyncio.loop のメソッド)
  • Connection (multiprocessing.connection のクラス)
    • (sqlite3 のクラス)
  • connection (sqlite3.Cursor の属性)
  • connection_lost() (asyncio.BaseProtocol のメソッド)
  • connection_made() (asyncio.BaseProtocol のメソッド)
  • ConnectionAbortedError
  • ConnectionError
  • ConnectionRefusedError
  • ConnectionResetError
  • ConnectRegistry() (winreg モジュール)
  • const (optparse.Option の属性)
  • constant
  • constructor
    • class
  • constructor() (copyreg モジュール)
  • consumed (asyncio.LimitOverrunError の属性)
  • container, [1]
    • iteration over
  • Container (collections.abc のクラス)
    • (typing のクラス)
  • contains() (operator モジュール)
  • content type
    • MIME
  • content_manager (email.policy.EmailPolicy の属性)
  • content_type (email.headerregistry.ContentTypeHeader の属性)
  • ContentDispositionHeader (email.headerregistry のクラス)
  • ContentHandler (xml.sax.handler のクラス)
  • ContentManager (email.contentmanager のクラス)
  • contents (ctypes._Pointer の属性)
  • contents() (importlib.abc.ResourceReader のメソッド)
    • (importlib.resources モジュール)
  • ContentTooShortError
  • ContentTransferEncoding (email.headerregistry のクラス)
  • ContentTypeHeader (email.headerregistry のクラス)
  • Context (contextvars のクラス)
    • (decimal のクラス)
  • context (ssl.SSLSocket の属性)
  • context management protocol
  • context manager, [1], [2]
  • context_diff() (difflib モジュール)
  • ContextDecorator (contextlib のクラス)
  • contextlib (モジュール)
  • ContextManager (typing のクラス)
  • contextmanager() (contextlib モジュール)
  • ContextVar (contextvars のクラス)
  • contextvars (モジュール)
  • contextvars.Token (contextvars のクラス)
  • contiguous, [1]
    • (memoryview の属性)
  • continue
    • 文, [1], [2], [3], [4]
  • continue (pdb command)
  • CONTINUE_LOOP (opcode)
  • Control (msilib のクラス)
    • (tkinter.tix のクラス)
  • control() (msilib.Dialog のメソッド)
    • (select.kqueue のメソッド)
  • controlnames (curses.ascii モジュール)
  • controls() (ossaudiodev.oss_mixer_device のメソッド)
  • conversion
    • arithmetic
    • string, [1]
  • ConversionError
  • conversions
    • numeric
  • convert_arg_line_to_args() (argparse.ArgumentParser のメソッド)
  • convert_field() (string.Formatter のメソッド)
  • convert_path() (distutils.util モジュール)
  • Cookie (http.cookiejar のクラス)
  • CookieError
  • CookieJar (http.cookiejar のクラス)
  • cookiejar (urllib.request.HTTPCookieProcessor の属性)
  • CookiePolicy (http.cookiejar のクラス)
  • Coordinated Universal Time
  • Copy
  • copy
    • protocol
    • モジュール
  • copy (モジュール)
  • copy() (collections.deque のメソッド)
    • (contextvars.Context のメソッド)
    • (copy モジュール)
    • (decimal.Context のメソッド)
    • (dict のメソッド)
    • (frozenset のメソッド)
    • (hashlib.hash のメソッド)
    • (hmac.HMAC のメソッド)
    • (http.cookies.Morsel のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (multiprocessing.sharedctypes モジュール)
    • (pipes.Template のメソッド)
    • (sequence method)
    • (shutil モジュール)
    • (types.MappingProxyType のメソッド)
    • (zlib.Compress のメソッド)
    • (zlib.Decompress のメソッド)
  • copy2() (shutil モジュール)
  • copy_abs() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • copy_context() (contextvars モジュール)
  • copy_decimal() (decimal.Context のメソッド)
  • copy_file() (distutils.file_util モジュール)
  • copy_location() (ast モジュール)
  • copy_negate() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • copy_sign() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • copy_tree() (distutils.dir_util モジュール)
  • copyfile() (shutil モジュール)
  • copyfileobj() (shutil モジュール)
  • copying files
  • copymode() (shutil モジュール)
  • copyreg (モジュール)
  • copyright (in module sys)
    • (sys モジュール)
    • (組み込み変数)
  • copysign() (math モジュール)
  • copystat() (shutil モジュール)
  • copytree() (shutil モジュール)
  • coroutine, [1], [2]
    • function
  • Coroutine (collections.abc のクラス)
    • (typing のクラス)
  • coroutine function
  • coroutine() (asyncio モジュール)
    • (types モジュール)
  • CoroutineType (types モジュール)
  • cos() (cmath モジュール)
    • (math モジュール)
  • cosh() (cmath モジュール)
    • (math モジュール)
  • count (tracemalloc.Statistic の属性)
    • (tracemalloc.StatisticDiff の属性)
  • count() (array.array のメソッド)
    • (bytearray のメソッド)
    • (bytes のメソッド)
    • (collections.deque のメソッド)
    • (itertools モジュール)
    • (sequence method)
    • (str のメソッド)
  • count_diff (tracemalloc.StatisticDiff の属性)
  • Counter (collections のクラス)
    • (typing のクラス)
  • countOf() (operator モジュール)
  • countTestCases() (unittest.TestCase のメソッド)
    • (unittest.TestSuite のメソッド)
  • CoverageResults (trace のクラス)
  • CPP
  • CPPFLAGS
  • cProfile (モジュール)
  • CPU time, [1], [2]
  • cpu_count() (multiprocessing モジュール)
    • (os モジュール)
  • CPython
  • cpython_only() (test.support モジュール)
  • crawl_delay() (urllib.robotparser.RobotFileParser のメソッド)
  • CRC (zipfile.ZipInfo の属性)
  • crc32() (binascii モジュール)
    • (zlib モジュール)
  • crc_hqx() (binascii モジュール)
  • create() (imaplib.IMAP4 のメソッド)
    • (venv モジュール)
    • (venv.EnvBuilder のメソッド)
  • create_aggregate() (sqlite3.Connection のメソッド)
  • create_archive() (zipapp モジュール)
  • create_autospec() (unittest.mock モジュール)
  • CREATE_BREAKAWAY_FROM_JOB (subprocess モジュール)
  • create_collation() (sqlite3.Connection のメソッド)
  • create_configuration() (venv.EnvBuilder のメソッド)
  • create_connection() (asyncio.loop のメソッド)
    • (socket モジュール)
  • create_datagram_endpoint() (asyncio.loop のメソッド)
  • create_decimal() (decimal.Context のメソッド)
  • create_decimal_from_float() (decimal.Context のメソッド)
  • create_default_context() (ssl モジュール)
  • CREATE_DEFAULT_ERROR_MODE (subprocess モジュール)
  • create_empty_file() (test.support モジュール)
  • create_function() (sqlite3.Connection のメソッド)
  • create_future() (asyncio.loop のメソッド)
  • create_module (C の関数)
  • create_module() (importlib.abc.Loader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
  • CREATE_NEW_CONSOLE (subprocess モジュール)
  • CREATE_NEW_PROCESS_GROUP (subprocess モジュール)
  • CREATE_NO_WINDOW (subprocess モジュール)
  • create_server() (asyncio.loop のメソッド)
  • create_shortcut() (組み込み関数)
  • create_socket() (asyncore.dispatcher のメソッド)
  • create_static_lib() (distutils.ccompiler.CCompiler のメソッド)
  • create_stats() (profile.Profile のメソッド)
  • create_string_buffer() (ctypes モジュール)
  • create_subprocess_exec() (asyncio モジュール)
  • create_subprocess_shell() (asyncio モジュール)
  • create_system (zipfile.ZipInfo の属性)
  • create_task() (asyncio モジュール)
    • (asyncio.loop のメソッド)
  • create_tree() (distutils.dir_util モジュール)
  • create_unicode_buffer() (ctypes モジュール)
  • create_unix_connection() (asyncio.loop のメソッド)
  • create_unix_server() (asyncio.loop のメソッド)
  • create_version (zipfile.ZipInfo の属性)
  • createAttribute() (xml.dom.Document のメソッド)
  • createAttributeNS() (xml.dom.Document のメソッド)
  • createComment() (xml.dom.Document のメソッド)
  • createDocument() (xml.dom.DOMImplementation のメソッド)
  • createDocumentType() (xml.dom.DOMImplementation のメソッド)
  • createElement() (xml.dom.Document のメソッド)
  • createElementNS() (xml.dom.Document のメソッド)
  • createfilehandler() (tkinter.Widget.tk のメソッド)
  • CreateKey() (winreg モジュール)
  • CreateKeyEx() (winreg モジュール)
  • createLock() (logging.Handler のメソッド)
    • (logging.NullHandler のメソッド)
  • createProcessingInstruction() (xml.dom.Document のメソッド)
  • CreateRecord() (msilib モジュール)
  • createSocket() (logging.handlers.SocketHandler のメソッド)
  • createTextNode() (xml.dom.Document のメソッド)
  • credits (組み込み変数)
  • critical() (logging モジュール)
    • (logging.Logger のメソッド)
  • CRNCYSTR (locale モジュール)
  • cross() (audioop モジュール)
  • crypt
    • モジュール
  • crypt (モジュール)
  • crypt() (crypt モジュール)
  • crypt(3), [1], [2]
  • cryptography
  • cssclass_month (calendar.HTMLCalendar の属性)
  • cssclass_month_head (calendar.HTMLCalendar の属性)
  • cssclass_noday (calendar.HTMLCalendar の属性)
  • cssclass_year (calendar.HTMLCalendar の属性)
  • cssclass_year_head (calendar.HTMLCalendar の属性)
  • cssclasses (calendar.HTMLCalendar の属性)
  • cssclasses_weekday_head (calendar.HTMLCalendar の属性)
  • csv
    • (モジュール)
  • cte (email.headerregistry.ContentTransferEncoding の属性)
  • cte_type (email.policy.Policy の属性)
  • ctermid() (os モジュール)
  • ctime() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (time モジュール)
  • ctrl() (curses.ascii モジュール)
  • CTRL_BREAK_EVENT (signal モジュール)
  • CTRL_C_EVENT (signal モジュール)
  • ctypes (モジュール)
  • curdir (os モジュール)
  • currency() (locale モジュール)
  • current() (tkinter.ttk.Combobox のメソッド)
  • current_process() (multiprocessing モジュール)
  • current_task() (asyncio モジュール)
    • (asyncio.Task のクラスメソッド)
  • current_thread() (threading モジュール)
  • CurrentByteIndex (xml.parsers.expat.xmlparser の属性)
  • CurrentColumnNumber (xml.parsers.expat.xmlparser の属性)
  • currentframe() (inspect モジュール)
  • CurrentLineNumber (xml.parsers.expat.xmlparser の属性)
  • curs_set() (curses モジュール)
  • curses (モジュール)
  • curses.ascii (モジュール)
  • curses.panel (モジュール)
  • curses.textpad (モジュール)
  • Cursor (sqlite3 のクラス)
  • cursor() (sqlite3.Connection のメソッド)
  • cursyncup() (curses.window のメソッド)
  • customize_compiler() (distutils.sysconfig モジュール)
  • Cut
  • cwd() (ftplib.FTP のメソッド)
    • (pathlib.Path のクラスメソッド)
  • cycle() (itertools モジュール)
  • Cyclic Redundancy Check

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – D

  • D_FMT (locale モジュール)
  • D_T_FMT (locale モジュール)
  • daemon (multiprocessing.Process の属性)
    • (threading.Thread の属性)
  • dangling
    • else
  • data
    • packing binary
    • tabular
    • type
    • type, immutable
  • data (collections.UserDict の属性)
    • (collections.UserList の属性)
    • (collections.UserString の属性)
  • Data (plistlib のクラス)
  • data (select.kevent の属性)
    • (selectors.SelectorKey の属性)
    • (urllib.request.Request の属性)
    • (xml.dom.Comment の属性)
    • (xml.dom.ProcessingInstruction の属性)
    • (xml.dom.Text の属性)
    • (xmlrpc.client.Binary の属性)
  • data() (xml.etree.ElementTree.TreeBuilder のメソッド)
  • data_open() (urllib.request.DataHandler のメソッド)
  • data_received() (asyncio.Protocol のメソッド)
  • database
    • Unicode
  • DatabaseError
  • databases
  • dataclass() (dataclasses モジュール)
  • dataclasses (モジュール)
  • datagram_received() (asyncio.DatagramProtocol のメソッド)
  • DatagramHandler (logging.handlers のクラス)
  • DatagramProtocol (asyncio のクラス)
  • DatagramRequestHandler (socketserver のクラス)
  • DatagramTransport (asyncio のクラス)
  • DataHandler (urllib.request のクラス)
  • date (datetime のクラス)
  • date() (datetime.datetime のメソッド)
    • (nntplib.NNTP のメソッド)
  • date_time (zipfile.ZipInfo の属性)
  • date_time_string() (http.server.BaseHTTPRequestHandler のメソッド)
  • DateHeader (email.headerregistry のクラス)
  • datetime (datetime のクラス)
    • (email.headerregistry.DateHeader の属性)
  • DateTime (xmlrpc.client のクラス)
  • datetime (モジュール)
  • datum
  • day (datetime.date の属性)
    • (datetime.datetime の属性)
  • day_abbr (calendar モジュール)
  • day_name (calendar モジュール)
  • daylight (time モジュール)
  • Daylight Saving Time
  • DbfilenameShelf (shelve のクラス)
  • dbm (モジュール)
  • dbm.dumb (モジュール)
  • dbm.gnu
    • モジュール, [1]
  • dbm.gnu (モジュール)
  • dbm.ndbm
    • モジュール, [1]
  • dbm.ndbm (モジュール)
  • dcgettext() (locale モジュール)
  • deallocation, object
  • debug (imaplib.IMAP4 の属性)
  • DEBUG (re モジュール)
  • debug (shlex.shlex の属性)
    • (zipfile.ZipFile の属性)
  • debug() (doctest モジュール)
    • (logging モジュール)
    • (logging.Logger のメソッド)
    • (pipes.Template のメソッド)
    • (unittest.TestCase のメソッド)
    • (unittest.TestSuite のメソッド)
  • DEBUG_BYTECODE_SUFFIXES (importlib.machinery モジュール)
  • DEBUG_COLLECTABLE (gc モジュール)
  • DEBUG_LEAK (gc モジュール)
  • debug_print() (distutils.ccompiler.CCompiler のメソッド)
  • DEBUG_SAVEALL (gc モジュール)
  • debug_src() (doctest モジュール)
  • DEBUG_STATS (gc モジュール)
  • DEBUG_UNCOLLECTABLE (gc モジュール)
  • debugger, [1], [2]
    • configuration file
  • debugging
    • CGI
    • assertions
  • DebuggingServer (smtpd のクラス)
  • debuglevel (http.client.HTTPResponse の属性)
  • DebugRunner (doctest のクラス)
  • Decimal (decimal のクラス)
  • decimal (モジュール)
  • decimal literal
  • decimal() (unicodedata モジュール)
  • DecimalException (decimal のクラス)
  • decode
    • Codecs
  • decode (codecs.CodecInfo の属性)
  • decode() (base64 モジュール)
    • (bytearray のメソッド)
    • (bytes のメソッド)
    • (codecs モジュール)
    • (codecs.Codec のメソッド)
    • (codecs.IncrementalDecoder のメソッド)
    • (json.JSONDecoder のメソッド)
    • (quopri モジュール)
    • (uu モジュール)
    • (xmlrpc.client.Binary のメソッド)
    • (xmlrpc.client.DateTime のメソッド)
  • decode_header() (email.header モジュール)
    • (nntplib モジュール)
  • decode_params() (email.utils モジュール)
  • decode_rfc2231() (email.utils モジュール)
  • decode_source() (importlib.util モジュール)
  • decodebytes() (base64 モジュール)
  • DecodedGenerator (email.generator のクラス)
  • decodestring() (base64 モジュール)
    • (quopri モジュール)
  • decomposition() (unicodedata モジュール)
  • decompress() (bz2 モジュール)
    • (bz2.BZ2Decompressor のメソッド)
    • (gzip モジュール)
    • (lzma モジュール)
    • (lzma.LZMADecompressor のメソッド)
    • (zlib モジュール)
    • (zlib.Decompress のメソッド)
  • decompressobj() (zlib モジュール)
  • decorator
  • DEDENT (token モジュール)
  • DEDENT token, [1]
  • dedent() (textwrap モジュール)
  • deepcopy() (copy モジュール)
  • def
    • 文
  • def_prog_mode() (curses モジュール)
  • def_shell_mode() (curses モジュール)
  • default
    • parameter value
  • default (email.policy モジュール)
    • (inspect.Parameter の属性)
    • (optparse.Option の属性)
  • DEFAULT (unittest.mock モジュール)
  • default() (cmd.Cmd のメソッド)
    • (json.JSONEncoder のメソッド)
  • DEFAULT_BUFFER_SIZE (io モジュール)
  • default_bufsize (xml.dom.pulldom モジュール)
  • default_exception_handler() (asyncio.loop のメソッド)
  • default_factory (collections.defaultdict の属性)
  • DEFAULT_FORMAT (tarfile モジュール)
  • DEFAULT_IGNORES (filecmp モジュール)
  • default_open() (urllib.request.BaseHandler のメソッド)
  • DEFAULT_PROTOCOL (pickle モジュール)
  • default_timer() (timeit モジュール)
  • DefaultContext (decimal のクラス)
  • DefaultCookiePolicy (http.cookiejar のクラス)
  • defaultdict (collections のクラス)
  • DefaultDict (typing のクラス)
  • DefaultEventLoopPolicy (asyncio のクラス)
  • DefaultHandler() (xml.parsers.expat.xmlparser のメソッド)
  • DefaultHandlerExpand() (xml.parsers.expat.xmlparser のメソッド)
  • defaults() (configparser.ConfigParser のメソッド)
  • DefaultSelector (selectors のクラス)
  • defaultTestLoader (unittest モジュール)
  • defaultTestResult() (unittest.TestCase のメソッド)
  • defects (email.headerregistry.BaseHeader の属性)
    • (email.message.EmailMessage の属性)
    • (email.message.Message の属性)
  • define_macro() (distutils.ccompiler.CCompiler のメソッド)
  • definition
    • class, [1]
    • function, [1]
  • defpath (os モジュール)
  • DefragResult (urllib.parse のクラス)
  • DefragResultBytes (urllib.parse のクラス)
  • degrees() (math モジュール)
    • (turtle モジュール)
  • del
    • 文, [1], [2], [3]
  • del_param() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • delattr() (組み込み関数)
  • delay() (turtle モジュール)
  • delay_output() (curses モジュール)
  • delayload (http.cookiejar.FileCookieJar の属性)
  • delch() (curses.window のメソッド)
  • dele() (poplib.POP3 のメソッド)
  • delete() (ftplib.FTP のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
  • DELETE_ATTR (opcode)
  • DELETE_DEREF (opcode)
  • DELETE_FAST (opcode)
  • DELETE_GLOBAL (opcode)
  • DELETE_NAME (opcode)
  • DELETE_SUBSCR (opcode)
  • deleteacl() (imaplib.IMAP4 のメソッド)
  • deletefilehandler() (tkinter.Widget.tk のメソッド)
  • DeleteKey() (winreg モジュール)
  • DeleteKeyEx() (winreg モジュール)
  • deleteln() (curses.window のメソッド)
  • deleteMe() (bdb.Breakpoint のメソッド)
  • DeleteValue() (winreg モジュール)
  • deletion
    • attribute
    • target
    • target list
  • delimiter (csv.Dialect の属性)
  • delimiters
  • delitem() (operator モジュール)
  • deliver_challenge() (multiprocessing.connection モジュール)
  • delocalize() (locale モジュール)
  • demo_app() (wsgiref.simple_server モジュール)
  • denominator (fractions.Fraction の属性)
    • (numbers.Rational の属性)
  • DeprecationWarning
  • deque (collections のクラス)
  • Deque (typing のクラス)
  • dequeue() (logging.handlers.QueueListener のメソッド)
  • DER_cert_to_PEM_cert() (ssl モジュール)
  • derwin() (curses.window のメソッド)
  • DES
    • cipher
  • description (sqlite3.Cursor の属性)
  • description() (nntplib.NNTP のメソッド)
  • descriptions() (nntplib.NNTP のメソッド)
  • descriptor
  • dest (optparse.Option の属性)
  • destructor, [1]
  • detach() (io.BufferedIOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (socket.socket のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
    • (weakref.finalize のメソッド)
  • Detach() (winreg.PyHKEY のメソッド)
  • DETACHED_PROCESS (subprocess モジュール)
  • detect_api_mismatch() (test.support モジュール)
  • detect_encoding() (tokenize モジュール)
  • detect_language() (distutils.ccompiler.CCompiler のメソッド)
  • deterministic profiling
  • device_encoding() (os モジュール)
  • devnull (os モジュール)
  • DEVNULL (subprocess モジュール)
  • devpoll() (select モジュール)
  • DevpollSelector (selectors のクラス)
  • dgettext() (gettext モジュール)
    • (locale モジュール)
  • Dialect (csv のクラス)
  • dialect (csv.csvreader の属性)
    • (csv.csvwriter の属性)
  • Dialog (msilib のクラス)
  • dict (2to3 fixer)
  • Dict (typing のクラス)
  • dict (組み込みクラス)
  • dict() (multiprocessing.managers.SyncManager のメソッド)
  • dictConfig() (logging.config モジュール)
  • dictionary
    • display
    • type, operations on
    • オブジェクト, [1], [2], [3], [4], [5], [6], [7]
  • dictionary view
  • DictReader (csv のクラス)
  • DictWriter (csv のクラス)
  • diff_bytes() (difflib モジュール)
  • diff_files (filecmp.dircmp の属性)
  • Differ (difflib のクラス), [1]
  • difference() (frozenset のメソッド)
  • difference_update() (frozenset のメソッド)
  • difflib (モジュール)
  • digest() (hashlib.hash のメソッド)
    • (hashlib.shake のメソッド)
    • (hmac モジュール)
    • (hmac.HMAC のメソッド)
  • digest_size (hmac.HMAC の属性)
  • digit() (unicodedata モジュール)
  • digits (string モジュール)
  • dir() (ftplib.FTP のメソッド)
    • (組み込み関数)
  • dircmp (filecmp のクラス)
  • directory
    • changing
    • creating
    • deleting, [1]
    • site-packages
    • traversal, [1]
    • walking, [1]
  • directory (http.server.SimpleHTTPRequestHandler の属性)
  • Directory (msilib のクラス)
  • directory ...
    • compileall コマンドラインオプション
  • directory_created() (組み込み関数)
  • DirEntry (os のクラス)
  • DirList (tkinter.tix のクラス)
  • dirname() (os.path モジュール)
  • DirSelectBox (tkinter.tix のクラス)
  • DirSelectDialog (tkinter.tix のクラス)
  • DirsOnSysPath (test.support のクラス)
  • DirTree (tkinter.tix のクラス)
  • dis (モジュール)
  • dis() (dis モジュール)
    • (dis.Bytecode のメソッド)
    • (pickletools モジュール)
  • disable (pdb command)
  • disable() (bdb.Breakpoint のメソッド)
    • (faulthandler モジュール)
    • (gc モジュール)
    • (logging モジュール)
    • (profile.Profile のメソッド)
  • disable_faulthandler() (test.support モジュール)
  • disable_gc() (test.support モジュール)
  • disable_interspersed_args() (optparse.OptionParser のメソッド)
  • DisableReflectionKey() (winreg モジュール)
  • disassemble() (dis モジュール)
  • discard (http.cookiejar.Cookie の属性)
  • discard() (frozenset のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.Mailbox のメソッド)
  • discard_buffers() (asynchat.async_chat のメソッド)
  • disco() (dis モジュール)
  • discover() (unittest.TestLoader のメソッド)
  • disk_usage() (shutil モジュール)
  • dispatch_call() (bdb.Bdb のメソッド)
  • dispatch_exception() (bdb.Bdb のメソッド)
  • dispatch_line() (bdb.Bdb のメソッド)
  • dispatch_return() (bdb.Bdb のメソッド)
  • dispatch_table (pickle.Pickler の属性)
  • dispatcher (asyncore のクラス)
  • dispatcher_with_send (asyncore のクラス)
  • display
    • dictionary
    • list
    • set
    • tuple
  • display (pdb command)
  • display_name (email.headerregistry.Address の属性)
    • (email.headerregistry.Group の属性)
  • displayhook() (sys モジュール)
  • dist() (platform モジュール)
  • distance() (turtle モジュール)
  • distb() (dis モジュール)
  • Distribution (distutils.core のクラス)
  • distutils (モジュール)
  • distutils.archive_util (モジュール)
  • distutils.bcppcompiler (モジュール)
  • distutils.ccompiler (モジュール)
  • distutils.cmd (モジュール)
  • distutils.command (モジュール)
  • distutils.command.bdist (モジュール)
  • distutils.command.bdist_dumb (モジュール)
  • distutils.command.bdist_msi (モジュール)
  • distutils.command.bdist_packager (モジュール)
  • distutils.command.bdist_rpm (モジュール)
  • distutils.command.bdist_wininst (モジュール)
  • distutils.command.build (モジュール)
  • distutils.command.build_clib (モジュール)
  • distutils.command.build_ext (モジュール)
  • distutils.command.build_py (モジュール)
  • distutils.command.build_scripts (モジュール)
  • distutils.command.check (モジュール)
  • distutils.command.clean (モジュール)
  • distutils.command.config (モジュール)
  • distutils.command.install (モジュール)
  • distutils.command.install_data (モジュール)
  • distutils.command.install_headers (モジュール)
  • distutils.command.install_lib (モジュール)
  • distutils.command.install_scripts (モジュール)
  • distutils.command.register (モジュール)
  • distutils.command.sdist (モジュール)
  • distutils.core (モジュール)
  • distutils.cygwinccompiler (モジュール)
  • distutils.debug (モジュール)
  • distutils.dep_util (モジュール)
  • distutils.dir_util (モジュール)
  • distutils.dist (モジュール)
  • distutils.errors (モジュール)
  • distutils.extension (モジュール)
  • distutils.fancy_getopt (モジュール)
  • distutils.file_util (モジュール)
  • distutils.filelist (モジュール)
  • distutils.log (モジュール)
  • distutils.msvccompiler (モジュール)
  • distutils.spawn (モジュール)
  • distutils.sysconfig (モジュール)
  • distutils.text_file (モジュール)
  • distutils.unixccompiler (モジュール)
  • distutils.util (モジュール)
  • distutils.version (モジュール)
  • DISTUTILS_DEBUG
  • divide() (decimal.Context のメソッド)
  • divide_int() (decimal.Context のメソッド)
  • division
  • DivisionByZero (decimal のクラス)
  • divmod
    • 組み込み関数, [1], [2]
  • divmod() (decimal.Context のメソッド)
    • (組み込み関数)
  • DllCanUnloadNow() (ctypes モジュール)
  • DllGetClassObject() (ctypes モジュール)
  • dllhandle (sys モジュール)
  • dngettext() (gettext モジュール)
  • do_clear() (bdb.Bdb のメソッド)
  • do_command() (curses.textpad.Textbox のメソッド)
  • do_GET() (http.server.SimpleHTTPRequestHandler のメソッド)
  • do_handshake() (ssl.SSLSocket のメソッド)
  • do_HEAD() (http.server.SimpleHTTPRequestHandler のメソッド)
  • do_POST() (http.server.CGIHTTPRequestHandler のメソッド)
  • doc (json.JSONDecodeError の属性)
  • doc_header (cmd.Cmd の属性)
  • DocCGIXMLRPCRequestHandler (xmlrpc.server のクラス)
  • DocFileSuite() (doctest モジュール)
  • doCleanups() (unittest.TestCase のメソッド)
  • docmd() (smtplib.SMTP のメソッド)
  • docstring, [1]
    • (doctest.DocTest の属性)
  • docstrings, [1]
  • DocTest (doctest のクラス)
  • doctest (モジュール)
  • DocTestFailure
  • DocTestFinder (doctest のクラス)
  • DocTestParser (doctest のクラス)
  • DocTestRunner (doctest のクラス)
  • DocTestSuite() (doctest モジュール)
  • doctype() (xml.etree.ElementTree.TreeBuilder のメソッド)
    • (xml.etree.ElementTree.XMLParser のメソッド)
  • documentation
    • generation
    • online
  • documentation string
  • documentation strings, [1]
  • documentElement (xml.dom.Document の属性)
  • DocXMLRPCRequestHandler (xmlrpc.server のクラス)
  • DocXMLRPCServer (xmlrpc.server のクラス)
  • domain (email.headerregistry.Address の属性)
    • (tracemalloc.DomainFilter の属性)
    • (tracemalloc.Filter の属性)
    • (tracemalloc.Trace の属性)
  • domain_initial_dot (http.cookiejar.Cookie の属性)
  • domain_return_ok() (http.cookiejar.CookiePolicy のメソッド)
  • domain_specified (http.cookiejar.Cookie の属性)
  • DomainFilter (tracemalloc のクラス)
  • DomainLiberal (http.cookiejar.DefaultCookiePolicy の属性)
  • DomainRFC2965Match (http.cookiejar.DefaultCookiePolicy の属性)
  • DomainStrict (http.cookiejar.DefaultCookiePolicy の属性)
  • DomainStrictNoDots (http.cookiejar.DefaultCookiePolicy の属性)
  • DomainStrictNonDomain (http.cookiejar.DefaultCookiePolicy の属性)
  • DOMEventStream (xml.dom.pulldom のクラス)
  • DOMException
  • DomstringSizeErr
  • done() (asyncio.Future のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
    • (turtle モジュール)
    • (xdrlib.Unpacker のメソッド)
  • DONT_ACCEPT_BLANKLINE (doctest モジュール)
  • DONT_ACCEPT_TRUE_FOR_1 (doctest モジュール)
  • dont_write_bytecode (sys モジュール)
  • doRollover() (logging.handlers.RotatingFileHandler のメソッド)
    • (logging.handlers.TimedRotatingFileHandler のメソッド)
  • DOT (token モジュール)
  • dot() (turtle モジュール)
  • DOTALL (re モジュール)
  • doublequote (csv.Dialect の属性)
  • DOUBLESLASH (token モジュール)
  • DOUBLESLASHEQUAL (token モジュール)
  • DOUBLESTAR (token モジュール)
  • DOUBLESTAREQUAL (token モジュール)
  • doupdate() (curses モジュール)
  • down (pdb command)
  • down() (turtle モジュール)
  • drain() (asyncio.StreamWriter のメソッド)
  • drop_whitespace (textwrap.TextWrapper の属性)
  • dropwhile() (itertools モジュール)
  • dst() (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (datetime.timezone のメソッド)
    • (datetime.tzinfo のメソッド)
  • DTDHandler (xml.sax.handler のクラス)
  • duck-typing
  • DumbWriter (formatter のクラス)
  • dummy_threading (モジュール)
  • dump() (ast モジュール)
    • (json モジュール)
    • (marshal モジュール)
    • (pickle モジュール)
    • (pickle.Pickler のメソッド)
    • (plistlib モジュール)
    • (tracemalloc.Snapshot のメソッド)
    • (xml.etree.ElementTree モジュール)
  • dump_stats() (profile.Profile のメソッド)
    • (pstats.Stats のメソッド)
  • dump_traceback() (faulthandler モジュール)
  • dump_traceback_later() (faulthandler モジュール)
  • dumps() (json モジュール)
    • (marshal モジュール)
    • (pickle モジュール)
    • (plistlib モジュール)
    • (xmlrpc.client モジュール)
  • dup() (os モジュール)
    • (socket.socket のメソッド)
  • dup2() (os モジュール)
  • DUP_TOP (opcode)
  • DUP_TOP_TWO (opcode)
  • DuplicateOptionError
  • DuplicateSectionError
  • dwFlags (subprocess.STARTUPINFO の属性)
  • DynamicClassAttribute() (types モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – E

  • e
    • in numeric literal
  • e (cmath モジュール)
    • (math モジュール)
  • E2BIG (errno モジュール)
  • EACCES (errno モジュール)
  • EADDRINUSE (errno モジュール)
  • EADDRNOTAVAIL (errno モジュール)
  • EADV (errno モジュール)
  • EAFNOSUPPORT (errno モジュール)
  • EAFP
  • EAGAIN (errno モジュール)
  • EALREADY (errno モジュール)
  • east_asian_width() (unicodedata モジュール)
  • EBADE (errno モジュール)
  • EBADF (errno モジュール)
  • EBADFD (errno モジュール)
  • EBADMSG (errno モジュール)
  • EBADR (errno モジュール)
  • EBADRQC (errno モジュール)
  • EBADSLT (errno モジュール)
  • EBFONT (errno モジュール)
  • EBUSY (errno モジュール)
  • ECHILD (errno モジュール)
  • echo() (curses モジュール)
  • echochar() (curses.window のメソッド)
  • ECHRNG (errno モジュール)
  • ECOMM (errno モジュール)
  • ECONNABORTED (errno モジュール)
  • ECONNREFUSED (errno モジュール)
  • ECONNRESET (errno モジュール)
  • EDEADLK (errno モジュール)
  • EDEADLOCK (errno モジュール)
  • EDESTADDRREQ (errno モジュール)
  • edit() (curses.textpad.Textbox のメソッド)
  • EDOM (errno モジュール)
  • EDOTDOT (errno モジュール)
  • EDQUOT (errno モジュール)
  • EEXIST (errno モジュール)
  • EFAULT (errno モジュール)
  • EFBIG (errno モジュール)
  • effective() (bdb モジュール)
  • ehlo() (smtplib.SMTP のメソッド)
  • ehlo_or_helo_if_needed() (smtplib.SMTP のメソッド)
  • EHOSTDOWN (errno モジュール)
  • EHOSTUNREACH (errno モジュール)
  • EIDRM (errno モジュール)
  • EILSEQ (errno モジュール)
  • EINPROGRESS (errno モジュール)
  • EINTR (errno モジュール)
  • EINVAL (errno モジュール)
  • EIO (errno モジュール)
  • EISCONN (errno モジュール)
  • EISDIR (errno モジュール)
  • EISNAM (errno モジュール)
  • EL2HLT (errno モジュール)
  • EL2NSYNC (errno モジュール)
  • EL3HLT (errno モジュール)
  • EL3RST (errno モジュール)
  • Element (xml.etree.ElementTree のクラス)
  • element_create() (tkinter.ttk.Style のメソッド)
  • element_names() (tkinter.ttk.Style のメソッド)
  • element_options() (tkinter.ttk.Style のメソッド)
  • ElementDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • elements() (collections.Counter のメソッド)
  • ElementTree (xml.etree.ElementTree のクラス)
  • ELIBACC (errno モジュール)
  • ELIBBAD (errno モジュール)
  • ELIBEXEC (errno モジュール)
  • ELIBMAX (errno モジュール)
  • ELIBSCN (errno モジュール)
  • elif
    • キーワード
  • Ellinghouse, Lance
  • Ellipsis
    • オブジェクト
  • ELLIPSIS (doctest モジュール)
    • (token モジュール)
  • Ellipsis (組み込み変数)
  • ELNRNG (errno モジュール)
  • ELOOP (errno モジュール)
  • else
    • conditional expression
    • dangling
    • キーワード, [1], [2], [3], [4], [5], [6], [7]
  • email (モジュール)
  • email.charset (モジュール)
  • email.contentmanager (モジュール)
  • email.encoders (モジュール)
  • email.errors (モジュール)
  • email.generator (モジュール)
  • email.header (モジュール)
  • email.headerregistry (モジュール)
  • email.iterators (モジュール)
  • email.message (モジュール), [1]
  • email.mime (モジュール)
  • email.parser (モジュール)
  • email.policy (モジュール)
  • email.utils (モジュール)
  • EmailMessage (email.message のクラス)
  • EmailPolicy (email.policy のクラス)
  • EMFILE (errno モジュール)
  • emit() (logging.FileHandler のメソッド)
    • (logging.Handler のメソッド)
    • (logging.NullHandler のメソッド)
    • (logging.StreamHandler のメソッド)
    • (logging.handlers.BufferingHandler のメソッド)
    • (logging.handlers.DatagramHandler のメソッド)
    • (logging.handlers.HTTPHandler のメソッド)
    • (logging.handlers.NTEventLogHandler のメソッド)
    • (logging.handlers.QueueHandler のメソッド)
    • (logging.handlers.RotatingFileHandler のメソッド)
    • (logging.handlers.SMTPHandler のメソッド)
    • (logging.handlers.SocketHandler のメソッド)
    • (logging.handlers.SysLogHandler のメソッド)
    • (logging.handlers.TimedRotatingFileHandler のメソッド)
    • (logging.handlers.WatchedFileHandler のメソッド)
  • EMLINK (errno モジュール)
  • Empty
  • empty
    • list
    • tuple, [1]
  • empty (inspect.Parameter の属性)
    • (inspect.Signature の属性)
  • empty() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (multiprocessing.SimpleQueue のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
    • (sched.scheduler のメソッド)
  • EMPTY_NAMESPACE (xml.dom モジュール)
  • emptyline() (cmd.Cmd のメソッド)
  • EMSGSIZE (errno モジュール)
  • EMULTIHOP (errno モジュール)
  • enable (pdb command)
  • enable() (bdb.Breakpoint のメソッド)
    • (cgitb モジュール)
    • (faulthandler モジュール)
    • (gc モジュール)
    • (imaplib.IMAP4 のメソッド)
    • (profile.Profile のメソッド)
  • enable_callback_tracebacks() (sqlite3 モジュール)
  • enable_interspersed_args() (optparse.OptionParser のメソッド)
  • enable_load_extension() (sqlite3.Connection のメソッド)
  • enable_traversal() (tkinter.ttk.Notebook のメソッド)
  • ENABLE_USER_SITE (site モジュール)
  • EnableReflectionKey() (winreg モジュール)
  • ENAMETOOLONG (errno モジュール)
  • ENAVAIL (errno モジュール)
  • enclose() (curses.window のメソッド)
  • encode
    • Codecs
  • encode (codecs.CodecInfo の属性)
  • encode() (base64 モジュール)
    • (codecs モジュール)
    • (codecs.Codec のメソッド)
    • (codecs.IncrementalEncoder のメソッド)
    • (email.header.Header のメソッド)
    • (json.JSONEncoder のメソッド)
    • (quopri モジュール)
    • (str のメソッド)
    • (uu モジュール)
    • (xmlrpc.client.Binary のメソッド)
    • (xmlrpc.client.DateTime のメソッド)
  • encode_7or8bit() (email.encoders モジュール)
  • encode_base64() (email.encoders モジュール)
  • encode_noop() (email.encoders モジュール)
  • encode_quopri() (email.encoders モジュール)
  • encode_rfc2231() (email.utils モジュール)
  • encodebytes() (base64 モジュール)
  • EncodedFile() (codecs モジュール)
  • encodePriority() (logging.handlers.SysLogHandler のメソッド)
  • encodestring() (base64 モジュール)
    • (quopri モジュール)
  • encoding
    • base64
    • quoted-printable
  • encoding (curses.window の属性)
    • (io.TextIOBase の属性)
  • ENCODING (tarfile モジュール)
    • (token モジュール)
  • encoding (UnicodeError の属性)
  • encoding declarations (source file)
  • encodings.idna (モジュール)
  • encodings.mbcs (モジュール)
  • encodings.utf_8_sig (モジュール)
  • encodings_map (mimetypes モジュール)
    • (mimetypes.MimeTypes の属性)
  • end (UnicodeError の属性)
  • end() (re.Match のメソッド)
    • (xml.etree.ElementTree.TreeBuilder のメソッド)
  • end_fill() (turtle モジュール)
  • END_FINALLY (opcode)
  • end_headers() (http.server.BaseHTTPRequestHandler のメソッド)
  • end_paragraph() (formatter.formatter のメソッド)
  • end_poly() (turtle モジュール)
  • EndCdataSectionHandler() (xml.parsers.expat.xmlparser のメソッド)
  • EndDoctypeDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • endDocument() (xml.sax.handler.ContentHandler のメソッド)
  • endElement() (xml.sax.handler.ContentHandler のメソッド)
  • EndElementHandler() (xml.parsers.expat.xmlparser のメソッド)
  • endElementNS() (xml.sax.handler.ContentHandler のメソッド)
  • endheaders() (http.client.HTTPConnection のメソッド)
  • ENDMARKER (token モジュール)
  • EndNamespaceDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • endpos (re.Match の属性)
  • endPrefixMapping() (xml.sax.handler.ContentHandler のメソッド)
  • endswith() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • endwin() (curses モジュール)
  • ENETDOWN (errno モジュール)
  • ENETRESET (errno モジュール)
  • ENETUNREACH (errno モジュール)
  • ENFILE (errno モジュール)
  • ENOANO (errno モジュール)
  • ENOBUFS (errno モジュール)
  • ENOCSI (errno モジュール)
  • ENODATA (errno モジュール)
  • ENODEV (errno モジュール)
  • ENOENT (errno モジュール)
  • ENOEXEC (errno モジュール)
  • ENOLCK (errno モジュール)
  • ENOLINK (errno モジュール)
  • ENOMEM (errno モジュール)
  • ENOMSG (errno モジュール)
  • ENONET (errno モジュール)
  • ENOPKG (errno モジュール)
  • ENOPROTOOPT (errno モジュール)
  • ENOSPC (errno モジュール)
  • ENOSR (errno モジュール)
  • ENOSTR (errno モジュール)
  • ENOSYS (errno モジュール)
  • ENOTBLK (errno モジュール)
  • ENOTCONN (errno モジュール)
  • ENOTDIR (errno モジュール)
  • ENOTEMPTY (errno モジュール)
  • ENOTNAM (errno モジュール)
  • ENOTSOCK (errno モジュール)
  • ENOTTY (errno モジュール)
  • ENOTUNIQ (errno モジュール)
  • enqueue() (logging.handlers.QueueHandler のメソッド)
  • enqueue_sentinel() (logging.handlers.QueueListener のメソッド)
  • ensure_directories() (venv.EnvBuilder のメソッド)
  • ensure_future() (asyncio モジュール)
  • ensurepip (モジュール)
  • enter() (sched.scheduler のメソッド)
  • enter_async_context() (contextlib.AsyncExitStack のメソッド)
  • enter_context() (contextlib.ExitStack のメソッド)
  • enterabs() (sched.scheduler のメソッド)
  • entities (xml.dom.DocumentType の属性)
  • EntityDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • entitydefs (html.entities モジュール)
  • EntityResolver (xml.sax.handler のクラス)
  • Enum (enum のクラス)
  • enum (モジュール)
  • enum_certificates() (ssl モジュール)
  • enum_crls() (ssl モジュール)
  • enumerate() (threading モジュール)
    • (組み込み関数)
  • EnumKey() (winreg モジュール)
  • EnumValue() (winreg モジュール)
  • EnvBuilder (venv のクラス)
  • environ (os モジュール)
    • (posix モジュール)
  • environb (os モジュール)
  • environment
  • environment variables
    • deleting
    • setting
  • EnvironmentError
  • Environments
    • virtual
  • EnvironmentVarGuard (test.support のクラス)
  • ENXIO (errno モジュール)
  • eof (bz2.BZ2Decompressor の属性)
    • (lzma.LZMADecompressor の属性)
    • (shlex.shlex の属性)
    • (ssl.MemoryBIO の属性)
    • (zlib.Decompress の属性)
  • eof_received() (asyncio.BufferedProtocol のメソッド)
    • (asyncio.Protocol のメソッド)
  • EOFError
    • (built-in exception)
  • EOPNOTSUPP (errno モジュール)
  • EOVERFLOW (errno モジュール)
  • EPERM (errno モジュール)
  • EPFNOSUPPORT (errno モジュール)
  • epilogue (email.message.EmailMessage の属性)
    • (email.message.Message の属性)
  • EPIPE (errno モジュール)
  • epoch
  • epoll() (select モジュール)
  • EpollSelector (selectors のクラス)
  • EPROTO (errno モジュール)
  • EPROTONOSUPPORT (errno モジュール)
  • EPROTOTYPE (errno モジュール)
  • eq() (operator モジュール)
  • EQEQUAL (token モジュール)
  • EQUAL (token モジュール)
  • ERA (locale モジュール)
  • ERA_D_FMT (locale モジュール)
  • ERA_D_T_FMT (locale モジュール)
  • ERA_T_FMT (locale モジュール)
  • ERANGE (errno モジュール)
  • erase() (curses.window のメソッド)
  • erasechar() (curses モジュール)
  • EREMCHG (errno モジュール)
  • EREMOTE (errno モジュール)
  • EREMOTEIO (errno モジュール)
  • ERESTART (errno モジュール)
  • erf() (math モジュール)
  • erfc() (math モジュール)
  • EROFS (errno モジュール)
  • ERR (curses モジュール)
  • errcheck (ctypes._FuncPtr の属性)
  • errcode (xmlrpc.client.ProtocolError の属性)
  • errmsg (xmlrpc.client.ProtocolError の属性)
  • errno
    • モジュール
  • errno (OSError の属性)
    • (モジュール)
  • Error, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]
  • error, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17]
  • error handling
  • error() (argparse.ArgumentParser のメソッド)
    • (logging モジュール)
    • (logging.Logger のメソッド)
    • (urllib.request.OpenerDirector のメソッド)
    • (xml.sax.handler.ErrorHandler のメソッド)
  • error_body (wsgiref.handlers.BaseHandler の属性)
  • error_content_type (http.server.BaseHTTPRequestHandler の属性)
  • error_headers (wsgiref.handlers.BaseHandler の属性)
  • error_leader() (shlex.shlex のメソッド)
  • error_message_format (http.server.BaseHTTPRequestHandler の属性)
  • error_output() (wsgiref.handlers.BaseHandler のメソッド)
  • error_perm
  • error_proto, [1]
  • error_received() (asyncio.DatagramProtocol のメソッド)
  • error_reply
  • error_status (wsgiref.handlers.BaseHandler の属性)
  • error_temp
  • ErrorByteIndex (xml.parsers.expat.xmlparser の属性)
  • errorcode (errno モジュール)
  • ErrorCode (xml.parsers.expat.xmlparser の属性)
  • ErrorColumnNumber (xml.parsers.expat.xmlparser の属性)
  • ErrorHandler (xml.sax.handler のクラス)
  • ErrorLineNumber (xml.parsers.expat.xmlparser の属性)
  • Errors
    • logging
  • errors
    • (io.TextIOBase の属性)
    • (unittest.TestLoader の属性)
    • (unittest.TestResult の属性)
  • ErrorString() (xml.parsers.expat モジュール)
  • ERRORTOKEN (token モジュール)
  • escape (shlex.shlex の属性)
  • escape sequence
  • escape() (cgi モジュール)
    • (glob モジュール)
    • (html モジュール)
    • (re モジュール)
    • (xml.sax.saxutils モジュール)
  • escapechar (csv.Dialect の属性)
  • escapedquotes (shlex.shlex の属性)
  • ESHUTDOWN (errno モジュール)
  • ESOCKTNOSUPPORT (errno モジュール)
  • ESPIPE (errno モジュール)
  • ESRCH (errno モジュール)
  • ESRMNT (errno モジュール)
  • ESTALE (errno モジュール)
  • ESTRPIPE (errno モジュール)
  • ETIME (errno モジュール)
  • ETIMEDOUT (errno モジュール)
  • Etiny() (decimal.Context のメソッド)
  • ETOOMANYREFS (errno モジュール)
  • Etop() (decimal.Context のメソッド)
  • ETXTBSY (errno モジュール)
  • EUCLEAN (errno モジュール)
  • EUNATCH (errno モジュール)
  • EUSERS (errno モジュール)
  • eval
    • 組み込み関数, [1], [2], [3], [4], [5]
  • eval() (組み込み関数)
  • evaluation
    • order
  • Event (asyncio のクラス)
    • (multiprocessing のクラス)
    • (threading のクラス)
  • event scheduling
  • event() (msilib.Control のメソッド)
  • Event() (multiprocessing.managers.SyncManager のメソッド)
  • events (selectors.SelectorKey の属性)
    • (widgets)
  • EWOULDBLOCK (errno モジュール)
  • EX_CANTCREAT (os モジュール)
  • EX_CONFIG (os モジュール)
  • EX_DATAERR (os モジュール)
  • EX_IOERR (os モジュール)
  • EX_NOHOST (os モジュール)
  • EX_NOINPUT (os モジュール)
  • EX_NOPERM (os モジュール)
  • EX_NOTFOUND (os モジュール)
  • EX_NOUSER (os モジュール)
  • EX_OK (os モジュール)
  • EX_OSERR (os モジュール)
  • EX_OSFILE (os モジュール)
  • EX_PROTOCOL (os モジュール)
  • EX_SOFTWARE (os モジュール)
  • EX_TEMPFAIL (os モジュール)
  • EX_UNAVAILABLE (os モジュール)
  • EX_USAGE (os モジュール)
  • Example (doctest のクラス)
  • example (doctest.DocTestFailure の属性)
    • (doctest.UnexpectedException の属性)
  • examples (doctest.DocTest の属性)
  • exc_info (doctest.UnexpectedException の属性)
    • (in module sys)
  • exc_info() (in module sys)
    • (sys モジュール)
  • exc_msg (doctest.Example の属性)
  • exc_type (traceback.TracebackException の属性)
  • excel (csv のクラス)
  • excel_tab (csv のクラス)
  • except
    • キーワード
    • 文
  • except (2to3 fixer)
  • excepthook() (in module sys)
    • (sys モジュール)
  • Exception
  • exception, [1]
    • chaining
    • handler
    • raising
  • EXCEPTION (tkinter モジュール)
  • exception handler
  • exception() (asyncio.Future のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
    • (logging モジュール)
    • (logging.Logger のメソッド)
  • exceptions
    • in CGI scripts
  • exclusive
    • or
  • EXDEV (errno モジュール)
  • exec
    • 組み込み関数, [1], [2], [3]
  • exec (2to3 fixer)
  • exec() (組み込み関数)
  • exec_module (C の関数)
  • exec_module() (importlib.abc.InspectLoader のメソッド)
    • (importlib.abc.Loader のメソッド)
    • (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
  • exec_prefix, [1], [2]
  • EXEC_PREFIX (distutils.sysconfig モジュール)
  • exec_prefix (sys モジュール)
  • execfile (2to3 fixer)
  • execl() (os モジュール)
  • execle() (os モジュール)
  • execlp() (os モジュール)
  • execlpe() (os モジュール)
  • executable (in module sys)
    • (sys モジュール)
  • Executable Zip Files
  • executable_filename() (distutils.ccompiler.CCompiler のメソッド)
  • execute() (distutils.ccompiler.CCompiler のメソッド)
    • (distutils.util モジュール)
  • Execute() (msilib.View のメソッド)
  • execute() (sqlite3.Connection のメソッド)
    • (sqlite3.Cursor のメソッド)
  • executemany() (sqlite3.Connection のメソッド)
    • (sqlite3.Cursor のメソッド)
  • executescript() (sqlite3.Connection のメソッド)
    • (sqlite3.Cursor のメソッド)
  • execution
    • frame, [1]
    • restricted
    • stack
  • execution model
  • ExecutionLoader (importlib.abc のクラス)
  • Executor (concurrent.futures のクラス)
  • execv() (os モジュール)
  • execve() (os モジュール)
  • execvp() (os モジュール)
  • execvpe() (os モジュール)
  • ExFileSelectBox (tkinter.tix のクラス)
  • EXFULL (errno モジュール)
  • exists() (os.path モジュール)
    • (pathlib.Path のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
  • exit (組み込み変数)
  • exit()
    • (_thread モジュール)
    • (argparse.ArgumentParser のメソッド)
    • (sys モジュール)
  • exitcode (multiprocessing.Process の属性)
  • exitfunc (2to3 fixer)
  • exitonclick() (turtle モジュール)
  • ExitStack (contextlib のクラス)
  • exp() (cmath モジュール)
    • (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (math モジュール)
  • expand() (re.Match のメソッド)
  • expand_tabs (textwrap.TextWrapper の属性)
  • ExpandEnvironmentStrings() (winreg モジュール)
  • expandNode() (xml.dom.pulldom.DOMEventStream のメソッド)
  • expandtabs() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • expanduser() (os.path モジュール)
    • (pathlib.Path のメソッド)
  • expandvars() (os.path モジュール)
  • Expat
  • ExpatError
  • expect() (telnetlib.Telnet のメソッド)
  • expected (asyncio.IncompleteReadError の属性)
  • expectedFailure() (unittest モジュール)
  • expectedFailures (unittest.TestResult の属性)
  • expires (http.cookiejar.Cookie の属性)
  • exploded (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • expm1() (math モジュール)
  • expovariate() (random モジュール)
  • expr() (parser モジュール)
  • expression, [1]
    • Conditional
    • conditional
    • generator
    • lambda, [1]
    • list, [1], [2]
    • statement
    • yield
  • expunge() (imaplib.IMAP4 のメソッド)
  • extend() (array.array のメソッド)
    • (collections.deque のメソッド)
    • (sequence method)
    • (xml.etree.ElementTree.Element のメソッド)
  • extend_path() (pkgutil モジュール)
  • EXTENDED_ARG (opcode)
  • ExtendedContext (decimal のクラス)
  • ExtendedInterpolation (configparser のクラス)
  • extendleft() (collections.deque のメソッド)
  • extension
    • module
  • Extension (distutils.core のクラス)
  • extension module
  • EXTENSION_SUFFIXES (importlib.machinery モジュール)
  • ExtensionFileLoader (importlib.machinery のクラス)
  • extensions_map (http.server.SimpleHTTPRequestHandler の属性)
  • External Data Representation, [1]
  • external_attr (zipfile.ZipInfo の属性)
  • ExternalClashError
  • ExternalEntityParserCreate() (xml.parsers.expat.xmlparser のメソッド)
  • ExternalEntityRefHandler() (xml.parsers.expat.xmlparser のメソッド)
  • extra (zipfile.ZipInfo の属性)
  • extract() (tarfile.TarFile のメソッド)
    • (traceback.StackSummary のクラスメソッド)
    • (zipfile.ZipFile のメソッド)
  • extract_cookies() (http.cookiejar.CookieJar のメソッド)
  • extract_stack() (traceback モジュール)
  • extract_tb() (traceback モジュール)
  • extract_version (zipfile.ZipInfo の属性)
  • extractall() (tarfile.TarFile のメソッド)
    • (zipfile.ZipFile のメソッド)
  • ExtractError
  • extractfile() (tarfile.TarFile のメソッド)
  • extsep (os モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – F

  • f"
    • formatted string literal
  • f'
    • formatted string literal
  • f-string, [1]
  • f_back (frame attribute)
  • f_builtins (frame attribute)
  • f_code (frame attribute)
  • f_contiguous (memoryview の属性)
  • f_globals (frame attribute)
  • f_lasti (frame attribute)
  • f_lineno (frame attribute)
  • f_locals (frame attribute)
  • F_LOCK (os モジュール)
  • F_OK (os モジュール)
  • F_TEST (os モジュール)
  • F_TLOCK (os モジュール)
  • f_trace (frame attribute)
  • f_trace_lines (frame attribute)
  • f_trace_opcodes (frame attribute)
  • F_ULOCK (os モジュール)
  • fabs() (math モジュール)
  • factorial() (math モジュール)
  • factory() (importlib.util.LazyLoader のクラスメソッド)
  • fail() (unittest.TestCase のメソッド)
  • FAIL_FAST (doctest モジュール)
  • failfast (unittest.TestResult の属性)
  • failureException (unittest.TestCase の属性)
  • failures (unittest.TestResult の属性)
  • FakePath (test.support のクラス)
  • False, [1], [2]
  • false
  • False (Built-in object)
    • (組み込み変数)
  • family (socket.socket の属性)
  • fancy_getopt() (distutils.fancy_getopt モジュール)
  • FancyGetopt (distutils.fancy_getopt のクラス)
  • FancyURLopener (urllib.request のクラス)
  • fast (pickle.Pickler の属性)
  • FastChildWatcher (asyncio のクラス)
  • fatalError() (xml.sax.handler.ErrorHandler のメソッド)
  • Fault (xmlrpc.client のクラス)
  • faultCode (xmlrpc.client.Fault の属性)
  • faulthandler (モジュール)
  • faultString (xmlrpc.client.Fault の属性)
  • fchdir() (os モジュール)
  • fchmod() (os モジュール)
  • fchown() (os モジュール)
  • FCICreate() (msilib モジュール)
  • fcntl (モジュール)
  • fcntl() (fcntl モジュール)
  • fd (selectors.SelectorKey の属性)
  • fd() (turtle モジュール)
  • fd_count() (test.support モジュール)
  • fdatasync() (os モジュール)
  • fdopen() (os モジュール)
  • Feature (msilib のクラス)
  • feature_external_ges (xml.sax.handler モジュール)
  • feature_external_pes (xml.sax.handler モジュール)
  • feature_namespace_prefixes (xml.sax.handler モジュール)
  • feature_namespaces (xml.sax.handler モジュール)
  • feature_string_interning (xml.sax.handler モジュール)
  • feature_validation (xml.sax.handler モジュール)
  • feed() (email.parser.BytesFeedParser のメソッド)
    • (html.parser.HTMLParser のメソッド)
    • (xml.etree.ElementTree.XMLParser のメソッド)
    • (xml.etree.ElementTree.XMLPullParser のメソッド)
    • (xml.sax.xmlreader.IncrementalParser のメソッド)
  • FeedParser (email.parser のクラス)
  • fetch() (imaplib.IMAP4 のメソッド)
  • Fetch() (msilib.View のメソッド)
  • fetchall() (sqlite3.Cursor のメソッド)
  • fetchmany() (sqlite3.Cursor のメソッド)
  • fetchone() (sqlite3.Cursor のメソッド)
  • fflags (select.kevent の属性)
  • Field (dataclasses のクラス)
  • field() (dataclasses モジュール)
  • field_size_limit() (csv モジュール)
  • fieldnames (csv.csvreader の属性)
  • fields (uuid.UUID の属性)
  • fields() (dataclasses モジュール)
  • file
    • .ini
    • .pdbrc
    • byte-code, [1]
    • configuration
    • copying
    • debugger configuration
    • large files
    • mime.types
    • modes
    • path configuration
    • plist
    • temporary
    • オブジェクト, [1]
  • file (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
  • file ...
    • compileall コマンドラインオプション
  • file control
    • UNIX
  • file name
    • temporary
  • file object
    • io module
    • open() built-in function
  • file-like object
  • 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_NO_SCRUB_DATA (stat モジュール)
  • FILE_ATTRIBUTE_NORMAL (stat モジュール)
  • FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (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 (stat モジュール)
  • file_created() (組み込み関数)
  • file_dispatcher (asyncore のクラス)
  • file_open() (urllib.request.FileHandler のメソッド)
  • file_size (zipfile.ZipInfo の属性)
  • file_wrapper (asyncore のクラス)
  • filecmp (モジュール)
  • fileConfig() (logging.config モジュール)
  • FileCookieJar (http.cookiejar のクラス)
  • FileEntry (tkinter.tix のクラス)
  • FileExistsError
  • FileFinder (importlib.machinery のクラス)
  • FileHandler (logging のクラス)
    • (urllib.request のクラス)
  • FileInput (fileinput のクラス)
  • fileinput (モジュール)
  • FileIO (io のクラス)
  • filelineno() (fileinput モジュール)
  • FileLoader (importlib.abc のクラス)
  • filemode() (stat モジュール)
  • filename (doctest.DocTest の属性)
    • (OSError の属性)
    • (http.cookiejar.FileCookieJar の属性)
    • (traceback.TracebackException の属性)
    • (tracemalloc.Frame の属性)
    • (zipfile.ZipFile の属性)
    • (zipfile.ZipInfo の属性)
  • filename() (fileinput モジュール)
  • filename2 (OSError の属性)
  • filename_only (tabnanny モジュール)
  • filename_pattern (tracemalloc.Filter の属性)
  • filenames
    • pathname expansion
    • wildcard expansion
  • fileno() (fileinput モジュール)
    • (http.client.HTTPResponse のメソッド)
    • (io.IOBase のメソッド)
    • (multiprocessing.connection.Connection のメソッド)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (ossaudiodev.oss_mixer_device のメソッド)
    • (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.kqueue のメソッド)
    • (selectors.DevpollSelector のメソッド)
    • (selectors.EpollSelector のメソッド)
    • (selectors.KqueueSelector のメソッド)
    • (socket.socket のメソッド)
    • (socketserver.BaseServer のメソッド)
    • (telnetlib.Telnet のメソッド)
  • FileNotFoundError
  • fileobj (selectors.SelectorKey の属性)
  • FileSelectBox (tkinter.tix のクラス)
  • FileType (argparse のクラス)
  • FileWrapper (wsgiref.util のクラス)
  • fill() (textwrap モジュール)
    • (textwrap.TextWrapper のメソッド)
  • fillcolor() (turtle モジュール)
  • filling() (turtle モジュール)
  • filter (2to3 fixer)
  • Filter (logging のクラス)
  • filter (select.kevent の属性)
  • Filter (tracemalloc のクラス)
  • filter() (curses モジュール)
    • (fnmatch モジュール)
    • (logging.Filter のメソッド)
    • (logging.Handler のメソッド)
    • (logging.Logger のメソッド)
    • (組み込み関数)
  • FILTER_DIR (unittest.mock モジュール)
  • filter_traces() (tracemalloc.Snapshot のメソッド)
  • filterfalse() (itertools モジュール)
  • filterwarnings() (warnings モジュール)
  • finalization, of objects
  • finalize (weakref のクラス)
  • finalize_options() (distutils.cmd.Command のメソッド)
  • finalizer
  • finally
    • キーワード, [1], [2], [3], [4]
  • find() (bytearray のメソッド)
    • (bytes のメソッド)
    • (doctest.DocTestFinder のメソッド)
    • (gettext モジュール)
    • (mmap.mmap のメソッド)
    • (str のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • find_class() (pickle protocol)
    • (pickle.Unpickler のメソッド)
  • find_library() (ctypes.util モジュール)
  • find_library_file() (distutils.ccompiler.CCompiler のメソッド)
  • find_loader() (importlib モジュール)
    • (importlib.abc.PathEntryFinder のメソッド)
    • (importlib.machinery.FileFinder のメソッド)
    • (pkgutil モジュール)
  • find_longest_match() (difflib.SequenceMatcher のメソッド)
  • find_module() (imp モジュール)
    • (imp.NullImporter のメソッド)
    • (importlib.abc.Finder のメソッド)
    • (importlib.abc.MetaPathFinder のメソッド)
    • (importlib.abc.PathEntryFinder のメソッド)
    • (importlib.machinery.PathFinder のクラスメソッド)
    • (zipimport.zipimporter のメソッド)
  • find_msvcrt() (ctypes.util モジュール)
  • find_spec
    • finder
  • find_spec() (importlib.abc.MetaPathFinder のメソッド)
    • (importlib.abc.PathEntryFinder のメソッド)
    • (importlib.machinery.FileFinder のメソッド)
    • (importlib.machinery.PathFinder のクラスメソッド)
    • (importlib.util モジュール)
  • find_unused_port() (test.support モジュール)
  • find_user_password() (urllib.request.HTTPPasswordMgr のメソッド), [1]
  • findall() (re モジュール)
    • (re.Pattern のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • findCaller() (logging.Logger のメソッド)
  • finder, [1]
    • find_spec
  • Finder (importlib.abc のクラス)
  • findfactor() (audioop モジュール)
  • findfile() (test.support モジュール)
  • findfit() (audioop モジュール)
  • finditer() (re モジュール)
    • (re.Pattern のメソッド)
  • findlabels() (dis モジュール)
  • findlinestarts() (dis モジュール)
  • findmatch() (mailcap モジュール)
  • findmax() (audioop モジュール)
  • findtext() (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • finish() (socketserver.BaseRequestHandler のメソッド)
  • finish_request() (socketserver.BaseServer のメソッド)
  • firstChild (xml.dom.Node の属性)
  • firstkey() (dbm.gnu.gdbm のメソッド)
  • firstweekday() (calendar モジュール)
  • fix_missing_locations() (ast モジュール)
  • fix_sentence_endings (textwrap.TextWrapper の属性)
  • Flag (enum のクラス)
  • flag_bits (zipfile.ZipInfo の属性)
  • flags (re.Pattern の属性)
    • (select.kevent の属性)
    • (sys モジュール)
  • flash() (curses モジュール)
  • flatten() (email.generator.BytesGenerator のメソッド)
    • (email.generator.Generator のメソッド)
  • flattening
    • objects
  • float
    • 組み込み関数, [1], [2]
  • float (組み込みクラス)
  • float_info (sys モジュール)
  • float_repr_style (sys モジュール)
  • floating point
    • literals
    • number
    • オブジェクト, [1], [2]
  • floating point literal
  • FloatingPointError
  • FloatOperation (decimal のクラス)
  • flock() (fcntl モジュール)
  • floor division
  • floor() (in module math)
    • (math モジュール)
  • floordiv() (operator モジュール)
  • flush() (bz2.BZ2Compressor のメソッド)
    • (formatter.writer のメソッド)
    • (io.BufferedWriter のメソッド)
    • (io.IOBase のメソッド)
    • (logging.Handler のメソッド)
    • (logging.StreamHandler のメソッド)
    • (logging.handlers.BufferingHandler のメソッド)
    • (logging.handlers.MemoryHandler のメソッド)
    • (lzma.LZMACompressor のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (mmap.mmap のメソッド)
    • (zlib.Compress のメソッド)
    • (zlib.Decompress のメソッド)
  • flush_headers() (http.server.BaseHTTPRequestHandler のメソッド)
  • flush_softspace() (formatter.formatter のメソッド)
  • flushinp() (curses モジュール)
  • FlushKey() (winreg モジュール)
  • fma() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • fmod() (math モジュール)
  • FMT_BINARY (plistlib モジュール)
  • FMT_XML (plistlib モジュール)
  • fnmatch (モジュール)
  • fnmatch() (fnmatch モジュール)
  • fnmatchcase() (fnmatch モジュール)
  • focus() (tkinter.ttk.Treeview のメソッド)
  • fold (datetime.datetime の属性)
    • (datetime.time の属性)
  • fold() (email.headerregistry.BaseHeader のメソッド)
    • (email.policy.Compat32 のメソッド)
    • (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • fold_binary() (email.policy.Compat32 のメソッド)
    • (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • for
    • in comprehensions
    • 文, [1], [2], [3]
  • FOR_ITER (opcode)
  • forget() (test.support モジュール)
    • (tkinter.ttk.Notebook のメソッド)
  • fork() (os モジュール)
    • (pty モジュール)
  • ForkingMixIn (socketserver のクラス)
  • ForkingTCPServer (socketserver のクラス)
  • ForkingUDPServer (socketserver のクラス)
  • forkpty() (os モジュール)
  • form
    • lambda
  • Form (tkinter.tix のクラス)
  • format (memoryview の属性)
    • (struct.Struct の属性)
  • format() (built-in function)
    • __str__() (object method)
  • format() (locale モジュール)
    • (logging.Formatter のメソッド)
    • (logging.Handler のメソッド)
    • (pprint.PrettyPrinter のメソッド)
    • (str のメソッド)
    • (string.Formatter のメソッド)
    • (traceback.StackSummary のメソッド)
    • (traceback.TracebackException のメソッド)
    • (tracemalloc.Traceback のメソッド)
    • (組み込み関数)
  • format_datetime() (email.utils モジュール)
  • format_exc() (traceback モジュール)
  • format_exception() (traceback モジュール)
  • format_exception_only() (traceback モジュール)
    • (traceback.TracebackException のメソッド)
  • format_field() (string.Formatter のメソッド)
  • format_help() (argparse.ArgumentParser のメソッド)
  • format_list() (traceback モジュール)
  • format_map() (str のメソッド)
  • format_stack() (traceback モジュール)
  • format_stack_entry() (bdb.Bdb のメソッド)
  • format_string() (locale モジュール)
  • format_tb() (traceback モジュール)
  • format_usage() (argparse.ArgumentParser のメソッド)
  • FORMAT_VALUE (opcode)
  • formataddr() (email.utils モジュール)
  • formatargspec() (inspect モジュール)
  • formatargvalues() (inspect モジュール)
  • formatdate() (email.utils モジュール)
  • FormatError
  • FormatError() (ctypes モジュール)
  • formatException() (logging.Formatter のメソッド)
  • formatmonth() (calendar.HTMLCalendar のメソッド)
    • (calendar.TextCalendar のメソッド)
  • formatStack() (logging.Formatter のメソッド)
  • formatted string literal
  • Formatter (logging のクラス)
    • (string のクラス)
  • formatter (モジュール)
  • formatTime() (logging.Formatter のメソッド)
  • formatting
    • bytearray (%)
    • bytes (%)
  • formatting, string (%)
  • formatwarning() (warnings モジュール)
  • formatyear() (calendar.HTMLCalendar のメソッド)
    • (calendar.TextCalendar のメソッド)
  • formatyearpage() (calendar.HTMLCalendar のメソッド)
  • Fortran contiguous, [1]
  • forward() (turtle モジュール)
  • found_terminator() (asynchat.async_chat のメソッド)
  • fpathconf() (os モジュール)
  • fqdn (smtpd.SMTPChannel の属性)
  • Fraction (fractions のクラス)
  • fractions (モジュール)
  • frame
    • execution, [1]
    • オブジェクト
  • frame (tkinter.scrolledtext.ScrolledText の属性)
  • Frame (tracemalloc のクラス)
  • FrameSummary (traceback のクラス)
  • FrameType (types モジュール)
  • free
    • variable
  • free()
  • freeze utility
  • freeze() (gc モジュール)
  • freeze_support() (multiprocessing モジュール)
  • frexp() (math モジュール)
  • from
    • import statement, [1]
    • yield from expression
    • キーワード, [1]
  • from_address() (ctypes._CData のメソッド)
  • from_buffer() (ctypes._CData のメソッド)
  • from_buffer_copy() (ctypes._CData のメソッド)
  • from_bytes() (int のクラスメソッド)
  • from_callable() (inspect.Signature のクラスメソッド)
  • from_decimal() (fractions.Fraction のメソッド)
  • from_exception() (traceback.TracebackException のクラスメソッド)
  • from_file() (zipfile.ZipInfo のクラスメソッド)
  • from_float() (decimal.Decimal のメソッド)
    • (fractions.Fraction のメソッド)
  • from_iterable() (itertools.chain のクラスメソッド)
  • from_list() (traceback.StackSummary のクラスメソッド)
  • from_param() (ctypes._CData のメソッド)
  • from_traceback() (dis.Bytecode のクラスメソッド)
  • frombuf() (tarfile.TarInfo のクラスメソッド)
  • frombytes() (array.array のメソッド)
  • fromfd() (select.epoll のメソッド)
    • (select.kqueue のメソッド)
    • (socket モジュール)
  • fromfile() (array.array のメソッド)
  • fromhex() (bytearray のクラスメソッド)
    • (bytes のクラスメソッド)
    • (float のクラスメソッド)
  • fromisoformat() (datetime.date のクラスメソッド)
    • (datetime.datetime のクラスメソッド)
    • (datetime.time のクラスメソッド)
  • fromkeys() (collections.Counter のメソッド)
    • (dict のクラスメソッド)
  • fromlist() (array.array のメソッド)
  • fromordinal() (datetime.date のクラスメソッド)
    • (datetime.datetime のクラスメソッド)
  • fromshare() (socket モジュール)
  • fromstring() (array.array のメソッド)
    • (xml.etree.ElementTree モジュール)
  • fromstringlist() (xml.etree.ElementTree モジュール)
  • fromtarfile() (tarfile.TarInfo のクラスメソッド)
  • fromtimestamp() (datetime.date のクラスメソッド)
    • (datetime.datetime のクラスメソッド)
  • fromunicode() (array.array のメソッド)
  • fromutc() (datetime.timezone のメソッド)
    • (datetime.tzinfo のメソッド)
  • FrozenImporter (importlib.machinery のクラス)
  • FrozenInstanceError
  • frozenset
    • オブジェクト, [1]
  • FrozenSet (typing のクラス)
  • frozenset (組み込みクラス)
  • fs_is_case_insensitive() (test.support モジュール)
  • FS_NONASCII (test.support モジュール)
  • fsdecode() (os モジュール)
  • fsencode() (os モジュール)
  • fspath() (os モジュール)
  • fstat() (os モジュール)
  • fstatvfs() (os モジュール)
  • fsum() (math モジュール)
  • fsync() (os モジュール)
  • FTP
    • ftplib (standard module)
    • protocol, [1]
  • FTP (ftplib のクラス)
  • ftp_open() (urllib.request.FTPHandler のメソッド)
  • FTP_TLS (ftplib のクラス)
  • FTPHandler (urllib.request のクラス)
  • ftplib (モジュール)
  • ftruncate() (os モジュール)
  • Full
  • full() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (queue.Queue のメソッド)
  • full_url (urllib.request.Request の属性)
  • fullmatch() (re モジュール)
    • (re.Pattern のメソッド)
  • func (functools.partial の属性)
  • funcattrs (2to3 fixer)
  • function
    • annotations, [1]
    • anonymous
    • argument
    • call, [1], [2]
    • call, user-defined
    • definition, [1]
    • generator, [1]
    • name, [1]
    • user-defined
    • オブジェクト, [1], [2], [3], [4], [5]
  • Function (symtable のクラス)
  • function annotation
  • function__entry (C の関数)
  • function__return (C の関数)
  • FunctionTestCase (unittest のクラス)
  • FunctionType (types モジュール)
  • functools (モジュール)
  • funny_files (filecmp.dircmp の属性)
  • future
    • statement
  • future (2to3 fixer)
  • Future (asyncio のクラス)
    • (concurrent.futures のクラス)
  • FutureWarning
  • fwalk() (os モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – G

  • G.722
  • gaierror
  • gamma() (math モジュール)
  • gammavariate() (random モジュール)
  • garbage (gc モジュール)
  • garbage collection, [1]
  • gather() (curses.textpad.Textbox のメソッド)
  • gauss() (random モジュール)
  • gc (モジュール)
  • gc__done (C の関数)
  • gc__start (C の関数)
  • gc_collect() (test.support モジュール)
  • gcd() (fractions モジュール)
    • (math モジュール)
  • ge() (operator モジュール)
  • gen_lib_options() (distutils.ccompiler モジュール)
  • gen_preprocess_options() (distutils.ccompiler モジュール)
  • gen_uuid() (msilib モジュール)
  • generate_help() (distutils.fancy_getopt.FancyGetopt のメソッド)
  • generator, [1]
    • expression
    • function, [1], [2]
    • iterator, [1]
    • オブジェクト, [1], [2]
  • Generator (collections.abc のクラス)
    • (email.generator のクラス)
    • (typing のクラス)
  • generator expression, [1]
  • generator iterator
  • GeneratorExit
    • 例外, [1]
  • GeneratorType (types モジュール)
  • generic
    • special attribute
  • Generic (typing のクラス)
  • generic function
  • generic_visit() (ast.NodeVisitor のメソッド)
  • genops() (pickletools モジュール)
  • get() (asyncio.Queue のメソッド)
    • (configparser.ConfigParser のメソッド)
    • (contextvars.Context のメソッド)
    • (contextvars.ContextVar のメソッド)
    • (dict のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (multiprocessing.SimpleQueue のメソッド)
    • (multiprocessing.pool.AsyncResult のメソッド)
    • (ossaudiodev.oss_mixer_device のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
    • (tkinter.ttk.Combobox のメソッド)
    • (tkinter.ttk.Spinbox のメソッド)
    • (types.MappingProxyType のメソッド)
    • (webbrowser モジュール)
    • (xml.etree.ElementTree.Element のメソッド)
  • GET_AITER (opcode)
  • get_all() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (wsgiref.headers.Headers のメソッド)
  • get_all_breaks() (bdb.Bdb のメソッド)
  • get_all_start_methods() (multiprocessing モジュール)
  • GET_ANEXT (opcode)
  • get_app() (wsgiref.simple_server.WSGIServer のメソッド)
  • get_archive_formats() (shutil モジュール)
  • get_asyncgen_hooks() (sys モジュール)
  • get_attribute() (test.support モジュール)
  • GET_AWAITABLE (opcode)
  • get_begidx() (readline モジュール)
  • get_blocking() (os モジュール)
  • get_body() (email.message.EmailMessage のメソッド)
  • get_body_encoding() (email.charset.Charset のメソッド)
  • get_boundary() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_bpbynumber() (bdb.Bdb のメソッド)
  • get_break() (bdb.Bdb のメソッド)
  • get_breaks() (bdb.Bdb のメソッド)
  • get_buffer() (asyncio.BufferedProtocol のメソッド)
    • (xdrlib.Packer のメソッド)
    • (xdrlib.Unpacker のメソッド)
  • get_bytes() (mailbox.Mailbox のメソッド)
  • get_ca_certs() (ssl.SSLContext のメソッド)
  • get_cache_token() (abc モジュール)
  • get_channel_binding() (ssl.SSLSocket のメソッド)
  • get_charset() (email.message.Message のメソッド)
  • get_charsets() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_child_watcher() (asyncio モジュール)
    • (asyncio.AbstractEventLoopPolicy のメソッド)
  • get_children() (symtable.SymbolTable のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
  • get_ciphers() (ssl.SSLContext のメソッド)
  • get_clock_info() (time モジュール)
  • get_close_matches() (difflib モジュール)
  • get_code() (importlib.abc.InspectLoader のメソッド)
    • (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
    • (importlib.machinery.SourcelessFileLoader のメソッド)
    • (zipimport.zipimporter のメソッド)
  • get_completer() (readline モジュール)
  • get_completer_delims() (readline モジュール)
  • get_completion_type() (readline モジュール)
  • get_config_h_filename() (distutils.sysconfig モジュール)
    • (sysconfig モジュール)
  • get_config_var() (distutils.sysconfig モジュール)
    • (sysconfig モジュール)
  • get_config_vars() (distutils.sysconfig モジュール)
    • (sysconfig モジュール)
  • get_content() (email.contentmanager モジュール)
    • (email.contentmanager.ContentManager のメソッド)
    • (email.message.EmailMessage のメソッド)
  • get_content_charset() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_content_disposition() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_content_maintype() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_content_subtype() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_content_type() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_context() (multiprocessing モジュール)
  • get_coroutine_origin_tracking_depth() (sys モジュール)
  • get_coroutine_wrapper() (sys モジュール)
  • get_count() (gc モジュール)
  • get_current_history_length() (readline モジュール)
  • get_data() (importlib.abc.FileLoader のメソッド)
    • (importlib.abc.ResourceLoader のメソッド)
    • (pkgutil モジュール)
    • (zipimport.zipimporter のメソッド)
  • get_date() (mailbox.MaildirMessage のメソッド)
  • get_debug() (asyncio.loop のメソッド)
    • (gc モジュール)
  • get_default() (argparse.ArgumentParser のメソッド)
  • get_default_compiler() (distutils.ccompiler モジュール)
  • get_default_domain() (nis モジュール)
  • get_default_type() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_default_verify_paths() (ssl モジュール)
  • get_dialect() (csv モジュール)
  • get_docstring() (ast モジュール)
  • get_doctest() (doctest.DocTestParser のメソッド)
  • get_endidx() (readline モジュール)
  • get_environ() (wsgiref.simple_server.WSGIRequestHandler のメソッド)
  • get_errno() (ctypes モジュール)
  • get_event_loop() (asyncio モジュール)
    • (asyncio.AbstractEventLoopPolicy のメソッド)
  • get_event_loop_policy() (asyncio モジュール)
  • get_examples() (doctest.DocTestParser のメソッド)
  • get_exception_handler() (asyncio.loop のメソッド)
  • get_exec_path() (os モジュール)
  • get_extra_info() (asyncio.BaseTransport のメソッド)
    • (asyncio.StreamWriter のメソッド)
  • get_field() (string.Formatter のメソッド)
  • get_file() (mailbox.Babyl のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.MMDF のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (mailbox.mbox のメソッド)
  • get_file_breaks() (bdb.Bdb のメソッド)
  • get_filename() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (importlib.abc.ExecutionLoader のメソッド)
    • (importlib.abc.FileLoader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
    • (zipimport.zipimporter のメソッド)
  • get_flags() (mailbox.MaildirMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
    • (mailbox.mboxMessage のメソッド)
  • get_folder() (mailbox.Maildir のメソッド)
    • (mailbox.MH のメソッド)
  • get_frees() (symtable.Function のメソッド)
  • get_freeze_count() (gc モジュール)
  • get_from() (mailbox.mboxMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
  • get_full_url() (urllib.request.Request のメソッド)
  • get_globals() (symtable.Function のメソッド)
  • get_grouped_opcodes() (difflib.SequenceMatcher のメソッド)
  • get_handle_inheritable() (os モジュール)
  • get_header() (urllib.request.Request のメソッド)
  • get_history_item() (readline モジュール)
  • get_history_length() (readline モジュール)
  • get_id() (symtable.SymbolTable のメソッド)
  • get_ident() (_thread モジュール)
    • (threading モジュール)
  • get_identifiers() (symtable.SymbolTable のメソッド)
  • get_importer() (pkgutil モジュール)
  • get_info() (mailbox.MaildirMessage のメソッド)
  • get_inheritable() (os モジュール)
    • (socket.socket のメソッド)
  • get_instructions() (dis モジュール)
  • get_interpreter() (zipapp モジュール)
  • GET_ITER (opcode)
  • get_key() (selectors.BaseSelector のメソッド)
  • get_labels() (mailbox.Babyl のメソッド)
    • (mailbox.BabylMessage のメソッド)
  • get_last_error() (ctypes モジュール)
  • get_line_buffer() (readline モジュール)
  • get_lineno() (symtable.SymbolTable のメソッド)
  • get_loader() (pkgutil モジュール)
  • get_locals() (symtable.Function のメソッド)
  • get_logger() (multiprocessing モジュール)
  • get_loop() (asyncio.Future のメソッド)
    • (asyncio.Server のメソッド)
  • get_magic() (imp モジュール)
  • get_makefile_filename() (distutils.sysconfig モジュール)
    • (sysconfig モジュール)
  • get_map() (selectors.BaseSelector のメソッド)
  • get_matching_blocks() (difflib.SequenceMatcher のメソッド)
  • get_message() (mailbox.Mailbox のメソッド)
  • get_method() (urllib.request.Request のメソッド)
  • get_methods() (symtable.Class のメソッド)
  • get_mixed_type_key() (ipaddress モジュール)
  • get_name() (symtable.Symbol のメソッド)
    • (symtable.SymbolTable のメソッド)
  • get_namespace() (symtable.Symbol のメソッド)
  • get_namespaces() (symtable.Symbol のメソッド)
  • get_nonstandard_attr() (http.cookiejar.Cookie のメソッド)
  • get_nowait() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
  • get_object_traceback() (tracemalloc モジュール)
  • get_objects() (gc モジュール)
  • get_opcodes() (difflib.SequenceMatcher のメソッド)
  • get_option() (optparse.OptionParser のメソッド)
  • get_option_group() (optparse.OptionParser のメソッド)
  • get_option_order() (distutils.fancy_getopt.FancyGetopt のメソッド)
  • get_original_stdout() (test.support モジュール)
  • get_osfhandle() (msvcrt モジュール)
  • get_output_charset() (email.charset.Charset のメソッド)
  • get_param() (email.message.Message のメソッド)
  • get_parameters() (symtable.Function のメソッド)
  • get_params() (email.message.Message のメソッド)
  • get_path() (sysconfig モジュール)
  • get_path_names() (sysconfig モジュール)
  • get_paths() (sysconfig モジュール)
  • get_payload() (email.message.Message のメソッド)
  • get_pid() (asyncio.SubprocessTransport のメソッド)
  • get_pipe_transport() (asyncio.SubprocessTransport のメソッド)
  • get_platform() (distutils.util モジュール)
    • (sysconfig モジュール)
  • get_poly() (turtle モジュール)
  • get_position() (xdrlib.Unpacker のメソッド)
  • get_protocol() (asyncio.BaseTransport のメソッド)
  • get_python_inc() (distutils.sysconfig モジュール)
  • get_python_lib() (distutils.sysconfig モジュール)
  • get_python_version() (sysconfig モジュール)
  • get_recsrc() (ossaudiodev.oss_mixer_device のメソッド)
  • get_referents() (gc モジュール)
  • get_referrers() (gc モジュール)
  • get_request() (socketserver.BaseServer のメソッド)
  • get_returncode() (asyncio.SubprocessTransport のメソッド)
  • get_running_loop() (asyncio モジュール)
  • get_scheme() (wsgiref.handlers.BaseHandler のメソッド)
  • get_scheme_names() (sysconfig モジュール)
  • get_sequences() (mailbox.MH のメソッド)
    • (mailbox.MHMessage のメソッド)
  • get_server() (multiprocessing.managers.BaseManager のメソッド)
  • get_server_certificate() (ssl モジュール)
  • get_shapepoly() (turtle モジュール)
  • get_socket() (telnetlib.Telnet のメソッド)
  • get_source() (importlib.abc.InspectLoader のメソッド)
    • (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
    • (importlib.machinery.SourcelessFileLoader のメソッド)
    • (zipimport.zipimporter のメソッド)
  • get_special_folder_path() (組み込み関数)
  • get_stack() (asyncio.Task のメソッド)
    • (bdb.Bdb のメソッド)
  • get_start_method() (multiprocessing モジュール)
  • get_starttag_text() (html.parser.HTMLParser のメソッド)
  • get_stats() (gc モジュール)
  • get_stderr() (wsgiref.handlers.BaseHandler のメソッド)
    • (wsgiref.simple_server.WSGIRequestHandler のメソッド)
  • get_stdin() (wsgiref.handlers.BaseHandler のメソッド)
  • get_string() (mailbox.Mailbox のメソッド)
  • get_subdir() (mailbox.MaildirMessage のメソッド)
  • get_suffixes() (imp モジュール)
  • get_symbols() (symtable.SymbolTable のメソッド)
  • get_tag() (imp モジュール)
  • get_task_factory() (asyncio.loop のメソッド)
  • get_terminal_size() (os モジュール)
    • (shutil モジュール)
  • get_terminator() (asynchat.async_chat のメソッド)
  • get_threshold() (gc モジュール)
  • get_token() (shlex.shlex のメソッド)
  • get_traceback_limit() (tracemalloc モジュール)
  • get_traced_memory() (tracemalloc モジュール)
  • get_tracemalloc_memory() (tracemalloc モジュール)
  • get_type() (symtable.SymbolTable のメソッド)
  • get_type_hints() (typing モジュール)
  • get_unixfrom() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • get_unpack_formats() (shutil モジュール)
  • get_usage() (optparse.OptionParser のメソッド)
  • get_value() (string.Formatter のメソッド)
  • get_version() (optparse.OptionParser のメソッド)
  • get_visible() (mailbox.BabylMessage のメソッド)
  • get_wch() (curses.window のメソッド)
  • get_write_buffer_limits() (asyncio.WriteTransport のメソッド)
  • get_write_buffer_size() (asyncio.WriteTransport のメソッド)
  • GET_YIELD_FROM_ITER (opcode)
  • getacl() (imaplib.IMAP4 のメソッド)
  • getaddresses() (email.utils モジュール)
  • getaddrinfo() (asyncio.loop のメソッド)
    • (socket モジュール)
  • getallocatedblocks() (sys モジュール)
  • getandroidapilevel() (sys モジュール)
  • getannotation() (imaplib.IMAP4 のメソッド)
  • getargspec() (inspect モジュール)
  • getargvalues() (inspect モジュール)
  • getatime() (os.path モジュール)
  • getattr() (組み込み関数)
  • getattr_static() (inspect モジュール)
  • getAttribute() (xml.dom.Element のメソッド)
  • getAttributeNode() (xml.dom.Element のメソッド)
  • getAttributeNodeNS() (xml.dom.Element のメソッド)
  • getAttributeNS() (xml.dom.Element のメソッド)
  • GetBase() (xml.parsers.expat.xmlparser のメソッド)
  • getbegyx() (curses.window のメソッド)
  • getbkgd() (curses.window のメソッド)
  • getblocking() (socket.socket のメソッド)
  • getboolean() (configparser.ConfigParser のメソッド)
  • getbuffer() (io.BytesIO のメソッド)
  • getByteStream() (xml.sax.xmlreader.InputSource のメソッド)
  • getcallargs() (inspect モジュール)
  • getcanvas() (turtle モジュール)
  • getcapabilities() (nntplib.NNTP のメソッド)
  • getcaps() (mailcap モジュール)
  • getch() (curses.window のメソッド)
    • (msvcrt モジュール)
  • getCharacterStream() (xml.sax.xmlreader.InputSource のメソッド)
  • getche() (msvcrt モジュール)
  • getcheckinterval() (sys モジュール)
  • getChild() (logging.Logger のメソッド)
  • getchildren() (xml.etree.ElementTree.Element のメソッド)
  • getclasstree() (inspect モジュール)
  • getclosurevars() (inspect モジュール)
  • GetColumnInfo() (msilib.View のメソッド)
  • getColumnNumber() (xml.sax.xmlreader.Locator のメソッド)
  • getcomments() (inspect モジュール)
  • getcompname() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getcomptype() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getContentHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • getcontext() (decimal モジュール)
  • getcoroutinelocals() (inspect モジュール)
  • getcoroutinestate() (inspect モジュール)
  • getctime() (os.path モジュール)
  • getcwd() (os モジュール)
  • getcwdb() (os モジュール)
  • getcwdu (2to3 fixer)
  • getdecoder() (codecs モジュール)
  • getdefaultencoding() (sys モジュール)
  • getdefaultlocale() (locale モジュール)
  • getdefaulttimeout() (socket モジュール)
  • getdlopenflags() (sys モジュール)
  • getdoc() (inspect モジュール)
  • getDOMImplementation() (xml.dom モジュール)
  • getDTDHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • getEffectiveLevel() (logging.Logger のメソッド)
  • getegid() (os モジュール)
  • getElementsByTagName() (xml.dom.Document のメソッド)
    • (xml.dom.Element のメソッド)
  • getElementsByTagNameNS() (xml.dom.Document のメソッド)
    • (xml.dom.Element のメソッド)
  • getencoder() (codecs モジュール)
  • getEncoding() (xml.sax.xmlreader.InputSource のメソッド)
  • getEntityResolver() (xml.sax.xmlreader.XMLReader のメソッド)
  • getenv() (os モジュール)
  • getenvb() (os モジュール)
  • getErrorHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • geteuid() (os モジュール)
  • getEvent() (xml.dom.pulldom.DOMEventStream のメソッド)
  • getEventCategory() (logging.handlers.NTEventLogHandler のメソッド)
  • getEventType() (logging.handlers.NTEventLogHandler のメソッド)
  • getException() (xml.sax.SAXException のメソッド)
  • getFeature() (xml.sax.xmlreader.XMLReader のメソッド)
  • GetFieldCount() (msilib.Record のメソッド)
  • getfile() (inspect モジュール)
  • getfilesystemencodeerrors() (sys モジュール)
  • getfilesystemencoding() (sys モジュール)
  • getfirst() (cgi.FieldStorage のメソッド)
  • getfloat() (configparser.ConfigParser のメソッド)
  • getfmts() (ossaudiodev.oss_audio_device のメソッド)
  • getfqdn() (socket モジュール)
  • getframeinfo() (inspect モジュール)
  • getframerate() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getfullargspec() (inspect モジュール)
  • getgeneratorlocals() (inspect モジュール)
  • getgeneratorstate() (inspect モジュール)
  • getgid() (os モジュール)
  • getgrall() (grp モジュール)
  • getgrgid() (grp モジュール)
  • getgrnam() (grp モジュール)
  • getgrouplist() (os モジュール)
  • getgroups() (os モジュール)
  • getheader() (http.client.HTTPResponse のメソッド)
  • getheaders() (http.client.HTTPResponse のメソッド)
  • gethostbyaddr() (in module socket)
    • (socket モジュール)
  • gethostbyname() (socket モジュール)
  • gethostbyname_ex() (socket モジュール)
  • gethostname() (in module socket)
    • (socket モジュール)
  • getincrementaldecoder() (codecs モジュール)
  • getincrementalencoder() (codecs モジュール)
  • getinfo() (zipfile.ZipFile のメソッド)
  • getinnerframes() (inspect モジュール)
  • GetInputContext() (xml.parsers.expat.xmlparser のメソッド)
  • getint() (configparser.ConfigParser のメソッド)
  • GetInteger() (msilib.Record のメソッド)
  • getitem() (operator モジュール)
  • getiterator() (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • getitimer() (signal モジュール)
  • getkey() (curses.window のメソッド)
  • GetLastError() (ctypes モジュール)
  • getLength() (xml.sax.xmlreader.Attributes のメソッド)
  • getLevelName() (logging モジュール)
  • getline() (linecache モジュール)
  • getLineNumber() (xml.sax.xmlreader.Locator のメソッド)
  • getlist() (cgi.FieldStorage のメソッド)
  • getloadavg() (os モジュール)
  • getlocale() (locale モジュール)
  • getLogger() (logging モジュール)
  • getLoggerClass() (logging モジュール)
  • getlogin() (os モジュール)
  • getLogRecordFactory() (logging モジュール)
  • getmark() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getmarkers() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getmaxyx() (curses.window のメソッド)
  • getmember() (tarfile.TarFile のメソッド)
  • getmembers() (inspect モジュール)
    • (tarfile.TarFile のメソッド)
  • getMessage() (logging.LogRecord のメソッド)
    • (xml.sax.SAXException のメソッド)
  • getMessageID() (logging.handlers.NTEventLogHandler のメソッド)
  • getmodule() (inspect モジュール)
  • getmodulename() (inspect モジュール)
  • getmouse() (curses モジュール)
  • getmro() (inspect モジュール)
  • getmtime() (os.path モジュール)
  • getname() (chunk.Chunk のメソッド)
  • getName() (threading.Thread のメソッド)
  • getNameByQName() (xml.sax.xmlreader.AttributesNS のメソッド)
  • getnameinfo() (asyncio.loop のメソッド)
    • (socket モジュール)
  • getnames() (tarfile.TarFile のメソッド)
  • getNames() (xml.sax.xmlreader.Attributes のメソッド)
  • getnchannels() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getnframes() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getnode
  • getnode() (uuid モジュール)
  • getopt (モジュール)
  • getopt() (distutils.fancy_getopt.FancyGetopt のメソッド)
    • (getopt モジュール)
  • GetoptError
  • getouterframes() (inspect モジュール)
  • getoutput() (subprocess モジュール)
  • getpagesize() (resource モジュール)
  • getparams() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getparyx() (curses.window のメソッド)
  • getpass (モジュール)
  • getpass() (getpass モジュール)
  • GetPassWarning
  • getpeercert() (ssl.SSLSocket のメソッド)
  • getpeername() (socket.socket のメソッド)
  • getpen() (turtle モジュール)
  • getpgid() (os モジュール)
  • getpgrp() (os モジュール)
  • getpid() (os モジュール)
  • getpos() (html.parser.HTMLParser のメソッド)
  • getppid() (os モジュール)
  • getpreferredencoding() (locale モジュール)
  • getpriority() (os モジュール)
  • getprofile() (sys モジュール)
  • GetProperty() (msilib.SummaryInformation のメソッド)
  • getProperty() (xml.sax.xmlreader.XMLReader のメソッド)
  • GetPropertyCount() (msilib.SummaryInformation のメソッド)
  • getprotobyname() (socket モジュール)
  • getproxies() (urllib.request モジュール)
  • getPublicId() (xml.sax.xmlreader.InputSource のメソッド)
    • (xml.sax.xmlreader.Locator のメソッド)
  • getpwall() (pwd モジュール)
  • getpwnam() (pwd モジュール)
  • getpwuid() (pwd モジュール)
  • getQNameByName() (xml.sax.xmlreader.AttributesNS のメソッド)
  • getQNames() (xml.sax.xmlreader.AttributesNS のメソッド)
  • getquota() (imaplib.IMAP4 のメソッド)
  • getquotaroot() (imaplib.IMAP4 のメソッド)
  • getrandbits() (random モジュール)
  • getrandom() (os モジュール)
  • getreader() (codecs モジュール)
  • getrecursionlimit() (sys モジュール)
  • getrefcount() (sys モジュール)
  • getresgid() (os モジュール)
  • getresponse() (http.client.HTTPConnection のメソッド)
  • getresuid() (os モジュール)
  • getrlimit() (resource モジュール)
  • getroot() (xml.etree.ElementTree.ElementTree のメソッド)
  • getrusage() (resource モジュール)
  • getsample() (audioop モジュール)
  • getsampwidth() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • getscreen() (turtle モジュール)
  • getservbyname() (socket モジュール)
  • getservbyport() (socket モジュール)
  • GetSetDescriptorType (types モジュール)
  • getshapes() (turtle モジュール)
  • getsid() (os モジュール)
  • getsignal() (signal モジュール)
  • getsitepackages() (site モジュール)
  • getsize() (chunk.Chunk のメソッド)
    • (os.path モジュール)
  • getsizeof() (sys モジュール)
  • getsockname() (socket.socket のメソッド)
  • getsockopt() (socket.socket のメソッド)
  • getsource() (inspect モジュール)
  • getsourcefile() (inspect モジュール)
  • getsourcelines() (inspect モジュール)
  • getspall() (spwd モジュール)
  • getspnam() (spwd モジュール)
  • getstate() (codecs.IncrementalDecoder のメソッド)
    • (codecs.IncrementalEncoder のメソッド)
    • (random モジュール)
  • getstatusoutput() (subprocess モジュール)
  • getstr() (curses.window のメソッド)
  • GetString() (msilib.Record のメソッド)
  • getSubject() (logging.handlers.SMTPHandler のメソッド)
  • GetSummaryInformation() (msilib.Database のメソッド)
  • getswitchinterval() (sys モジュール)
  • getSystemId() (xml.sax.xmlreader.InputSource のメソッド)
    • (xml.sax.xmlreader.Locator のメソッド)
  • getsyx() (curses モジュール)
  • gettarinfo() (tarfile.TarFile のメソッド)
  • gettempdir() (tempfile モジュール)
  • gettempdirb() (tempfile モジュール)
  • gettempprefix() (tempfile モジュール)
  • gettempprefixb() (tempfile モジュール)
  • getTestCaseNames() (unittest.TestLoader のメソッド)
  • gettext (モジュール)
  • gettext() (gettext モジュール)
    • (gettext.GNUTranslations のメソッド)
    • (gettext.NullTranslations のメソッド)
    • (locale モジュール)
  • gettimeout() (socket.socket のメソッド)
  • gettrace() (sys モジュール)
  • getturtle() (turtle モジュール)
  • getType() (xml.sax.xmlreader.Attributes のメソッド)
  • getuid() (os モジュール)
  • geturl() (urllib.parse.urllib.parse.SplitResult のメソッド)
  • getuser() (getpass モジュール)
  • getuserbase() (site モジュール)
  • getusersitepackages() (site モジュール)
  • getvalue() (io.BytesIO のメソッド)
    • (io.StringIO のメソッド)
  • getValue() (xml.sax.xmlreader.Attributes のメソッド)
  • getValueByQName() (xml.sax.xmlreader.AttributesNS のメソッド)
  • getwch() (msvcrt モジュール)
  • getwche() (msvcrt モジュール)
  • getweakrefcount() (weakref モジュール)
  • getweakrefs() (weakref モジュール)
  • getwelcome() (ftplib.FTP のメソッド)
    • (nntplib.NNTP のメソッド)
    • (poplib.POP3 のメソッド)
  • getwin() (curses モジュール)
  • getwindowsversion() (sys モジュール)
  • getwriter() (codecs モジュール)
  • getxattr() (os モジュール)
  • getyx() (curses.window のメソッド)
  • gid (tarfile.TarInfo の属性)
  • GIL
  • glob
    • モジュール
  • glob (モジュール)
  • glob() (glob モジュール)
    • (msilib.Directory のメソッド)
    • (pathlib.Path のメソッド)
  • global
    • name binding
    • namespace
    • 文, [1]
  • global interpreter lock, [1]
  • globals() (組み込み関数)
  • globs (doctest.DocTest の属性)
  • gmtime() (time モジュール)
  • gname (tarfile.TarInfo の属性)
  • GNOME
  • GNU_FORMAT (tarfile モジュール)
  • gnu_getopt() (getopt モジュール)
  • GNUTranslations (gettext のクラス)
  • got (doctest.DocTestFailure の属性)
  • goto() (turtle モジュール)
  • grammar
  • Graphical User Interface
  • GREATER (token モジュール)
  • GREATEREQUAL (token モジュール)
  • Greenwich Mean Time
  • GRND_NONBLOCK (os モジュール)
  • GRND_RANDOM (os モジュール)
  • Group (email.headerregistry のクラス)
  • group() (nntplib.NNTP のメソッド)
    • (pathlib.Path のメソッド)
    • (re.Match のメソッド)
  • groupby() (itertools モジュール)
  • groupdict() (re.Match のメソッド)
  • groupindex (re.Pattern の属性)
  • grouping
  • groups (email.headerregistry.AddressHeader の属性)
    • (re.Pattern の属性)
  • groups() (re.Match のメソッド)
  • grp (モジュール)
  • gt() (operator モジュール)
  • guess_all_extensions() (mimetypes モジュール)
    • (mimetypes.MimeTypes のメソッド)
  • guess_extension() (mimetypes モジュール)
    • (mimetypes.MimeTypes のメソッド)
  • guess_scheme() (wsgiref.util モジュール)
  • guess_type() (mimetypes モジュール)
    • (mimetypes.MimeTypes のメソッド)
  • GUI
  • gzip (モジュール)
  • GzipFile (gzip のクラス)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – H

  • halfdelay() (curses モジュール)
  • Handle (asyncio のクラス)
  • handle an exception
  • handle() (http.server.BaseHTTPRequestHandler のメソッド)
    • (logging.Handler のメソッド)
    • (logging.Logger のメソッド)
    • (logging.NullHandler のメソッド)
    • (logging.handlers.QueueListener のメソッド)
    • (socketserver.BaseRequestHandler のメソッド)
    • (wsgiref.simple_server.WSGIRequestHandler のメソッド)
  • handle_accept() (asyncore.dispatcher のメソッド)
  • handle_accepted() (asyncore.dispatcher のメソッド)
  • handle_charref() (html.parser.HTMLParser のメソッド)
  • handle_close() (asyncore.dispatcher のメソッド)
  • handle_comment() (html.parser.HTMLParser のメソッド)
  • handle_connect() (asyncore.dispatcher のメソッド)
  • handle_data() (html.parser.HTMLParser のメソッド)
  • handle_decl() (html.parser.HTMLParser のメソッド)
  • handle_defect() (email.policy.Policy のメソッド)
  • handle_endtag() (html.parser.HTMLParser のメソッド)
  • handle_entityref() (html.parser.HTMLParser のメソッド)
  • handle_error() (asyncore.dispatcher のメソッド)
    • (socketserver.BaseServer のメソッド)
  • handle_expect_100() (http.server.BaseHTTPRequestHandler のメソッド)
  • handle_expt() (asyncore.dispatcher のメソッド)
  • handle_one_request() (http.server.BaseHTTPRequestHandler のメソッド)
  • handle_pi() (html.parser.HTMLParser のメソッド)
  • handle_read() (asyncore.dispatcher のメソッド)
  • handle_request() (socketserver.BaseServer のメソッド)
    • (xmlrpc.server.CGIXMLRPCRequestHandler のメソッド)
  • handle_startendtag() (html.parser.HTMLParser のメソッド)
  • handle_starttag() (html.parser.HTMLParser のメソッド)
  • handle_timeout() (socketserver.BaseServer のメソッド)
  • handle_write() (asyncore.dispatcher のメソッド)
  • handleError() (logging.Handler のメソッド)
    • (logging.handlers.SocketHandler のメソッド)
  • handler
    • exception
  • Handler (logging のクラス)
  • handler() (cgitb モジュール)
  • harmonic_mean() (statistics モジュール)
  • HAS_ALPN (ssl モジュール)
  • has_children() (symtable.SymbolTable のメソッド)
  • has_colors() (curses モジュール)
  • HAS_ECDH (ssl モジュール)
  • has_exec() (symtable.SymbolTable のメソッド)
  • has_extn() (smtplib.SMTP のメソッド)
  • has_function() (distutils.ccompiler.CCompiler のメソッド)
  • has_header() (csv.Sniffer のメソッド)
    • (urllib.request.Request のメソッド)
  • has_ic() (curses モジュール)
  • has_il() (curses モジュール)
  • has_ipv6 (socket モジュール)
  • has_key (2to3 fixer)
  • has_key() (curses モジュール)
  • has_location (importlib.machinery.ModuleSpec の属性)
  • HAS_NEVER_CHECK_COMMON_NAME (ssl モジュール)
  • has_nonstandard_attr() (http.cookiejar.Cookie のメソッド)
  • HAS_NPN (ssl モジュール)
  • has_option() (configparser.ConfigParser のメソッド)
    • (optparse.OptionParser のメソッド)
  • has_section() (configparser.ConfigParser のメソッド)
  • HAS_SNI (ssl モジュール)
  • HAS_SSLv2 (ssl モジュール)
  • HAS_SSLv3 (ssl モジュール)
  • has_ticket (ssl.SSLSession の属性)
  • HAS_TLSv1 (ssl モジュール)
  • HAS_TLSv1_1 (ssl モジュール)
  • HAS_TLSv1_2 (ssl モジュール)
  • HAS_TLSv1_3 (ssl モジュール)
  • hasattr() (組み込み関数)
  • hasAttribute() (xml.dom.Element のメソッド)
  • hasAttributeNS() (xml.dom.Element のメソッド)
  • hasAttributes() (xml.dom.Node のメソッド)
  • hasChildNodes() (xml.dom.Node のメソッド)
  • hascompare (dis モジュール)
  • hasconst (dis モジュール)
  • hasFeature() (xml.dom.DOMImplementation のメソッド)
  • hasfree (dis モジュール)
  • hash
    • 組み込み関数, [1], [2], [3]
  • hash character
  • hash() (組み込み関数)
  • hash-based pyc
  • hash.block_size (hashlib モジュール)
  • hash.digest_size (hashlib モジュール)
  • hash_info (sys モジュール)
  • hashable, [1]
  • Hashable (collections.abc のクラス)
    • (typing のクラス)
  • hasHandlers() (logging.Logger のメソッド)
  • hashlib (モジュール)
  • hasjabs (dis モジュール)
  • hasjrel (dis モジュール)
  • haslocal (dis モジュール)
  • hasname (dis モジュール)
  • HAVE_ARGUMENT (opcode)
  • HAVE_DOCSTRINGS (test.support モジュール)
  • HAVE_THREADS (decimal モジュール)
  • HCI_DATA_DIR (socket モジュール)
  • HCI_FILTER (socket モジュール)
  • HCI_TIME_STAMP (socket モジュール)
  • head() (nntplib.NNTP のメソッド)
  • Header (email.header のクラス)
  • header_encode() (email.charset.Charset のメソッド)
  • header_encode_lines() (email.charset.Charset のメソッド)
  • header_encoding (email.charset.Charset の属性)
  • header_factory (email.policy.EmailPolicy の属性)
  • header_fetch_parse() (email.policy.Compat32 のメソッド)
    • (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • header_items() (urllib.request.Request のメソッド)
  • header_max_count() (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • header_offset (zipfile.ZipInfo の属性)
  • header_source_parse() (email.policy.Compat32 のメソッド)
    • (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • header_store_parse() (email.policy.Compat32 のメソッド)
    • (email.policy.EmailPolicy のメソッド)
    • (email.policy.Policy のメソッド)
  • HeaderError
  • HeaderParseError
  • HeaderParser (email.parser のクラス)
  • HeaderRegistry (email.headerregistry のクラス)
  • headers
    • MIME, [1]
  • headers (http.server.BaseHTTPRequestHandler の属性)
    • (urllib.error.HTTPError の属性)
  • Headers (wsgiref.headers のクラス)
  • headers (xmlrpc.client.ProtocolError の属性)
  • heading() (tkinter.ttk.Treeview のメソッド)
    • (turtle モジュール)
  • heapify() (heapq モジュール)
  • heapmin() (msvcrt モジュール)
  • heappop() (heapq モジュール)
  • heappush() (heapq モジュール)
  • heappushpop() (heapq モジュール)
  • heapq (モジュール)
  • heapreplace() (heapq モジュール)
  • helo() (smtplib.SMTP のメソッド)
  • help
    • online
    • 組み込み関数
  • help (optparse.Option の属性)
    • (pdb command)
  • help() (nntplib.NNTP のメソッド)
    • (組み込み関数)
  • herror
  • hex (uuid.UUID の属性)
  • hex() (bytearray のメソッド)
    • (bytes のメソッド)
    • (float のメソッド)
    • (memoryview のメソッド)
    • (組み込み関数)
  • hexadecimal
    • literals
  • hexadecimal literal
  • hexbin() (binhex モジュール)
  • hexdigest() (hashlib.hash のメソッド)
    • (hashlib.shake のメソッド)
    • (hmac.HMAC のメソッド)
  • hexdigits (string モジュール)
  • hexlify() (binascii モジュール)
  • hexversion (sys モジュール)
  • hidden() (curses.panel.Panel のメソッド)
  • hide() (curses.panel.Panel のメソッド)
    • (tkinter.ttk.Notebook のメソッド)
  • hide_cookie2 (http.cookiejar.CookiePolicy の属性)
  • hideturtle() (turtle モジュール)
  • hierarchy
    • type
  • HierarchyRequestErr
  • HIGH_PRIORITY_CLASS (subprocess モジュール)
  • HIGHEST_PROTOCOL (pickle モジュール)
  • HKEY_CLASSES_ROOT (winreg モジュール)
  • HKEY_CURRENT_CONFIG (winreg モジュール)
  • HKEY_CURRENT_USER (winreg モジュール)
  • HKEY_DYN_DATA (winreg モジュール)
  • HKEY_LOCAL_MACHINE (winreg モジュール)
  • HKEY_PERFORMANCE_DATA (winreg モジュール)
  • HKEY_USERS (winreg モジュール)
  • hline() (curses.window のメソッド)
  • HList (tkinter.tix のクラス)
  • hls_to_rgb() (colorsys モジュール)
  • hmac (モジュール)
  • HOME, [1], [2], [3], [4]
  • home() (pathlib.Path のクラスメソッド)
    • (turtle モジュール)
  • HOMEDRIVE, [1]
  • HOMEPATH, [1]
  • hook_compressed() (fileinput モジュール)
  • hook_encoded() (fileinput モジュール)
  • hooks
    • import
    • meta
    • path
  • host (urllib.request.Request の属性)
  • hostmask (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • hostname_checks_common_name (ssl.SSLContext の属性)
  • hosts (netrc.netrc の属性)
  • hosts() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • hour (datetime.datetime の属性)
    • (datetime.time の属性)
  • HRESULT (ctypes のクラス)
  • hStdError (subprocess.STARTUPINFO の属性)
  • hStdInput (subprocess.STARTUPINFO の属性)
  • hStdOutput (subprocess.STARTUPINFO の属性)
  • hsv_to_rgb() (colorsys モジュール)
  • ht() (turtle モジュール)
  • HTML, [1]
  • html (モジュール)
  • html() (cgitb モジュール)
  • html.entities (モジュール)
  • html.parser (モジュール)
  • html5 (html.entities モジュール)
  • HTMLCalendar (calendar のクラス)
  • HtmlDiff (difflib のクラス)
  • HTMLParser (html.parser のクラス)
  • htonl() (socket モジュール)
  • htons() (socket モジュール)
  • HTTP
    • http (standard module)
    • http.client (standard module)
    • protocol, [1], [2], [3], [4], [5]
  • HTTP (email.policy モジュール)
  • http (モジュール)
  • http.client (モジュール)
  • http.cookiejar (モジュール)
  • http.cookies (モジュール)
  • http.server (モジュール)
  • http_error_301() (urllib.request.HTTPRedirectHandler のメソッド)
  • http_error_302() (urllib.request.HTTPRedirectHandler のメソッド)
  • http_error_303() (urllib.request.HTTPRedirectHandler のメソッド)
  • http_error_307() (urllib.request.HTTPRedirectHandler のメソッド)
  • http_error_401() (urllib.request.HTTPBasicAuthHandler のメソッド)
    • (urllib.request.HTTPDigestAuthHandler のメソッド)
  • http_error_407() (urllib.request.ProxyBasicAuthHandler のメソッド)
    • (urllib.request.ProxyDigestAuthHandler のメソッド)
  • http_error_auth_reqed() (urllib.request.AbstractBasicAuthHandler のメソッド)
    • (urllib.request.AbstractDigestAuthHandler のメソッド)
  • http_error_default() (urllib.request.BaseHandler のメソッド)
  • http_error_nnn() (urllib.request.BaseHandler のメソッド)
  • http_open() (urllib.request.HTTPHandler のメソッド)
  • HTTP_PORT (http.client モジュール)
  • http_proxy, [1], [2]
  • http_response() (urllib.request.HTTPErrorProcessor のメソッド)
  • http_version (wsgiref.handlers.BaseHandler の属性)
  • HTTPBasicAuthHandler (urllib.request のクラス)
  • HTTPConnection (http.client のクラス)
  • HTTPCookieProcessor (urllib.request のクラス)
  • httpd
  • HTTPDefaultErrorHandler (urllib.request のクラス)
  • HTTPDigestAuthHandler (urllib.request のクラス)
  • HTTPError
  • HTTPErrorProcessor (urllib.request のクラス)
  • HTTPException
  • HTTPHandler (logging.handlers のクラス)
    • (urllib.request のクラス)
  • HTTPPasswordMgr (urllib.request のクラス)
  • HTTPPasswordMgrWithDefaultRealm (urllib.request のクラス)
  • HTTPPasswordMgrWithPriorAuth (urllib.request のクラス)
  • HTTPRedirectHandler (urllib.request のクラス)
  • HTTPResponse (http.client のクラス)
  • https_open() (urllib.request.HTTPSHandler のメソッド)
  • HTTPS_PORT (http.client モジュール)
  • https_response() (urllib.request.HTTPErrorProcessor のメソッド)
  • HTTPSConnection (http.client のクラス)
  • HTTPServer (http.server のクラス)
  • HTTPSHandler (urllib.request のクラス)
  • HTTPStatus (http のクラス)
  • hypot() (math モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – I

  • I (re モジュール)
  • I/O control
    • POSIX
    • UNIX
    • buffering, [1]
    • tty
  • iadd() (operator モジュール)
  • iand() (operator モジュール)
  • iconcat() (operator モジュール)
  • id
    • 組み込み関数
  • id (ssl.SSLSession の属性)
  • id() (unittest.TestCase のメソッド)
    • (組み込み関数)
  • idcok() (curses.window のメソッド)
  • ident (select.kevent の属性)
    • (threading.Thread の属性)
  • identchars (cmd.Cmd の属性)
  • identifier, [1]
  • identify() (tkinter.ttk.Notebook のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
    • (tkinter.ttk.Widget のメソッド)
  • identify_column() (tkinter.ttk.Treeview のメソッド)
  • identify_element() (tkinter.ttk.Treeview のメソッド)
  • identify_region() (tkinter.ttk.Treeview のメソッド)
  • identify_row() (tkinter.ttk.Treeview のメソッド)
  • identity
    • test
  • identity of an object
  • idioms (2to3 fixer)
  • IDLE, [1]
  • IDLE_PRIORITY_CLASS (subprocess モジュール)
  • IDLESTARTUP, [1], [2]
  • idlok() (curses.window のメソッド)
  • if
    • conditional expression
    • in comprehensions
    • 文, [1]
  • if_indextoname() (socket モジュール)
  • if_nameindex() (socket モジュール)
  • if_nametoindex() (socket モジュール)
  • ifloordiv() (operator モジュール)
  • iglob() (glob モジュール)
  • ignorableWhitespace() (xml.sax.handler.ContentHandler のメソッド)
  • ignore (pdb command)
  • ignore_errors() (codecs モジュール)
  • IGNORE_EXCEPTION_DETAIL (doctest モジュール)
  • ignore_patterns() (shutil モジュール)
  • IGNORECASE (re モジュール)
  • ihave() (nntplib.NNTP のメソッド)
  • IISCGIHandler (wsgiref.handlers のクラス)
  • ilshift() (operator モジュール)
  • imag (numbers.Complex の属性)
  • imaginary literal
  • imap() (multiprocessing.pool.Pool のメソッド)
  • IMAP4
    • protocol
  • IMAP4 (imaplib のクラス)
  • IMAP4.abort
  • IMAP4.error
  • IMAP4.readonly
  • IMAP4_SSL
    • protocol
  • IMAP4_SSL (imaplib のクラス)
  • IMAP4_stream
    • protocol
  • IMAP4_stream (imaplib のクラス)
  • imap_unordered() (multiprocessing.pool.Pool のメソッド)
  • imaplib (モジュール)
  • imatmul() (operator モジュール)
  • imghdr (モジュール)
  • immedok() (curses.window のメソッド)
  • immutable
    • data type
    • object, [1]
    • sequence types
    • オブジェクト
  • immutable object
  • immutable sequence
    • オブジェクト
  • immutable types
    • subclassing
  • imod() (operator モジュール)
  • imp
    • モジュール
  • imp (モジュール)
  • ImpImporter (pkgutil のクラス)
  • impl_detail() (test.support モジュール)
  • implementation (sys モジュール)
  • ImpLoader (pkgutil のクラス)
  • import
    • hooks
    • 文, [1], [2], [3], [4]
  • import (2to3 fixer)
  • import hooks
  • import machinery
  • import path
  • import__find__load__done (C の関数)
  • import__find__load__start (C の関数)
  • import_fresh_module() (test.support モジュール)
  • IMPORT_FROM (opcode)
  • import_module() (importlib モジュール)
    • (test.support モジュール)
  • IMPORT_NAME (opcode)
  • IMPORT_STAR (opcode)
  • importer
  • ImportError
    • 例外
  • importing
  • importlib (モジュール)
  • importlib.abc (モジュール)
  • importlib.machinery (モジュール)
  • importlib.resources (モジュール)
  • importlib.util (モジュール)
  • imports (2to3 fixer)
  • imports2 (2to3 fixer)
  • ImportWarning
  • ImproperConnectionState
  • imul() (operator モジュール)
  • in
    • キーワード, [1]
    • 演算子, [1], [2]
  • in_dll() (ctypes._CData のメソッド)
  • in_table_a1() (stringprep モジュール)
  • in_table_b1() (stringprep モジュール)
  • in_table_c11() (stringprep モジュール)
  • in_table_c11_c12() (stringprep モジュール)
  • in_table_c12() (stringprep モジュール)
  • in_table_c21() (stringprep モジュール)
  • in_table_c21_c22() (stringprep モジュール)
  • in_table_c22() (stringprep モジュール)
  • in_table_c3() (stringprep モジュール)
  • in_table_c4() (stringprep モジュール)
  • in_table_c5() (stringprep モジュール)
  • in_table_c6() (stringprep モジュール)
  • in_table_c7() (stringprep モジュール)
  • in_table_c8() (stringprep モジュール)
  • in_table_c9() (stringprep モジュール)
  • in_table_d1() (stringprep モジュール)
  • in_table_d2() (stringprep モジュール)
  • in_transaction (sqlite3.Connection の属性)
  • inch() (curses.window のメソッド)
  • inclusive
    • or
  • inclusive (tracemalloc.DomainFilter の属性)
    • (tracemalloc.Filter の属性)
  • Incomplete
  • IncompleteRead
  • IncompleteReadError
  • incr_item(), [1]
  • increment_lineno() (ast モジュール)
  • IncrementalDecoder (codecs のクラス)
  • incrementaldecoder (codecs.CodecInfo の属性)
  • IncrementalEncoder (codecs のクラス)
  • incrementalencoder (codecs.CodecInfo の属性)
  • IncrementalNewlineDecoder (io のクラス)
  • IncrementalParser (xml.sax.xmlreader のクラス)
  • indent (doctest.Example の属性)
  • INDENT (token モジュール)
  • INDENT token
  • indent() (textwrap モジュール)
  • indentation
  • IndentationError
  • index operation
  • index() (array.array のメソッド)
    • (bytearray のメソッド)
    • (bytes のメソッド)
    • (collections.deque のメソッド)
    • (operator モジュール)
    • (sequence method)
    • (str のメソッド)
    • (tkinter.ttk.Notebook のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
  • IndexError
  • indexOf() (operator モジュール)
  • IndexSizeErr
  • indices() (slice のメソッド)
  • inet_aton() (socket モジュール)
  • inet_ntoa() (socket モジュール)
  • inet_ntop() (socket モジュール)
  • inet_pton() (socket モジュール)
  • Inexact (decimal のクラス)
  • inf (cmath モジュール)
    • (math モジュール)
  • infile
    • json.tool コマンドラインオプション
  • infile (shlex.shlex の属性)
  • Infinity
  • infj (cmath モジュール)
  • info() (dis.Bytecode のメソッド)
    • (gettext.NullTranslations のメソッド)
    • (logging モジュール)
    • (logging.Logger のメソッド)
  • infolist() (zipfile.ZipFile のメソッド)
  • inheritance
  • ini file
  • init() (mimetypes モジュール)
  • init_color() (curses モジュール)
  • init_database() (msilib モジュール)
  • init_pair() (curses モジュール)
  • inited (mimetypes モジュール)
  • initgroups() (os モジュール)
  • initial_indent (textwrap.TextWrapper の属性)
  • initialize_options() (distutils.cmd.Command のメソッド)
  • initscr() (curses モジュール)
  • inode() (os.DirEntry のメソッド)
  • INPLACE_ADD (opcode)
  • INPLACE_AND (opcode)
  • INPLACE_FLOOR_DIVIDE (opcode)
  • INPLACE_LSHIFT (opcode)
  • INPLACE_MATRIX_MULTIPLY (opcode)
  • INPLACE_MODULO (opcode)
  • INPLACE_MULTIPLY (opcode)
  • INPLACE_OR (opcode)
  • INPLACE_POWER (opcode)
  • INPLACE_RSHIFT (opcode)
  • INPLACE_SUBTRACT (opcode)
  • INPLACE_TRUE_DIVIDE (opcode)
  • INPLACE_XOR (opcode)
  • input
    • (2to3 fixer)
  • input() (fileinput モジュール)
    • (組み込み関数)
  • input_charset (email.charset.Charset の属性)
  • input_codec (email.charset.Charset の属性)
  • InputOnly (tkinter.tix のクラス)
  • InputSource (xml.sax.xmlreader のクラス)
  • inquiry (C のデータ型)
  • insch() (curses.window のメソッド)
  • insdelln() (curses.window のメソッド)
  • insert() (array.array のメソッド)
    • (collections.deque のメソッド)
    • (sequence method)
    • (tkinter.ttk.Notebook のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
  • insert_text() (readline モジュール)
  • insertBefore() (xml.dom.Node のメソッド)
  • insertln() (curses.window のメソッド)
  • insnstr() (curses.window のメソッド)
  • insort() (bisect モジュール)
  • insort_left() (bisect モジュール)
  • insort_right() (bisect モジュール)
  • inspect (モジュール)
  • inspect コマンドラインオプション
    • --details
  • InspectLoader (importlib.abc のクラス)
  • insstr() (curses.window のメソッド)
  • install() (gettext モジュール)
    • (gettext.NullTranslations のメソッド)
  • install_opener() (urllib.request モジュール)
  • install_scripts() (venv.EnvBuilder のメソッド)
  • installHandler() (unittest モジュール)
  • instance
    • call, [1]
    • class
    • オブジェクト, [1], [2]
  • instancemethod
    • オブジェクト
  • instate() (tkinter.ttk.Widget のメソッド)
  • instr() (curses.window のメソッド)
  • instream (shlex.shlex の属性)
  • Instruction (dis のクラス)
  • Instruction.arg (dis モジュール)
  • Instruction.argrepr (dis モジュール)
  • Instruction.argval (dis モジュール)
  • Instruction.is_jump_target (dis モジュール)
  • Instruction.offset (dis モジュール)
  • Instruction.opcode (dis モジュール)
  • Instruction.opname (dis モジュール)
  • Instruction.starts_line (dis モジュール)
  • int
    • 組み込み関数, [1], [2]
  • int (uuid.UUID の属性)
    • (組み込みクラス)
  • Int2AP() (imaplib モジュール)
  • int_info (sys モジュール)
  • integer
    • literals
    • representation
    • types, operations on
    • オブジェクト, [1], [2]
  • integer literal
  • Integral (numbers のクラス)
  • Integrated Development Environment
  • IntegrityError
  • Intel/DVI ADPCM
  • IntEnum (enum のクラス)
  • interact (pdb command)
  • interact() (code モジュール)
    • (code.InteractiveConsole のメソッド)
    • (telnetlib.Telnet のメソッド)
  • interactive
  • interactive mode
  • InteractiveConsole (code のクラス)
  • InteractiveInterpreter (code のクラス)
  • intern (2to3 fixer)
  • intern() (sys モジュール)
  • internal type
  • internal_attr (zipfile.ZipInfo の属性)
  • Internaldate2tuple() (imaplib モジュール)
  • internalSubset (xml.dom.DocumentType の属性)
  • Internet
  • interpolated string literal
  • interpolation
    • bytearray (%)
    • bytes (%)
  • interpolation, string (%)
  • InterpolationDepthError
  • InterpolationError
  • InterpolationMissingOptionError
  • InterpolationSyntaxError
  • interpreted
  • interpreter
  • interpreter lock
  • interpreter prompts
  • interpreter shutdown
  • interpreter_requires_environment() (test.support.script_helper モジュール)
  • interrupt() (sqlite3.Connection のメソッド)
  • interrupt_main() (_thread モジュール)
  • InterruptedError
  • intersection() (frozenset のメソッド)
  • intersection_update() (frozenset のメソッド)
  • IntFlag (enum のクラス)
  • intro (cmd.Cmd の属性)
  • InuseAttributeErr
  • inv() (operator モジュール)
  • InvalidAccessErr
  • invalidate_caches() (importlib モジュール)
    • (importlib.abc.MetaPathFinder のメソッド)
    • (importlib.abc.PathEntryFinder のメソッド)
    • (importlib.machinery.FileFinder のメソッド)
    • (importlib.machinery.PathFinder のクラスメソッド)
  • InvalidCharacterErr
  • InvalidModificationErr
  • InvalidOperation (decimal のクラス)
  • InvalidStateErr
  • InvalidStateError
  • InvalidURL
  • inversion
  • invert() (operator モジュール)
  • invocation
  • io
    • モジュール
  • IO (typing のクラス)
  • io (モジュール)
  • io.StringIO
    • オブジェクト
  • IOBase (io のクラス)
  • ioctl() (fcntl モジュール)
    • (socket.socket のメソッド)
  • IOCTL_VM_SOCKETS_GET_LOCAL_CID (socket モジュール)
  • IOError
  • ior() (operator モジュール)
  • ip (ipaddress.IPv4Interface の属性)
    • (ipaddress.IPv6Interface の属性)
  • ip_address() (ipaddress モジュール)
  • ip_interface() (ipaddress モジュール)
  • ip_network() (ipaddress モジュール)
  • ipaddress (モジュール)
  • ipow() (operator モジュール)
  • ipv4_mapped (ipaddress.IPv6Address の属性)
  • IPv4Address (ipaddress のクラス)
  • IPv4Interface (ipaddress のクラス)
  • IPv4Network (ipaddress のクラス)
  • IPV6_ENABLED (test.support モジュール)
  • IPv6Address (ipaddress のクラス)
  • IPv6Interface (ipaddress のクラス)
  • IPv6Network (ipaddress のクラス)
  • irshift() (operator モジュール)
  • is
    • 演算子, [1]
  • is not
    • 演算子, [1]
  • is_() (operator モジュール)
  • is_absolute() (pathlib.PurePath のメソッド)
  • is_alive() (multiprocessing.Process のメソッド)
    • (threading.Thread のメソッド)
  • is_android (test.support モジュール)
  • is_assigned() (symtable.Symbol のメソッド)
  • is_attachment() (email.message.EmailMessage のメソッド)
  • is_authenticated() (urllib.request.HTTPPasswordMgrWithPriorAuth のメソッド)
  • is_block_device() (pathlib.Path のメソッド)
  • is_blocked() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • is_canonical() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_char_device() (pathlib.Path のメソッド)
  • IS_CHARACTER_JUNK() (difflib モジュール)
  • is_check_supported() (lzma モジュール)
  • is_closed() (asyncio.loop のメソッド)
  • is_closing() (asyncio.BaseTransport のメソッド)
    • (asyncio.StreamWriter のメソッド)
  • is_dataclass() (dataclasses モジュール)
  • is_declared_global() (symtable.Symbol のメソッド)
  • is_dir() (os.DirEntry のメソッド)
    • (pathlib.Path のメソッド)
    • (zipfile.ZipInfo のメソッド)
  • is_enabled() (faulthandler モジュール)
  • is_expired() (http.cookiejar.Cookie のメソッド)
  • is_fifo() (pathlib.Path のメソッド)
  • is_file() (os.DirEntry のメソッド)
    • (pathlib.Path のメソッド)
  • is_finalizing() (sys モジュール)
  • is_finite() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_free() (symtable.Symbol のメソッド)
  • is_global (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv6Address の属性)
  • is_global() (symtable.Symbol のメソッド)
  • is_hop_by_hop() (wsgiref.util モジュール)
  • is_imported() (symtable.Symbol のメソッド)
  • is_infinite() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_integer() (float のメソッド)
  • is_jython (test.support モジュール)
  • IS_LINE_JUNK() (difflib モジュール)
  • is_linetouched() (curses.window のメソッド)
  • is_link_local (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_local() (symtable.Symbol のメソッド)
  • is_loopback (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_mount() (pathlib.Path のメソッド)
  • is_multicast (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_multipart() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • is_namespace() (symtable.Symbol のメソッド)
  • is_nan() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_nested() (symtable.SymbolTable のメソッド)
  • is_normal() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_not() (operator モジュール)
  • is_not_allowed() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • is_optimized() (symtable.SymbolTable のメソッド)
  • is_package() (importlib.abc.InspectLoader のメソッド)
    • (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.ExtensionFileLoader のメソッド)
    • (importlib.machinery.SourceFileLoader のメソッド)
    • (importlib.machinery.SourcelessFileLoader のメソッド)
    • (zipimport.zipimporter のメソッド)
  • is_parameter() (symtable.Symbol のメソッド)
  • is_private (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_python_build() (sysconfig モジュール)
  • is_qnan() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_reading() (asyncio.ReadTransport のメソッド)
  • is_referenced() (symtable.Symbol のメソッド)
  • is_reserved (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_reserved() (pathlib.PurePath のメソッド)
  • is_resource() (importlib.abc.ResourceReader のメソッド)
    • (importlib.resources モジュール)
  • is_resource_enabled() (test.support モジュール)
  • is_running() (asyncio.loop のメソッド)
  • is_safe (uuid.UUID の属性)
  • is_serving() (asyncio.Server のメソッド)
  • is_set() (asyncio.Event のメソッド)
    • (threading.Event のメソッド)
  • is_signed() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_site_local (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_snan() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_socket() (pathlib.Path のメソッド)
  • is_subnormal() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_symlink() (os.DirEntry のメソッド)
    • (pathlib.Path のメソッド)
  • is_tarfile() (tarfile モジュール)
  • is_term_resized() (curses モジュール)
  • is_tracing() (tracemalloc モジュール)
  • is_tracked() (gc モジュール)
  • is_unspecified (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • is_wintouched() (curses.window のメソッド)
  • is_zero() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • is_zipfile() (zipfile モジュール)
  • isabs() (os.path モジュール)
  • isabstract() (inspect モジュール)
  • IsADirectoryError
  • isalnum() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isalpha() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isascii() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isasyncgen() (inspect モジュール)
  • isasyncgenfunction() (inspect モジュール)
  • isatty() (chunk.Chunk のメソッド)
    • (io.IOBase のメソッド)
    • (os モジュール)
  • isawaitable() (inspect モジュール)
  • isblank() (curses.ascii モジュール)
  • isblk() (tarfile.TarInfo のメソッド)
  • isbuiltin() (inspect モジュール)
  • ischr() (tarfile.TarInfo のメソッド)
  • isclass() (inspect モジュール)
  • isclose() (cmath モジュール)
    • (math モジュール)
  • iscntrl() (curses.ascii モジュール)
  • iscode() (inspect モジュール)
  • iscoroutine() (asyncio モジュール)
    • (inspect モジュール)
  • iscoroutinefunction() (asyncio モジュール)
    • (inspect モジュール)
  • isctrl() (curses.ascii モジュール)
  • isDaemon() (threading.Thread のメソッド)
  • isdatadescriptor() (inspect モジュール)
  • isdecimal() (str のメソッド)
  • isdev() (tarfile.TarInfo のメソッド)
  • isdigit() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isdir() (os.path モジュール)
    • (tarfile.TarInfo のメソッド)
  • isdisjoint() (frozenset のメソッド)
  • isdown() (turtle モジュール)
  • iselement() (xml.etree.ElementTree モジュール)
  • isenabled() (gc モジュール)
  • isEnabledFor() (logging.Logger のメソッド)
  • isendwin() (curses モジュール)
  • ISEOF() (token モジュール)
  • isexpr() (parser モジュール)
    • (parser.ST のメソッド)
  • isfifo() (tarfile.TarInfo のメソッド)
  • isfile() (os.path モジュール)
    • (tarfile.TarInfo のメソッド)
  • isfinite() (cmath モジュール)
    • (math モジュール)
  • isfirstline() (fileinput モジュール)
  • isframe() (inspect モジュール)
  • isfunction() (inspect モジュール)
  • isfuture() (asyncio モジュール)
  • isgenerator() (inspect モジュール)
  • isgeneratorfunction() (inspect モジュール)
  • isgetsetdescriptor() (inspect モジュール)
  • isgraph() (curses.ascii モジュール)
  • isidentifier() (str のメソッド)
  • isinf() (cmath モジュール)
    • (math モジュール)
  • isinstance (2to3 fixer)
  • isinstance() (組み込み関数)
  • iskeyword() (keyword モジュール)
  • isleap() (calendar モジュール)
  • islice() (itertools モジュール)
  • islink() (os.path モジュール)
  • islnk() (tarfile.TarInfo のメソッド)
  • islower() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • ismemberdescriptor() (inspect モジュール)
  • ismeta() (curses.ascii モジュール)
  • ismethod() (inspect モジュール)
  • ismethoddescriptor() (inspect モジュール)
  • ismodule() (inspect モジュール)
  • ismount() (os.path モジュール)
  • isnan() (cmath モジュール)
    • (math モジュール)
  • ISNONTERMINAL() (token モジュール)
  • isnumeric() (str のメソッド)
  • isocalendar() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
  • isoformat() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
  • isolation_level (sqlite3.Connection の属性)
  • isoweekday() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
  • isprint() (curses.ascii モジュール)
  • isprintable() (str のメソッド)
  • ispunct() (curses.ascii モジュール)
  • isreadable() (pprint モジュール)
    • (pprint.PrettyPrinter のメソッド)
  • isrecursive() (pprint モジュール)
    • (pprint.PrettyPrinter のメソッド)
  • isreg() (tarfile.TarInfo のメソッド)
  • isReservedKey() (http.cookies.Morsel のメソッド)
  • isroutine() (inspect モジュール)
  • isSameNode() (xml.dom.Node のメソッド)
  • isspace() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isstdin() (fileinput モジュール)
  • issubclass() (組み込み関数)
  • issubset() (frozenset のメソッド)
  • issuite() (parser モジュール)
    • (parser.ST のメソッド)
  • issuperset() (frozenset のメソッド)
  • issym() (tarfile.TarInfo のメソッド)
  • ISTERMINAL() (token モジュール)
  • istitle() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • istraceback() (inspect モジュール)
  • isub() (operator モジュール)
  • isupper() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.ascii モジュール)
    • (str のメソッド)
  • isvisible() (turtle モジュール)
  • isxdigit() (curses.ascii モジュール)
  • item
    • sequence
    • string
  • item selection
  • item() (tkinter.ttk.Treeview のメソッド)
    • (xml.dom.NamedNodeMap のメソッド)
    • (xml.dom.NodeList のメソッド)
  • itemgetter() (operator モジュール)
  • items() (configparser.ConfigParser のメソッド)
    • (contextvars.Context のメソッド)
    • (dict のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (types.MappingProxyType のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
  • itemsize (array.array の属性)
    • (memoryview の属性)
  • ItemsView (collections.abc のクラス)
    • (typing のクラス)
  • iter() (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
    • (組み込み関数)
  • iter_attachments() (email.message.EmailMessage のメソッド)
  • iter_child_nodes() (ast モジュール)
  • iter_fields() (ast モジュール)
  • iter_importers() (pkgutil モジュール)
  • iter_modules() (pkgutil モジュール)
  • iter_parts() (email.message.EmailMessage のメソッド)
  • iter_unpack() (struct モジュール)
    • (struct.Struct のメソッド)
  • iterable
    • unpacking
  • Iterable (collections.abc のクラス)
    • (typing のクラス)
  • iterator
  • Iterator (collections.abc のクラス)
    • (typing のクラス)
  • iterator protocol
  • iterdecode() (codecs モジュール)
  • iterdir() (pathlib.Path のメソッド)
  • iterdump() (sqlite3.Connection のメソッド)
  • iterencode() (codecs モジュール)
    • (json.JSONEncoder のメソッド)
  • iterfind() (xml.etree.ElementTree.Element のメソッド)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • iteritems() (mailbox.Mailbox のメソッド)
  • iterkeys() (mailbox.Mailbox のメソッド)
  • itermonthdates() (calendar.Calendar のメソッド)
  • itermonthdays() (calendar.Calendar のメソッド)
  • itermonthdays2() (calendar.Calendar のメソッド)
  • itermonthdays3() (calendar.Calendar のメソッド)
  • itermonthdays4() (calendar.Calendar のメソッド)
  • iterparse() (xml.etree.ElementTree モジュール)
  • itertext() (xml.etree.ElementTree.Element のメソッド)
  • itertools (2to3 fixer)
    • (モジュール)
  • itertools_imports (2to3 fixer)
  • itervalues() (mailbox.Mailbox のメソッド)
  • iterweekdays() (calendar.Calendar のメソッド)
  • ITIMER_PROF (signal モジュール)
  • ITIMER_REAL (signal モジュール)
  • ITIMER_VIRTUAL (signal モジュール)
  • ItimerError
  • itruediv() (operator モジュール)
  • ixor() (operator モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – J

  • j
    • in numeric literal
  • Jansen, Jack
  • Java
    • language
  • java_ver() (platform モジュール)
  • join() (asyncio.Queue のメソッド)
    • (bytearray のメソッド)
    • (bytes のメソッド)
    • (multiprocessing.JoinableQueue のメソッド)
    • (multiprocessing.Process のメソッド)
    • (multiprocessing.pool.Pool のメソッド)
    • (os.path モジュール)
    • (queue.Queue のメソッド)
    • (str のメソッド)
    • (threading.Thread のメソッド)
  • join_thread() (multiprocessing.Queue のメソッド)
    • (test.support モジュール)
  • JoinableQueue (multiprocessing のクラス)
  • joinpath() (pathlib.PurePath のメソッド)
  • js_output() (http.cookies.BaseCookie のメソッド)
    • (http.cookies.Morsel のメソッド)
  • json
    • モジュール
  • json (モジュール)
  • json.tool (モジュール)
  • json.tool コマンドラインオプション
    • --sort-keys
    • -h, --help
    • infile
    • outfile
  • JSONDecodeError
  • JSONDecoder (json のクラス)
  • JSONEncoder (json のクラス)
  • jump (pdb command)
  • JUMP_ABSOLUTE (opcode)
  • JUMP_FORWARD (opcode)
  • JUMP_IF_FALSE_OR_POP (opcode)
  • JUMP_IF_TRUE_OR_POP (opcode)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – K

  • kbhit() (msvcrt モジュール)
  • KDEDIR
  • kevent() (select モジュール)
  • key
    • (http.cookies.Morsel の属性)
  • key function
  • key/datum pair
  • KEY_ALL_ACCESS (winreg モジュール)
  • KEY_CREATE_LINK (winreg モジュール)
  • KEY_CREATE_SUB_KEY (winreg モジュール)
  • KEY_ENUMERATE_SUB_KEYS (winreg モジュール)
  • KEY_EXECUTE (winreg モジュール)
  • KEY_NOTIFY (winreg モジュール)
  • KEY_QUERY_VALUE (winreg モジュール)
  • KEY_READ (winreg モジュール)
  • KEY_SET_VALUE (winreg モジュール)
  • KEY_WOW64_32KEY (winreg モジュール)
  • KEY_WOW64_64KEY (winreg モジュール)
  • KEY_WRITE (winreg モジュール)
  • KeyboardInterrupt
    • (built-in exception), [1]
  • KeyError
  • keyname() (curses モジュール)
  • keypad() (curses.window のメソッド)
  • keyrefs() (weakref.WeakKeyDictionary のメソッド)
  • keys() (contextvars.Context のメソッド)
    • (dict のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (sqlite3.Row のメソッド)
    • (types.MappingProxyType のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
  • KeysView (collections.abc のクラス)
    • (typing のクラス)
  • keyword
    • (モジュール)
  • keyword argument
  • keywords (functools.partial の属性)
  • kill() (asyncio.asyncio.subprocess.Process のメソッド)
    • (asyncio.SubprocessTransport のメソッド)
    • (multiprocessing.Process のメソッド)
    • (os モジュール)
    • (subprocess.Popen のメソッド)
  • kill_python() (test.support.script_helper モジュール)
  • killchar() (curses モジュール)
  • killpg() (os モジュール)
  • kind (inspect.Parameter の属性)
  • knownfiles (mimetypes モジュール)
  • kqueue() (select モジュール)
  • KqueueSelector (selectors のクラス)
  • kwargs (inspect.BoundArguments の属性)
  • kwlist (keyword モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – L

  • L (re モジュール)
  • LabelEntry (tkinter.tix のクラス)
  • LabelFrame (tkinter.tix のクラス)
  • lambda
    • expression, [1]
    • form
  • LambdaType (types モジュール)
  • LANG, [1], [2], [3], [4]
  • LANGUAGE, [1]
  • language
    • C, [1], [2], [3], [4], [5]
    • Java
  • large files
  • LargeZipFile
  • last() (nntplib.NNTP のメソッド)
  • last_accepted (multiprocessing.connection.Listener の属性)
  • last_traceback (in module sys)
    • (sys モジュール)
  • last_type (sys モジュール)
  • last_value (sys モジュール)
  • lastChild (xml.dom.Node の属性)
  • lastcmd (cmd.Cmd の属性)
  • lastgroup (re.Match の属性)
  • lastindex (re.Match の属性)
  • lastResort (logging モジュール)
  • lastrowid (sqlite3.Cursor の属性)
  • layout() (tkinter.ttk.Style のメソッド)
  • lazycache() (linecache モジュール)
  • LazyLoader (importlib.util のクラス)
  • LBRACE (token モジュール)
  • LBYL
  • LC_ALL, [1]
    • (locale モジュール)
  • LC_COLLATE (locale モジュール)
  • LC_CTYPE (locale モジュール)
  • LC_MESSAGES, [1]
    • (locale モジュール)
  • LC_MONETARY (locale モジュール)
  • LC_NUMERIC (locale モジュール)
  • LC_TIME (locale モジュール)
  • lchflags() (os モジュール)
  • lchmod() (os モジュール)
    • (pathlib.Path のメソッド)
  • lchown() (os モジュール)
  • LDCXXSHARED
  • ldexp() (math モジュール)
  • LDFLAGS
  • ldgettext() (gettext モジュール)
  • ldngettext() (gettext モジュール)
  • le() (operator モジュール)
  • leading whitespace
  • leapdays() (calendar モジュール)
  • leaveok() (curses.window のメソッド)
  • left (filecmp.dircmp の属性)
  • left() (turtle モジュール)
  • left_list (filecmp.dircmp の属性)
  • left_only (filecmp.dircmp の属性)
  • LEFTSHIFT (token モジュール)
  • LEFTSHIFTEQUAL (token モジュール)
  • len
    • 組み込み関数, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]
  • len() (組み込み関数)
  • length (xml.dom.NamedNodeMap の属性)
    • (xml.dom.NodeList の属性)
  • length_hint() (operator モジュール)
  • LESS (token モジュール)
  • LESSEQUAL (token モジュール)
  • lexical analysis
  • lexical definitions
  • lexists() (os.path モジュール)
  • lgamma() (math モジュール)
  • lgettext() (gettext モジュール)
    • (gettext.GNUTranslations のメソッド)
    • (gettext.NullTranslations のメソッド)
  • lib2to3 (モジュール)
  • libc_ver() (platform モジュール)
  • library (dbm.ndbm モジュール)
    • (ssl.SSLError の属性)
  • library_dir_option() (distutils.ccompiler.CCompiler のメソッド)
  • library_filename() (distutils.ccompiler.CCompiler のメソッド)
  • library_option() (distutils.ccompiler.CCompiler のメソッド)
  • LibraryLoader (ctypes のクラス)
  • license (組み込み変数)
  • LifoQueue (asyncio のクラス)
    • (queue のクラス)
  • light-weight processes
  • limit_denominator() (fractions.Fraction のメソッド)
  • LimitOverrunError
  • lin2adpcm() (audioop モジュール)
  • lin2alaw() (audioop モジュール)
  • lin2lin() (audioop モジュール)
  • lin2ulaw() (audioop モジュール)
  • line (C の関数)
  • line continuation
  • line joining, [1]
  • line structure
  • line() (msilib.Dialog のメソッド)
  • line-buffered I/O
  • line_buffering (io.TextIOWrapper の属性)
  • line_num (csv.csvreader の属性)
  • linecache (モジュール)
  • lineno (ast.AST の属性)
    • (doctest.DocTest の属性)
    • (doctest.Example の属性)
    • (json.JSONDecodeError の属性)
    • (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
    • (re.error の属性)
    • (shlex.shlex の属性)
    • (traceback.TracebackException の属性)
    • (tracemalloc.Filter の属性)
    • (tracemalloc.Frame の属性)
    • (xml.parsers.expat.ExpatError の属性)
  • lineno() (fileinput モジュール)
  • LINES, [1], [2], [3], [4]
  • lines (os.terminal_size の属性)
  • linesep (email.policy.Policy の属性)
    • (os モジュール)
  • lineterminator (csv.Dialect の属性)
  • LineTooLong
  • link() (distutils.ccompiler.CCompiler のメソッド)
    • (os モジュール)
  • link_executable() (distutils.ccompiler.CCompiler のメソッド)
  • link_shared_lib() (distutils.ccompiler.CCompiler のメソッド)
  • link_shared_object() (distutils.ccompiler.CCompiler のメソッド)
  • linkname (tarfile.TarInfo の属性)
  • linux_distribution() (platform モジュール)
  • list
    • assignment, target
    • comprehensions
    • deletion target
    • display
    • empty
    • expression, [1], [2]
    • target, [1], [2]
    • type, operations on
    • オブジェクト, [1], [2], [3], [4], [5], [6], [7], [8]
  • list (pdb command)
  • List (typing のクラス)
  • list (組み込みクラス)
  • list comprehension
  • list() (imaplib.IMAP4 のメソッド)
    • (multiprocessing.managers.SyncManager のメソッド)
    • (nntplib.NNTP のメソッド)
    • (poplib.POP3 のメソッド)
    • (tarfile.TarFile のメソッド)
  • LIST_APPEND (opcode)
  • list_dialects() (csv モジュール)
  • list_folders() (mailbox.Maildir のメソッド)
    • (mailbox.MH のメソッド)
  • listdir() (os モジュール)
  • listen() (asyncore.dispatcher のメソッド)
    • (logging.config モジュール)
    • (socket.socket のメソッド)
    • (turtle モジュール)
  • Listener (multiprocessing.connection のクラス)
  • listMethods() (xmlrpc.client.ServerProxy.system のメソッド)
  • ListNoteBook (tkinter.tix のクラス)
  • listxattr() (os モジュール)
  • literal, [1]
  • literal_eval() (ast モジュール)
  • literals
    • binary
    • complex number
    • floating point
    • hexadecimal
    • integer
    • numeric
    • octal
  • LittleEndianStructure (ctypes のクラス)
  • ljust() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • LK_LOCK (msvcrt モジュール)
  • LK_NBLCK (msvcrt モジュール)
  • LK_NBRLCK (msvcrt モジュール)
  • LK_RLCK (msvcrt モジュール)
  • LK_UNLCK (msvcrt モジュール)
  • ll (pdb command)
  • LMTP (smtplib のクラス)
  • ln() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • LNAME
  • lngettext() (gettext モジュール)
    • (gettext.GNUTranslations のメソッド)
    • (gettext.NullTranslations のメソッド)
  • load() (http.cookiejar.FileCookieJar のメソッド)
    • (http.cookies.BaseCookie のメソッド)
    • (json モジュール)
    • (marshal モジュール)
    • (pickle モジュール)
    • (pickle.Unpickler のメソッド)
    • (plistlib モジュール)
    • (tracemalloc.Snapshot のクラスメソッド)
  • LOAD_ATTR (opcode)
  • LOAD_BUILD_CLASS (opcode)
  • load_cert_chain() (ssl.SSLContext のメソッド)
  • LOAD_CLASSDEREF (opcode)
  • LOAD_CLOSURE (opcode)
  • LOAD_CONST (opcode)
  • load_default_certs() (ssl.SSLContext のメソッド)
  • LOAD_DEREF (opcode)
  • load_dh_params() (ssl.SSLContext のメソッド)
  • load_extension() (sqlite3.Connection のメソッド)
  • LOAD_FAST (opcode)
  • LOAD_GLOBAL (opcode)
  • LOAD_METHOD (opcode)
  • load_module() (imp モジュール)
    • (importlib.abc.FileLoader のメソッド)
    • (importlib.abc.InspectLoader のメソッド)
    • (importlib.abc.Loader のメソッド)
    • (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.SourceFileLoader のメソッド)
    • (importlib.machinery.SourcelessFileLoader のメソッド)
    • (zipimport.zipimporter のメソッド)
  • LOAD_NAME (opcode)
  • load_package_tests() (test.support モジュール)
  • load_verify_locations() (ssl.SSLContext のメソッド)
  • loader, [1]
  • Loader (importlib.abc のクラス)
  • loader (importlib.machinery.ModuleSpec の属性)
  • loader_state (importlib.machinery.ModuleSpec の属性)
  • LoadError
  • LoadKey() (winreg モジュール)
  • LoadLibrary() (ctypes.LibraryLoader のメソッド)
  • loads() (json モジュール)
    • (marshal モジュール)
    • (pickle モジュール)
    • (plistlib モジュール)
    • (xmlrpc.client モジュール)
  • loadTestsFromModule() (unittest.TestLoader のメソッド)
  • loadTestsFromName() (unittest.TestLoader のメソッド)
  • loadTestsFromNames() (unittest.TestLoader のメソッド)
  • loadTestsFromTestCase() (unittest.TestLoader のメソッド)
  • local (threading のクラス)
  • localcontext() (decimal モジュール)
  • LOCALE (re モジュール)
  • locale (モジュール)
  • localeconv() (locale モジュール)
  • LocaleHTMLCalendar (calendar のクラス)
  • LocaleTextCalendar (calendar のクラス)
  • localName (xml.dom.Attr の属性)
    • (xml.dom.Node の属性)
  • locals() (組み込み関数)
  • localtime() (email.utils モジュール)
    • (time モジュール)
  • Locator (xml.sax.xmlreader のクラス)
  • Lock (asyncio のクラス)
    • (multiprocessing のクラス)
    • (threading のクラス)
  • lock() (mailbox.Babyl のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.MMDF のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (mailbox.mbox のメソッド)
  • Lock() (multiprocessing.managers.SyncManager のメソッド)
  • lock, interpreter
  • lock_held() (imp モジュール)
  • locked() (_thread.lock のメソッド)
    • (asyncio.Condition のメソッド)
    • (asyncio.Lock のメソッド)
    • (asyncio.Semaphore のメソッド)
  • lockf() (fcntl モジュール)
    • (os モジュール)
  • locking() (msvcrt モジュール)
  • LockType (_thread モジュール)
  • log() (cmath モジュール)
    • (logging モジュール)
    • (logging.Logger のメソッド)
    • (math モジュール)
  • log10() (cmath モジュール)
    • (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (math モジュール)
  • log1p() (math モジュール)
  • log2() (math モジュール)
  • log_date_time_string() (http.server.BaseHTTPRequestHandler のメソッド)
  • log_error() (http.server.BaseHTTPRequestHandler のメソッド)
  • log_exception() (wsgiref.handlers.BaseHandler のメソッド)
  • log_message() (http.server.BaseHTTPRequestHandler のメソッド)
  • log_request() (http.server.BaseHTTPRequestHandler のメソッド)
  • log_to_stderr() (multiprocessing モジュール)
  • logb() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • Logger (logging のクラス)
  • LoggerAdapter (logging のクラス)
  • logging
    • Errors
  • logging (モジュール)
  • logging.config (モジュール)
  • logging.handlers (モジュール)
  • logical line
  • logical_and() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • logical_invert() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • logical_or() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • logical_xor() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • login() (ftplib.FTP のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (nntplib.NNTP のメソッド)
    • (smtplib.SMTP のメソッド)
  • login_cram_md5() (imaplib.IMAP4 のメソッド)
  • LOGNAME, [1]
  • lognormvariate() (random モジュール)
  • logout() (imaplib.IMAP4 のメソッド)
  • LogRecord (logging のクラス)
  • long (2to3 fixer)
  • long integer
    • オブジェクト
  • LONG_MAX
  • longMessage (unittest.TestCase の属性)
  • longname() (curses モジュール)
  • lookup() (codecs モジュール)
    • (symtable.SymbolTable のメソッド)
    • (tkinter.ttk.Style のメソッド)
    • (unicodedata モジュール)
  • lookup_error() (codecs モジュール)
  • LookupError
  • loop
    • over mutable sequence
    • statement, [1], [2], [3]
  • loop control
    • target
  • loop() (asyncore モジュール)
  • lower() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • LPAR (token モジュール)
  • lpAttributeList (subprocess.STARTUPINFO の属性)
  • lru_cache() (functools モジュール)
  • lseek() (os モジュール)
  • lshift() (operator モジュール)
  • LSQB (token モジュール)
  • lstat() (os モジュール)
    • (pathlib.Path のメソッド)
  • lstrip() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • lsub() (imaplib.IMAP4 のメソッド)
  • lt() (operator モジュール)
    • (turtle モジュール)
  • LWPCookieJar (http.cookiejar のクラス)
  • lzma (モジュール)
  • LZMACompressor (lzma のクラス)
  • LZMADecompressor (lzma のクラス)
  • LZMAError
  • LZMAFile (lzma のクラス)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – M

  • M (re モジュール)
  • mac_ver() (platform モジュール)
  • machine() (platform モジュール)
  • macpath (モジュール)
  • macros (netrc.netrc の属性)
  • MAGIC_NUMBER (importlib.util モジュール)
  • MagicMock (unittest.mock のクラス)
  • Mailbox (mailbox のクラス)
  • mailbox (モジュール)
  • mailcap (モジュール)
  • Maildir (mailbox のクラス)
  • MaildirMessage (mailbox のクラス)
  • mailfrom (smtpd.SMTPChannel の属性)
  • MailmanProxy (smtpd のクラス)
  • main(), [1], [2]
    • (py_compile モジュール)
    • (site モジュール)
    • (unittest モジュール)
  • main_thread() (threading モジュール)
  • mainloop() (turtle モジュール)
  • maintype (email.headerregistry.ContentTypeHeader の属性)
  • major (email.headerregistry.MIMEVersionHeader の属性)
  • major() (os モジュール)
  • make_alternative() (email.message.EmailMessage のメソッド)
  • make_archive() (distutils.archive_util モジュール)
    • (shutil モジュール)
  • make_bad_fd() (test.support モジュール)
  • make_cookies() (http.cookiejar.CookieJar のメソッド)
  • make_dataclass() (dataclasses モジュール)
  • make_file() (difflib.HtmlDiff のメソッド)
  • MAKE_FUNCTION (opcode)
  • make_header() (email.header モジュール)
  • make_legacy_pyc() (test.support モジュール)
  • make_mixed() (email.message.EmailMessage のメソッド)
  • make_msgid() (email.utils モジュール)
  • make_parser() (xml.sax モジュール)
  • make_pkg() (test.support.script_helper モジュール)
  • make_related() (email.message.EmailMessage のメソッド)
  • make_script() (test.support.script_helper モジュール)
  • make_server() (wsgiref.simple_server モジュール)
  • make_table() (difflib.HtmlDiff のメソッド)
  • make_tarball() (distutils.archive_util モジュール)
  • make_zip_pkg() (test.support.script_helper モジュール)
  • make_zip_script() (test.support.script_helper モジュール)
  • make_zipfile() (distutils.archive_util モジュール)
  • makedev() (os モジュール)
  • makedirs() (os モジュール)
  • makeelement() (xml.etree.ElementTree.Element のメソッド)
  • makefile() (socket method)
    • (socket.socket のメソッド)
  • makeLogRecord() (logging モジュール)
  • makePickle() (logging.handlers.SocketHandler のメソッド)
  • makeRecord() (logging.Logger のメソッド)
  • makeSocket() (logging.handlers.DatagramHandler のメソッド)
    • (logging.handlers.SocketHandler のメソッド)
  • maketrans() (bytearray の静的メソッド)
    • (bytes の静的メソッド)
    • (str の静的メソッド)
  • malloc()
  • mangle_from_ (email.policy.Compat32 の属性)
    • (email.policy.Policy の属性)
  • mangling
    • name, [1]
  • map (2to3 fixer)
  • map() (concurrent.futures.Executor のメソッド)
    • (multiprocessing.pool.Pool のメソッド)
    • (tkinter.ttk.Style のメソッド)
    • (組み込み関数)
  • MAP_ADD (opcode)
  • map_async() (multiprocessing.pool.Pool のメソッド)
  • map_table_b2() (stringprep モジュール)
  • map_table_b3() (stringprep モジュール)
  • map_to_type() (email.headerregistry.HeaderRegistry のメソッド)
  • mapLogRecord() (logging.handlers.HTTPHandler のメソッド)
  • mapping
    • types, operations on
    • オブジェクト, [1], [2], [3], [4], [5]
  • Mapping (collections.abc のクラス)
    • (typing のクラス)
  • mapping() (msilib.Control のメソッド)
  • MappingProxyType (types のクラス)
  • MappingView (collections.abc のクラス)
    • (typing のクラス)
  • mapPriority() (logging.handlers.SysLogHandler のメソッド)
  • maps (collections.ChainMap の属性)
  • maps() (nis モジュール)
  • marshal (モジュール)
  • marshalling
    • objects
  • masking
    • operations
  • Match (typing のクラス)
  • match() (nis モジュール)
    • (pathlib.PurePath のメソッド)
    • (re モジュール)
    • (re.Pattern のメソッド)
  • match_hostname() (ssl モジュール)
  • match_test() (test.support モジュール)
  • match_value() (test.support.Matcher のメソッド)
  • Matcher (test.support のクラス)
  • matches() (test.support.Matcher のメソッド)
  • math
    • モジュール, [1]
  • math (モジュール)
  • matmul() (operator モジュール)
  • matrix multiplication
  • max
    • 組み込み関数
  • max (datetime.date の属性)
    • (datetime.datetime の属性)
    • (datetime.time の属性)
    • (datetime.timedelta の属性)
  • max() (audioop モジュール)
    • (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (組み込み関数)
  • max_count (email.headerregistry.BaseHeader の属性)
  • MAX_EMAX (decimal モジュール)
  • MAX_INTERPOLATION_DEPTH (configparser モジュール)
  • max_line_length (email.policy.Policy の属性)
  • max_lines (textwrap.TextWrapper の属性)
  • max_mag() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • max_memuse (test.support モジュール)
  • MAX_PREC (decimal モジュール)
  • max_prefixlen (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
  • MAX_Py_ssize_t (test.support モジュール)
  • maxarray (reprlib.Repr の属性)
  • maxdeque (reprlib.Repr の属性)
  • maxdict (reprlib.Repr の属性)
  • maxDiff (unittest.TestCase の属性)
  • maxfrozenset (reprlib.Repr の属性)
  • MAXIMUM_SUPPORTED (ssl.TLSVersion の属性)
  • maximum_version (ssl.SSLContext の属性)
  • maxlen (collections.deque の属性)
  • maxlevel (reprlib.Repr の属性)
  • maxlist (reprlib.Repr の属性)
  • maxlong (reprlib.Repr の属性)
  • maxother (reprlib.Repr の属性)
  • maxpp() (audioop モジュール)
  • maxset (reprlib.Repr の属性)
  • maxsize (asyncio.Queue の属性)
    • (sys モジュール)
  • maxstring (reprlib.Repr の属性)
  • maxtuple (reprlib.Repr の属性)
  • maxunicode (sys モジュール)
  • MAXYEAR (datetime モジュール)
  • MB_ICONASTERISK (winsound モジュール)
  • MB_ICONEXCLAMATION (winsound モジュール)
  • MB_ICONHAND (winsound モジュール)
  • MB_ICONQUESTION (winsound モジュール)
  • MB_OK (winsound モジュール)
  • mbox (mailbox のクラス)
  • mboxMessage (mailbox のクラス)
  • mean() (statistics モジュール)
  • median() (statistics モジュール)
  • median_grouped() (statistics モジュール)
  • median_high() (statistics モジュール)
  • median_low() (statistics モジュール)
  • MemberDescriptorType (types モジュール)
  • membership
    • test
  • memmove() (ctypes モジュール)
  • MemoryBIO (ssl のクラス)
  • MemoryError
  • MemoryHandler (logging.handlers のクラス)
  • memoryview
    • オブジェクト, [1]
  • memoryview (組み込みクラス)
  • memset() (ctypes モジュール)
  • merge() (heapq モジュール)
  • Message (email.message のクラス)
    • (mailbox のクラス)
  • message digest, MD5
  • message_factory (email.policy.Policy の属性)
  • message_from_binary_file() (email モジュール)
  • message_from_bytes() (email モジュール)
  • message_from_file() (email モジュール)
  • message_from_string() (email モジュール)
  • MessageBeep() (winsound モジュール)
  • MessageClass (http.server.BaseHTTPRequestHandler の属性)
  • MessageError
  • MessageParseError
  • messages (xml.parsers.expat.errors モジュール)
  • meta
    • hooks
  • meta hooks
  • meta path finder
  • meta() (curses モジュール)
  • meta_path (sys モジュール)
  • metaclass, [1]
    • (2to3 fixer)
  • metaclass hint
  • MetaPathFinder (importlib.abc のクラス)
  • metavar (optparse.Option の属性)
  • MetavarTypeHelpFormatter (argparse のクラス)
  • Meter (tkinter.tix のクラス)
  • METH_CLASS (組み込み変数)
  • METH_COEXIST (組み込み変数)
  • METH_KEYWORDS (組み込み変数)
  • METH_NOARGS (組み込み変数)
  • METH_O (組み込み変数)
  • METH_STATIC (組み込み変数)
  • METH_VARARGS (組み込み変数)
  • method
    • built-in
    • call
    • user-defined
    • オブジェクト, [1], [2], [3], [4], [5]
  • method (urllib.request.Request の属性)
  • method resolution order
  • METHOD_BLOWFISH (crypt モジュール)
  • method_calls (unittest.mock.Mock の属性)
  • METHOD_CRYPT (crypt モジュール)
  • METHOD_MD5 (crypt モジュール)
  • METHOD_SHA256 (crypt モジュール)
  • METHOD_SHA512 (crypt モジュール)
  • methodattrs (2to3 fixer)
  • methodcaller() (operator モジュール)
  • MethodDescriptorType (types モジュール)
  • methodHelp() (xmlrpc.client.ServerProxy.system のメソッド)
  • methods
    • bytearray
    • bytes
    • string
  • methods (crypt モジュール)
    • (pyclbr.Class の属性)
  • methodSignature() (xmlrpc.client.ServerProxy.system のメソッド)
  • MethodType (in module types), [1]
    • (types モジュール)
  • MethodWrapperType (types モジュール)
  • MH (mailbox のクラス)
  • MHMessage (mailbox のクラス)
  • microsecond (datetime.datetime の属性)
    • (datetime.time の属性)
  • MIME
    • base64 encoding
    • content type
    • headers, [1]
    • quoted-printable encoding
  • MIMEApplication (email.mime.application のクラス)
  • MIMEAudio (email.mime.audio のクラス)
  • MIMEBase (email.mime.base のクラス)
  • MIMEImage (email.mime.image のクラス)
  • MIMEMessage (email.mime.message のクラス)
  • MIMEMultipart (email.mime.multipart のクラス)
  • MIMENonMultipart (email.mime.nonmultipart のクラス)
  • MIMEPart (email.message のクラス)
  • MIMEText (email.mime.text のクラス)
  • MimeTypes (mimetypes のクラス)
  • mimetypes (モジュール)
  • MIMEVersionHeader (email.headerregistry のクラス)
  • min
    • 組み込み関数
  • min (datetime.date の属性)
    • (datetime.datetime の属性)
    • (datetime.time の属性)
    • (datetime.timedelta の属性)
  • min() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (組み込み関数)
  • MIN_EMIN (decimal モジュール)
  • MIN_ETINY (decimal モジュール)
  • min_mag() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • MINEQUAL (token モジュール)
  • MINIMUM_SUPPORTED (ssl.TLSVersion の属性)
  • minimum_version (ssl.SSLContext の属性)
  • minmax() (audioop モジュール)
  • minor (email.headerregistry.MIMEVersionHeader の属性)
  • minor() (os モジュール)
  • minus
  • MINUS (token モジュール)
  • minus() (decimal.Context のメソッド)
  • minute (datetime.datetime の属性)
    • (datetime.time の属性)
  • MINYEAR (datetime モジュール)
  • mirrored() (unicodedata モジュール)
  • misc_header (cmd.Cmd の属性)
  • MISSING (contextvars.contextvars.Token.Token の属性)
  • MISSING_C_DOCSTRINGS (test.support モジュール)
  • missing_compiler_executable() (test.support モジュール)
  • MissingSectionHeaderError
  • MIXERDEV
  • mkd() (ftplib.FTP のメソッド)
  • mkdir() (os モジュール)
    • (pathlib.Path のメソッド)
  • mkdtemp() (tempfile モジュール)
  • mkfifo() (os モジュール)
  • mknod() (os モジュール)
  • mkpath() (distutils.ccompiler.CCompiler のメソッド)
    • (distutils.dir_util モジュール)
  • mksalt() (crypt モジュール)
  • mkstemp() (tempfile モジュール)
  • mktemp() (tempfile モジュール)
  • mktime() (time モジュール)
  • mktime_tz() (email.utils モジュール)
  • mlsd() (ftplib.FTP のメソッド)
  • mmap (mmap のクラス)
    • (モジュール)
  • MMDF (mailbox のクラス)
  • MMDFMessage (mailbox のクラス)
  • Mock (unittest.mock のクラス)
  • mock_add_spec() (unittest.mock.Mock のメソッド)
  • mock_calls (unittest.mock.Mock の属性)
  • mock_open() (unittest.mock モジュール)
  • mod() (operator モジュール)
  • mode (io.FileIO の属性)
    • (ossaudiodev.oss_audio_device の属性)
    • (tarfile.TarInfo の属性)
  • mode() (statistics モジュール)
    • (turtle モジュール)
  • modes
    • file
  • modf() (math モジュール)
  • modified() (urllib.robotparser.RobotFileParser のメソッド)
  • Modify() (msilib.View のメソッド)
  • modify() (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.poll のメソッド)
    • (selectors.BaseSelector のメソッド)
  • module
    • extension
    • importing
    • namespace
    • search path, [1], [2], [3], [4], [5], [6], [7]
    • オブジェクト, [1], [2]
  • module (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
  • module spec, [1]
  • module_for_loader() (importlib.util モジュール)
  • module_from_spec() (importlib.util モジュール)
  • module_repr() (importlib.abc.Loader のメソッド)
  • ModuleFinder (modulefinder のクラス)
  • modulefinder (モジュール)
  • ModuleInfo (pkgutil のクラス)
  • ModuleNotFoundError
  • modules (in module sys), [1]
    • (modulefinder.ModuleFinder の属性)
    • (sys モジュール)
  • modules_cleanup() (test.support モジュール)
  • modules_setup() (test.support モジュール)
  • ModuleSpec (importlib.machinery のクラス)
  • ModuleType (in module types)
    • (types のクラス)
  • modulo
  • monotonic() (time モジュール)
  • monotonic_ns() (time モジュール)
  • month (datetime.date の属性)
    • (datetime.datetime の属性)
  • month() (calendar モジュール)
  • month_abbr (calendar モジュール)
  • month_name (calendar モジュール)
  • monthcalendar() (calendar モジュール)
  • monthdatescalendar() (calendar.Calendar のメソッド)
  • monthdays2calendar() (calendar.Calendar のメソッド)
  • monthdayscalendar() (calendar.Calendar のメソッド)
  • monthrange() (calendar モジュール)
  • Morsel (http.cookies のクラス)
  • most_common() (collections.Counter のメソッド)
  • mouseinterval() (curses モジュール)
  • mousemask() (curses モジュール)
  • move() (curses.panel.Panel のメソッド)
    • (curses.window のメソッド)
    • (mmap.mmap のメソッド)
    • (shutil モジュール)
    • (tkinter.ttk.Treeview のメソッド)
  • move_file() (distutils.ccompiler.CCompiler のメソッド)
    • (distutils.file_util モジュール)
  • move_to_end() (collections.OrderedDict のメソッド)
  • MozillaCookieJar (http.cookiejar のクラス)
  • MRO
  • mro() (class のメソッド)
  • msg (http.client.HTTPResponse の属性)
    • (json.JSONDecodeError の属性)
    • (re.error の属性)
    • (traceback.TracebackException の属性)
  • msg() (telnetlib.Telnet のメソッド)
  • msi
  • msilib (モジュール)
  • msvcrt (モジュール)
  • mt_interact() (telnetlib.Telnet のメソッド)
  • mtime (gzip.GzipFile の属性)
    • (tarfile.TarInfo の属性)
  • mtime() (urllib.robotparser.RobotFileParser のメソッド)
  • mul() (audioop モジュール)
    • (operator モジュール)
  • MultiCall (xmlrpc.client のクラス)
  • MULTILINE (re モジュール)
  • MultipartConversionError
  • multiplication
  • multiply() (decimal.Context のメソッド)
  • multiprocessing (モジュール)
  • multiprocessing.connection (モジュール)
  • multiprocessing.dummy (モジュール)
  • multiprocessing.Manager() (multiprocessing.sharedctypes モジュール)
  • multiprocessing.managers (モジュール)
  • multiprocessing.pool (モジュール)
  • multiprocessing.sharedctypes (モジュール)
  • mutable
    • sequence types
    • オブジェクト, [1], [2]
  • mutable object
  • mutable sequence
    • loop over
    • オブジェクト
  • MutableMapping (collections.abc のクラス)
    • (typing のクラス)
  • MutableSequence (collections.abc のクラス)
    • (typing のクラス)
  • MutableSet (collections.abc のクラス)
    • (typing のクラス)
  • mvderwin() (curses.window のメソッド)
  • mvwin() (curses.window のメソッド)
  • myrights() (imaplib.IMAP4 のメソッド)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – N

  • N_TOKENS (token モジュール)
  • n_waiting (threading.Barrier の属性)
  • name, [1], [2]
    • binding, [1], [2], [3], [4], [5], [6]
    • binding, global
    • class
    • function, [1]
    • mangling, [1]
    • rebinding
    • unbinding
  • name (codecs.CodecInfo の属性)
    • (contextvars.ContextVar の属性)
    • (doctest.DocTest の属性)
    • (email.headerregistry.BaseHeader の属性)
    • (hashlib.hash の属性)
    • (hmac.HMAC の属性)
    • (http.cookiejar.Cookie の属性)
    • (importlib.abc.FileLoader の属性)
    • (importlib.machinery.ExtensionFileLoader の属性)
    • (importlib.machinery.ModuleSpec の属性)
    • (importlib.machinery.SourceFileLoader の属性)
    • (importlib.machinery.SourcelessFileLoader の属性)
    • (inspect.Parameter の属性)
    • (io.FileIO の属性)
    • (multiprocessing.Process の属性)
    • (os モジュール)
    • (os.DirEntry の属性)
    • (ossaudiodev.oss_audio_device の属性)
    • (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
    • (tarfile.TarInfo の属性)
    • (threading.Thread の属性)
  • NAME (token モジュール)
  • name (xml.dom.Attr の属性)
    • (xml.dom.DocumentType の属性)
  • name() (unicodedata モジュール)
  • name2codepoint (html.entities モジュール)
  • named tuple
  • NamedTemporaryFile() (tempfile モジュール)
  • NamedTuple (typing のクラス)
  • namedtuple() (collections モジュール)
  • NameError
    • 例外
  • NameError (built-in exception)
  • namelist() (zipfile.ZipFile のメソッド)
  • nameprep() (encodings.idna モジュール)
  • namer (logging.handlers.BaseRotatingHandler の属性)
  • namereplace_errors() (codecs モジュール)
  • names
    • private
  • namespace, [1]
    • global
    • module
    • package
  • Namespace (argparse のクラス)
    • (multiprocessing.managers のクラス)
  • namespace package
  • namespace() (imaplib.IMAP4 のメソッド)
  • Namespace() (multiprocessing.managers.SyncManager のメソッド)
  • NAMESPACE_DNS (uuid モジュール)
  • NAMESPACE_OID (uuid モジュール)
  • NAMESPACE_URL (uuid モジュール)
  • NAMESPACE_X500 (uuid モジュール)
  • NamespaceErr
  • namespaceURI (xml.dom.Node の属性)
  • NaN
  • nan (cmath モジュール)
    • (math モジュール)
  • nanj (cmath モジュール)
  • NannyNag
  • napms() (curses モジュール)
  • nargs (optparse.Option の属性)
  • nbytes (memoryview の属性)
  • ndiff() (difflib モジュール)
  • ndim (memoryview の属性)
  • ne (2to3 fixer)
  • ne() (operator モジュール)
  • needs_input (bz2.BZ2Decompressor の属性)
    • (lzma.LZMADecompressor の属性)
  • neg() (operator モジュール)
  • negation
  • nested scope
  • netmask (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • NetmaskValueError
  • netrc (netrc のクラス)
    • (モジュール)
  • NetrcParseError
  • netscape (http.cookiejar.CookiePolicy の属性)
  • network (ipaddress.IPv4Interface の属性)
    • (ipaddress.IPv6Interface の属性)
  • Network News Transfer Protocol
  • network_address (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • new() (hashlib モジュール)
    • (hmac モジュール)
  • new-style class
  • new_alignment() (formatter.writer のメソッド)
  • new_child() (collections.ChainMap のメソッド)
  • new_class() (types モジュール)
  • new_compiler() (distutils.ccompiler モジュール)
  • new_event_loop() (asyncio モジュール)
    • (asyncio.AbstractEventLoopPolicy のメソッド)
  • new_font() (formatter.writer のメソッド)
  • new_margin() (formatter.writer のメソッド)
  • new_module() (imp モジュール)
  • new_panel() (curses.panel モジュール)
  • new_spacing() (formatter.writer のメソッド)
  • new_styles() (formatter.writer のメソッド)
  • newer() (distutils.dep_util モジュール)
  • newer_group() (distutils.dep_util モジュール)
  • newer_pairwise() (distutils.dep_util モジュール)
  • newgroups() (nntplib.NNTP のメソッド)
  • NEWLINE (token モジュール)
  • NEWLINE token, [1]
  • newlines (io.TextIOBase の属性)
  • newnews() (nntplib.NNTP のメソッド)
  • newpad() (curses モジュール)
  • NewType() (typing モジュール)
  • newwin() (curses モジュール)
  • next (2to3 fixer)
    • (pdb command)
  • next() (nntplib.NNTP のメソッド)
    • (tarfile.TarFile のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
    • (組み込み関数)
  • next_minus() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • next_plus() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • next_toward() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • nextfile() (fileinput モジュール)
  • nextkey() (dbm.gnu.gdbm のメソッド)
  • nextSibling (xml.dom.Node の属性)
  • ngettext() (gettext モジュール)
    • (gettext.GNUTranslations のメソッド)
    • (gettext.NullTranslations のメソッド)
  • nice() (os モジュール)
  • nis (モジュール)
  • NL (token モジュール)
  • nl() (curses モジュール)
  • nl_langinfo() (locale モジュール)
  • nlargest() (heapq モジュール)
  • nlst() (ftplib.FTP のメソッド)
  • NNTP
    • protocol
  • NNTP (nntplib のクラス)
  • nntp_implementation (nntplib.NNTP の属性)
  • NNTP_SSL (nntplib のクラス)
  • nntp_version (nntplib.NNTP の属性)
  • NNTPDataError
  • NNTPError
  • nntplib (モジュール)
  • NNTPPermanentError
  • NNTPProtocolError
  • NNTPReplyError
  • NNTPTemporaryError
  • no_proxy
  • no_tracing() (test.support モジュール)
  • no_type_check() (typing モジュール)
  • no_type_check_decorator() (typing モジュール)
  • nocbreak() (curses モジュール)
  • NoDataAllowedErr
  • node() (platform モジュール)
  • nodelay() (curses.window のメソッド)
  • nodeName (xml.dom.Node の属性)
  • NodeTransformer (ast のクラス)
  • nodeType (xml.dom.Node の属性)
  • nodeValue (xml.dom.Node の属性)
  • NodeVisitor (ast のクラス)
  • noecho() (curses モジュール)
  • NOEXPR (locale モジュール)
  • NoModificationAllowedErr
  • nonblock() (ossaudiodev.oss_audio_device のメソッド)
  • NonCallableMagicMock (unittest.mock のクラス)
  • NonCallableMock (unittest.mock のクラス)
  • None
    • オブジェクト, [1], [2]
  • None (Built-in object)
    • (組み込み変数)
  • nonl() (curses モジュール)
  • nonlocal
    • 文
  • nonzero (2to3 fixer)
  • noop() (imaplib.IMAP4 のメソッド)
    • (poplib.POP3 のメソッド)
  • NoOptionError
  • NOP (opcode)
  • noqiflush() (curses モジュール)
  • noraw() (curses モジュール)
  • NoReturn (typing モジュール)
  • NORMAL_PRIORITY_CLASS (subprocess モジュール)
  • normalize() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (locale モジュール)
    • (unicodedata モジュール)
    • (xml.dom.Node のメソッド)
  • NORMALIZE_WHITESPACE (doctest モジュール)
  • normalvariate() (random モジュール)
  • normcase() (os.path モジュール)
  • normpath() (os.path モジュール)
  • NoSectionError
  • NoSuchMailboxError
  • not
    • 演算子, [1]
  • not in
    • 演算子, [1], [2]
  • not_() (operator モジュール)
  • NotADirectoryError
  • notation
  • notationDecl() (xml.sax.handler.DTDHandler のメソッド)
  • NotationDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • notations (xml.dom.DocumentType の属性)
  • NotConnected
  • NoteBook (tkinter.tix のクラス)
  • Notebook (tkinter.ttk のクラス)
  • NotEmptyError
  • NOTEQUAL (token モジュール)
  • NotFoundErr
  • notify() (asyncio.Condition のメソッド)
    • (threading.Condition のメソッド)
  • notify_all() (asyncio.Condition のメソッド)
    • (threading.Condition のメソッド)
  • notimeout() (curses.window のメソッド)
  • NotImplemented
    • オブジェクト
  • NotImplemented (組み込み変数)
  • NotImplementedError
  • NotStandaloneHandler() (xml.parsers.expat.xmlparser のメソッド)
  • NotSupportedErr
  • NotSupportedError
  • noutrefresh() (curses.window のメソッド)
  • now() (datetime.datetime のクラスメソッド)
  • NSIG (signal モジュール)
  • nsmallest() (heapq モジュール)
  • NT_OFFSET (token モジュール)
  • NTEventLogHandler (logging.handlers のクラス)
  • ntohl() (socket モジュール)
  • ntohs() (socket モジュール)
  • ntransfercmd() (ftplib.FTP のメソッド)
  • null
    • operation, [1]
  • nullcontext() (contextlib モジュール)
  • NullFormatter (formatter のクラス)
  • NullHandler (logging のクラス)
  • NullImporter (imp のクラス)
  • NullTranslations (gettext のクラス)
  • NullWriter (formatter のクラス)
  • num_addresses (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • number
    • complex
    • floating point
  • Number (numbers のクラス)
  • NUMBER (token モジュール)
  • number_class() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • numbers (モジュール)
  • numerator (fractions.Fraction の属性)
    • (numbers.Rational の属性)
  • numeric
    • conversions
    • literals
    • object
    • types, operations on
    • オブジェクト, [1], [2], [3]
  • numeric literal
  • numeric() (unicodedata モジュール)
  • Numerical Python
  • numinput() (turtle モジュール)
  • numliterals (2to3 fixer)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – O

  • O_APPEND (os モジュール)
  • O_ASYNC (os モジュール)
  • O_BINARY (os モジュール)
  • O_CLOEXEC (os モジュール)
  • O_CREAT (os モジュール)
  • O_DIRECT (os モジュール)
  • O_DIRECTORY (os モジュール)
  • O_DSYNC (os モジュール)
  • O_EXCL (os モジュール)
  • O_EXLOCK (os モジュール)
  • O_NDELAY (os モジュール)
  • O_NOATIME (os モジュール)
  • O_NOCTTY (os モジュール)
  • O_NOFOLLOW (os モジュール)
  • O_NOINHERIT (os モジュール)
  • O_NONBLOCK (os モジュール)
  • O_PATH (os モジュール)
  • O_RANDOM (os モジュール)
  • O_RDONLY (os モジュール)
  • O_RDWR (os モジュール)
  • O_RSYNC (os モジュール)
  • O_SEQUENTIAL (os モジュール)
  • O_SHLOCK (os モジュール)
  • O_SHORT_LIVED (os モジュール)
  • O_SYNC (os モジュール)
  • O_TEMPORARY (os モジュール)
  • O_TEXT (os モジュール)
  • O_TMPFILE (os モジュール)
  • O_TRUNC (os モジュール)
  • O_WRONLY (os モジュール)
  • obj (memoryview の属性)
  • object, [1]
    • code, [1], [2], [3]
    • deallocation
    • finalization
    • immutable, [1]
    • numeric
  • object (UnicodeError の属性)
    • (組み込みクラス)
  • object.__slots__ (組み込み変数)
  • object_filenames() (distutils.ccompiler.CCompiler のメソッド)
  • objects
    • comparing
    • flattening
    • marshalling
    • persistent
    • pickling
    • serializing
  • obufcount() (ossaudiodev.oss_audio_device のメソッド)
  • obuffree() (ossaudiodev.oss_audio_device のメソッド)
  • oct() (組み込み関数)
  • octal
    • literals
  • octal literal
  • octdigits (string モジュール)
  • offset (traceback.TracebackException の属性)
    • (xml.parsers.expat.ExpatError の属性)
  • OK (curses モジュール)
  • old_value (contextvars.contextvars.Token.Token の属性)
  • OleDLL (ctypes のクラス)
  • onclick() (turtle モジュール), [1]
  • ondrag() (turtle モジュール)
  • onecmd() (cmd.Cmd のメソッド)
  • onkey() (turtle モジュール)
  • onkeypress() (turtle モジュール)
  • onkeyrelease() (turtle モジュール)
  • onrelease() (turtle モジュール)
  • onscreenclick() (turtle モジュール)
  • ontimer() (turtle モジュール)
  • OP (token モジュール)
  • OP_ALL (ssl モジュール)
  • OP_CIPHER_SERVER_PREFERENCE (ssl モジュール)
  • OP_ENABLE_MIDDLEBOX_COMPAT (ssl モジュール)
  • OP_NO_COMPRESSION (ssl モジュール)
  • OP_NO_RENEGOTIATION (ssl モジュール)
  • OP_NO_SSLv2 (ssl モジュール)
  • OP_NO_SSLv3 (ssl モジュール)
  • OP_NO_TICKET (ssl モジュール)
  • OP_NO_TLSv1 (ssl モジュール)
  • OP_NO_TLSv1_1 (ssl モジュール)
  • OP_NO_TLSv1_2 (ssl モジュール)
  • OP_NO_TLSv1_3 (ssl モジュール)
  • OP_SINGLE_DH_USE (ssl モジュール)
  • OP_SINGLE_ECDH_USE (ssl モジュール)
  • open
    • 組み込み関数, [1]
  • open() (aifc モジュール)
    • (bz2 モジュール)
    • (codecs モジュール)
    • (dbm モジュール)
    • (dbm.dumb モジュール)
    • (dbm.gnu モジュール)
    • (dbm.ndbm モジュール)
    • (distutils.text_file.TextFile のメソッド)
    • (gzip モジュール)
    • (imaplib.IMAP4 のメソッド)
    • (io モジュール)
    • (lzma モジュール)
    • (os モジュール)
    • (ossaudiodev モジュール)
    • (pathlib.Path のメソッド)
    • (pipes.Template のメソッド)
    • (shelve モジュール)
    • (sunau モジュール)
    • (tarfile モジュール)
    • (tarfile.TarFile のクラスメソッド)
    • (telnetlib.Telnet のメソッド)
    • (tokenize モジュール)
    • (urllib.request.OpenerDirector のメソッド)
    • (urllib.request.URLopener のメソッド)
    • (wave モジュール)
    • (webbrowser モジュール)
    • (webbrowser.controller のメソッド)
    • (zipfile.ZipFile のメソッド)
    • (組み込み関数)
  • open_binary() (importlib.resources モジュール)
  • open_connection() (asyncio モジュール)
  • open_new() (webbrowser モジュール)
    • (webbrowser.controller のメソッド)
  • open_new_tab() (webbrowser モジュール)
    • (webbrowser.controller のメソッド)
  • open_osfhandle() (msvcrt モジュール)
  • open_resource() (importlib.abc.ResourceReader のメソッド)
  • open_text() (importlib.resources モジュール)
  • open_unix_connection() (asyncio モジュール)
  • open_unknown() (urllib.request.URLopener のメソッド)
  • open_urlresource() (test.support モジュール)
  • OpenDatabase() (msilib モジュール)
  • OpenerDirector (urllib.request のクラス)
  • openfp() (sunau モジュール)
    • (wave モジュール)
  • OpenKey() (winreg モジュール)
  • OpenKeyEx() (winreg モジュール)
  • openlog() (syslog モジュール)
  • openmixer() (ossaudiodev モジュール)
  • openpty() (os モジュール)
    • (pty モジュール)
  • OpenSSL
    • (use in module hashlib)
    • (use in module ssl)
  • OPENSSL_VERSION (ssl モジュール)
  • OPENSSL_VERSION_INFO (ssl モジュール)
  • OPENSSL_VERSION_NUMBER (ssl モジュール)
  • OpenView() (msilib.Database のメソッド)
  • operation
    • Boolean
    • binary arithmetic
    • binary bitwise
    • concatenation
    • null, [1]
    • power
    • repetition
    • shifting
    • slice
    • subscript
    • unary arithmetic
    • unary bitwise
  • OperationalError
  • operations
    • Boolean, [1]
    • bitwise
    • masking
    • shifting
  • operations on
    • dictionary type
    • integer types
    • list type
    • mapping types
    • numeric types
    • sequence types, [1]
  • operator
    • + (plus), [1], [2]
    • - (minus), [1], [2]
    • comparison
    • overloading
    • precedence
    • ternary
  • operator (2to3 fixer)
    • (モジュール)
  • operators
  • opmap (dis モジュール)
  • opname (dis モジュール)
  • optim_args_from_interpreter_flags() (test.support モジュール)
  • optimize() (pickletools モジュール)
  • OPTIMIZED_BYTECODE_SUFFIXES (importlib.machinery モジュール)
  • Optional (typing モジュール)
  • OptionGroup (optparse のクラス)
  • OptionMenu (tkinter.tix のクラス)
  • OptionParser (optparse のクラス)
  • options (doctest.Example の属性)
  • Options (ssl のクラス)
  • options (ssl.SSLContext の属性)
  • options() (configparser.ConfigParser のメソッド)
  • optionxform() (configparser.ConfigParser のメソッド), [1]
  • optparse (モジュール)
  • or
    • bitwise
    • exclusive
    • inclusive
    • 演算子, [1], [2]
  • or_() (operator モジュール)
  • ord
    • 組み込み関数
  • ord() (組み込み関数)
  • order
    • evaluation
  • ordered_attributes (xml.parsers.expat.xmlparser の属性)
  • OrderedDict (collections のクラス)
    • (typing のクラス)
  • origin (importlib.machinery.ModuleSpec の属性)
  • origin_req_host (urllib.request.Request の属性)
  • origin_server (wsgiref.handlers.BaseHandler の属性)
  • os
    • モジュール
  • os (モジュール)
  • os.path (モジュール)
  • os_environ (wsgiref.handlers.BaseHandler の属性)
  • OSError
  • ossaudiodev (モジュール)
  • OSSAudioError
  • outfile
    • json.tool コマンドラインオプション
  • output
    • standard
  • output (subprocess.CalledProcessError の属性)
    • (subprocess.TimeoutExpired の属性)
    • (unittest.TestCase の属性)
  • output() (http.cookies.BaseCookie のメソッド)
    • (http.cookies.Morsel のメソッド)
  • output_charset (email.charset.Charset の属性)
  • output_charset() (gettext.NullTranslations のメソッド)
  • output_codec (email.charset.Charset の属性)
  • output_difference() (doctest.OutputChecker のメソッド)
  • OutputChecker (doctest のクラス)
  • OutputString() (http.cookies.Morsel のメソッド)
  • over() (nntplib.NNTP のメソッド)
  • Overflow (decimal のクラス)
  • OverflowError
    • (built-in exception), [1], [2], [3], [4], [5]
  • overlaps() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • overlay() (curses.window のメソッド)
  • overload() (typing モジュール)
  • overloading
    • operator
  • overwrite() (curses.window のメソッド)
  • owner() (pathlib.Path のメソッド)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – P

  • p (pdb command)
  • P_ALL (os モジュール)
  • P_DETACH (os モジュール)
  • P_NOWAIT (os モジュール)
  • P_NOWAITO (os モジュール)
  • P_OVERLAY (os モジュール)
  • P_PGID (os モジュール)
  • P_PID (os モジュール)
  • P_WAIT (os モジュール)
  • pack() (mailbox.MH のメソッド)
    • (struct モジュール)
    • (struct.Struct のメソッド)
  • pack_array() (xdrlib.Packer のメソッド)
  • pack_bytes() (xdrlib.Packer のメソッド)
  • pack_double() (xdrlib.Packer のメソッド)
  • pack_farray() (xdrlib.Packer のメソッド)
  • pack_float() (xdrlib.Packer のメソッド)
  • pack_fopaque() (xdrlib.Packer のメソッド)
  • pack_fstring() (xdrlib.Packer のメソッド)
  • pack_into() (struct モジュール)
    • (struct.Struct のメソッド)
  • pack_list() (xdrlib.Packer のメソッド)
  • pack_opaque() (xdrlib.Packer のメソッド)
  • pack_string() (xdrlib.Packer のメソッド)
  • package, [1], [2]
    • namespace
    • portion
    • regular
  • Package (importlib.resources モジュール)
  • package variable
    • __all__
  • packed (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv6Address の属性)
  • Packer (xdrlib のクラス)
  • packing
    • binary data
  • packing (widgets)
  • PAGER
  • pair_content() (curses モジュール)
  • pair_number() (curses モジュール)
  • PanedWindow (tkinter.tix のクラス)
  • parameter
    • call semantics
    • difference from argument
    • function definition
    • value, default
  • Parameter (inspect のクラス)
  • ParameterizedMIMEHeader (email.headerregistry のクラス)
  • parameters (inspect.Signature の属性)
  • params (email.headerregistry.ParameterizedMIMEHeader の属性)
  • pardir (os モジュール)
  • paren (2to3 fixer)
  • parent (importlib.machinery.ModuleSpec の属性)
    • (pyclbr.Class の属性)
    • (pyclbr.Function の属性)
    • (urllib.request.BaseHandler の属性)
  • parent() (tkinter.ttk.Treeview のメソッド)
  • parenthesized form
  • parentNode (xml.dom.Node の属性)
  • parents (collections.ChainMap の属性)
  • paretovariate() (random モジュール)
  • parse() (ast モジュール)
    • (cgi モジュール)
    • (doctest.DocTestParser のメソッド)
    • (email.parser.BytesParser のメソッド)
    • (email.parser.Parser のメソッド)
    • (string.Formatter のメソッド)
    • (urllib.robotparser.RobotFileParser のメソッド)
    • (xml.dom.minidom モジュール)
    • (xml.dom.pulldom モジュール)
    • (xml.etree.ElementTree モジュール)
    • (xml.etree.ElementTree.ElementTree のメソッド)
  • Parse() (xml.parsers.expat.xmlparser のメソッド)
  • parse() (xml.sax モジュール)
    • (xml.sax.xmlreader.XMLReader のメソッド)
  • parse_and_bind() (readline モジュール)
  • parse_args() (argparse.ArgumentParser のメソッド)
  • PARSE_COLNAMES (sqlite3 モジュール)
  • parse_config_h() (sysconfig モジュール)
  • PARSE_DECLTYPES (sqlite3 モジュール)
  • parse_header() (cgi モジュール)
  • parse_intermixed_args() (argparse.ArgumentParser のメソッド)
  • parse_known_args() (argparse.ArgumentParser のメソッド)
  • parse_known_intermixed_args() (argparse.ArgumentParser のメソッド)
  • parse_multipart() (cgi モジュール)
  • parse_qs() (cgi モジュール)
    • (urllib.parse モジュール)
  • parse_qsl() (cgi モジュール)
    • (urllib.parse モジュール)
  • parseaddr() (email.utils モジュール)
  • parsebytes() (email.parser.BytesParser のメソッド)
  • parsedate() (email.utils モジュール)
  • parsedate_to_datetime() (email.utils モジュール)
  • parsedate_tz() (email.utils モジュール)
  • ParseError (xml.etree.ElementTree のクラス)
  • ParseFile() (xml.parsers.expat.xmlparser のメソッド)
  • ParseFlags() (imaplib モジュール)
  • parser
  • Parser (email.parser のクラス)
  • parser (モジュール)
  • ParserCreate() (xml.parsers.expat モジュール)
  • ParserError
  • ParseResult (urllib.parse のクラス)
  • ParseResultBytes (urllib.parse のクラス)
  • parsestr() (email.parser.Parser のメソッド)
  • parseString() (xml.dom.minidom モジュール)
    • (xml.dom.pulldom モジュール)
    • (xml.sax モジュール)
  • parsing
    • Python source code
    • URL
  • ParsingError
  • partial (asyncio.IncompleteReadError の属性)
  • partial() (functools モジュール)
    • (imaplib.IMAP4 のメソッド)
  • partialmethod (functools のクラス)
  • parties (threading.Barrier の属性)
  • partition() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • pass
    • 文
  • pass_() (poplib.POP3 のメソッド)
  • Paste
  • patch() (test.support モジュール)
    • (unittest.mock モジュール)
  • patch.dict() (unittest.mock モジュール)
  • patch.multiple() (unittest.mock モジュール)
  • patch.object() (unittest.mock モジュール)
  • patch.stopall() (unittest.mock モジュール)
  • PATH, [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], [31], [32], [33], [34], [35]
  • path
    • configuration file
    • hooks
    • module search, [1], [2], [3], [4], [5], [6], [7]
    • operations, [1]
  • path (http.cookiejar.Cookie の属性)
    • (http.server.BaseHTTPRequestHandler の属性)
    • (importlib.abc.FileLoader の属性)
    • (importlib.machinery.ExtensionFileLoader の属性)
    • (importlib.machinery.FileFinder の属性)
    • (importlib.machinery.SourceFileLoader の属性)
    • (importlib.machinery.SourcelessFileLoader の属性)
    • (in module sys), [1], [2], [3]
    • (os.DirEntry の属性)
  • Path (pathlib のクラス)
  • path (sys モジュール)
  • path based finder, [1]
  • Path browser
  • path entry
  • path entry finder
  • path entry hook
  • path hooks
  • path() (importlib.resources モジュール)
  • path-like object
  • path_hook() (importlib.machinery.FileFinder のクラスメソッド)
  • path_hooks (sys モジュール)
  • path_importer_cache (sys モジュール)
  • path_mtime() (importlib.abc.SourceLoader のメソッド)
  • path_return_ok() (http.cookiejar.CookiePolicy のメソッド)
  • path_stats() (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.SourceFileLoader のメソッド)
  • pathconf() (os モジュール)
  • pathconf_names (os モジュール)
  • PathEntryFinder (importlib.abc のクラス)
  • PATHEXT, [1], [2]
  • PathFinder (importlib.machinery のクラス)
  • pathlib (モジュール)
  • PathLike (os のクラス)
  • pathname2url() (urllib.request モジュール)
  • pathsep (os モジュール)
  • pattern (re.error の属性)
    • (re.Pattern の属性)
  • Pattern (typing のクラス)
  • pause() (signal モジュール)
  • pause_reading() (asyncio.ReadTransport のメソッド)
  • pause_writing() (asyncio.BaseProtocol のメソッド)
  • PAX_FORMAT (tarfile モジュール)
  • pax_headers (tarfile.TarFile の属性)
    • (tarfile.TarInfo の属性)
  • pbkdf2_hmac() (hashlib モジュール)
  • pd() (turtle モジュール)
  • Pdb (class in pdb)
    • (pdb のクラス)
  • pdb (モジュール)
  • peek() (bz2.BZ2File のメソッド)
    • (gzip.GzipFile のメソッド)
    • (io.BufferedReader のメソッド)
    • (lzma.LZMAFile のメソッド)
    • (weakref.finalize のメソッド)
  • peer (smtpd.SMTPChannel の属性)
  • PEM_cert_to_DER_cert() (ssl モジュール)
  • pen() (turtle モジュール)
  • pencolor() (turtle モジュール)
  • pending (ssl.MemoryBIO の属性)
  • pending() (ssl.SSLSocket のメソッド)
  • PendingDeprecationWarning
  • pendown() (turtle モジュール)
  • pensize() (turtle モジュール)
  • penup() (turtle モジュール)
  • PEP
  • PERCENT (token モジュール)
  • PERCENTEQUAL (token モジュール)
  • perf_counter() (time モジュール)
  • perf_counter_ns() (time モジュール)
  • Performance
  • PermissionError
  • permutations() (itertools モジュール)
  • Persist() (msilib.SummaryInformation のメソッド)
  • persistence
  • persistent
    • objects
  • persistent_id (pickle protocol)
  • persistent_id() (pickle.Pickler のメソッド)
  • persistent_load (pickle protocol)
  • persistent_load() (pickle.Unpickler のメソッド)
  • PF_CAN (socket モジュール)
  • PF_PACKET (socket モジュール)
  • PF_RDS (socket モジュール)
  • pformat() (pprint モジュール)
    • (pprint.PrettyPrinter のメソッド)
  • PGO (test.support モジュール)
  • phase() (cmath モジュール)
  • Philbrick, Geoff
  • physical line, [1], [2]
  • pi (cmath モジュール)
    • (math モジュール)
  • pickle
    • モジュール, [1], [2], [3]
  • pickle (モジュール)
  • pickle() (copyreg モジュール)
  • PickleError
  • Pickler (pickle のクラス)
  • pickletools (モジュール)
  • pickletools コマンドラインオプション
    • -a, --annotate
    • -l, --indentlevel=<num>
    • -m, --memo
    • -o, --output=<file>
    • -p, --preamble=<preamble>
  • pickling
    • objects
  • PicklingError
  • pid (asyncio.asyncio.subprocess.Process の属性)
    • (multiprocessing.Process の属性)
    • (subprocess.Popen の属性)
  • PIPE (subprocess モジュール)
  • Pipe() (multiprocessing モジュール)
  • pipe() (os モジュール)
  • pipe2() (os モジュール)
  • PIPE_BUF (select モジュール)
  • pipe_connection_lost() (asyncio.SubprocessProtocol のメソッド)
  • pipe_data_received() (asyncio.SubprocessProtocol のメソッド)
  • PIPE_MAX_SIZE (test.support モジュール)
  • pipes (モジュール)
  • PKG_DIRECTORY (imp モジュール)
  • pkgutil (モジュール)
  • placeholder (textwrap.TextWrapper の属性)
  • PLAT
  • platform (in module sys)
    • (sys モジュール)
    • (モジュール)
  • platform() (platform モジュール)
  • PlaySound() (winsound モジュール)
  • plist
    • file
  • plistlib (モジュール)
  • plock() (os モジュール)
  • plus
  • PLUS (token モジュール)
  • plus() (decimal.Context のメソッド)
  • PLUSEQUAL (token モジュール)
  • pm() (pdb モジュール)
  • POINTER() (ctypes モジュール)
  • pointer() (ctypes モジュール)
  • polar() (cmath モジュール)
  • Policy (email.policy のクラス)
  • poll() (multiprocessing.connection.Connection のメソッド)
    • (select モジュール)
    • (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.poll のメソッド)
    • (subprocess.Popen のメソッド)
  • PollSelector (selectors のクラス)
  • Pool (multiprocessing.pool のクラス)
  • pop() (array.array のメソッド)
    • (collections.deque のメソッド)
    • (dict のメソッド)
    • (frozenset のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (sequence method)
  • POP3
    • protocol
  • POP3 (poplib のクラス)
  • POP3_SSL (poplib のクラス)
  • pop_alignment() (formatter.formatter のメソッド)
  • pop_all() (contextlib.ExitStack のメソッド)
  • POP_BLOCK (opcode)
  • POP_EXCEPT (opcode)
  • pop_font() (formatter.formatter のメソッド)
  • POP_JUMP_IF_FALSE (opcode)
  • POP_JUMP_IF_TRUE (opcode)
  • pop_margin() (formatter.formatter のメソッド)
  • pop_source() (shlex.shlex のメソッド)
  • pop_style() (formatter.formatter のメソッド)
  • POP_TOP (opcode)
  • Popen (subprocess のクラス)
  • popen() (in module os), [1]
    • (os モジュール)
    • (platform モジュール)
  • popitem() (collections.OrderedDict のメソッド)
    • (dict のメソッド)
    • (mailbox.Mailbox のメソッド)
  • popleft() (collections.deque のメソッド)
  • poplib (モジュール)
  • PopupMenu (tkinter.tix のクラス)
  • port (http.cookiejar.Cookie の属性)
  • port_specified (http.cookiejar.Cookie の属性)
  • portion
    • package
  • pos (json.JSONDecodeError の属性)
    • (re.Match の属性)
    • (re.error の属性)
  • pos() (operator モジュール)
    • (turtle モジュール)
  • position (xml.etree.ElementTree.ParseError の属性)
  • position() (turtle モジュール)
  • positional argument (位置引数)
  • POSIX
    • I/O control
    • threads
  • posix (モジュール)
  • POSIX_FADV_DONTNEED (os モジュール)
  • POSIX_FADV_NOREUSE (os モジュール)
  • POSIX_FADV_NORMAL (os モジュール)
  • POSIX_FADV_RANDOM (os モジュール)
  • POSIX_FADV_SEQUENTIAL (os モジュール)
  • POSIX_FADV_WILLNEED (os モジュール)
  • posix_fadvise() (os モジュール)
  • posix_fallocate() (os モジュール)
  • POSIXLY_CORRECT
  • PosixPath (pathlib のクラス)
  • post() (nntplib.NNTP のメソッド)
    • (ossaudiodev.oss_audio_device のメソッド)
  • post_handshake_auth (ssl.SSLContext の属性)
  • post_mortem() (pdb モジュール)
  • post_setup() (venv.EnvBuilder のメソッド)
  • postcmd() (cmd.Cmd のメソッド)
  • postloop() (cmd.Cmd のメソッド)
  • pow
    • 組み込み関数, [1], [2], [3], [4], [5]
  • pow() (math モジュール)
    • (operator モジュール)
    • (組み込み関数)
  • power
    • operation
  • power() (decimal.Context のメソッド)
  • pp (pdb command)
  • pprint (モジュール)
  • pprint() (pprint モジュール)
    • (pprint.PrettyPrinter のメソッド)
  • prcal() (calendar モジュール)
  • pread() (os モジュール)
  • preadv() (os モジュール)
  • preamble (email.message.EmailMessage の属性)
    • (email.message.Message の属性)
  • precedence
    • operator
  • precmd() (cmd.Cmd のメソッド)
  • prefix, [1], [2], [3]
  • PREFIX (distutils.sysconfig モジュール)
  • prefix (sys モジュール)
    • (xml.dom.Attr の属性)
    • (xml.dom.Node の属性)
    • (zipimport.zipimporter の属性)
  • PREFIXES (site モジュール)
  • prefixlen (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Network の属性)
  • preloop() (cmd.Cmd のメソッド)
  • prepare() (logging.handlers.QueueHandler のメソッド)
    • (logging.handlers.QueueListener のメソッド)
  • prepare_class() (types モジュール)
  • prepare_input_source() (xml.sax.saxutils モジュール)
  • prepend() (pipes.Template のメソッド)
  • preprocess() (distutils.ccompiler.CCompiler のメソッド)
  • PrettyPrinter (pprint のクラス)
  • prev() (tkinter.ttk.Treeview のメソッド)
  • previousSibling (xml.dom.Node の属性)
  • primary
  • print
    • 組み込み関数
  • print (2to3 fixer)
  • print() (built-in function)
    • __str__() (object method)
  • print() (組み込み関数)
  • print_callees() (pstats.Stats のメソッド)
  • print_callers() (pstats.Stats のメソッド)
  • print_directory() (cgi モジュール)
  • print_environ() (cgi モジュール)
  • print_environ_usage() (cgi モジュール)
  • print_exc() (timeit.Timer のメソッド)
    • (traceback モジュール)
  • print_exception() (traceback モジュール)
  • PRINT_EXPR (opcode)
  • print_form() (cgi モジュール)
  • print_help() (argparse.ArgumentParser のメソッド)
  • print_last() (traceback モジュール)
  • print_stack() (asyncio.Task のメソッド)
    • (traceback モジュール)
  • print_stats() (profile.Profile のメソッド)
    • (pstats.Stats のメソッド)
  • print_tb() (traceback モジュール)
  • print_usage() (argparse.ArgumentParser のメソッド)
    • (optparse.OptionParser のメソッド)
  • print_version() (optparse.OptionParser のメソッド)
  • printable (string モジュール)
  • printdir() (zipfile.ZipFile のメソッド)
  • printf-style formatting, [1]
  • PRIO_PGRP (os モジュール)
  • PRIO_PROCESS (os モジュール)
  • PRIO_USER (os モジュール)
  • PriorityQueue (asyncio のクラス)
    • (queue のクラス)
  • private
    • names
  • prlimit() (resource モジュール)
  • prmonth() (calendar モジュール)
    • (calendar.TextCalendar のメソッド)
  • ProactorEventLoop (asyncio のクラス)
  • procedure
    • call
  • process
    • group, [1]
    • id
    • id of parent
    • killing, [1]
    • scheduling priority, [1]
    • signalling, [1]
  • Process (multiprocessing のクラス)
  • process() (logging.LoggerAdapter のメソッド)
  • process_exited() (asyncio.SubprocessProtocol のメソッド)
  • process_message() (smtpd.SMTPServer のメソッド)
  • process_request() (socketserver.BaseServer のメソッド)
  • process_time() (time モジュール)
  • process_time_ns() (time モジュール)
  • process_tokens() (tabnanny モジュール)
  • ProcessError
  • processes, light-weight
  • ProcessingInstruction() (xml.etree.ElementTree モジュール)
  • processingInstruction() (xml.sax.handler.ContentHandler のメソッド)
  • ProcessingInstructionHandler() (xml.parsers.expat.xmlparser のメソッド)
  • ProcessLookupError
  • processor time, [1], [2]
  • processor() (platform モジュール)
  • ProcessPoolExecutor (concurrent.futures のクラス)
  • product() (itertools モジュール)
  • Profile (profile のクラス)
  • profile (モジュール)
  • profile function, [1], [2]
  • profiler, [1]
  • profiling, deterministic
  • program
  • ProgrammingError
  • Progressbar (tkinter.ttk のクラス)
  • prompt (cmd.Cmd の属性)
  • prompt_user_passwd() (urllib.request.FancyURLopener のメソッド)
  • prompts, interpreter
  • propagate (logging.Logger の属性)
  • property (組み込みクラス)
  • property list
  • property_declaration_handler (xml.sax.handler モジュール)
  • property_dom_node (xml.sax.handler モジュール)
  • property_lexical_handler (xml.sax.handler モジュール)
  • property_xml_string (xml.sax.handler モジュール)
  • PropertyMock (unittest.mock のクラス)
  • prot_c() (ftplib.FTP_TLS のメソッド)
  • prot_p() (ftplib.FTP_TLS のメソッド)
  • proto (socket.socket の属性)
  • protocol
    • CGI
    • FTP, [1]
    • HTTP, [1], [2], [3], [4], [5]
    • IMAP4
    • IMAP4_SSL
    • IMAP4_stream
    • NNTP
    • POP3
    • SMTP
    • Telnet
    • context management
    • copy
    • iterator
  • Protocol (asyncio のクラス)
  • protocol (ssl.SSLContext の属性)
  • PROTOCOL_SSLv2 (ssl モジュール)
  • PROTOCOL_SSLv23 (ssl モジュール)
  • PROTOCOL_SSLv3 (ssl モジュール)
  • PROTOCOL_TLS (ssl モジュール)
  • PROTOCOL_TLS_CLIENT (ssl モジュール)
  • PROTOCOL_TLS_SERVER (ssl モジュール)
  • PROTOCOL_TLSv1 (ssl モジュール)
  • PROTOCOL_TLSv1_1 (ssl モジュール)
  • PROTOCOL_TLSv1_2 (ssl モジュール)
  • protocol_version (http.server.BaseHTTPRequestHandler の属性)
  • PROTOCOL_VERSION (imaplib.IMAP4 の属性)
  • ProtocolError (xmlrpc.client のクラス)
  • provisional API
  • provisional package
  • proxy() (weakref モジュール)
  • proxyauth() (imaplib.IMAP4 のメソッド)
  • ProxyBasicAuthHandler (urllib.request のクラス)
  • ProxyDigestAuthHandler (urllib.request のクラス)
  • ProxyHandler (urllib.request のクラス)
  • ProxyType (weakref モジュール)
  • ProxyTypes (weakref モジュール)
  • pryear() (calendar.TextCalendar のメソッド)
  • ps1 (sys モジュール)
  • ps2 (sys モジュール)
  • pstats (モジュール)
  • pstdev() (statistics モジュール)
  • pthread_getcpuclockid() (time モジュール)
  • pthread_kill() (signal モジュール)
  • pthread_sigmask() (signal モジュール)
  • pthreads
  • pty
    • モジュール
  • pty (モジュール)
  • pu() (turtle モジュール)
  • publicId (xml.dom.DocumentType の属性)
  • PullDom (xml.dom.pulldom のクラス)
  • punctuation (string モジュール)
  • punctuation_chars (shlex.shlex の属性)
  • PurePath (pathlib のクラス)
  • PurePath.anchor (pathlib モジュール)
  • PurePath.drive (pathlib モジュール)
  • PurePath.name (pathlib モジュール)
  • PurePath.parent (pathlib モジュール)
  • PurePath.parents (pathlib モジュール)
  • PurePath.parts (pathlib モジュール)
  • PurePath.root (pathlib モジュール)
  • PurePath.stem (pathlib モジュール)
  • PurePath.suffix (pathlib モジュール)
  • PurePath.suffixes (pathlib モジュール)
  • PurePosixPath (pathlib のクラス)
  • PureProxy (smtpd のクラス)
  • PureWindowsPath (pathlib のクラス)
  • purge() (re モジュール)
  • Purpose.CLIENT_AUTH (ssl モジュール)
  • Purpose.SERVER_AUTH (ssl モジュール)
  • push() (asynchat.async_chat のメソッド)
    • (code.InteractiveConsole のメソッド)
    • (contextlib.ExitStack のメソッド)
  • push_alignment() (formatter.formatter のメソッド)
  • push_async_callback() (contextlib.AsyncExitStack のメソッド)
  • push_async_exit() (contextlib.AsyncExitStack のメソッド)
  • push_font() (formatter.formatter のメソッド)
  • push_margin() (formatter.formatter のメソッド)
  • push_source() (shlex.shlex のメソッド)
  • push_style() (formatter.formatter のメソッド)
  • push_token() (shlex.shlex のメソッド)
  • push_with_producer() (asynchat.async_chat のメソッド)
  • pushbutton() (msilib.Dialog のメソッド)
  • put() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (multiprocessing.SimpleQueue のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
  • put_nowait() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
  • putch() (msvcrt モジュール)
  • putenv() (os モジュール)
  • putheader() (http.client.HTTPConnection のメソッド)
  • putp() (curses モジュール)
  • putrequest() (http.client.HTTPConnection のメソッド)
  • putwch() (msvcrt モジュール)
  • putwin() (curses.window のメソッド)
  • pvariance() (statistics モジュール)
  • pwd
    • モジュール
  • pwd (モジュール)
  • pwd() (ftplib.FTP のメソッド)
  • pwrite() (os モジュール)
  • pwritev() (os モジュール)
  • Py_ABS (C のマクロ)
  • Py_AddPendingCall (C の関数)
  • Py_AddPendingCall()
  • Py_AtExit (C の関数)
  • Py_BEGIN_ALLOW_THREADS
    • (C のマクロ)
  • Py_BLOCK_THREADS (C のマクロ)
  • Py_buffer (C のデータ型)
  • Py_buffer.buf (C のメンバ変数)
  • Py_buffer.format (C のメンバ変数)
  • Py_buffer.internal (C のメンバ変数)
  • Py_buffer.itemsize (C のメンバ変数)
  • Py_buffer.len (C のメンバ変数)
  • Py_buffer.ndim (C のメンバ変数)
  • Py_buffer.obj (C のメンバ変数)
  • Py_buffer.readonly (C のメンバ変数)
  • Py_buffer.shape (C のメンバ変数)
  • Py_buffer.strides (C のメンバ変数)
  • Py_buffer.suboffsets (C のメンバ変数)
  • Py_BuildValue (C の関数)
  • Py_BytesWarningFlag (C の変数)
  • Py_CHARMASK (C のマクロ)
  • Py_CLEAR (C の関数)
  • py_compile (モジュール)
  • PY_COMPILED (imp モジュール)
  • Py_CompileString (C の関数)
  • Py_CompileString(), [1], [2]
  • Py_CompileStringExFlags (C の関数)
  • Py_CompileStringFlags (C の関数)
  • Py_CompileStringObject (C の関数)
  • Py_complex (C のデータ型)
  • Py_DebugFlag (C の変数)
  • Py_DecodeLocale (C の関数)
  • Py_DECREF (C の関数)
  • Py_DECREF()
  • Py_DontWriteBytecodeFlag (C の変数)
  • Py_Ellipsis (C の変数)
  • Py_EncodeLocale (C の関数)
  • Py_END_ALLOW_THREADS
    • (C のマクロ)
  • Py_EndInterpreter (C の関数)
  • Py_EnterRecursiveCall (C の関数)
  • Py_eval_input (C の変数)
  • Py_Exit (C の関数)
  • Py_False (C の変数)
  • Py_FatalError (C の関数)
  • Py_FatalError()
  • Py_FdIsInteractive (C の関数)
  • Py_file_input (C の変数)
  • Py_Finalize (C の関数)
  • Py_FinalizeEx (C の関数)
  • Py_FinalizeEx(), [1], [2], [3], [4]
  • PY_FROZEN (imp モジュール)
  • Py_FrozenFlag (C の変数)
  • Py_GetBuildInfo (C の関数)
  • Py_GetCompiler (C の関数)
  • Py_GetCopyright (C の関数)
  • Py_GETENV (C のマクロ)
  • Py_GetExecPrefix (C の関数)
  • Py_GetExecPrefix()
  • Py_GetPath (C の関数)
  • Py_GetPath(), [1], [2]
  • Py_GetPlatform (C の関数)
  • Py_GetPrefix (C の関数)
  • Py_GetPrefix()
  • Py_GetProgramFullPath (C の関数)
  • Py_GetProgramFullPath()
  • Py_GetProgramName (C の関数)
  • Py_GetPythonHome (C の関数)
  • Py_GetVersion (C の関数)
  • Py_HashRandomizationFlag (C の変数)
  • Py_IgnoreEnvironmentFlag (C の変数)
  • Py_INCREF (C の関数)
  • Py_INCREF()
  • Py_Initialize (C の関数)
  • Py_Initialize(), [1], [2], [3]
  • Py_InitializeEx (C の関数)
  • Py_InspectFlag (C の変数)
  • Py_InteractiveFlag (C の変数)
  • Py_IsInitialized (C の関数)
  • Py_IsInitialized()
  • Py_IsolatedFlag (C の変数)
  • Py_LeaveRecursiveCall (C の関数)
  • Py_LegacyWindowsFSEncodingFlag (C の変数)
  • Py_LegacyWindowsStdioFlag (C の変数)
  • Py_Main (C の関数)
  • Py_MAX (C のマクロ)
  • Py_MEMBER_SIZE (C のマクロ)
  • Py_MIN (C のマクロ)
  • Py_mod_create (C の変数)
  • Py_mod_exec (C の変数)
  • Py_NewInterpreter (C の関数)
  • Py_None (C の変数)
  • Py_NoSiteFlag (C の変数)
  • Py_NotImplemented (C の変数)
  • Py_NoUserSiteDirectory (C の変数)
  • py_object (ctypes のクラス)
  • Py_OptimizeFlag (C の変数)
  • Py_PRINT_RAW
  • Py_QuietFlag (C の変数)
  • Py_REFCNT (C のマクロ)
  • Py_ReprEnter (C の関数)
  • Py_ReprLeave (C の関数)
  • Py_RETURN_FALSE (C のマクロ)
  • Py_RETURN_NONE (C のマクロ)
  • Py_RETURN_NOTIMPLEMENTED (C のマクロ)
  • Py_RETURN_RICHCOMPARE (C の関数)
  • Py_RETURN_TRUE (C のマクロ)
  • Py_SetPath (C の関数)
  • Py_SetPath()
  • Py_SetProgramName (C の関数)
  • Py_SetProgramName(), [1], [2], [3]
  • Py_SetPythonHome (C の関数)
  • Py_SetStandardStreamEncoding (C の関数)
  • Py_single_input (C の変数)
  • Py_SIZE (C のマクロ)
  • PY_SOURCE (imp モジュール)
  • PY_SSIZE_T_MAX
  • Py_STRINGIFY (C のマクロ)
  • Py_TPFLAGS_BASE_EXC_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_BASETYPE (組み込み変数)
  • Py_TPFLAGS_BYTES_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_DEFAULT (組み込み変数)
  • Py_TPFLAGS_DICT_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_HAVE_FINALIZE (組み込み変数)
  • Py_TPFLAGS_HAVE_GC (組み込み変数)
  • Py_TPFLAGS_HEAPTYPE (組み込み変数)
  • Py_TPFLAGS_LIST_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_LONG_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_READY (組み込み変数)
  • Py_TPFLAGS_READYING (組み込み変数)
  • Py_TPFLAGS_TUPLE_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_TYPE_SUBCLASS (組み込み変数)
  • Py_TPFLAGS_UNICODE_SUBCLASS (組み込み変数)
  • Py_tracefunc (C のデータ型)
  • Py_True (C の変数)
  • Py_tss_NEEDS_INIT (C のマクロ)
  • Py_tss_t (C のデータ型)
  • Py_TYPE (C のマクロ)
  • Py_UCS1 (C のデータ型)
  • Py_UCS2 (C のデータ型)
  • Py_UCS4 (C のデータ型)
  • Py_UNBLOCK_THREADS (C のマクロ)
  • Py_UnbufferedStdioFlag (C の変数)
  • Py_UNICODE (C のデータ型)
  • Py_UNICODE_IS_HIGH_SURROGATE (C のマクロ)
  • Py_UNICODE_IS_LOW_SURROGATE (C のマクロ)
  • Py_UNICODE_IS_SURROGATE (C のマクロ)
  • Py_UNICODE_ISALNUM (C の関数)
  • Py_UNICODE_ISALPHA (C の関数)
  • Py_UNICODE_ISDECIMAL (C の関数)
  • Py_UNICODE_ISDIGIT (C の関数)
  • Py_UNICODE_ISLINEBREAK (C の関数)
  • Py_UNICODE_ISLOWER (C の関数)
  • Py_UNICODE_ISNUMERIC (C の関数)
  • Py_UNICODE_ISPRINTABLE (C の関数)
  • Py_UNICODE_ISSPACE (C の関数)
  • Py_UNICODE_ISTITLE (C の関数)
  • Py_UNICODE_ISUPPER (C の関数)
  • Py_UNICODE_JOIN_SURROGATES (C のマクロ)
  • Py_UNICODE_TODECIMAL (C の関数)
  • Py_UNICODE_TODIGIT (C の関数)
  • Py_UNICODE_TOLOWER (C の関数)
  • Py_UNICODE_TONUMERIC (C の関数)
  • Py_UNICODE_TOTITLE (C の関数)
  • Py_UNICODE_TOUPPER (C の関数)
  • Py_UNREACHABLE (C のマクロ)
  • Py_UNUSED (C のマクロ)
  • Py_VaBuildValue (C の関数)
  • Py_VerboseFlag (C の変数)
  • Py_VISIT (C の関数)
  • Py_XDECREF (C の関数)
  • Py_XDECREF()
  • Py_XINCREF (C の関数)
  • PyAnySet_Check (C の関数)
  • PyAnySet_CheckExact (C の関数)
  • PyArg_Parse (C の関数)
  • PyArg_ParseTuple (C の関数)
  • PyArg_ParseTuple()
  • PyArg_ParseTupleAndKeywords (C の関数)
  • PyArg_ParseTupleAndKeywords()
  • PyArg_UnpackTuple (C の関数)
  • PyArg_ValidateKeywordArguments (C の関数)
  • PyArg_VaParse (C の関数)
  • PyArg_VaParseTupleAndKeywords (C の関数)
  • PyASCIIObject (C のデータ型)
  • PyAsyncMethods (C のデータ型)
  • PyAsyncMethods.am_aiter (C のメンバ変数)
  • PyAsyncMethods.am_anext (C のメンバ変数)
  • PyAsyncMethods.am_await (C のメンバ変数)
  • PyBool_Check (C の関数)
  • PyBool_FromLong (C の関数)
  • PyBUF_ANY_CONTIGUOUS (C のマクロ)
  • PyBUF_C_CONTIGUOUS (C のマクロ)
  • PyBUF_CONTIG (C のマクロ)
  • PyBUF_CONTIG_RO (C のマクロ)
  • PyBUF_F_CONTIGUOUS (C のマクロ)
  • PyBUF_FORMAT (C のマクロ)
  • PyBUF_FULL (C のマクロ)
  • PyBUF_FULL_RO (C のマクロ)
  • PyBUF_INDIRECT (C のマクロ)
  • PyBUF_ND (C のマクロ), [1]
  • PyBUF_RECORDS (C のマクロ)
  • PyBUF_RECORDS_RO (C のマクロ)
  • PyBUF_SIMPLE (C のマクロ)
  • PyBUF_STRIDED (C のマクロ)
  • PyBUF_STRIDED_RO (C のマクロ)
  • PyBUF_STRIDES (C のマクロ)
  • PyBUF_WRITABLE (C のマクロ)
  • PyBuffer_FillContiguousStrides (C の関数)
  • PyBuffer_FillInfo (C の関数)
  • PyBuffer_IsContiguous (C の関数)
  • PyBuffer_Release (C の関数)
  • PyBuffer_SizeFromFormat (C の関数)
  • PyBuffer_ToContiguous (C の関数)
  • PyBufferProcs
    • (C のデータ型)
  • PyBufferProcs.bf_getbuffer (C のメンバ変数)
  • PyBufferProcs.bf_releasebuffer (C のメンバ変数)
  • PyByteArray_AS_STRING (C の関数)
  • PyByteArray_AsString (C の関数)
  • PyByteArray_Check (C の関数)
  • PyByteArray_CheckExact (C の関数)
  • PyByteArray_Concat (C の関数)
  • PyByteArray_FromObject (C の関数)
  • PyByteArray_FromStringAndSize (C の関数)
  • PyByteArray_GET_SIZE (C の関数)
  • PyByteArray_Resize (C の関数)
  • PyByteArray_Size (C の関数)
  • PyByteArray_Type (C の変数)
  • PyByteArrayObject (C のデータ型)
  • PyBytes_AS_STRING (C の関数)
  • PyBytes_AsString (C の関数)
  • PyBytes_AsStringAndSize (C の関数)
  • PyBytes_Check (C の関数)
  • PyBytes_CheckExact (C の関数)
  • PyBytes_Concat (C の関数)
  • PyBytes_ConcatAndDel (C の関数)
  • PyBytes_FromFormat (C の関数)
  • PyBytes_FromFormatV (C の関数)
  • PyBytes_FromObject (C の関数)
  • PyBytes_FromString (C の関数)
  • PyBytes_FromStringAndSize (C の関数)
  • PyBytes_GET_SIZE (C の関数)
  • PyBytes_Size (C の関数)
  • PyBytes_Type (C の変数)
  • PyBytesObject (C のデータ型)
  • PyCallable_Check (C の関数)
  • PyCallIter_Check (C の関数)
  • PyCallIter_New (C の関数)
  • PyCallIter_Type (C の変数)
  • PyCapsule (C のデータ型)
  • PyCapsule_CheckExact (C の関数)
  • PyCapsule_Destructor (C のデータ型)
  • PyCapsule_GetContext (C の関数)
  • PyCapsule_GetDestructor (C の関数)
  • PyCapsule_GetName (C の関数)
  • PyCapsule_GetPointer (C の関数)
  • PyCapsule_Import (C の関数)
  • PyCapsule_IsValid (C の関数)
  • PyCapsule_New (C の関数)
  • PyCapsule_SetContext (C の関数)
  • PyCapsule_SetDestructor (C の関数)
  • PyCapsule_SetName (C の関数)
  • PyCapsule_SetPointer (C の関数)
  • PyCell_Check (C の関数)
  • PyCell_GET (C の関数)
  • PyCell_Get (C の関数)
  • PyCell_New (C の関数)
  • PyCell_SET (C の関数)
  • PyCell_Set (C の関数)
  • PyCell_Type (C の変数)
  • PyCellObject (C のデータ型)
  • PyCFunction (C のデータ型)
  • PyCFunctionWithKeywords (C のデータ型)
  • PycInvalidationMode (py_compile のクラス)
  • pyclbr (モジュール)
  • PyCode_Check (C の関数)
  • PyCode_GetNumFree (C の関数)
  • PyCode_New (C の関数)
  • PyCode_NewEmpty (C の関数)
  • PyCode_Type (C の変数)
  • PyCodec_BackslashReplaceErrors (C の関数)
  • PyCodec_Decode (C の関数)
  • PyCodec_Decoder (C の関数)
  • PyCodec_Encode (C の関数)
  • PyCodec_Encoder (C の関数)
  • PyCodec_IgnoreErrors (C の関数)
  • PyCodec_IncrementalDecoder (C の関数)
  • PyCodec_IncrementalEncoder (C の関数)
  • PyCodec_KnownEncoding (C の関数)
  • PyCodec_LookupError (C の関数)
  • PyCodec_NameReplaceErrors (C の関数)
  • PyCodec_Register (C の関数)
  • PyCodec_RegisterError (C の関数)
  • PyCodec_ReplaceErrors (C の関数)
  • PyCodec_StreamReader (C の関数)
  • PyCodec_StreamWriter (C の関数)
  • PyCodec_StrictErrors (C の関数)
  • PyCodec_XMLCharRefReplaceErrors (C の関数)
  • PyCodeObject (C のデータ型)
  • PyCompactUnicodeObject (C のデータ型)
  • PyCompileError
  • PyCompilerFlags (C のデータ型)
  • PyComplex_AsCComplex (C の関数)
  • PyComplex_Check (C の関数)
  • PyComplex_CheckExact (C の関数)
  • PyComplex_FromCComplex (C の関数)
  • PyComplex_FromDoubles (C の関数)
  • PyComplex_ImagAsDouble (C の関数)
  • PyComplex_RealAsDouble (C の関数)
  • PyComplex_Type (C の変数)
  • PyComplexObject (C のデータ型)
  • PyContext (C のデータ型)
  • PyContext_CheckExact (C の関数)
  • PyContext_ClearFreeList (C の関数)
  • PyContext_Copy (C の関数)
  • PyContext_CopyCurrent (C の関数)
  • PyContext_Enter (C の関数)
  • PyContext_Exit (C の関数)
  • PyContext_New (C の関数)
  • PyContext_Type (C の変数)
  • PyContextToken (C のデータ型)
  • PyContextToken_CheckExact (C の関数)
  • PyContextToken_Type (C の変数)
  • PyContextVar (C のデータ型)
  • PyContextVar_CheckExact (C の関数)
  • PyContextVar_Get (C の関数)
  • PyContextVar_New (C の関数)
  • PyContextVar_Reset (C の関数)
  • PyContextVar_Set (C の関数)
  • PyContextVar_Type (C の変数)
  • PyCoro_CheckExact (C の関数)
  • PyCoro_New (C の関数)
  • PyCoro_Type (C の変数)
  • PyCoroObject (C のデータ型)
  • PyDate_Check (C の関数)
  • PyDate_CheckExact (C の関数)
  • PyDate_FromDate (C の関数)
  • PyDate_FromTimestamp (C の関数)
  • PyDateTime_Check (C の関数)
  • PyDateTime_CheckExact (C の関数)
  • PyDateTime_DATE_GET_HOUR (C の関数)
  • PyDateTime_DATE_GET_MICROSECOND (C の関数)
  • PyDateTime_DATE_GET_MINUTE (C の関数)
  • PyDateTime_DATE_GET_SECOND (C の関数)
  • PyDateTime_DELTA_GET_DAYS (C の関数)
  • PyDateTime_DELTA_GET_MICROSECONDS (C の関数)
  • PyDateTime_DELTA_GET_SECONDS (C の関数)
  • PyDateTime_FromDateAndTime (C の関数)
  • PyDateTime_FromTimestamp (C の関数)
  • PyDateTime_GET_DAY (C の関数)
  • PyDateTime_GET_MONTH (C の関数)
  • PyDateTime_GET_YEAR (C の関数)
  • PyDateTime_TIME_GET_HOUR (C の関数)
  • PyDateTime_TIME_GET_MICROSECOND (C の関数)
  • PyDateTime_TIME_GET_MINUTE (C の関数)
  • PyDateTime_TIME_GET_SECOND (C の関数)
  • PyDateTime_TimeZone_UTC (C の変数)
  • PyDelta_Check (C の関数)
  • PyDelta_CheckExact (C の関数)
  • PyDelta_FromDSU (C の関数)
  • PyDescr_IsData (C の関数)
  • PyDescr_NewClassMethod (C の関数)
  • PyDescr_NewGetSet (C の関数)
  • PyDescr_NewMember (C の関数)
  • PyDescr_NewMethod (C の関数)
  • PyDescr_NewWrapper (C の関数)
  • PyDict_Check (C の関数)
  • PyDict_CheckExact (C の関数)
  • PyDict_Clear (C の関数)
  • PyDict_ClearFreeList (C の関数)
  • PyDict_Contains (C の関数)
  • PyDict_Copy (C の関数)
  • PyDict_DelItem (C の関数)
  • PyDict_DelItemString (C の関数)
  • PyDict_GetItem (C の関数)
  • PyDict_GetItemString (C の関数)
  • PyDict_GetItemWithError (C の関数)
  • PyDict_Items (C の関数)
  • PyDict_Keys (C の関数)
  • PyDict_Merge (C の関数)
  • PyDict_MergeFromSeq2 (C の関数)
  • PyDict_New (C の関数)
  • PyDict_Next (C の関数)
  • PyDict_SetDefault (C の関数)
  • PyDict_SetItem (C の関数)
  • PyDict_SetItemString (C の関数)
  • PyDict_Size (C の関数)
  • PyDict_Type (C の変数)
  • PyDict_Update (C の関数)
  • PyDict_Values (C の関数)
  • PyDictObject (C のデータ型)
  • PyDictProxy_New (C の関数)
  • PyDLL (ctypes のクラス)
  • pydoc (モジュール)
  • PyErr_BadArgument (C の関数)
  • PyErr_BadInternalCall (C の関数)
  • PyErr_CheckSignals (C の関数)
  • PyErr_Clear (C の関数)
  • PyErr_Clear(), [1]
  • PyErr_ExceptionMatches (C の関数)
  • PyErr_ExceptionMatches()
  • PyErr_Fetch (C の関数)
  • PyErr_Fetch()
  • PyErr_Format (C の関数)
  • PyErr_FormatV (C の関数)
  • PyErr_GetExcInfo (C の関数)
  • PyErr_GivenExceptionMatches (C の関数)
  • PyErr_NewException (C の関数)
  • PyErr_NewExceptionWithDoc (C の関数)
  • PyErr_NoMemory (C の関数)
  • PyErr_NormalizeException (C の関数)
  • PyErr_Occurred (C の関数)
  • PyErr_Occurred()
  • PyErr_Print (C の関数)
  • PyErr_PrintEx (C の関数)
  • PyErr_ResourceWarning (C の関数)
  • PyErr_Restore (C の関数)
  • PyErr_Restore()
  • PyErr_SetExcFromWindowsErr (C の関数)
  • PyErr_SetExcFromWindowsErrWithFilename (C の関数)
  • PyErr_SetExcFromWindowsErrWithFilenameObject (C の関数)
  • PyErr_SetExcFromWindowsErrWithFilenameObjects (C の関数)
  • PyErr_SetExcInfo (C の関数)
  • PyErr_SetFromErrno (C の関数)
  • PyErr_SetFromErrnoWithFilename (C の関数)
  • PyErr_SetFromErrnoWithFilenameObject (C の関数)
  • PyErr_SetFromErrnoWithFilenameObjects (C の関数)
  • PyErr_SetFromWindowsErr (C の関数)
  • PyErr_SetFromWindowsErrWithFilename (C の関数)
  • PyErr_SetImportError (C の関数)
  • PyErr_SetImportErrorSubclass (C の関数)
  • PyErr_SetInterrupt (C の関数)
  • PyErr_SetNone (C の関数)
  • PyErr_SetObject (C の関数)
  • PyErr_SetString (C の関数)
  • PyErr_SetString()
  • PyErr_SyntaxLocation (C の関数)
  • PyErr_SyntaxLocationEx (C の関数)
  • PyErr_SyntaxLocationObject (C の関数)
  • PyErr_WarnEx (C の関数)
  • PyErr_WarnExplicit (C の関数)
  • PyErr_WarnExplicitObject (C の関数)
  • PyErr_WarnFormat (C の関数)
  • PyErr_WriteUnraisable (C の関数)
  • PyEval_AcquireLock (C の関数)
  • PyEval_AcquireThread (C の関数)
  • PyEval_AcquireThread()
  • PyEval_EvalCode (C の関数)
  • PyEval_EvalCodeEx (C の関数)
  • PyEval_EvalFrame (C の関数)
  • PyEval_EvalFrameEx (C の関数)
  • PyEval_GetBuiltins (C の関数)
  • PyEval_GetFrame (C の関数)
  • PyEval_GetFuncDesc (C の関数)
  • PyEval_GetFuncName (C の関数)
  • PyEval_GetGlobals (C の関数)
  • PyEval_GetLocals (C の関数)
  • PyEval_InitThreads (C の関数)
  • PyEval_InitThreads()
  • PyEval_MergeCompilerFlags (C の関数)
  • PyEval_ReInitThreads (C の関数)
  • PyEval_ReleaseLock (C の関数)
  • PyEval_ReleaseThread (C の関数)
  • PyEval_ReleaseThread()
  • PyEval_RestoreThread (C の関数)
  • PyEval_RestoreThread(), [1]
  • PyEval_SaveThread (C の関数)
  • PyEval_SaveThread(), [1]
  • PyEval_SetProfile (C の関数)
  • PyEval_SetTrace (C の関数)
  • PyEval_ThreadsInitialized (C の関数)
  • PyExc_ArithmeticError
  • PyExc_AssertionError
  • PyExc_AttributeError
  • PyExc_BaseException
  • PyExc_BlockingIOError
  • PyExc_BrokenPipeError
  • PyExc_BufferError
  • PyExc_BytesWarning
  • PyExc_ChildProcessError
  • PyExc_ConnectionAbortedError
  • PyExc_ConnectionError
  • PyExc_ConnectionRefusedError
  • PyExc_ConnectionResetError
  • PyExc_DeprecationWarning
  • PyExc_EnvironmentError
  • PyExc_EOFError
  • PyExc_Exception
  • PyExc_FileExistsError
  • PyExc_FileNotFoundError
  • PyExc_FloatingPointError
  • PyExc_FutureWarning
  • PyExc_GeneratorExit
  • PyExc_ImportError
  • PyExc_ImportWarning
  • PyExc_IndentationError
  • PyExc_IndexError
  • PyExc_InterruptedError
  • PyExc_IOError
  • PyExc_IsADirectoryError
  • PyExc_KeyboardInterrupt
  • PyExc_KeyError
  • 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
  • PyException_GetCause (C の関数)
  • PyException_GetContext (C の関数)
  • PyException_GetTraceback (C の関数)
  • PyException_SetCause (C の関数)
  • PyException_SetContext (C の関数)
  • PyException_SetTraceback (C の関数)
  • pyexpat
    • モジュール
  • PyFile_FromFd (C の関数)
  • PyFile_GetLine (C の関数)
  • PyFile_WriteObject (C の関数)
  • PyFile_WriteString (C の関数)
  • PyFloat_AS_DOUBLE (C の関数)
  • PyFloat_AsDouble (C の関数)
  • PyFloat_Check (C の関数)
  • PyFloat_CheckExact (C の関数)
  • PyFloat_ClearFreeList (C の関数)
  • PyFloat_FromDouble (C の関数)
  • PyFloat_FromString (C の関数)
  • PyFloat_GetInfo (C の関数)
  • PyFloat_GetMax (C の関数)
  • PyFloat_GetMin (C の関数)
  • PyFloat_Type (C の変数)
  • PyFloatObject (C のデータ型)
  • PyFrame_GetLineNumber (C の関数)
  • PyFrameObject (C のデータ型)
  • PyFrozenSet_Check (C の関数)
  • PyFrozenSet_CheckExact (C の関数)
  • PyFrozenSet_New (C の関数)
  • PyFrozenSet_Type (C の変数)
  • PyFunction_Check (C の関数)
  • PyFunction_GetAnnotations (C の関数)
  • PyFunction_GetClosure (C の関数)
  • PyFunction_GetCode (C の関数)
  • PyFunction_GetDefaults (C の関数)
  • PyFunction_GetGlobals (C の関数)
  • PyFunction_GetModule (C の関数)
  • PyFunction_New (C の関数)
  • PyFunction_NewWithQualName (C の関数)
  • PyFunction_SetAnnotations (C の関数)
  • PyFunction_SetClosure (C の関数)
  • PyFunction_SetDefaults (C の関数)
  • PyFunction_Type (C の変数)
  • PyFunctionObject (C のデータ型)
  • PYFUNCTYPE() (ctypes モジュール)
  • PyGen_Check (C の関数)
  • PyGen_CheckExact (C の関数)
  • PyGen_New (C の関数)
  • PyGen_NewWithQualName (C の関数)
  • PyGen_Type (C の変数)
  • PyGenObject (C のデータ型)
  • PyGetSetDef (C のデータ型)
  • PyGILState_Check (C の関数)
  • PyGILState_Ensure (C の関数)
  • PyGILState_GetThisThreadState (C の関数)
  • PyGILState_Release (C の関数)
  • PyImport_AddModule (C の関数)
  • PyImport_AddModuleObject (C の関数)
  • PyImport_AppendInittab (C の関数)
  • PyImport_Cleanup (C の関数)
  • PyImport_ExecCodeModule (C の関数)
  • PyImport_ExecCodeModuleEx (C の関数)
  • PyImport_ExecCodeModuleObject (C の関数)
  • PyImport_ExecCodeModuleWithPathnames (C の関数)
  • PyImport_ExtendInittab (C の関数)
  • PyImport_FrozenModules (C の変数)
  • PyImport_GetImporter (C の関数)
  • PyImport_GetMagicNumber (C の関数)
  • PyImport_GetMagicTag (C の関数)
  • PyImport_GetModule (C の関数)
  • PyImport_GetModuleDict (C の関数)
  • PyImport_Import (C の関数)
  • PyImport_ImportFrozenModule (C の関数)
  • PyImport_ImportFrozenModuleObject (C の関数)
  • PyImport_ImportModule (C の関数)
  • PyImport_ImportModuleEx (C の関数)
  • PyImport_ImportModuleLevel (C の関数)
  • PyImport_ImportModuleLevelObject (C の関数)
  • PyImport_ImportModuleNoBlock (C の関数)
  • PyImport_ReloadModule (C の関数)
  • PyIndex_Check (C の関数)
  • PyInit_modulename (C の関数)
  • PyInstanceMethod_Check (C の関数)
  • PyInstanceMethod_Function (C の関数)
  • PyInstanceMethod_GET_FUNCTION (C の関数)
  • PyInstanceMethod_New (C の関数)
  • PyInstanceMethod_Type (C の変数)
  • PyInterpreterState (C のデータ型)
  • PyInterpreterState_Clear (C の関数)
  • PyInterpreterState_Delete (C の関数)
  • PyInterpreterState_GetID (C の関数)
  • PyInterpreterState_Head (C の関数)
  • PyInterpreterState_New (C の関数)
  • PyInterpreterState_Next (C の関数)
  • PyInterpreterState_ThreadHead (C の関数)
  • PyIter_Check (C の関数)
  • PyIter_Next (C の関数)
  • PyList_Append (C の関数)
  • PyList_AsTuple (C の関数)
  • PyList_Check (C の関数)
  • PyList_CheckExact (C の関数)
  • PyList_ClearFreeList (C の関数)
  • PyList_GET_ITEM (C の関数)
  • PyList_GET_SIZE (C の関数)
  • PyList_GetItem (C の関数)
  • PyList_GetItem()
  • PyList_GetSlice (C の関数)
  • PyList_Insert (C の関数)
  • PyList_New (C の関数)
  • PyList_Reverse (C の関数)
  • PyList_SET_ITEM (C の関数)
  • PyList_SetItem (C の関数)
  • PyList_SetItem()
  • PyList_SetSlice (C の関数)
  • PyList_Size (C の関数)
  • PyList_Sort (C の関数)
  • PyList_Type (C の変数)
  • PyListObject (C のデータ型)
  • PyLong_AsDouble (C の関数)
  • PyLong_AsLong (C の関数)
  • PyLong_AsLongAndOverflow (C の関数)
  • PyLong_AsLongLong (C の関数)
  • PyLong_AsLongLongAndOverflow (C の関数)
  • PyLong_AsSize_t (C の関数)
  • PyLong_AsSsize_t (C の関数)
  • PyLong_AsUnsignedLong (C の関数)
  • PyLong_AsUnsignedLongLong (C の関数)
  • PyLong_AsUnsignedLongLongMask (C の関数)
  • PyLong_AsUnsignedLongMask (C の関数)
  • PyLong_AsVoidPtr (C の関数)
  • PyLong_Check (C の関数)
  • PyLong_CheckExact (C の関数)
  • PyLong_FromDouble (C の関数)
  • PyLong_FromLong (C の関数)
  • PyLong_FromLongLong (C の関数)
  • PyLong_FromSize_t (C の関数)
  • PyLong_FromSsize_t (C の関数)
  • PyLong_FromString (C の関数)
  • PyLong_FromUnicode (C の関数)
  • PyLong_FromUnicodeObject (C の関数)
  • PyLong_FromUnsignedLong (C の関数)
  • PyLong_FromUnsignedLongLong (C の関数)
  • PyLong_FromVoidPtr (C の関数)
  • PyLong_Type (C の変数)
  • PyLongObject (C のデータ型)
  • PyMapping_Check (C の関数)
  • PyMapping_DelItem (C の関数)
  • PyMapping_DelItemString (C の関数)
  • PyMapping_GetItemString (C の関数)
  • PyMapping_HasKey (C の関数)
  • PyMapping_HasKeyString (C の関数)
  • PyMapping_Items (C の関数)
  • PyMapping_Keys (C の関数)
  • PyMapping_Length (C の関数)
  • PyMapping_SetItemString (C の関数)
  • PyMapping_Size (C の関数)
  • PyMapping_Values (C の関数)
  • PyMappingMethods (C のデータ型)
  • PyMappingMethods.mp_ass_subscript (C のメンバ変数)
  • PyMappingMethods.mp_length (C のメンバ変数)
  • PyMappingMethods.mp_subscript (C のメンバ変数)
  • PyMarshal_ReadLastObjectFromFile (C の関数)
  • PyMarshal_ReadLongFromFile (C の関数)
  • PyMarshal_ReadObjectFromFile (C の関数)
  • PyMarshal_ReadObjectFromString (C の関数)
  • PyMarshal_ReadShortFromFile (C の関数)
  • PyMarshal_WriteLongToFile (C の関数)
  • PyMarshal_WriteObjectToFile (C の関数)
  • PyMarshal_WriteObjectToString (C の関数)
  • PyMem_Calloc (C の関数)
  • PyMem_Del (C の関数)
  • PYMEM_DOMAIN_MEM (C の変数)
  • PYMEM_DOMAIN_OBJ (C の変数)
  • PYMEM_DOMAIN_RAW (C の変数)
  • PyMem_Free (C の関数)
  • PyMem_GetAllocator (C の関数)
  • PyMem_Malloc (C の関数)
  • PyMem_New (C の関数)
  • PyMem_RawCalloc (C の関数)
  • PyMem_RawFree (C の関数)
  • PyMem_RawMalloc (C の関数)
  • PyMem_RawRealloc (C の関数)
  • PyMem_Realloc (C の関数)
  • PyMem_Resize (C の関数)
  • PyMem_SetAllocator (C の関数)
  • PyMem_SetupDebugHooks (C の関数)
  • PyMemAllocatorDomain (C のデータ型)
  • PyMemAllocatorEx (C のデータ型)
  • PyMemberDef (C のデータ型)
  • PyMemoryView_Check (C の関数)
  • PyMemoryView_FromBuffer (C の関数)
  • PyMemoryView_FromMemory (C の関数)
  • PyMemoryView_FromObject (C の関数)
  • PyMemoryView_GET_BASE (C の関数)
  • PyMemoryView_GET_BUFFER (C の関数)
  • PyMemoryView_GetContiguous (C の関数)
  • PyMethod_Check (C の関数)
  • PyMethod_ClearFreeList (C の関数)
  • PyMethod_Function (C の関数)
  • PyMethod_GET_FUNCTION (C の関数)
  • PyMethod_GET_SELF (C の関数)
  • PyMethod_New (C の関数)
  • PyMethod_Self (C の関数)
  • PyMethod_Type (C の変数)
  • PyMethodDef (C のデータ型)
  • PyModule_AddFunctions (C の関数)
  • PyModule_AddIntConstant (C の関数)
  • PyModule_AddIntMacro (C の関数)
  • PyModule_AddObject (C の関数)
  • PyModule_AddStringConstant (C の関数)
  • PyModule_AddStringMacro (C の関数)
  • PyModule_Check (C の関数)
  • PyModule_CheckExact (C の関数)
  • PyModule_Create (C の関数)
  • PyModule_Create2 (C の関数)
  • PyModule_ExecDef (C の関数)
  • PyModule_FromDefAndSpec (C の関数)
  • PyModule_FromDefAndSpec2 (C の関数)
  • PyModule_GetDef (C の関数)
  • PyModule_GetDict (C の関数)
  • PyModule_GetFilename (C の関数)
  • PyModule_GetFilenameObject (C の関数)
  • PyModule_GetName (C の関数)
  • PyModule_GetNameObject (C の関数)
  • PyModule_GetState (C の関数)
  • PyModule_New (C の関数)
  • PyModule_NewObject (C の関数)
  • PyModule_SetDocString (C の関数)
  • PyModule_Type (C の変数)
  • PyModuleDef (C のデータ型)
  • PyModuleDef.m_base (C のメンバ変数)
  • PyModuleDef.m_clear (C のメンバ変数)
  • PyModuleDef.m_doc (C のメンバ変数)
  • PyModuleDef.m_free (C のメンバ変数)
  • PyModuleDef.m_methods (C のメンバ変数)
  • PyModuleDef.m_name (C のメンバ変数)
  • PyModuleDef.m_reload (C のメンバ変数)
  • PyModuleDef.m_size (C のメンバ変数)
  • PyModuleDef.m_slots (C のメンバ変数)
  • PyModuleDef.m_traverse (C のメンバ変数)
  • PyModuleDef_Init (C の関数)
  • PyModuleDef_Slot (C のデータ型)
  • PyModuleDef_Slot.slot (C のメンバ変数)
  • PyModuleDef_Slot.value (C のメンバ変数)
  • PyNumber_Absolute (C の関数)
  • PyNumber_Add (C の関数)
  • PyNumber_And (C の関数)
  • PyNumber_AsSsize_t (C の関数)
  • PyNumber_Check (C の関数)
  • PyNumber_Divmod (C の関数)
  • PyNumber_Float (C の関数)
  • PyNumber_FloorDivide (C の関数)
  • PyNumber_Index (C の関数)
  • PyNumber_InPlaceAdd (C の関数)
  • PyNumber_InPlaceAnd (C の関数)
  • PyNumber_InPlaceFloorDivide (C の関数)
  • PyNumber_InPlaceLshift (C の関数)
  • PyNumber_InPlaceMatrixMultiply (C の関数)
  • PyNumber_InPlaceMultiply (C の関数)
  • PyNumber_InPlaceOr (C の関数)
  • PyNumber_InPlacePower (C の関数)
  • PyNumber_InPlaceRemainder (C の関数)
  • PyNumber_InPlaceRshift (C の関数)
  • PyNumber_InPlaceSubtract (C の関数)
  • PyNumber_InPlaceTrueDivide (C の関数)
  • PyNumber_InPlaceXor (C の関数)
  • PyNumber_Invert (C の関数)
  • PyNumber_Long (C の関数)
  • PyNumber_Lshift (C の関数)
  • PyNumber_MatrixMultiply (C の関数)
  • PyNumber_Multiply (C の関数)
  • PyNumber_Negative (C の関数)
  • PyNumber_Or (C の関数)
  • PyNumber_Positive (C の関数)
  • PyNumber_Power (C の関数)
  • PyNumber_Remainder (C の関数)
  • PyNumber_Rshift (C の関数)
  • PyNumber_Subtract (C の関数)
  • PyNumber_ToBase (C の関数)
  • PyNumber_TrueDivide (C の関数)
  • PyNumber_Xor (C の関数)
  • PyNumberMethods (C のデータ型)
  • PyObject (C のデータ型)
  • PyObject._ob_next (C のメンバ変数)
  • PyObject._ob_prev (C のメンバ変数)
  • PyObject.ob_refcnt (C のメンバ変数)
  • PyObject.ob_type (C のメンバ変数)
  • PyObject_AsCharBuffer (C の関数)
  • PyObject_ASCII (C の関数)
  • PyObject_AsFileDescriptor (C の関数)
  • PyObject_AsReadBuffer (C の関数)
  • PyObject_AsWriteBuffer (C の関数)
  • PyObject_Bytes (C の関数)
  • PyObject_Call (C の関数)
  • PyObject_CallFunction (C の関数)
  • PyObject_CallFunctionObjArgs (C の関数)
  • PyObject_CallMethod (C の関数)
  • PyObject_CallMethodObjArgs (C の関数)
  • PyObject_CallObject (C の関数)
  • PyObject_CallObject()
  • PyObject_Calloc (C の関数)
  • PyObject_CheckBuffer (C の関数)
  • PyObject_CheckReadBuffer (C の関数)
  • PyObject_Del (C の関数)
  • PyObject_DelAttr (C の関数)
  • PyObject_DelAttrString (C の関数)
  • PyObject_DelItem (C の関数)
  • PyObject_Dir (C の関数)
  • PyObject_Free (C の関数)
  • PyObject_GC_Del (C の関数)
  • PyObject_GC_New (C の関数)
  • PyObject_GC_NewVar (C の関数)
  • PyObject_GC_Resize (C の関数)
  • PyObject_GC_Track (C の関数)
  • PyObject_GC_UnTrack (C の関数)
  • PyObject_GenericGetAttr (C の関数)
  • PyObject_GenericGetDict (C の関数)
  • PyObject_GenericSetAttr (C の関数)
  • PyObject_GenericSetDict (C の関数)
  • PyObject_GetArenaAllocator (C の関数)
  • PyObject_GetAttr (C の関数)
  • PyObject_GetAttrString (C の関数)
  • PyObject_GetBuffer (C の関数)
  • PyObject_GetItem (C の関数)
  • PyObject_GetIter (C の関数)
  • PyObject_HasAttr (C の関数)
  • PyObject_HasAttrString (C の関数)
  • PyObject_Hash (C の関数)
  • PyObject_HashNotImplemented (C の関数)
  • PyObject_HEAD (C のマクロ)
  • PyObject_HEAD_INIT (C のマクロ)
  • PyObject_Init (C の関数)
  • PyObject_InitVar (C の関数)
  • PyObject_IsInstance (C の関数)
  • PyObject_IsSubclass (C の関数)
  • PyObject_IsTrue (C の関数)
  • PyObject_Length (C の関数)
  • PyObject_LengthHint (C の関数)
  • PyObject_Malloc (C の関数)
  • PyObject_New (C の関数)
  • PyObject_NewVar (C の関数)
  • PyObject_Not (C の関数)
  • PyObject_Print (C の関数)
  • PyObject_Realloc (C の関数)
  • PyObject_Repr (C の関数)
  • PyObject_RichCompare (C の関数)
  • PyObject_RichCompareBool (C の関数)
  • PyObject_SetArenaAllocator (C の関数)
  • PyObject_SetAttr (C の関数)
  • PyObject_SetAttrString (C の関数)
  • PyObject_SetItem (C の関数)
  • PyObject_Size (C の関数)
  • PyObject_Str (C の関数)
  • PyObject_Type (C の関数)
  • PyObject_TypeCheck (C の関数)
  • PyObject_VAR_HEAD (C のマクロ)
  • PyObjectArenaAllocator (C のデータ型)
  • PyOS_AfterFork (C の関数)
  • PyOS_AfterFork_Child (C の関数)
  • PyOS_AfterFork_Parent (C の関数)
  • PyOS_BeforeFork (C の関数)
  • PyOS_CheckStack (C の関数)
  • PyOS_double_to_string (C の関数)
  • PyOS_FSPath (C の関数)
  • PyOS_getsig (C の関数)
  • PyOS_InputHook (C の変数)
  • PyOS_ReadlineFunctionPointer (C の変数)
  • PyOS_setsig (C の関数)
  • PyOS_snprintf (C の関数)
  • PyOS_stricmp (C の関数)
  • PyOS_string_to_double (C の関数)
  • PyOS_strnicmp (C の関数)
  • PyOS_vsnprintf (C の関数)
  • PyParser_SimpleParseFile (C の関数)
  • PyParser_SimpleParseFileFlags (C の関数)
  • PyParser_SimpleParseString (C の関数)
  • PyParser_SimpleParseStringFlags (C の関数)
  • PyParser_SimpleParseStringFlagsFilename (C の関数)
  • PyPI
    • (see Python Package Index (PyPI))
  • PyProperty_Type (C の変数)
  • PyRun_AnyFile (C の関数)
  • PyRun_AnyFileEx (C の関数)
  • PyRun_AnyFileExFlags (C の関数)
  • PyRun_AnyFileFlags (C の関数)
  • PyRun_File (C の関数)
  • PyRun_FileEx (C の関数)
  • PyRun_FileExFlags (C の関数)
  • PyRun_FileFlags (C の関数)
  • PyRun_InteractiveLoop (C の関数)
  • PyRun_InteractiveLoopFlags (C の関数)
  • PyRun_InteractiveOne (C の関数)
  • PyRun_InteractiveOneFlags (C の関数)
  • PyRun_SimpleFile (C の関数)
  • PyRun_SimpleFileEx (C の関数)
  • PyRun_SimpleFileExFlags (C の関数)
  • PyRun_SimpleString (C の関数)
  • PyRun_SimpleStringFlags (C の関数)
  • PyRun_String (C の関数)
  • PyRun_StringFlags (C の関数)
  • PySeqIter_Check (C の関数)
  • PySeqIter_New (C の関数)
  • PySeqIter_Type (C の変数)
  • PySequence_Check (C の関数)
  • PySequence_Concat (C の関数)
  • PySequence_Contains (C の関数)
  • PySequence_Count (C の関数)
  • PySequence_DelItem (C の関数)
  • PySequence_DelSlice (C の関数)
  • PySequence_Fast (C の関数)
  • PySequence_Fast_GET_ITEM (C の関数)
  • PySequence_Fast_GET_SIZE (C の関数)
  • PySequence_Fast_ITEMS (C の関数)
  • PySequence_GetItem (C の関数)
  • PySequence_GetItem()
  • PySequence_GetSlice (C の関数)
  • PySequence_Index (C の関数)
  • PySequence_InPlaceConcat (C の関数)
  • PySequence_InPlaceRepeat (C の関数)
  • PySequence_ITEM (C の関数)
  • PySequence_Length (C の関数)
  • PySequence_List (C の関数)
  • PySequence_Repeat (C の関数)
  • PySequence_SetItem (C の関数)
  • PySequence_SetSlice (C の関数)
  • PySequence_Size (C の関数)
  • PySequence_Tuple (C の関数)
  • PySequenceMethods (C のデータ型)
  • PySequenceMethods.sq_ass_item (C のメンバ変数)
  • PySequenceMethods.sq_concat (C のメンバ変数)
  • PySequenceMethods.sq_contains (C のメンバ変数)
  • PySequenceMethods.sq_inplace_concat (C のメンバ変数)
  • PySequenceMethods.sq_inplace_repeat (C のメンバ変数)
  • PySequenceMethods.sq_item (C のメンバ変数)
  • PySequenceMethods.sq_length (C のメンバ変数)
  • PySequenceMethods.sq_repeat (C のメンバ変数)
  • PySet_Add (C の関数)
  • PySet_Check (C の関数)
  • PySet_Clear (C の関数)
  • PySet_ClearFreeList (C の関数)
  • PySet_Contains (C の関数)
  • PySet_Discard (C の関数)
  • PySet_GET_SIZE (C の関数)
  • PySet_New (C の関数)
  • PySet_Pop (C の関数)
  • PySet_Size (C の関数)
  • PySet_Type (C の変数)
  • PySetObject (C のデータ型)
  • PySignal_SetWakeupFd (C の関数)
  • PySlice_AdjustIndices (C の関数)
  • PySlice_Check (C の関数)
  • PySlice_GetIndices (C の関数)
  • PySlice_GetIndicesEx (C の関数)
  • PySlice_New (C の関数)
  • PySlice_Type (C の変数)
  • PySlice_Unpack (C の関数)
  • PyState_AddModule (C の関数)
  • PyState_FindModule (C の関数)
  • PyState_RemoveModule (C の関数)
  • PyStructSequence_Desc (C のデータ型)
  • PyStructSequence_Field (C のデータ型)
  • PyStructSequence_GET_ITEM (C の関数)
  • PyStructSequence_GetItem (C の関数)
  • PyStructSequence_InitType (C の関数)
  • PyStructSequence_InitType2 (C の関数)
  • PyStructSequence_New (C の関数)
  • PyStructSequence_NewType (C の関数)
  • PyStructSequence_SET_ITEM (C の関数)
  • PyStructSequence_SetItem (C の関数)
  • PyStructSequence_UnnamedField (C の変数)
  • PySys_AddWarnOption (C の関数)
  • PySys_AddWarnOptionUnicode (C の関数)
  • PySys_AddXOption (C の関数)
  • PySys_FormatStderr (C の関数)
  • PySys_FormatStdout (C の関数)
  • PySys_GetObject (C の関数)
  • PySys_GetXOptions (C の関数)
  • PySys_ResetWarnOptions (C の関数)
  • PySys_SetArgv (C の関数)
  • PySys_SetArgv()
  • PySys_SetArgvEx (C の関数)
  • PySys_SetArgvEx(), [1]
  • PySys_SetObject (C の関数)
  • PySys_SetPath (C の関数)
  • PySys_WriteStderr (C の関数)
  • PySys_WriteStdout (C の関数)
  • Python 3000
  • Python Editor
  • Python Enhancement Proposals
    • PEP 0342, [1]
    • PEP 1
    • PEP 100
    • PEP 11, [1], [2], [3], [4]
    • PEP 205, [1]
    • PEP 207
    • PEP 208
    • PEP 217
    • PEP 218, [1], [2]
    • PEP 227, [1], [2]
    • PEP 229, [1]
    • PEP 230
    • PEP 232
    • PEP 234
    • PEP 235
    • PEP 236, [1]
    • PEP 237, [1], [2], [3], [4], [5], [6]
    • PEP 238, [1], [2], [3], [4], [5], [6]
    • PEP 241
    • PEP 243
    • PEP 247
    • PEP 249, [1], [2], [3]
    • PEP 252, [1]
    • PEP 253, [1], [2], [3], [4]
    • PEP 255, [1], [2], [3], [4], [5]
    • PEP 261, [1]
    • PEP 263, [1], [2], [3], [4], [5]
    • PEP 264
    • PEP 273, [1], [2]
    • PEP 274
    • PEP 275
    • PEP 277
    • PEP 278, [1]
    • PEP 279
    • PEP 282, [1], [2], [3]
    • PEP 285, [1]
    • PEP 288
    • PEP 289, [1], [2]
    • PEP 292, [1]
    • PEP 293
    • PEP 3000
    • PEP 301, [1]
    • PEP 302, [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]
    • PEP 305, [1]
    • PEP 307, [1], [2], [3]
    • PEP 308, [1], [2]
    • PEP 309
    • PEP 3100
    • PEP 3101, [1], [2], [3], [4], [5]
    • PEP 3102
    • PEP 3104, [1]
    • PEP 3105, [1], [2], [3]
    • PEP 3106
    • PEP 3107, [1], [2], [3], [4]
    • PEP 3108, [1], [2]
    • PEP 3109, [1]
    • PEP 3110, [1], [2]
    • PEP 3111
    • PEP 3112, [1]
    • PEP 3113
    • PEP 3114
    • PEP 3115, [1], [2], [3], [4]
    • PEP 3116, [1], [2]
    • PEP 3118, [1], [2], [3], [4], [5]
    • PEP 3119, [1], [2], [3], [4], [5]
    • PEP 3120, [1], [2]
    • PEP 3121, [1], [2]
    • PEP 3123
    • PEP 3127
    • PEP 3129, [1]
    • PEP 3131, [1], [2]
    • PEP 3132, [1]
    • PEP 3134, [1], [2]
    • PEP 3135, [1]
    • PEP 3137
    • PEP 3138
    • PEP 314, [1]
    • PEP 3141, [1], [2]
    • PEP 3144
    • PEP 3147, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21]
    • PEP 3148, [1]
    • PEP 3149, [1]
    • PEP 3151, [1], [2], [3], [4], [5]
    • PEP 3153
    • PEP 3154, [1], [2]
    • PEP 3155, [1]
    • PEP 3156, [1], [2], [3], [4]
    • PEP 318, [1], [2], [3]
    • PEP 322, [1]
    • PEP 324, [1]
    • PEP 325
    • PEP 327
    • PEP 328, [1], [2], [3], [4], [5], [6], [7], [8], [9]
    • PEP 331
    • PEP 333, [1]
    • PEP 3333, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]
    • PEP 338, [1], [2], [3]
    • PEP 339
    • PEP 341
    • PEP 342, [1], [2], [3], [4]
    • PEP 343, [1], [2], [3], [4], [5], [6]
    • PEP 347
    • PEP 352, [1], [2]
    • PEP 353, [1], [2]
    • PEP 356
    • PEP 357
    • PEP 361
    • PEP 362, [1], [2], [3]
    • PEP 366, [1], [2], [3], [4], [5], [6]
    • PEP 370, [1], [2], [3], [4]
    • PEP 371
    • PEP 372, [1]
    • PEP 373
    • PEP 378, [1], [2]
    • PEP 380, [1]
    • PEP 383, [1], [2], [3], [4]
    • PEP 384, [1], [2]
    • PEP 385
    • PEP 389, [1]
    • PEP 391, [1]
    • PEP 392
    • PEP 393, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]
    • PEP 395
    • PEP 397, [1], [2], [3]
    • PEP 398
    • PEP 4
    • PEP 405, [1]
    • PEP 409
    • PEP 411, [1], [2], [3], [4], [5], [6]
    • PEP 412
    • PEP 414, [1]
    • PEP 418
    • PEP 420, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13]
    • PEP 421, [1]
    • PEP 424, [1]
    • PEP 427
    • PEP 428, [1], [2]
    • PEP 429
    • PEP 432
    • PEP 434
    • PEP 435, [1], [2]
    • PEP 436, [1], [2]
    • PEP 441, [1]
    • PEP 442, [1], [2], [3], [4], [5], [6]
    • PEP 443, [1], [2]
    • PEP 445, [1], [2], [3]
    • PEP 446, [1], [2], [3]
    • PEP 448, [1], [2], [3], [4]
    • PEP 450, [1], [2]
    • PEP 451, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]
    • PEP 453, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]
    • PEP 454, [1], [2]
    • PEP 456, [1]
    • PEP 461, [1], [2]
    • PEP 465, [1], [2]
    • PEP 466, [1], [2], [3]
    • PEP 468, [1]
    • PEP 471, [1]
    • PEP 475, [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]
    • PEP 476
    • PEP 477
    • PEP 478
    • PEP 479, [1], [2], [3], [4], [5], [6]
    • PEP 483, [1]
    • PEP 484, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19]
    • PEP 485, [1], [2], [3]
    • PEP 486, [1]
    • PEP 487, [1], [2], [3]
    • PEP 488, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]
    • PEP 489, [1], [2], [3], [4], [5], [6], [7], [8], [9]
    • PEP 492, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20]
    • PEP 493
    • PEP 494
    • PEP 495, [1]
    • PEP 498, [1], [2], [3]
    • PEP 5, [1]
    • PEP 506, [1]
    • PEP 511
    • PEP 515, [1], [2]
    • PEP 519, [1]
    • PEP 520
    • PEP 523, [1]
    • PEP 524, [1], [2], [3], [4], [5]
    • PEP 525, [1], [2], [3], [4], [5], [6]
    • PEP 526, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]
    • PEP 528, [1]
    • PEP 529, [1], [2], [3], [4], [5]
    • PEP 530, [1], [2]
    • PEP 538, [1], [2], [3], [4]
    • PEP 539, [1], [2]
    • PEP 540, [1], [2], [3]
    • PEP 545, [1]
    • PEP 552, [1], [2], [3], [4], [5]
    • PEP 553, [1]
    • PEP 557, [1]
    • PEP 560, [1], [2], [3], [4], [5], [6]
    • PEP 562, [1], [2], [3]
    • PEP 563, [1], [2]
    • PEP 564, [1], [2], [3]
    • PEP 565
    • PEP 567, [1], [2], [3], [4], [5], [6], [7]
    • PEP 6
    • PEP 628, [1]
    • PEP 7, [1]
    • PEP 8, [1], [2], [3], [4]
  • Python Package Index (PyPI)
    • .pypirc file
  • PYTHON*, [1], [2], [3]
  • python.function.entry (C の関数)
  • python.function.return (C の関数)
  • python_branch() (platform モジュール)
  • python_build() (platform モジュール)
  • python_compiler() (platform モジュール)
  • PYTHON_DOM
  • python_implementation() (platform モジュール)
  • python_is_optimized() (test.support モジュール)
  • python_revision() (platform モジュール)
  • python_version() (platform モジュール)
  • python_version_tuple() (platform モジュール)
  • PYTHONASYNCIODEBUG, [1]
  • PYTHONBREAKPOINT, [1], [2], [3]
  • PYTHONCASEOK
  • PYTHONCOERCECLOCALE, [1]
  • PYTHONDEBUG, [1]
  • PYTHONDEVMODE, [1]
  • PYTHONDOCS
  • PYTHONDONTWRITEBYTECODE, [1], [2], [3], [4], [5]
  • PYTHONDUMPREFS
  • PYTHONFAULTHANDLER, [1]
  • PYTHONHASHSEED, [1], [2], [3], [4], [5], [6], [7], [8]
  • PYTHONHOME, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15]
  • Pythonic
  • PYTHONINSPECT, [1], [2]
  • PYTHONIOENCODING, [1], [2], [3], [4], [5], [6]
  • PYTHONLEGACYWINDOWSFSENCODING, [1], [2]
  • PYTHONLEGACYWINDOWSSTDIO, [1], [2]
  • PYTHONMALLOC, [1], [2], [3], [4], [5], [6]
  • PYTHONMALLOCSTATS, [1]
  • PYTHONNOUSERSITE, [1], [2], [3], [4]
  • PYTHONOPTIMIZE, [1]
  • PYTHONPATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24]
  • PYTHONPROFILEIMPORTTIME, [1], [2]
  • PYTHONSHOWALLOCCOUNT
  • PYTHONSHOWREFCOUNT
  • PYTHONSTARTUP, [1], [2], [3], [4], [5], [6], [7], [8], [9]
  • PYTHONTRACEMALLOC, [1], [2]
  • PYTHONUNBUFFERED, [1]
  • PYTHONUSERBASE, [1], [2]
  • PYTHONUSERSITE
  • PYTHONUTF8, [1], [2]
  • PYTHONVERBOSE, [1]
  • PYTHONWARNINGS, [1], [2], [3], [4], [5], [6], [7]
  • PyThread_create_key (C の関数)
  • PyThread_delete_key (C の関数)
  • PyThread_delete_key_value (C の関数)
  • PyThread_get_key_value (C の関数)
  • PyThread_ReInitTLS (C の関数)
  • PyThread_set_key_value (C の関数)
  • PyThread_tss_alloc (C の関数)
  • PyThread_tss_create (C の関数)
  • PyThread_tss_delete (C の関数)
  • PyThread_tss_free (C の関数)
  • PyThread_tss_get (C の関数)
  • PyThread_tss_is_created (C の関数)
  • PyThread_tss_set (C の関数)
  • PyThreadState, [1]
    • (C のデータ型)
  • PyThreadState_Clear (C の関数)
  • PyThreadState_Delete (C の関数)
  • PyThreadState_Get (C の関数)
  • PyThreadState_GetDict (C の関数)
  • PyThreadState_New (C の関数)
  • PyThreadState_Next (C の関数)
  • PyThreadState_SetAsyncExc (C の関数)
  • PyThreadState_Swap (C の関数)
  • PyTime_Check (C の関数)
  • PyTime_CheckExact (C の関数)
  • PyTime_FromTime (C の関数)
  • PyTimeZone_FromOffset (C の関数)
  • PyTimeZone_FromOffsetAndName (C の関数)
  • PyTrace_C_CALL (C の変数)
  • PyTrace_C_EXCEPTION (C の変数)
  • PyTrace_C_RETURN (C の変数)
  • PyTrace_CALL (C の変数)
  • PyTrace_EXCEPTION (C の変数)
  • PyTrace_LINE (C の変数)
  • PyTrace_OPCODE (C の変数)
  • PyTrace_RETURN (C の変数)
  • PyTuple_Check (C の関数)
  • PyTuple_CheckExact (C の関数)
  • PyTuple_ClearFreeList (C の関数)
  • PyTuple_GET_ITEM (C の関数)
  • PyTuple_GET_SIZE (C の関数)
  • PyTuple_GetItem (C の関数)
  • PyTuple_GetSlice (C の関数)
  • PyTuple_New (C の関数)
  • PyTuple_Pack (C の関数)
  • PyTuple_SET_ITEM (C の関数)
  • PyTuple_SetItem (C の関数)
  • PyTuple_SetItem()
  • PyTuple_Size (C の関数)
  • PyTuple_Type (C の変数)
  • PyTupleObject (C のデータ型)
  • PyType_Check (C の関数)
  • PyType_CheckExact (C の関数)
  • PyType_ClearCache (C の関数)
  • PyType_FromSpec (C の関数)
  • PyType_FromSpecWithBases (C の関数)
  • PyType_GenericAlloc (C の関数)
  • PyType_GenericNew (C の関数)
  • PyType_GetFlags (C の関数)
  • PyType_GetSlot (C の関数)
  • PyType_HasFeature (C の関数)
  • PyType_IS_GC (C の関数)
  • PyType_IsSubtype (C の関数)
  • PyType_Modified (C の関数)
  • PyType_Ready (C の関数)
  • PyType_Type (C の変数)
  • PyTypeObject (C のデータ型)
  • PyTypeObject.tp_alloc (C のメンバ変数)
  • PyTypeObject.tp_allocs (C のメンバ変数)
  • PyTypeObject.tp_as_buffer (C のメンバ変数)
  • PyTypeObject.tp_base (C のメンバ変数)
  • PyTypeObject.tp_bases (C のメンバ変数)
  • PyTypeObject.tp_basicsize (C のメンバ変数)
  • PyTypeObject.tp_cache (C のメンバ変数)
  • PyTypeObject.tp_call (C のメンバ変数)
  • PyTypeObject.tp_clear (C のメンバ変数)
  • PyTypeObject.tp_dealloc (C のメンバ変数)
  • PyTypeObject.tp_descr_get (C のメンバ変数)
  • PyTypeObject.tp_descr_set (C のメンバ変数)
  • PyTypeObject.tp_dict (C のメンバ変数)
  • PyTypeObject.tp_dictoffset (C のメンバ変数)
  • PyTypeObject.tp_doc (C のメンバ変数)
  • PyTypeObject.tp_finalize (C のメンバ変数)
  • PyTypeObject.tp_flags (C のメンバ変数)
  • PyTypeObject.tp_free (C のメンバ変数)
  • PyTypeObject.tp_frees (C のメンバ変数)
  • PyTypeObject.tp_getattr (C のメンバ変数)
  • PyTypeObject.tp_getattro (C のメンバ変数)
  • PyTypeObject.tp_getset (C のメンバ変数)
  • PyTypeObject.tp_hash (C のメンバ変数)
  • PyTypeObject.tp_init (C のメンバ変数)
  • PyTypeObject.tp_is_gc (C のメンバ変数)
  • PyTypeObject.tp_itemsize (C のメンバ変数)
  • PyTypeObject.tp_iter (C のメンバ変数)
  • PyTypeObject.tp_iternext (C のメンバ変数)
  • PyTypeObject.tp_maxalloc (C のメンバ変数)
  • PyTypeObject.tp_members (C のメンバ変数)
  • PyTypeObject.tp_methods (C のメンバ変数)
  • PyTypeObject.tp_mro (C のメンバ変数)
  • PyTypeObject.tp_name (C のメンバ変数)
  • PyTypeObject.tp_new (C のメンバ変数)
  • PyTypeObject.tp_next (C のメンバ変数)
  • PyTypeObject.tp_print (C のメンバ変数)
  • PyTypeObject.tp_repr (C のメンバ変数)
  • PyTypeObject.tp_richcompare (C のメンバ変数)
  • PyTypeObject.tp_setattr (C のメンバ変数)
  • PyTypeObject.tp_setattro (C のメンバ変数)
  • PyTypeObject.tp_str (C のメンバ変数)
  • PyTypeObject.tp_subclasses (C のメンバ変数)
  • PyTypeObject.tp_traverse (C のメンバ変数)
  • PyTypeObject.tp_weaklist (C のメンバ変数)
  • PyTypeObject.tp_weaklistoffset (C のメンバ変数)
  • PyTZInfo_Check (C の関数)
  • PyTZInfo_CheckExact (C の関数)
  • PyUnicode_1BYTE_DATA (C の関数)
  • PyUnicode_1BYTE_KIND (C のマクロ)
  • PyUnicode_2BYTE_DATA (C の関数)
  • PyUnicode_2BYTE_KIND (C のマクロ)
  • PyUnicode_4BYTE_DATA (C の関数)
  • PyUnicode_4BYTE_KIND (C のマクロ)
  • PyUnicode_AS_DATA (C の関数)
  • PyUnicode_AS_UNICODE (C の関数)
  • PyUnicode_AsASCIIString (C の関数)
  • PyUnicode_AsCharmapString (C の関数)
  • PyUnicode_AsEncodedString (C の関数)
  • PyUnicode_AsLatin1String (C の関数)
  • PyUnicode_AsMBCSString (C の関数)
  • PyUnicode_AsRawUnicodeEscapeString (C の関数)
  • PyUnicode_AsUCS4 (C の関数)
  • PyUnicode_AsUCS4Copy (C の関数)
  • PyUnicode_AsUnicode (C の関数)
  • PyUnicode_AsUnicodeAndSize (C の関数)
  • PyUnicode_AsUnicodeCopy (C の関数)
  • PyUnicode_AsUnicodeEscapeString (C の関数)
  • PyUnicode_AsUTF16String (C の関数)
  • PyUnicode_AsUTF32String (C の関数)
  • PyUnicode_AsUTF8 (C の関数)
  • PyUnicode_AsUTF8AndSize (C の関数)
  • PyUnicode_AsUTF8String (C の関数)
  • PyUnicode_AsWideChar (C の関数)
  • PyUnicode_AsWideCharString (C の関数)
  • PyUnicode_Check (C の関数)
  • PyUnicode_CheckExact (C の関数)
  • PyUnicode_ClearFreeList (C の関数)
  • PyUnicode_Compare (C の関数)
  • PyUnicode_CompareWithASCIIString (C の関数)
  • PyUnicode_Concat (C の関数)
  • PyUnicode_Contains (C の関数)
  • PyUnicode_CopyCharacters (C の関数)
  • PyUnicode_Count (C の関数)
  • PyUnicode_DATA (C の関数)
  • PyUnicode_Decode (C の関数)
  • PyUnicode_DecodeASCII (C の関数)
  • PyUnicode_DecodeCharmap (C の関数)
  • PyUnicode_DecodeFSDefault (C の関数)
  • PyUnicode_DecodeFSDefaultAndSize (C の関数)
  • PyUnicode_DecodeLatin1 (C の関数)
  • PyUnicode_DecodeLocale (C の関数)
  • PyUnicode_DecodeLocaleAndSize (C の関数)
  • PyUnicode_DecodeMBCS (C の関数)
  • PyUnicode_DecodeMBCSStateful (C の関数)
  • PyUnicode_DecodeRawUnicodeEscape (C の関数)
  • PyUnicode_DecodeUnicodeEscape (C の関数)
  • PyUnicode_DecodeUTF16 (C の関数)
  • PyUnicode_DecodeUTF16Stateful (C の関数)
  • PyUnicode_DecodeUTF32 (C の関数)
  • PyUnicode_DecodeUTF32Stateful (C の関数)
  • PyUnicode_DecodeUTF7 (C の関数)
  • PyUnicode_DecodeUTF7Stateful (C の関数)
  • PyUnicode_DecodeUTF8 (C の関数)
  • PyUnicode_DecodeUTF8Stateful (C の関数)
  • PyUnicode_Encode (C の関数)
  • PyUnicode_EncodeASCII (C の関数)
  • PyUnicode_EncodeCharmap (C の関数)
  • PyUnicode_EncodeCodePage (C の関数)
  • PyUnicode_EncodeFSDefault (C の関数)
  • PyUnicode_EncodeLatin1 (C の関数)
  • PyUnicode_EncodeLocale (C の関数)
  • PyUnicode_EncodeMBCS (C の関数)
  • PyUnicode_EncodeRawUnicodeEscape (C の関数)
  • PyUnicode_EncodeUnicodeEscape (C の関数)
  • PyUnicode_EncodeUTF16 (C の関数)
  • PyUnicode_EncodeUTF32 (C の関数)
  • PyUnicode_EncodeUTF7 (C の関数)
  • PyUnicode_EncodeUTF8 (C の関数)
  • PyUnicode_Fill (C の関数)
  • PyUnicode_Find (C の関数)
  • PyUnicode_FindChar (C の関数)
  • PyUnicode_Format (C の関数)
  • PyUnicode_FromEncodedObject (C の関数)
  • PyUnicode_FromFormat (C の関数)
  • PyUnicode_FromFormatV (C の関数)
  • PyUnicode_FromKindAndData (C の関数)
  • PyUnicode_FromObject (C の関数)
  • PyUnicode_FromString (C の関数)
  • PyUnicode_FromString()
  • PyUnicode_FromStringAndSize (C の関数)
  • PyUnicode_FromUnicode (C の関数)
  • PyUnicode_FromWideChar (C の関数)
  • PyUnicode_FSConverter (C の関数)
  • PyUnicode_FSDecoder (C の関数)
  • PyUnicode_GET_DATA_SIZE (C の関数)
  • PyUnicode_GET_LENGTH (C の関数)
  • PyUnicode_GET_SIZE (C の関数)
  • PyUnicode_GetLength (C の関数)
  • PyUnicode_GetSize (C の関数)
  • PyUnicode_InternFromString (C の関数)
  • PyUnicode_InternInPlace (C の関数)
  • PyUnicode_Join (C の関数)
  • PyUnicode_KIND (C の関数)
  • PyUnicode_MAX_CHAR_VALUE (C の関数)
  • PyUnicode_New (C の関数)
  • PyUnicode_READ (C の関数)
  • PyUnicode_READ_CHAR (C の関数)
  • PyUnicode_ReadChar (C の関数)
  • PyUnicode_READY (C の関数)
  • PyUnicode_Replace (C の関数)
  • PyUnicode_RichCompare (C の関数)
  • PyUnicode_Split (C の関数)
  • PyUnicode_Splitlines (C の関数)
  • PyUnicode_Substring (C の関数)
  • PyUnicode_Tailmatch (C の関数)
  • PyUnicode_TransformDecimalToASCII (C の関数)
  • PyUnicode_Translate (C の関数), [1]
  • PyUnicode_TranslateCharmap (C の関数)
  • PyUnicode_Type (C の変数)
  • PyUnicode_WCHAR_KIND (C のマクロ)
  • PyUnicode_WRITE (C の関数)
  • PyUnicode_WriteChar (C の関数)
  • PyUnicodeDecodeError_Create (C の関数)
  • PyUnicodeDecodeError_GetEncoding (C の関数)
  • PyUnicodeDecodeError_GetEnd (C の関数)
  • PyUnicodeDecodeError_GetObject (C の関数)
  • PyUnicodeDecodeError_GetReason (C の関数)
  • PyUnicodeDecodeError_GetStart (C の関数)
  • PyUnicodeDecodeError_SetEnd (C の関数)
  • PyUnicodeDecodeError_SetReason (C の関数)
  • PyUnicodeDecodeError_SetStart (C の関数)
  • PyUnicodeEncodeError_Create (C の関数)
  • PyUnicodeEncodeError_GetEncoding (C の関数)
  • PyUnicodeEncodeError_GetEnd (C の関数)
  • PyUnicodeEncodeError_GetObject (C の関数)
  • PyUnicodeEncodeError_GetReason (C の関数)
  • PyUnicodeEncodeError_GetStart (C の関数)
  • PyUnicodeEncodeError_SetEnd (C の関数)
  • PyUnicodeEncodeError_SetReason (C の関数)
  • PyUnicodeEncodeError_SetStart (C の関数)
  • PyUnicodeObject (C のデータ型)
  • PyUnicodeTranslateError_Create (C の関数)
  • PyUnicodeTranslateError_GetEnd (C の関数)
  • PyUnicodeTranslateError_GetObject (C の関数)
  • PyUnicodeTranslateError_GetReason (C の関数)
  • PyUnicodeTranslateError_GetStart (C の関数)
  • PyUnicodeTranslateError_SetEnd (C の関数)
  • PyUnicodeTranslateError_SetReason (C の関数)
  • PyUnicodeTranslateError_SetStart (C の関数)
  • PyVarObject (C のデータ型)
  • PyVarObject.ob_size (C のメンバ変数)
  • PyVarObject_HEAD_INIT (C のマクロ)
  • PyWeakref_Check (C の関数)
  • PyWeakref_CheckProxy (C の関数)
  • PyWeakref_CheckRef (C の関数)
  • PyWeakref_GET_OBJECT (C の関数)
  • PyWeakref_GetObject (C の関数)
  • PyWeakref_NewProxy (C の関数)
  • PyWeakref_NewRef (C の関数)
  • PyWrapper_New (C の関数)
  • PyZipFile (zipfile のクラス)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – Q

  • qiflush() (curses モジュール)
  • QName (xml.etree.ElementTree のクラス)
  • qsize() (asyncio.Queue のメソッド)
    • (multiprocessing.Queue のメソッド)
    • (queue.Queue のメソッド)
    • (queue.SimpleQueue のメソッド)
  • qualified name
  • quantize() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • QueryInfoKey() (winreg モジュール)
  • QueryReflectionKey() (winreg モジュール)
  • QueryValue() (winreg モジュール)
  • QueryValueEx() (winreg モジュール)
  • Queue (asyncio のクラス)
    • (multiprocessing のクラス)
    • (queue のクラス)
  • queue (sched.scheduler の属性)
    • (モジュール)
  • Queue() (multiprocessing.managers.SyncManager のメソッド)
  • QueueEmpty
  • QueueFull
  • QueueHandler (logging.handlers のクラス)
  • QueueListener (logging.handlers のクラス)
  • quick_ratio() (difflib.SequenceMatcher のメソッド)
  • quit (pdb command)
    • (組み込み変数)
  • quit() (ftplib.FTP のメソッド)
    • (nntplib.NNTP のメソッド)
    • (poplib.POP3 のメソッド)
    • (smtplib.SMTP のメソッド)
  • quopri (モジュール)
  • quote() (email.utils モジュール)
    • (shlex モジュール)
    • (urllib.parse モジュール)
  • QUOTE_ALL (csv モジュール)
  • quote_from_bytes() (urllib.parse モジュール)
  • QUOTE_MINIMAL (csv モジュール)
  • QUOTE_NONE (csv モジュール)
  • QUOTE_NONNUMERIC (csv モジュール)
  • quote_plus() (urllib.parse モジュール)
  • quoteattr() (xml.sax.saxutils モジュール)
  • quotechar (csv.Dialect の属性)
  • quoted-printable
    • encoding
  • quotes (shlex.shlex の属性)
  • quoting (csv.Dialect の属性)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – R

  • r"
    • raw string literal
  • r'
    • raw string literal
  • R_OK (os モジュール)
  • radians() (math モジュール)
    • (turtle モジュール)
  • RadioButtonGroup (msilib のクラス)
  • radiogroup() (msilib.Dialog のメソッド)
  • radix() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • RADIXCHAR (locale モジュール)
  • raise
    • 文, [1]
  • raise (2to3 fixer)
  • raise an exception
  • raise_on_defect (email.policy.Policy の属性)
  • RAISE_VARARGS (opcode)
  • raising
    • exception
  • RAND_add() (ssl モジュール)
  • RAND_bytes() (ssl モジュール)
  • RAND_egd() (ssl モジュール)
  • RAND_pseudo_bytes() (ssl モジュール)
  • RAND_status() (ssl モジュール)
  • randbelow() (secrets モジュール)
  • randbits() (secrets モジュール)
  • randint() (random モジュール)
  • random (モジュール)
  • random() (random モジュール)
  • randrange() (random モジュール)
  • range
    • オブジェクト
    • 組み込み関数
  • range (組み込みクラス)
  • RARROW (token モジュール)
  • ratecv() (audioop モジュール)
  • ratio() (difflib.SequenceMatcher のメソッド)
  • Rational (numbers のクラス)
  • raw (io.BufferedIOBase の属性)
  • raw string
  • raw() (curses モジュール)
  • raw_data_manager (email.contentmanager モジュール)
  • raw_decode() (json.JSONDecoder のメソッド)
  • raw_input (2to3 fixer)
  • raw_input() (code.InteractiveConsole のメソッド)
  • RawArray() (multiprocessing.sharedctypes モジュール)
  • RawConfigParser (configparser のクラス)
  • RawDescriptionHelpFormatter (argparse のクラス)
  • RawIOBase (io のクラス)
  • RawPen (turtle のクラス)
  • RawTextHelpFormatter (argparse のクラス)
  • RawTurtle (turtle のクラス)
  • RawValue() (multiprocessing.sharedctypes モジュール)
  • RBRACE (token モジュール)
  • rcpttos (smtpd.SMTPChannel の属性)
  • re
    • モジュール, [1]
  • re (re.Match の属性)
    • (モジュール)
  • read() (asyncio.StreamReader のメソッド)
    • (chunk.Chunk のメソッド)
    • (codecs.StreamReader のメソッド)
    • (configparser.ConfigParser のメソッド)
    • (http.client.HTTPResponse のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (io.BufferedIOBase のメソッド)
    • (io.BufferedReader のメソッド)
    • (io.RawIOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (mimetypes.MimeTypes のメソッド)
    • (mmap.mmap のメソッド)
    • (os モジュール)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (ssl.MemoryBIO のメソッド)
    • (ssl.SSLSocket のメソッド)
    • (urllib.robotparser.RobotFileParser のメソッド)
    • (zipfile.ZipFile のメソッド)
  • read1() (io.BufferedIOBase のメソッド)
    • (io.BufferedReader のメソッド)
    • (io.BytesIO のメソッド)
  • read_all() (telnetlib.Telnet のメソッド)
  • read_binary() (importlib.resources モジュール)
  • read_byte() (mmap.mmap のメソッド)
  • read_bytes() (pathlib.Path のメソッド)
  • read_dict() (configparser.ConfigParser のメソッド)
  • read_eager() (telnetlib.Telnet のメソッド)
  • read_environ() (wsgiref.handlers モジュール)
  • read_events() (xml.etree.ElementTree.XMLPullParser のメソッド)
  • read_file() (configparser.ConfigParser のメソッド)
  • read_history_file() (readline モジュール)
  • read_init_file() (readline モジュール)
  • read_lazy() (telnetlib.Telnet のメソッド)
  • read_mime_types() (mimetypes モジュール)
  • READ_RESTRICTED
  • read_sb_data() (telnetlib.Telnet のメソッド)
  • read_some() (telnetlib.Telnet のメソッド)
  • read_string() (configparser.ConfigParser のメソッド)
  • read_text() (importlib.resources モジュール)
    • (pathlib.Path のメソッド)
  • read_token() (shlex.shlex のメソッド)
  • read_until() (telnetlib.Telnet のメソッド)
  • read_very_eager() (telnetlib.Telnet のメソッド)
  • read_very_lazy() (telnetlib.Telnet のメソッド)
  • read_windows_registry() (mimetypes.MimeTypes のメソッド)
  • READABLE (tkinter モジュール)
  • readable() (asyncore.dispatcher のメソッド)
    • (io.IOBase のメソッド)
  • readall() (io.RawIOBase のメソッド)
  • reader() (csv モジュール)
  • ReadError
  • readexactly() (asyncio.StreamReader のメソッド)
  • readfp() (configparser.ConfigParser のメソッド)
    • (mimetypes.MimeTypes のメソッド)
  • readframes() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • readinto() (http.client.HTTPResponse のメソッド)
    • (io.BufferedIOBase のメソッド)
    • (io.RawIOBase のメソッド)
  • readinto1() (io.BufferedIOBase のメソッド)
    • (io.BytesIO のメソッド)
  • readline (モジュール)
  • readline() (asyncio.StreamReader のメソッド)
    • (codecs.StreamReader のメソッド)
    • (distutils.text_file.TextFile のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (io.IOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (mmap.mmap のメソッド)
  • readlines() (codecs.StreamReader のメソッド)
    • (distutils.text_file.TextFile のメソッド)
    • (io.IOBase のメソッド)
  • readlink() (os モジュール)
  • readmodule() (pyclbr モジュール)
  • readmodule_ex() (pyclbr モジュール)
  • READONLY
  • readonly (memoryview の属性)
  • readPlist() (plistlib モジュール)
  • readPlistFromBytes() (plistlib モジュール)
  • ReadTransport (asyncio のクラス)
  • readuntil() (asyncio.StreamReader のメソッド)
  • readv() (os モジュール)
  • ready() (multiprocessing.pool.AsyncResult のメソッド)
  • Real (numbers のクラス)
  • real (numbers.Complex の属性)
  • Real Media File Format
  • real_max_memuse (test.support モジュール)
  • real_quick_ratio() (difflib.SequenceMatcher のメソッド)
  • realloc()
  • realpath() (os.path モジュール)
  • REALTIME_PRIORITY_CLASS (subprocess モジュール)
  • reap_children() (test.support モジュール)
  • reap_threads() (test.support モジュール)
  • reason (http.client.HTTPResponse の属性)
    • (UnicodeError の属性)
    • (ssl.SSLError の属性)
    • (urllib.error.HTTPError の属性)
    • (urllib.error.URLError の属性)
  • reattach() (tkinter.ttk.Treeview のメソッド)
  • rebinding
    • name
  • reccontrols() (ossaudiodev.oss_mixer_device のメソッド)
  • received_data (smtpd.SMTPChannel の属性)
  • received_lines (smtpd.SMTPChannel の属性)
  • recent() (imaplib.IMAP4 のメソッド)
  • reconfigure() (io.TextIOWrapper のメソッド)
  • record_original_stdout() (test.support モジュール)
  • records (unittest.TestCase の属性)
  • rect() (cmath モジュール)
  • rectangle() (curses.textpad モジュール)
  • RecursionError
  • recursive_repr() (reprlib モジュール)
  • recv() (asyncore.dispatcher のメソッド)
    • (multiprocessing.connection.Connection のメソッド)
    • (socket.socket のメソッド)
  • recv_bytes() (multiprocessing.connection.Connection のメソッド)
  • recv_bytes_into() (multiprocessing.connection.Connection のメソッド)
  • recv_into() (socket.socket のメソッド)
  • recvfrom() (socket.socket のメソッド)
  • recvfrom_into() (socket.socket のメソッド)
  • recvmsg() (socket.socket のメソッド)
  • recvmsg_into() (socket.socket のメソッド)
  • redirect_request() (urllib.request.HTTPRedirectHandler のメソッド)
  • redirect_stderr() (contextlib モジュール)
  • redirect_stdout() (contextlib モジュール)
  • redisplay() (readline モジュール)
  • redrawln() (curses.window のメソッド)
  • redrawwin() (curses.window のメソッド)
  • reduce (2to3 fixer)
  • reduce() (functools モジュール)
  • ref (weakref のクラス)
  • refcount_test() (test.support モジュール)
  • reference
    • attribute
  • reference count
  • reference counting
  • ReferenceError, [1]
  • ReferenceType (weakref モジュール)
  • refold_source (email.policy.EmailPolicy の属性)
  • refresh() (curses.window のメソッド)
  • REG_BINARY (winreg モジュール)
  • REG_DWORD (winreg モジュール)
  • REG_DWORD_BIG_ENDIAN (winreg モジュール)
  • REG_DWORD_LITTLE_ENDIAN (winreg モジュール)
  • REG_EXPAND_SZ (winreg モジュール)
  • REG_FULL_RESOURCE_DESCRIPTOR (winreg モジュール)
  • REG_LINK (winreg モジュール)
  • REG_MULTI_SZ (winreg モジュール)
  • REG_NONE (winreg モジュール)
  • REG_QWORD (winreg モジュール)
  • REG_QWORD_LITTLE_ENDIAN (winreg モジュール)
  • REG_RESOURCE_LIST (winreg モジュール)
  • REG_RESOURCE_REQUIREMENTS_LIST (winreg モジュール)
  • REG_SZ (winreg モジュール)
  • register() (abc.ABCMeta のメソッド)
    • (atexit モジュール)
    • (codecs モジュール)
    • (faulthandler モジュール)
    • (multiprocessing.managers.BaseManager のメソッド)
    • (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.poll のメソッド)
    • (selectors.BaseSelector のメソッド)
    • (webbrowser モジュール)
  • register_adapter() (sqlite3 モジュール)
  • register_archive_format() (shutil モジュール)
  • register_at_fork() (os モジュール)
  • register_converter() (sqlite3 モジュール)
  • register_defect() (email.policy.Policy のメソッド)
  • register_dialect() (csv モジュール)
  • register_error() (codecs モジュール)
  • register_function() (xmlrpc.server.CGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.SimpleXMLRPCServer のメソッド)
  • register_instance() (xmlrpc.server.CGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.SimpleXMLRPCServer のメソッド)
  • register_introspection_functions() (xmlrpc.server.CGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.SimpleXMLRPCServer のメソッド)
  • register_multicall_functions() (xmlrpc.server.CGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.SimpleXMLRPCServer のメソッド)
  • register_namespace() (xml.etree.ElementTree モジュール)
  • register_optionflag() (doctest モジュール)
  • register_shape() (turtle モジュール)
  • register_unpack_format() (shutil モジュール)
  • registerDOMImplementation() (xml.dom モジュール)
  • registerResult() (unittest モジュール)
  • regular
    • package
  • regular package
  • relative
    • URL
    • import
  • relative_to() (pathlib.PurePath のメソッド)
  • release() (_thread.lock のメソッド)
    • (asyncio.Condition のメソッド)
    • (asyncio.Lock のメソッド)
    • (asyncio.Semaphore のメソッド)
    • (logging.Handler のメソッド)
    • (memoryview のメソッド)
    • (multiprocessing.Lock のメソッド)
    • (multiprocessing.RLock のメソッド)
    • (platform モジュール)
    • (threading.Condition のメソッド)
    • (threading.Lock のメソッド)
    • (threading.RLock のメソッド)
    • (threading.Semaphore のメソッド)
  • release_lock() (imp モジュール)
  • reload (2to3 fixer)
  • reload() (imp モジュール)
    • (importlib モジュール)
  • relpath() (os.path モジュール)
  • remainder() (decimal.Context のメソッド)
    • (math モジュール)
  • remainder_near() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • RemoteDisconnected
  • remove() (array.array のメソッド)
    • (collections.deque のメソッド)
    • (frozenset のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (os モジュール)
    • (sequence method)
    • (xml.etree.ElementTree.Element のメソッド)
  • remove_child_handler() (asyncio.AbstractChildWatcher のメソッド)
  • remove_done_callback() (asyncio.Future のメソッド)
    • (asyncio.Task のメソッド)
  • remove_flag() (mailbox.MaildirMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
    • (mailbox.mboxMessage のメソッド)
  • remove_folder() (mailbox.Maildir のメソッド)
    • (mailbox.MH のメソッド)
  • remove_header() (urllib.request.Request のメソッド)
  • remove_history_item() (readline モジュール)
  • remove_label() (mailbox.BabylMessage のメソッド)
  • remove_option() (configparser.ConfigParser のメソッド)
    • (optparse.OptionParser のメソッド)
  • remove_pyc() (msilib.Directory のメソッド)
  • remove_reader() (asyncio.loop のメソッド)
  • remove_section() (configparser.ConfigParser のメソッド)
  • remove_sequence() (mailbox.MHMessage のメソッド)
  • remove_signal_handler() (asyncio.loop のメソッド)
  • remove_tree() (distutils.dir_util モジュール)
  • remove_writer() (asyncio.loop のメソッド)
  • removeAttribute() (xml.dom.Element のメソッド)
  • removeAttributeNode() (xml.dom.Element のメソッド)
  • removeAttributeNS() (xml.dom.Element のメソッド)
  • removeChild() (xml.dom.Node のメソッド)
  • removedirs() (os モジュール)
  • removeFilter() (logging.Handler のメソッド)
    • (logging.Logger のメソッド)
  • removeHandler() (logging.Logger のメソッド)
    • (unittest モジュール)
  • removeResult() (unittest モジュール)
  • removexattr() (os モジュール)
  • rename() (ftplib.FTP のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (os モジュール)
    • (pathlib.Path のメソッド)
  • renames (2to3 fixer)
  • renames() (os モジュール)
  • reopenIfNeeded() (logging.handlers.WatchedFileHandler のメソッド)
  • reorganize() (dbm.gnu.gdbm のメソッド)
  • repeat() (itertools モジュール)
    • (timeit モジュール)
    • (timeit.Timer のメソッド)
  • repetition
    • operation
  • replace() (bytearray のメソッド)
    • (bytes のメソッド)
    • (curses.panel.Panel のメソッド)
    • (dataclasses モジュール)
    • (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (inspect.Parameter のメソッド)
    • (inspect.Signature のメソッド)
    • (os モジュール)
    • (pathlib.Path のメソッド)
    • (str のメソッド)
  • replace_errors() (codecs モジュール)
  • replace_header() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • replace_history_item() (readline モジュール)
  • replace_whitespace (textwrap.TextWrapper の属性)
  • replaceChild() (xml.dom.Node のメソッド)
  • ReplacePackage() (modulefinder モジュール)
  • report() (filecmp.dircmp のメソッド)
    • (modulefinder.ModuleFinder のメソッド)
  • REPORT_CDIFF (doctest モジュール)
  • report_failure() (doctest.DocTestRunner のメソッド)
  • report_full_closure() (filecmp.dircmp のメソッド)
  • REPORT_NDIFF (doctest モジュール)
  • REPORT_ONLY_FIRST_FAILURE (doctest モジュール)
  • report_partial_closure() (filecmp.dircmp のメソッド)
  • report_start() (doctest.DocTestRunner のメソッド)
  • report_success() (doctest.DocTestRunner のメソッド)
  • REPORT_UDIFF (doctest モジュール)
  • report_unexpected_exception() (doctest.DocTestRunner のメソッド)
  • REPORTING_FLAGS (doctest モジュール)
  • repr
    • 組み込み関数, [1], [2], [3]
  • repr (2to3 fixer)
  • Repr (reprlib のクラス)
  • repr() (built-in function)
    • __repr__() (object method)
  • repr() (reprlib モジュール)
    • (reprlib.Repr のメソッド)
    • (組み込み関数)
  • repr1() (reprlib.Repr のメソッド)
  • representation
    • integer
  • reprlib (モジュール)
  • Request (urllib.request のクラス)
  • request() (http.client.HTTPConnection のメソッド)
  • request_queue_size (socketserver.BaseServer の属性)
  • request_rate() (urllib.robotparser.RobotFileParser のメソッド)
  • request_uri() (wsgiref.util モジュール)
  • request_version (http.server.BaseHTTPRequestHandler の属性)
  • RequestHandlerClass (socketserver.BaseServer の属性)
  • requestline (http.server.BaseHTTPRequestHandler の属性)
  • requires() (test.support モジュール)
  • requires_bz2() (test.support モジュール)
  • requires_docstrings() (test.support モジュール)
  • requires_freebsd_version() (test.support モジュール)
  • requires_gzip() (test.support モジュール)
  • requires_IEEE_754() (test.support モジュール)
  • requires_linux_version() (test.support モジュール)
  • requires_lzma() (test.support モジュール)
  • requires_mac_version() (test.support モジュール)
  • requires_resource() (test.support モジュール)
  • requires_zlib() (test.support モジュール)
  • reserved (zipfile.ZipInfo の属性)
  • reserved word
  • RESERVED_FUTURE (uuid モジュール)
  • RESERVED_MICROSOFT (uuid モジュール)
  • RESERVED_NCS (uuid モジュール)
  • reset() (bdb.Bdb のメソッド)
    • (codecs.IncrementalDecoder のメソッド)
    • (codecs.IncrementalEncoder のメソッド)
    • (codecs.StreamReader のメソッド)
    • (codecs.StreamWriter のメソッド)
    • (contextvars.ContextVar のメソッド)
    • (html.parser.HTMLParser のメソッド)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (pipes.Template のメソッド)
    • (threading.Barrier のメソッド)
    • (turtle モジュール), [1]
    • (xdrlib.Packer のメソッド)
    • (xdrlib.Unpacker のメソッド)
    • (xml.dom.pulldom.DOMEventStream のメソッド)
    • (xml.sax.xmlreader.IncrementalParser のメソッド)
  • reset_mock() (unittest.mock.Mock のメソッド)
  • reset_prog_mode() (curses モジュール)
  • reset_shell_mode() (curses モジュール)
  • resetbuffer() (code.InteractiveConsole のメソッド)
  • resetlocale() (locale モジュール)
  • resetscreen() (turtle モジュール)
  • resetty() (curses モジュール)
  • resetwarnings() (warnings モジュール)
  • resize() (ctypes モジュール)
    • (curses.window のメソッド)
    • (mmap.mmap のメソッド)
  • resize_term() (curses モジュール)
  • resizemode() (turtle モジュール)
  • resizeterm() (curses モジュール)
  • resolution (datetime.date の属性)
    • (datetime.datetime の属性)
    • (datetime.time の属性)
    • (datetime.timedelta の属性)
  • resolve() (pathlib.Path のメソッド)
  • resolve_bases() (types モジュール)
  • resolve_name() (importlib.util モジュール)
  • resolveEntity() (xml.sax.handler.EntityResolver のメソッド)
  • Resource (importlib.resources モジュール)
  • resource (モジュール)
  • resource_path() (importlib.abc.ResourceReader のメソッド)
  • ResourceDenied
  • ResourceLoader (importlib.abc のクラス)
  • ResourceReader (importlib.abc のクラス)
  • ResourceWarning
  • response (nntplib.NNTPError の属性)
  • response() (imaplib.IMAP4 のメソッド)
  • ResponseNotReady
  • responses (http.client モジュール)
    • (http.server.BaseHTTPRequestHandler の属性)
  • restart (pdb command)
  • restore() (difflib モジュール)
  • RESTRICTED
  • restricted
    • execution
  • restype (ctypes._FuncPtr の属性)
  • result() (asyncio.Future のメソッド)
    • (asyncio.Task のメソッド)
    • (concurrent.futures.Future のメソッド)
  • results() (trace.Trace のメソッド)
  • resume_reading() (asyncio.ReadTransport のメソッド)
  • resume_writing() (asyncio.BaseProtocol のメソッド)
  • retr() (poplib.POP3 のメソッド)
  • retrbinary() (ftplib.FTP のメソッド)
  • retrieve() (urllib.request.URLopener のメソッド)
  • retrlines() (ftplib.FTP のメソッド)
  • return
    • 文, [1], [2]
  • return (pdb command)
  • return_annotation (inspect.Signature の属性)
  • return_ok() (http.cookiejar.CookiePolicy のメソッド)
  • RETURN_VALUE (opcode)
  • return_value (unittest.mock.Mock の属性)
  • returncode (asyncio.asyncio.subprocess.Process の属性)
    • (subprocess.CalledProcessError の属性)
    • (subprocess.CompletedProcess の属性)
    • (subprocess.Popen の属性)
  • reverse() (array.array のメソッド)
    • (audioop モジュール)
    • (collections.deque のメソッド)
    • (sequence method)
  • reverse_order() (pstats.Stats のメソッド)
  • reverse_pointer (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv6Address の属性)
  • reversed() (組み込み関数)
  • Reversible (collections.abc のクラス)
    • (typing のクラス)
  • revert() (http.cookiejar.FileCookieJar のメソッド)
  • rewind() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (wave.Wave_read のメソッド)
  • RFC
    • RFC 1014, [1]
    • RFC 1123
    • RFC 1321
    • RFC 1422, [1]
    • RFC 1521, [1], [2]
    • RFC 1522, [1], [2]
    • RFC 1524, [1]
    • RFC 1730
    • RFC 1738
    • RFC 1750
    • RFC 1766, [1]
    • RFC 1808, [1], [2]
    • RFC 1832, [1]
    • RFC 1869, [1]
    • RFC 1870, [1], [2]
    • RFC 1939, [1]
    • RFC 2033
    • RFC 2045, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]
    • RFC 2045#section-6.8
    • RFC 2046, [1], [2]
    • RFC 2047, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]
    • RFC 2060, [1]
    • RFC 2068
    • RFC 2087, [1], [2]
    • RFC 2104, [1]
    • RFC 2109, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15]
    • RFC 2183, [1], [2]
    • RFC 2231, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]
    • RFC 2295
    • RFC 2342, [1]
    • RFC 2368
    • RFC 2373, [1], [2]
    • RFC 2396, [1], [2], [3], [4]
    • RFC 2397
    • RFC 2449
    • RFC 2487
    • RFC 2518
    • RFC 2595, [1]
    • RFC 2616, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]
    • RFC 2732, [1], [2]
    • RFC 2774
    • RFC 2818, [1]
    • RFC 2822, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17]
    • RFC 2964
    • RFC 2965, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19]
    • RFC 2980, [1]
    • RFC 3056
    • RFC 3171
    • RFC 3207
    • RFC 3229
    • RFC 3280
    • RFC 3330
    • RFC 3454, [1]
    • RFC 3490, [1], [2], [3]
    • RFC 3490#section-3.1
    • RFC 3492, [1]
    • RFC 3493
    • RFC 3501
    • RFC 3542, [1]
    • RFC 3548, [1], [2], [3], [4], [5]
    • RFC 3659
    • RFC 3879
    • RFC 3927
    • RFC 3977, [1], [2], [3], [4]
    • RFC 3986, [1], [2], [3], [4], [5], [6], [7]
    • RFC 4086
    • RFC 4122, [1], [2], [3], [4], [5], [6], [7], [8]
    • RFC 4180
    • RFC 4193
    • RFC 4217
    • RFC 4291
    • RFC 4366
    • RFC 4380
    • RFC 4627, [1]
    • RFC 4642
    • RFC 4918, [1], [2], [3], [4]
    • RFC 4954, [1]
    • RFC 5161, [1]
    • RFC 5233
    • RFC 5246, [1]
    • RFC 5280, [1], [2], [3], [4]
    • RFC 5321, [1], [2], [3], [4]
    • RFC 5322, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21]
    • RFC 5424, [1], [2], [3]
    • RFC 5424#section-6
    • RFC 5735
    • RFC 5802
    • RFC 5842, [1]
    • RFC 5929
    • RFC 6066, [1], [2]
    • RFC 6125, [1]
    • RFC 6152, [1]
    • RFC 6531, [1], [2], [3], [4], [5], [6], [7], [8]
    • RFC 6532, [1], [2], [3]
    • RFC 6585, [1], [2], [3]
    • RFC 6855, [1], [2], [3]
    • RFC 6856, [1]
    • RFC 7159, [1], [2]
    • RFC 7230, [1]
    • RFC 7231, [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], [31], [32], [33], [34]
    • RFC 7232, [1]
    • RFC 7233, [1]
    • RFC 7235, [1]
    • RFC 7238
    • RFC 7301, [1], [2]
    • RFC 7525
    • RFC 7540
    • RFC 7693
    • RFC 7914
    • RFC 821, [1]
    • RFC 822, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]
    • RFC 854, [1]
    • RFC 959, [1]
    • RFC 977
  • rfc2109 (http.cookiejar.Cookie の属性)
  • rfc2109_as_netscape (http.cookiejar.DefaultCookiePolicy の属性)
  • rfc2965 (http.cookiejar.CookiePolicy の属性)
  • rfc822_escape() (distutils.util モジュール)
  • RFC_4122 (uuid モジュール)
  • rfile (http.server.BaseHTTPRequestHandler の属性)
  • rfind() (bytearray のメソッド)
    • (bytes のメソッド)
    • (mmap.mmap のメソッド)
    • (str のメソッド)
  • rgb_to_hls() (colorsys モジュール)
  • rgb_to_hsv() (colorsys モジュール)
  • rgb_to_yiq() (colorsys モジュール)
  • rglob() (pathlib.Path のメソッド)
  • right (filecmp.dircmp の属性)
  • right() (turtle モジュール)
  • right_list (filecmp.dircmp の属性)
  • right_only (filecmp.dircmp の属性)
  • RIGHTSHIFT (token モジュール)
  • RIGHTSHIFTEQUAL (token モジュール)
  • rindex() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • rjust() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • rlcompleter (モジュール)
  • rlecode_hqx() (binascii モジュール)
  • rledecode_hqx() (binascii モジュール)
  • RLIM_INFINITY (resource モジュール)
  • RLIMIT_AS (resource モジュール)
  • RLIMIT_CORE (resource モジュール)
  • RLIMIT_CPU (resource モジュール)
  • RLIMIT_DATA (resource モジュール)
  • RLIMIT_FSIZE (resource モジュール)
  • RLIMIT_MEMLOCK (resource モジュール)
  • RLIMIT_MSGQUEUE (resource モジュール)
  • RLIMIT_NICE (resource モジュール)
  • RLIMIT_NOFILE (resource モジュール)
  • RLIMIT_NPROC (resource モジュール)
  • RLIMIT_NPTS (resource モジュール)
  • RLIMIT_OFILE (resource モジュール)
  • RLIMIT_RSS (resource モジュール)
  • RLIMIT_RTPRIO (resource モジュール)
  • RLIMIT_RTTIME (resource モジュール)
  • RLIMIT_SBSIZE (resource モジュール)
  • RLIMIT_SIGPENDING (resource モジュール)
  • RLIMIT_STACK (resource モジュール)
  • RLIMIT_SWAP (resource モジュール)
  • RLIMIT_VMEM (resource モジュール)
  • RLock (multiprocessing のクラス)
    • (threading のクラス)
  • RLock() (multiprocessing.managers.SyncManager のメソッド)
  • rmd() (ftplib.FTP のメソッド)
  • rmdir() (os モジュール)
    • (pathlib.Path のメソッド)
    • (test.support モジュール)
  • RMFF
  • rms() (audioop モジュール)
  • rmtree() (shutil モジュール)
    • (test.support モジュール)
  • RobotFileParser (urllib.robotparser のクラス)
  • robots.txt
  • rollback() (sqlite3.Connection のメソッド)
  • ROT_THREE (opcode)
  • ROT_TWO (opcode)
  • rotate() (collections.deque のメソッド)
    • (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (logging.handlers.BaseRotatingHandler のメソッド)
  • RotatingFileHandler (logging.handlers のクラス)
  • rotation_filename() (logging.handlers.BaseRotatingHandler のメソッド)
  • rotator (logging.handlers.BaseRotatingHandler の属性)
  • round
    • 組み込み関数
  • round() (組み込み関数)
  • ROUND_05UP (decimal モジュール)
  • ROUND_CEILING (decimal モジュール)
  • ROUND_DOWN (decimal モジュール)
  • ROUND_FLOOR (decimal モジュール)
  • ROUND_HALF_DOWN (decimal モジュール)
  • ROUND_HALF_EVEN (decimal モジュール)
  • ROUND_HALF_UP (decimal モジュール)
  • ROUND_UP (decimal モジュール)
  • Rounded (decimal のクラス)
  • Row (sqlite3 のクラス)
  • row_factory (sqlite3.Connection の属性)
  • rowcount (sqlite3.Cursor の属性)
  • RPAR (token モジュール)
  • rpartition() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • rpc_paths (xmlrpc.server.SimpleXMLRPCRequestHandler の属性)
  • rpop() (poplib.POP3 のメソッド)
  • rset() (poplib.POP3 のメソッド)
  • rshift() (operator モジュール)
  • rsplit() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • RSQB (token モジュール)
  • rstrip() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • rt() (turtle モジュール)
  • RTLD_DEEPBIND (os モジュール)
  • RTLD_GLOBAL (os モジュール)
  • RTLD_LAZY (os モジュール)
  • RTLD_LOCAL (os モジュール)
  • RTLD_NODELETE (os モジュール)
  • RTLD_NOLOAD (os モジュール)
  • RTLD_NOW (os モジュール)
  • ruler (cmd.Cmd の属性)
  • run (pdb command)
  • Run script
  • run() (asyncio モジュール)
    • (bdb.Bdb のメソッド)
    • (contextvars.Context のメソッド)
    • (distutils.cmd.Command のメソッド)
    • (doctest.DocTestRunner のメソッド)
    • (multiprocessing.Process のメソッド)
    • (pdb モジュール)
    • (pdb.Pdb のメソッド)
    • (profile モジュール)
    • (profile.Profile のメソッド)
    • (sched.scheduler のメソッド)
    • (subprocess モジュール)
    • (test.support.BasicTestRunner のメソッド)
    • (threading.Thread のメソッド)
    • (trace.Trace のメソッド)
    • (unittest.TestCase のメソッド)
    • (unittest.TestSuite のメソッド)
    • (unittest.TextTestRunner のメソッド)
    • (wsgiref.handlers.BaseHandler のメソッド)
  • run_coroutine_threadsafe() (asyncio モジュール)
  • run_docstring_examples() (doctest モジュール)
  • run_doctest() (test.support モジュール)
  • run_forever() (asyncio.loop のメソッド)
  • run_in_executor() (asyncio.loop のメソッド)
  • run_in_subinterp() (test.support モジュール)
  • run_module() (runpy モジュール)
  • run_path() (runpy モジュール)
  • run_python_until_end() (test.support.script_helper モジュール)
  • run_script() (modulefinder.ModuleFinder のメソッド)
  • run_setup() (distutils.core モジュール)
  • run_unittest() (test.support モジュール)
  • run_until_complete() (asyncio.loop のメソッド)
  • run_with_locale() (test.support モジュール)
  • run_with_tz() (test.support モジュール)
  • runcall() (bdb.Bdb のメソッド)
    • (pdb モジュール)
    • (pdb.Pdb のメソッド)
    • (profile.Profile のメソッド)
  • runcode() (code.InteractiveInterpreter のメソッド)
  • runctx() (bdb.Bdb のメソッド)
    • (profile モジュール)
    • (profile.Profile のメソッド)
    • (trace.Trace のメソッド)
  • runeval() (bdb.Bdb のメソッド)
    • (pdb モジュール)
    • (pdb.Pdb のメソッド)
  • runfunc() (trace.Trace のメソッド)
  • running() (concurrent.futures.Future のメソッド)
  • runpy (モジュール)
  • runsource() (code.InteractiveInterpreter のメソッド)
  • runtime_library_dir_option() (distutils.ccompiler.CCompiler のメソッド)
  • RuntimeError
  • RuntimeWarning
  • RUSAGE_BOTH (resource モジュール)
  • RUSAGE_CHILDREN (resource モジュール)
  • RUSAGE_SELF (resource モジュール)
  • RUSAGE_THREAD (resource モジュール)
  • RWF_DSYNC (os モジュール)
  • RWF_HIPRI (os モジュール)
  • RWF_NOWAIT (os モジュール)
  • RWF_SYNC (os モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – S

  • S (re モジュール)
  • S_ENFMT (stat モジュール)
  • S_IEXEC (stat モジュール)
  • S_IFBLK (stat モジュール)
  • S_IFCHR (stat モジュール)
  • S_IFDIR (stat モジュール)
  • S_IFDOOR (stat モジュール)
  • S_IFIFO (stat モジュール)
  • S_IFLNK (stat モジュール)
  • S_IFMT() (stat モジュール)
  • S_IFPORT (stat モジュール)
  • S_IFREG (stat モジュール)
  • S_IFSOCK (stat モジュール)
  • S_IFWHT (stat モジュール)
  • S_IMODE() (stat モジュール)
  • S_IREAD (stat モジュール)
  • S_IRGRP (stat モジュール)
  • S_IROTH (stat モジュール)
  • S_IRUSR (stat モジュール)
  • S_IRWXG (stat モジュール)
  • S_IRWXO (stat モジュール)
  • S_IRWXU (stat モジュール)
  • S_ISBLK() (stat モジュール)
  • S_ISCHR() (stat モジュール)
  • S_ISDIR() (stat モジュール)
  • S_ISDOOR() (stat モジュール)
  • S_ISFIFO() (stat モジュール)
  • S_ISGID (stat モジュール)
  • S_ISLNK() (stat モジュール)
  • S_ISPORT() (stat モジュール)
  • S_ISREG() (stat モジュール)
  • S_ISSOCK() (stat モジュール)
  • S_ISUID (stat モジュール)
  • S_ISVTX (stat モジュール)
  • S_ISWHT() (stat モジュール)
  • S_IWGRP (stat モジュール)
  • S_IWOTH (stat モジュール)
  • S_IWRITE (stat モジュール)
  • S_IWUSR (stat モジュール)
  • S_IXGRP (stat モジュール)
  • S_IXOTH (stat モジュール)
  • S_IXUSR (stat モジュール)
  • safe (uuid.SafeUUID の属性)
  • safe_substitute() (string.Template のメソッド)
  • SafeChildWatcher (asyncio のクラス)
  • saferepr() (pprint モジュール)
  • SafeUUID (uuid のクラス)
  • same_files (filecmp.dircmp の属性)
  • same_quantum() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • samefile() (os.path モジュール)
    • (pathlib.Path のメソッド)
  • SameFileError
  • sameopenfile() (os.path モジュール)
  • samestat() (os.path モジュール)
  • sample() (random モジュール)
  • save() (http.cookiejar.FileCookieJar のメソッド)
  • SAVEDCWD (test.support モジュール)
  • SaveKey() (winreg モジュール)
  • SaveSignals (test.support のクラス)
  • savetty() (curses モジュール)
  • SAX2DOM (xml.dom.pulldom のクラス)
  • SAXException
  • SAXNotRecognizedException
  • SAXNotSupportedException
  • SAXParseException
  • scaleb() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • scandir() (os モジュール)
  • scanf()
  • sched (モジュール)
  • SCHED_BATCH (os モジュール)
  • SCHED_FIFO (os モジュール)
  • sched_get_priority_max() (os モジュール)
  • sched_get_priority_min() (os モジュール)
  • sched_getaffinity() (os モジュール)
  • sched_getparam() (os モジュール)
  • sched_getscheduler() (os モジュール)
  • SCHED_IDLE (os モジュール)
  • SCHED_OTHER (os モジュール)
  • sched_param (os のクラス)
  • sched_priority (os.sched_param の属性)
  • SCHED_RESET_ON_FORK (os モジュール)
  • SCHED_RR (os モジュール)
  • sched_rr_get_interval() (os モジュール)
  • sched_setaffinity() (os モジュール)
  • sched_setparam() (os モジュール)
  • sched_setscheduler() (os モジュール)
  • SCHED_SPORADIC (os モジュール)
  • sched_yield() (os モジュール)
  • scheduler (sched のクラス)
  • schema (msilib モジュール)
  • scope, [1]
  • Screen (turtle のクラス)
  • screensize() (turtle モジュール)
  • script_from_examples() (doctest モジュール)
  • scroll() (curses.window のメソッド)
  • ScrolledCanvas (turtle のクラス)
  • scrollok() (curses.window のメソッド)
  • scrypt() (hashlib モジュール)
  • sdterr
    • stdin stdout
  • seal() (unittest.mock モジュール)
  • search
    • path, module, [1], [2], [3], [4], [5], [6], [7]
  • search() (imaplib.IMAP4 のメソッド)
    • (re モジュール)
    • (re.Pattern のメソッド)
  • second (datetime.datetime の属性)
    • (datetime.time の属性)
  • seconds since the epoch
  • secrets (モジュール)
  • SECTCRE (configparser.ConfigParser の属性)
  • sections() (configparser.ConfigParser のメソッド)
  • secure (http.cookiejar.Cookie の属性)
  • secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
  • Secure Sockets Layer
  • security
    • CGI
  • see() (tkinter.ttk.Treeview のメソッド)
  • seed() (random モジュール)
  • seek() (chunk.Chunk のメソッド)
    • (io.IOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (mmap.mmap のメソッド)
  • SEEK_CUR (os モジュール)
  • SEEK_END (os モジュール)
  • SEEK_SET (os モジュール)
  • seekable() (io.IOBase のメソッド)
  • seen_greeting (smtpd.SMTPChannel の属性)
  • Select (tkinter.tix のクラス)
  • select (モジュール)
  • select() (imaplib.IMAP4 のメソッド)
    • (select モジュール)
    • (selectors.BaseSelector のメソッド)
    • (tkinter.ttk.Notebook のメソッド)
  • selected_alpn_protocol() (ssl.SSLSocket のメソッド)
  • selected_npn_protocol() (ssl.SSLSocket のメソッド)
  • selection() (tkinter.ttk.Treeview のメソッド)
  • selection_add() (tkinter.ttk.Treeview のメソッド)
  • selection_remove() (tkinter.ttk.Treeview のメソッド)
  • selection_set() (tkinter.ttk.Treeview のメソッド)
  • selection_toggle() (tkinter.ttk.Treeview のメソッド)
  • selector (urllib.request.Request の属性)
  • SelectorEventLoop (asyncio のクラス)
  • SelectorKey (selectors のクラス)
  • selectors (モジュール)
  • SelectSelector (selectors のクラス)
  • Semaphore (asyncio のクラス)
    • (multiprocessing のクラス)
    • (threading のクラス)
  • Semaphore() (multiprocessing.managers.SyncManager のメソッド)
  • semaphores, binary
  • SEMI (token モジュール)
  • send() (asyncore.dispatcher のメソッド)
    • (coroutine のメソッド)
    • (generator のメソッド)
    • (http.client.HTTPConnection のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (logging.handlers.DatagramHandler のメソッド)
    • (logging.handlers.SocketHandler のメソッド)
    • (multiprocessing.connection.Connection のメソッド)
    • (socket.socket のメソッド)
  • send_bytes() (multiprocessing.connection.Connection のメソッド)
  • send_error() (http.server.BaseHTTPRequestHandler のメソッド)
  • send_flowing_data() (formatter.writer のメソッド)
  • send_header() (http.server.BaseHTTPRequestHandler のメソッド)
  • send_hor_rule() (formatter.writer のメソッド)
  • send_label_data() (formatter.writer のメソッド)
  • send_line_break() (formatter.writer のメソッド)
  • send_literal_data() (formatter.writer のメソッド)
  • send_message() (smtplib.SMTP のメソッド)
  • send_paragraph() (formatter.writer のメソッド)
  • send_response() (http.server.BaseHTTPRequestHandler のメソッド)
  • send_response_only() (http.server.BaseHTTPRequestHandler のメソッド)
  • send_signal() (asyncio.asyncio.subprocess.Process のメソッド)
    • (asyncio.SubprocessTransport のメソッド)
    • (subprocess.Popen のメソッド)
  • sendall() (socket.socket のメソッド)
  • sendcmd() (ftplib.FTP のメソッド)
  • sendfile() (asyncio.loop のメソッド)
    • (os モジュール)
    • (socket.socket のメソッド)
    • (wsgiref.handlers.BaseHandler のメソッド)
  • SendfileNotAvailableError
  • sendmail() (smtplib.SMTP のメソッド)
  • sendmsg() (socket.socket のメソッド)
  • sendmsg_afalg() (socket.socket のメソッド)
  • sendto() (asyncio.DatagramTransport のメソッド)
    • (socket.socket のメソッド)
  • sentinel (multiprocessing.Process の属性)
    • (unittest.mock モジュール)
  • sep (os モジュール)
  • sequence
    • item
    • iteration
    • types, immutable
    • types, mutable
    • types, operations on, [1]
    • オブジェクト, [1], [2], [3], [4], [5], [6], [7], [8]
  • Sequence (collections.abc のクラス)
  • sequence (msilib モジュール)
  • Sequence (typing のクラス)
  • sequence2st() (parser モジュール)
  • SequenceMatcher (difflib のクラス), [1]
  • serializing
    • objects
  • serve_forever() (asyncio.Server のメソッド)
    • (socketserver.BaseServer のメソッド)
  • server
    • WWW, [1]
  • Server (asyncio のクラス)
  • server (http.server.BaseHTTPRequestHandler の属性)
  • server_activate() (socketserver.BaseServer のメソッド)
  • server_address (socketserver.BaseServer の属性)
  • server_bind() (socketserver.BaseServer のメソッド)
  • server_close() (socketserver.BaseServer のメソッド)
  • server_hostname (ssl.SSLSocket の属性)
  • server_side (ssl.SSLSocket の属性)
  • server_software (wsgiref.handlers.BaseHandler の属性)
  • server_version (http.server.BaseHTTPRequestHandler の属性)
    • (http.server.SimpleHTTPRequestHandler の属性)
  • ServerProxy (xmlrpc.client のクラス)
  • service_actions() (socketserver.BaseServer のメソッド)
  • session (ssl.SSLSocket の属性)
  • session_reused (ssl.SSLSocket の属性)
  • session_stats() (ssl.SSLContext のメソッド)
  • set
    • display
    • オブジェクト, [1], [2], [3]
  • Set (collections.abc のクラス)
    • (typing のクラス)
  • set (組み込みクラス)
  • Set Breakpoint
  • set type
    • オブジェクト
  • set() (asyncio.Event のメソッド)
    • (configparser.ConfigParser のメソッド)
    • (configparser.RawConfigParser のメソッド)
    • (contextvars.ContextVar のメソッド)
    • (http.cookies.Morsel のメソッド)
    • (ossaudiodev.oss_mixer_device のメソッド)
    • (test.support.EnvironmentVarGuard のメソッド)
    • (threading.Event のメソッド)
    • (tkinter.ttk.Combobox のメソッド)
    • (tkinter.ttk.Spinbox のメソッド)
    • (tkinter.ttk.Treeview のメソッド)
    • (xml.etree.ElementTree.Element のメソッド)
  • SET_ADD (opcode)
  • set_all()
  • set_allowed_domains() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • set_alpn_protocols() (ssl.SSLContext のメソッド)
  • set_app() (wsgiref.simple_server.WSGIServer のメソッド)
  • set_asyncgen_hooks() (sys モジュール)
  • set_authorizer() (sqlite3.Connection のメソッド)
  • set_auto_history() (readline モジュール)
  • set_blocked_domains() (http.cookiejar.DefaultCookiePolicy のメソッド)
  • set_blocking() (os モジュール)
  • set_boundary() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • set_break() (bdb.Bdb のメソッド)
  • set_charset() (email.message.Message のメソッド)
  • set_child_watcher() (asyncio モジュール)
    • (asyncio.AbstractEventLoopPolicy のメソッド)
  • set_children() (tkinter.ttk.Treeview のメソッド)
  • set_ciphers() (ssl.SSLContext のメソッド)
  • set_completer() (readline モジュール)
  • set_completer_delims() (readline モジュール)
  • set_completion_display_matches_hook() (readline モジュール)
  • set_content() (email.contentmanager モジュール)
    • (email.contentmanager.ContentManager のメソッド)
    • (email.message.EmailMessage のメソッド)
  • set_continue() (bdb.Bdb のメソッド)
  • set_cookie() (http.cookiejar.CookieJar のメソッド)
  • set_cookie_if_ok() (http.cookiejar.CookieJar のメソッド)
  • set_coroutine_origin_tracking_depth() (sys モジュール)
  • set_coroutine_wrapper() (sys モジュール)
  • set_current() (msilib.Feature のメソッド)
  • set_data() (importlib.abc.SourceLoader のメソッド)
    • (importlib.machinery.SourceFileLoader のメソッド)
  • set_date() (mailbox.MaildirMessage のメソッド)
  • set_debug() (asyncio.loop のメソッド)
    • (gc モジュール)
  • set_debuglevel() (ftplib.FTP のメソッド)
    • (http.client.HTTPConnection のメソッド)
    • (nntplib.NNTP のメソッド)
    • (poplib.POP3 のメソッド)
    • (smtplib.SMTP のメソッド)
    • (telnetlib.Telnet のメソッド)
  • set_default_executor() (asyncio.loop のメソッド)
  • set_default_type() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • set_default_verify_paths() (ssl.SSLContext のメソッド)
  • set_defaults() (argparse.ArgumentParser のメソッド)
    • (optparse.OptionParser のメソッド)
  • set_ecdh_curve() (ssl.SSLContext のメソッド)
  • set_errno() (ctypes モジュール)
  • set_event_loop() (asyncio モジュール)
    • (asyncio.AbstractEventLoopPolicy のメソッド)
  • set_event_loop_policy() (asyncio モジュール)
  • set_exception() (asyncio.Future のメソッド)
    • (concurrent.futures.Future のメソッド)
  • set_exception_handler() (asyncio.loop のメソッド)
  • set_executable() (multiprocessing モジュール)
  • set_executables() (distutils.ccompiler.CCompiler のメソッド)
  • set_flags() (mailbox.MaildirMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
    • (mailbox.mboxMessage のメソッド)
  • set_from() (mailbox.mboxMessage のメソッド)
    • (mailbox.MMDFMessage のメソッド)
  • set_handle_inheritable() (os モジュール)
  • set_history_length() (readline モジュール)
  • set_include_dirs() (distutils.ccompiler.CCompiler のメソッド)
  • set_info() (mailbox.MaildirMessage のメソッド)
  • set_inheritable() (os モジュール)
    • (socket.socket のメソッド)
  • set_labels() (mailbox.BabylMessage のメソッド)
  • set_last_error() (ctypes モジュール)
  • set_libraries() (distutils.ccompiler.CCompiler のメソッド)
  • set_library_dirs() (distutils.ccompiler.CCompiler のメソッド)
  • set_link_objects() (distutils.ccompiler.CCompiler のメソッド)
  • set_literal (2to3 fixer)
  • set_loader() (importlib.util モジュール)
  • set_match_tests() (test.support モジュール)
  • set_memlimit() (test.support モジュール)
  • set_next() (bdb.Bdb のメソッド)
  • set_nonstandard_attr() (http.cookiejar.Cookie のメソッド)
  • set_npn_protocols() (ssl.SSLContext のメソッド)
  • set_ok() (http.cookiejar.CookiePolicy のメソッド)
  • set_option_negotiation_callback() (telnetlib.Telnet のメソッド)
  • set_output_charset() (gettext.NullTranslations のメソッド)
  • set_package() (importlib.util モジュール)
  • set_param() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • set_pasv() (ftplib.FTP のメソッド)
  • set_payload() (email.message.Message のメソッド)
  • set_policy() (http.cookiejar.CookieJar のメソッド)
  • set_position() (xdrlib.Unpacker のメソッド)
  • set_pre_input_hook() (readline モジュール)
  • set_progress_handler() (sqlite3.Connection のメソッド)
  • set_protocol() (asyncio.BaseTransport のメソッド)
  • set_proxy() (urllib.request.Request のメソッド)
  • set_python_build() (distutils.sysconfig モジュール)
  • set_quit() (bdb.Bdb のメソッド)
  • set_recsrc() (ossaudiodev.oss_mixer_device のメソッド)
  • set_result() (asyncio.Future のメソッド)
    • (concurrent.futures.Future のメソッド)
  • set_return() (bdb.Bdb のメソッド)
  • set_running_or_notify_cancel() (concurrent.futures.Future のメソッド)
  • set_runtime_library_dirs() (distutils.ccompiler.CCompiler のメソッド)
  • set_seq1() (difflib.SequenceMatcher のメソッド)
  • set_seq2() (difflib.SequenceMatcher のメソッド)
  • set_seqs() (difflib.SequenceMatcher のメソッド)
  • set_sequences() (mailbox.MH のメソッド)
    • (mailbox.MHMessage のメソッド)
  • set_server_documentation() (xmlrpc.server.DocCGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.DocXMLRPCServer のメソッド)
  • set_server_name() (xmlrpc.server.DocCGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.DocXMLRPCServer のメソッド)
  • set_server_title() (xmlrpc.server.DocCGIXMLRPCRequestHandler のメソッド)
    • (xmlrpc.server.DocXMLRPCServer のメソッド)
  • set_servername_callback (ssl.SSLContext の属性)
  • set_spacing() (formatter.formatter のメソッド)
  • set_start_method() (multiprocessing モジュール)
  • set_startup_hook() (readline モジュール)
  • set_step() (bdb.Bdb のメソッド)
  • set_subdir() (mailbox.MaildirMessage のメソッド)
  • set_task_factory() (asyncio.loop のメソッド)
  • set_terminator() (asynchat.async_chat のメソッド)
  • set_threshold() (gc モジュール)
  • set_trace() (bdb モジュール)
    • (bdb.Bdb のメソッド)
    • (pdb モジュール)
    • (pdb.Pdb のメソッド)
  • set_trace_callback() (sqlite3.Connection のメソッド)
  • set_tunnel() (http.client.HTTPConnection のメソッド)
  • set_type() (email.message.Message のメソッド)
  • set_unittest_reportflags() (doctest モジュール)
  • set_unixfrom() (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
  • set_until() (bdb.Bdb のメソッド)
  • set_url() (urllib.robotparser.RobotFileParser のメソッド)
  • set_usage() (optparse.OptionParser のメソッド)
  • set_userptr() (curses.panel.Panel のメソッド)
  • set_visible() (mailbox.BabylMessage のメソッド)
  • set_wakeup_fd() (signal モジュール)
  • set_write_buffer_limits() (asyncio.WriteTransport のメソッド)
  • setacl() (imaplib.IMAP4 のメソッド)
  • setannotation() (imaplib.IMAP4 のメソッド)
  • setattr() (組み込み関数)
  • setAttribute() (xml.dom.Element のメソッド)
  • setAttributeNode() (xml.dom.Element のメソッド)
  • setAttributeNodeNS() (xml.dom.Element のメソッド)
  • setAttributeNS() (xml.dom.Element のメソッド)
  • SetBase() (xml.parsers.expat.xmlparser のメソッド)
  • setblocking() (socket.socket のメソッド)
  • setByteStream() (xml.sax.xmlreader.InputSource のメソッド)
  • setcbreak() (tty モジュール)
  • setCharacterStream() (xml.sax.xmlreader.InputSource のメソッド)
  • setcheckinterval() (sys モジュール)
  • setcomptype() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • setContentHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • setcontext() (decimal モジュール)
  • setDaemon() (threading.Thread のメソッド)
  • setdefault() (dict のメソッド)
    • (http.cookies.Morsel のメソッド)
  • setdefaulttimeout() (socket モジュール)
  • setdlopenflags() (sys モジュール)
  • setDocumentLocator() (xml.sax.handler.ContentHandler のメソッド)
  • setDTDHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • setegid() (os モジュール)
  • setEncoding() (xml.sax.xmlreader.InputSource のメソッド)
  • setEntityResolver() (xml.sax.xmlreader.XMLReader のメソッド)
  • setErrorHandler() (xml.sax.xmlreader.XMLReader のメソッド)
  • seteuid() (os モジュール)
  • setFeature() (xml.sax.xmlreader.XMLReader のメソッド)
  • setfirstweekday() (calendar モジュール)
  • setfmt() (ossaudiodev.oss_audio_device のメソッド)
  • setFormatter() (logging.Handler のメソッド)
  • setframerate() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • setgid() (os モジュール)
  • setgroups() (os モジュール)
  • seth() (turtle モジュール)
  • setheading() (turtle モジュール)
  • sethostname() (socket モジュール)
  • SetInteger() (msilib.Record のメソッド)
  • setitem() (operator モジュール)
  • setitimer() (signal モジュール)
  • setLevel() (logging.Handler のメソッド)
    • (logging.Logger のメソッド)
  • setlocale() (locale モジュール)
  • setLocale() (xml.sax.xmlreader.XMLReader のメソッド)
  • setLoggerClass() (logging モジュール)
  • setlogmask() (syslog モジュール)
  • setLogRecordFactory() (logging モジュール)
  • setmark() (aifc.aifc のメソッド)
  • setMaxConns() (urllib.request.CacheFTPHandler のメソッド)
  • setmode() (msvcrt モジュール)
  • setName() (threading.Thread のメソッド)
  • setnchannels() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • setnframes() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • SetParamEntityParsing() (xml.parsers.expat.xmlparser のメソッド)
  • setparameters() (ossaudiodev.oss_audio_device のメソッド)
  • setparams() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • setpassword() (zipfile.ZipFile のメソッド)
  • setpgid() (os モジュール)
  • setpgrp() (os モジュール)
  • setpos() (aifc.aifc のメソッド)
    • (sunau.AU_read のメソッド)
    • (turtle モジュール)
    • (wave.Wave_read のメソッド)
  • setposition() (turtle モジュール)
  • setpriority() (os モジュール)
  • setprofile() (sys モジュール)
    • (threading モジュール)
  • SetProperty() (msilib.SummaryInformation のメソッド)
  • setProperty() (xml.sax.xmlreader.XMLReader のメソッド)
  • setPublicId() (xml.sax.xmlreader.InputSource のメソッド)
  • setquota() (imaplib.IMAP4 のメソッド)
  • setraw() (tty モジュール)
  • setrecursionlimit() (sys モジュール)
  • setregid() (os モジュール)
  • setresgid() (os モジュール)
  • setresuid() (os モジュール)
  • setreuid() (os モジュール)
  • setrlimit() (resource モジュール)
  • setsampwidth() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • setscrreg() (curses.window のメソッド)
  • setsid() (os モジュール)
  • setsockopt() (socket.socket のメソッド), [1], [2]
  • setstate() (codecs.IncrementalDecoder のメソッド)
    • (codecs.IncrementalEncoder のメソッド)
    • (random モジュール)
  • setStream() (logging.StreamHandler のメソッド)
  • SetStream() (msilib.Record のメソッド)
  • SetString() (msilib.Record のメソッド)
  • setswitchinterval() (in module sys)
    • (sys モジュール)
    • (test.support モジュール)
  • setSystemId() (xml.sax.xmlreader.InputSource のメソッド)
  • setsyx() (curses モジュール)
  • setTarget() (logging.handlers.MemoryHandler のメソッド)
  • settiltangle() (turtle モジュール)
  • settimeout() (socket.socket のメソッド)
  • setTimeout() (urllib.request.CacheFTPHandler のメソッド)
  • settrace() (sys モジュール)
    • (threading モジュール)
  • setuid() (os モジュール)
  • setundobuffer() (turtle モジュール)
  • setup() (distutils.core モジュール)
    • (socketserver.BaseRequestHandler のメソッド)
    • (turtle モジュール)
  • setUp() (unittest.TestCase のメソッド)
  • SETUP_ANNOTATIONS (opcode)
  • SETUP_ASYNC_WITH (opcode)
  • setup_environ() (wsgiref.handlers.BaseHandler のメソッド)
  • SETUP_EXCEPT (opcode)
  • SETUP_FINALLY (opcode)
  • SETUP_LOOP (opcode)
  • setup_python() (venv.EnvBuilder のメソッド)
  • setup_scripts() (venv.EnvBuilder のメソッド)
  • setup_testing_defaults() (wsgiref.util モジュール)
  • SETUP_WITH (opcode)
  • setUpClass() (unittest.TestCase のメソッド)
  • setupterm() (curses モジュール)
  • SetValue() (winreg モジュール)
  • SetValueEx() (winreg モジュール)
  • setworldcoordinates() (turtle モジュール)
  • setx() (turtle モジュール)
  • setxattr() (os モジュール)
  • sety() (turtle モジュール)
  • SF_APPEND (stat モジュール)
  • SF_ARCHIVED (stat モジュール)
  • SF_IMMUTABLE (stat モジュール)
  • SF_MNOWAIT (os モジュール)
  • SF_NODISKIO (os モジュール)
  • SF_NOUNLINK (stat モジュール)
  • SF_SNAPSHOT (stat モジュール)
  • SF_SYNC (os モジュール)
  • shape (memoryview の属性)
  • Shape (turtle のクラス)
  • shape() (turtle モジュール)
  • shapesize() (turtle モジュール)
  • shapetransform() (turtle モジュール)
  • share() (socket.socket のメソッド)
  • shared_ciphers() (ssl.SSLSocket のメソッド)
  • shared_object_filename() (distutils.ccompiler.CCompiler のメソッド)
  • shearfactor() (turtle モジュール)
  • Shelf (shelve のクラス)
  • shelve
    • モジュール
  • shelve (モジュール)
  • shift() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • shift_path_info() (wsgiref.util モジュール)
  • shifting
    • operation
    • operations
  • shlex (shlex のクラス)
    • (モジュール)
  • shortDescription() (unittest.TestCase のメソッド)
  • shorten() (textwrap モジュール)
  • shouldFlush() (logging.handlers.BufferingHandler のメソッド)
    • (logging.handlers.MemoryHandler のメソッド)
  • shouldStop (unittest.TestResult の属性)
  • show() (curses.panel.Panel のメソッド)
  • show_code() (dis モジュール)
  • show_compilers() (distutils.ccompiler モジュール)
  • showsyntaxerror() (code.InteractiveInterpreter のメソッド)
  • showtraceback() (code.InteractiveInterpreter のメソッド)
  • showturtle() (turtle モジュール)
  • showwarning() (warnings モジュール)
  • shuffle() (random モジュール)
  • shutdown() (concurrent.futures.Executor のメソッド)
    • (imaplib.IMAP4 のメソッド)
    • (logging モジュール)
    • (multiprocessing.managers.BaseManager のメソッド)
    • (socket.socket のメソッド)
    • (socketserver.BaseServer のメソッド)
  • shutdown_asyncgens() (asyncio.loop のメソッド)
  • shutil (モジュール)
  • side_effect (unittest.mock.Mock の属性)
  • SIG_BLOCK (signal モジュール)
  • SIG_DFL (signal モジュール)
  • SIG_IGN (signal モジュール)
  • SIG_SETMASK (signal モジュール)
  • SIG_UNBLOCK (signal モジュール)
  • SIGINT, [1]
  • siginterrupt() (signal モジュール)
  • signal
    • モジュール, [1]
  • signal (モジュール)
  • signal() (signal モジュール)
  • Signature (inspect のクラス)
  • signature (inspect.BoundArguments の属性)
  • signature() (inspect モジュール)
  • sigpending() (signal モジュール)
  • sigtimedwait() (signal モジュール)
  • sigwait() (signal モジュール)
  • sigwaitinfo() (signal モジュール)
  • simple
    • statement
  • Simple Mail Transfer Protocol
  • SimpleCookie (http.cookies のクラス)
  • simplefilter() (warnings モジュール)
  • SimpleHandler (wsgiref.handlers のクラス)
  • SimpleHTTPRequestHandler (http.server のクラス)
  • SimpleNamespace (types のクラス)
  • SimpleQueue (multiprocessing のクラス)
    • (queue のクラス)
  • SimpleXMLRPCRequestHandler (xmlrpc.server のクラス)
  • SimpleXMLRPCServer (xmlrpc.server のクラス)
  • sin() (cmath モジュール)
    • (math モジュール)
  • single dispatch
  • SingleAddressHeader (email.headerregistry のクラス)
  • singledispatch() (functools モジュール)
  • singleton
    • tuple
  • sinh() (cmath モジュール)
    • (math モジュール)
  • SIO_KEEPALIVE_VALS (socket モジュール)
  • SIO_LOOPBACK_FAST_PATH (socket モジュール)
  • SIO_RCVALL (socket モジュール)
  • site (モジュール)
  • site コマンドラインオプション
    • --user-base
    • --user-site
  • site-packages
    • directory
  • sitecustomize
    • モジュール
  • sixtofour (ipaddress.IPv6Address の属性)
  • size (struct.Struct の属性)
    • (tarfile.TarInfo の属性)
    • (tracemalloc.Statistic の属性)
    • (tracemalloc.StatisticDiff の属性)
    • (tracemalloc.Trace の属性)
  • size() (ftplib.FTP のメソッド)
    • (mmap.mmap のメソッド)
  • size_diff (tracemalloc.StatisticDiff の属性)
  • SIZE_MAX
  • Sized (collections.abc のクラス)
    • (typing のクラス)
  • sizeof() (ctypes モジュール)
  • SKIP (doctest モジュール)
  • skip() (chunk.Chunk のメソッド)
    • (unittest モジュール)
  • skip_unless_bind_unix_socket() (test.support モジュール)
  • skip_unless_symlink() (test.support モジュール)
  • skip_unless_xattr() (test.support モジュール)
  • skipIf() (unittest モジュール)
  • skipinitialspace (csv.Dialect の属性)
  • skipped (unittest.TestResult の属性)
  • skippedEntity() (xml.sax.handler.ContentHandler のメソッド)
  • SkipTest
  • skipTest() (unittest.TestCase のメソッド)
  • skipUnless() (unittest モジュール)
  • SLASH (token モジュール)
  • SLASHEQUAL (token モジュール)
  • slave() (nntplib.NNTP のメソッド)
  • sleep() (asyncio モジュール)
    • (time モジュール)
  • slice, [1]
    • assignment
    • operation
    • オブジェクト
    • 組み込み関数, [1]
  • slice (組み込みクラス)
  • slicing, [1], [2]
    • assignment
  • SMTP
    • protocol
  • SMTP (email.policy モジュール)
    • (smtplib のクラス)
  • smtp_server (smtpd.SMTPChannel の属性)
  • SMTP_SSL (smtplib のクラス)
  • smtp_state (smtpd.SMTPChannel の属性)
  • SMTPAuthenticationError
  • SMTPChannel (smtpd のクラス)
  • SMTPConnectError
  • smtpd (モジュール)
  • SMTPDataError
  • SMTPException
  • SMTPHandler (logging.handlers のクラス)
  • SMTPHeloError
  • smtplib (モジュール)
  • SMTPNotSupportedError
  • SMTPRecipientsRefused
  • SMTPResponseException
  • SMTPSenderRefused
  • SMTPServer (smtpd のクラス)
  • SMTPServerDisconnected
  • SMTPUTF8 (email.policy モジュール)
  • Snapshot (tracemalloc のクラス)
  • SND_ALIAS (winsound モジュール)
  • SND_ASYNC (winsound モジュール)
  • SND_FILENAME (winsound モジュール)
  • SND_LOOP (winsound モジュール)
  • SND_MEMORY (winsound モジュール)
  • SND_NODEFAULT (winsound モジュール)
  • SND_NOSTOP (winsound モジュール)
  • SND_NOWAIT (winsound モジュール)
  • SND_PURGE (winsound モジュール)
  • sndhdr (モジュール)
  • sni_callback (ssl.SSLContext の属性)
  • sniff() (csv.Sniffer のメソッド)
  • Sniffer (csv のクラス)
  • sock_accept() (asyncio.loop のメソッド)
  • SOCK_CLOEXEC (socket モジュール)
  • sock_connect() (asyncio.loop のメソッド)
  • SOCK_DGRAM (socket モジュール)
  • SOCK_MAX_SIZE (test.support モジュール)
  • SOCK_NONBLOCK (socket モジュール)
  • SOCK_RAW (socket モジュール)
  • SOCK_RDM (socket モジュール)
  • sock_recv() (asyncio.loop のメソッド)
  • sock_recv_into() (asyncio.loop のメソッド)
  • sock_sendall() (asyncio.loop のメソッド)
  • sock_sendfile() (asyncio.loop のメソッド)
  • SOCK_SEQPACKET (socket モジュール)
  • SOCK_STREAM (socket モジュール)
  • socket
    • オブジェクト
    • モジュール
  • socket (socketserver.BaseServer の属性)
    • (モジュール)
  • socket() (imaplib.IMAP4 のメソッド)
    • (in module socket)
    • (socket モジュール)
  • socket_type (socketserver.BaseServer の属性)
  • SocketHandler (logging.handlers のクラス)
  • socketpair() (socket モジュール)
  • sockets (asyncio.Server の属性)
  • socketserver (モジュール)
  • SocketType (socket モジュール)
  • SOL_ALG (socket モジュール)
  • SOL_RDS (socket モジュール)
  • SOMAXCONN (socket モジュール)
  • sort() (imaplib.IMAP4 のメソッド)
    • (list のメソッド)
  • sort_stats() (pstats.Stats のメソッド)
  • sortdict() (test.support モジュール)
  • sorted() (組み込み関数)
  • sortTestMethodsUsing (unittest.TestLoader の属性)
  • source (doctest.Example の属性)
    • (pdb command)
    • (shlex.shlex の属性)
  • source character set
  • SOURCE_DATE_EPOCH, [1], [2], [3], [4], [5], [6]
  • source_from_cache() (imp モジュール)
    • (importlib.util モジュール)
  • source_hash() (importlib.util モジュール)
  • SOURCE_SUFFIXES (importlib.machinery モジュール)
  • source_to_code() (importlib.abc.InspectLoader の静的メソッド)
  • SourceFileLoader (importlib.machinery のクラス)
  • sourcehook() (shlex.shlex のメソッド)
  • SourcelessFileLoader (importlib.machinery のクラス)
  • SourceLoader (importlib.abc のクラス)
  • space
    • in printf-style formatting, [1]
    • in string formatting
  • span() (re.Match のメソッド)
  • spawn() (distutils.ccompiler.CCompiler のメソッド)
    • (pty モジュール)
  • spawn_python() (test.support.script_helper モジュール)
  • spawnl() (os モジュール)
  • spawnle() (os モジュール)
  • spawnlp() (os モジュール)
  • spawnlpe() (os モジュール)
  • spawnv() (os モジュール)
  • spawnve() (os モジュール)
  • spawnvp() (os モジュール)
  • spawnvpe() (os モジュール)
  • spec_from_file_location() (importlib.util モジュール)
  • spec_from_loader() (importlib.util モジュール)
  • special
    • attribute
    • attribute, generic
  • special method
  • specified_attributes (xml.parsers.expat.xmlparser の属性)
  • speed() (ossaudiodev.oss_audio_device のメソッド)
    • (turtle モジュール)
  • Spinbox (tkinter.ttk のクラス)
  • split() (bytearray のメソッド)
    • (bytes のメソッド)
    • (os.path モジュール)
    • (re モジュール)
    • (re.Pattern のメソッド)
    • (shlex モジュール)
    • (str のメソッド)
  • split_quoted() (distutils.util モジュール)
  • splitdrive() (os.path モジュール)
  • splitext() (os.path モジュール)
  • splitlines() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • SplitResult (urllib.parse のクラス)
  • SplitResultBytes (urllib.parse のクラス)
  • SpooledTemporaryFile() (tempfile モジュール)
  • sprintf-style formatting, [1]
  • spwd (モジュール)
  • sqlite3 (モジュール)
  • sqlite_version (sqlite3 モジュール)
  • sqlite_version_info (sqlite3 モジュール)
  • sqrt() (cmath モジュール)
    • (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
    • (math モジュール)
  • SSL
  • ssl (モジュール)
  • SSL_CERT_FILE
  • SSL_CERT_PATH
  • ssl_version (ftplib.FTP_TLS の属性)
  • SSLCertVerificationError
  • SSLContext (ssl のクラス)
  • SSLEOFError
  • SSLError
  • SSLErrorNumber (ssl のクラス)
  • SSLObject (ssl のクラス)
  • sslobject_class (ssl.SSLContext の属性)
  • SSLSession (ssl のクラス)
  • SSLSocket (ssl のクラス)
  • sslsocket_class (ssl.SSLContext の属性)
  • SSLSyscallError
  • SSLv3 (ssl.TLSVersion の属性)
  • SSLWantReadError
  • SSLWantWriteError
  • SSLZeroReturnError
  • st() (turtle モジュール)
  • st2list() (parser モジュール)
  • st2tuple() (parser モジュール)
  • st_atime (os.stat_result の属性)
  • ST_ATIME (stat モジュール)
  • st_atime_ns (os.stat_result の属性)
  • st_birthtime (os.stat_result の属性)
  • st_blksize (os.stat_result の属性)
  • st_blocks (os.stat_result の属性)
  • st_creator (os.stat_result の属性)
  • st_ctime (os.stat_result の属性)
  • ST_CTIME (stat モジュール)
  • st_ctime_ns (os.stat_result の属性)
  • st_dev (os.stat_result の属性)
  • ST_DEV (stat モジュール)
  • st_file_attributes (os.stat_result の属性)
  • st_flags (os.stat_result の属性)
  • st_fstype (os.stat_result の属性)
  • st_gen (os.stat_result の属性)
  • st_gid (os.stat_result の属性)
  • ST_GID (stat モジュール)
  • st_ino (os.stat_result の属性)
  • ST_INO (stat モジュール)
  • st_mode (os.stat_result の属性)
  • ST_MODE (stat モジュール)
  • st_mtime (os.stat_result の属性)
  • ST_MTIME (stat モジュール)
  • st_mtime_ns (os.stat_result の属性)
  • st_nlink (os.stat_result の属性)
  • ST_NLINK (stat モジュール)
  • st_rdev (os.stat_result の属性)
  • st_rsize (os.stat_result の属性)
  • st_size (os.stat_result の属性)
  • ST_SIZE (stat モジュール)
  • st_type (os.stat_result の属性)
  • st_uid (os.stat_result の属性)
  • ST_UID (stat モジュール)
  • stack
    • execution
    • trace
  • stack (traceback.TracebackException の属性)
  • stack viewer
  • stack() (inspect モジュール)
  • stack_effect() (dis モジュール)
  • stack_size() (_thread モジュール)
    • (threading モジュール)
  • stackable
    • streams
  • StackSummary (traceback のクラス)
  • stamp() (turtle モジュール)
  • standard
    • output
  • Standard C
  • standard input
  • standard_b64decode() (base64 モジュール)
  • standard_b64encode() (base64 モジュール)
  • standarderror (2to3 fixer)
  • standend() (curses.window のメソッド)
  • standout() (curses.window のメソッド)
  • STAR (token モジュール)
  • STAREQUAL (token モジュール)
  • starmap() (itertools モジュール)
    • (multiprocessing.pool.Pool のメソッド)
  • starmap_async() (multiprocessing.pool.Pool のメソッド)
  • start (range の属性)
    • (UnicodeError の属性)
    • (slice object attribute), [1]
  • start() (logging.handlers.QueueListener のメソッド)
    • (multiprocessing.Process のメソッド)
    • (multiprocessing.managers.BaseManager のメソッド)
    • (re.Match のメソッド)
    • (threading.Thread のメソッド)
    • (tkinter.ttk.Progressbar のメソッド)
    • (tracemalloc モジュール)
    • (xml.etree.ElementTree.TreeBuilder のメソッド)
  • start_color() (curses モジュール)
  • start_component() (msilib.Directory のメソッド)
  • start_new_thread() (_thread モジュール)
  • start_server() (asyncio モジュール)
  • start_serving() (asyncio.Server のメソッド)
  • start_threads() (test.support モジュール)
  • start_tls() (asyncio.loop のメソッド)
  • start_unix_server() (asyncio モジュール)
  • StartCdataSectionHandler() (xml.parsers.expat.xmlparser のメソッド)
  • StartDoctypeDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • startDocument() (xml.sax.handler.ContentHandler のメソッド)
  • startElement() (xml.sax.handler.ContentHandler のメソッド)
  • StartElementHandler() (xml.parsers.expat.xmlparser のメソッド)
  • startElementNS() (xml.sax.handler.ContentHandler のメソッド)
  • STARTF_USESHOWWINDOW (subprocess モジュール)
  • STARTF_USESTDHANDLES (subprocess モジュール)
  • startfile() (os モジュール)
  • StartNamespaceDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • startPrefixMapping() (xml.sax.handler.ContentHandler のメソッド)
  • startswith() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • startTest() (unittest.TestResult のメソッド)
  • startTestRun() (unittest.TestResult のメソッド)
  • starttls() (imaplib.IMAP4 のメソッド)
    • (nntplib.NNTP のメソッド)
    • (smtplib.SMTP のメソッド)
  • STARTUPINFO (subprocess のクラス)
  • stat
    • モジュール
  • stat (モジュール)
  • stat() (nntplib.NNTP のメソッド)
    • (os モジュール)
    • (os.DirEntry のメソッド)
    • (pathlib.Path のメソッド)
    • (poplib.POP3 のメソッド)
  • stat_result (os のクラス)
  • state() (tkinter.ttk.Widget のメソッド)
  • statement
    • assignment, [1]
    • assignment, annotated
    • assignment, augmented
    • compound
    • expression
    • future
    • loop, [1], [2], [3]
    • simple
  • statement grouping
  • staticmethod
    • 組み込み関数
  • staticmethod() (組み込み関数)
  • Statistic (tracemalloc のクラス)
  • StatisticDiff (tracemalloc のクラス)
  • statistics (モジュール)
  • statistics() (tracemalloc.Snapshot のメソッド)
  • StatisticsError
  • Stats (pstats のクラス)
  • status (http.client.HTTPResponse の属性)
  • status() (imaplib.IMAP4 のメソッド)
  • statvfs() (os モジュール)
  • STD_ERROR_HANDLE (subprocess モジュール)
  • STD_INPUT_HANDLE (subprocess モジュール)
  • STD_OUTPUT_HANDLE (subprocess モジュール)
  • StdButtonBox (tkinter.tix のクラス)
  • stderr (asyncio.asyncio.subprocess.Process の属性)
    • (in module sys), [1]
    • (subprocess.CalledProcessError の属性)
    • (subprocess.CompletedProcess の属性)
    • (subprocess.Popen の属性)
    • (subprocess.TimeoutExpired の属性)
    • (sys モジュール)
  • stdev() (statistics モジュール)
  • stdin
    • stdout sdterr
  • stdin (asyncio.asyncio.subprocess.Process の属性)
    • (in module sys), [1]
    • (subprocess.Popen の属性)
    • (sys モジュール)
  • stdio
  • stdout
    • sdterr, stdin
  • stdout (asyncio.asyncio.subprocess.Process の属性)
    • (in module sys), [1]
  • STDOUT (subprocess モジュール)
  • stdout (subprocess.CalledProcessError の属性)
    • (subprocess.CompletedProcess の属性)
    • (subprocess.Popen の属性)
    • (subprocess.TimeoutExpired の属性)
    • (sys モジュール)
  • step (pdb command)
    • (range の属性)
    • (slice object attribute), [1]
  • step() (tkinter.ttk.Progressbar のメソッド)
  • stereocontrols() (ossaudiodev.oss_mixer_device のメソッド)
  • stls() (poplib.POP3 のメソッド)
  • stop (range の属性)
    • (slice object attribute), [1]
  • stop() (asyncio.loop のメソッド)
    • (logging.handlers.QueueListener のメソッド)
    • (tkinter.ttk.Progressbar のメソッド)
    • (tracemalloc モジュール)
    • (unittest.TestResult のメソッド)
  • stop_here() (bdb.Bdb のメソッド)
  • StopAsyncIteration
    • 例外
  • StopIteration
    • 例外, [1]
  • stopListening() (logging.config モジュール)
  • stopTest() (unittest.TestResult のメソッド)
  • stopTestRun() (unittest.TestResult のメソッド)
  • storbinary() (ftplib.FTP のメソッド)
  • store() (imaplib.IMAP4 のメソッド)
  • STORE_ACTIONS (optparse.Option の属性)
  • STORE_ATTR (opcode)
  • STORE_DEREF (opcode)
  • STORE_FAST (opcode)
  • STORE_GLOBAL (opcode)
  • STORE_NAME (opcode)
  • STORE_SUBSCR (opcode)
  • storlines() (ftplib.FTP のメソッド)
  • str (built-in class)
    • (see also string)
  • str (組み込みクラス)
  • str() (locale モジュール)
  • strcoll() (locale モジュール)
  • StreamError
  • StreamHandler (logging のクラス)
  • StreamReader (asyncio のクラス)
    • (codecs のクラス)
  • streamreader (codecs.CodecInfo の属性)
  • StreamReaderWriter (codecs のクラス)
  • StreamRecoder (codecs のクラス)
  • StreamRequestHandler (socketserver のクラス)
  • streams
    • stackable
  • StreamWriter (asyncio のクラス)
    • (codecs のクラス)
  • streamwriter (codecs.CodecInfo の属性)
  • strerror (OSError の属性)
  • strerror()
    • (os モジュール)
  • strftime() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (time モジュール)
  • strict (csv.Dialect の属性)
    • (email.policy モジュール)
  • strict_domain (http.cookiejar.DefaultCookiePolicy の属性)
  • strict_errors() (codecs モジュール)
  • strict_ns_domain (http.cookiejar.DefaultCookiePolicy の属性)
  • strict_ns_set_initial_dollar (http.cookiejar.DefaultCookiePolicy の属性)
  • strict_ns_set_path (http.cookiejar.DefaultCookiePolicy の属性)
  • strict_ns_unverifiable (http.cookiejar.DefaultCookiePolicy の属性)
  • strict_rfc2965_unverifiable (http.cookiejar.DefaultCookiePolicy の属性)
  • strides (memoryview の属性)
  • string
    • PyObject_Str (C function)
    • __format__() (object method)
    • __str__() (object method)
    • conversion, [1]
    • format() (built-in function)
    • formatted literal
    • formatting, printf
    • immutable sequences
    • interpolated literal
    • interpolation, printf
    • item
    • methods
    • object representation
    • str (built-in class)
    • str() (built-in function)
    • text sequence type
    • オブジェクト, [1], [2]
    • モジュール
  • string (re.Match の属性)
  • STRING (token モジュール)
  • string (モジュール)
  • string literal
  • string_at() (ctypes モジュール)
  • StringIO (io のクラス)
  • stringprep (モジュール)
  • strings, documentation, [1]
  • strip() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • strip_dirs() (pstats.Stats のメソッド)
  • strip_python_strerr() (test.support モジュール)
  • stripspaces (curses.textpad.Textbox の属性)
  • strptime() (datetime.datetime のクラスメソッド)
    • (time モジュール)
  • strtobool() (distutils.util モジュール)
  • struct
    • モジュール
  • Struct (struct のクラス)
  • struct (モジュール)
  • struct sequence
  • struct_time (time のクラス)
  • Structure (ctypes のクラス)
  • structures
    • C
  • strxfrm() (locale モジュール)
  • STType (parser モジュール)
  • style
    • coding
  • Style (tkinter.ttk のクラス)
  • sub() (operator モジュール)
    • (re モジュール)
    • (re.Pattern のメソッド)
  • sub_commands (distutils.cmd.Command の属性)
  • subclassing
    • immutable types
  • subdirs (filecmp.dircmp の属性)
  • SubElement() (xml.etree.ElementTree モジュール)
  • submit() (concurrent.futures.Executor のメソッド)
  • submodule_search_locations (importlib.machinery.ModuleSpec の属性)
  • subn() (re モジュール)
    • (re.Pattern のメソッド)
  • subnet_of() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • subnets() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • Subnormal (decimal のクラス)
  • suboffsets (memoryview の属性)
  • subpad() (curses.window のメソッド)
  • subprocess (モジュール)
  • subprocess_exec() (asyncio.loop のメソッド)
  • subprocess_shell() (asyncio.loop のメソッド)
  • SubprocessError
  • SubprocessProtocol (asyncio のクラス)
  • SubprocessTransport (asyncio のクラス)
  • subscribe() (imaplib.IMAP4 のメソッド)
  • subscript
    • assignment
    • operation
  • subscription, [1], [2], [3]
    • assignment
  • subsequent_indent (textwrap.TextWrapper の属性)
  • subst_vars() (distutils.util モジュール)
  • substitute() (string.Template のメソッド)
  • subTest() (unittest.TestCase のメソッド)
  • subtract() (collections.Counter のメソッド)
    • (decimal.Context のメソッド)
  • subtraction
  • subtype (email.headerregistry.ContentTypeHeader の属性)
  • subwin() (curses.window のメソッド)
  • successful() (multiprocessing.pool.AsyncResult のメソッド)
  • suffix_map (mimetypes モジュール)
    • (mimetypes.MimeTypes の属性)
  • suite
  • suite() (parser モジュール)
  • suiteClass (unittest.TestLoader の属性)
  • sum() (組み込み関数)
  • sum_list()
  • sum_sequence(), [1]
  • summarize() (doctest.DocTestRunner のメソッド)
  • summarize_address_range() (ipaddress モジュール)
  • sunau (モジュール)
  • super (pyclbr.Class の属性)
  • super() (組み込み関数)
  • supernet() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • supernet_of() (ipaddress.IPv4Network のメソッド)
    • (ipaddress.IPv6Network のメソッド)
  • supports_bytes_environ (os モジュール)
  • supports_dir_fd (os モジュール)
  • supports_effective_ids (os モジュール)
  • supports_fd (os モジュール)
  • supports_follow_symlinks (os モジュール)
  • supports_unicode_filenames (os.path モジュール)
  • SupportsAbs (typing のクラス)
  • SupportsBytes (typing のクラス)
  • SupportsComplex (typing のクラス)
  • SupportsFloat (typing のクラス)
  • SupportsInt (typing のクラス)
  • SupportsRound (typing のクラス)
  • suppress() (contextlib モジュール)
  • SuppressCrashReport (test.support のクラス)
  • SW_HIDE (subprocess モジュール)
  • swap_attr() (test.support モジュール)
  • swap_item() (test.support モジュール)
  • swapcase() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • sym_name (symbol モジュール)
  • Symbol (symtable のクラス)
  • symbol (モジュール)
  • SymbolTable (symtable のクラス)
  • symlink() (os モジュール)
  • symlink_to() (pathlib.Path のメソッド)
  • symmetric_difference() (frozenset のメソッド)
  • symmetric_difference_update() (frozenset のメソッド)
  • symtable (モジュール)
  • symtable() (symtable モジュール)
  • sync() (dbm.dumb.dumbdbm のメソッド)
    • (dbm.gnu.gdbm のメソッド)
    • (os モジュール)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (shelve.Shelf のメソッド)
  • syncdown() (curses.window のメソッド)
  • synchronized() (multiprocessing.sharedctypes モジュール)
  • SyncManager (multiprocessing.managers のクラス)
  • syncok() (curses.window のメソッド)
  • syncup() (curses.window のメソッド)
  • syntax
  • SyntaxErr
  • SyntaxError
  • SyntaxWarning
  • sys
    • モジュール, [1], [2], [3], [4], [5], [6]
  • sys (モジュール)
  • sys.exc_info
  • sys.last_traceback
  • sys.meta_path
  • sys.modules
  • sys.path
  • sys.path_hooks
  • sys.path_importer_cache
  • sys.stderr
  • sys.stdin
  • sys.stdout
  • sys_exc (2to3 fixer)
  • sys_version (http.server.BaseHTTPRequestHandler の属性)
  • sysconf() (os モジュール)
  • sysconf_names (os モジュール)
  • sysconfig (モジュール)
  • syslog (モジュール)
  • syslog() (syslog モジュール)
  • SysLogHandler (logging.handlers のクラス)
  • system() (os モジュール)
    • (platform モジュール)
  • system_alias() (platform モジュール)
  • system_must_validate_cert() (test.support モジュール)
  • SystemError
    • (built-in exception), [1]
  • SystemExit
    • (built-in exception)
  • systemId (xml.dom.DocumentType の属性)
  • SystemRandom (random のクラス)
    • (secrets のクラス)
  • SystemRoot

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – T

  • T_FMT (locale モジュール)
  • T_FMT_AMPM (locale モジュール)
  • tab
  • tab() (tkinter.ttk.Notebook のメソッド)
  • TabError
  • tabnanny (モジュール)
  • tabs() (tkinter.ttk.Notebook のメソッド)
  • tabsize (textwrap.TextWrapper の属性)
  • tabular
    • data
  • tag (xml.etree.ElementTree.Element の属性)
  • tag_bind() (tkinter.ttk.Treeview のメソッド)
  • tag_configure() (tkinter.ttk.Treeview のメソッド)
  • tag_has() (tkinter.ttk.Treeview のメソッド)
  • tagName (xml.dom.Element の属性)
  • tail (xml.etree.ElementTree.Element の属性)
  • take_snapshot() (tracemalloc モジュール)
  • takewhile() (itertools モジュール)
  • tan() (cmath モジュール)
    • (math モジュール)
  • tanh() (cmath モジュール)
    • (math モジュール)
  • TarError
  • TarFile (tarfile のクラス), [1]
  • tarfile (モジュール)
  • tarfile コマンドラインオプション
    • --create <tarfile> <source1> ... <sourceN>
    • --extract <tarfile> [<output_dir>]
    • --list <tarfile>
    • --test <tarfile>
    • -c <tarfile> <source1> ... <sourceN>
    • -e <tarfile> [<output_dir>]
    • -l <tarfile>
    • -t <tarfile>
    • -v, --verbose
  • target
    • deletion
    • list, [1], [2]
    • list assignment
    • list, deletion
    • loop control
  • target (xml.dom.ProcessingInstruction の属性)
  • TarInfo (tarfile のクラス)
  • Task (asyncio のクラス)
  • task_done() (asyncio.Queue のメソッド)
    • (multiprocessing.JoinableQueue のメソッド)
    • (queue.Queue のメソッド)
  • tau (cmath モジュール)
    • (math モジュール)
  • tb_frame (traceback attribute)
  • tb_lasti (traceback attribute)
  • tb_lineno (traceback attribute)
  • tb_locals (unittest.TestResult の属性)
  • tb_next (traceback attribute)
  • tbreak (pdb command)
  • tcdrain() (termios モジュール)
  • tcflow() (termios モジュール)
  • tcflush() (termios モジュール)
  • tcgetattr() (termios モジュール)
  • tcgetpgrp() (os モジュール)
  • Tcl() (tkinter モジュール)
  • TCL_LIBRARY
  • TCPServer (socketserver のクラス)
  • tcsendbreak() (termios モジュール)
  • tcsetattr() (termios モジュール)
  • tcsetpgrp() (os モジュール)
  • tearDown() (unittest.TestCase のメソッド)
  • tearDownClass() (unittest.TestCase のメソッド)
  • tee() (itertools モジュール)
  • tell() (aifc.aifc のメソッド), [1]
    • (chunk.Chunk のメソッド)
    • (io.IOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (mmap.mmap のメソッド)
    • (sunau.AU_read のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_read のメソッド)
    • (wave.Wave_write のメソッド)
  • Telnet (telnetlib のクラス)
  • telnetlib (モジュール)
  • TEMP
  • temp_cwd() (test.support モジュール)
  • temp_dir() (test.support モジュール)
  • temp_umask() (test.support モジュール)
  • tempdir (tempfile モジュール)
  • tempfile (モジュール)
  • Template (pipes のクラス)
    • (string のクラス)
  • template (string.Template の属性)
  • temporary
    • file
    • file name
  • TemporaryDirectory() (tempfile モジュール)
  • TemporaryFile() (tempfile モジュール)
  • teredo (ipaddress.IPv6Address の属性)
  • TERM, [1]
  • termattrs() (curses モジュール)
  • terminal_size (os のクラス)
  • terminate() (asyncio.asyncio.subprocess.Process のメソッド)
    • (asyncio.SubprocessTransport のメソッド)
    • (multiprocessing.Process のメソッド)
    • (multiprocessing.pool.Pool のメソッド)
    • (subprocess.Popen のメソッド)
  • termination model
  • termios (モジュール)
  • termname() (curses モジュール)
  • ternary
    • operator
  • test
    • identity
    • membership
  • test (doctest.DocTestFailure の属性)
    • (doctest.UnexpectedException の属性)
    • (モジュール)
  • test() (cgi モジュール)
  • test.support (モジュール)
  • test.support.script_helper (モジュール)
  • TEST_DATA_DIR (test.support モジュール)
  • TEST_HOME_DIR (test.support モジュール)
  • TEST_SUPPORT_DIR (test.support モジュール)
  • TestCase (unittest のクラス)
  • TestFailed
  • testfile() (doctest モジュール)
  • TESTFN (test.support モジュール)
  • TESTFN_ENCODING (test.support モジュール)
  • TESTFN_NONASCII (test.support モジュール)
  • TESTFN_UNDECODABLE (test.support モジュール)
  • TESTFN_UNENCODABLE (test.support モジュール)
  • TESTFN_UNICODE (test.support モジュール)
  • TestHandler (test.support のクラス)
  • TestLoader (unittest のクラス)
  • testMethodPrefix (unittest.TestLoader の属性)
  • testmod() (doctest モジュール)
  • testNamePatterns (unittest.TestLoader の属性)
  • TestResult (unittest のクラス)
  • tests (imghdr モジュール)
  • testsource() (doctest モジュール)
  • testsRun (unittest.TestResult の属性)
  • TestSuite (unittest のクラス)
  • testzip() (zipfile.ZipFile のメソッド)
  • text (msilib モジュール)
    • (traceback.TracebackException の属性)
  • Text (typing のクラス)
  • text (xml.etree.ElementTree.Element の属性)
  • text encoding
  • text file
  • text mode
  • text() (cgitb モジュール)
    • (msilib.Dialog のメソッド)
  • text_factory (sqlite3.Connection の属性)
  • Textbox (curses.textpad のクラス)
  • TextCalendar (calendar のクラス)
  • textdomain() (gettext モジュール)
    • (locale モジュール)
  • TextFile (distutils.text_file のクラス)
  • textinput() (turtle モジュール)
  • TextIO (typing のクラス)
  • TextIOBase (io のクラス)
  • TextIOWrapper (io のクラス)
  • TextTestResult (unittest のクラス)
  • TextTestRunner (unittest のクラス)
  • textwrap (モジュール)
  • TextWrapper (textwrap のクラス)
  • theme_create() (tkinter.ttk.Style のメソッド)
  • theme_names() (tkinter.ttk.Style のメソッド)
  • theme_settings() (tkinter.ttk.Style のメソッド)
  • theme_use() (tkinter.ttk.Style のメソッド)
  • THOUSEP (locale モジュール)
  • Thread (threading のクラス)
  • thread() (imaplib.IMAP4 のメソッド)
  • thread_info (sys モジュール)
  • thread_time() (time モジュール)
  • thread_time_ns() (time モジュール)
  • threading (モジュール)
  • threading_cleanup() (test.support モジュール)
  • threading_setup() (test.support モジュール)
  • ThreadingHTTPServer (http.server のクラス)
  • ThreadingMixIn (socketserver のクラス)
  • ThreadingTCPServer (socketserver のクラス)
  • ThreadingUDPServer (socketserver のクラス)
  • ThreadPoolExecutor (concurrent.futures のクラス)
  • threads
    • POSIX
  • throw (2to3 fixer)
  • throw() (coroutine のメソッド)
    • (generator のメソッド)
  • ticket_lifetime_hint (ssl.SSLSession の属性)
  • tigetflag() (curses モジュール)
  • tigetnum() (curses モジュール)
  • tigetstr() (curses モジュール)
  • TILDE (token モジュール)
  • tilt() (turtle モジュール)
  • tiltangle() (turtle モジュール)
  • time (datetime のクラス)
    • (ssl.SSLSession の属性)
    • (モジュール)
  • time() (asyncio.loop のメソッド)
    • (datetime.datetime のメソッド)
    • (time モジュール)
  • Time2Internaldate() (imaplib モジュール)
  • time_ns() (time モジュール)
  • timedelta (datetime のクラス)
  • TimedRotatingFileHandler (logging.handlers のクラス)
  • timegm() (calendar モジュール)
  • timeit (モジュール)
  • timeit コマンドラインオプション
    • -h, --help
    • -n N, --number=N
    • -p, --process
    • -r N, --repeat=N
    • -s S, --setup=S
    • -u, --unit=U
    • -v, --verbose
  • timeit() (timeit モジュール)
    • (timeit.Timer のメソッド)
  • timeout
    • (socketserver.BaseServer の属性)
    • (ssl.SSLSession の属性)
    • (subprocess.TimeoutExpired の属性)
  • timeout() (curses.window のメソッド)
  • TIMEOUT_MAX (_thread モジュール)
    • (threading モジュール)
  • TimeoutError, [1], [2], [3]
  • TimeoutExpired
  • Timer (threading のクラス)
    • (timeit のクラス)
  • TimerHandle (asyncio のクラス)
  • times() (os モジュール)
  • TIMESTAMP (py_compile.PycInvalidationMode の属性)
  • timestamp() (datetime.datetime のメソッド)
  • timetuple() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
  • timetz() (datetime.datetime のメソッド)
  • timezone (datetime のクラス)
    • (time モジュール)
  • title() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
    • (turtle モジュール)
  • Tix
  • tix_addbitmapdir() (tkinter.tix.tixCommand のメソッド)
  • tix_cget() (tkinter.tix.tixCommand のメソッド)
  • tix_configure() (tkinter.tix.tixCommand のメソッド)
  • tix_filedialog() (tkinter.tix.tixCommand のメソッド)
  • tix_getbitmap() (tkinter.tix.tixCommand のメソッド)
  • tix_getimage() (tkinter.tix.tixCommand のメソッド)
  • TIX_LIBRARY
  • tix_option_get() (tkinter.tix.tixCommand のメソッド)
  • tix_resetoptions() (tkinter.tix.tixCommand のメソッド)
  • tixCommand (tkinter.tix のクラス)
  • Tk
    • (tkinter のクラス)
    • (tkinter.tix のクラス)
  • Tk Option Data Types
  • TK_LIBRARY
  • Tkinter
  • tkinter (モジュール)
  • tkinter.scrolledtext (モジュール)
  • tkinter.tix (モジュール)
  • tkinter.ttk (モジュール)
  • TList (tkinter.tix のクラス)
  • TLS
  • TLSv1 (ssl.TLSVersion の属性)
  • TLSv1_1 (ssl.TLSVersion の属性)
  • TLSv1_2 (ssl.TLSVersion の属性)
  • TLSv1_3 (ssl.TLSVersion の属性)
  • TLSVersion (ssl のクラス)
  • TMP
  • TMPDIR
  • to_bytes() (int のメソッド)
  • to_eng_string() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • to_integral() (decimal.Decimal のメソッド)
  • to_integral_exact() (decimal.Context のメソッド)
    • (decimal.Decimal のメソッド)
  • to_integral_value() (decimal.Decimal のメソッド)
  • to_sci_string() (decimal.Context のメソッド)
  • ToASCII() (encodings.idna モジュール)
  • tobuf() (tarfile.TarInfo のメソッド)
  • tobytes() (array.array のメソッド)
    • (memoryview のメソッド)
  • today() (datetime.date のクラスメソッド)
    • (datetime.datetime のクラスメソッド)
  • tofile() (array.array のメソッド)
  • tok_name (token モジュール)
  • token
    • (shlex.shlex の属性)
    • (モジュール)
  • token_bytes() (secrets モジュール)
  • token_hex() (secrets モジュール)
  • token_urlsafe() (secrets モジュール)
  • TokenError
  • tokenize (モジュール)
  • tokenize コマンドラインオプション
    • -e, --exact
    • -h, --help
  • tokenize() (tokenize モジュール)
  • tolist() (array.array のメソッド)
    • (memoryview のメソッド)
    • (parser.ST のメソッド)
  • tomono() (audioop モジュール)
  • toordinal() (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
  • top() (curses.panel.Panel のメソッド)
    • (poplib.POP3 のメソッド)
  • top_panel() (curses.panel モジュール)
  • toprettyxml() (xml.dom.minidom.Node のメソッド)
  • tostereo() (audioop モジュール)
  • tostring() (array.array のメソッド)
    • (xml.etree.ElementTree モジュール)
  • tostringlist() (xml.etree.ElementTree モジュール)
  • total_changes (sqlite3.Connection の属性)
  • total_ordering() (functools モジュール)
  • total_seconds() (datetime.timedelta のメソッド)
  • totuple() (parser.ST のメソッド)
  • touch() (pathlib.Path のメソッド)
  • touchline() (curses.window のメソッド)
  • touchwin() (curses.window のメソッド)
  • tounicode() (array.array のメソッド)
  • ToUnicode() (encodings.idna モジュール)
  • towards() (turtle モジュール)
  • toxml() (xml.dom.minidom.Node のメソッド)
  • tp_as_async (C のメンバ変数)
  • tp_as_mapping (C のメンバ変数)
  • tp_as_number (C のメンバ変数)
  • tp_as_sequence (C のメンバ変数)
  • tparm() (curses モジュール)
  • trace
    • stack
  • Trace (trace のクラス)
    • (tracemalloc のクラス)
  • trace (モジュール)
  • trace function, [1], [2]
  • trace コマンドラインオプション
    • --help
    • --ignore-dir=<dir>
    • --ignore-module=<mod>
    • --version
    • -C, --coverdir=<dir>
    • -R, --no-report
    • -T, --trackcalls
    • -c, --count
    • -f, --file=<file>
    • -g, --timing
    • -l, --listfuncs
    • -m, --missing
    • -r, --report
    • -s, --summary
    • -t, --trace
  • trace() (inspect モジュール)
  • trace_dispatch() (bdb.Bdb のメソッド)
  • traceback
    • オブジェクト, [1], [2], [3], [4]
  • Traceback (tracemalloc のクラス)
  • traceback (tracemalloc.Statistic の属性)
    • (tracemalloc.StatisticDiff の属性)
    • (tracemalloc.Trace の属性)
    • (モジュール)
  • traceback_limit (tracemalloc.Snapshot の属性)
    • (wsgiref.handlers.BaseHandler の属性)
  • TracebackException (traceback のクラス)
  • tracebacklimit (sys モジュール)
  • tracebacks
    • in CGI scripts
  • TracebackType (types のクラス)
  • tracemalloc (モジュール)
  • tracer() (turtle モジュール)
  • traces (tracemalloc.Snapshot の属性)
  • trailing
    • comma
  • transfercmd() (ftplib.FTP のメソッド)
  • transient_internet() (test.support モジュール)
  • TransientResource (test.support のクラス)
  • translate() (bytearray のメソッド)
    • (bytes のメソッド)
    • (fnmatch モジュール)
    • (str のメソッド)
  • translation() (gettext モジュール)
  • Transport (asyncio のクラス)
  • transport (asyncio.StreamWriter の属性)
  • Transport Layer Security
  • traverseproc (C のデータ型)
  • Tree (tkinter.tix のクラス)
  • TreeBuilder (xml.etree.ElementTree のクラス)
  • Treeview (tkinter.ttk のクラス)
  • triangular() (random モジュール)
  • triple-quoted string, [1]
  • True, [1], [2]
  • true
  • True (組み込み変数)
  • truediv() (operator モジュール)
  • trunc() (in module math)
    • (math モジュール)
  • truncate() (io.IOBase のメソッド)
    • (os モジュール)
  • truth
    • value
  • truth() (operator モジュール)
  • try
    • 文, [1], [2]
  • ttk
  • tty
    • I/O control
  • tty (モジュール)
  • ttyname() (os モジュール)
  • tuple
    • display
    • empty, [1]
    • singleton
    • オブジェクト, [1], [2], [3], [4], [5], [6]
    • 組み込み関数, [1]
  • Tuple (typing モジュール)
  • tuple (組み込みクラス)
  • tuple2st() (parser モジュール)
  • tuple_params (2to3 fixer)
  • Turtle (turtle のクラス)
  • turtle (モジュール)
  • turtledemo (モジュール)
  • turtles() (turtle モジュール)
  • TurtleScreen (turtle のクラス)
  • turtlesize() (turtle モジュール)
  • type, [1]
    • Boolean
    • data
    • hierarchy
    • immutable data
    • operations on dictionary
    • operations on list
    • オブジェクト, [1], [2]
    • 組み込み関数, [1], [2], [3]
  • type (optparse.Option の属性)
    • (socket.socket の属性)
    • (tarfile.TarInfo の属性)
  • Type (typing のクラス)
  • type (urllib.request.Request の属性)
    • (組み込みクラス)
  • type alias
  • type hint
  • type of an object
  • TYPE_CHECKER (optparse.Option の属性)
  • TYPE_CHECKING (typing モジュール)
  • typeahead() (curses モジュール)
  • typecode (array.array の属性)
  • typecodes (array モジュール)
  • TYPED_ACTIONS (optparse.Option の属性)
  • typed_subpart_iterator() (email.iterators モジュール)
  • TypeError
    • 例外
  • types
    • built-in
    • immutable sequence
    • mutable sequence
    • operations on integer
    • operations on mapping
    • operations on numeric
    • operations on sequence, [1]
    • モジュール
  • types (2to3 fixer)
  • TYPES (optparse.Option の属性)
  • types (モジュール)
  • types, internal
  • types_map (mimetypes モジュール)
    • (mimetypes.MimeTypes の属性)
  • types_map_inv (mimetypes.MimeTypes の属性)
  • TypeVar (typing のクラス)
  • typing (モジュール)
  • TZ, [1], [2], [3], [4], [5]
  • tzinfo (datetime のクラス)
    • (datetime.datetime の属性)
    • (datetime.time の属性)
  • tzname (time モジュール)
  • tzname() (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (datetime.timezone のメソッド)
    • (datetime.tzinfo のメソッド)
  • tzset() (time モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – U

  • u"
    • string literal
  • u'
    • string literal
  • u-LAW, [1], [2]
  • ucd_3_2_0 (unicodedata モジュール)
  • udata (select.kevent の属性)
  • UDPServer (socketserver のクラス)
  • UF_APPEND (stat モジュール)
  • UF_COMPRESSED (stat モジュール)
  • UF_HIDDEN (stat モジュール)
  • UF_IMMUTABLE (stat モジュール)
  • UF_NODUMP (stat モジュール)
  • UF_NOUNLINK (stat モジュール)
  • UF_OPAQUE (stat モジュール)
  • uid (tarfile.TarInfo の属性)
  • uid() (imaplib.IMAP4 のメソッド)
  • uidl() (poplib.POP3 のメソッド)
  • ulaw2lin() (audioop モジュール)
  • ULONG_MAX
  • umask() (os モジュール)
  • unalias (pdb command)
  • uname (tarfile.TarInfo の属性)
  • uname() (os モジュール)
    • (platform モジュール)
  • unary
    • arithmetic operation
    • bitwise operation
  • UNARY_INVERT (opcode)
  • UNARY_NEGATIVE (opcode)
  • UNARY_NOT (opcode)
  • UNARY_POSITIVE (opcode)
  • unbinding
    • name
  • UnboundLocalError, [1]
  • unbuffered I/O
  • UNC paths
    • and os.makedirs()
  • UNCHECKED_HASH (py_compile.PycInvalidationMode の属性)
  • unconsumed_tail (zlib.Decompress の属性)
  • unctrl() (curses モジュール)
    • (curses.ascii モジュール)
  • undefine_macro() (distutils.ccompiler.CCompiler のメソッド)
  • Underflow (decimal のクラス)
  • undisplay (pdb command)
  • undo() (turtle モジュール)
  • undobufferentries() (turtle モジュール)
  • undoc_header (cmd.Cmd の属性)
  • unescape() (html モジュール)
    • (xml.sax.saxutils モジュール)
  • UnexpectedException
  • unexpectedSuccesses (unittest.TestResult の属性)
  • unfreeze() (gc モジュール)
  • unget_wch() (curses モジュール)
  • ungetch() (curses モジュール)
    • (msvcrt モジュール)
  • ungetmouse() (curses モジュール)
  • ungetwch() (msvcrt モジュール)
  • unhexlify() (binascii モジュール)
  • Unicode, [1], [2]
    • database
  • unicode (2to3 fixer)
  • Unicode Consortium
  • unicodedata (モジュール)
  • UnicodeDecodeError
  • UnicodeEncodeError
  • UnicodeError
  • UnicodeTranslateError
  • UnicodeWarning
  • unidata_version (unicodedata モジュール)
  • unified_diff() (difflib モジュール)
  • uniform() (random モジュール)
  • UnimplementedFileMode
  • Union (ctypes のクラス)
    • (typing モジュール)
  • union() (frozenset のメソッド)
  • unique() (enum モジュール), [1]
  • unittest (モジュール)
  • unittest コマンドラインオプション
    • --locals
    • -b, --buffer
    • -c, --catch
    • -f, --failfast
    • -k
  • unittest-discover コマンドラインオプション
    • -p, --pattern pattern
    • -s, --start-directory directory
    • -t, --top-level-directory directory
    • -v, --verbose
  • unittest.mock (モジュール)
  • universal newlines
    • What's new, [1], [2], [3]
    • bytearray.splitlines method
    • bytes.splitlines method
    • csv.reader function
    • importlib.abc.InspectLoader.get_source method
    • io.IncrementalNewlineDecoder class
    • io.TextIOWrapper class
    • open() built-in function
    • str.splitlines method
    • subprocess module
  • UNIX
    • I/O control
    • file control
  • unix_dialect (csv のクラス)
  • unix_shell (test.support モジュール)
  • UnixDatagramServer (socketserver のクラス)
  • UnixStreamServer (socketserver のクラス)
  • unknown (uuid.SafeUUID の属性)
  • unknown_decl() (html.parser.HTMLParser のメソッド)
  • unknown_open() (urllib.request.BaseHandler のメソッド)
    • (urllib.request.UnknownHandler のメソッド)
  • UnknownHandler (urllib.request のクラス)
  • UnknownProtocol
  • UnknownTransferEncoding
  • unlink() (os モジュール)
    • (pathlib.Path のメソッド)
    • (test.support モジュール)
    • (xml.dom.minidom.Node のメソッド)
  • unload() (test.support モジュール)
  • unlock() (mailbox.Babyl のメソッド)
    • (mailbox.MH のメソッド)
    • (mailbox.MMDF のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (mailbox.mbox のメソッド)
  • unpack() (struct モジュール)
    • (struct.Struct のメソッド)
  • unpack_archive() (shutil モジュール)
  • unpack_array() (xdrlib.Unpacker のメソッド)
  • unpack_bytes() (xdrlib.Unpacker のメソッド)
  • unpack_double() (xdrlib.Unpacker のメソッド)
  • UNPACK_EX (opcode)
  • unpack_farray() (xdrlib.Unpacker のメソッド)
  • unpack_float() (xdrlib.Unpacker のメソッド)
  • unpack_fopaque() (xdrlib.Unpacker のメソッド)
  • unpack_from() (struct モジュール)
    • (struct.Struct のメソッド)
  • unpack_fstring() (xdrlib.Unpacker のメソッド)
  • unpack_list() (xdrlib.Unpacker のメソッド)
  • unpack_opaque() (xdrlib.Unpacker のメソッド)
  • UNPACK_SEQUENCE (opcode)
  • unpack_string() (xdrlib.Unpacker のメソッド)
  • Unpacker (xdrlib のクラス)
  • unpacking
    • dictionary
    • in function calls
    • iterable
  • unparsedEntityDecl() (xml.sax.handler.DTDHandler のメソッド)
  • UnparsedEntityDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • Unpickler (pickle のクラス)
  • UnpicklingError
  • unquote() (email.utils モジュール)
    • (urllib.parse モジュール)
  • unquote_plus() (urllib.parse モジュール)
  • unquote_to_bytes() (urllib.parse モジュール)
  • unreachable object
  • unreadline() (distutils.text_file.TextFile のメソッド)
  • unrecognized escape sequence
  • unregister() (atexit モジュール)
    • (faulthandler モジュール)
    • (select.devpoll のメソッド)
    • (select.epoll のメソッド)
    • (select.poll のメソッド)
    • (selectors.BaseSelector のメソッド)
  • unregister_archive_format() (shutil モジュール)
  • unregister_dialect() (csv モジュール)
  • unregister_unpack_format() (shutil モジュール)
  • unsafe (uuid.SafeUUID の属性)
  • unset() (test.support.EnvironmentVarGuard のメソッド)
  • unsetenv() (os モジュール)
  • UnstructuredHeader (email.headerregistry のクラス)
  • unsubscribe() (imaplib.IMAP4 のメソッド)
  • UnsupportedOperation
  • until (pdb command)
  • untokenize() (tokenize モジュール)
  • untouchwin() (curses.window のメソッド)
  • unused_data (bz2.BZ2Decompressor の属性)
    • (lzma.LZMADecompressor の属性)
    • (zlib.Decompress の属性)
  • unverifiable (urllib.request.Request の属性)
  • unwrap() (inspect モジュール)
    • (ssl.SSLSocket のメソッド)
  • up (pdb command)
  • up() (turtle モジュール)
  • update() (collections.Counter のメソッド)
    • (dict のメソッド)
    • (frozenset のメソッド)
    • (hashlib.hash のメソッド)
    • (hmac.HMAC のメソッド)
    • (http.cookies.Morsel のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (mailbox.Maildir のメソッド)
    • (trace.CoverageResults のメソッド)
    • (turtle モジュール)
  • update_authenticated() (urllib.request.HTTPPasswordMgrWithPriorAuth のメソッド)
  • update_lines_cols() (curses モジュール)
  • update_panels() (curses.panel モジュール)
  • update_visible() (mailbox.BabylMessage のメソッド)
  • update_wrapper() (functools モジュール)
  • upper() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • urandom() (os モジュール)
  • URL, [1], [2], [3]
    • parsing
    • relative
  • url (xmlrpc.client.ProtocolError の属性)
  • url2pathname() (urllib.request モジュール)
  • urlcleanup() (urllib.request モジュール)
  • urldefrag() (urllib.parse モジュール)
  • urlencode() (urllib.parse モジュール)
  • URLError
  • urljoin() (urllib.parse モジュール)
  • urllib (2to3 fixer)
    • (モジュール)
  • urllib.error (モジュール)
  • urllib.parse (モジュール)
  • urllib.request
    • モジュール
  • urllib.request (モジュール)
  • urllib.response (モジュール)
  • urllib.robotparser (モジュール)
  • urlopen() (urllib.request モジュール)
  • URLopener (urllib.request のクラス)
  • urlparse() (urllib.parse モジュール)
  • urlretrieve() (urllib.request モジュール)
  • urlsafe_b64decode() (base64 モジュール)
  • urlsafe_b64encode() (base64 モジュール)
  • urlsplit() (urllib.parse モジュール)
  • urlunparse() (urllib.parse モジュール)
  • urlunsplit() (urllib.parse モジュール)
  • urn (uuid.UUID の属性)
  • use_default_colors() (curses モジュール)
  • use_env() (curses モジュール)
  • use_rawinput (cmd.Cmd の属性)
  • UseForeignDTD() (xml.parsers.expat.xmlparser のメソッド)
  • USER
  • user
    • effective id
    • id
    • id, setting
  • user() (poplib.POP3 のメソッド)
  • user-defined
    • function
    • function call
    • method
  • user-defined function
    • オブジェクト, [1], [2]
  • user-defined method
    • オブジェクト
  • USER_BASE
    • (site モジュール)
  • user_call() (bdb.Bdb のメソッド)
  • user_exception() (bdb.Bdb のメソッド)
  • user_line() (bdb.Bdb のメソッド)
  • user_return() (bdb.Bdb のメソッド)
  • USER_SITE (site モジュール)
  • usercustomize
    • モジュール
  • UserDict (collections のクラス)
  • UserList (collections のクラス)
  • USERNAME, [1]
  • username (email.headerregistry.Address の属性)
  • USERPROFILE, [1]
  • userptr() (curses.panel.Panel のメソッド)
  • UserString (collections のクラス)
  • UserWarning
  • USTAR_FORMAT (tarfile モジュール)
  • UTC
  • utc (datetime.timezone の属性)
  • utcfromtimestamp() (datetime.datetime のクラスメソッド)
  • utcnow() (datetime.datetime のクラスメソッド)
  • utcoffset() (datetime.datetime のメソッド)
    • (datetime.time のメソッド)
    • (datetime.timezone のメソッド)
    • (datetime.tzinfo のメソッド)
  • utctimetuple() (datetime.datetime のメソッド)
  • utf8 (email.policy.EmailPolicy の属性)
  • utf8() (poplib.POP3 のメソッド)
  • utf8_enabled (imaplib.IMAP4 の属性)
  • utime() (os モジュール)
  • uu
    • モジュール
  • uu (モジュール)
  • UUID (uuid のクラス)
  • uuid (モジュール)
  • uuid1
  • uuid1() (uuid モジュール)
  • uuid3
  • uuid3() (uuid モジュール)
  • uuid4
  • uuid4() (uuid モジュール)
  • uuid5
  • uuid5() (uuid モジュール)
  • UuidCreate() (msilib モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – V

  • v4_int_to_packed() (ipaddress モジュール)
  • v6_int_to_packed() (ipaddress モジュール)
  • validator() (wsgiref.validate モジュール)
  • value
    • default parameter
    • truth
  • value (ctypes._SimpleCData の属性)
    • (http.cookiejar.Cookie の属性)
    • (http.cookies.Morsel の属性)
    • (xml.dom.Attr の属性)
  • value of an object
  • Value() (multiprocessing モジュール)
    • (multiprocessing.managers.SyncManager のメソッド)
    • (multiprocessing.sharedctypes モジュール)
  • value_decode() (http.cookies.BaseCookie のメソッド)
  • value_encode() (http.cookies.BaseCookie のメソッド)
  • ValueError
    • 例外
  • valuerefs() (weakref.WeakValueDictionary のメソッド)
  • values
    • Boolean
    • writing
  • values() (contextvars.Context のメソッド)
    • (dict のメソッド)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (mailbox.Mailbox のメソッド)
    • (types.MappingProxyType のメソッド)
  • ValuesView (collections.abc のクラス)
    • (typing のクラス)
  • var (contextvars.contextvars.Token.Token の属性)
  • variable
    • free
  • variable annotation
  • variance() (statistics モジュール)
  • variant (uuid.UUID の属性)
  • vars() (組み込み関数)
  • vbar (tkinter.scrolledtext.ScrolledText の属性)
  • VBAR (token モジュール)
  • VBAREQUAL (token モジュール)
  • Vec2D (turtle のクラス)
  • venv (モジュール)
  • VERBOSE (re モジュール)
  • verbose (tabnanny モジュール)
    • (test.support モジュール)
  • verify() (smtplib.SMTP のメソッド)
  • verify_client_post_handshake() (ssl.SSLSocket のメソッド)
  • verify_code (ssl.SSLCertVerificationError の属性)
  • VERIFY_CRL_CHECK_CHAIN (ssl モジュール)
  • VERIFY_CRL_CHECK_LEAF (ssl モジュール)
  • VERIFY_DEFAULT (ssl モジュール)
  • verify_flags (ssl.SSLContext の属性)
  • verify_message (ssl.SSLCertVerificationError の属性)
  • verify_mode (ssl.SSLContext の属性)
  • verify_request() (socketserver.BaseServer のメソッド)
  • VERIFY_X509_STRICT (ssl モジュール)
  • VERIFY_X509_TRUSTED_FIRST (ssl モジュール)
  • VerifyFlags (ssl のクラス)
  • VerifyMode (ssl のクラス)
  • version (curses モジュール)
    • (email.headerregistry.MIMEVersionHeader の属性)
    • (http.client.HTTPResponse の属性)
    • (http.cookiejar.Cookie の属性)
    • (in module sys), [1], [2]
    • (ipaddress.IPv4Address の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Address の属性)
    • (ipaddress.IPv6Network の属性)
    • (marshal モジュール)
    • (sqlite3 モジュール)
    • (sys モジュール)
    • (urllib.request.URLopener の属性)
    • (uuid.UUID の属性)
  • version() (ensurepip モジュール)
    • (platform モジュール)
    • (ssl.SSLSocket のメソッド)
  • version_info (sqlite3 モジュール)
    • (sys モジュール)
  • version_string() (http.server.BaseHTTPRequestHandler のメソッド)
  • vformat() (string.Formatter のメソッド)
  • virtual
    • Environments
  • virtual environment
  • virtual machine
  • visit() (ast.NodeVisitor のメソッド)
  • visitproc (C のデータ型)
  • vline() (curses.window のメソッド)
  • voidcmd() (ftplib.FTP のメソッド)
  • volume (zipfile.ZipInfo の属性)
  • vonmisesvariate() (random モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – W

  • W_OK (os モジュール)
  • wait() (asyncio モジュール)
    • (asyncio.Condition のメソッド)
    • (asyncio.Event のメソッド)
    • (asyncio.asyncio.subprocess.Process のメソッド)
    • (concurrent.futures モジュール)
    • (multiprocessing.connection モジュール)
    • (multiprocessing.pool.AsyncResult のメソッド)
    • (os モジュール)
    • (subprocess.Popen のメソッド)
    • (threading.Barrier のメソッド)
    • (threading.Condition のメソッド)
    • (threading.Event のメソッド)
  • wait3() (os モジュール)
  • wait4() (os モジュール)
  • wait_closed() (asyncio.Server のメソッド)
    • (asyncio.StreamWriter のメソッド)
  • wait_for() (asyncio モジュール)
    • (asyncio.Condition のメソッド)
    • (threading.Condition のメソッド)
  • wait_threads_exit() (test.support モジュール)
  • waitid() (os モジュール)
  • waitpid() (os モジュール)
  • walk() (ast モジュール)
    • (email.message.EmailMessage のメソッド)
    • (email.message.Message のメソッド)
    • (os モジュール)
  • walk_packages() (pkgutil モジュール)
  • walk_stack() (traceback モジュール)
  • walk_tb() (traceback モジュール)
  • want (doctest.Example の属性)
  • warn() (distutils.ccompiler.CCompiler のメソッド)
    • (distutils.text_file.TextFile のメソッド)
    • (warnings モジュール)
  • warn_explicit() (warnings モジュール)
  • Warning, [1]
  • warning() (logging モジュール)
    • (logging.Logger のメソッド)
    • (xml.sax.handler.ErrorHandler のメソッド)
  • warnings
    • (モジュール)
  • WarningsRecorder (test.support のクラス)
  • warnoptions (sys モジュール)
  • wasSuccessful() (unittest.TestResult のメソッド)
  • WatchedFileHandler (logging.handlers のクラス)
  • wave (モジュール)
  • WCONTINUED (os モジュール)
  • WCOREDUMP() (os モジュール)
  • WeakKeyDictionary (weakref のクラス)
  • WeakMethod (weakref のクラス)
  • weakref (モジュール)
  • WeakSet (weakref のクラス)
  • WeakValueDictionary (weakref のクラス)
  • webbrowser (モジュール)
  • weekday() (calendar モジュール)
    • (datetime.date のメソッド)
    • (datetime.datetime のメソッド)
  • weekheader() (calendar モジュール)
  • weibullvariate() (random モジュール)
  • WEXITED (os モジュール)
  • WEXITSTATUS() (os モジュール)
  • wfile (http.server.BaseHTTPRequestHandler の属性)
  • what() (imghdr モジュール)
    • (sndhdr モジュール)
  • whathdr() (sndhdr モジュール)
  • whatis (pdb command)
  • when() (asyncio.TimerHandle のメソッド)
  • where (pdb command)
  • which() (shutil モジュール)
  • whichdb() (dbm モジュール)
  • while
    • 文, [1], [2], [3]
  • whitespace (shlex.shlex の属性)
    • (string モジュール)
  • whitespace_split (shlex.shlex の属性)
  • Widget (tkinter.ttk のクラス)
  • width (textwrap.TextWrapper の属性)
  • width() (turtle モジュール)
  • WIFCONTINUED() (os モジュール)
  • WIFEXITED() (os モジュール)
  • WIFSIGNALED() (os モジュール)
  • WIFSTOPPED() (os モジュール)
  • win32_ver() (platform モジュール)
  • WinDLL (ctypes のクラス)
  • window manager (widgets)
  • window() (curses.panel.Panel のメソッド)
  • window_height() (turtle モジュール)
  • window_width() (turtle モジュール)
  • Windows
  • Windows ini file
  • WindowsError
  • WindowsPath (pathlib のクラス)
  • WindowsProactorEventLoopPolicy (asyncio のクラス)
  • WindowsRegistryFinder (importlib.machinery のクラス)
  • winerror (OSError の属性)
  • WinError() (ctypes モジュール)
  • WINFUNCTYPE() (ctypes モジュール)
  • winreg (モジュール)
  • WinSock
  • winsound (モジュール)
  • winver (sys モジュール)
  • with
    • 文, [1]
  • WITH_CLEANUP_FINISH (opcode)
  • WITH_CLEANUP_START (opcode)
  • with_hostmask (ipaddress.IPv4Interface の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Interface の属性)
    • (ipaddress.IPv6Network の属性)
  • with_name() (pathlib.PurePath のメソッド)
  • with_netmask (ipaddress.IPv4Interface の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Interface の属性)
    • (ipaddress.IPv6Network の属性)
  • with_prefixlen (ipaddress.IPv4Interface の属性)
    • (ipaddress.IPv4Network の属性)
    • (ipaddress.IPv6Interface の属性)
    • (ipaddress.IPv6Network の属性)
  • with_pymalloc() (test.support モジュール)
  • with_suffix() (pathlib.PurePath のメソッド)
  • with_traceback() (BaseException のメソッド)
  • WNOHANG (os モジュール)
  • WNOWAIT (os モジュール)
  • wordchars (shlex.shlex の属性)
  • World Wide Web, [1], [2]
  • wrap() (textwrap モジュール)
    • (textwrap.TextWrapper のメソッド)
  • wrap_bio() (ssl.SSLContext のメソッド)
  • wrap_future() (asyncio モジュール)
  • wrap_socket() (ssl モジュール)
    • (ssl.SSLContext のメソッド)
  • wrap_text() (distutils.fancy_getopt モジュール)
  • wrapper() (curses モジュール)
  • WrapperDescriptorType (types モジュール)
  • wraps() (functools モジュール)
  • WRITABLE (tkinter モジュール)
  • writable() (asyncore.dispatcher のメソッド)
    • (io.IOBase のメソッド)
  • write() (asyncio.StreamWriter のメソッド)
    • (asyncio.WriteTransport のメソッド)
    • (code.InteractiveInterpreter のメソッド)
    • (codecs.StreamWriter のメソッド)
    • (configparser.ConfigParser のメソッド)
    • (email.generator.BytesGenerator のメソッド)
    • (email.generator.Generator のメソッド)
    • (io.BufferedIOBase のメソッド)
    • (io.BufferedWriter のメソッド)
    • (io.RawIOBase のメソッド)
    • (io.TextIOBase のメソッド)
    • (mmap.mmap のメソッド)
    • (os モジュール)
    • (ossaudiodev.oss_audio_device のメソッド)
    • (ssl.MemoryBIO のメソッド)
    • (ssl.SSLSocket のメソッド)
    • (telnetlib.Telnet のメソッド)
    • (turtle モジュール)
    • (xml.etree.ElementTree.ElementTree のメソッド)
    • (zipfile.ZipFile のメソッド)
  • write_byte() (mmap.mmap のメソッド)
  • write_bytes() (pathlib.Path のメソッド)
  • write_docstringdict() (turtle モジュール)
  • write_eof() (asyncio.StreamWriter のメソッド)
    • (asyncio.WriteTransport のメソッド)
    • (ssl.MemoryBIO のメソッド)
  • write_file() (distutils.file_util モジュール)
  • write_history_file() (readline モジュール)
  • WRITE_RESTRICTED
  • write_results() (trace.CoverageResults のメソッド)
  • write_text() (pathlib.Path のメソッド)
  • write_through (io.TextIOWrapper の属性)
  • writeall() (ossaudiodev.oss_audio_device のメソッド)
  • writeframes() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • writeframesraw() (aifc.aifc のメソッド)
    • (sunau.AU_write のメソッド)
    • (wave.Wave_write のメソッド)
  • writeheader() (csv.DictWriter のメソッド)
  • writelines() (asyncio.StreamWriter のメソッド)
    • (asyncio.WriteTransport のメソッド)
    • (codecs.StreamWriter のメソッド)
    • (io.IOBase のメソッド)
  • writePlist() (plistlib モジュール)
  • writePlistToBytes() (plistlib モジュール)
  • writepy() (zipfile.PyZipFile のメソッド)
  • writer (formatter.formatter の属性)
  • writer() (csv モジュール)
  • writerow() (csv.csvwriter のメソッド)
  • writerows() (csv.csvwriter のメソッド)
  • writestr() (zipfile.ZipFile のメソッド)
  • WriteTransport (asyncio のクラス)
  • writev() (os モジュール)
  • writexml() (xml.dom.minidom.Node のメソッド)
  • writing
    • values
  • WrongDocumentErr
  • ws_comma (2to3 fixer)
  • wsgi_file_wrapper (wsgiref.handlers.BaseHandler の属性)
  • wsgi_multiprocess (wsgiref.handlers.BaseHandler の属性)
  • wsgi_multithread (wsgiref.handlers.BaseHandler の属性)
  • wsgi_run_once (wsgiref.handlers.BaseHandler の属性)
  • wsgiref (モジュール)
  • wsgiref.handlers (モジュール)
  • wsgiref.headers (モジュール)
  • wsgiref.simple_server (モジュール)
  • wsgiref.util (モジュール)
  • wsgiref.validate (モジュール)
  • WSGIRequestHandler (wsgiref.simple_server のクラス)
  • WSGIServer (wsgiref.simple_server のクラス)
  • wShowWindow (subprocess.STARTUPINFO の属性)
  • WSTOPPED (os モジュール)
  • WSTOPSIG() (os モジュール)
  • wstring_at() (ctypes モジュール)
  • WTERMSIG() (os モジュール)
  • WUNTRACED (os モジュール)
  • WWW, [1], [2]
    • server, [1]

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – X

  • X (re モジュール)
  • X509 certificate
  • X_OK (os モジュール)
  • xatom() (imaplib.IMAP4 のメソッド)
  • XATTR_CREATE (os モジュール)
  • XATTR_REPLACE (os モジュール)
  • XATTR_SIZE_MAX (os モジュール)
  • xcor() (turtle モジュール)
  • XDR
  • xdrlib (モジュール)
  • xhdr() (nntplib.NNTP のメソッド)
  • XHTML
  • XHTML_NAMESPACE (xml.dom モジュール)
  • xml (モジュール)
  • XML() (xml.etree.ElementTree モジュール)
  • xml.dom (モジュール)
  • xml.dom.minidom (モジュール)
  • xml.dom.pulldom (モジュール)
  • xml.etree.ElementTree (モジュール)
  • xml.parsers.expat (モジュール)
  • xml.parsers.expat.errors (モジュール)
  • xml.parsers.expat.model (モジュール)
  • xml.sax (モジュール)
  • xml.sax.handler (モジュール)
  • xml.sax.saxutils (モジュール)
  • xml.sax.xmlreader (モジュール)
  • XML_ERROR_ABORTED (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.parsers.expat.errors モジュール)
  • XML_ERROR_BINARY_ENTITY_REF (xml.parsers.expat.errors モジュール)
  • XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING (xml.parsers.expat.errors モジュール)
  • XML_ERROR_DUPLICATE_ATTRIBUTE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_ENTITY_DECLARED_IN_PE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_EXTERNAL_ENTITY_HANDLING (xml.parsers.expat.errors モジュール)
  • XML_ERROR_FEATURE_REQUIRES_XML_DTD (xml.parsers.expat.errors モジュール)
  • XML_ERROR_FINISHED (xml.parsers.expat.errors モジュール)
  • XML_ERROR_INCOMPLETE_PE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_INCORRECT_ENCODING (xml.parsers.expat.errors モジュール)
  • XML_ERROR_INVALID_TOKEN (xml.parsers.expat.errors モジュール)
  • XML_ERROR_JUNK_AFTER_DOC_ELEMENT (xml.parsers.expat.errors モジュール)
  • XML_ERROR_MISPLACED_XML_PI (xml.parsers.expat.errors モジュール)
  • XML_ERROR_NO_ELEMENTS (xml.parsers.expat.errors モジュール)
  • XML_ERROR_NO_MEMORY (xml.parsers.expat.errors モジュール)
  • XML_ERROR_NOT_STANDALONE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_NOT_SUSPENDED (xml.parsers.expat.errors モジュール)
  • XML_ERROR_PARAM_ENTITY_REF (xml.parsers.expat.errors モジュール)
  • XML_ERROR_PARTIAL_CHAR (xml.parsers.expat.errors モジュール)
  • XML_ERROR_PUBLICID (xml.parsers.expat.errors モジュール)
  • XML_ERROR_RECURSIVE_ENTITY_REF (xml.parsers.expat.errors モジュール)
  • XML_ERROR_SUSPEND_PE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_SUSPENDED (xml.parsers.expat.errors モジュール)
  • XML_ERROR_SYNTAX (xml.parsers.expat.errors モジュール)
  • XML_ERROR_TAG_MISMATCH (xml.parsers.expat.errors モジュール)
  • XML_ERROR_TEXT_DECL (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNBOUND_PREFIX (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNCLOSED_CDATA_SECTION (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNCLOSED_TOKEN (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNDECLARING_PREFIX (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNDEFINED_ENTITY (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNEXPECTED_STATE (xml.parsers.expat.errors モジュール)
  • XML_ERROR_UNKNOWN_ENCODING (xml.parsers.expat.errors モジュール)
  • XML_ERROR_XML_DECL (xml.parsers.expat.errors モジュール)
  • XML_NAMESPACE (xml.dom モジュール)
  • xmlcharrefreplace_errors() (codecs モジュール)
  • XmlDeclHandler() (xml.parsers.expat.xmlparser のメソッド)
  • XMLFilterBase (xml.sax.saxutils のクラス)
  • XMLGenerator (xml.sax.saxutils のクラス)
  • XMLID() (xml.etree.ElementTree モジュール)
  • XMLNS_NAMESPACE (xml.dom モジュール)
  • XMLParser (xml.etree.ElementTree のクラス)
  • XMLParserType (xml.parsers.expat モジュール)
  • XMLPullParser (xml.etree.ElementTree のクラス)
  • XMLReader (xml.sax.xmlreader のクラス)
  • xmlrpc.client (モジュール)
  • xmlrpc.server (モジュール)
  • xor
    • bitwise
  • xor() (operator モジュール)
  • xover() (nntplib.NNTP のメソッド)
  • xpath() (nntplib.NNTP のメソッド)
  • xrange (2to3 fixer)
  • xreadlines (2to3 fixer)
  • xview() (tkinter.ttk.Treeview のメソッド)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – Y

  • Y2K
  • ycor() (turtle モジュール)
  • year (datetime.date の属性)
    • (datetime.datetime の属性)
  • Year 2000
  • Year 2038
  • yeardatescalendar() (calendar.Calendar のメソッド)
  • yeardays2calendar() (calendar.Calendar のメソッド)
  • yeardayscalendar() (calendar.Calendar のメソッド)
  • YESEXPR (locale モジュール)
  • yield
    • examples
    • expression
    • yield from (in What's New)
    • キーワード
    • 文
  • YIELD_FROM (opcode)
  • YIELD_VALUE (opcode)
  • yiq_to_rgb() (colorsys モジュール)
  • yview() (tkinter.ttk.Treeview のメソッド)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – Z

  • Zen of Python
  • ZeroDivisionError
    • 例外
  • zfill() (bytearray のメソッド)
    • (bytes のメソッド)
    • (str のメソッド)
  • zip (2to3 fixer)
  • zip() (組み込み関数)
  • ZIP_BZIP2 (zipfile モジュール)
  • ZIP_DEFLATED (zipfile モジュール)
  • zip_longest() (itertools モジュール)
  • ZIP_LZMA (zipfile モジュール)
  • ZIP_STORED (zipfile モジュール)
  • zipapp (モジュール)
  • zipapp コマンドラインオプション
    • --info
    • -c, --compress
    • -h, --help
    • -m <mainfn>, --main=<mainfn>
    • -o <output>, --output=<output>
    • -p <interpreter>, --python=<interpreter>
  • ZipFile (zipfile のクラス)
  • zipfile (モジュール)
  • zipfile コマンドラインオプション
    • --create <zipfile> <source1> ... <sourceN>
    • --extract <zipfile> <output_dir>
    • --list <zipfile>
    • --test <zipfile>
    • -c <zipfile> <source1> ... <sourceN>
    • -e <zipfile> <output_dir>
    • -l <zipfile>
    • -t <zipfile>
  • zipimport (モジュール)
  • zipimporter (zipimport のクラス)
  • ZipImportError
  • ZipInfo (zipfile のクラス)
  • zlib (モジュール)
  • ZLIB_RUNTIME_VERSION (zlib モジュール)
  • ZLIB_VERSION (zlib モジュール)

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – オ

  • オブジェクト
    • Boolean, [1]
    • Capsule
    • Ellipsis
    • None, [1], [2]
    • NotImplemented
    • asynchronous-generator
    • built-in function, [1]
    • built-in method, [1]
    • bytearray, [1], [2], [3]
    • bytes, [1], [2]
    • callable, [1]
    • class, [1], [2]
    • class instance, [1], [2]
    • complex
    • complex number, [1]
    • dictionary, [1], [2], [3], [4], [5], [6], [7]
    • file, [1]
    • floating point, [1], [2]
    • frame
    • frozenset, [1]
    • function, [1], [2], [3], [4], [5]
    • generator, [1], [2]
    • immutable
    • immutable sequence
    • instance, [1], [2]
    • instancemethod
    • integer, [1], [2]
    • io.StringIO
    • list, [1], [2], [3], [4], [5], [6], [7], [8]
    • long integer
    • mapping, [1], [2], [3], [4], [5]
    • memoryview, [1]
    • method, [1], [2], [3], [4], [5]
    • module, [1], [2]
    • mutable, [1], [2]
    • mutable sequence
    • numeric, [1], [2], [3]
    • range
    • sequence, [1], [2], [3], [4], [5], [6], [7], [8]
    • set, [1], [2], [3]
    • set type
    • slice
    • socket
    • string, [1], [2]
    • traceback, [1], [2], [3], [4]
    • tuple, [1], [2], [3], [4], [5], [6]
    • type, [1], [2]
    • user-defined function, [1], [2]
    • user-defined method

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – キ

  • キーワード
    • as, [1], [2]
    • async
    • await, [1]
    • elif
    • else, [1], [2], [3], [4], [5], [6], [7]
    • except
    • finally, [1], [2], [3], [4]
    • from, [1]
    • in, [1]
    • yield

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – コ

  • コマンドラインオプション
    • --check-hash-based-pycs default|always|never
    • --help
    • --version
    • -?
    • -B
    • -E
    • -I
    • -J
    • -O
    • -OO
    • -R
    • -S
    • -V
    • -W arg
    • -X
    • -b
    • -c <command>
    • -d
    • -h
    • -i
    • -m <module-name>
    • -q
    • -s
    • -u
    • -v
    • -x

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – メ

  • メソッド

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – モ

  • モジュール
    • __main__, [1], [2], [3], [4], [5], [6], [7]
    • _locale
    • _thread
    • array, [1]
    • base64
    • bdb
    • binhex
    • builtins, [1], [2], [3], [4]
    • cmd
    • copy
    • crypt
    • dbm.gnu, [1]
    • dbm.ndbm, [1]
    • errno
    • glob
    • imp
    • io
    • json
    • math, [1]
    • os
    • pickle, [1], [2], [3]
    • pty
    • pwd
    • pyexpat
    • re, [1]
    • shelve
    • signal, [1]
    • sitecustomize
    • socket
    • stat
    • string
    • struct
    • sys, [1], [2], [3], [4], [5], [6]
    • types
    • urllib.request
    • usercustomize
    • uu

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – 例

  • 例外
    • AssertionError
    • AttributeError
    • GeneratorExit, [1]
    • ImportError
    • NameError
    • StopAsyncIteration
    • StopIteration, [1]
    • TypeError
    • ValueError
    • ZeroDivisionError

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – 文

  • 文
    • assert, [1]
    • async def
    • async for
    • async with
    • break, [1], [2], [3], [4]
    • class
    • continue, [1], [2], [3], [4]
    • def
    • del, [1], [2], [3]
    • except
    • for, [1], [2], [3]
    • global, [1]
    • if, [1]
    • import, [1], [2], [3], [4]
    • nonlocal
    • pass
    • raise, [1]
    • return, [1], [2]
    • try, [1], [2]
    • while, [1], [2], [3]
    • with, [1]
    • yield

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – 演

  • 演算子
    • !=, [1]
    • % (percent), [1]
    • & (ampersand), [1]
    • * (asterisk), [1]
    • **, [1]
    • / (slash), [1]
    • //, [1]
    • < (less), [1]
    • <<, [1]
    • <=, [1]
    • ==, [1]
    • > (greater), [1]
    • >=, [1]
    • >>, [1]
    • @ (at)
    • ^ (caret), [1]
    • and, [1], [2]
    • in, [1], [2]
    • is, [1]
    • is not, [1]
    • not, [1]
    • not in, [1], [2]
    • or, [1], [2]
    • | (vertical bar), [1]
    • ~ (tilde), [1]

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – 環

  • 環境変数
    • APPDATA
    • AUDIODEV
    • BROWSER, [1]
    • CC
    • CFLAGS, [1], [2], [3]
    • COLS, [1]
    • COLUMNS, [1]
    • COMSPEC, [1]
    • CPP
    • CPPFLAGS
    • DISTUTILS_DEBUG
    • HOME, [1], [2], [3], [4]
    • HOMEDRIVE, [1]
    • HOMEPATH, [1]
    • IDLESTARTUP, [1], [2]
    • KDEDIR
    • LANG, [1], [2], [3], [4]
    • LANGUAGE, [1]
    • LC_ALL, [1]
    • LC_MESSAGES, [1]
    • LDCXXSHARED
    • LDFLAGS
    • LINES, [1], [2], [3], [4]
    • LNAME
    • LOGNAME, [1]
    • MIXERDEV
    • PAGER
    • PATH, [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], [31], [32], [33], [34], [35]
    • PATHEXT, [1], [2]
    • PLAT
    • POSIXLY_CORRECT
    • PYTHON*, [1], [2], [3]
    • PYTHONASYNCIODEBUG, [1], [2]
    • PYTHONBREAKPOINT, [1], [2], [3], [4]
    • PYTHONCASEOK, [1]
    • PYTHONCOERCECLOCALE, [1], [2]
    • PYTHONDEBUG, [1], [2]
    • PYTHONDEVMODE, [1], [2]
    • PYTHONDOCS
    • PYTHONDONTWRITEBYTECODE, [1], [2], [3], [4], [5], [6]
    • PYTHONDUMPREFS, [1]
    • PYTHONEXECUTABLE
    • PYTHONFAULTHANDLER, [1], [2]
    • PYTHONHASHSEED, [1], [2], [3], [4], [5], [6], [7], [8], [9]
    • PYTHONHOME, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16]
    • PYTHONINSPECT, [1], [2], [3]
    • PYTHONIOENCODING, [1], [2], [3], [4], [5], [6], [7]
    • PYTHONLEGACYWINDOWSFSENCODING, [1], [2], [3]
    • PYTHONLEGACYWINDOWSSTDIO, [1], [2], [3]
    • PYTHONMALLOC, [1], [2], [3], [4], [5], [6], [7]
    • PYTHONMALLOCSTATS, [1], [2]
    • PYTHONNOUSERSITE, [1], [2], [3], [4], [5]
    • PYTHONOPTIMIZE, [1], [2]
    • PYTHONPATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24]
    • PYTHONPROFILEIMPORTTIME, [1], [2], [3]
    • PYTHONSHOWALLOCCOUNT
    • PYTHONSHOWREFCOUNT
    • PYTHONSTARTUP, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]
    • PYTHONTHREADDEBUG
    • PYTHONTRACEMALLOC, [1], [2], [3]
    • PYTHONUNBUFFERED, [1], [2]
    • PYTHONUSERBASE, [1], [2], [3]
    • PYTHONUSERSITE
    • PYTHONUTF8, [1], [2], [3]
    • PYTHONVERBOSE, [1], [2]
    • PYTHONWARNINGS, [1], [2], [3], [4], [5], [6], [7], [8]
    • PYTHON_DOM
    • SOURCE_DATE_EPOCH, [1], [2], [3], [4], [5], [6]
    • SSL_CERT_FILE
    • SSL_CERT_PATH
    • SystemRoot
    • TCL_LIBRARY
    • TEMP
    • TERM, [1]
    • TIX_LIBRARY
    • TK_LIBRARY
    • TMP
    • TMPDIR
    • TZ, [1], [2], [3], [4], [5]
    • USER
    • USERNAME, [1]
    • USERPROFILE, [1]
    • USER_BASE
    • exec_prefix, [1], [2]
    • http_proxy, [1], [2]
    • no_proxy
    • prefix, [1], [2], [3]

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – 組

  • 組み込み関数
    • __import__
    • abs, [1]
    • ascii
    • bytes, [1]
    • chr
    • classmethod
    • compile, [1], [2], [3], [4]
    • complex, [1]
    • divmod, [1], [2]
    • eval, [1], [2], [3], [4], [5]
    • exec, [1], [2], [3]
    • float, [1], [2]
    • hash, [1], [2], [3]
    • help
    • id
    • int, [1], [2]
    • len, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]
    • max
    • min
    • open, [1]
    • ord
    • pow, [1], [2], [3], [4], [5]
    • print
    • range
    • repr, [1], [2], [3]
    • round
    • slice, [1]
    • staticmethod
    • tuple, [1]
    • type, [1], [2], [3]

ナビゲーション

  • 索引
  • モジュール |


索引

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

索引 – 記号

  • ! (exclamation)
    • in a command interpreter
    • in curses module
    • in formatted string literal
    • in glob-style wildcards, [1]
    • in string formatting
    • in struct format strings
  • ! (pdb command)
  • !=
    • 演算子, [1]
  • " (double quote)
    • string literal
  • """
    • string literal
  • # (hash)
    • comment, [1], [2]
    • in doctests
    • in printf-style formatting, [1]
    • in regular expressions
    • in string formatting
    • source encoding declaration
  • $ (dollar)
    • environment variables expansion
    • in regular expressions
    • in template strings
    • interpolation in configuration files
  • % (percent)
    • datetime format, [1], [2]
    • environment variables expansion (Windows), [1]
    • interpolation in configuration files
    • printf-style formatting, [1]
    • 演算子, [1]
  • %=
    • augmented assignment
  • & (ampersand)
    • 演算子, [1]
  • &=
    • augmented assignment
  • ' (single quote)
    • string literal
  • '''
    • string literal
  • () (parentheses)
    • call
    • class definition
    • function definition
    • generator expression
    • in assignment target list
    • in printf-style formatting, [1]
    • in regular expressions
    • tuple display
  • (?
    • in regular expressions
  • (?!
    • in regular expressions
  • (?#
    • in regular expressions
  • (?:
    • in regular expressions
  • (?<!
    • in regular expressions
  • (?<=
    • in regular expressions
  • (?P<
    • in regular expressions
  • (?P=
    • in regular expressions
  • * (asterisk)
    • function definition
    • import statement
    • in AST grammar
    • in argparse module
    • in assignment target list
    • in expression lists
    • in function calls, [1]
    • in glob-style wildcards, [1]
    • in printf-style formatting, [1]
    • in regular expressions
    • 演算子, [1]
  • **
    • function definition
    • in dictionary displays
    • in function calls, [1]
    • in glob-style wildcards
    • 演算子, [1]
  • **=
    • augmented assignment
  • *=
    • augmented assignment
  • *?
    • in regular expressions
  • + (plus)
    • binary operator, [1]
    • in argparse module
    • in doctests
    • in printf-style formatting, [1]
    • in regular expressions
    • in string formatting
    • unary operator, [1]
  • +=
    • augmented assignment
  • +?
    • in regular expressions
  • , (comma)
    • argument list
    • expression list, [1], [2], [3], [4]
    • identifier list, [1]
    • import statement
    • in dictionary displays
    • in string formatting
    • in target list
    • parameter list
    • slicing
    • tuple display
    • with statement
  • - (minus)
    • binary operator, [1]
    • in doctests
    • in glob-style wildcards, [1]
    • in printf-style formatting, [1]
    • in regular expressions
    • in string formatting
    • unary operator, [1]
  • --check-hash-based-pycs default|always|never
    • コマンドラインオプション
  • --create <tarfile> <source1> ... <sourceN>
    • tarfile コマンドラインオプション
  • --create <zipfile> <source1> ... <sourceN>
    • zipfile コマンドラインオプション
  • --details
    • inspect コマンドラインオプション
  • --extract <tarfile> [<output_dir>]
    • tarfile コマンドラインオプション
  • --extract <zipfile> <output_dir>
    • zipfile コマンドラインオプション
  • --help
    • trace コマンドラインオプション
    • コマンドラインオプション
  • --ignore-dir=<dir>
    • trace コマンドラインオプション
  • --ignore-module=<mod>
    • trace コマンドラインオプション
  • --info
    • zipapp コマンドラインオプション
  • --invalidation-mode [timestamp|checked-hash|unchecked-hash]
    • compileall コマンドラインオプション
  • --list <tarfile>
    • tarfile コマンドラインオプション
  • --list <zipfile>
    • zipfile コマンドラインオプション
  • --locals
    • unittest コマンドラインオプション
  • --sort-keys
    • json.tool コマンドラインオプション
  • --test <tarfile>
    • tarfile コマンドラインオプション
  • --test <zipfile>
    • zipfile コマンドラインオプション
  • --user-base
    • site コマンドラインオプション
  • --user-site
    • site コマンドラインオプション
  • --version
    • trace コマンドラインオプション
    • コマンドラインオプション
  • -=
    • augmented assignment
  • ->
    • function annotations, [1]
  • -?
    • コマンドラインオプション
  • -a, --annotate
    • pickletools コマンドラインオプション
  • -B
    • コマンドラインオプション
  • -b
    • compileall コマンドラインオプション
    • コマンドラインオプション
  • -b, --buffer
    • unittest コマンドラインオプション
  • -c <command>
    • コマンドラインオプション
  • -c <tarfile> <source1> ... <sourceN>
    • tarfile コマンドラインオプション
  • -c <zipfile> <source1> ... <sourceN>
    • zipfile コマンドラインオプション
  • -c, --catch
    • unittest コマンドラインオプション
  • -c, --compress
    • zipapp コマンドラインオプション
  • -c, --count
    • trace コマンドラインオプション
  • -C, --coverdir=<dir>
    • trace コマンドラインオプション
  • -d
    • コマンドラインオプション
  • -d destdir
    • compileall コマンドラインオプション
  • -E
    • コマンドラインオプション
  • -e <tarfile> [<output_dir>]
    • tarfile コマンドラインオプション
  • -e <zipfile> <output_dir>
    • zipfile コマンドラインオプション
  • -e, --exact
    • tokenize コマンドラインオプション
  • -f
    • compileall コマンドラインオプション
  • -f, --failfast
    • unittest コマンドラインオプション
  • -f, --file=<file>
    • trace コマンドラインオプション
  • -g, --timing
    • trace コマンドラインオプション
  • -h
    • コマンドラインオプション
  • -h, --help
    • json.tool コマンドラインオプション
    • timeit コマンドラインオプション
    • tokenize コマンドラインオプション
    • zipapp コマンドラインオプション
  • -I
    • コマンドラインオプション
  • -i
    • コマンドラインオプション
  • -i list
    • compileall コマンドラインオプション
  • -J
    • コマンドラインオプション
  • -j N
    • compileall コマンドラインオプション
  • -k
    • unittest コマンドラインオプション
  • -l
    • compileall コマンドラインオプション
  • -l <tarfile>
    • tarfile コマンドラインオプション
  • -l <zipfile>
    • zipfile コマンドラインオプション
  • -l, --indentlevel=<num>
    • pickletools コマンドラインオプション
  • -l, --listfuncs
    • trace コマンドラインオプション
  • -m <mainfn>, --main=<mainfn>
    • zipapp コマンドラインオプション
  • -m <module-name>
    • コマンドラインオプション
  • -m, --memo
    • pickletools コマンドラインオプション
  • -m, --missing
    • trace コマンドラインオプション
  • -n N, --number=N
    • timeit コマンドラインオプション
  • -O
    • コマンドラインオプション
  • -o <output>, --output=<output>
    • zipapp コマンドラインオプション
  • -o, --output=<file>
    • pickletools コマンドラインオプション
  • -OO
    • コマンドラインオプション
  • -p <interpreter>, --python=<interpreter>
    • zipapp コマンドラインオプション
  • -p, --pattern pattern
    • unittest-discover コマンドラインオプション
  • -p, --preamble=<preamble>
    • pickletools コマンドラインオプション
  • -p, --process
    • timeit コマンドラインオプション
  • -q
    • compileall コマンドラインオプション
    • コマンドラインオプション
  • -R
    • コマンドラインオプション
  • -r
    • compileall コマンドラインオプション
  • -r N, --repeat=N
    • timeit コマンドラインオプション
  • -R, --no-report
    • trace コマンドラインオプション
  • -r, --report
    • trace コマンドラインオプション
  • -S
    • コマンドラインオプション
  • -s
    • コマンドラインオプション
  • -s S, --setup=S
    • timeit コマンドラインオプション
  • -s, --start-directory directory
    • unittest-discover コマンドラインオプション
  • -s, --summary
    • trace コマンドラインオプション
  • -t <tarfile>
    • tarfile コマンドラインオプション
  • -t <zipfile>
    • zipfile コマンドラインオプション
  • -t, --top-level-directory directory
    • unittest-discover コマンドラインオプション
  • -t, --trace
    • trace コマンドラインオプション
  • -T, --trackcalls
    • trace コマンドラインオプション
  • -u
    • コマンドラインオプション
  • -u, --unit=U
    • timeit コマンドラインオプション
  • -V
    • コマンドラインオプション
  • -v
    • コマンドラインオプション
  • -v, --verbose
    • tarfile コマンドラインオプション
    • timeit コマンドラインオプション
    • unittest-discover コマンドラインオプション
  • -W arg
    • コマンドラインオプション
  • -X
    • コマンドラインオプション
  • -x
    • コマンドラインオプション
  • -x regex
    • compileall コマンドラインオプション
  • . (dot)
    • attribute reference
    • in Tkinter
    • in glob-style wildcards
    • in numeric literal
    • in pathnames, [1]
    • in printf-style formatting, [1]
    • in regular expressions
    • in string formatting
  • ..
    • in pathnames
  • ...
    • ellipsis literal, [1], [2]
    • in doctests
    • interpreter prompt, [1]
    • placeholder, [1], [2]
  • .ini
    • file
  • .pdbrc
    • file
  • .pypirc file
  • / (slash)
    • in pathnames, [1]
    • 演算子, [1]
  • //
    • 演算子, [1]
  • //=
    • augmented assignment
  • /=
    • augmented assignment
  • 0b
    • integer literal
  • 0o
    • integer literal
  • 0x
    • integer literal
  • 2to3
  • : (colon)
    • annotated variable
    • compound statement, [1], [2], [3], [4], [5], [6]
    • function annotations, [1]
    • in SQL statements
    • in dictionary expressions
    • in formatted string literal
    • in string formatting
    • lambda expression
    • path separator (POSIX)
    • slicing
  • ; (semicolon), [1]
  • < (less)
    • in string formatting
    • in struct format strings
    • 演算子, [1]
  • <<
    • 演算子, [1]
  • <<=
    • augmented assignment
  • <=
    • 演算子, [1]
  • <BLANKLINE>
  • = (equals)
    • assignment statement
    • class definition
    • function definition
    • in function calls
    • in string formatting
    • in struct format strings
  • ==
    • 演算子, [1]
  • > (greater)
    • in string formatting
    • in struct format strings
    • 演算子, [1]
  • >=
    • 演算子, [1]
  • >>
    • 演算子, [1]
  • >>=
    • augmented assignment
  • >>>
    • interpreter prompt, [1]
  • ? (question mark)
    • in AST grammar
    • in SQL statements
    • in a command interpreter
    • in argparse module
    • in glob-style wildcards, [1]
    • in regular expressions
    • in struct format strings, [1]
    • replacement character
  • ??
    • in regular expressions
  • @ (at)
    • class definition
    • function definition
    • in struct format strings
    • 演算子
  • [] (square brackets)
    • in assignment target list
    • in glob-style wildcards, [1]
    • in regular expressions
    • in string formatting
    • list expression
    • subscription
  • \ (backslash)
    • escape sequence, [1]
    • in pathnames (Windows)
    • in regular expressions, [1], [2]
  • \\
    • escape sequence
    • in regular expressions
  • \A
    • in regular expressions
  • \a
    • escape sequence
    • in regular expressions
  • \B
    • in regular expressions
  • \b
    • escape sequence
    • in regular expressions, [1]
  • \D
    • in regular expressions
  • \d
    • in regular expressions
  • \f
    • escape sequence
    • in regular expressions
  • \g
    • in regular expressions
  • \N
    • escape sequence, [1]
    • in regular expressions
  • \n
    • escape sequence
    • in regular expressions
  • \r
    • escape sequence
    • in regular expressions
  • \S
    • in regular expressions
  • \s
    • in regular expressions
  • \t
    • escape sequence
    • in regular expressions
  • \U
    • escape sequence, [1]
    • in regular expressions
  • \u
    • escape sequence, [1]
    • in regular expressions
  • \v
    • escape sequence
    • in regular expressions
  • \W
    • in regular expressions
  • \w
    • in regular expressions
  • \x
    • escape sequence, [1]
    • in regular expressions
  • \Z
    • in regular expressions
  • ^ (caret)
    • in curses module
    • in regular expressions, [1]
    • in string formatting
    • marker, [1]
    • 演算子, [1]
  • ^=
    • augmented assignment
  • {} (curly brackets)
    • dictionary expression
    • in formatted string literal
    • in regular expressions
    • in string formatting
    • set expression
  • | (vertical bar)
    • in regular expressions
    • 演算子, [1]
  • |=
    • augmented assignment
  • ~ (tilde)
    • home directory expansion
    • 演算子, [1]

ナビゲーション

  • 索引
  • モジュール |


3.7.2 Documentation

  • モジュール |
  • Python »
  • 3.7.2 Documentation »

Python 3.7.2 ドキュメント

ようこそ! Python 3.7.2 ドキュメントへ。

ドキュメント一覧

What's new in Python 3.7?
あるいは2.0からのすべての "What's new" ドキュメント

チュートリアル
ここから始めましょう

ライブラリーリファレンス
枕の下に置きましょう

言語リファレンス
構文と言語要素の解説

Python のセットアップと利用
各プラットフォームでの Python の使い方

Python HOWTO
特定のトピックに関する、より深いドキュメント

Python モジュールのインストール
Python Package Index などからのインストール

Python モジュールの配布
他人がインストールできるようにモジュールを配布する

拡張と埋め込み
C/C++ プログラマ向けチュートリアル

Python/C API
C/C++ プログラマ向けリファレンス

FAQ
よくある質問（解答つき！）

索引と表一覧:

モジュール総索引
全モジュール早見表

総合索引
関数、クラスおよび用語総覧

用語集
重要な用語の説明

検索
ドキュメントを検索

総合目次
章／節一覧

メタ情報

バグを報告する

このドキュメントについて

Python の歴史とライセンス

著作権

ナビゲーション

  • 索引
  • モジュール |


9. コマンドリファレンス

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python モジュールの配布 (レガシーバージョン) »

9. コマンドリファレンス

9.1. モジュールをインストールする: install コマンド群

install コマンドは最初にビルドコマンドを実行しておいてから、サブコマンド install_lib を実行します。 install_data and install_scripts.

9.1.1. install_data

このコマンドは配布物中に提供されている全てのデータファイルをインストールします。

9.1.2. install_scripts

このコマンドは配布物中の全ての (Python) スクリプトをインストールします。

9.2. ソース配布物を生成する: sdist コマンド

マニフェストテンプレートコマンド一覧:

コマンド | 説明
include pat1 pat2 ... | リストされたパターンのどれかにマッチする全てのファイルを含める
exclude pat1 pat2 ... | リストされたパターンのどれかにマッチする全てのファイルを除外する
recursive-include dir pat1 pat2 ... | dir 配下の、リストされたパターンのどれかにマッチする全てのファイルを含める
recursive-exclude dir pat1 pat2 ... | dir 配下の、リストされたパターンのどれかにマッチする全てのファイルを除外する
global-include pat1 pat2 ... | ソースツリー内にある、リストされたパターンのどれかにマッチする全てのファイルを含める
global-exclude pat1 pat2 ... | ソースツリー内にある、リストされたパターンのどれかにマッチする全てのファイルを除外する
prune dir | dir 配下の全てのファイルを除外する
graft dir | dir 配下の全てのファイルを含める

ここで使うパターンは、 Unix スタイルの "glob" パターンです。 * は通常のファイル名文字の任意のシーケンスにマッチします。 ? は通常のファイル名文字の1文字にマッチします。 [range] は range に含まれる全ての文字にマッチします (例: a-z, a-zA-Z, a-f0-9_.) 通常のファイル名文字は、プラットフォーム依存になります。 Unix ではスラッシュ以外の全ての文字で、 Windows ではコロンとバックスラッシュ以外の全ての文字です。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python モジュールの配布 (レガシーバージョン) »


3. setup 設定ファイル (setup configuration file) を書く

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python モジュールの配布 (レガシーバージョン) »

3. setup 設定ファイル (setup configuration file) を書く

時に、配布物をビルドする際に必要な全ての設定を あらかじめ 書ききれない状況が起きます: 例えば、ビルドを進めるために、ユーザに関する情報や、ユーザのシステムに関する情報を必要とするかもしれません。こうした情報が単純 --- C ヘッダファイルやライブラリを検索するディレクトリのリストのように --- であるかぎり、ユーザに設定ファイル (configuration file) setup.cfg を提供して編集してもらうのが、安上がりで簡単な特定方法になります。設定ファイルはまた、あらゆるコマンドにおけるオプションにデフォルト値を与えておき、インストール作業者がコマンドライン上や設定ファイルの編集でデフォルト設定を上書きできるようにします。

The setup configuration file is a useful middle-ground between the setup script---which, ideally, would be opaque to installers [1]---and the command-line to the setup script, which is outside of your control and entirely up to the installer. In fact, setup.cfg (and any other Distutils configuration files present on the target system) are processed after the contents of the setup script, but before the command-line. This has several useful consequences:

  • インストール作業者は、作者が setup.py に設定した項目のいくつかを setup.cfg を変更して上書きできます
  • setup.py では簡単に設定できないような、標準でないオプションのデフォルト値を設定できます
  • インストール作業者は、 setup.cfg に書かれたどんな設定も setup.py のコマンドラインオプションで上書きできます

The basic syntax of the configuration file is simple:

[command]
option=value
...

ここで、 command は Distutils コマンドのうちの一つ (例えば build_py, install) で、 option はそのコマンドでサポートされているオプションのうちの一つです。各コマンドには任意の数のオプションを設定でき、一つの設定ファイル中には任意の数のコマンドセクションを収められます。空白行は無視されます、 '#' 文字で開始して行末まで続くコメントも同様に無視されます。長いオプション設定値は、継続行をインデントするだけで複数行にわたって記述できます。

You can find out the list of options supported by a particular command with the universal --help option, e.g.

$ python setup.py --help build_ext
[...]
Options for 'build_ext' command:
  --build-lib (-b)     directory for compiled extension modules
  --build-temp (-t)    directory for temporary files (build by-products)
  --inplace (-i)       ignore build-lib and put compiled extensions into the
                       source directory alongside your pure Python modules
  --include-dirs (-I)  list of directories to search for header files
  --define (-D)        C preprocessor macros to define
  --undef (-U)         C preprocessor macros to undefine
  --swig-opts          list of SWIG command line options
[...]

Note that an option spelled --foo-bar on the command-line is spelled foo_bar in configuration files.

For example, say you want your extensions to be built "in-place"---that is, you have an extension pkg.ext, and you want the compiled extension file (ext.so on Unix, say) to be put in the same source directory as your pure Python modules pkg.mod1 and pkg.mod2. You can always use the --inplace option on the command-line to ensure this:

python setup.py build_ext --inplace

But this requires that you always specify the build_ext command explicitly, and remember to provide --inplace. An easier way is to "set and forget" this option, by encoding it in setup.cfg, the configuration file for this distribution:

[build_ext]
inplace=1

この設定は、明示的に build_ext を指定するかどうかに関わらず、モジュール配布物の全てのビルドに影響します。ソース配布物に setup.cfg を含めると、エンドユーザの手で行われるビルドにも影響します --- このオプションの例に関しては setup.cfg を含めるのはおそらくよくないアイデアでしょう。というのは、拡張モジュールをインプレースでビルドすると常にインストールしたモジュール配布物を壊してしまうからです。とはいえ、ある特定の状況では、モジュールをインストールディレクトリの下に正しく構築できるので、機能としては有用だと考えられます。 (ただ、インストールディレクトリ上でのビルドを想定するような拡張モジュールの配布は、ほとんどの場合よくない考え方です。)

Another example: certain commands take a lot of options that don't change from run to run; for example, bdist_rpm needs to know everything required to generate a "spec" file for creating an RPM distribution. Some of this information comes from the setup script, and some is automatically generated by the Distutils (such as the list of files installed). But some of it has to be supplied as options to bdist_rpm, which would be very tedious to do on the command-line for every run. Hence, here is a snippet from the Distutils' own setup.cfg:

[bdist_rpm]
release = 1
packager = Greg Ward <gward@python.net>
doc_files = CHANGES.txt
            README.txt
            USAGE.txt
            doc/
            examples/

doc_files オプションは、単に空白で区切られた文字列で、ここでは可読性のために複数行をまたぐようにしています。

参考

"Python モジュールのインストール" の 設定ファイルの構文
設定ファイルに関する詳細情報は、システム管理者向けのこのマニュアルにあります。

脚注

[1] Distutils が自動設定機能 (auto-configuration) をサポートするまで、おそらくこの理想状態を達成することはないでしょう。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python モジュールの配布 (レガシーバージョン) »


7. 使用例

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python モジュールの配布 (レガシーバージョン) »

7. 使用例

この章は distutils を使い始めるのに役立つ幾つかの基本的な例を提供します。distutils を使うための追加の情報は Distutils Cookbook で見つけることができます。

参考

Distutils Cookbook
distutils をもっと制御するためのレシピ集。

7.1. pure Python 配布物 (モジュール形式)

単に二つのモジュール、特定のパッケージに属しないモジュールを配布するだけなら、setup スクリプト中で py_modules オプションを使って個別に指定できます。

もっとも単純なケースでは、二つのファイル: setup スクリプト自体と、配布したい単一のモジュール、この例では foo.py について考えなければなりません:

<root>/
        setup.py
        foo.py

(この節の全ての図において、<root> は配布物ルートディレクトリを参照します。) この状況を扱うための最小の setup スクリプトは以下のようになります:

from distutils.core import setup
setup(name='foo',
      version='1.0',
      py_modules=['foo'],
      )

配布物の名前は name オプションで個々に指定し、配布されるモジュールの一つと配布物を同じ名前にする必要はないことに注意してください (とはいえ、この命名方法はよいならわしでしょう)。ただし、配布物名はファイル名を作成するときに使われるので、文字、数字、アンダースコア、ハイフンだけで構成しなければなりません。

py_modules はリストなので、もちろん複数のモジュールを指定できます。例えば、モジュール foo と bar を配布しようとしているのなら、 setup スクリプトは以下のようになります:

<root>/
        setup.py
        foo.py
        bar.py

また、セットアップスクリプトは以下のようになります

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      py_modules=['foo', 'bar'],
      )

モジュールのソースファイルは他のディレクトリに置けますが、そうしなければならないようなモジュールを沢山持っているのなら、モジュールを個別に列挙するよりもパッケージを指定した方が簡単でしょう。

7.2. pure Python 配布物 (パッケージ形式)

二つ以上のモジュールを配布する場合、とりわけ二つのパッケージに分かれている場合、おそらく個々のモジュールよりもパッケージ全体を指定する方が簡単です。たとえモジュールがパッケージ内に入っていなくても状況は同じで、その場合はルートパッケージにモジュールが入っていると Distutils に教えることができ、他のパッケージと同様にうまく処理されます (ただし、 __init__.py があってはなりません)。

最後の例で挙げた setup スクリプトは

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      packages=[''],
      )

のようにも書けます (空文字はルートパッケージを意味します)

これら二つのファイルをサブディレクトリ下に移動しておいて、インストール先はルートパッケージのままにしておきたい、例えば:

<root>/
        setup.py
        src/      foo.py
                  bar.py

のような場合には、パッケージ名にはルートパッケージをそのまま指定しておきますが、ルートパッケージに置くソースファイルがどこにあるかを Distutils に教えなければなりません:

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      package_dir={'': 'src'},
      packages=[''],
      )

もっと典型的なケースでは、複数のモジュールを同じパッケージ (またはサブパッケージ) に入れて配布しようと思うでしょう。例えば、 foo と bar モジュールがパッケージ foobar に属する場合、ソースツリーをレイアウトする一案として、以下が考えられます

<root>/
        setup.py
        foobar/
                 __init__.py
                 foo.py
                 bar.py

実際、Distutils ではこれをデフォルトのレイアウトとして想定していて、setup スクリプトを書く際にも最小限の作業しか必要ありません:

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      packages=['foobar'],
      )

モジュールを入れるディレクトリをパッケージの名前にしたくない場合、ここでも package_dir オプションを使う必要があります。例えば、パッケージ foobar のモジュールが src に入っているとします:

<root>/
        setup.py
        src/
                 __init__.py
                 foo.py
                 bar.py

適切な setup スクリプトは、以下のようになるでしょう

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      package_dir={'foobar': 'src'},
      packages=['foobar'],
      )

また、メインパッケージ内のモジュールを配布物ルート下に置くことがあるかもしれません:

<root>/
        setup.py
        __init__.py
        foo.py
        bar.py

この場合、setup スクリプトは

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      package_dir={'foobar': ''},
      packages=['foobar'],
      )

のようになるでしょう。(空文字列も現在のディレクトリを表します。)

サブパッケージがある場合、 packages で明示的に列挙しなければなりませんが、 package_dir はサブパッケージへのパスを自動的に展開します。 (別の言い方をすれば、 Distutils はソースツリーを 走査せず 、どのディレクトリが Python パッケージに相当するのかを __init__.py files. を探して調べようとします。) このようにして、デフォルトのレイアウトはサブパッケージ形式に展開されます:

<root>/
        setup.py
        foobar/
                 __init__.py
                 foo.py
                 bar.py
                 subfoo/
                           __init__.py
                           blah.py

対応する setup スクリプトは以下のようになります

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      packages=['foobar', 'foobar.subfoo'],
      )

7.3. 単体の拡張モジュール

拡張モジュールは、ext_modules オプションを使って指定します。package_dir は、拡張モジュールのソースファイルをどこで探すかには影響しません; pure Python モジュールのソースのみに影響します。もっとも単純なケースでは、単一の C ソースファイルで書かれた単一の拡張モジュールは以下のようになります:

<root>/
        setup.py
        foo.c

foo 拡張モジュールがルートパッケージに属している場合は、 setup スクリプトは次のように書けます

from distutils.core import setup
from distutils.extension import Extension
setup(name='foobar',
      version='1.0',
      ext_modules=[Extension('foo', ['foo.c'])],
      )

同じソースツリーレイアウトで、この拡張モジュールを foopkg の下に置き、拡張モジュールの名前を変えるには

foopkg 拡張をルートパッケージ下に所属させたい場合、 setup スクリプトは以下のようにします:

from distutils.core import setup
from distutils.extension import Extension
setup(name='foobar',
      version='1.0',
      ext_modules=[Extension('foopkg.foo', ['foo.c'])],
      )

7.4. パッケージのチェック

check コマンドで、パッケージのメタデータが配布物をビルドするための最低限の条件を満たしているかの検証が行えます。

コマンドを実行するには、単純に setup.py スクリプトを使って呼び出してください。何かが不足していた場合は、 check で警告が表示されるでしょう。

簡単なスクリプトを例に取ってみましょう:

from distutils.core import setup

setup(name='foobar')

check コマンドを走らせると、いくつかの警告が表示されます:

$ python setup.py check
running check
warning: check: missing required meta-data: version, url
warning: check: missing meta-data: either (author and author_email) or
         (maintainer and maintainer_email) must be supplied

long_description フィールドで reStructuredText の構文を使用し、docutils がインストールされている場合は、check コマンドに restructuredtext オプションを使用して、その構文が正しいかどうかチェックできます。

例えば、 setup.py スクリプトを次のように変えたとします:

from distutils.core import setup

desc = """\
My description
==============

This is the description of the ``foobar`` package.
"""

setup(name='foobar', version='1', author='tarek',
    author_email='tarek@ziade.org',
    url='http://example.com', long_description=desc)

long description の壊れている箇所を、 docutils 構文解析器を使い check で検出できます:

$ python setup.py check --restructuredtext
running check
warning: check: Title underline too short. (line 2)
warning: check: Could not finish the parsing.

7.5. メタデータの読み込み

distutils.core.setup() 関数は、プロジェクトの setup.py スクリプトを通して、プロジェクトのメタデータフィールドの値を調べることのできるコマンドライン・インターフェイスを提供します:

$ python setup.py --name
distribute

この呼び出しは、 distutils.core.setup() 関数を実行して name メタデータを読み取っています。ソース配布物もしくはバイナリ配布物が Distutils で作られていたとしても、メタデータフィールドは PKG-INFO という静的なファイルに書かれます。Distutils ベースのプロジェクトが Python にインストールされるとき、 NAME-VERSION-pyX.X.egg-info 以下にある配布物のモジュールやパッケージと一緒に PKG-INFO がコピーされます。ここで NAME はプロジェクト名、 VERSION はメタデータで定義されたバージョン、 pyX.X は 2.7 や 3.2 のような Python のメジャーバージョンとマイナーバージョンです。

distutils.dist.DistributionMetadata クラスとその read_pkg_file() メソッドを使って、この静的ファイルを読むことができます:

>>> from distutils.dist import DistributionMetadata
>>> metadata = DistributionMetadata()
>>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
>>> metadata.name
'distribute'
>>> metadata.version
'0.6.8'
>>> metadata.description
'Easily download, build, install, upgrade, and uninstall Python packages'

このクラスは、値を読み取るメタデータのファイルパスを引数に取ってインスタンス化することもできることに注意してください:

>>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info'
>>> DistributionMetadata(pkg_info_path).name
'distribute'

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python モジュールの配布 (レガシーバージョン) »


8. Distutilsの拡張

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python モジュールの配布 (レガシーバージョン) »

8. Distutilsの拡張

Distutilsは様々な方法で拡張できます。ほとんどの拡張は新規のコマンドという形をとるか、既存のコマンドを置換します。例えば、新しいコマンドはプラットフォーム特有の新しいパッケージ形式をサポートするために書かれているかもしませんし、既存のコマンドを置換するものは既存コマンドでのパッケージ処理の詳細を変更するでしょう。

ほとんどのdistutilsの拡張は、既存コマンドの動作を修正したい setup.py スクリプト中で行われます。その多くは、パッケージ中にコピーすべきファイルとして、 .py ファイル以外のいくつかのファイル拡張子を単に追加するものです。

ほとんどのdistutilsのコマンド実装は distutils.cmd の distutils.cmd.Command クラスのサブクラスとして実装されています。新しいコマンドは Command を直接継承し、置換するコマンドでは置換対象のコマンドのサブクラスにすることで Command を間接的に継承します。コマンドは Command から派生したものである必要があります。

8.1. 新しいコマンドの統合

新しいコマンド実装をdistutilsに統合するにはいくつかの方法があります。一番難しい方法は新機能をdistutils本体に取り込むように働きかけ、そのサポートを提供するPythonのバージョンが出ることを待つ(そして要求する)ことです。これは様々な理由で本当に難しいことです。

もっとも一般的な、そしておそらくほとんどの場合にもっとも妥当な方法は、新しい実装をあなたの setup.py スクリプトに取り込み、 distutils.core.setup() 関数でそれらを使うようにすることです:

from distutils.command.build_py import build_py as _build_py
from distutils.core import setup

class build_py(_build_py):
    """Specialized Python source builder."""

    # implement whatever needs to be different...

setup(cmdclass={'build_py': build_py},
      ...)

このアプローチは、新実装をある特定のパッケージで利用したい時、そのパッケージに興味をもつ人全員がコマンドの新実装を必要とする時にもっとも価値があります。

Beginning with Python 2.4, a third option is available, intended to allow new commands to be added which can support existing setup.py scripts without requiring modifications to the Python installation. This is expected to allow third-party extensions to provide support for additional packaging systems, but the commands can be used for anything distutils commands can be used for. A new configuration option, command_packages (command-line option --command-packages), can be used to specify additional packages to be searched for modules implementing commands. Like all distutils options, this can be specified on the command line or in a configuration file. This option can only be set in the [global] section of a configuration file, or before any commands on the command line. If set in a configuration file, it can be overridden from the command line; setting it to an empty string on the command line causes the default to be used. This should never be set in a configuration file provided with a package.

この新オプションによってコマンド実装を探すためのパッケージをいくつでも追加することができます。複数のパッケージ名はコンマで区切って指定します。指定がなければ、検索は distutils.command パッケージのみで行われます。ただし setup.py がオプション --command-packages distcmds,buildcmds で実行されている場合には、パッケージは distutils.command 、 distcmds 、そして buildcmds を、この順番で検索します。新コマンドはコマンドと同じ名前のモジュールに、コマンドと同じ名前のクラスで実装されていると想定しています。上のコマドラインオプションの例では、コマンド bdist_openpkg は、 distcmds.bdist_openpkg.bdist_openpkg か、 buildcmds.bdist_openpkg.bdist_openpkg で実装されるかもしれません。

8.2. 配布物の種類を追加する

配布物 (dist/ ディレクトリの中のファイル) を作成するコマンドは、 upload がその配布物をPyPIにアップロードできるように、 (command, filename) のペアを self.distribution.dist_files に追加する必要があります。ペア中の filename はパスに関する情報を持たず、単にファイル名だけを持ちます。 dry-run モードでも、何が作成されたかを示すために、同じペアが必要になります。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python モジュールの配布 (レガシーバージョン) »


  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »

Python モジュールの配布 (レガシーバージョン)

Authors: | Greg Ward, Anthony Baxter
Email: | distutils-sig@python.org

参考

Python モジュールの配布
最新のモジュール配布ドキュメンテーション

このドキュメントでは、 Python 配布ユーティリティ (Python Distribution Utilities, "Distutils") について、 モジュール開発者の視点に立ち、多くの人々がビルド/リリース/インストール の手間をほとんどかけずに Python モジュールや拡張モジュールを入手できるようにする方法について述べます。

注釈

This guide only covers the basic tools for building and distributing extensions that are provided as part of this version of Python. Third party tools offer easier to use and more secure alternatives. Refer to the quick recommendations section in the Python Packaging User Guide for more information.

  • 1. Distutilsの紹介
    • 1.1. 概念と用語
    • 1.2. 簡単な例
    • 1.3. Python 一般の用語
    • 1.4. Distutils 固有の用語
  • 2. setup スクリプトを書く
    • 2.1. パッケージを全て列挙する
    • 2.2. 個々のモジュールを列挙する
    • 2.3. 拡張モジュールについて記述する
    • 2.4. パッケージと配布物の関係
    • 2.5. スクリプトをインストールする
    • 2.6. パッケージデータをインストールする
    • 2.7. 追加のファイルをインストールする
    • 2.8. 追加のメタデータ
    • 2.9. setup スクリプトをデバッグする
  • 3. setup 設定ファイル (setup configuration file) を書く
  • 4. ソースコード配布物を作成する
    • 4.1. 配布するファイルを指定する
    • 4.2. マニフェスト (manifest) 関連のオプション
  • 5. ビルド済み配布物を作成する
    • 5.1. RPM パッケージを作成する
    • 5.2. Windows インストーラを作成する
    • 5.3. Windows でのクロスコンパイル
    • 5.4. Vista のユーザアカウント制御 (UAC)
  • 6. Python Package Index (PyPI)
    • 6.1. PyPI の概要
    • 6.2. Distutils コマンド
    • 6.3. PyPI パッケージ表示
  • 7. 使用例
    • 7.1. pure Python 配布物 (モジュール形式)
    • 7.2. pure Python 配布物 (パッケージ形式)
    • 7.3. 単体の拡張モジュール
    • 7.4. パッケージのチェック
    • 7.5. メタデータの読み込み
  • 8. Distutilsの拡張
    • 8.1. 新しいコマンドの統合
    • 8.2. 配布物の種類を追加する
  • 9. コマンドリファレンス
    • 9.1. モジュールをインストールする: install コマンド群
    • 9.2. ソース配布物を生成する: sdist コマンド
  • 10. API リファレンス
    • 10.1. distutils.core --- Distutils のコア機能
    • 10.2. distutils.ccompiler --- CCompiler ベースクラス
    • 10.3. distutils.unixccompiler --- Unix C コンパイラ
    • 10.4. distutils.msvccompiler --- Microsoft コンパイラ
    • 10.5. distutils.bcppcompiler --- Borland コンパイラ
    • 10.6. distutils.cygwincompiler --- Cygwin コンパイラ
    • 10.7. distutils.archive_util --- アーカイブユーティリティ
    • 10.8. distutils.dep_util --- 依存関係のチェック
    • 10.9. distutils.dir_util --- ディレクトリツリーの操作
    • 10.10. distutils.file_util --- 1ファイルの操作
    • 10.11. distutils.util --- その他のユーティリティ関数
    • 10.12. distutils.dist --- Distribution クラス
    • 10.13. distutils.extension --- Extension クラス
    • 10.14. distutils.debug --- Distutils デバッグモード
    • 10.15. distutils.errors --- Distutils 例外
    • 10.16. distutils.fancy_getopt --- 標準 getopt モジュールのラッパ
    • 10.17. distutils.filelist --- FileList クラス
    • 10.18. distutils.log --- シンプルな PEP 282 スタイルのロギング
    • 10.19. distutils.spawn --- サブプロセスの生成
    • 10.20. distutils.sysconfig --- システム設定情報
    • 10.21. distutils.text_file --- TextFile クラス
    • 10.22. distutils.version --- バージョン番号クラス
    • 10.23. distutils.cmd --- Distutils コマンドの抽象クラス
    • 10.24. 新しいDistutilsコマンドの作成
    • 10.25. distutils.command --- Distutils 各コマンド
    • 10.26. distutils.command.bdist --- バイナリインストーラの構築
    • 10.27. distutils.command.bdist_packager --- パッケージの抽象ベースクラス
    • 10.28. distutils.command.bdist_dumb --- "ダム"インストーラを構築
    • 10.29. distutils.command.bdist_msi --- Microsoft Installer バイナリパッケージをビルドする
    • 10.30. distutils.command.bdist_rpm --- Redhat RPMとSRPM形式のバイナリディストリビューションを構築
    • 10.31. distutils.command.bdist_wininst --- Windowsインストーラの構築
    • 10.32. distutils.command.sdist --- ソース配布物の構築
    • 10.33. distutils.command.build --- パッケージ中の全ファイルを構築
    • 10.34. distutils.command.build_clib --- パッケージ中のCライブラリを構築
    • 10.35. distutils.command.build_ext --- パッケージ中の拡張を構築
    • 10.36. distutils.command.build_py --- パッケージ中の.py/.pyc ファイルを構築
    • 10.37. distutils.command.build_scripts --- パッケージ中のスクリプトを構築
    • 10.38. distutils.command.clean --- パッケージのビルドエリアを消去
    • 10.39. distutils.command.config --- パッケージの設定
    • 10.40. distutils.command.install --- パッケージのインストール
    • 10.41. distutils.command.install_data --- パッケージ中のデータファイルをインストール
    • 10.42. distutils.command.install_headers --- パッケージから C/C++ ヘッダファイルをインストール
    • 10.43. distutils.command.install_lib --- パッケージからライブラリファイルをインストール
    • 10.44. distutils.command.install_scripts --- パッケージからスクリプトファイルをインストール
    • 10.45. distutils.command.register --- モジュールをPython Package Indexに登録する
    • 10.46. distutils.command.check --- パッケージのメタデータをチェックする

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |


6. Python Package Index (PyPI)

  • モジュール |
  • 次へ |
  • 前へ |
  • Python »
  • 3.7.2 Documentation »
  • Python モジュールの配布 (レガシーバージョン) »

6. Python Package Index (PyPI)

Python Package Index (PyPI) はパッケージ作者が望む場合、配布ファイルのようなパッケージデータだけでなく、 distutils でパッケージされた配布物について記述した メタデータ も保存します。

Distutils には、メタデータの発行を行う register と、PyPI に配布物をアップロードする upload コマンドが用意されています。これらコマンドについての詳細は Distutils コマンド を参照してください。

6.1. PyPI の概要

配布物の様々なバージョンについて、好きなだけインデクスへの提出を行ってかまいません。特定のバージョンに関するメタデータを入れ替えたければ、再度提出を行えば、インデクス上のデータが更新されます。

PyPI は提出された配布物の (名前、バージョン) の各組み合わせについて記録を保持しています。ある配布物名について最初に情報を提出したユーザが、 その配布物名のオーナ (owner) になります。変更は register コマンドか、web インタフェースを介して提出できます。オーナは他のユーザをオーナやメンテナとして指名できます。 メンテナはパッケージ情報を編集できますが、他の人をオーナやメンテナに指名することはできません。

デフォルトでは PyPI はパッケージの最新バージョンしか表示しません。Web インターフェースからこのデフォルトの振る舞いを変更することができ、手動でどのバージョンを見せ、どのバージョンを見せないかを選べます。

それぞれのバージョンについて、 PyPI はホームページを表示します。ホームページは register コマンドで提出出来る long_description から作られます。詳細については PyPI パッケージ表示 をご覧ください。

6.2. Distutils コマンド

distutils には PyPI にパッケージのデータを送信するための 2 つのコマンドがあります: PyPI にメタデータを送信するための register と配布物ファイルを送信するための upload です。どちらのコマンドも、 .pypirc ファイル という特別なファイルから設定データを読みます。

6.2.1. register コマンド

Distutils の register コマンドは、配布物のメタデータをインデックスサーバーに送信するために使います。次のように実行します:

python setup.py register

Distutils は以下のようなプロンプトを出します:

running register
We need to know who you are, so please choose either:
    1. use your existing login,
    2. register as a new user,
    3. have the server generate a new password for you (and email it to you), or
    4. quit
Your selection [default 1]:

注意: ユーザ名とパスワードをローカルに保存している場合、このメニューは表示されません。認証情報を .pypirc ファイルに保存する方法については .pypirc ファイル を参照してください。

まだ PyPI に登録したことがなければ、まず登録する必要があります。この場合選択肢 2 番を選び、リクエストされた詳細情報を入力してゆきます。詳細情報を提出し終えると、登録情報の承認を行うためのメールを受け取るはずです。

すでに登録を行ったことがあれば、選択肢 1 を選べます。この選択肢を選ぶと、PyPI ユーザ名とパスワードを入力するよう促され、 register がメタデータをインデクスに自動的に提出します。

register コマンドのオプションについては 追加のコマンドオプション を参照してください。

6.2.2. upload コマンド

Distutils のコマンド upload は、配布物ファイルを PyPI へ送ります。

このコマンドは一つ以上の配布物ファイルをビルドした直後に呼び出されます。例えば、次のコマンド

python setup.py sdist bdist_wininst upload

は、ソース配布物とWindowsのインストーラをPyPIにアップロードします。以前に setup.py を実行してビルドした配布物もアップロード対象になるけれども、アップロードされるのは upload コマンドと同時に指定された配布物だけだということに注意してください。

同じコマンド内で register コマンドが呼ばれていて、そこでプロンプトからパスワードを入力した場合、 upload は入力されたパスワードを再利用します。 $HOME/.pypirc ファイルにプレインテキストでパスワードを保存したくない場合はこの方法を利用できます。

You can use the --sign option to tell upload to sign each uploaded file using GPG (GNU Privacy Guard). The gpg program must be available for execution on the system PATH. You can also specify which key to use for signing using the --identity=name option.

upload コマンドの追加のオプションについては 追加のコマンドオプション を参照してください。

6.2.3. 追加のコマンドオプション

このセクションで説明するオプションは register, upload の両コマンドに共通です。

--repository または -r オプションで、デフォルトとは異なる PyPI サーバを指定出来ます。例えば:

python setup.py sdist bdist_wininst upload -r https://example.com/pypi

簡単のために、 .pypirc ファイルでそのように設定してあれば、URL の場所に名前を使えます。例えば:

python setup.py register -r other

代替サーバーを定義することについて、より詳しい情報は .pypirc ファイル を参照してください。

--show-response オプションを指定することで、 PyPI サーバからの全ての応答をテキストで表示します。これは登録時・アップロード時に何か問題があった場合のデバッグに有用です。

6.2.4. .pypirc ファイル

The register and upload commands both check for the existence of a .pypirc file at the location $HOME/.pypirc. If this file exists, the command uses the username, password, and repository URL configured in the file. The format of a .pypirc file is as follows:

[distutils]
index-servers =
    pypi

[pypi]
repository: <repository-url>
username: <username>
password: <password>

distutils セクションは、 index-servers でリポジトリを設定する全てのセクション名の リストを定義しています。

リポジトリを表す各セクションは3つの変数を定義します:

  • repository は PyPI サーバの URL を定義します。
    デフォルトは https://upload.pypi.org/legacy/ です。
  • username は PyPI サーバーに登録されたユーザー名です。
  • password は認証に使われます。
    省略された場合、必要なときに入力を求められます。

If you want to define another server a new section can be created and listed in the index-servers variable:

[distutils]
index-servers =
    pypi
    other

[pypi]
repository: <repository-url>
username: <username>
password: <password>

[other]
repository: https://example.com/pypi
username: <username>
password: <password>

これらセクションは register, upload コマンドで、 追加のコマンドオプション で説明した --repository オプションとともに使うことが出来ます。

特に、 PyPI そのものに最初にアップロードする前にテストするのを容易にすべく、あなたの .pypirc には PyPI Test Repository を追加したいでしょう。

6.3. PyPI パッケージ表示

long_description フィールドは PyPI において特別な役目を持ちます。サーバーは登録されたパッケージのホームページを表示するためにこれを利用します。

このフィールドに reStructuredText 記法を利用した場合、PyPI はこれをパースして、パッケージのホームページにHTML 出力を表示します。

long_description フィールドにパッケージ内のファイルの内容を利用することもできます:

from distutils.core import setup

with open('README.txt') as file:
    long_description = file.read()

setup(name='Distutils',
      long_description=long_description)

この例では、 README.txt は通常の reStructuredText テキストファイルで、 setup.py と同じパッケージのルートディレクトリに置かれています。

壊れた reStructuredText を登録してしまうのを防ぐために、コマンドラインから docutils パッケージが提供している rst2html プログラムを利用して long_description をチェックすることができます:

$ python setup.py --long-description | rst2html.py > output.html

docutils は文法に何か問題があると警告を表示します。 PyPI は他にもチェックを行うので (例えば rst2html.py に --no-raw を指定します)、上のコマンドを警告なしに実行できたとしても PyPI での変換が成功することを保証するわけではありません。

ナビゲーション

  • 索引
  • モジュール |
  • 次へ |
  • 前へ |
  • Python モジュールの配布 (レガシーバージョン) »


  • モジュール |
  • Python »
  • 3.7.2 Documentation »

パッケージを Package Index にアップロードする

このページの内容は Python Package Index (PyPI) に移動しました。

ナビゲーション

  • 索引
  • モジュール |