1. 命令行與環(huán)境?

1.1.1. 接口選項?

解釋器接口類似于 UNIX shell，但提供了額外的調(diào)用方法:

• 用連接到 tty 設(shè)備的標準輸入調(diào)用時，會提示輸入并執(zhí)行命令，輸入 EOF （文件結(jié)束符，UNIX 中按 Ctrl-D，Windows 中按 Ctrl-Z, Enter）時終止。

• 用文件名參數(shù)或以標準輸入文件調(diào)用時，讀取，并執(zhí)行該腳本文件。

• 用目錄名參數(shù)調(diào)用時，從該目錄讀取、執(zhí)行適當名稱的腳本。

• 用 -c command 調(diào)用時，執(zhí)行 command 表示的 Python 語句。command 可以包含用換行符分隔的多條語句。注意，前導(dǎo)空白字符在 Python 語句中非常重要！

• 用 -m module-name 調(diào)用時，在 Python 模塊路徑中查找指定的模塊，并將其作為腳本執(zhí)行。

非交互模式下，先解析全部輸入，再執(zhí)行。

接口選項會終結(jié)解釋器讀入的選項列表，所有后續(xù)參數(shù)都在 sys.argv 里 -- 注意，首個元素，即下標為零的元素（sys.argv[0]）是表示程序來源的字符串。

-c <command>?

執(zhí)行 command 中的 Python 代碼。command 可以是一條語句，也可以是用換行符分隔的多條語句，其中，前導(dǎo)空白字符與普通模塊代碼中的作用一樣。

使用此選項時，sys.argv 的首個元素為 "-c"，并會把當前目錄加入至 sys.path 開頭（讓該目錄中的模塊作為頂層模塊導(dǎo)入）。

使用 command 參數(shù)會引發(fā) 審計事件 cpython.run_command 。

-m <module-name>?

在 sys.path 中搜索指定模塊，并以 __main__ 模塊執(zhí)行其內(nèi)容。

該參數(shù)是 模塊名，請勿輸入文件擴展名（.py）。模塊名應(yīng)為有效的絕對 Python 模塊名，但本實現(xiàn)對此不作強制要求（例如，允許使用含連字符 - 的名稱）。

包名稱（包括命名空間包）也允許使用。使用包名稱而不是普通模塊名時，解釋器把 <pkg>.__main__ 作為主模塊執(zhí)行。此行為特意被設(shè)計為與作為腳本參數(shù)傳遞給解釋器的目錄和 zip 文件的處理方式類似。

備注

此選項不適用于內(nèi)置模塊和以 C 編寫的擴展模塊，因為它們并沒有對應(yīng)的 Python 模塊文件。 但是它仍然適用于預(yù)編譯的模塊，即使沒有可用的初始源文件。

如果給出此選項，sys.argv 的首個元素將為模塊文件的完整路徑 (在定位模塊文件期間，首個元素將設(shè)為 "-m")。 與 -c 選項一樣，當前目錄將被加入 sys.path 的開頭。

-I 選項可用來在隔離模式下運行腳本，此模式中 sys.path 既不包含當前目錄也不包含用戶的 site-packages 目錄。 所有 PYTHON* 環(huán)境變量也會被忽略。

許多標準庫模塊都包含在執(zhí)行時，以腳本方式調(diào)用的代碼。例如 timeit 模塊：

python -m timeit -s 'setup here' 'benchmarked code here'
python -m timeit -h # for details

使用 module-name 參數(shù)會引發(fā) 審計事件 cpython.run_module 。

參見

runpy.run_module()

Python 代碼可以直接使用的等效功能

PEP 338 -- 將模塊作為腳本執(zhí)行

在 3.1 版更改: 提供包名稱來運行 __main__ 子模塊。

在 3.4 版更改: 同樣支持命名空間包

-

從標準輸入 (sys.stdin) 讀取命令。標準輸入為終端時，使用 -i。

使用此選項時，sys.argv 的第一個元素是 "-"， 同時，把當前目錄加入 sys.path 開頭。

沒有參數(shù)時，會觸發(fā) 審計事件 cpython.run_stdin 。

<script>

執(zhí)行 script 中的 Python 代碼，該參數(shù)應(yīng)為（絕對或相對）文件系統(tǒng)路徑，指向 Python 文件、包含 __main__.py 文件的目錄，或包含 __main__.py 文件的 zip 文件。

給出此選項時，sys.argv 的第一個元素就是在命令行中指定的腳本名稱。

如果腳本名稱直接指向 Python 文件，則把該文件所在目錄加入 sys.path 的開頭，并且把該文件當作 __main__ 模塊來執(zhí)行。

如果腳本名稱指向目錄或 zip 文件，則把腳本名加入 sys.path 的開頭，并把該位置中的 __main__.py 文件當作 __main__ 模塊來執(zhí)行。

-I 選項以隔離模式運行腳本，此模式中，sys.path 既不包含腳本目錄，也不包含用戶的 site-packages 目錄，還會忽略所有 PYTHON* 環(huán)境變量。

使用 filename 參數(shù)會引發(fā) 審計事件 cpython.run_file 。

參見

runpy.run_path()

Python 代碼可以直接使用的等效功能

未給出接口選項時，使用 -i，sys.argv[0] 為空字符串 ("")，并把當前目錄加至 sys.path 的開頭。 此外，如果系統(tǒng)支持，還能自動啟用 tab 補全和歷史編輯（參見 Readline 配置）。

1.1.2. 通用選項?

-??

-h?

--help?

輸出所有命令行選項的簡介。

-V?

--version?

輸出 Python 版本號并退出。示例如下：

Python 3.8.0b2+

輸入兩次 V 選項時，輸出更多構(gòu)建信息，例如：

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

3.6 新版功能: -VV 選項。

1.1.3. 其他選項?

-b?

用 str 與 bytes 或 bytearray 對比， 或?qū)Ρ?bytes 與 int 時，會發(fā)出警告。重復(fù)給出該選項（-bb）時會報錯。

在 3.5 版更改: 影響 bytes 與 int 的比較。

-B?

給出此選項時，Python 不在導(dǎo)入源模塊時寫入 .pyc 文件。另請參閱 PYTHONDONTWRITEBYTECODE。

--check-hash-based-pycs default|always|never?

控制基于哈希值的 .pyc 文件的驗證行為。 參見 已緩存字節(jié)碼的失效。 當設(shè)為 default 時，已選定和未選定的基于哈希值的字節(jié)碼緩存文件將根據(jù)其默認語義進行驗證。 當設(shè)為 always 時，所有基于哈希值的 .pyc 文件，不論是已選定還是未選定的都將根據(jù)其對應(yīng)的源文件進行驗證。 當設(shè)為 never 時，基于哈希值的 .pyc 文件將不會根據(jù)其對應(yīng)的源文件進行驗證。

基于時間戳的 .pyc 文件的語義不會受此選項影響。

-d?

Turn on parser debugging output (for expert only). See also the PYTHONDEBUG environment variable.

This option requires a debug build of Python, otherwise it's ignored.

-E?

忽略所有 PYTHON* 環(huán)境變量，例如，已設(shè)置的 PYTHONPATH 和 PYTHONHOME。

See also the -P and -I (isolated) options.

-i?

腳本是第一個參數(shù)，或使用 -c 時，即便 sys.stdin 不是終端，執(zhí)行腳本或命令后，也會進入交互模式。不讀取 PYTHONSTARTUP 文件。

本選項用于，腳本觸發(fā)異常時，檢查全局變量或堆棧回溯。 詳見 PYTHONINSPECT。

-I?

Run Python in isolated mode. This also implies -E, -P and -s options.

In isolated mode sys.path contains neither the script's directory nor the user's site-packages directory. All PYTHON* environment variables are ignored, too. Further restrictions may be imposed to prevent the user from injecting malicious code.

3.4 新版功能.

-O?

移除 assert 語句以及任何以 __debug__ 的值作為條件的代碼。 通過在 .pyc 擴展名之前添加 .opt-1 來擴充已編譯文件 (bytecode) 的文件名 (參見 PEP 488)。 另請參閱 PYTHONOPTIMIZE。

在 3.5 版更改: 依據(jù) PEP 488 修改 .pyc 文件名。

-OO?

在啟用 -O 的同時丟棄文檔字符串。 通過在 .pyc 擴展名之前添加 .opt-2 來擴展已編譯文件 (bytecode) 的文件名 (參見 PEP 488)。

