1. 命令行和环境

CPython解释器扫描命令行和环境以进行各种设置。

CPython实现细节:其他实现的命令行方案可能不同。有关更多资源,请参见Alternate Implementations

1.1. Command line

调用Python时,您可以指定以下任何选项:

python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args]

当然,最常见的用例是简单的调用脚本:

python myscript.py

1.1.1. 界面选项

解释器界面类似于 UNIX 外壳,但提供了一些额外的调用方法︰

  • When called with standard input connected to a tty device, it prompts for commands and executes them until an EOF (an end-of-file character, you can produce that with Ctrl-D on UNIX or Ctrl-Z, Enter on Windows) is read.
  • 当使用文件名参数或文件作为标准输入调用时,它从该文件读取并执行脚本。
  • 当使用目录名称参数调用时,它从该目录读取并执行适当命名的脚本。
  • 当使用-c 命令调用时,它会执行作为命令给出的Python语句。这里命令可能包含多个用换行符分隔的语句。前导空白是重要的 Python 语句 !
  • 当使用-m module-name调用时,给定模块位于Python模块路径上,并作为脚本执行。

在非交互式模式下,整个输入在执行前解析。

接口选项终止解释器消耗的选项列表,所有连续的参数将在sys.argv中结束 - 注意第一个元素,下标零(sys.argv[0]),是一个反映程序源代码的字符串。

-c <command>

命令中执行Python代码。命令可以是由换行符分隔的一个或多个语句,其中重要的前导空白与正常模块代码中一样。

如果给出此选项,则sys.argv的第一个元素将为"-c",当前目录将添加到sys.path(允许该目录中的模块作为顶级模块导入)。

-m <module-name>

搜索sys.path命名模块,并将其内容作为__main__模块执行。

由于参数是模块名称,因此您不能给出文件扩展名(.py)。模块名称应为有效的绝对Python模块名称,但实施可能并不总是强制此。它可能允许您使用包含连字符的名称)。

还允许包名称(包括命名空间包)。当提供包名称而不是普通模块时,解释器将执行<pkg>.__main__作为主模块。此行为故意类似于作为脚本参数传递到解释器的目录和zip文件的处理。

注意

此选项不能用于以C编写的内建模块和扩展模块,因为它们没有Python模块文件。但是,它仍然可以用于预编译的模块,即使原始源文件不可用。

如果给出此选项,则sys.argv的第一个元素将是模块文件的完整路径(在定位模块文件时,第一个元素将设置为"-m")。-c选项一样,当前目录将添加到sys.path的开头。

许多标准库模块包含在作为脚本执行时调用的代码。一个例子是 timeit 模块:

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

也可以看看

runpy.run_module()
等价的功能直接可用于Python代码

PEP 338 - 将模块作为脚本执行

在版本3.1中已更改:提供软件包名称以运行__main__子模块。

更改了版本3.4:命名空间包也受支持

-

从标准输入(sys.stdin)读取命令。如果标准输入是终端,则暗示为-i

如果给出此选项,则sys.argv的第一个元素将为"-",并且当前目录将添加到sys.path

<script>

执行脚本中包含的Python代码,它必须是指向Python文件,包含__main__.py文件的目录的文件系统路径(绝对或相对)包含__main__.py文件的zip文件。

如果给出此选项,则sys.argv的第一个元素将是在命令行上给定的脚本名称。

如果脚本名称直接指向Python文件,则包含该文件的目录将添加到sys.path的开头,该文件将作为__main__模块执行。

如果脚本名称指向目录或zip文件,则脚本名称将添加到sys.path的开头,并且该位置中的__main__.py文件将作为__main__模块。

也可以看看

runpy.run_path()
等价的功能直接可用于Python代码

如果未给出接口选项,则暗示-isys.argv[0]是空字符串(""),目录将被添加到sys.path的开始。此外,如果您的平台上可用,则会自动启用制表符完成和历史记录编辑(请参阅Readline configuration)。

在版本3.4中更改:自动启用制表符完成和历史记录编辑。

1.1.2. 通用选项

-?
-h
--help

打印所有命令行选项的简短描述。

-V
--version

打印Python版本号并退出。示例输出可以是:

Python 3.0

1.1.3. 杂项选项

-b

在比较bytesbytearraystrbytesint时发出警告。在给出选项两次(-bb)时发出错误。

在版本3.5中更改:影响bytesint的比较。

-B

如果给定,Python将不会尝试在导入源模块时写入.pyc文件。另见 PYTHONDONTWRITEBYTECODE

-d

打开解析器调试输出(仅适用于向导,具体取决于编译选项)。另见 PYTHONDEBUG

-E

忽略所有 PYTHON*环境变量,例如 PYTHONPATH PYTHONHOME

-i

当脚本作为第一个参数传递或使用-c选项时,即使sys.stdin未出现,也会在执行脚本或命令后进入交互模式是终端。未读取 PYTHONSTARTUP文件。

当脚本引发异常时,这可用于检查全局变量或堆栈跟踪。另见 PYTHONINSPECT

-I

