sys —- 系统相关的参数和函数

该模块提供了一些变量和函数。这些变量可能被解释器使用，也可能由解释器提供。这些函数会影响解释器。本模块总是可用的。

sys.abiflags

在POSIX系统上，以标准的 configure 脚本构建的 Python 中，这个变量会包含 PEP 3149 中定义的ABI标签。

在 3.8 版更改: 默认的 flags 变为了空字符串（用于 pymalloc 的 m 旗标已经移除）

3.2 新版功能.

sys.addaudithook(hook)

将可调用对象 hook 附加到当前（子）解释器的活动的审计钩子列表中。

当通过 sys.audit() 函数引发审计事件时，每个钩子将按照其被加入的先后顺序被调用，调用时会传入事件名称和参数元组。 由 PySys_AddAuditHook() 添加的原生钩子会先被调用，然后是当前（子）解释器中添加的钩子。 接下来这些钩子会记录事件，引发异常来中止操作，或是完全终止进程。

调用 sys.addaudithook() 时它自身将引发一个名为 sys.addaudithook 的审计事件且不附带参数。 如果任何现有的钩子引发了派生自 RuntimeError 的异常，则新的钩子不会被添加并且该异常会被抑制。 其结果就是，调用者无法确保他们的钩子已经被添加，除非他们控制了全部现有的钩子。

请参阅 审计事件表 以获取由 CPython 引发的所有事件，并参阅 PEP 578 了解最初的设计讨论。

3.8 新版功能.

在 3.8.1 版更改: 派生自 Exception （而非 RuntimeError ）的异常不会被抑制。

CPython implementation detail: 启用跟踪时（参阅 settrace() ），仅当可调用对象（钩子）的 __cantrace__ 成员设置为 true 时，才会跟踪该钩子。否则，跟踪功能将跳过该钩子。

sys.argv

一个列表，其中包含了被传递给 Python 脚本的命令行参数。 argv[0] 为脚本的名称（是否是完整的路径名取决于操作系统）。如果是通过 Python 解释器的命令行参数 -c 来执行的， argv[0] 会被设置成字符串 '-c' 。如果没有脚本名被传递给 Python 解释器， argv[0] 为空字符串。

为了遍历标准输入，或者通过命令行传递的文件列表，参照 fileinput 模块

注解

在 Unix 上，系统传递的命令行参数是字节类型的。Python 使用文件系统编码和 “surrogateescape” 错误处理方案对它们进行解码。当需要原始字节时，可以通过 [os.fsencode(arg) for arg in sys.argv] 来获取。

sys.audit(event, \args*)

引发一个审计事件并触发任何激活的审计钩子。 event 是一个用于标识事件的字符串，args 会包含有关事件的更多信息的可选参数。 特定事件的参数的数量和类型会被视为是公有的稳定 API 且不应当在版本之间进行修改。

例如，有一个审计事件的名称为 os.chdir。 此事件具有一个名为 path 的参数，该参数将包含所请求的新工作目录。

sys.audit() 将调用现有的审计钩子，传入事件名称和参数，并将重新引发来自任何钩子的第一个异常。 通常来说，如果有一个异常被引发，则它不应当被处理且其进程应当被尽可能快地终止。 这将允许钩子实现来决定对特定事件要如何反应：它们可以只是将事件写入日志或是通过引发异常来中止操作。

钩子程序由 sys.addaudithook() 或 PySys_AddAuditHook() 函数添加。

与本函数相等效的原生函数是 PySys_Audit()，应尽量使用原生函数。

参阅 审计事件表 以获取 CPython 定义的所有审计事件。

3.8 新版功能.

sys.base_exec_prefix

在 site.py 运行之前， Python 启动的时候被设置为跟 exec_prefix 同样的值。如果不是运行在 虚拟环境 中，两个值会保持相同；如果 site.py 发现处于一个虚拟环境中， prefix 和 exec_prefix 将会指向虚拟环境。然而 base_prefix 和 base_exec_prefix 将仍然会指向基础的 Python 环境（用来创建虚拟环境的 Python 环境）

3.3 新版功能.

sys.base_prefix

在 site.py 运行之前， Python 启动的时候被设置为跟 prefix 同样的值。如果不是运行在 虚拟环境 中, 两个值会保持相同；如果 site.py 发现处于一个虚拟环境中， prefix 和 exec_prefix 将会指向虚拟环境。然而 base_prefix 和 base_exec_prefix 将仍然会指向基础的 Python 环境（用来创建虚拟环境的 Python 环境）

3.3 新版功能.

sys.byteorder

本地字节顺序的指示符。在大端序（最高有效位优先）操作系统上值为 'big' ，在小端序（最低有效位优先）操作系统上为 'little' 。

sys.builtin_module_names

一个元素为字符串的元组。包含了所有的被编译进 Python 解释器的模块。（这个信息无法通过其他的办法获取， modules.keys() 只包括被导入过的模块。）

sys.call_tracing(func, args)

在启用跟踪时调用 func(*args) 来保存跟踪状态，然后恢复跟踪状态。这将从检查点的调试器调用，以便递归地调试其他的一些代码。

sys.copyright

一个字符串，包含了 Python 解释器有关的版权信息

sys._clear_type_cache()

清除内部的类型缓存。类型缓存是为了加速查找方法和属性的。在调试引用泄漏的时候调用这个函数 只会 清除不必要的引用。

这个函数应该只在内部为了一些特定的目的使用。

sys._current_frames()

返回一个字典，存放着每个线程的标识符与（调用本函数时）该线程栈顶的帧（当前活动的帧）之间的映射。注意 traceback 模块中的函数可以在给定某一帧的情况下构建调用堆栈。

这对于调试死锁最有用：本函数不需要死锁线程的配合，并且只要这些线程的调用栈保持死锁，它们就是冻结的。在调用本代码来检查栈顶的帧的那一刻，非死锁线程返回的帧可能与该线程当前活动的帧没有任何关系。

这个函数应该只在内部为了一些特定的目的使用。

引发一个 审计事件 sys._current_frames，没有附带参数。

sys.breakpointhook()

