前のトピックへ

27. Python ランタイムサービス

次のトピックへ

27.2. __builtin__ — 組み込みオブジェクト

このページ

27.1. sys — システムパラメータと関数

このモジュールでは、インタープリタで使用・管理している変数や、インタープリタの動作に深く関連する関数を定義しています。このモジュールは常に利用可能です。

sys.argv

Pythonスクリプトに渡されたコマンドライン引数のリスト。 argv[0] はスクリプトの名前となりますが、フルパス名かどうかは、OSによって異なります。コマンドライン引数に -c を付けて Pythonを起動した場合、 argv[0] は文字列 '-c' となります。スクリプト名なしでPythonを起動した場合、 argv[0] は空文字列になります。

標準入力もしくはコマンドライン引数で指定されたファイルのリストに対してループするには、 fileinput モジュールを参照してください。

sys.byteorder

プラットフォームのバイト順を示します。ビッグエンディアン (最上位バイトが先頭) のプラットフォームでは 'big', リトルエンディアン (最下位バイトが先頭) では 'little' となります。

バージョン 2.0 で追加.

sys.subversion

3つ組 (repo, branch, version) で Python インタプリタの Subversion 情報を表します。 repo はリポジトリの名前で、 'CPython'branch'trunk', 'branches/name' または 'tags/name' のいずれかの形式の文字列です。 version はもしインタプリタが Subversion のチェックアウトからビルドされたものならば svnversion の出力であり、リビジョン番号 (範囲) とローカルでの変更がある場合には最後に ‘M’ が付きます。ツリーがエクスポートされたもの (または svnversion が取得できない) で、 branch がタグならば Include/patchlevel.h のリビジョンになります。それ以外の場合には None です。

バージョン 2.5 で追加.

sys.builtin_module_names

コンパイル時にPythonインタープリタに組み込まれた、全てのモジュール名のタプル(この情報は、他の手段では取得することができません。 modules.keys() は、インポートされたモジュールのみのリストを返します。)

sys.copyright

Pythonインタープリタの著作権を表示する文字列。

sys._clear_type_cache()

内部の型キャッシュをクリアします。型キャッシュは属性とメソッドの検索を高速化するために利用されます。この関数は、参照リークをデバッグするときに不要な参照を削除するため だけ に利用してください。

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。

バージョン 2.6 で追加.

sys._current_frames()

各スレッドの識別子を関数が呼ばれた時点のそのスレッドでアクティブになっている一番上のスタックフレームに結びつける辞書を返します。モジュール traceback の関数を使えばそのように与えられたフレームのコールスタックを構築できます。

この関数はデッドロックをデバッグするのに非常に有効です。デッドロック状態のスレッドの協調動作を必要としませんし、そういったスレッドのコールスタックはデッドロックである限り凍り付いたままです。デッドロックにないスレッドのフレームについては、そのフレームを調べるコードを呼んだ時にはそのスレッドの現在の実行状況とは関係ないところを指し示しているかもしれません。

この関数は外部に見せない特別な目的でのみ使われるべきです。

バージョン 2.5 で追加.

sys.dllhandle

Python DLLのハンドルを示す整数。利用可能: Windows

sys.displayhook(value)

valueNone 以外の場合、 valuesys.stdout に出力して __builtin__._ に保存します。

sys.displayhook は、Pythonの対話セッションで入力された式(expression)が評価されたときに呼び出されます。対話セッションの出力をカスタマイズする場合、 sys.displayhook に引数の数が一つの関数を指定します。

sys.excepthook(type, value, traceback)

指定したトレースバックと例外を sys.stderr に出力します。

例外が発生し、その例外が捕捉されない場合、インタープリタは例外クラス・例外インスタンス・トレースバックオブジェクトを引数として sys.excepthook を呼び出します。対話セッション中に発生した場合はプロンプトに戻る直前に呼び出され、Pythonプログラムの実行中に発生した場合はプログラムの終了直前に呼び出されます。このトップレベルでの例外情報出力処理をカスタマイズする場合、 sys.excepthook に引数の数が三つの関数を指定します。

sys.__displayhook__
sys.__excepthook__

それぞれ、起動時の displayhookexcepthook の値を保存しています。この値は、 displayhookexcepthook に不正なオブジェクトが指定された場合に、元の値に復旧するために使用します。

