1. コマンドラインと環境¶
CPython インタプリタはコマンドラインと環境を読み取って様々な設定を行ないます。
CPython 実装の詳細: 他の実装のコマンドラインスキームは CPython とは異なります。さらなる情報は 別のPythonの実装 を参照してください。
1.1. コマンドライン¶
Python を起動するとき、以下のうち任意のオプションを指定できます:
python [-bBdEiOQsRStuUvVWxX3?] [-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) を含めてはいけません。module-nameは有効な Python のモジュール名であるべきですが、実装がそれを強制しているとは限りません (例えば、ハイフンを名前に含める事を許可するかもしれません)。パッケージ名を指定することもできます。通常のモジュールの代わりにパッケージ名を指定された場合、インタープリタは
<pkg>.__main__をメインモジュールとして実行します。この動作はインタープリタのスクリプト引数としてディレクトリやzipファイルを指定された時の動作と意図的に似せています。注釈
このオプションはビルトインモジュールや C で書かれた拡張モジュールには利用できません。 Python モジュールファイルを持っていないからです。しかし、コンパイル済みのモジュールは、たとえ元のソースファイルがなくても利用可能です。
このオプションが指定された場合、
sys.argvの先頭要素はモジュールファイルのフルパスになります。-cオプションのように、カレントディレクトリがsys.pathの先頭に追加されます。多くの標準ライブラリモジュールにはスクリプトとして実行された時のためのコードがあります。例えば、
timeitモジュールは次のように実行可能です:python -mtimeit -s 'setup here' 'benchmarked code here' python -mtimeit -h # for details
バージョン 2.4 で追加.
バージョン 2.5 で変更: パッケージ内のモジュールを指定できるようになりました。
バージョン 2.7 で変更: パッケージ名を指定したときに
__main__サブモジュールを実行するようにしました。そのモジュールを検索している間の sys.argv[0] は"-m"に設定されるようになりました。 (以前は間違って"-c"が設定されていました)
-
- 標準入力 (
sys.stdin) からコマンドを読み込みます。標準入力がターミナルだった場合、暗黙的に-iオプションが指定されます。このオプションが指定された場合、
sys.argvの最初の要素は"-"で、カレントディレクトリがsys.pathの先頭に追加されます。参考
runpy.run_path()- Python コードで直接使える等価な機能
-
<script> script 内の Python コードを実行します。 script は、Python ファイル、
__main__.pyファイルがあるディレクトリ、__main__.pyファイルがある zip ファイルのいずれかの、ファイルシステム上の (絶対または相対) パスでなければなりません。このオプションが指定された場合、
sys.argvの最初の要素はコマンドラインで指定されたスクリプト名になります。スクリプト名が Python ファイルを直接指定していた場合、そのファイルを含むディレクトリが
sys.pathの先頭に追加され、そのファイルは__main__モジュールとして実行されます。スクリプト名がディレクトリか zip ファイルを指定していた場合、スクリプト名が
sys.pathに追加され、その中の__main__.pyファイルが__main__モジュールとして実行されます。バージョン 2.5 で変更: トップレベルに
__main__.pyファイルを持つディレクトリや zip ファイルが有効な Python スクリプトとなりました。
インターフェイスオプションが与えられなかった場合、 -i が暗黙的に指定され、 sys.argv[0] は空白文字列 ("")で、カレントディレクトリが sys.path の先頭に追加されます。
参考
1.1.2. 一般オプション¶
1.1.3. その他のオプション¶
-
-b¶ Issue a warning when comparing
unicodewithbytearray. Issue an error when the option is given twice (-bb).Note that, unlike the corresponding Python 3.x flag, this will not emit warnings for comparisons between
strandunicode. Instead, thestrinstance will be implicitly decoded tounicodeand Unicode comparison used.バージョン 2.6 で追加.
-
-B¶ Python は import したソースモジュールの
.pycや.pyoファイルの作成を試みません。PYTHONDONTWRITEBYTECODE環境変数も参照してください。バージョン 2.6 で追加.
-
-d¶ パーサーのデバッグ出力を有効にします。(呪文を解する人だけ使ってください。コンパイルオプションに依存します)。
PYTHONDEBUGも参照してください。
-
-E¶ 全ての
PYTHON*環境変数を無視します。例えば、PYTHONPATHやPYTHONHOMEなどです。バージョン 2.2 で追加.
-
-i¶ 最初の引数にスクリプトが指定された場合や
-cオプションが利用された場合、sys.stdinがターミナルに出力されない場合も含めて、スクリプトかコマンドを実行した後にインタラクティブモードに入ります。PYTHONSTARTUPファイルは読み込みません。このオプションはグローバル変数や、スクリプトが例外を発生させるときにそのスタックトレースを調べるのに便利です。
PYTHONINSPECTも参照してください。
-
-O¶ 基本的な最適化を有効にします。コンパイル済み (bytecode) ファイルの拡張子を
.pycから.pyoに変更します。PYTHONOPTIMIZEも参照してください。
-
-Q<arg>¶ 除算制御。引数は以下のうち1つでなければなりません:
old- int/int と long/long の除算は、 int か long を返します。 (デフォルト)
new- 新しい除算方式。 int/int や long/long の除算が float を返します。
warn- 古い除算方式で、 int/int や long/long 除算に警告を表示します。
warnall- 古い除算方式で、全ての除算演算子に対して警告を表示します。
-
-R¶ ハッシュのランダム化をします。文字列、バイト列、datetime オブジェクトの
__hash__()値は予測不可能なランダム値で "ソルト化" されます。 ハッシュ値は単独の Python プロセス内では定数であり続けますが、Python を繰り返し起動する毎に、予測できなくなります。これは、慎重に選ばれた入力で辞書挿入の最悪性能 O(n^2) 複雑性を悪用することで引き起こされるサービス妨害 (denial-of-service) に対する保護を目的とするものです。詳細は http://www.ocert.org/advisories/ocert-2011-003.html を参照してください。
ハッシュ値の変更は辞書からキーを取り出す順序に影響します。 Python はこの順序付けを保証していませんが (そして通常 32-bit と 64-bit の間でも異なります)、たくさんの実世界でのコードが、ランダム化がデフォルトで無効というこの保障されない振る舞いに、暗黙で依存しています。
PYTHONHASHSEEDも参照してください。バージョン 2.6.8 で追加.
-
-s¶ user site-packages directoryをsys.pathに追加しません。バージョン 2.6 で追加.
参考
PEP 370 – Per user site-packages directory
-
-t¶ ソースファイルが、タブ幅に依存して意味が変わるような方法でタブ文字とスペースを混ぜて含んでいる場合に警告を発生させます。このオプションを2重にする (
-tt) とエラーになります。
-
-u¶ stdin, stdout, stderr のバッファを強制的に無効にします。関係するシステムでは、 stdin, stdout, stderr をバイナリモードにします。
file.readlines()や ファイルオブジェクト (for line in sys.stdin) はこのオプションに影響されない内部バッファリングをしています。これを回避したい場合は、while 1:ループの中でfile.readline()します。PYTHONUNBUFFEREDも参照してください。
-
-v¶ モジュールが初期化されるたびに、それがどこ(ファイル名やビルトインモジュール) からロードされたのかを示すメッセージを出力します。 二重に指定された場合(
-vv)は、モジュールを検索するときにチェックされた各ファイルに対してメッセージを出力します。また、終了時のモジュールクリーンアップに関する情報も提供します。PYTHONVERBOSEも参照してください。
-
-Warg¶ 警告制御。 Python の警告機構はデフォルトでは警告メッセージを
sys.stderrに出力します。典型的な警告メッセージは次のような形式です:file:line: category: message
デフォルトでは、各警告は発生したソース行ごとに一度だけ表示されます。このオプションは、警告をどれくらいの頻度で表示するかを制御します。
複数の
-Wオプションを指定することができます。警告が1つ以上のオプションとマッチしたときは、最後にマッチしたオプションのアクションが有効になります。不正な-Wオプションは無視されます (最初の警告が発生したときに、不正なオプションに対する警告メッセージが表示されます)。Python 2.7 から、
DeprecationWarningとその子クラスはデフォルトで無視されます。-Wdオプションを指定して有効にすることができます。警告は 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専用のハックのみを目的としています。
-
-3¶ Warn about Python 3.x possible incompatibilities by emitting a
DeprecationWarningfor features that are removed or significantly changed in Python 3 and can’t be detected using static code analysis.バージョン 2.6 で追加.
See Python 2 から Python 3 への移植 for more details.
1.1.4. 使うべきでないオプション¶
-
-U¶ 全ての文字列リテラルを、全部 unicode にします。このオプションはあなたの世界を破壊してしまうかもしれないので、このオプションを使おうとしないでください。これは、通常とは違うマジックナンバーを使って
.pycファイルを生成します。ファイルの先頭に次のように書いて、このオプションの代わりにモジュール単位で unicode リテラルを有効にできます。from __future__ import unicode_literals
詳細は
__future__を参照してください。
-
-X¶ 別の Python の実装が独自の目的で利用するために予約されています。
1.2. 環境変数¶
以下の環境変数は Python の挙動に影響します。環境変数は -E 以外のコマンドラインスイッチの前に処理されます。衝突したときにコマンドラインスイッチが環境変数をオーバーライドするのは慣例です。
-
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 コマンドを実行します。このファイルはインタラクティブコマンドが実行されるのと同じ名前空間の中で実行されるので、このファイル内で定義されたり import されたオブジェクトはインタラクティブセッションから制限無しに利用することができます。このファイルで
sys.ps1とsys.ps2を変更してプロンプトを変更することもできます。
-
PYTHONY2K¶ この変数に空でない文字列を設定すると、
timeモジュールが文字列で指定される日付に4桁の年を含むことを要求するようになります。そうでなければ、2桁の年はtimeモジュールのドキュメントに書かれているルールで変換されます。
-
PYTHONINSPECT¶ この変数に空でない文字列を設定するのは
-iオプションを指定するのと等価です。この変数は Python コードから
os.environを使って変更して、プログラム終了時のインスペクトモードを強制することができます。
-
PYTHONCASEOK¶ この環境変数が設定されていると、 Python は
import文で大文字/小文字を区別しません。 これは Windows, OS X, OS/2, RiscOS でのみ動作します。
-
PYTHONDONTWRITEBYTECODE¶ この環境変数が設定されていると、 Python はソースモジュールの import 時に
.pyc,.pyoファイルを生成しません。これは-Bオプションを指定したのと等価です。バージョン 2.6 で追加.
-
PYTHONHASHSEED¶ この変数が
randomに設定された場合-Rを指定するのと同じ効果が得られます: 乱数値が str、bytes ならびに datetime オブジェクトのハッシュのシードに使われます。PYTHONHASHSEEDが整数値に設定された場合、その値はハッシュランダム化が扱う型の hash() 生成の固定シードに使われます。その目的は再現性のあるハッシュを可能にすることです。例えばインタープリタ自身の自己テストや Python プロセスのクラスタでハッシュ値を共有するのに用います。
整数は [0,4294967295] の十進数でなければなりません。0 を指定するとハッシュはハッシュランダム化を無効にしたのと同じ値になります。
バージョン 2.6.8 で追加.
-
PYTHONIOENCODING¶ stdin/stdout/stderr のエンコーディングを強制します。シンタックスは
encodingname:errorhandlerです。:errorhandlerの部分はオプションで、str.encode()の引数と同じ意味です。バージョン 2.6 で追加.
-
PYTHONNOUSERSITE¶ この環境変数が設定されている場合、 Python は
ユーザ site-packages ディレクトリをsys.pathに追加しません。バージョン 2.6 で追加.
参考
PEP 370 – Per user site-packages directory
-
PYTHONUSERBASE¶ user base directoryを設定します。これはpython setup.py install --user時にuser site-packages directoryと Distutils installation paths のパスを計算するのに使われます。バージョン 2.6 で追加.
参考
PEP 370 – Per user site-packages directory
-
PYTHONEXECUTABLE¶ この環境変数が設定された場合、
sys.argv[0]に、C ランタイムから取得した値の代わりにこの環境変数の値が設定されます。Mac OS X でのみ動作します。
-
PYTHONHTTPSVERIFY¶ この環境変数が
0に設定されていた場合、sslが初めてインポートされたときにssl._https_verify_certificates()をenable=Falseで暗黙的に呼び出したのと同じことになります。詳細は
ssl._https_verify_certificates()の説明を参照してください。バージョン 2.7.12 で追加.
1.2.1. デバッグモード変数¶
以下の環境変数は、--with-pydebug ビルドオプションを指定して構成されたデバッグビルド版の Python でのみ効果があります。
-
PYTHONTHREADDEBUG¶ 設定された場合、 Python はスレッドデバッグ情報を表示します。
バージョン 2.6 で変更: 以前は、この変数は
THREADDEBUGという名前でした。
-
PYTHONDUMPREFS¶ 設定された場合、 Python はインタプリタのシャットダウン後に残っているオブジェクトとリファレンスカウントをダンプします。
-
PYTHONMALLOCSTATS¶ 設定された場合、 Python は、新しいオブジェクトアリーナを作成するときと、シャットダウン時に、メモリアロケーション統計情報を表示します。
-
PYTHONSHOWALLOCCOUNT¶ If set and Python was compiled with
COUNT_ALLOCSdefined, Python will dump allocations counts into stderr on shutdown.バージョン 2.7.15 で追加.
-
PYTHONSHOWREFCOUNT¶ If set, Python will print the total reference count when the program finishes or after each statement in the interactive interpreter.
バージョン 2.7.15 で追加.