本钩子函数由内建函数 breakpoint() 调用。默认情况下，它将进入 pdb 调试器，但可以将其改为任何其他函数，以选择使用哪个调试器。

该函数的特征取决于其调用的函数。例如，默认绑定（即 pdb.set_trace() ）不要求提供参数，但可以将绑定换成要求提供附加参数（位置参数/关键字参数）的函数。内建函数 breakpoint() 直接将其 *args 和 **kws 传入。breakpointhooks() 返回的所有内容都会从 breakpoint() 返回。

默认的实现首先会查询环境变量 PYTHONBREAKPOINT。如果将该变量设置为 "0"，则本函数立即返回，表示在断点处无操作。如果未设置该环境变量或将其设置为空字符串，则调用 pdb.set_trace()。否则，此变量应指定要运行的函数，指定函数时应使用 Python 的点导入命名法，如 package.subpackage.module.function。这种情况下将导入 package.subpackage.module，且导入的模块必须有一个名为 function() 的可调用对象。该可调用对象会运行，*args 和 **kws 会传入，且无论 function() 返回什么，sys.breakpointhook() 都将返回到內建函数 breakpoint()。

请注意，如果在导入 PYTHONBREAKPOINT 指定的可调用对象时出错，则将报告一个 RuntimeWarning 并忽略断点。

另请注意，如果以编程方式覆盖 sys.breakpointhook()，则 不会 查询 PYTHONBREAKPOINT。

3.7 新版功能.

sys._debugmallocstats()

将有关 CPython 内存分配器状态的底层的信息打印至 stderr。

如果 Python 被配置为 —with-pydebug，本方法还将执行一些开销较大的内部一致性检查。

3.3 新版功能.

CPython implementation detail: 本函数仅限 CPython。此处没有定义确切的输出格式，且可能会更改。

sys.dllhandle

指向 Python DLL 句柄的整数。

可用性: Windows。

sys.displayhook(value)

如果 value 不是 None，则本函数会将 repr(value) 打印至 sys.stdout，并将 value 保存在 builtins._ 中。如果 repr(value) 无法用 sys.stdout.errors 错误处理方案（可能为 'strict' ）编码为 sys.stdout.encoding，则用 'backslashreplace' 错误处理方案将其编码为 sys.stdout.encoding。

在交互式 Python 会话中运行 expression 产生结果后，将在结果上调用 sys.displayhook。若要自定义这些 value 的显示，可以将 sys.displayhook 指定为另一个单参数函数。

伪代码:

def displayhook(value):
    if value is None:
        return
    # Set '_' to None to avoid recursion
    builtins._ = None
    text = repr(value)
    try:
        sys.stdout.write(text)
    except UnicodeEncodeError:
        bytes = text.encode(sys.stdout.encoding, 'backslashreplace')
        if hasattr(sys.stdout, 'buffer'):
            sys.stdout.buffer.write(bytes)
        else:
            text = bytes.decode(sys.stdout.encoding, 'strict')
            sys.stdout.write(text)
    sys.stdout.write("\n")
    builtins._ = value

在 3.2 版更改: 在发生 UnicodeEncodeError 时使用 'backslashreplace' 错误处理方案。

sys.dont_write_bytecode

如果该值为 true，则 Python 在导入源码模块时将不会尝试写入 .pyc 文件。该值会被初始化为 True 或 False，依据是 -B 命令行选项和 PYTHONDONTWRITEBYTECODE 环境变量，可以自行设置该值，来控制是否生成字节码文件。

sys.pycache_prefix

如果将该值设为某个目录（不是 None ），Python 会将字节码缓存文件 .pyc 写入到以该目录为根的并行目录树中（并从中读取），而不是在源码树中的 __pycache__ 目录下读写。源码树中所有的 __pycache__ 目录都将被忽略，并将在 pycache prefix 内写入新的 .pyc 文件。因此，如果使用 compileall 作为预构建步骤，则必须确保预构建时使用的 pycache prefix （如果有）与将来运行的时候相同。

相对路径将解释为相对于当前工作目录。

该值的初值设置，依据 -X pycache_prefix=PATH 命令行选项或 PYTHONPYCACHEPREFIX 环境变量的值（命令行优先）。如果两者均未设置，则为 None。

3.8 新版功能.

sys.excepthook(type, value, traceback)

本函数会将所给的回溯和异常输出到 sys.stderr 中。

当抛出一个异常，且未被捕获时，解释器将调用 sys.excepthook 并带有三个参数：异常类、异常实例和一个回溯对象。在交互式会话中，这会在控制权返回到提示符之前发生。在 Python 程序中，这会在程序退出之前发生。如果要自定义此类顶级异常的处理过程，可以将另一个 3 个参数的函数赋给 sys.excepthook。

引发一个 审计事件 sys.excepthook，附带参数 hook, type, value, traceback。

参见

sys.unraisablehook() 函数处理无法抛出的异常，threading.excepthook() 函数处理 threading.Thread.run() 抛出的异常。

sys.__breakpointhook__

sys.__displayhook__

sys.__excepthook__

sys.__unraisablehook__

程序开始时，这些对象存有 breakpointhook、displayhook、excepthook 和 unraisablehook 的初始值。保存它们是为了可以在 breakpointhook、displayhook 和 excepthook、unraisablehook 被破坏或被替换时恢复它们。

3.7 新版功能: __breakpointhook__

3.8 新版功能: __unraisablehook__

sys.exc_info()

本函数返回的元组包含三个值，它们给出当前正在处理的异常的信息。返回的信息仅限于当前线程和当前堆栈帧。如果当前堆栈帧没有正在处理的异常，则信息将从下级被调用的堆栈帧或上级调用者等位置获取，依此类推，直到找到正在处理异常的堆栈帧为止。此处的“处理异常”指的是“执行 except 子句”。任何堆栈帧都只能访问当前正在处理的异常的信息。

如果整个堆栈都没有正在处理的异常，则返回包含三个 None 值的元组。否则返回值为 (type, value, traceback)。它们的含义是：type 是正在处理的异常类型（它是 BaseException 的子类）；value 是异常实例（异常类型的实例）；traceback 是一个 回溯对象，该对象封装了最初发生异常时的调用堆栈。