sys.exc_info()

この関数は、現在処理中の例外を示す三つの値のタプルを返します。この値は、現在のスレッド・現在のスタックフレームのものです。現在のスタックフレームが例外処理中でない場合、例外処理中のスタックフレームが見つかるまで次々とその呼び出し元スタックフレームを調べます。ここで、”例外処理中” とは “except 節を実行中、または実行した” フレームを指します。どのスタックフレームでも、最後に処理した例外の情報のみを参照することができます。

スタック上で例外が発生していない場合、三つの None のタプルを返します。例外が発生している場合、 (type, value, traceback) を返します。 type は、処理中の例外の型を示します (クラスオブジェクト)。 value は、例外パラメータ (例外に 関連する値 または raise の第二引数。 type がクラスオブジェクトの場合は常にクラスインスタンス) です。 traceback は、トレースバックオブジェクトで、例外が発生した時点でのコールスタックをカプセル化したオブジェクトです(リファレンスマニュアル参照)。

exc_clear() が呼び出されると、現在のスレッドで他の例外が発生するか、又は別の例外を処理中のフレームに実行スタックが復帰するまで、 exc_info() は三つの None を返します。

警告

例外処理中に戻り値の traceback をローカル変数に代入すると循環参照が発生し、関数内のローカル変数やトレースバックが参照している全てのオブジェクトは解放されなくなります。特にトレースバック情報が必要ではなければ exctype, value = sys.exc_info()[:2] のように例外型と例外オブジェクトのみを取得するようにして下さい。もしトレースバックが必要な場合には、処理終了後にdeleteして下さい。このdeleteは、 try ... finally ...で行うと良いでしょう。

ノート

Python 2.2 以降では、ガベージコレクションが有効であればこのような到達不能オブジェクトは自動的に削除されます。しかし、循環参照を作らないようにしたほうが効率的です。

sys.exc_clear()

この関数は、現在のスレッドで処理中、又は最後に発生した例外の情報を全てクリアします。この関数を呼び出すと、現在のスレッドで他の例外が発生するか、又は別の例外を処理中のフレームに実行スタックが復帰するまで、 exc_info() は三つの None を返します。

この関数が必要となることは滅多にありません。ロギングやエラー処理などで最後に発生したエラーの報告を行う場合などに使用します。また、リソースを解放してオブジェクトの終了処理を起動するために使用することもできますが、オブジェクトが実際にされるかどうかは保障の限りではありません。

バージョン 2.3 で追加.

sys.exc_type
sys.exc_value
sys.exc_traceback

バージョン 1.5 で撤廃: exc_info() を使用してください

これらの変数はグローバル変数なのでスレッド毎の情報を示すことができません。この為、マルチスレッドなプログラムでは安全に参照することはできません。例外処理中でない場合、 exc_type の値は None となり、 exc_valueexc_traceback は未定義となります。

sys.exec_prefix

Python のプラットフォーム依存なファイルがインストールされているディレクトリ名(サイト固有)。デフォルトでは、この値は '/usr/local' ですが、ビルド時に configure--exec-prefix 引数で指定することができます。全ての設定ファイル(pyconfig.h など)は exec_prefix + '/lib/pythonversion/config' に、共有ライブラリは exec_prefix + '/lib/pythonversion/lib-dynload' にインストールされます (但し versionversion[:3])。

sys.executable

Python インタープリタの実行ファイルの名前を示す文字列。このような名前が意味を持つシステムでは利用可能。

sys.exit([arg])

Python を終了します。 exit()SystemExit を送出するので、 try ステートメントの finally 節に終了処理を記述したり、上位レベルで例外を捕捉して exit 処理を中断したりすることができます。オプション引数 arg には、終了ステータスとして整数(デフォルトは0)または整数以外の型のオブジェクトを指定することができます。整数を指定した場合、シェル等は 0 は”正常終了”、 0 以外の整数を”異常終了”として扱います。多くのシステムでは、有効な終了ステータスは 0-127 で、これ以外の値を返した場合の動作は未定義です。システムによっては特定の終了コードに個別の意味を持たせている場合がありますが、このような定義は僅かしかありません。 Unix プログラムでは文法エラーの場合には 2 を、それ以外のエラーならば 1 を返します。 argNone を指定した場合は、数値の 0 を指定した場合と同じです。それ以外のオブジェクトを指定すると、そのオブェクトが sys.stderr に出力され、終了コードとして 1 を返します。エラー発生時には sys.exit("エラーメッセージ") と書くと、簡単にプログラムを終了することができます。