在隔离模式下运行Python。这也意味着-E和-s。在隔离模式下,sys.path既不包含脚本的目录也不包含用户的site-packages目录。所有 PYTHON*环境变量也被忽略。可以施加进一步的限制以防止用户注入恶意代码。

版本3.4中的新功能。

-O

打开基本优化。这会将已编译(bytecode)文件的文件扩展名从.pyc更改为.pyo另见 PYTHONOPTIMIZE

-OO

除了-O优化之外,还要舍弃文档字符串。

-q

即使在交互模式下也不显示版权和版本消息。

版本3.2中的新功能。

-R

保持兼容性。在 Python 3.3 和以后版本,默认情况下打开哈希随机化。

在以前的Python版本中,此选项打开哈希随机化,以使得str,bytes和datetime的__hash__()值被“salted”,具有不可预测的随机值。虽然它们在单个Python进程中保持不变,但是在重复调用Python之前是不可预测的。

哈希随机化旨在提供保护以防止由仔细选择的输入引起的拒绝服务,该输入利用字符构造的最坏情况性能O(n ^ 2)复杂度。有关详情,请参阅http://www.ocert.org/advisories/ocert-2011-003.html

PYTHONHASHSEED允许您为散列种子密码设置固定值。

版本3.2.3中的新功能。

-s

不要将user site-packages directory添加到sys.path

也可以看看

PEP 370 - 每个用户site-packages目录

-S

停用导入模块site以及与之相关的sys.path的站点相关操作。如果稍后显式导入site,请禁用这些操作(如果您希望触发它们,请调用site.main())。

-u

强制stdout和stderr流(它们作为buffer属性可用)的二进制层是无缓冲的。如果写入控制台,文本I / O层仍将进行行缓冲,如果重定向到非交互式文件,则文本I / O层仍然是块缓冲。

另见 PYTHONUNBUFFERED

-v

每次模块初始化时打印一条消息,显示从中加载模块的位置(文件名或内建模块)。当给出两次(-vv)时,为搜索模块时检查的每个文件打印一条消息。还提供退出时模块清理的信息。另请参阅 PYTHONVERBOSE

-W arg

警告控制。Python的警告机制默认向sys.stderr打印警告消息。典型的警告消息具有以下形式:

file:line: category: message

默认情况下,每个警告对于其发生的每个源行打印一次。此选项控制打印警告的频率。

可以给出多个-W选项;当警告匹配多个选项时,将执行上一个匹配选项的操作。无效的-W选项被忽略(但是,当发出第一个警告时,将打印有关无效选项的警告消息)。

警告也可以使用warnings模块从Python程序中进行控制。

参数的最简单形式是以下操作字符串之一(或唯一的缩写):

ignore
忽略所有警告。
default
显式请求默认行为(每个源行打印一次警告)。
all
在每次发生时打印警告(如果对同一源行重复触发警告,例如在循环内,可能会生成许多消息)。
module
仅在每个模块第一次出现时打印每个警告。
once
仅在程序第一次出现时打印每个警告。
error
引发异常而不是打印警告消息。

参数的完整形式是:

action:message:category:module:line

这里,操作如上所述,但仅适用于与剩余字段匹配的邮件。空字段匹配所有值;可以省略拖尾空字段。消息字段与打印的警告消息的开始相匹配;此匹配不区分大小写。类别字段与警告类别匹配。这必须是类名;该匹配测试消息的实际警告类别是否是指定警告类别的子类。必须给出完整的类名。模块字段与(完全限定)模块名称匹配;此匹配区分大小写。字段与行号匹配,其中零匹配所有行号,因此等效于省略的行号。

也可以看看

warnings - 警告模块

PEP 230 - 警告框架

PYTHONWARNINGS

-x

跳过源代码的第一行,允许使用#!cmd的非Unix形式。这只适用于DOS特定的黑客。

注意

错误消息中的行号将关闭一。

-X

保留用于各种实现特定的选项。CPython目前定义了以下可能的值:

  • -X faulthandler启用faulthandler
  • -X showrefcount启用总引用计数和内存块的输出(仅适用于调试版本);
  • -X tracemalloc使用tracemalloc模块开始跟踪Python内存分配。默认情况下,只有最近的帧存储在跟踪的追踪中。Use -X tracemalloc=NFRAME to start tracing with a traceback limit of NFRAME frames. 有关详细信息,请参阅tracemalloc.start()

它还允许传递任意值并通过sys._xoptions字典检索它们。

在版本3.2中更改:现在允许使用CPython传递-X

版本3.3中的新功能: -X faulthandler选项。

新版本3.4: -X showrefcount-X tracemalloc选项。

1.1.4. Options you shouldn’t use

-J

保留供Jython使用。

1.2. 环境变量

这些环境变量影响Python的行为,它们在除了-E或-I之外的命令行开关之前被处理。通常,命令行开关覆盖存在冲突的环境变量。

PYTHONHOME

更改标准Python库的位置。By default, the libraries are searched in prefix/lib/pythonversion and exec_prefix/lib/pythonversion, where prefix and exec_prefix are installation-dependent directories, both defaulting to /usr/local.