sys.exec_prefix

一个字符串，提供特定域的目录前缀，该目录中安装了与平台相关的 Python 文件，默认也是 '/usr/local'。该目录前缀可以在构建时使用 configure 脚本的 --exec-prefix 参数进行设置。具体而言，所有配置文件（如 pyconfig.h 头文件）都安装在目录 *exec_prefix*/lib/python*X.Y*/config 中，共享库模块安装在 *exec_prefix*/lib/python*X.Y*/lib-dynload 中，其中 X.Y 是 Python 的版本号，如 3.2。

注解

如果在一个 虚拟环境 中，那么该值将在 site.py 中被修改，指向虚拟环境。Python 安装位置仍然可以用 base_exec_prefix 来获取。

sys.executable

一个字符串，提供 Python 解释器的可执行二进制文件的绝对路径，仅在部分系统中此值有意义。如果 Python 无法获取其可执行文件的真实路径，则 sys.executable 将为空字符串或 None。

sys.exit([arg])

从 Python 中退出。实现方式是抛出一个 SystemExit 异常，因此异常抛出后 try 语句的 finally 分支的清除动作将被触发，这样可能会打断外层的退出尝试。

可选参数 arg 可以是表示退出状态的整数（默认为 0），也可以是其他类型的对象。如果它是整数，则 shell 等将 0 视为“成功终止”，非零值视为“异常终止”。大多数系统要求该值的范围是 0—127，否则会产生不确定的结果。某些系统为退出代码约定了特定的含义，但通常尚不完善；Unix 程序通常用 2 表示命令行语法错误，用 1 表示所有其他类型的错误。传入其他类型的对象，如果传入 None 等同于传入 0，如果传入其他对象则将其打印至 stderr，且退出代码为 1。特别地，sys.exit("some error message") 可以在发生错误时快速退出程序。

由于 exit() 最终“只是”抛出一个异常，因此当从主线程调用时，只会从进程退出；而异常不会因此被打断。

在 3.6 版更改: 在 Python 解释器捕获 SystemExit 后，如果在清理中发生错误（如清除标准流中的缓冲数据时出错），则退出状态码将变为 120。

sys.flags

具名元组 flags 含有命令行标志的状态。这些属性是只读的。

在 3.2 版更改: 为新的 -q 标志添加了 quiet 属性

3.2.3 新版功能: hash_randomization 属性

在 3.3 版更改: 删除了过时的 division_warning 属性

在 3.4 版更改: 为 -I isolated 标志添加了 isolated 属性。

在 3.7 版更改: 为新的 Python 开发模式 添加了 dev_mode 属性，为新的 -X utf8 标志添加了 utf8_mode 属性。

sys.float_info

一个 具名元组，存有浮点型的相关信息。它包含的是关于精度和内部表示的底层信息。这些值与标准头文件 float.h 中为 C 语言定义的各种浮点常量对应，详情请参阅 1999 ISO/IEC C 标准 [C99] 的 5.2.4.2.2 节，’Characteristics of floating types（浮点型的特性）’。

关于 sys.float_info.dig 属性的进一步说明。如果 s 是表示十进制数的字符串，而该数最多有 sys.float_info.dig 位有效数字，则将 s 转换为 float 再转回去将恢复原先相同十进制值的字符串:

>>> import sys
>>> sys.float_info.dig
15
>>> s = '3.14159265358979'    # decimal string with 15 significant digits
>>> format(float(s), '.15g')  # convert to float and back -> same value
'3.14159265358979'

但是对于超过 sys.float_info.dig 位有效数字的字符串，转换前后并非总是相同:

>>> s = '9876543211234567'    # 16 significant digits is too many!
>>> format(float(s), '.16g')  # conversion changes value
'9876543211234568'

sys.float_repr_style

一个字符串，反映 repr() 函数在浮点数上的行为。如果该字符串是 'short'，那么对于（非无穷的）浮点数 x，repr(x) 将会生成一个短字符串，满足 float(repr(x)) == x 的特性。这是 Python 3.1 及更高版本中的常见行为。否则 float_repr_style 的值将是 'legacy'，此时 repr(x) 的行为方式将与 Python 3.1 之前的版本相同。

3.1 新版功能.

sys.getallocatedblocks()

返回解释器当前已分配的内存块数，无论它们大小如何。本函数主要用于跟踪和调试内存泄漏。因为解释器有内部缓存，所以不同调用之间结果会变化。可能需要调用 _clear_type_cache() 和 gc.collect() 使结果更容易预测。

如果当前 Python 构建或实现无法合理地计算此信息，允许 getallocatedblocks() 返回 0。

3.4 新版功能.

sys.getandroidapilevel()

返回一个整数，表示 Android 构建时 API 版本。

可用性：Android。

3.7 新版功能.

sys.getdefaultencoding()

返回当前 Unicode 实现所使用的默认字符串编码名称。

sys.getdlopenflags()

返回当前 dlopen() 调用所使用的标志位的值。标志值对应的符号名称可以在 os 模块中找到（形如 RTLD_xxx 的常量，如 os.RTLD_LAZY ）。

可用性: Unix。

sys.getfilesystemencoding()

返回编码名称，该编码用于在 Unicode 文件名和 bytes 文件名之间转换。为获得最佳兼容性，任何时候都应使用 str 表示文件名，尽管用字节来表示文件名也是支持的。函数如果需要接受或返回文件名，它应支持 str 或 bytes，并在内部将其转换为系统首选的表示形式。

该编码始终是 ASCII 兼容的。

应使用 os.fsencode() 和 os.fsdecode() 来保证所采用的编码和错误处理方案都是正确的。

• 在 UTF-8 模式下，任何平台上的编码均为 utf-8。

• 在 macOS 上，编码为 'utf-8'。

• 在 Unix 上，编码是语言环境编码。

• 在 Windows 上取决于用户配置，编码可能是 'utf-8' 或 'mbcs'。

• 在 Android 上，编码为 'utf-8'。

• 在 VxWorks 上，编码为 'utf-8'。