sys.exitfunc

この値はモジュールに存在しませんが、ユーザプログラムでプログラム終了時に呼び出される終了処理関数として、引数の数が 0 の関数を設定することができます。この関数は、インタープリタ終了時に呼び出されます。 exitfunc に指定することができる終了処理関数は一つだけですので、複数のクリーンアップ処理が必要な場合は atexit モジュールを使用してください。

ノート

プログラムがシグナルで kill された場合、 Python 内部で致命的なエラーが発生した場合、 os._exit() が呼び出された場合には、終了処理関数は呼び出されません。

バージョン 2.4 で撤廃: atexit を使ってください。

sys.flags

属性とシーケンスを利用して、コマンドラインフラグの状態を提供しています。属性は読み込み専用になっています。

属性 フラグ
debug -d
py3k_warning -3
division_warning -Q
division_new -Qnew
inspect -i
interactive -i
optimize -O or -OO
dont_write_bytecode -B
no_user_site -s
no_site -S
ignore_environment -E
tabcheck -t or -tt
verbose -v
unicode -U
bytes_warning -b

バージョン 2.6 で追加.

sys.float_info

属性とシーケンスを利用して、 float 型に関する情報を提供します。精度と内部表現に関する情報を含みます。プログラミング言語 ‘C’ の標準ヘッダファイル float.h に定義された様々な浮動小数点定数に対応する値の詳細については、1999 ISO/IEC C standard [C99] の 4.2.4.2.2 章を参照して下さい。

属性 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 算術演算で利用される丸めモードを表す定数

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'

バージョン 2.6 で追加.

sys.getcheckinterval()

インタプリタの “チェックインターバル (check interval)” を返します; setcheckinterval() を参照してください。

バージョン 2.3 で追加.

sys.getdefaultencoding()

現在の Unicode 処理のデフォルトエンコーディング名を返します。

バージョン 2.0 で追加.

sys.getdlopenflags()

dlopen() で指定されるフラグを返します。このフラグは dlDLFCN で定義されています。

利用可能: Unix.

バージョン 2.2 で追加.

sys.getfilesystemencoding()

Unicode ファイル名をシステムのファイル名に変換する際に使用するエンコード名を返します。システムのデフォルトエンコーディングを使用する場合には None を返します。

  • Mac OS X では、エンコーディングは utf-8 となります。
  • Unix では、エンコーディングは nl_langinfo(CODESET) が返すユーザの設定となります。 nl_langinfo(CODESET) が失敗すると None を返します。
  • Windows NT+ では、 Unicode をファイル名として使用できるので変換の必要はありません。 getfilesystemencoding()'mbcs' を返しますが、これはある Unicode 文字列をバイト文字列に明示的に変換して、ファイル名として使うと同じファイルを指すようにしたい場合に、アプリケーションが使わねばならないエンコーディングです。
  • Windows 9x では、エンコーディングは “mbcs” となります。

バージョン 2.3 で追加.

sys.getrefcount(object)

object の参照数を返します。 object は(一時的に) getrefcount() からも参照されるため、参照数は予想される数よりも 1 多くなります。

sys.getrecursionlimit()

現在の最大再帰数を返します。最大再帰数は、Python インタープリタスタックの最大の深さです。この制限は Python プログラムが無限に再帰し、C スタックがオーバーフローしてクラッシュすることを防止するために設けられています。この値は setrecursionlimit() で指定することができます。

sys.getsizeof(object[, default])

object のサイズをバイト数で返します。 object は任意の型のオブジェクトです。全てのビルトイン型は正しい値を返します。サードパーティー製の型については実装依存になります。

default 引数が与えられると、オブジェクト型がサイズを取得する手段を提供していない場合に返されます。与えられてない場合には TypeError 例外が発生します。

