1. 命令行和环境

CPython 解释器会在命令行和环境中扫描各种设置。

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

1.1. 命令行

调用 Python 时，您可以指定以下任何选项：

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

当然，最常见的用例是对脚本的简单调用：

python myscript.py

1.1.1. 界面选项

解释器接口类似于 UNIX shell 的接口，但是提供了一些其他的调用方法：

• 在将标准 Importing 连接到 tty 设备的情况下调用时，它会提示 Importing 命令并执行命令，直到 EOF(文件结束符，您可以在 UNIX 上使用 Ctrl-D 或在 Windows 上使用 Ctrl-Z 生成，然后再 Importing)读。

• 当使用文件名参数或以文件作为标准 Importing 调用时，它将读取并执行该文件中的脚本。

• 当使用目录名称参数调用时，它将从该目录读取并执行一个适当命名的脚本。

• 当用-c command调用时，它将执行以* command *形式给出的 Python 语句。 * command *可能包含多个用换行符分隔的语句。领先的空格在 Python 语句中非常重要！

• 用-m module-name调用时，给定的模块位于 Python 模块路径上并作为脚本执行。

在非交互模式下，将在执行整个 Importing 之前对其进行解析。

接口选项终止解释器使用的选项列表，所有连续参数都以sys.argv结尾–请注意，第一个元素下标零(sys.argv[0])是反映程序源的字符串。

• -c <command>
  • 在* command *中执行 Python 代码。 * command *可以是一个或多个用换行符分隔的语句，与常规模块代码一样，前导空格很大。

如果指定了此选项，则sys.argv的第一个元素将是"-c"，并且当前目录将被添加到sys.path的开头(允许将该目录中的模块作为顶级模块导入)。

• -m <module-name>
  • 在sys.path中搜索命名的模块，并以main模块的身份执行其内容。

由于参数是* module *名称，因此您不能给文件 extensions(.py)。 module-name应该是有效的 Python 模块名称，但是实现可能并不总是强制执行此操作(例如，它可能允许您使用包含连字符的名称)。

包名称也是允许的。当提供软件包名称而不是常规模块时，解释器将执行<pkg>.__main__作为主模块。这种行为故意类似于处理作为脚本参数传递给解释器的目录和 zipfile。

如果指定了此选项，则sys.argv的第一个元素将是模块文件的完整路径。与-c选项一样，当前目录将添加到sys.path的开头。

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

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

2.4 版的新Function。

在版本 2.5 中进行了更改：命名模块现在可以位于包中。

在 2.7 版中进行了更改：提供程序包名称以运行__main__子模块。现在在搜索模块时将 sys.argv [0]设置为"-m"(以前错误地将其设置为"-c")

• -

  • 从标准 Importing(sys.stdin)读取命令。如果标准 Importing 为端子，则表示-i。

如果指定了此选项，则sys.argv的第一个元素将是"-"，并且当前目录将被添加到sys.path的开头。

• <script>

  • 执行* script *中包含的 Python 代码，该代码必须是指向 Python 文件，包含__main__.py文件的目录或包含__main__.py文件的 zip 文件的文件系统路径(绝对或相对)。

如果指定了此选项，则sys.argv的第一个元素将是在命令行中指定的脚本名称。

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

如果脚本名称引用目录或 zipfile，则将脚本名称添加到sys.path的开头，并将该位置的__main__.py文件作为main模块执行。

在版本 2.5 中进行了更改：在顶层包含__main__.py文件的目录和 zipfile 现在被视为有效的 Python 脚本。

如果未提供任何接口选项，则表示-i，sys.argv[0]是空字符串("")，并且当前目录将添加到sys.path的开头。

1.1.2. 通用选项

• -? ``
• -h ``
• --help ``
  • 打印所有命令行选项的简短描述。

在版本 2.5 中进行了更改：--help变体。

• -V ``
• --version ``
  • 打印 Python 版本号并退出。示例输出可能是：

Python 2.5.1

在版本 2.5 中进行了更改：--version变体。

1.1.3. 杂项选项

• -b ``
  • 比较unicode和bytearray时发出警告。给定两次选项(-bb)时发出错误。

请注意，与相应的 Python 3.x 标志不同，此标志将“不”发出str和unicode之间进行比较的警告。而是将str实例隐式解码为unicode并使用 Unicode 比较。

2.6 版的新Function。

• -B ``
  • 如果提供，Python 将不会try在导入源模块时写入.pyc或.pyo文件。另请参见 PYTHONDONTWRITEBYTECODE。

2.6 版的新Function。

• -d ``

  • 打开解析器调试输出(仅对于向导，取决于编译选项)。另请参见 PYTHONDEBUG。

• -E ``

  • 忽略所有 PYTHON*环境变量，例如 PYTHONPATH和 PYTHONHOME，可以设置。

2.2 版中的新Function。

