29.1. 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._debugmallocstats()

CPython のメモリアロケータの状態に関する低レベルの情報を標準エラー出力に出力します。

Python が configure 時に –with-pydebug オプションを指定してビルドされている場合、負荷のかかる一貫性チェックも行います。

バージョン 3.3 で追加.

CPython implementation detail: この関数は CPython 固有です。正確な出力形式は定義されていませんし、変更されるかもしれません。

sys.dllhandle

Python DLLのハンドルを示す整数です。利用できる環境: Windows。

sys.displayhook(value)

valueNone 以外の時、repr(value)sys.stdout に出力し、builtins._ に保存します。repr(value) がエラーハンドラを sys.stdout.errors (おそらく 'strict') として sys.stdout.encoding にエンコードできない場合、エラーハンドラを 'backslashreplace' として sys.stdout.encoding にエンコードします。

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

擬似コード:

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

If this is true, Python won’t try to write .pyc files on the import of source modules. This value is initially set to True or False depending on the -B command line option and the PYTHONDONTWRITEBYTECODE environment variable, but you can set it yourself to control bytecode file generation.

sys.excepthook(type, value, traceback)

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

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

sys.__displayhook__
sys.__excepthook__

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

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.Y3.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 を返します。argNone を指定した場合は、数値の 0 を指定した場合と同じです。それ以外の型のオブジェクトを指定すると、そのオブェクトが stderr に出力され、終了コードとして 1 を返します。エラー発生時には sys.exit("エラーメッセージ") と書くと、簡単にプログラムを終了することができます。

究極には、exit() は例外を送出する “だけ” なので、これがメインスレッドから呼び出された時は、プロセスを終了するだけで、例外は遮断されません。

sys.flags

コマンドラインフラグの状態を表す 構造体シーケンス です。各属性は読み込み専用になっています。

attribute

フラグ

debug -d
inspect -i
interactive -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

バージョン 3.2 で変更: 新しい -q 向けに quiet 属性が追加されました。

バージョン 3.2.3 で追加: hash_randomization 属性が追加されました。

バージョン 3.3 で変更: 廃止済みの division_warning 属性を削除しました。

sys.float_info

float 型に関する情報を保持している 構造体シーケンス です。精度と内部表現に関する低レベル情報を含んでいます。これらの値は ‘C’ 言語の標準ヘッダファイル float.h で定義されている様々な浮動小数点定数に対応しています。詳細は 1999 ISO/IEC C standard [C99] の 5.2.4.2.2 節 ‘Characteristics of floating types’ を参照してください。

attribute

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

floa tが 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()

Return the number of memory blocks currently allocated by the interpreter, regardless of their size. This function is mainly useful for tracking and debugging memory leaks. Because of the interpreter’s internal caches, the result can vary from call to call; you may have to call _clear_type_cache() and gc.collect() to get more predictable results.

If a Python build or implementation cannot reasonably compute this information, getallocatedblocks() is allowed to return 0 instead.

バージョン 3.4 で追加.

sys.getcheckinterval()

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

バージョン 3.2 で撤廃: 代わりに getswitchinterval() を使ってください。

sys.getdefaultencoding()

Unicode 実装で使用される現在のデフォルトエンコーディング名を返します。

sys.getdlopenflags()

Return the current value of the flags that are used for dlopen() calls. Symbolic names for the flag values can be found in the os module (RTLD_xxx constants, e.g. os.RTLD_LAZY). Availability: Unix.

sys.getfilesystemencoding()

Unicode ファイル名をシステムのファイル名に変換する際に使用するエンコード名を返します。返り値ははオペレーティングシステムに依存します:

  • Mac OS X では、エンコーディングは 'utf-8' となります。

  • Unix では、エンコーディングはユーザー設定 (nl_langinfo(CODESET) の結果) に従います。

  • Windows NT+ では、Unicode をファイル名として使用できるので変換の必要はありません。getfilesystemencoding()'mbcs' を返しますが、これはある Unicode 文字列をバイト文字列に明示的に変換して、ファイル名として使うと同じファイルを指すようにしたい場合に、アプリケーションが使わなければならないエンコーディングです。

  • Windows 9x では、エンコーディングは 'mbcs' となります。

バージョン 3.2 で変更: getfilesystemencoding() の結果が None になることはなくなりました。

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__ メソッドを呼び出し、そのオブジェクトがガベージコレクタに管理されていた場合はガベージコレクタのオーバーヘッドを増やします。

See recursive sizeof recipe for an example of using getsizeof() recursively to find the size of containers and all their contents.

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 バージョンを示す、名前付きタプルを返します。名前付き要素には、majorminorbuildplatformservice_packservice_pack_minorservice_pack_majorsuite_mask、および product_type があります。service_pack は文字列を含み、それ以外は整数です。この構成要素には名前でもアクセスできるので、sys.getwindowsversion()[0]sys.getwindowsversion().major と等価です。先行のバージョンとの互換性のため、最初の 5 要素がインデックス指定で得られます。

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

product_type は、以下の値のいずれかになります:

定数

意味

1 (VER_NT_WORKSTATION)

システムはワークステーションです。

2 (VER_NT_DOMAIN_CONTROLLER)

システムはドメインコントローラです。

3 (VER_NT_SERVER)

システムはサーバですが、ドメインコントローラではありません。

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

利用出来る環境 : Windows.

バージョン 3.2 で変更: 名前付きタプルに変更され、service_pack_minor, service_pack_major, suite_mask, および product_type が 追加されました。

sys.get_coroutine_wrapper()

Returns None, or a wrapper set by set_coroutine_wrapper().

バージョン 3.5 で追加: See PEP 492 for more details.

注釈

This function has been added on a provisional basis (see PEP 411 for details.) Use it only for debugging purposes.

sys.hash_info

数値のハッシュ実装のパラメータを与える 構造体シーケンス です。数値型のハッシュ化についての詳細は 数値型のハッシュ化 を参照してください。

attribute

説明

width

ハッシュ値に利用されるビット幅

modulus

数値ハッシュ計算に利用される素数の法

inf

正の無限大に対して返されるハッシュ値

nan

nan に対して返されるハッシュ値

imag

複素数の虚部を表すための乗数

algorithm

strbytesmemoryview オブジェクトのハッシュアルゴリズムの名前

hash_bits

ハッシュアルゴリズムの内部出力サイズ

seed_bits

ハッシュアルゴリズムのシードキーのサイズ

バージョン 3.2 で追加.

バージョン 3.4 で変更: algorithmhash_bitsseed_bits を追加

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 進数に変換しなければ値の意味を持ちません。より読みやすいバージョン番号が必要な場合には 構造体シーケンス sys.version_info を使用してください。

More details of hexversion can be found at API と ABI のバージョニング.

sys.implementation

現在起動している Python インタプリタに関する情報が格納されたオブジェクトです。すべての Python 実装において、以下の属性が存在することが要求されています。

name は実装の識別子です (例: 'cpython')。実際の文字列は Python 実装によって定義されますが、小文字であることが保証されています。

versionsys.version_info と同じ形式の、Python 実装 のバージョンを表す名前付きタプルです。これは現在起動しているインタプリタ固有のバージョンを意味します。sys.version_info は Python *言語*のバージョンであり、これはそのバージョンに準拠した*実装*のバージョンです。例えば、PyPy 1.8 の sys.implementation.versionsys.version_info(1, 8, 0, 'final', 0) になるのに対し、sys.version_infosys.version_info(2, 7, 2, 'final', 0) になります。CPython は、それがリファレンス実装であるため、両者は同じ値になります。

hexversionsys.hexversion と同形式の、16 進数での実装のバージョンです。

cache_tag は、キャッシュされたモジュールのファイル名に使用されるタグです。慣例により、これは実装名とバージョンを組み合わせた文字列になります (例: 'cpython-33') が、Python 実装はその他の適切な値を使う場合があります。cache_tagNone が設定された場合、モジュールのキャッシングが無効になっていることを示します。

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 の値は 0xFFFF0x10FFFF になっていました。

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 モジュールでは、sys.path を拡張する .pth ファイルの使い方を説明します。

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

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

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関数は 3 個の引数、frameevent、および arg を受け取る必要があります。frame は現在のスタックフレームです。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'

インタプリタがコードの新しい行を実行しようとしている、または、ループの条件で再実行しようとしている。ローカルの trace 関数が呼ばれる。argNone。返り値は新しいローカルの trace 関数。これがどのように動作するかの詳細な説明は、Objects/lnotab_notes.txt を参照のこと。

'return'

関数 (あるいは別のコードブロック) から戻ろうとしている。ローカルの trace 関数が呼ばれる。arg は返されようとしている値、または、このイベントが例外が送出されることによって起こったなら None。trace 関数の戻り値値は無視される。

'exception'

例外が発生した。ローカルの trace 関数が呼ばれる。arg(exception, value, traceback) のタプル。戻り値は新しいローカルの trace 関数。

'c_call'

C 関数 (拡張関数かビルトイン関数) が呼ばれようとしている。arg は C 関数オブジェクト。

'c_return'

C 関数から戻った。arg は C の関数オブジェクト。

'c_exception'

C 関数が例外を送出した。arg は C の関数オブジェクト。

例外が呼び出しチェインをたどって伝播していくことに注意してください。'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 を参照してください。

CPython implementation detail: This function is intimately bound to CPython implementation details and thus not likely to be implemented elsewhere.

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 で追加: See PEP 492 for more details.

注釈

This function has been added on a provisional basis (see PEP 411 for details.) Use it only for debugging purposes.

sys.stdin
sys.stdout
sys.stderr

インタプリタが使用する、それぞれ標準入力、標準出力、および標準エラー出力の ファイルオブジェクト です:

  • stdin は (input() の呼び出しも含む) すべての対話型入力に使われます。

  • stdoutprint() および expression 文の出力と、input() のプロンプトに使用されます。

  • インタプリタ自身のプロンプトおよびエラーメッセージは stderr に出力されます。

これらのストリームは open() が返すような通常の テキストファイル です。引数は以下のように選択されます:

  • 文字エンコーディングはプラットフォーム依存です。Windows では、ストリームが対話型 (isatty() メソッドが True を返す場合) であれば、コンソールのコードページが、それ以外では ANSI コードページが使用されます。その他のプラットフォームでは、ロケールのエンコーディングが使用されます (locale.getpreferredencoding() を参照)。

    しかしながら、どのプラットフォームでも Python を起動する前に環境変数 PYTHONIOENCODING を設定することでこの値を上書きすることが出来ます。

  • 対話型の場合、標準ストリームはラインバッファになります。それ以外の場合は、一般のテキストファイルと同様にブロックバッファになります。この設定はコマンドラインオプション -u で上書きできます。

注釈

標準ストリームにバイナリーデータの読み書きを行うには下位のバイナリー buffer オブジェクトを使用してください。例えば bytesstdout に書き出す場合は 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__

それぞれ起動時の stdinstderr、および stdout の値を保存しています。これらは終了処理時に使用されます。また、sys.std* オブジェクトがリダイレクトされている場合に、実際の標準ストリームへの出力に利用できます。

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

注釈

一部の条件下では、stdinstdout、および stderr もオリジナルの __stdin____stdout__、および __stderr__ も None になることがあります。これはコンソールに接続しない Windows GUI アプリケーションであり、かつ pythonw で起動された Python アプリケーションが該当します。

sys.thread_info

スレッドの実装に関する情報が格納された 構造体シーケンス です。

属性

説明

name

スレッド実装の名前:

  • 'nt': Windows スレッド

  • 'pthread': POSIX スレッド

  • 'solaris': Solaris スレッド

lock

ロック実装の名前:

  • 'semaphore': セマフォを使用するロック

  • 'mutex+cond': mutex と条件変数を使用するロック

  • None この情報が不明の場合

version

スレッドライブラリの名前とバージョン。文字列、あるいは不明の場合は None

バージョン 3.3 で追加.

sys.tracebacklimit

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

sys.version

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

sys.api_version

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

sys.version_info

バージョン番号を示す 5 個の値のタプル: majorminormicroreleaselevel、および 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

Windows プラットフォームで、レジストリのキーとなるバージョン番号です。Python DLL の文字列リソース 1000 に設定されています。通常、この値は version の先頭三文字となります。 この値は情報を得るために sys モジュールで提供されています。別の値を設定しても 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