getsizeof()object__sizeof__ メソッドを呼び出し、そのオブジェクトがガベージコレクタに管理されていた場合はガベージコレクタのオーバーヘッドを増やします。

バージョン 2.6 で追加.

sys._getframe([depth])

コールスタックからフレームオブジェクトを取得します。オプション引数 depth を指定すると、スタックのトップから depth だけ下のフレームオブジェクトを取得します。 depth がコールスタックよりも深ければ、 ValueError が発生します。 depth のデフォルト値は 0 で、この場合はコールスタックのトップのフレームを返します。

CPython implementation detail: この関数は、内部的な、特殊な用途にのみ利用することができます。この関数の存在は全ての Python 実装で保証されるものではありません。

sys.getprofile()

setprofile() 関数などで設定した profiler 関数を取得します。

バージョン 2.6 で追加.

sys.gettrace()

settrace() 関数などで設定した trace 関数を取得します。

CPython implementation detail:

gettrace() 関数は、デバッガ、プロファイラ、カバレッジツールなどの実装に使うことのみを想定しています。この関数の振る舞いは言語定義ではなく実装プラットフォームの一部です。そのため、他の Python 実装では利用できないかもしれません。

バージョン 2.6 で追加.

sys.getwindowsversion()

実行中の Windows のバージョンを示す、以下の値のタプルを返します: major, minor, build, platform, texttext は文字列、それ以外の値は整数です。

platform は、以下の値となります:

Constant Platform
0 (VER_PLATFORM_WIN32s) Win32s on Windows 3.1
1 (VER_PLATFORM_WIN32_WINDOWS) Windows 95/98/ME
2 (VER_PLATFORM_WIN32_NT) Windows NT/2000/XP/x64
3 (VER_PLATFORM_WIN32_CE) Windows CE

この関数は、Win32 GetVersionEx() 関数を呼び出します。詳細はマイクロソフトのドキュメントを参照してください。

利用可能: Windows.

バージョン 2.3 で追加.

sys.hexversion

整数にエンコードされたバージョン番号。この値は新バージョン(正規リリース以外であっても)ごとにかならず増加します。例えば、Python 1.5.2 以降でのみ動作するプログラムでは、以下のようなチェックを行います。

if sys.hexversion >= 0x010502F0:
    # use some advanced feature
    ...
else:
    # use an alternative implementation or warn the user
    ...

hexversionhex() で16進数に変換しなければ値の意味がわかりません。より読みやすいバージョン番号が必要な場合には version_info を使用してください。

バージョン 1.5.2 で追加.

sys.last_type
sys.last_value
sys.last_traceback

通常は定義されておらず、捕捉されない例外が発生してインタープリタがエラーメッセージとトレースバックを出力した場合にのみ設定されます。この値は、対話セッション中にエラーが発生したとき、デバッグモジュールをロード (例:import pdb; pdb.pm() など。詳細は pdb — Python デバッガ を参照)して発生したエラーを調査する場合に利用します。デバッガをロードすると、プログラムを再実行せずに情報を取得することができます。

変数の意味は、上の exc_info() の戻り値と同じです。対話セッションを実行するスレッドは常に1つだけなので、 exc_type のようにスレッドに関する問題は発生しません。

sys.maxint

Pythonの整数型でサポートされる、最大の整数。この値は最低でも 2**31-1 です。最大の負数は -maxint-1 となります。正負の最大数が非対称ですが、これは 2 の補数計算を行うためです。

sys.maxsize

プラットフォームの Py_ssize_t 型がサポートしている最大の正の整数。したがって、リスト、文字列、辞書、その他コンテナ型の最大のサイズ。

sys.maxunicode

Unicode 文字の最大のコードポイントを示す整数。この値は、オプション設定で Unicode 文字の保存形式として USC-2 と UCS-4 のいずれを指定したかによって異なります。

sys.meta_path

finder オブジェクトのリストです。 finder オブジェクトの find_module() メソッドは、 import するモジュールを探すために呼び出されます。 import するモジュールがパッケージに含まれる場合、親パッケージの __path__ 属性が第 2 引数として渡されます。そのメソッドは、モジュールが見つからなかった場合は None を、見つかった場合は loader を返します。

sys.meta_path は、デフォルトの暗黙の finder や、 sys.path よりも先に検索されます。