在 3.2 版更改: getfilesystemencoding() 的结果将不再有可能是 None。

在 3.6 版更改: Windows 不再保证会返回 'mbcs'。详情请参阅 PEP 529 和 _enablelegacywindowsfsencoding()。

在 3.7 版更改: 在 UTF-8 模式下返回 ‘utf-8’ 。

sys.getfilesystemencodeerrors()

返回错误处理方案的名称，该错误处理方案将在 Unicode 文件名和 bytes 文件名转换时生效。编码的名称是由 getfilesystemencoding() 返回的。

应使用 os.fsencode() 和 os.fsdecode() 来保证所采用的编码和错误处理方案都是正确的。

3.6 新版功能.

sys.getrefcount(object)

返回 object 的引用计数。返回的计数通常比预期的多一，因为它包括了作为 getrefcount() 参数的这一次（临时）引用。

sys.getrecursionlimit()

返回当前的递归限制值，即 Python 解释器堆栈的最大深度。此限制可防止无限递归导致的 C 堆栈溢出和 Python 崩溃。该值可以通过 setrecursionlimit() 设置。

sys.getsizeof(object[, default])

返回对象的大小（以字节为单位）。该对象可以是任何类型。所有内建对象返回的结果都是正确的，但对于第三方扩展不一定正确，因为这与具体实现有关。

只计算直接分配给对象的内存消耗，不计算它所引用的对象的内存消耗。

对象不提供计算大小的方法时，如果传入过 default 则返回它，否则抛出 TypeError 异常。

如果对象由垃圾回收器管理，则 getsizeof() 将调用对象的 __sizeof__ 方法，并在上层添加额外的垃圾回收器。

可以参考 recursive sizeof recipe 中的示例，关于递归调用 getsizeof() 来得到各个容器及其所有内容物的大小。

sys.getswitchinterval()

返回解释器的“线程切换间隔时间”，请参阅 setswitchinterval()。

3.2 新版功能.

sys._getframe([depth])

返回来自调用栈的一个帧对象。如果传入可选整数 depth，则返回从栈顶往下相应调用层数的帧对象。如果该数比调用栈更深，则抛出 ValueError。depth 的默认值是 0，返回调用栈顶部的帧。

引发一个 审计事件 sys._getframe，没有附带参数。

CPython implementation detail: 这个函数应该只在内部为了一些特定的目的使用。不保证它在所有 Python 实现中都存在。

sys.getprofile()

返回由 setprofile() 设置的性能分析函数。

sys.gettrace()

返回由 settrace() 设置的跟踪函数。

CPython implementation detail: gettrace() 函数仅用于实现调试器，性能分析器，打包工具等。它的行为是实现平台的一部分，而不是语言定义的一部分，因此并非在所有 Python 实现中都可用。

sys.getwindowsversion()

返回一个具名元组，描述当前正在运行的 Windows 版本。元素名称包括 major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type 和 platform_version。service_pack 包含一个字符串，platform_version 包含一个三元组，其他所有值都是整数。元素也可以通过名称来访问，所以 sys.getwindowsversion()[0] 与 sys.getwindowsversion().major 是等效的。为保持与旧版本的兼容性，只有前 5 个元素可以用索引检索。

platform 将会是 2 (VER_PLATFORM_WIN32_NT)。

product_type 可能是以下值之一：

本函数包装了 Win32 GetVersionEx() 函数，参阅 Microsoft 文档有关 OSVERSIONINFOEX() 的内容可获取这些字段的更多信息。

platform_version 返回当前操作系统的主要版本、次要版本和编译版本号，而不是为该进程所模拟的版本。 它旨在用于日志记录而非特性检测。

注解

platform_version 会从 kernel32.dll 获取版本号，这个版本可能与 OS 版本不同。 请使用 platform 模块来获取准确的 OS 版本号。

可用性: Windows。

在 3.2 版更改: 更改为具名元组，添加 service_pack_minor, service_pack_major, suite_mask 和 product_type。

在 3.6 版更改: 添加了 platform_version

sys.get_asyncgen_hooks()

返回一个 asyncgen_hooks 对象，该对象类似于 namedtuple，形式为 (firstiter, finalizer)，其中 firstiter 和 finalizer 为 None 或函数，函数以 异步生成器迭代器 作为参数，并用于在事件循环中干预异步生成器的终结。

3.6 新版功能: 详情请参阅 PEP 525。

注解

本函数已添加至暂定软件包（详情请参阅 PEP 411 ）。

sys.get_coroutine_origin_tracking_depth()

获取由 set_coroutine_origin_tracking_depth() 设置的协程来源的追踪深度。

3.7 新版功能.

注解

本函数已添加至暂定软件包（详情请参阅 PEP 411 ）。仅将其用于调试目的。

sys.hash_info

一个 具名元组，给出数字类型的哈希的实现参数。关于数字类型的哈希的详情请参阅 数字类型的哈希运算。

3.2 新版功能.

在 3.4 版更改: 添加了 algorithm, hash_bits 和 seed_bits

sys.hexversion

编码为单个整数的版本号。该整数会确保每个版本都自增，其中适当包括了未发布版本。举例来说，要测试 Python 解释器的版本不低于 1.5.2，请使用:

if sys.hexversion >= 0x010502F0:
    # use some advanced feature
    ...
else:
    # use an alternative implementation or warn the user
    ...

之所以称它为 hexversion，是因为只有将它传入内置函数 hex() 后，其结果才看起来有意义。也可以使用 具名元组 sys.version_info，它对相同信息有着更人性化的编码。

关于 hexversion 的更多信息可以在 API 和 ABI 版本管理 中找到。

sys.implementation

一个对象，该对象包含当前运行的 Python 解释器的实现信息。所有 Python 实现中都必须存在下列属性。

name 是当前实现的标识符，如 'cpython'。实际的字符串由 Python 实现定义，但保证是小写字母。

version 是一个具名元组，格式与 sys.version_info 相同。它表示 Python 实现 的版本。 另一个（由 sys.version_info 表示）是当前解释器遵循的相应 Python 语言 的版本，两者具有不同的含义。 例如，对于 PyPy 1.8，sys.implementation.version 可能是 sys.version_info(1, 8, 0, 'final', 0)，而 sys.version_info 则是 sys.version_info(2, 7, 2, 'final', 0)。对于 CPython 而言两个值是相同的，因为它是参考实现。

hexversion 是十六进制的实现版本，类似于 sys.hexversion。

cache_tag 是导入机制使用的标记，用于已缓存模块的文件名。按照惯例，它将由实现的名称和版本组成，如 'cpython-33'。但如果合适，Python 实现可以使用其他值。如果 cache_tag 被置为 None，表示模块缓存已禁用。

sys.implementation 可能包含相应 Python 实现的其他属性。这些非标准属性必须以下划线开头，此处不详细阐述。无论其内容如何，sys.implementation 在解释器运行期间或不同实现版本之间都不会更改。（但是不同 Python 语言版本间可能会不同。）详情请参阅 PEP 421。

3.3 新版功能.

注解

新的必要属性的添加必须经过常规的 PEP 过程。详情请参阅 PEP 421。

sys.int_info

一个 具名元组，包含 Python 内部整数表示形式的信息。这些属性是只读的。

3.1 新版功能.

sys.__interactivehook__

当本属性存在，则以 交互模式 启动解释器时，将自动（不带参数地）调用本属性的值。该过程是在读取 PYTHONSTARTUP 文件之后完成的，所以可以在该文件中设置这一钩子。site 模块 设置了这一属性。

引发一个 审计事件 cpython.run_interactivehook，附带参数 hook。

3.4 新版功能.

sys.intern(string)

将 string 插入 “interned” （驻留）字符串表，返回被插入的字符串 — 它是 string 本身或副本。驻留字符串对提高字典查找的性能很有用 — 如果字典中的键已驻留，且所查找的键也已驻留，则键（取散列后）的比较可以用指针代替字符串来比较。通常，Python 程序使用到的名称会被自动驻留，且用于保存模块、类或实例属性的字典的键也已驻留。

驻留字符串不是永久存在的，对 intern() 返回值的引用必须保留下来，才能发挥驻留字符串的优势。

sys.is_finalizing()

如果 Python 解释器 正在关闭 则返回 True，否则返回 False。

3.5 新版功能.

sys.last_type

sys.last_value

sys.last_traceback

这三个变量并非总是有定义，仅当有异常未处理，且解释器打印了错误消息和堆栈回溯时，才会给它们赋值。它们的预期用途，是允许交互中的用户导入调试器模块，进行事后调试，而不必重新运行导致错误的命令。（通常使用 import pdb; pdb.pm() 进入事后调试器，详情请参阅 pdb 模块。）

这些变量的含义与上述 exc_info() 返回值的含义相同。

sys.maxsize

一个整数，表示 Py_ssize_t 类型的变量可以取到的最大值。在 32 位平台上通常为 2**31 - 1，在 64 位平台上通常为 2**63 - 1。

sys.maxunicode

一个整数，表示最大的 Unicode 码点值，如 1114111 （十六进制为 0x10FFFF ）。

在 3.3 版更改: 在 PEP 393 之前，sys.maxunicode 曾是 0xFFFF 或 0x10FFFF，具体取决于配置选项，该选项指定将 Unicode 字符存储为 UCS-2 还是 UCS-4。

sys.meta_path

一个由 元路径查找器 对象组成的列表，当查找需要导入的模块时，会调用这些对象的 find_spec() 方法，观察这些对象是否能找到所需模块。调用 find_spec() 方法最少需要传入待导入模块的绝对名称。如果待导入模块包含在一个包中，则父包的 __path__ 属性将作为第二个参数被传入。该方法返回 模块规格，找不到模块则返回 None。

参见

• importlib.abc.MetaPathFinder

  抽象基类，定义了 meta_path 内的查找器对象的接口。

  importlib.machinery.ModuleSpec

  find_spec() 返回的实例所对应的具体类。

在 3.4 版更改: 在 Python 3.4 中通过 PEP 451 引入了 模块规格。早期版本的 Python 会寻找一个称为 find_module() 的方法。如果某个 meta_path 条目没有 find_spec() 方法，就会回退去调用前一种方法。

sys.modules

一个字典，将模块名称映射到已加载的模块。可以操作该字典来强制重新加载模块，或是实现其他技巧。但是，替换的字典不一定会按预期工作，并且从字典中删除必要的项目可能会导致 Python 崩溃。

sys.path

一个由字符串组成的列表，用于指定模块的搜索路径。初始化自环境变量 PYTHONPATH，再加上一条与安装有关的默认路径。

程序启动时将初始化本列表，列表的第一项 path[0] 目录含有调用 Python 解释器的脚本。如果脚本目录不可用（比如以交互方式调用了解释器，或脚本是从标准输入中读取的），则 path[0] 为空字符串，这将导致 Python 优先搜索当前目录中的模块。注意，脚本目录将插入在 PYTHONPATH 的条目*之前*。

程序可以随意修改本列表用于自己的目的。只能向 sys.path 中添加 string 和 bytes 类型，其他数据类型将在导入期间被忽略。

参见

site 模块，该模块描述了如何使用 .pth 文件来扩展 sys.path。

sys.path_hooks

一个由可调用对象组成的列表，这些对象接受一个路径作为参数，并尝试为该路径创建一个 查找器。如果成功创建查找器，则可调用对象将返回它，否则将引发 ImportError 异常。

本特性最早在 PEP 302 中被提及。

sys.path_importer_cache

一个字典，作为 查找器 对象的缓存。key 是传入 sys.path_hooks 的路径，value 是相应已找到的查找器。如果路径是有效的文件系统路径，但在 sys.path_hooks 中未找到查找器，则存入 None。

本特性最早在 PEP 302 中被提及。

在 3.3 版更改: 未找到查找器时，改为存储 None，而不是 imp.NullImporter。

sys.platform

本字符串是一个平台标识符，举例而言，该标识符可用于将特定平台的组件追加到 sys.path 中。