• -i ``
  • 当将脚本作为第一个参数传递或使用-c选项时，即使sys.stdin似乎不是终端，执行脚本或命令后也要进入交互模式。无法读取 PYTHONSTARTUP文件。

当脚本引发异常时，这对于检查全局变量或堆栈跟踪很有用。另请参见 PYTHONINSPECT。

• -O ``

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

• -OO ``

  • 除-O优化外，还丢弃文档字符串。

• -Q <arg>

  • 分区控制。该参数必须是以下之一：

• old

  • int/int 和 long/long 的除法返回 int 或 long(* default *)

  • new

    • 新的除法语义，即 int/int 和 long/long 的除法返回浮点数

  • warn

    • 带有 int/int 和 long/long 警告的旧除法语义

  • warnall

    • 警告除法运算符的所有用法的旧除法语义

• -R ``
  • 启用散列随机化，以便使用不可预测的随机值对 str，bytes 和 datetime 对象的hash()值进行“盐化”。尽管它们在单个 Python 进程中保持不变，但在重复调用 Python 之间是不可预测的。

这旨在提供保护，防止由于精心选择的 Importing 而导致的拒绝服务，这些 Importing 利用了 dict 结构的最坏情况的性能，即 O(n ^ 2)复杂度。有关详情，请参见http://www.ocert.org/advisories/ocert-2011-003.html。

更改哈希值会影响从字典中检索键的 Sequences。尽管 Python 从未对此 Sequences 提供保证(并且通常在 32 位和 64 位版本之间有所不同)，但足够多的实际代码隐式依赖于这种非保证行为，即默认情况下禁用了随机化。

另请参见 PYTHONHASHSEED。

2.6.8 版中的新Function。

• -s ``
  • 不要将用户站点包目录添加到sys.path。

2.6 版的新Function。

• -S ``

  • 禁止导入模块site及其需要的与站点相关的sys.path操作。

• -t ``

  • 当源文件混合制表符和空格以使其缩进时，发出警告，使其依赖于以空格表示的制表符的价值。给定两次选项(-tt)时发出错误。

• -u ``

  • 强制 stdin，stdout 和 stderr 完全没有缓冲。在重要的系统上，还将 stdin，stdout 和 stderr 置于二进制模式。

请注意，file.readlines()和File Objects(for line in sys.stdin)中有内部缓冲，不受该选项的影响。若要解决此问题，您将需要在while 1:循环内使用file.readline()。

另请参见 PYTHONUNBUFFERED。

• -v ``

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

• -W arg

  • 警告控制。默认情况下，Python 的警告机制将警告消息打印到sys.stderr。典型的警告消息具有以下形式：

file:line: category: message

默认情况下，每个警告在发生该警告的每个源行中都打印一次。此选项控制打印警告的频率。

可以提供多个-W选项；当警告匹配多个选项时，将执行最后一个匹配选项的操作。无效的-W选项将被忽略(尽管在发出第一个警告时会显示有关无效选项的警告消息)。

从 Python 2.7 开始，默认情况下会忽略DeprecationWarning及其后代。 -Wd选项可用于重新启用它们。

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

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

• ignore

  • 忽略所有警告。

  • default

    • 明确请求默认行为(每个源行打印每个警告一次)。

  • all

    • 每次出现警告时都要打印警告(如果针对同一源代码行(例如在循环内)重复触发警告，则可能会生成许多消息)。

  • module

    • 仅在每个模块中第一次出现时打印每个警告。

  • once

    • 仅在程序第一次出现时打印每个警告。

  • error

    • 引发异常，而不是打印警告消息。

完整的参数形式为：

action:message:category:module:line

这里，* action *如上所述，但仅适用于与其余字段匹配的消息。空字段匹配所有值；尾随的空白字段可以Ellipsis。 * message *字段与打印的警告消息的开头匹配；此匹配不区分大小写。 * category *字段与警告类别匹配。这必须是一个类名；匹配项测试消息的实际警告类别是否为指定警告类别的子类。必须提供完整的类名。 * module *字段与(完全限定的)模块名称匹配；此匹配区分大小写。 * line *字段与行号匹配，其中零与所有行号匹配，因此等效于Ellipsis的行号。

• -x ``

  • 跳过源代码的第一行，允许使用非 Unix 形式的#!cmd。这仅适用于 DOS 特定的 hack。

• -3 ``

  • pass发出DeprecationWarning来警告 Python 3.x 可能的不兼容性，这些Function在 Python 3 中已删除或已显着更改，但无法使用静态代码分析检测到。

2.6 版的新Function。

有关更多详细信息，请参见将 Python 2 代码移植到 Python 3。

1.1.4. 您不应该使用的选项

• -J ``

  • 保留供Jython使用。