オリジナルの仕様については、 PEP 302 を参照してください。

sys.modules

ロード済みモジュールのモジュール名とモジュールオブジェクトの辞書。強制的にモジュールを再読み込みする場合などに使用します。この辞書からモジュールを削除するのは、 reload() の呼び出しと等価では ありません

sys.path

モジュールを検索するパスを示す文字列のリスト。 PYTHONPATH 環境変数と、インストール時に指定したデフォルトパスで初期化されます。

開始時に初期化された後、リストの先頭(path[0])には Python インタープリタを起動するために指定したスクリプトのディレクトリが挿入されます。スクリプトのディレクトリがない(インタープリタで対話セッションで起動された時や、スクリプトを標準入力から読み込む場合など)場合、 path[0] には空文字列となり、Python はカレントディレクトリからモジュールの検索を開始します。スクリプトディレクトリは、 PYTHONPATH で指定したディレクトリの に挿入されますので注意が必要です。

必要に応じて、プログラム内で自由に変更することができます。

バージョン 2.3 で変更: Unicode 文字列が無視されなくなりました.

参考

site モジュールのドキュメントで、 .pth ファイルを使って sys.path を拡張する方法を解説しています。

sys.path_hooks

path を引数にとって、その path に対する finder の作成を試みる呼び出し可能オブジェクトのリスト。 finder の作成に成功したら、その呼出可能オブジェクトのは finder を返します。失敗した場合は、 ImportError を発生させます。

オリジナルの仕様は PEP 302 を参照してください。

sys.path_importer_cache

finder オブジェクトのキャッシュとなる辞書。キーは sys.path_hooks に渡される path で、値は見つかった finder オブジェクト。 path が有効なファイルシステムパスであり、かつ finder が sys.path_hooks から見つからない場合、暗黙のデフォルト finder を利用するという意味で None が格納されます。 path が既存のパスではない場合、 imp.NullImporter が格納されます。

オリジナルの仕様は PEP 302 を参照してください。

sys.platform

プラットフォームを識別する文字列で、 path にプラットフォーム別のサブディレクトリを追加する場合などに利用します。

Unix システムでは、この値は uname -s が返す小文字のOS名を前半に、 uname -r が返すバージョン名を後半に追加したものになります。例えば、 'sunos5''linux2' といった具合です。 この値はPythonをビルドした時のものです 。それ以外のシステムでは、次のような値になります。 :

システム platform の値
Windows 'win32'
Windows/Cygwin 'cygwin'
Mac OS X 'darwin'
OS/2 'os2'
OS/2 EMX 'os2emx'
RiscOS 'riscos'
AtheOS 'atheos'
sys.prefix

サイト固有の、プラットフォームに依存しないファイルを格納するディレクトリを示す文字列。デフォルトでは '/usr/local' になります。この値はビルド時に configure スクリプトの --prefix 引数で指定する事ができます。 Python ライブラリの主要部分は prefix + '/lib/pythonversion' にインストールされ、プラットフォーム非依存なヘッダファイル(pyconfig.h 以外)は prefix + '/include/pythonversion' に格納されます (但し versionversion[:3])。

sys.ps1
sys.ps2

インタープリタの一次プロンプト、二次プロンプトを指定する文字列。対話モードで実行中のみ定義され、初期値は '>>> ''... ' です。文字列以外のオブジェクトを指定した場合、インタープリタが対話コマンドを読み込むごとにオブジェクトの str() を評価します。この機能は、動的に変化するプロンプトを実装する場合に利用します。

sys.py3kwarning

Python 3.0 warning flag の状態を格納する Bool 値。 Python が -3 オプションを付けて起動された場合は True になります。 (この値は定数として扱ってください。この変数を変更しても、Python 3.0 warning の動作には影響しません)

バージョン 2.6 で追加.

sys.dont_write_bytecode

この値が true の時、 Python はソースモジュールを import するときに .pyc.pyo ファイルを生成しません。この値は -B コマンドラインオプションと PYTHONDONTWRITEBYTECODE 環境変数の値によって起動時に TrueFalse に設定されます。しかし、実行時にこの変数を変更して、バイトコード生成を制御することもできます。

バージョン 2.6 で追加.

sys.setcheckinterval(interval)

