1. コマンドラインと環境¶
CPython インタプリタはコマンドラインと環境を読み取って様々な設定を行ないます。
CPython 実装の詳細: 他の実装のコマンドラインスキームは 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
バージョン 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. 一般オプション¶
1.1.3. その他のオプション¶
-
-b¶ bytesまたはbytearrayをstrと比較した場合、または、bytesをintと比較した場合に警告を発生させます。このオプションを2度指定した場合 (-bb) は、エラーを発生させます。
-
-B¶ 与えられた場合、Python はソースモジュールのインポート時に
.pycファイルの作成を試みません。PYTHONDONTWRITEBYTECODE環境変数も参照してください。
-
-d¶ パーサーのデバッグ出力を有効にします。(エキスパート専用です。コンパイルオプションに依存します)。
PYTHONDEBUGも参照してください。
-
-E¶ 全ての
PYTHON*環境変数を無視します。例えば、PYTHONPATHやPYTHONHOMEなどです。
-
-i¶ 最初の引数にスクリプトが指定された場合や
-cオプションが利用された場合、sys.stdinがターミナルに出力されない場合も含めて、スクリプトかコマンドを実行した後にインタラクティブモードに入ります。PYTHONSTARTUPファイルは読み込みません。このオプションはグローバル変数や、スクリプトが例外を発生させるときにそのスタックトレースを調べるのに便利です。
PYTHONINSPECTも参照してください。
-
-I¶ Python を隔離モードで実行します。-E と -s も暗黙的に指定されます。隔離モードでは
sys.pathはスクリプトのディレクトリやユーザのサイトパッケージのディレクトリを含みません。全PYTHON*環境変数も無視されます。ユーザが悪意のあるコードを注入するのを防ぐために更なる制限が課されるかもしれません。バージョン 3.4 で追加.
-
-O¶ 基本的な最適化を有効にします。 :envvar:PYTHONOPTIMIZE: も見てください。
-
-q¶ インタラクティブモードでも copyright とバージョンのメッセージを表示しません。
バージョン 3.2 で追加.
-
-R¶ 互換性のために残されています。Python 3.3 以降ではデフォルトでハッシュランダム化されます。
以前のバージョンの Python では、このオプションはハッシュのランダム化を有効にします。これにより、 str, bytes, datetime 型の
__hash__()値が予測不可能な乱数で “塩漬け” されます。ハッシュ値は各 Python プロセスでは固定ですが、 Python を繰り返し再実行した場合は別の予測不能な値になります。ハッシュのランダム化は、dict の生成コストが最悪の O(n^2) になるように注意深く選ばれた入力値を与えることによる DoS 攻撃への防御策として提供されています。詳細は http://www.ocert.org/advisories/ocert-2011-003.html を参照してください。
PYTHONHASHSEEDによってハッシュシードの固定値を秘密にすることが出来ます。バージョン 3.2.3 で追加.
-
-s¶ user site-packages directoryをsys.pathに追加しません。参考
PEP 370 – Per user site-packages directory
-
-S¶ siteモジュールの import と、そのモジュールが行なっていた site ごとのsys.pathへの操作を無効にします。後にsiteを明示的に import しても、これらの操作は実行されません (実行したい場合は、site.main()を呼び出してください)。
-
-u¶ 標準出力と標準エラー出力のストリームのバイナリーレイヤー (
buffer属性として利用可能) がバッファされないよう強制します。それでもテキスト I/O レイヤーは、コンソールに出力する場合はラインバッファされ、日対話的なファイルにリダイレクトされた場合はブロックバッファされます。PYTHONUNBUFFEREDも参照してください。
-
-v¶ モジュールが初期化されるたびに、それがどこ(ファイル名やビルトインモジュール) からロードされたのかを示すメッセージを出力します。 二重に指定された場合(
-vv)は、モジュールを検索するときにチェックされた各ファイルに対してメッセージを出力します。また、終了時のモジュールクリーンアップに関する情報も提供します。PYTHONVERBOSEも参照してください。
-
-Warg¶ 警告制御。 Python の警告機構はデフォルトでは警告メッセージを
sys.stderrに出力します。典型的な警告メッセージは次のような形式です:file:line: category: message
デフォルトでは、各警告は発生したソース行ごとに一度だけ表示されます。このオプションは、警告をどれくらいの頻度で表示するかを制御します。
複数の
-Wオプションを指定することができます。警告が1つ以上のオプションとマッチしたときは、最後にマッチしたオプションのアクションが有効になります。不正な-Wオプションは無視されます (最初の警告が発生したときに、不正なオプションに対する警告メッセージが表示されます)。警告は Python プログラムの中から
warningsモジュールを利用して制御することができます。引数の最もシンプルな形は、以下のアクションの文字列 (あるいはそのユニークな短縮形) です:
ignore全ての警告を無視する。
default明示的にデフォルトの動作(ソース行ごとに1度警告を表示する)を要求する。
all警告が発生するたびに表示する (これは、ループの中などで同じソース行により繰り返し警告が発生された場合に、大量のメッセージを表示します)。
module各モジュールで最初に発生した警告を表示する。
onceプログラムで最初に発生した警告だけを表示する。
error警告メッセージを表示する代わりに例外を発生させる。
引数の完全形は次のようになります:
action:message:category:module:line
ここで、 action は上で説明されたものですが、残りのフィールドにマッチしたメッセージにだけ適用されます。空のフィールドは全ての値にマッチします。空のフィールドの後ろは除外されます。 message フィールドは表示される警告メッセージの先頭に、大文字小文字を無視してマッチします。 category フィールドは警告カテゴリにマッチします。これはクラス名でなければなりません。 category のマッチは、メッセージの実際の警告カテゴリーが指定された警告カテゴリーのサブクラスかどうかをチェックします。完全なクラス名を指定しなければなりません。 module フィールドは、(完全正規形(fully-qualified)の) モジュール名に対してマッチします。このマッチは大文字小文字を区別します。 line フィールドは行番号にマッチします。 0 は全ての行番号にマッチし、省略した時と同じです。
-
-x¶ Unix 以外の形式の
#!cmdを使うために、ソースの最初の行をスキップします。これは、DOS専用のハックのみを目的としています。注釈
エラーメッセージ内の行番号は -1 されます。
-
-X¶ 様々な実装固有のオプションのために予約されています。現在のところ CPython は以下の値を定義しています:
-X faulthandlerはfaulthandlerを有効化します;-X showrefcountは全参照カウントとメモリブロックの出力を有効化します (デバッグビルドでのみ動きます);-X tracemallocはtracemallocモジュールを用いて Python のメモリ割り当てのトレースを開始します。デフォルトでは最新のフレームのみがトレースのトレースバックに格納されます。最大 NFRAME フレームのトレースバックで トレースを開始するには-X tracemalloc=NFRAMEを使用してください。詳細はtracemalloc.start()を参照してください。
任意の値を渡し、
sys._xoptions辞書から取り出すことも出来ます。バージョン 3.2 で変更: CPython に
-Xを渡すことが可能になりました。バージョン 3.3 で追加:
-X faulthandlerオプション。バージョン 3.4 で追加:
-X showrefcountおよび-X tracemallocオプション。
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__を変更することも出来ます。
-
PYTHONINSPECT¶ この変数に空でない文字列を設定するのは
-iオプションを指定するのと等価です。この変数は Python コードから
os.environを使って変更して、プログラム終了時のインスペクトモードを強制することができます。
-
PYTHONDONTWRITEBYTECODE¶ If this is set to a non-empty string, Python won’t try to write
.pycfiles on the import of source modules. This is equivalent to specifying the-Boption.
-
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の部分が任意になりました。
-
PYTHONNOUSERSITE¶ この環境変数が設定されている場合、 Python は
ユーザ site-packages ディレクトリをsys.pathに追加しません。参考
PEP 370 – Per user site-packages directory
-
PYTHONUSERBASE¶ user base directoryを設定します。これはpython setup.py install --user時にuser site-packages directoryと Distutils installation paths のパスを計算するのに使われます。参考
PEP 370 – Per user site-packages directory
-
PYTHONEXECUTABLE¶ この環境変数が設定された場合、
sys.argv[0]に、C ランタイムから取得した値の代わりにこの環境変数の値が設定されます。Mac OS X でのみ動作します。
-
PYTHONFAULTHANDLER¶ この環境変数が空でない文字列に設定された場合、起動時に
faulthandler.enable()が呼び出されます。Python のトレースバックをダンプするためにSIGSEGV、SIGFPE、SIGABRT、SIGBUSおよびSIGILLシグナルのハンドラを導入します。-Xfaulthandlerオプションと等価です。バージョン 3.3 で追加.
-
PYTHONTRACEMALLOC¶ この環境変数が空でない文字列に設定された場合、
tracemallocモジュールを利用して Python のメモリ割り当てのトレースを開始します。変数の値はトレース時のトレースバックで保持されるフレームの最大数です。例えばPYTHONTRACEMALLOC=1の場合、最新のフレームのみを保持します。詳細はtracemalloc.start()を参照してください、バージョン 3.4 で追加.
1.2.1. デバッグモード変数¶
以下の環境変数は、--with-pydebug ビルドオプションを指定して構成されたデバッグビルド版の Python でのみ効果があります。
-
PYTHONTHREADDEBUG¶ 設定された場合、 Python はスレッドデバッグ情報を表示します。
-
PYTHONDUMPREFS¶ 設定された場合、 Python はインタプリタのシャットダウン後に残っているオブジェクトと参照カウントをダンプします。
-
PYTHONMALLOCSTATS¶ 設定された場合、 Python は新しいオブジェクトの活動の場作成するときとシャットダウンときに、メモリ割り当ての統計情報を表示します。