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

  valueが`None`以外の場合、`value`を`sys.stdout`に 出力して`__builtin__._`に保存します。

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

`excepthook`( | type, value, traceback)

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

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

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

`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_value`と`exc_traceback`は未定義となります。

`exec_prefix`

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

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

`exit`( | [arg])

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

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

`getcheckinterval`( | )

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

`getdefaultencoding`( | )

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

`getdlopenflags`( | )

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

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

`getfilesystemencoding`( | )

  Unicodeファイル名をシステムのファイル名に変換する際に使用する エンコード名を返します。システムのデフォルトエンコーディングを使用する 場合には`None`を返します。
  - Windows 9xでは、エンコーディングは ``mbcs'' となります。
  - OS Xでは、エンコーディングは ``utf-8'' となります。
  - Unixでは、エンコーディングはユーザのnl_langinfo(CODESET)の設定となります。 nl_langinfo(CODESET)が失敗すると`None`を返します。
  - Windows NT+では、Unicodeをファイル名として使用することができるので 変換の必要がありません。
  バージョン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, text。 textは文字列、それ以外の値は整数です。

  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
  3 (`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'`に格納されます (但しversionは`version[: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)`と指定します。 フラグの定義名は`dl`か`DLFCN`で定義されています。 `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()`を呼び出し、ト レース関数を登録してください。

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

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

`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`
  バージョン番号を示す５つの値のタプル: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`.