インタープリタの”チェック間隔”を示す整数値を指定します。この値はスレッドスイッチやシグナルハンドラのチェックを行う周期を決定します。デフォルト値は 100 で、この場合 100 の仮想命令を実行するとチェックを行います。この値を大きくすればスレッドを利用するプログラムのパフォーマンスが向上します。この値が 0 以下の場合、全ての仮想命令を実行するたびにチェックを行い、レスポンス速度と最大になりますがオーバヘッドもまた最大となります。

sys.setdefaultencoding(name)

現在の Unicode 処理のデフォルトエンコーディング名を設定します。 name に一致するエンコーディングが見つからない場合、 LookupError が発生します。この関数は、 site モジュールの実装が、 sitecustomize モジュールから使用するためだけに定義されています。 site から呼び出された後、この関数は sys から削除されます。

バージョン 2.0 で追加.

sys.setdlopenflags(n)

インタープリタが拡張モジュールをロードする時、 dlopen() で使用するフラグを設定します。 sys.setdlopenflags(0) とすれば、モジュールインポート時にシンボルの遅延解決を行う事ができます。シンボルを拡張モジュール間で共有する場合には、 sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL) と指定します。フラグの定義名は dlDLFCN で定義されています。 DLFCN が存在しない場合、 h2py スクリプトを使って /usr/include/dlfcn.h から生成することができます。

利用可能: Unix.

バージョン 2.2 で追加.

sys.setprofile(profilefunc)

システムのプロファイル関数を登録します。プロファイル関数は、 Python のソースコードプロファイルを行う関数で、 Python で記述することができます。詳細は Python プロファイラ を参照してください。プロファイル関数はトレース関数(settrace() 参照)と似ていますが、ソース行が実行されるごとに呼び出されるのではなく、関数の呼出しと復帰時のみ呼び出されます(例外が発生している場合でも、復帰時のイベントは発生します)。プロファイル関数はスレッド毎に設定することができますが、プロファイラはスレッド間のコンテキスト切り替えを検出することはできません。従って、マルチスレッド環境でのプロファイルはあまり意味がありません。 setprofile() は常に None を返します。

sys.setrecursionlimit(limit)

Python インタープリタの、スタックの最大の深さを limit に設定します。この制限は Python プログラムが無限に再帰し、 C スタックがオーバーフローしてクラッシュすることを防止するために設けられています。

limit の最大値はプラットフォームによって異なります。深い再帰処理が必要な場合にはプラットフォームがサポートしている範囲内でより大きな値を指定することができますが、この値が大きすぎればクラッシュするので注意が必要です。

sys.settrace(tracefunc)

システムのトレース関数を登録します。トレース関数は Python のソースデバッガを実装するために使用することができます。トレース関数はスレッド毎に設定することができるので、デバッグを行う全てのスレッドで settrace() を呼び出し、トレース関数を登録してください。

Trace関数は3つの引数: frame, event, arg を受け取る必要があります。 event は文字列です。 'call', 'line', 'return', 'exception', 'c_call', 'c_return', 'c_exception' のどれかが渡されます。 arg はイベントの種類によって異なります。

trace 関数は (event'call' を渡された状態で) 新しいローカルスコープに入るたびに呼ばれます。この場合、そのスコープで利用するローカルの trace 関数か、そのスコープを trace しないのであれば None を返します。

ローカル trace 関数は自身への参照 (もしくはそのスコープの以降の trace を行う別の関数) を返すべきです。もしくは、そのスコープの trace を止めるために None を返します。

event には以下の意味があります。

'call'
関数が呼び出された(もしくは、何かのコードブロックに入った)。グローバルの trace 関数が呼ばれる。 argNone が渡される。戻り値はローカルの trace 関数。
'line'
インタプリタが新しい行を実行しようとしている。 (1つの行に対して複数回の line イベントが発生する場合があります) 戻り値は新しいローカルの trace 関数。
'return'
関数(あるいは別のコードブロック)から戻ろうとしている。ローカルの trace 関数が呼ばれる。 arg は返り値。 trace 関数の戻り値は無視される。
'exception'
例外が発生した。ローカルの trace 関数が呼ばれる。 arg(exception, value, traceback) のタプル。戻り値は新しいローカルの trace 関数。
'c_call'
C 関数(拡張関数かビルトイン関数)が呼ばれようとしている。 arg は C 関数オブジェクト。
'c_return'
C 関数から戻った。 argNone
'c_exception'
C 関数が例外を発生させた。 argNone