在 3.5 版更改: 依據(jù) PEP 488 修改 .pyc 文件名。

-P?

Don't prepend a potentially unsafe path to sys.path:

• python -m module command line: Don't prepend the current working directory.

• python script.py command line: Don't prepend the script's directory. If it's a symbolic link, resolve symbolic links.

• python -c code and python (REPL) command lines: Don't prepend an empty string, which means the current working directory.

See also the PYTHONSAFEPATH environment variable, and -E and -I (isolated) options.

3.11 新版功能.

-q?

即使在交互模式下也不顯示版權(quán)和版本信息。

3.2 新版功能.

-R?

開啟哈希隨機化。 此選項權(quán) PYTHONHASHSEED 環(huán)境變量設(shè)置為 0 時起作用，因為哈希隨機化是默認啟用的。

在Python的早期版本中，此選項啟用哈希隨機化，將 str 和 bytes 的對象 __hash__() 的值 "加鹽" 為不可預(yù)測的隨機值。雖然它們在單個Python進程中保持不變，但是在重復(fù)調(diào)用的Python進程之間它們是不可預(yù)測的。

Hash randomization is intended to provide protection against a denial-of-service caused by carefully-chosen inputs that exploit the worst case performance of a dict construction, O(n²) complexity. See http://www.ocert.org/advisories/ocert-2011-003.html for details.

PYTHONHASHSEED 允許你為哈希種子密碼設(shè)置一個固定值。

在 3.7 版更改: 此選項不會再被忽略。

3.2.3 新版功能.

-s?

不要將 用戶 site-packages 目錄 添加到 sys.path。

參見

PEP 370 -- 分用戶的 site-packages 目錄

-S?

禁用 site 的導(dǎo)入及其所附帶的基于站點對 sys.path 的操作。 如果 site 會在稍后被顯式地導(dǎo)入也會禁用這些操作 (如果你希望觸發(fā)它們則應(yīng)調(diào)用 site.main())。

-u?

強制 stdout 和 stderr 流不使用緩沖。 此選項對 stdin 流無影響。

另請參閱 PYTHONUNBUFFERED。

在 3.7 版更改: stdout 和 stderr 流在文本層現(xiàn)在不使用緩沖。

-v?

每次在初始化模塊時會打印一條信息，顯示被加載的地方（文件名或內(nèi)置模塊名）。當給出兩個v（ -vv ）時，搜索模塊時會為每個文件打印一條信息。退出時模塊清理的信息也會給出來。

在 3.10 版更改: 由 site 模塊可以得到將要處理的站點路徑和 .pth 文件。

參閱 PYTHONVERBOSE 。

-W arg?

警告信息的控制。Python 的警告機制默認將警告信息打印到 sys.stderr。

最簡單的設(shè)置是將某個特定操作無條件地應(yīng)用于進程所發(fā)出所有警告 (即使是在默認情況下會忽略的那些警告):

-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

action 名可以根據(jù)需要進行縮寫，解釋器將會解析為合適的名稱。例如，-Wi 與 -Wignore 相同。

完整的參數(shù)如下：

action:message:category:module:lineno

空字段匹配所有值；尾部的空字段可以省略。例如，-W ignore::DeprecationWarning 將忽略所有的 DeprecationWarning 警告。

action 字段如上所述，但只適用于匹配其余字段的警告。

message 字段必須與整個警告信息相匹配；不區(qū)分大小寫。

category 字段與警告類別相匹配（DeprecationWarning 等）。必須是個類名；檢測消息的實際警告類別是否為指定類別的子類。

module 字段匹配的是（完全限定）模塊名；區(qū)分大小寫。

lineno 字段匹配行號，其中 0 匹配所有行號，相當于省略了行號。

可以給出多個 -W 選項；當某條警告信息匹配上多個選項時，將執(zhí)行最后一個匹配項的操作。非法 -W 選項將被忽略（不過，在觸發(fā)第一條警告時，會打印出一條無效選項的警告信息）。

警告信息還可以用 PYTHONWARNINGS 環(huán)境變量來控制，也可以在 Python 程序中用 warnings 模塊進行控制。例如， warnings.filterwarnings() 函數(shù)可對警告信息使用正則表達式。

請參閱 警告過濾器 和 警告過濾器的介紹 了解更多細節(jié)。

-x?

跳過源中第一行，以允許使用非 Unix 形式的 #!cmd。 這適用于 DOS 專屬的破解操作。

-X?

保留用于各種具體實現(xiàn)專屬的選項。 CPython 目前定義了下列可用的值：

• -X faulthandler 啟用 faulthandler；

• -X showrefcount 可在程序結(jié)束時或在交互式解釋器每條語句后，輸出總的引用計數(shù)和使用的內(nèi)存塊數(shù)。這只適用于 調(diào)試版本。

• -X tracemalloc 使用 tracemalloc 模塊啟動對 Python 內(nèi)存分配的跟蹤。 默認情況下，只有最近的幀會保存在跟蹤的回溯信息中。 使用 -X tracemalloc=NFRAME 以啟動限定回溯 NFRAME 幀的跟蹤。 請參閱 tracemalloc.start() 了解詳情。

• -X importtime 顯示每次導(dǎo)入耗費的時間。 它會顯示模塊名稱，累計時間（包括嵌套的導(dǎo)入）和自身時間（排除嵌套的導(dǎo)入）。 請注意它的輸出在多線程應(yīng)用程序中可能會出錯。 典型用法如 python3 -X importtime -c 'import asyncio'。 另請參閱 PYTHONPROFILEIMPORTTIME。

• -X dev: 啟用 Python 開發(fā)模式，引入在默認情況下啟用會導(dǎo)致開銷過大的運行時檢查。

• -X utf8 啟用 Python UTF-8 模式。 -X utf8=0 顯式禁用 Python UTF-8 模式 (即便已自動啟用)。

• -X pycache_prefix=PATH 允許將 .pyc 文件寫入以給定目錄為根的并行樹，而不是代碼樹。另見 PYTHONPYCACHEPREFIX 。

• -X warn_default_encoding issues a EncodingWarning when the locale-specific default encoding is used for opening files. See also PYTHONWARNDEFAULTENCODING.

• -X no_debug_ranges disables the inclusion of the tables mapping extra location information (end line, start column offset and end column offset) to every instruction in code objects. This is useful when smaller code objects and pyc files are desired as well as suppressing the extra visual location indicators when the interpreter displays tracebacks. See also PYTHONNODEBUGRANGES.

• -X frozen_modules determines whether or not frozen modules are ignored by the import machinery. A value of "on" means they get imported and "off" means they are ignored. The default is "on" if this is an installed Python (the normal case). If it's under development (running from the source tree) then the default is "off". Note that the "importlib_bootstrap" and "importlib_bootstrap_external" frozen modules are always used, even if this flag is set to "off".

它還允許傳入任意值并通過 sys._xoptions 字典來提取這些值。

在 3.2 版更改: 增加了 -X 選項。

3.3 新版功能: -X faulthandler 選項。

3.4 新版功能: -X showrefcount 與 -X tracemalloc 選項。

3.6 新版功能: -X showalloccount 選項。

3.7 新版功能: -X importtime, -X dev 與 -X utf8 選項。

3.8 新版功能: -X pycache_prefix 選項。 -X dev 選項現(xiàn)在在 io.IOBase 析構(gòu)函數(shù)中記錄 close() 異常。

在 3.9 版更改: 使用 -X dev 選項，在字符串編碼和解碼操作時檢查 encoding 和 errors 參數(shù)。

The -X showalloccount 選項已被移除。

3.10 新版功能: -X warn_default_encoding 選項。

Deprecated since version 3.9, removed in version 3.10: The -X oldparser option.

3.11 新版功能: The -X no_debug_ranges option.

3.11 新版功能: The -X frozen_modules option.

1.1.4. 不應(yīng)當使用的選項?

-J?

保留給 Jython 使用。

1.2.1. 調(diào)試模式變量?

PYTHONDUMPREFS?

如果設(shè)置，Python在關(guān)閉解釋器，及轉(zhuǎn)儲對象和引用計數(shù)后仍將保持活動。

需用 --with-trace-refs 編譯選項來配置 Python。

PYTHONDUMPREFSFILE=FILENAME?

If set, Python will dump objects and reference counts still alive after shutting down the interpreter into a file called FILENAME.

需用 --with-trace-refs 編譯選項來配置 Python。

3.11 新版功能.