3.1 sys -- システムパラメータと関数

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

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

byteorder
プラットフォームのバイト順を示します。ビッグエンディアン(最上位バ イトが先頭)のプラットフォームでは'big'、リトルエンディアン(最下 位バイトが先頭)では'little'となります。 バージョン 2.0 で 新たに追加 された仕様です。

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

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

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

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

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

excepthook( type, value, traceback)
指定したトレースバックと例外をsys.stderrに出力します。

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

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

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

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

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

exc_type
exc_value
exc_traceback
リリース 1.5 で撤廃されました。 exc_info()を使用してください

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

exec_prefix

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

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

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

exitfunc
この値はモジュールに存在しませんが、ユーザプログラムでプログラム終了時 に呼び出される終了処理関数として、引数の数が0の関数を設定することがで きます。この関数は、インタープリタ終了時に呼び出されます。 exitfuncに指定することができる終了処理関数は一つだけですので、 複数のクリーンアップ処理が必要な場合はatexitモジュールを使 用してください。 注意: プログラムがシグナルでkillされた場合,Python内部で致命的なエラーが 発生した場合,os._exit()が呼び出された場合には, 終了処理関数は呼び出されません。
リリース 2.4 で撤廃されました。 atexit を使ってください.

getcheckinterval( )
インタプリタの ``チェックインターバル (check interval)'' を 返します; setcheckinterval() を参照してください。 バージョン 2.3 で 新たに追加 された仕様です。

getdefaultencoding( )
現在のUnicode処理のデフォルトエンコーディング名を返します。 バージョン 2.0 で 新たに追加 された仕様です。

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

利用可能: Unix. バージョン 2.2 で 新たに追加 された仕様です。

getfilesystemencoding( )
Unicodeファイル名をシステムのファイル名に変換する際に使用する エンコード名を返します。システムのデフォルトエンコーディングを使用する 場合にはNoneを返します。 バージョン 2.3 で 新たに追加 された仕様です。

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

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

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

この関数は、内部的な、特殊な用途にのみ利用することができます。

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

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

Constant Platform
VER_PLATFORM_WIN32s Win32s on Windows 3.1
VER_PLATFORM_WIN32_WINDOWS Windows 95/98/ME
VER_PLATFORM_WIN32_NT Windows NT/2000/XP
VER_PLATFORM_WIN32_CE Windows CE

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

利用可能: Windows. バージョン 2.3 で 新たに追加 された仕様です。

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進数に変換しなければ値の意味が わかりません。より読みやすいバージョン番号が必要な場合には version_infoを使用してください。 バージョン 1.5.2 で 新たに追加 された仕様です。

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

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

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

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

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

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

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

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

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

platform
プラットフォームを識別する文字列(例: 'sunos5', 'linux1' 等)。pathにプラットフォーム別のサブディレクトリを追加する場 合などに利用します。

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

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

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

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

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

利用可能: Unix. バージョン 2.2 で 新たに追加 された仕様です。

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

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

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

settrace( tracefunc)
システムのトレース関数を登録します。トレース関数 はPythonのソースデバッガを実装するために使用することができます。 9.2の``How It Works,''を参照してください。 トレース関数はスレッド毎に設定することができますの で、デバッグを行う全てのスレッドでsettrace()を呼び出し、ト レース関数を登録してください。 注意: settrace() 関数は,デバッガ,プロファイラ, カバレッジツール等で使うためだけのものです. この関数の挙動は言語定義よりも実装プラットフォームの分野の問題で, 全ての Python 実装で利用できるとは限りません.

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

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

__stdin__
__stdout__
__stderr__
それぞれ起動時のstdinstderrstdoutの値を保存し ます。終了処理時や、不正なオブジェクトが指定された場合に元の値に復旧す るために使用します。

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

version
Pythonインタープリタのバージョンとビルド番号・使用コンパイラなどの情 報を示す文字列で、'バージョン(#ビルド番号, ビルド日付, ビルド時間)[コンパイラ]'となります。先 頭の三文字は、バージョンごとのインストール先ディレクトリ内を識別するた めに使用されます。例:

>>> import sys
>>> sys.version
'1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]'

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

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

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

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

参考:

site:モジュール
This describes how to use .pth files to extend sys.path.

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。