PYTHONHOME设置为单个目录时,其值将替换prefixexec_prefix要为这些值指定不同的值,请将 PYTHONHOME设置为prefix exec_prefix

PYTHONPATH

扩充模块文件的默认搜索路径。格式与shell的 PATH相同:os.pathsep分隔的一个或多个目录路径名称Unix上的冒号或Windows上的分号)。默认忽略不存在的目录。

除了正常目录,单个 PYTHONPATH条目可以指包含纯Python模块(源或编译形式)的zip文件。无法从zip文件导入扩展模块。

The default search path is installation dependent, but generally begins with prefix/lib/pythonversion (see PYTHONHOME above). 总是附加到 PYTHONPATH

将在Interface options之前的 PYTHONPATH之前的搜索路径中插入一个附加目录。搜索路径可以在Python程序中作为变量sys.path进行操作。

PYTHONSTARTUP

如果这是可读文件的名称,则在交互式模式下显示第一个提示之前,将执行该文件中的Python命令。该文件在执行交互式命令的同一命名空间中执行,使得在其中定义或导入的对象可以在交互式会话中无限制地使用。您还可以更改此文件中的提示sys.ps1sys.ps2和钩子sys.__interactivehook__

PYTHONOPTIMIZE

如果设置为非空字符串,则等效于指定-O选项。如果设置为整数,则相当于多次指定-O

PYTHONDEBUG

如果将其设置为非空字符串,则等效于指定-d选项。如果设置为整数,则等效于多次指定-d

PYTHONINSPECT

如果设置为非空字符串,则等效于指定-i选项。

此变量也可以通过Python代码使用os.environ修改,以在程序终止时强制检查模式。

PYTHONUNBUFFERED

如果设置为非空字符串,则等效于指定-u选项。

PYTHONVERBOSE

如果设置为非空字符串,则等效于指定-v选项。如果设置为整数,则等效于多次指定-v

PYTHONCASEOK

如果设置了此项,Python会忽略import语句中的大小写。这只适用于Windows和操作系统X.

PYTHONDONTWRITEBYTECODE

如果设置为非空字符串,Python将不会尝试在导入源模块时写入.pyc.pyo文件。这相当于指定-B选项。

PYTHONHASHSEED

如果此变量未设置或设置为random,则使用随机值对str,bytes和datetime对象的散列进行种子。

如果 PYTHONHASHSEED设置为整数值,则将其用作用于生成散列随机化覆盖的类型的hash()的固定种子。

它的目的是允许可重复的哈希,例如用于解释器本身的selftest,或允许一群python进程共享哈希值。

整数必须是范围[0,4294967295]中的十进制数。指定值0将禁用哈希随机化。

版本3.2.3中的新功能。

PYTHONIOENCODING

如果在运行解释器之前设置它,它将在语法encodingname:errorhandler中覆盖用于stdin / stdout / stderr的编码。encodingname:errorhandler部分都是可选的,并且具有与str.encode()中相同的含义。

对于stderr,:errorhandler部分被忽略;处理程序将始终为'backslashreplace'

在版本3.4中更改: encodingname部分现在是可选的。

PYTHONNOUSERSITE

如果设置此选项,Python不会将user site-packages directory添加到sys.path

也可以看看

PEP 370 - 每个用户site-packages目录

PYTHONUSERBASE

Defines the user base directory, which is used to compute the path of the user site-packages directory and Distutils installation paths for python setup.py install --user.

也可以看看

PEP 370 - 每个用户site-packages目录

PYTHONEXECUTABLE

如果设置了此环境变量,则sys.argv[0]将设置为其值,而不是通过C运行时获得的值。仅适用于Mac OS X。

PYTHONWARNINGS

这相当于-W选项。如果设置为逗号分隔字符串,则相当于多次指定-W

PYTHONFAULTHANDLER

If this environment variable is set to a non-empty string, faulthandler.enable() is called at startup: install a handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals to dump the Python traceback. 这相当于-X faulthandler选项。

版本3.3中的新功能。

PYTHONTRACEMALLOC

如果此环境变量设置为非空字符串,请使用tracemalloc模块开始跟踪Python内存分配。变量的值是存储在跟踪的追踪中的最大帧数。例如,PYTHONTRACEMALLOC=1只存储最近的帧。有关详细信息,请参阅tracemalloc.start()

版本3.4中的新功能。

PYTHONASYNCIODEBUG

如果此环境变量设置为非空字符串,请启用asyncio模块的debug mode

版本3.4中的新功能。

1.2.1. Debug-mode variables

设置这些变量只会对Python的调试版本产生影响,也就是说,如果Python配置了--with-pydebug构建选项。

PYTHONTHREADDEBUG

如果设置,Python将打印线程调试信息。

PYTHONDUMPREFS

如果设置,Python将关闭解释器后转储对象和引用计数仍然活着。

PYTHONMALLOCSTATS

如果设置,Python将在每次创建新的对象竞技场时以及关闭时打印内存分配统计信息。