对于 Unix 系统（除 Linux 和 AIX 外），该字符串是 Python 构建时的 uname -s 返回的小写操作系统名称，并附加了 uname -r 返回的系统版本的第一部分，如 'sunos5' 或 'freebsd8'。除非需要检测特定版本的系统，否则建议使用以下习惯用法:

if sys.platform.startswith('freebsd'):
    # FreeBSD-specific code here...
elif sys.platform.startswith('linux'):
    # Linux-specific code here...
elif sys.platform.startswith('aix'):
    # AIX-specific code here...

对于其他系统，值是：

在 3.3 版更改: 在 Linux 上，sys.platform 将不再包含副版本号。它将总是 'linux' 而不是 'linux2' 或 'linux3'。由于旧版本的 Python 会包含该版本号，因此推荐总是使用上述 startswith 习惯用法。

在 3.8 版更改: 在 AIX 上，sys.platform 将不再包含副版本号。它将总是 'aix' 而不是 'aix5' 或 'aix7'。由于旧版本的 Python 会包含该版本号，因此推荐总是使用上述 startswith 习惯用法。

参见

os.name 更加简略。os.uname() 提供系统的版本信息。

platform 模块提供了对系统标识更详细的检查。

sys.platlibdir

平台专用库目录。用于构建标准库的路径和已安装扩展模块的路径。

在大多数平台上，它等同于 "lib" 。在 Fedora 和 SuSE 上，它等同于给出了以下 sys.path 路径的 64 位平台上的 "lib64" （其中 X.Y 是 Python 的 major.minor 版本）。

• /usr/lib64/pythonX.Y/：标准库（如 os 模块的 os.py ）

• /usr/lib64/pythonX.Y/lib-dynload/：标准库的 C 扩展模块（如 errno 模块，确切的文件名取决于平台）

• /usr/lib/pythonX.Y/site-packages/ (请使用 lib, 而非 sys.platlibdir): 第三方模块

• /usr/lib64/pythonX.Y/site-packages/: 第三方包的 C 扩展模块

3.9 新版功能.

sys.prefix

一个字符串，给出特定域的目录前缀，该目录中安装了与平台不相关的 Python 文件，默认为 '/usr/local'。该目录前缀可以在构建时使用 configure 脚本的 --prefix 参数进行设置。Python 库模块的的主要集合安装在目录 *prefix*/lib/python*X.Y* ，而与平台无关的头文件 (除了 pyconfig.h) 保存在 *prefix*/include/python*X.Y*, 其中 X.Y 是 Python 的版本号, 例如 3.2.

注解

如果在一个 虚拟环境 中，那么该值将在 site.py 中被修改，指向虚拟环境。Python 安装位置仍然可以用 base_prefix 来获取。

sys.ps1

sys.ps2

字符串，指定解释器的首要和次要提示符。仅当解释器处于交互模式时，它们才有定义。这种情况下，它们的初值为 '>>> ' 和 '... '。如果赋给其中某个变量的是非字符串对象，则每次解释器准备读取新的交互式命令时，都会重新运行该对象的 str()，这可以用来实现动态的提示符。

sys.setdlopenflags(n)

设置解释器在调用 dlopen() 时用到的标志，例如解释器在加载扩展模块时。首先，调用 sys.setdlopenflags(0) 将在导入模块时对符号启用惰性解析。要在扩展模块之间共享符号，请调用 sys.setdlopenflags(os.RTLD_GLOBAL)。标志值的符号名称可以在 os 模块中找到（即 RTLD_xxx 常量，如 os.RTLD_LAZY ）。

可用性: Unix。

sys.setprofile(profilefunc)

设置系统的性能分析函数，该函数使得在 Py​​thon 中能够实现一个 Python 源代码性能分析器。关于 Python Profiler 的更多信息请参阅 Python Profilers 分析器 章节。性能分析函数的调用方式类似于系统的跟踪函数（参阅 settrace() ），但它是通过不同的事件调用的，例如，不是每执行一行代码就调用它一次（仅在调用某函数和从某函数返回时才会调用性能分析函数，但即使某函数发生异常也会算作返回事件）。该函数是特定于单个线程的，但是性能分析器无法得知线程之间的上下文切换，因此在存在多个线程的情况下使用它是没有意义的。另外，因为它的返回值不会被用到，所以可以简单地返回 None。性能分析函数中的错误将导致其自身被解除设置。

性能分析函数应接收三个参数：frame、event 和 arg。frame 是当前的堆栈帧。event 是一个字符串：'call'、'return'、'c_call'、'c_return' 或 'c_exception'。arg 取决于事件类型。

引发一个 审计事件 sys.setprofile，不附带任何参数。

这些事件具有以下含义：

• 'call'

  表示调用了某个函数（或进入了其他的代码块）。性能分析函数将被调用，arg 为 None。

  'return'

  表示某个函数（或别的代码块）即将返回。性能分析函数将被调用，arg 是即将返回的值，如果此次返回事件是由于抛出异常，arg 为 None。

  'c_call'

  表示即将调用某个 C 函数。它可能是扩展函数或是内建函数。arg 是 C 函数对象。

  'c_return'

  表示返回了某个 C 函数。arg 是 C 函数对象。

  'c_exception'

  表示某个 C 函数抛出了异常。arg 是 C 函数对象。

sys.setrecursionlimit(limit)

将 Python 解释器堆栈的最大深度设置为 limit。此限制可防止无限递归导致的 C 堆栈溢出和 Python 崩溃。

不同平台所允许的最高限值不同。当用户有需要深度递归的程序且平台支持更高的限值，可能就需要调高限值。进行该操作需要谨慎，因为过高的限值可能会导致崩溃。

如果新的限值低于当前的递归深度，将抛出 RecursionError 异常。

在 3.5.1 版更改: 如果新的限值低于当前的递归深度，现在将抛出 RecursionError 异常。

sys.setswitchinterval(interval)

设置解释器的线程切换间隔时间（单位为秒）。该浮点数决定了“时间片”的理想持续时间，时间片将分配给同时运行的 Python 线程。请注意，实际值可能更高，尤其是使用了运行时间长的内部函数或方法时。同时，在时间间隔末尾调度哪个线程是操作系统的决定。解释器没有自己的调度程序。

