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

1.1.1. 接口選項(xiàng)?

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

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

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

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

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

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

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

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

-c <command>?

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

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

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

-m <module-name>?

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

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

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

備注

此選項(xiàng)不適用于內(nèi)置模塊和以 C 編寫的擴(kuò)展模塊，因?yàn)樗鼈儾]有對(duì)應(yīng)的 Python 模塊文件。 但是它仍然適用于預(yù)編譯的模塊，即使沒有可用的初始源文件。

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

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

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

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

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

參見

runpy.run_module()

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

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

在 3.1 版更改: 提供包名稱來運(yùn)行 __main__ 子模塊。

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

-

從標(biāo)準(zhǔn)輸入 (sys.stdin) 讀取命令。標(biāo)準(zhǔn)輸入為終端時(shí)，使用 -i。

使用此選項(xiàng)時(shí)，sys.argv 的第一個(gè)元素是 "-"， 同時(shí)，把當(dāng)前目錄加入 sys.path 開頭。

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

<script>

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

給出此選項(xiàng)時(shí)，sys.argv 的第一個(gè)元素就是在命令行中指定的腳本名稱。

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

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

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

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

參見

runpy.run_path()

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

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

1.1.2. 通用選項(xiàng)?

-??

-h?

--help?

輸出所有命令行選項(xiàng)的簡(jiǎn)介。

-V?

--version?

輸出 Python 版本號(hào)并退出。示例如下：

Python 3.8.0b2+

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

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

3.6 新版功能: -VV 選項(xiàng)。

1.1.3. 其他選項(xiàng)?

-b?

用 str 與 bytes 或 bytearray 對(duì)比， 或?qū)Ρ?bytes 與 int 時(shí)，會(huì)發(fā)出警告。重復(fù)給出該選項(xiàng)（-bb）時(shí)會(huì)報(bào)錯(cuò)。

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

-B?

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

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

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

基于時(shí)間戳的 .pyc 文件的語(yǔ)義不會(huì)受此選項(xiàng)影響。

-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?

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

本選項(xiàng)用于，腳本觸發(fā)異常時(shí)，檢查全局變量或堆?；厮荨?詳見 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 語(yǔ)句以及任何以 __debug__ 的值作為條件的代碼。 通過在 .pyc 擴(kuò)展名之前添加 .opt-1 來擴(kuò)充已編譯文件 (bytecode) 的文件名 (參見 PEP 488)。 另請(qǐng)參閱 PYTHONOPTIMIZE。

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

-OO?

在啟用 -O 的同時(shí)丟棄文檔字符串。 通過在 .pyc 擴(kuò)展名之前添加 .opt-2 來擴(kuò)展已編譯文件 (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?

開啟哈希隨機(jī)化。 此選項(xiàng)權(quán) PYTHONHASHSEED 環(huán)境變量設(shè)置為 0 時(shí)起作用，因?yàn)楣ｋS機(jī)化是默認(rèn)啟用的。

在Python的早期版本中，此選項(xiàng)啟用哈希隨機(jī)化，將 str 和 bytes 的對(duì)象 __hash__() 的值 "加鹽" 為不可預(yù)測(cè)的隨機(jī)值。雖然它們?cè)趩蝹€(gè)Python進(jìn)程中保持不變，但是在重復(fù)調(diào)用的Python進(jìn)程之間它們是不可預(yù)測(cè)的。

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è)置一個(gè)固定值。

在 3.7 版更改: 此選項(xiàng)不會(huì)再被忽略。

3.2.3 新版功能.

-s?

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

參見

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

-S?

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

-u?

強(qiáng)制 stdout 和 stderr 流不使用緩沖。 此選項(xiàng)對(duì) stdin 流無影響。

另請(qǐng)參閱 PYTHONUNBUFFERED。

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

-v?

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

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

參閱 PYTHONVERBOSE 。

-W arg?

警告信息的控制。Python 的警告機(jī)制默認(rèn)將警告信息打印到 sys.stderr。

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

-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ù)需要進(jìn)行縮寫，解釋器將會(huì)解析為合適的名稱。例如，-Wi 與 -Wignore 相同。

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

action:message:category:module:lineno

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

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

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

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

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

lineno 字段匹配行號(hào)，其中 0 匹配所有行號(hào)，相當(dāng)于省略了行號(hào)。

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

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

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

-x?

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

-X?

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

• -X faulthandler 啟用 faulthandler；

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

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

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

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

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

• -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 選項(xiàng)。

3.3 新版功能: -X faulthandler 選項(xiàng)。

3.4 新版功能: -X showrefcount 與 -X tracemalloc 選項(xiàng)。

3.6 新版功能: -X showalloccount 選項(xiàng)。

3.7 新版功能: -X importtime, -X dev 與 -X utf8 選項(xiàng)。

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

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

The -X showalloccount 選項(xiàng)已被移除。

3.10 新版功能: -X warn_default_encoding 選項(xiàng)。

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)當(dāng)使用的選項(xiàng)?

-J?

保留給 Jython 使用。

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

PYTHONDUMPREFS?

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

需用 --with-trace-refs 編譯選項(xiàng)來配置 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 編譯選項(xiàng)來配置 Python。

3.11 新版功能.