1. 命令行和环境¶
cpython解释器扫描命令行和环境中的各种设置。
CPython implementation detail: 其他实现的命令行方案可能不同。见 其他实现 获取更多资源。
1.1. 命令行¶
调用python时,可以指定以下任何选项:
python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args]
当然,最常见的用例是对脚本的简单调用:
python myscript.py
1.1.1. 接口选项¶
解释器接口类似于unix shell,但提供了一些额外的调用方法:
当使用连接到tty设备的标准输入调用时,它会提示输入命令并执行这些命令,直到出现EOF(文件结束字符),您可以使用 Ctrl-D 关于UNIX或 Ctrl-Z, Enter 在Windows上)被读取。
当使用文件名参数或文件作为标准输入调用时,它从该文件读取并执行脚本。
当使用directory name参数调用时,它从该目录读取并执行一个适当命名的脚本。
当与调用时
-c command
,它执行以下给定的python语句: 命令 . 在这里 命令 可以包含多个用换行符分隔的语句。前面的空白在python语句中非常重要!当与调用时
-m module-name
,给定的模块位于python模块路径上,并作为脚本执行。
在非交互模式下,在执行整个输入之前对其进行分析。
接口选项终止解释器使用的选项列表,所有连续参数将以 sys.argv
--注意第一个元素,下标零 (sys.argv[0]
)是反映程序源的字符串。
- -c <command>¶
在中执行python代码 命令 . 命令 可以是用换行符分隔的一个或多个语句,其前导空格与正常模块代码中的空格相同。
如果给定此选项,则
sys.argv
将"-c"
当前目录将添加到sys.path
(允许将该目录中的模块作为顶级模块导入)。提出一个 auditing event
cpython.run_command
带着论证command
.
- -m <module-name>¶
搜索
sys.path
并将其内容作为__main__
模块。因为参数是 模块 名称,不能提供文件扩展名 (
.py
)模块名应该是一个有效的绝对Python模块名,但实现可能并不总是强制执行该名称(例如,它可能允许您使用包含连字符的名称)。也允许使用包名称(包括命名空间包)。当提供包名而不是普通模块时,解释器将执行
<pkg>.__main__
作为主模块。这种行为故意类似于处理作为脚本参数传递给解释器的目录和zipfile。注解
此选项不能用于用C编写的内置模块和扩展模块,因为它们没有python模块文件。但是,即使原始源文件不可用,它仍然可以用于预编译模块。
如果给定此选项,则
sys.argv
将是模块文件的完整路径(当模块文件被定位时,第一个元素将被设置为"-m"
)如同-c
选项,当前目录将添加到sys.path
.-I
选项可用于在独立模式下运行脚本,其中sys.path
既不包含当前目录,也不包含用户的网站包目录。全部PYTHON*
环境变量也被忽略。许多标准库模块包含在执行时作为脚本调用的代码。一个例子是
timeit
模块:python -m timeit -s 'setup here' 'benchmarked code here' python -m timeit -h # for details
提出一个 auditing event
cpython.run_module
带着论证module-name
.在 3.1 版更改: 提供要运行的包名称
__main__
子模块。在 3.4 版更改: 也支持命名空间包
- -
从标准输入读取命令 (
sys.stdin
)。如果标准输入是终端,-i
是隐含的。如果给定此选项,则
sys.argv
将"-"
当前目录将添加到sys.path
.提出一个 auditing event
cpython.run_stdin
没有参数。
- <script>
执行中包含的python代码 脚本 ,它必须是文件系统路径(绝对或相对),引用python文件,包含
__main__.py
文件,或包含__main__.py
文件。如果给定此选项,则
sys.argv
将是命令行上给定的脚本名称。如果脚本名直接引用Python文件,则包含该文件的目录将添加到
sys.path
,文件作为__main__
模块。如果脚本名引用目录或zip文件,则脚本名将添加到
sys.path
以及__main__.py
该位置中的文件作为__main__
模块。-I
选项可用于在独立模式下运行脚本,其中sys.path
既不包含脚本的目录,也不包含用户的站点包目录。所有PYTHON*
环境变量也被忽略。提出一个 auditing event
cpython.run_file
带着论证filename
.参见
runpy.run_path()
可直接用于python代码的等效功能
如果没有提供接口选项, -i
暗示, sys.argv[0]
是空字符串 (""
)当前目录将添加到 sys.path
. 此外,如果在您的平台上可用,则会自动启用选项卡完成和历史记录编辑(请参见 读线配置 )
参见
在 3.4 版更改: 自动启用选项卡完成和历史编辑。
1.1.2. 通用选项¶
1.1.3. 其他选项¶
- -B¶
如果给定,python不会尝试写入
.pyc
导入源模块时的文件。也见PYTHONDONTWRITEBYTECODE
.
- --check-hash-based-pycs default|always|never¶
控制基于hash的验证行为
.pyc
文件夹。见 缓存字节码无效 . 当设置为default
检查和未检查的基于hash的字节码缓存文件将根据其默认语义进行验证。当设置为always
,所有基于hash的.pyc
文件,无论是选中还是未选中,都将根据其对应的源文件进行验证。当设置为never
基于hash的.pyc
没有根据相应的源文件验证文件。基于时间戳的语义
.pyc
文件不受此选项的影响。
- -d¶
打开解析器调试输出(仅适用于专家,具体取决于编译选项)。也见
PYTHONDEBUG
.
- -E¶
忽略所有
PYTHON*
环境变量,例如PYTHONPATH
和PYTHONHOME
,可以设置。
- -i¶
当脚本作为第一个参数或
-c
使用选项,在执行脚本或命令后进入交互模式,即使在sys.stdin
似乎不是终端。这个PYTHONSTARTUP
未读取文件。这对于在脚本引发异常时检查全局变量或堆栈跟踪很有用。也见
PYTHONINSPECT
.
- -I¶
以隔离模式运行python。这也意味着孤立模式下的-e和-s。
sys.path
既不包含脚本的目录,也不包含用户的站点包目录。所有PYTHON*
环境变量也被忽略。可能会施加进一步的限制,以防止用户注入恶意代码。3.4 新版功能.
- -O¶
移除assert语句和任何以值为条件的代码
__debug__
. 为编译文件增加文件名 (bytecode )通过添加.opt-1
之前.pyc
延伸部分(参见 PEP 488 )也见PYTHONOPTIMIZE
.在 3.5 版更改: 修改
.pyc
文件名依据 PEP 488 .
- -OO¶
做
-O
并丢弃docstring。为编译文件增加文件名 (bytecode )通过添加.opt-2
之前.pyc
延伸部分(参见 PEP 488 )在 3.5 版更改: 修改
.pyc
文件名依据 PEP 488 .
- -q¶
即使在交互模式下也不显示版权和版本消息。
3.2 新版功能.
- -R¶
启用hash随机化。只有当
PYTHONHASHSEED
环境变量设置为0
,因为默认情况下已启用hash随机化。在以前的Python版本中,此选项启用哈希随机化,以便
__hash__()
str和bytes对象的值是用一个不可预测的随机值“转换”的。尽管它们在一个单独的Python进程中保持不变,但是在重复调用Python之间它们是不可预测的。hash随机化是为了防止由于精心选择的输入而导致的拒绝服务,这些输入利用了dict构造的最坏情况性能,即O(n^2)复杂性。有关详细信息,请参阅http://www.ocert.org/advisories/ocert-2011-003.html。
PYTHONHASHSEED
允许您设置hash种子机密的固定值。在 3.7 版更改: 该选项不再被忽略。
3.2.3 新版功能.
- -s¶
不要添加
user site-packages directory
到sys.path
.参见
PEP 370 --每用户站点包目录
- -S¶
禁用模块导入
site
以及sys.path
这是必然的。如果site
稍后显式导入(调用site.main()
如果你想触发它们)。
- -u¶
强制取消缓冲stdout和stderr流。此选项对stdin流没有影响。
也见
PYTHONUNBUFFERED
.在 3.7 版更改: stdout和stderr流的文本层现在已取消缓冲。
- -v¶
每次初始化模块时打印一条消息,显示从中加载模块的位置(文件名或内置模块)。当给予两次 (
-vv
),为搜索模块时检查的每个文件打印消息。还提供了有关在退出时清除模块的信息。在 3.10 版更改: 这个
site
模块报告特定于站点的路径和.pth
正在处理的文件。也见
PYTHONVERBOSE
.
- -W arg¶
警告控制。默认情况下,python的警告机制将警告消息打印到
sys.stderr
. 典型警告消息的格式如下:file:line: category: message
默认情况下,每个警告对于其发生的每一个源行打印一次。此选项控制打印警告的频率。
倍数
-W
可以提供选项;当警告与多个选项匹配时,将执行最后一个匹配选项的操作。无效-W
选项被忽略(但是,当发出第一个警告时,会打印一条关于无效选项的警告消息)。也可以使用
PYTHONWARNINGS
环境变量和来自使用warnings
模块。最简单的设置无条件地将特定操作应用于进程发出的所有警告(即使默认情况下忽略的警告)::
-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
操作名称可以根据需要缩写(例如
-Wi
,-Wd
,-Wa
,-We
)解释器将它们解析为适当的操作名。
- -x¶
跳过源代码的第一行,允许使用
#!cmd
. 这仅适用于DOS特定的黑客。
- -X¶
为各种特定于实现的选项保留。cpython当前定义了以下可能的值:
-X faulthandler
使能faulthandler
;-X showrefcount
当程序完成时或在交互解释器中的每个语句之后输出总引用计数和已用内存块的数目。这只适用于调试版本。-X tracemalloc
要开始跟踪python内存分配,请使用tracemalloc
模块。默认情况下,只有最新的帧存储在跟踪的跟踪中。使用-X tracemalloc=NFRAME
开始跟踪的回溯限制为 NFRAME 框架。查看tracemalloc.start()
更多信息。-X importtime
显示每次导入需要多长时间。它显示模块名称、累计时间(包括嵌套导入)和自时间(不包括嵌套导入)。请注意,在多线程应用程序中,它的输出可能会中断。典型用法是python3 -X importtime -c 'import asyncio'
.另请参见PYTHONPROFILEIMPORTTIME
.-X dev
:启用 Python Development Mode ,引入额外的运行时检查,这些检查成本太高,无法默认启用。-X utf8
启用 Python UTF-8 Mode 。-X utf8=0
显式禁用 Python UTF-8 Mode (即使它本来会自动激活)。-X pycache_prefix=PATH
启用写入.pyc
文件的根目录是给定目录,而不是代码树。也见PYTHONPYCACHEPREFIX
.
它还允许传递任意值并通过
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
close()
io.IOBase
在 3.9 版更改: 使用
-X dev
选项,检查 编码 和 错误 字符串编码和解码操作的参数。这个
-X showalloccount
选项已被删除。Deprecated since version 3.9, removed in version 3.10: 这个
-X oldparser
选择权。
1.1.4. 你不应该使用的选项¶
1.2. 环境变量¶
这些环境变量会影响python的行为,它们在命令行开关(而不是-e或-i)之前进行处理。通常情况下,命令行开关会在发生冲突时覆盖环境变量。
- PYTHONHOME¶
更改标准python库的位置。默认情况下,在
{prefix}/lib/python{version}
和{exec_prefix}/lib/python{version}
在哪里{prefix}
和{exec_prefix}
是安装相关目录,都默认为/usr/local
.什么时候?
PYTHONHOME
设置为单个目录,其值将同时替换两个目录{prefix}
和{exec_prefix}
. 要为这些指定不同的值,请设置PYTHONHOME
到{prefix}:{exec_prefix}
.
- PYTHONPATH¶
增加模块文件的默认搜索路径。格式与shell的相同
PATH
:一个或多个目录路径名,由分隔os.pathsep
(例如Unix上的冒号或Windows上的分号)。不存在的目录将被静默忽略。除了普通目录,个人
PYTHONPATH
条目可以引用包含纯python模块的zipfiles(以源代码或编译格式)。扩展模块不能从zipfiles导入。默认搜索路径取决于安装,但通常以
{prefix}/lib/python{version}
(见PYTHONHOME
以上)。它是 总是 追加到PYTHONPATH
.将在前面的搜索路径中插入一个附加目录
PYTHONPATH
如上所述 接口选项 . 搜索路径可以在python程序中作为变量进行操作。sys.path
.
- PYTHONPLATLIBDIR¶
如果设置为非空字符串,它将重写
sys.platlibdir
价值。3.9 新版功能.
- PYTHONSTARTUP¶
如果这是可读文件的名称,则在交互模式下显示第一个提示之前,将执行该文件中的python命令。该文件在执行交互命令的同一命名空间中执行,以便在交互会话中无需限定即可使用其中定义或导入的对象。您还可以更改提示
sys.ps1
和sys.ps2
钩子sys.__interactivehook__
在此文件中。提出一个 auditing event
cpython.run_startup
带着论证filename
.
- PYTHONBREAKPOINT¶
如果设置了该选项,则使用点路径表示法命名可调用文件。将导入包含可调用的模块,然后按默认实现运行可调用
sys.breakpointhook()
它本身是由内置的breakpoint()
.如果未设置或设置为空字符串,则等于值“pdb.set_trace”。将其设置为字符串“0”将导致sys.breakpointhook()
什么都不做,只是马上回来。3.7 新版功能.
- PYTHONINSPECT¶
如果将其设置为非空字符串,则相当于指定
-i
选择权。也可以使用python代码修改此变量
os.environ
在程序终止时强制检查模式。
- PYTHONPYCACHEPREFIX¶
如果设置了此选项,python将写入
.pyc
位于此路径的镜像目录树中的文件,而不是位于__pycache__
源码树中的目录。这相当于指定-X
pycache_prefix=PATH
选择权。3.8 新版功能.
- PYTHONHASHSEED¶
如果此变量未设置或设置为
random
,随机值用于为str和bytes对象的散列种子。如果
PYTHONHASHSEED
设置为整数值,它用作生成hash随机化所覆盖类型的hash()的固定种子。它的目的是允许可重复的散列,例如对解释器本身进行自测,或者允许一组Python进程共享散列值。
整数必须是范围内的十进制数 [04294967295] . 指定值0将禁用hash随机化。
3.2.3 新版功能.
- PYTHONIOENCODING¶
如果在运行解释器之前设置了这个值,它将在语法中重写stdin/stdout/stderr使用的编码。
encodingname:errorhandler
. 两个encodingname
以及:errorhandler
零件是可选的,具有与中相同的含义str.encode()
.对于STDRR,
:errorhandler
忽略部分;处理程序将始终'backslashreplace'
.在 3.4 版更改: 这个
encodingname
零件现在是可选的。在 3.6 版更改: 在Windows上,此变量指定的编码对于交互式控制台缓冲区将被忽略,除非
PYTHONLEGACYWINDOWSSTDIO
也被指定。通过标准流重定向的文件和管道不受影响。
- PYTHONNOUSERSITE¶
如果设置了此选项,python将不会添加
user site-packages directory
到sys.path
.参见
PEP 370 --每用户站点包目录
- PYTHONUSERBASE¶
定义
user base directory
,用于计算user site-packages directory
和 Distutils installation paths 对于python setup.py install --user
.参见
PEP 370 --每用户站点包目录
- PYTHONEXECUTABLE¶
如果设置了此环境变量,
sys.argv[0]
将被设置为其值,而不是通过C运行时获得的值。仅适用于Mac OS X。
- PYTHONWARNINGS¶
这相当于
-W
选择权。如果设置为逗号分隔的字符串,则相当于指定-W
多次,列表后面的过滤器优先于列表前面的过滤器。最简单的设置无条件地将特定操作应用于进程发出的所有警告(即使默认情况下忽略的警告)::
PYTHONWARNINGS=default # Warn once per call location PYTHONWARNINGS=error # Convert to exceptions PYTHONWARNINGS=always # Warn every time PYTHONWARNINGS=module # Warn once per calling module PYTHONWARNINGS=once # Warn once per Python process PYTHONWARNINGS=ignore # Never warn
- PYTHONFAULTHANDLER¶
如果此环境变量设置为非空字符串,
faulthandler.enable()
在启动时调用:为安装处理程序SIGSEGV
,SIGFPE
,SIGABRT
,SIGBUS
和SIGILL
用于转储python跟踪的信号。这相当于-X
faulthandler
选择权。3.3 新版功能.
- PYTHONTRACEMALLOC¶
如果此环境变量设置为非空字符串,请使用
tracemalloc
模块。变量的值是记录道回溯中存储的最大帧数。例如,PYTHONTRACEMALLOC=1
仅存储最近的帧。见tracemalloc.start()
更多信息。3.4 新版功能.
- PYTHONPROFILEIMPORTTIME¶
如果将此环境变量设置为非空字符串,则python将显示每次导入所需的时间。这完全等同于设置
-X importtime
在命令行上。3.7 新版功能.
- PYTHONASYNCIODEBUG¶
如果此环境变量设置为非空字符串,请启用 debug mode 的
asyncio
模块。3.4 新版功能.
- PYTHONMALLOC¶
设置python内存分配器和/或安装调试挂钩。
设置python使用的内存分配器系列:
default
使用 default memory allocators .malloc
使用malloc()
所有域的C库函数 (PYMEM_DOMAIN_RAW
,PYMEM_DOMAIN_MEM
,PYMEM_DOMAIN_OBJ
)pymalloc
使用 pymalloc allocator 对于PYMEM_DOMAIN_MEM
和PYMEM_DOMAIN_OBJ
域和使用malloc()
功能PYMEM_DOMAIN_RAW
领域。
安装调试挂钩:
debug
:在 default memory allocators .malloc_debug
一样malloc
但也要安装调试挂钩。pymalloc_debug
一样pymalloc
但也要安装调试挂钩。
见 default memory allocators 以及
PyMem_SetupDebugHooks()
函数(在python内存分配器上安装调试挂钩)。在 3.7 版更改: 增加了
"default"
分配器。3.6 新版功能.
- PYTHONMALLOCSTATS¶
如果设置为非空字符串,python将打印 pymalloc memory allocator 每次创建新的PymalLoc对象竞技场时,以及关闭时。
如果
PYTHONMALLOC
环境变量用于强制malloc()
C库的分配器,或者如果在没有pymalloc
支持。在 3.6 版更改: 这个变量现在也可以在以发布模式编译的Python上使用。如果设置为空字符串,则现在没有效果。
- PYTHONLEGACYWINDOWSFSENCODING¶
如果设置为非空字符串,则默认为 filesystem encoding and error handler 模式将分别恢复到其3.6版本之前的值‘MBCS’和‘REPLACE’。否则,将使用新的默认值‘utf-8’和‘surogue atepass’。
也可以在运行时使用
sys._enablelegacywindowsfsencoding()
.Availability :Windows。
3.6 新版功能: 见 PEP 529 了解更多详细信息。
- PYTHONLEGACYWINDOWSSTDIO¶
如果设置为非空字符串,则不使用新的控制台读写器。这意味着Unicode字符将根据活动控制台代码页进行编码,而不是使用UTF-8。
如果标准流被重定向(到文件或管道),而不是引用控制台缓冲区,则忽略此变量。
Availability :Windows。
3.6 新版功能.
- PYTHONCOERCECLOCALE¶
如果设置为值
0
,使主python命令行应用程序跳过将基于ASCII的C和POSIX区域设置强制为更强大的基于UTF-8的替代方案。如果这个变量是 not 设置(或设置为除
0
)LC_ALL
也未设置locale override环境变量,并且为LC_CTYPE
类别不是默认的C
区域设置,否则显式基于ASCIIPOSIX
然后,python cli将尝试为LC_CTYPE
按照加载解释器运行时之前列出的顺序分类:C.UTF-8
C.utf8
UTF-8
如果设置这些区域设置类别之一成功,则
LC_CTYPE
在初始化python运行时之前,还将在当前流程环境中相应地设置环境变量。这确保了除了被解释器本身和运行在同一进程中的其他支持区域设置的组件(如GNU)看到之外readline
在子进程(无论这些进程是否运行Python解释器)以及查询环境而不是当前C语言环境的操作(如python自己的)中也可以看到更新的设置。locale.getdefaultlocale()
)配置这些区域设置之一(显式或通过上述隐式区域设置强制)将自动启用
surrogateescape
error handler 对于sys.stdin
和sys.stdout
(sys.stderr
继续使用backslashreplace
就像在其他地方一样)。此流处理行为可以使用重写PYTHONIOENCODING
像往常一样。出于调试目的,设置
PYTHONCOERCECLOCALE=warn
将导致python在上发出警告消息stderr
如果区域设置强制激活,或者如果区域设置 将 当python运行时初始化时,已经触发的强制仍处于活动状态。还要注意,即使禁用了区域设置强制,或者找不到合适的目标区域设置,
PYTHONUTF8
默认情况下,仍将在基于ASCII的旧区域设置中激活。必须禁用这两个功能才能强制解释程序使用ASCII
而不是UTF-8
用于系统接口。Availability : * 尼克斯。
3.7 新版功能: 见 PEP 538 了解更多详细信息。
- PYTHONDEVMODE¶
如果此环境变量设置为非空字符串,请启用 Python Development Mode ,引入额外的运行时检查,这些检查成本太高,无法默认启用。
3.7 新版功能.
- PYTHONUTF8¶
如果设置为
1
,启用 Python UTF-8 Mode 。如果设置为
0
,禁用 Python UTF-8 Mode 。设置任何其他非空字符串都会在解释器初始化过程中导致错误。
3.7 新版功能.
1.2.1. 调试模式变量¶
设置这些变量只在Python的调试版本中起作用。
- PYTHONTHREADDEBUG¶
如果设置,python将打印线程调试信息。
需要用
--with-pydebug
建立选项。
- PYTHONDUMPREFS¶
如果设置了,则在关闭解释器后,python将转储对象并保持引用计数活动。
需要用
--with-trace-refs
建立选项。