3.2 新版功能.

sys.settrace(tracefunc)

设置系统的跟踪函数，使得用户在 Python 中就可以实现 Python 源代码调试器。该函数是特定于单个线程的，所以要让调试器支持多线程，必须为正在调试的每个线程都用 settrace() 注册一个跟踪函数，或使用 threading.settrace()。

跟踪函数应接收三个参数：frame、event 和 arg。frame 是当前的堆栈帧。event 是一个字符串：'call'、'line'、'return'、'exception' 或 'opcode'。arg 取决于事件类型。

每次进入 trace 函数的新的局部作用范围，都会调用 trace 函数（ event 会被设置为 'call' ），它应该返回一个引用，指向即将用在新作用范围上的局部跟踪函数；如果不需要跟踪当前的作用范围，则返回 None。

局部跟踪函数应返回对自身的引用（或对另一个函数的引用，用来在其作用范围内进行进一步的跟踪），或者返回 None 来停止跟踪其作用范围。

如果跟踪函数出错，则该跟踪函数将被取消设置，类似于调用 settrace(None)。

这些事件具有以下含义：

• 'call'

  表示调用了某个函数（或进入了其他的代码块）。全局跟踪函数将被调用，arg 为 None。返回值将指定局部跟踪函数。

  'line'

  表示解释器即将执行新一行代码或重新执行循环条件。局部跟踪函数将被调用，arg 为 None，其返回值将指定新的局部跟踪函数。关于其工作原理的详细说明，请参见 Objects/lnotab_notes.txt。要在该堆栈帧禁用每行触发事件，可以在堆栈帧上将 f_trace_lines 设置为 False。

  'return'

  表示某个函数（或别的代码块）即将返回。局部跟踪函数将被调用，arg 是即将返回的值，如果此次返回事件是由于抛出异常，arg 为 None。跟踪函数的返回值将被忽略。

  'exception'

  表示发生了某个异常。局部跟踪函数将被调用，arg 是一个 (exception, value, traceback) 元组，返回值将指定新的局部跟踪函数。

  'opcode'

  表示解释器即将执行一个新的操作码（操作码的详情请参阅 dis ）。局部跟踪函数将被调用，arg 为 None，其返回值将指定新的局部跟踪函数。每操作码触发事件默认情况下都不发出：必须在堆栈帧上将 f_trace_opcodes 显式地设置为 True 来请求这些事件。

注意，由于异常是在链式调用中传播的，所以每一级都会产生一个 'exception' 事件。

更细微的用法是，可以显式地通过赋值 frame.f_trace = tracefunc 来设置跟踪函数，而不是用现有跟踪函数的返回值去间接设置它。当前帧上的跟踪函数必须激活，而 settrace() 还没有做这件事。注意，为了使上述设置起效，必须使用 settrace() 来安装全局跟踪函数才能启用运行时跟踪机制，但是它不必与上述是同一个跟踪函数（它可以是一个开销很低的跟踪函数，只返回 None，即在各个帧上立即将其自身禁用）。

关于代码对象和帧对象的更多信息请参考 标准类型层级结构。

引发一个 审计事件 sys.settrace，不附带任何参数。

CPython implementation detail: settrace() 函数仅用于实现调试器，性能分析器，打包工具等。它的行为是实现平台的一部分，而不是语言定义的一部分，因此并非在所有 Python 实现中都可用。

在 3.7 版更改: 添加了 'opcode' 事件类型；为帧对象添加了 f_trace_lines 和 f_trace_opcodes 属性

sys.set_asyncgen_hooks(firstiter, finalizer)

接受两个可选的关键字参数，要求它们是可调用对象，且接受一个 异步生成器迭代器 作为参数。firstiter 对象将在异步生成器第一次迭代时调用。finalizer 将在异步生成器即将被销毁时调用。

引发一个 审计事件 sys.set_asyncgen_hooks_firstiter，不附带任何参数。

引发一个 审计事件 sys.set_asyncgen_hooks_finalizer，不附带任何参数。

之所以会引发两个审计事件，是因为底层的 API 由两个调用组成，每个调用都须要引发自己的事件。

3.6 新版功能: 更多详情请参阅 PEP 525，finalizer 方法的参考示例可参阅 Lib/asyncio/base_events.py 中 asyncio.Loop.shutdown_asyncgens 的实现。

注解

本函数已添加至暂定软件包（详情请参阅 PEP 411 ）。

sys.set_coroutine_origin_tracking_depth(depth)

用于启用或禁用协程溯源。启用后，协程对象上的 cr_origin 属性将包含一个元组，它由多个（文件名 filename，行号 line number，函数名 function name）元组组成，整个元组描述出了协程对象创建过程的回溯，元组首端是最近一次的调用。禁用后，cr_origin 将为 None。

要启用，请向 depth 传递一个大于零的值，它指定了有多少帧将被捕获信息。要禁用，请将 depth 置为零。

该设置是特定于单个线程的。

3.7 新版功能.

注解

本函数已添加至暂定软件包（详情请参阅 PEP 411 ）。仅将其用于调试目的。

sys._enablelegacywindowsfsencoding()

将默认文件系统编码和错误处理方案分别更改为 ‘mbcs’ 和 ‘replace’，这是为了与 Python 3.6 前的版本保持一致。

这等同于在启动 Python 前先定义好 PYTHONLEGACYWINDOWSFSENCODING 环境变量。

可用性: Windows。

3.6 新版功能: 更多详情请参阅 PEP 529。

sys.stdin

sys.stdout

sys.stderr

解释器用于标准输入、标准输出和标准错误的 文件对象：

• stdin 用于所有交互式输入（包括对 input() 的调用）；

• stdout 用于 print() 和 expression 语句的输出，以及用于 input() 的提示符；

• 解释器自身的提示符和它的错误消息都发往 stderr。

这些流都是常规 文本文件，与 open() 函数返回的对象一致。它们的参数选择如下：

