007

Date

本周关注 Python 的命令行参数与环境变量，大体是在翻译文档。版本为 Python 3.7.0

Python Command line and environment

Command line

Interface options

  • -c <command> 执行 command 中的 Python 代码，command 可以是一个或者多个由换行符分隔的语句，与正常代码一样前导空白符是具有意义的。指定此参数后，sys.argv 的第一个元素将是 -c，并且当前目录会被添加至 sys.path 的开头

  • -m <module-name> 从 sys.path 中搜索指定名称的模块，然后作为 __main__ 执行。因为参数是模块的名称，所以不需要提供文件扩展名 .py。模块的名称应当是合法的 Python 模块名称，但是实际的实现并没有强制这一点，比如它可以运行使用包含连字符 - 的名称。参数也可以是包名，这时解释器会去执行 <pkg>.__main__。指定此参数后，sys.argv 的第一个元素将是模块文件的路径，并且当前目录将会被添加至 sys.path 的开头

  • - 从标准输入(sys.stdin)读取 command，如果标准输入是 terminal，则隐含 -i 参数。指定此参数后，sys.argv 的第一个元素为 "-"，并且当前目录将会被添加到 sys.path 的开头

  • <script> 可以为一个 Python 脚本的路径，包含此文件的目录将会被添加到 sys.path 的开头；或者含有 __main__.py 的目录，或者含有 __main__.py 的 zip 压缩包，此时 <script> 将被添加到 sys.path 的开头

$ /home/a/b# python __main__.py
/home/a/b
$ /home/a# python b/__main__.py
/home/a/b
$ /home/a# python b
b
$ /home# python a/b
a/b
$ /home# python a/b/__main__.py
/home/a/b

Generic options

  • -?
  • -h

  • --help 输出所有命令行选项的简要说明

  • -V

  • --version 显示 Python 的版本信息，3.6 后可以通过 -VV 显示更详细的编译信息(其实就是进入 REPL 时显示的那个)

Miscellaneous options

  • -b 当 bytes/bytearray 和 str 或者 bytes 和 int 进行比较时抛出 warning；-bb 则会抛出异常

  • -B 不会生成 pyc 文件

  • --check-hash-based-pycs default|always|never Control the validation behavior of hash-based .pyc files. See Cached bytecode invalidation. When set to default, checked and unchecked hash-based bytecode cache files are validated according to their default semantics. When set to always, all hash-based .pyc files, whether checked or unchecked, are validated against their corresponding source file. When set to never, hash-based .pyc files are not validated against their corresponding source files. The semantics of timestamp-based .pyc files are unaffected by this option.

  • -d 输出调试信息，另见 PYTHONDEBUG

  • -E 忽略所有的 PYTHON* 环境变量
  • -i 执行脚本或者 command(-c) 后进入交互模式。PYTHONSTARTUP 中指定的文件不会被读取
  • -I 以隔离模式运行 Python。忽略所有的 PYTHON* 环境变量并且 sys.path 不会包含脚本所在目录或者 user site-packages 目录
  • -O 移除所有的 assert 语句并且 __debug__ 常量为 True。此时编译后的字节码文件名后缀为 .opt-1.pyc
  • -OO 移除所有的 assert 语句，抛弃 docstring 并且 __debug__ 常量为 True。此时编译后的字节码文件名后缀为 .opt-2.pyc
  • -q 交互模式不显示 copyright 和版本信息
  • -R 开启 hash randomization。因为默认开启所以只有在环境变量 PYTHONHASHSEED 为 0 的时候这个选项才有效果
  • -s 不向 sys.path 添加 user site-packages 目录
  • -S 禁止启动时导入 site 模块。site 模块会修改 sys.path 并且添加一些 built-in constants 比如 exit
  • -u 强制 stdout 和 stderr 流不使用缓冲，另见 PYTHONUNBUFFERED
  • -v 每次对模块进行初始化时都会打印信息，显示加载它的位置，同时在退出时提供模块的析构信息， 另见 PYTHONVERBOSE。如果指定 -vv 则会为搜索模块时检查的每个文件都打印信息
  • -W arg Warning 控制。Python 的 warning 机制默认打印 warning 信息到 sys.stderr。典型的 warning 信息格式如下:
file:line: category: message

默认每条 warning 只会打印一次(比如在循环内部)。可以给定多个 -W 选项，当有多个选项符合匹配时，将执行最后一个匹配向。虽然无效的 -W 选项将会被忽略，但是在打印第一个 warning 时也会打印有关于无效选项的 warning 信息。另外 warning 可以通过 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 跳过源代码的第一行，允许使用非 Unix 格式的 #!cmd
  • -X 保留用于各种特定于实现的选项。CPython 当前定义如下：
  • -X faulthandler 开启 faulthandler
  • -X showrefcount 程序结束时或者交互式下每条语句执行后打印书总共的引用计数和占用的内存块。需要在编译时开启 debug
  • -X tracemalloc 使用 tracemalloc 模块去跟踪 Python 的内存分配。默认情况下，只有最近的栈帧会被存储。可以使用 -X tracemalloc=NFRAME 调整阈值
  • -X showalloccount 当程序结束时打印每个类型所分配对象的总数量。需要编译时指定 COUNT_ALLOCS
  • -X importtime 显示每个导入操作的耗时，比如 python3 -X importtime -c 'import asyncio'，另见 PYTHONPROFILEIMPORTTIME
  • -X dev 开启 CPython 的 "development mode"
    • Add default warning filter, as -W default.
    • Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks() C function.
    • Enable the faulthandler module to dump the Python traceback on a crash.
    • Enable asyncio debug mode.
    • Set the dev_mode attribute of sys.flags to True
  • -X utf8 启动 UTF-8 模式
  • -X utf8=0 显示关闭 UTF-8 模式