• -U ``

  • 全局将所有字符串 Literals 转换为 unicode。不要试图使用此选项，因为它可能会破坏您的世界。它还会产生.pyc个文件，其魔术编号与正常的有所不同。相反，您可以使用以下方法在每个模块的基础上启用 unicodeLiterals：

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设置为单个目录时，其值将替换prefix和exec_prefix。要为此指定不同的值，请将 PYTHONHOME设置为prefix:exec_prefix。

• PYTHONPATH
  • 扩展模块文件的默认搜索路径。格式与 Shell 的 PATH相同：一个或多个用os.pathsep分隔的目录路径名(例如 Unix 上的冒号或 Windows 上的分号)。不存在的目录将被静默忽略。

除普通目录外，单独的 PYTHONPATH条目可能引用包含纯 Python 模块(源或编译形式)的 zipfile。无法从 zip 文件导入扩展模块。

默认搜索路径取决于安装，但通常以prefix/lib/pythonversion开头(请参见上面的 PYTHONHOME)。总是将它附加到 PYTHONPATH。

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

• PYTHONSTARTUP

  • 如果这是可读文件的名称，则在以交互方式显示第一个提示之前，将执行该文件中的 Python 命令。在与执行交互命令相同的名称空间中执行文件，以便在其中定义或导入的对象可以在交互会话中使用而无需限定。您也可以在此文件中更改提示sys.ps1和sys.ps2。

• PYTHONY2K

  • 将此设置为非空字符串会导致time模块要求指定为字符串的日期包含 4 位数字的年份，否则，将根据time模块文档中描述的规则转换 2 位数字的年份。

• PYTHONOPTIMIZE

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

• PYTHONDEBUG

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

• PYTHONINSPECT

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

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

• PYTHONUNBUFFERED

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

• PYTHONVERBOSE

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

• PYTHONCASEOK

  • 如果设置了该值，Python 将忽略import语句中的大小写。这仅适用于 Windows，OS X，OS/2 和 RiscOS。

• PYTHONDONTWRITEBYTECODE

  • 如果设置了此选项，Python 将不会try在导入源模块时写入.pyc或.pyo文件。这等效于指定-B选项。

2.6 版的新Function。

• PYTHONHASHSEED
  • 如果此变量设置为random，则效果与指定-R选项相同：使用随机值来播种 str，bytes 和 datetime 对象的哈希。

如果 PYTHONHASHSEED设置为整数值，则将其用作固定种子来生成哈希随机化所覆盖类型的 hash()。

其目的是允许可重复的哈希，例如用于解释程序本身的自测，或允许一组 python 进程共享哈希值。

整数必须是[0,4294967295]范围内的十进制数。指定值 0 将产生与禁用散列随机化时相同的散列值。

2.6.8 版中的新Function。

• PYTHONIOENCODING
  • 用语法encodingname:errorhandler覆盖用于 stdin/stdout/stderr 的编码。 :errorhandler部分是可选的，与str.encode()中的含义相同。

2.6 版的新Function。

• PYTHONNOUSERSITE
  • 如果设置了此选项，Python 不会将用户站点包目录添加到sys.path。

2.6 版的新Function。

• PYTHONUSERBASE
  • 定义用户基本目录，用于计算python setup.py install --user的用户站点包目录和Distutils 安装路径的路径。

2.6 版的新Function。

• PYTHONEXECUTABLE

  • 如果设置了此环境变量，则将sys.argv[0]设置为其值，而不是pass C 运行时获取的值。仅适用于 Mac OSX。

• PYTHONWARNINGS

  • 这等效于-W选项。如果设置为逗号分隔的字符串，则等效于多次指定-W。

• PYTHONHTTPSVERIFY

  • 如果此环境变量专门设置为0，则等效于首次导入ssl时用enable=False隐式调用ssl._https_verify_certificates()。

有关详细信息，请参见ssl._https_verify_certificates()的文档。

2.7.12 版中的新Function。

1.2.1. 调试模式变量

设置这些变量仅在 Python 的调试版本中有效，也就是说，如果 Python 是使用--with-pydebug build 选项配置的。

• PYTHONTHREADDEBUG
  • 如果设置，Python 将打印线程调试信息。

在 2.6 版中更改：以前，此变量称为THREADDEBUG。

• PYTHONDUMPREFS

  • 如果设置了该选项，Python 将在关闭解释器后转储对象并且引用计数仍然有效。

• PYTHONMALLOCSTATS

  • 如果设置，Python 将在每次创建新的对象舞台时以及关闭时打印内存分配统计信息。

• PYTHONSHOWALLOCCOUNT

  • 如果设置了并且 Python 定义了COUNT_ALLOCS进行编译，则 Python 将在关机时将分配计数转储到 stderr 中。

2.7.15 版中的新Function。

• PYTHONSHOWREFCOUNT
  • 如果设置，则 Python 将在程序完成时或在交互式解释器中的每个语句之后打印总引用计数。

2.7.15 版中的新Function。