• 字符编码取决于各个平台。在非 Windows 平台上使用的是语言环境 (locale) 编码（可参阅 locale.getpreferredencoding() ）。

  在 Windows 上，控制台设备使用 UTF-8 编码。非字符设备（如磁盘文件和管道）使用系统语言环境编码（即 ANSI 代码页）。非控制台字符设备（即 isatty() 返回的是 True，如 NUL）在启动时，会把控制台输入代码页和输出代码页的值分别用于 stdin 和 stdout/stderr。如果进程原本没有附加到控制台，则默认为系统语言环境编码。

  要重写控制台的特殊行为，可以在启动 Python 前设置 PYTHONLEGACYWINDOWSSTDIO 环境变量。此时，控制台代码页将用于其他字符设备。

  在所有平台上，都可以通过在 Python 启动前设置 PYTHONIOENCODING 环境变量来重写字符编码，或通过新的 -X utf8 命令行选项和 PYTHONUTF8 环境变量来设置。但是，对 Windows 控制台来说，上述方法仅在设置了 PYTHONLEGACYWINDOWSSTDIO 后才起效。

• 交互模式下，stdout 流是行缓冲的。其他情况下，它像常规文本文件一样是块缓冲的。两种情况下的 stderr 流都是行缓冲的。要使得两个流都变成无缓冲，可以传入 -u 命令行选项或设置 PYTHONUNBUFFERED 环境变量。

在 3.9 版更改: 非交互模式下，stderr 现在是行缓冲的，而不是全缓冲的。

注解

要从标准流写入或读取二进制数据，请使用底层二进制 buffer 对象。例如，要将字节写入 stdout，请使用 sys.stdout.buffer.write(b'abc')。

但是，如果你在写一个库（并且不限制执行库代码时的上下文），那么请注意，标准流可能会被替换为文件类对象，如 io.StringIO，它们是不支持 buffer 属性的。

sys.__stdin__

sys.__stdout__

sys.__stderr__

程序开始时，这些对象存有 stdin、stderr 和 stdout 的初始值。它们在程序结束前都可以使用，且在需要向实际的标准流打印内容时很有用，无论 sys.std* 对象是否已重定向。

如果实际文件已经被覆盖成一个损坏的对象了，那它也可用于将实际文件还原成能正常工作的文件对象。但是，本过程的最佳方法应该是，在原来的流被替换之前就显式地保存它，并使用这一保存的对象来还原。

注解

某些情况下的 stdin、stdout 和 stderr 以及初始值 __stdin__、__stdout__ 和 __stderr__ 可以是 None。通常发生在未连接到控制台的 Windows GUI app 中，以及在用 pythonw 启动的 Python app 中。

sys.thread_info

一个 具名元组，包含线程实现的信息。

3.3 新版功能.

sys.tracebacklimit

当该变量值设置为整数，在发生未处理的异常时，它将决定打印的回溯信息的最大层级数。默认为 1000。当将其设置为 0 或小于 0，将关闭所有回溯信息，并且只打印异常类型和异常值。

sys.unraisablehook(unraisable, /)

处理一个无法抛出的异常。

它会在发生了一个异常但 Python 没有办法处理时被调用。例如，当一个析构器引发了异常，或在垃圾回收 (gc.collect()) 期间引发了异常。

unraisable 参数具有以下属性:

• exc_type: 异常类型

• exc_value: 异常值，可以是 None.

• exc_traceback: 异常回溯，可以是 None.

• err_msg: 错误信息，可以是 None.

• object: 导致异常的对象，可以为 None.

默认的钩子程序会将 err_msg 和 object 格式化为： f'{err_msg}: {object!r}'；如果 err_msg 为 None 则采用 “Exception ignored in” 错误信息。

要改变无法抛出的异常的处理过程，可以重写 sys.unraisablehook()。

使用定制钩子存放 exc_value 可能会创建引用循环。 它应当在不再需要异常时被显式地清空以打破引用循环。

如果一个 object 正在被销毁，那么使用自定义的钩子储存该对象可能会将其复活。请在自定义钩子生效后避免储存 object，以避免对象的复活。

另请参阅 excepthook()，它处理未捕获的异常。

引发一个审计事件 sys.unraisablehook 并附带参数 hook, unraisable。

3.8 新版功能.

sys.version

一个包含 Python 解释器版本号加编译版本号以及所用编译器等额外信息的字符串。 此字符串会在交互式解释器启动时显示。 请不要从中提取版本信息，而应当使用 version_info 以及 platform 模块所提供的函数。

sys.api_version

这个解释器的 C API 版本。当你在调试 Python及期扩展模板的版本冲突这个功能非常有用。

sys.version_info

一个包含版本号五部分的元组: major, minor, micro, releaselevel 和 serial。 除 releaselevel 外的所有值均为整数；发布级别值则为 'alpha', 'beta', 'candidate' 或 'final'。 对应于 Python 版本 2.0 的 version_info 值为 (2, 0, 0, 'final', 0)。 这些部分也可按名称访问，因此 sys.version_info[0] 就等价于 sys.version_info.major，依此类推。

在 3.1 版更改: 增加了以名称表示的各部分属性。

sys.warnoptions

这是警告框架的一个实现细节；请不要修改此值。 有关警告框架的更多信息请参阅 warnings 模块。

sys.winver

用于在 Windows 平台上组成注册表键的版本号。 这在 Python DLL 中存储为 1000 号字符串资源。 其值通常是 version 的头三个字符。 它在 sys 模块中提供是为了信息展示目的；修改此值不会影响 Python 所使用的注册表键。

可用性: Windows。

sys._xoptions

一个字典，包含通过 -X 命令行选项传递的旗标，这些旗标专属于各种具体实现。选项名称将会映射到对应的值（如果显式指定）或者 True。例如:

$ ./python -Xa=b -Xc
Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys._xoptions
{'a': 'b', 'c': True}

CPython implementation detail: 这是 CPython 专属的访问通过 -X 传递的选项的方式。 其他实现可能会通过其他方式导出它们，或者完全不导出。

3.2 新版功能.

引用

C99

ISO/IEC 9899:1999. “Programming languages — C.” 该标准的公开草案可从 http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf获得。