Environment variables

环境变量会影响 Python 的行为，他们会在除了 -E 和 -I 外的所有命令行参数处理前得到处理。通常命令行参数会覆盖掉产生冲突的环境变量

  • 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 相同，不存在的目录将被忽略。除了普通目录外，可以是包含 Python 模块的 zip 文件。默认的搜索路径依赖于安装位置，通常以 prefix/lib/pythonverion 开头。另见 PYTHONHOME，它总是会被添加到 PYTHONPATH

  • PYTHONSTARTUP 如果这是一个可读文件的名称，那么在交互模式显示第一个 prompt 前文件内的代码将会被执行。该文件中的代码和交互式命令运行在同一个命名空间下，以便在交互式命令中使用其定义与导入的对象。可以在此文件中修改 sys.ps1 和 sys.ps2 或者 sys.__interactivehook__

  • PYTHONOPTIMIZE 如果被设置为一个非空字符串则等效于 -O 选项；如果被设置为一个整数 n 则等效于 -O{n}

  • PYTHONBREAKPOINT 如果设置了这个选项，它的名称应当为以 . 分隔的 callable。包含这个 callable 的模块会先被导入，然后由 sys.breakpointhook() 所调用(breakpoint() 会调用 sys.breakpointhook())。如果不设置或者为空字符串，那么等效于 pdf.set_trace。如果设置为字符串 "0"，那么 sys.breakpointhook() 会直接返回，不执行任何操作

  • PYTHONDEBUG 如果被设置为一个非空字符串则等效于 -d 选项。如果设置为一个整数 则等效于 -d{n}

  • PYTHONINSPECT 如果被设置为一个非空字符串则等效于 -i。这个环境变量可以在 Python 代码中通过 os.environ 修改从而强制在程序结束时进入交互模式

  • PYTHONUNBUFFERED 如果被设置为一个非空字符串则等效于 -u 选项

  • PYTHONVERBOSE 如果被设置为一个非空字符串则等效于 -v 选项。如果设置为一个整数 则等效于 -v{n}

  • PYTHONCASEOK OSX 和 Win 环境下有效，import 语句将大小写不敏感

  • PYTHONDONTWRITEBYTECODE 如果被设置为非空字符串，Python 不会生成 .pyc 文件。等效于 -B 选项

  • PYTHONHASHSEED 如果这个变量没有被设置或者被设置为 random，str、bytes、datetime 对象哈希值的种子将为一个随机值。如果 PYTHONHASHSEED 被设置为一个整数(0 到 4294967295 之间，左闭右开)，将使用固定的种子值。特别地，0 表示禁用哈希随机。PYTHONHASHSEED 的目的是允许可重复的哈希，例如解释器本身的自测，或允许一组 Python 进程共享哈希值

  • PYTHONIOENCODING 如果在运行解释器之前设置了它，将覆盖 stdin/stdout/stderr 的编码。格式为 encodingname:errorhandler。二者都是可选的，且和 str.encode() 具有相同的含义。特别的对于 stderr，errorhandler 部分一定会被忽略，永远是 backslashreplace

  • PYTHONNOUSERSITE 如果被设置，Python 不会向 sys.path 添加 user site-packages 目录

  • PYTHONUSERBASE 定义 user base directory

  • PYTHONEXECUTABLE OSX 下的参数，会覆盖 sys.argv[0]

  • PYTHONWARNINGS 等效于 -W 参数。如果被设置为逗号分隔的多个字符串，则等效于指定 -W 多次

  • PYTHONFAULTHANDLER 如果被设置为非空字符串，faulthandler.enable() 将会在启动时被调用。这将为 SIGSEGV, SIGFPE, SIGABRT, SIGBUS， SIGILL 信号注册特殊的处理函数来 dump Python 的 trackback。等效于 -X faulthanlder 选项

  • PYTHONTRACEMALLOC 如果被设置为非空字符串，将使用 tracemalloc 模块去跟踪 Python 的内存分配。此环境变量的值将决定存储在 trackback 中栈帧的上限。比如 PYTHONTRACEMALLOC=1 将仅存储最近的栈帧

  • PYTHONPROFILEIMPORTTIME 如果被设置为非空字符串，Python 将显示 import 操作的耗时。等效于 -X importtime 选项

  • PYTHONASYNCIODEBUG 如果被设置为非空字符串，则开启 asyncio 模块的调试模式

  • PYTHONMALLOC 设置 Python 的内存分配器或者安装调试钩子 参考文档

  • PYTHONMALLOCSTATS 如果被设置为非空字符串，Python 将在 pymalloc memory allocator 每次创建/销毁 arena 时打印统计信息。如果通过 PYTHONMALLOC 强制使用 malloc() 或者 Python 没有 pymalloc 支持时，这个环境变量将被忽略

  • PYTHONLEGACYWINDOWSFSENCODING 仅 Win 可用

  • PYTHONLEGACYWINDOWSSTDIO 仅 Win 可用

  • PYTHONCOERCECLOCALE 3.7 新增，详见 PEP 538

  • PYTHONDEVMODE 如果被设置为非空字符串，开启 CPython 的 "development mode"，等同于 -X dev

  • PYTHONUTF8 3.7 新增，详见 PEP 540

  • PYTHONTHREADDEBUG 编译 Python 时需要添加 -with-pydebug 才会存在的环境变量，作用是打印线程调试信息

  • PYTHONDUMPREFS 编译 Python 时需要添加 -with-pydebug 才会存在的环境变量，作用是在解释器运行结束时输出仍然存活的对象和引用计数