例外が呼び出しチェインを辿って伝播していくことに注意してください。 'exception' イベントは各レベルで発生します。

code と frame オブジェクトについては、 標準型の階層 を参照してください。

CPython implementation detail: settrace() 関数は、デバッガ、プロファイラ、カバレッジツール等で使うためだけのものです。この関数の挙動は言語定義よりも実装プラットフォームの分野の問題で、全ての Python 実装で利用できるとは限りません。

sys.settscdump(on_flag)

on_flag が真の場合、Pentium タイムスタンプカウンタを使った VM 計測結果のダンプ出力を有効にします。 on_flag をオフにするとダンプ出力を無効化します。この関数は Python を --with-tsc つきでコンパイルしたときにのみ利用できます。ダンプの内容を理解したければ、 Python ソースコード中の Python/ceval.c を読んでください。

バージョン 2.4 で追加.

CPython implementation detail: この関数は CPython の実装の詳細に密接に結びついています、そのため他の Python 実装では実装されていないでしょう。

sys.stdin
sys.stdout
sys.stderr

インタープリタの標準入力・標準出力・標準エラー出力に対応するファイルオブジェクト。 stdin はスクリプトの読み込みを除く全ての入力処理で使用され、 input()raw_input()stdin から読み込みます。 stdout は、 print や式(expression)の評価結果、 input(), raw_input() のプロンプトの出力先となります。インタープリタのプロンプトは(ほとんど) stderr に出力されます。 stdoutstderr は必ずしも組み込みのファイルオブジェクトである必要はなく、 write() メソッドを持つオブジェクトであれば使用することができます。 stdoutstderr を別のオブジェクトに置き換えても、 os.popen(), os.system(), osexec*() などから起動されたプロセスが使用する標準 I/O ストリームは変更されません。

sys.__stdin__
sys.__stdout__
sys.__stderr__

それぞれ起動時の stdin, stderr, stdout の値を保存します。終了処理時に利用されます。また、 sys.std* オブジェクトが(訳注:別のファイルライクオブジェクトに)リダイレクトされている場合でも、本当の標準ストリームに表示する場合に利用できます。

また、標準ストリームを置き換えたオブジェクトが壊れた場合に、動作する本物のファイルをリストアするために利用することもできます。しかし、明示的に置き換え前のストリームを保存しておき、そのオブジェクトをリストアする事を推奨します。

sys.tracebacklimit

捕捉されない例外が発生した時、出力されるトレースバック情報の最大レベル数を指定する整数値(デフォルト値は 1000)。 0 以下の値が設定された場合、トレースバック情報は出力されず例外型と例外値のみが出力されます。

sys.version

Pythonインタープリタのバージョンとビルド番号・使用コンパイラなどの情報を示す文字列です。この文字列は Python 対話インタプリタが起動したときに表示されます。バージョン情報はここから抜き出さずに platform が提供する version_info を使って下さい。

sys.api_version

使用中のインタープリタの C API バージョン。 Python と拡張モジュール間の不整合をデバッグする場合などに利用できます。

バージョン 2.3 で追加.

sys.version_info

バージョン番号を示す5つの値のタプル:major, minor, micro, releaselevel, serialreleaselevel 以外は全て整数です。 releaselevel の値は、 'alpha', 'beta', 'candidate', 'final' の何れかです。 Python 2.0 の version_info は、 (2, 0, 0, 'final', 0) となります。

バージョン 2.0 で追加.

sys.warnoptions

この値は、warnings framework 内部のみ使用され、変更することはできません。詳細は warnings を参照してください。

sys.winver

Windows プラットフォームで、レジストリのキーとなるバージョン番号。 Python DLL の文字列リソース 1000 に設定されています。通常、この値は version の先頭三文字となります。この値は参照専用で、別の値を設定しても Python が使用するレジストリキーを変更することはできません。利用可能: Windows.

Citations

[C99]ISO/IEC 9899:1999. “Programming languages – C.” A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf .