sys — 系统特定的参数和函数

---

此模块提供对解释器使用或维护的一些变量以及与解释器强交互的函数的访问。它始终可用。除非另有明确说明，否则所有变量都是只读的。

sys.abiflags

在 POSIX 系统上，如果 Python 是用标准 configure 脚本构建的，则此变量包含 PEP 3149 中指定的 ABI 标志。

在 3.2 版本加入。

3.8 版中已更改: 默认标志变为空字符串（移除了 pymalloc 的 m 标志）。

可用性: Unix。

sys.addaudithook(hook)

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

当通过 sys.audit() 函数引发审计事件时，每个钩子将按照其添加的顺序被调用，并带有事件名称和参数元组。通过 PySys_AddAuditHook() 添加的本机钩子首先被调用，然后是当前（子）解释器中添加的钩子。钩子可以记录事件、引发异常以中止操作，或完全终止进程。

请注意，审计钩子主要用于收集有关内部或无法观察到的操作的信息，无论是 Python 还是用 Python 编写的库。它们不适合实现“沙箱”。特别是，恶意代码可以轻易禁用或绕过使用此函数添加的钩子。至少，任何安全敏感的钩子都必须在使用 C API PySys_AddAuditHook() 初始化运行时之前添加，并且任何允许任意内存修改的模块（例如 ctypes）都应完全移除或严密监控。

调用 sys.addaudithook() 本身将引发一个名为 sys.addaudithook 且不带参数的审计事件。如果任何现有钩子引发派生自 RuntimeError 的异常，则不会添加新钩子，并且异常将被抑制。因此，除非调用方控制所有现有钩子，否则不能假定其钩子已添加。

有关 CPython 引发的所有事件，请参见审计事件表，有关原始设计讨论，请参见 PEP 578。

在 3.8 版本加入。

3.8.1 版中已更改: 派生自 Exception 但不是 RuntimeError 的异常不再被抑制。

CPython 实现细节: 当启用追踪时（参见 settrace()），只有当可调用对象有一个设置为真值的 __cantrace__ 成员时，Python 钩子才会被追踪。否则，追踪函数将跳过该钩子。

sys.argv

传递给 Python 脚本的命令行参数列表。argv[0] 是脚本名称（这是否是完整路径名取决于操作系统）。如果使用解释器的 -c 命令行选项执行命令，则 argv[0] 设置为字符串 '-c'。如果没有将脚本名称传递给 Python 解释器，则 argv[0] 是空字符串。

要遍历标准输入或命令行上给定的文件列表，请参见 fileinput 模块。

另请参见 sys.orig_argv。

备注

在 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

等同于 exec_prefix，但指向基础 Python 安装。

在 虚拟环境 下运行时，exec_prefix 会被覆盖为虚拟环境前缀。base_exec_prefix 则不会改变，始终指向基础 Python 安装。有关更多信息，请参阅 虚拟环境。

在 3.3 版本加入。

sys.base_prefix

等同于 prefix，但指向基础 Python 安装。

在 虚拟环境 下运行时，prefix 会被覆盖为虚拟环境前缀。base_prefix 则不会改变，始终指向基础 Python 安装。有关更多信息，请参阅 虚拟环境。

在 3.3 版本加入。

sys.byteorder

本机字节顺序的指示器。在大端序（最高有效字节在前）平台上，此值将为 'big'，在小端序（最低有效字节在前）平台上将为 'little'。

sys.builtin_module_names

一个字符串元组，包含所有编译到此 Python 解释器中的模块的名称。（此信息无法通过其他方式获得 — modules.keys() 只列出已导入的模块。）

另请参见 sys.stdlib_module_names 列表。

sys.call_tracing(func, args)

在启用追踪的情况下调用 func(*args)。追踪状态会被保存，并在之后恢复。这旨在从检查点由调试器调用，以递归调试或分析其他代码。

调用由 settrace() 或 setprofile() 设置的追踪函数时，追踪会暂停，以避免无限递归。call_tracing() 启用追踪函数的显式递归。

sys.copyright

一个包含与 Python 解释器相关的版权信息的字符串。

sys._clear_type_cache()

清除内部类型缓存。类型缓存用于加速属性和方法查找。*仅* 在引用泄露调试期间删除不必要的引用时使用此函数。

此函数仅应用于内部和专用目的。

自 3.13 版弃用: 改用更通用的 _clear_internal_caches() 函数。

sys._clear_internal_caches()

清除所有内部性能相关的缓存。*仅* 在寻找内存泄漏时，为了释放不必要的引用和内存块而使用此函数。

在 3.13 版本加入。

sys._current_frames()

返回一个字典，将每个线程的标识符映射到调用该函数时该线程中当前活动的顶部堆栈帧。请注意，traceback 模块中的函数可以根据此类帧构建调用堆栈。

这对于调试死锁最有用：此函数不需要死锁线程的协作，并且这些线程的调用堆栈在它们死锁期间保持冻结。对于非死锁线程返回的帧可能与调用代码检查帧时该线程的当前活动无关。

此函数仅应用于内部和专用目的。

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

sys._current_exceptions()

返回一个字典，将每个线程的标识符映射到调用该函数时该线程中当前活动的顶部异常。如果一个线程当前没有处理异常，则它不包含在结果字典中。

这对于统计分析最有用。

此函数仅应用于内部和专用目的。

引发一个带有 sys._current_exceptions 的审计事件，不带参数。

3.12 版中已更改: 字典中的每个值现在都是一个单独的异常实例，而不是 sys.exc_info() 返回的 3 元组。

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 以 调试模式 构建（configure --with-pydebug option），它还会执行一些耗时的内部一致性检查。

在 3.3 版本加入。

CPython 实现细节: 此函数特定于 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。

sys.displayhook 在交互式 Python 会话中输入的表达式求值结果上调用。这些值的显示可以通过将另一个单参数函数分配给 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

如果此项为真，Python 将不会在导入源模块时尝试写入 .pyc 文件。此值最初根据 -B 命令行选项和 PYTHONDONTWRITEBYTECODE 环境变量设置为 True 或 False，但您可以自行设置以控制字节码文件生成。

sys._emscripten_info

一个命名元组，包含 *wasm32-emscripten* 平台环境的信息。该命名元组是临时的，将来可能会更改。

_emscripten_info.emscripten_version

Emscripten 版本，以整数元组形式表示（主、次、微），例如 (3, 1, 8)。

_emscripten_info.runtime

运行时字符串，例如浏览器用户代理、'Node.js v14.18.2' 或 'UNKNOWN'。

_emscripten_info.pthreads

如果 Python 使用 Emscripten pthreads 支持编译，则为 True。

_emscripten_info.shared_memory

如果 Python 使用共享内存支持编译，则为 True。

可用性：Emscripten。

在 3.11 版本中新增。

sys.pycache_prefix

如果此项已设置（不是 None），Python 会将字节码缓存 .pyc 文件写入（并从其中读取）一个以该目录为根的并行目录树，而不是源文件树中的 __pycache__ 目录。源文件树中的任何 __pycache__ 目录都将被忽略，新的 .pyc 文件将写入 pycache 前缀中。因此，如果您使用 compileall 作为预构建步骤，则必须确保在运行时使用相同的 pycache 前缀（如果有）。

相对路径是相对于当前工作目录解释的。

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

在 3.8 版本加入。

sys.excepthook(type, value, traceback)

此函数将给定的追踪信息和异常打印到 sys.stderr。

当引发并捕获到非 SystemExit 的异常时，解释器会调用 sys.excepthook，并传递三个参数：异常类、异常实例和追踪对象。在交互式会话中，这发生在控制权返回到提示符之前；在 Python 程序中，这发生在程序退出之前。可以通过将另一个三参数函数分配给 sys.excepthook 来自定义此类顶级异常的处理。

当发生未捕获的异常时，引发一个审计事件 sys.excepthook，参数为 hook、type、value、traceback。如果未设置钩子，hook 可能为 None。如果任何钩子引发派生自 RuntimeError 的异常，则对钩子的调用将被抑制。否则，审计钩子异常将被报告为不可引发，并调用 sys.excepthook。

参见

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.exception()

当在异常处理程序执行期间（例如 except 或 except* 子句）调用此函数时，它会返回此处理程序捕获的异常实例。当异常处理程序相互嵌套时，只有最内部处理程序处理的异常可访问。

如果没有异常处理程序正在执行，此函数返回 None。

在 3.11 版本中新增。

sys.exc_info()

此函数返回已处理异常的旧式表示。如果当前正在处理异常 e (因此 exception() 会返回 e)，则 exc_info() 返回元组 (type(e), e, e.__traceback__)。也就是说，一个元组包含异常的类型（BaseException 的子类）、异常本身以及通常封装异常最后发生时调用堆栈的追踪对象。

如果堆栈上的任何地方都没有处理异常，则此函数返回一个包含三个 None 值的元组。

3.11 版中已更改: type 和 traceback 字段现在从 value（异常实例）派生，因此当异常在处理期间被修改时，这些更改会反映在后续调用 exc_info() 的结果中。

sys.exec_prefix

一个字符串，给出安装平台相关 Python 文件的特定站点目录前缀；默认情况下，这也是 '/usr/local'。这可以在构建时使用 configure 脚本的 --exec-prefix 参数设置。具体来说，所有配置文件（例如 pyconfig.h 头文件）都安装在目录 exec_prefix/lib/pythonX.Y/config 中，共享库模块安装在 exec_prefix/lib/pythonX.Y/lib-dynload 中，其中 *X.Y* 是 Python 的版本号，例如 3.2。

备注

如果 虚拟环境 生效，此 exec_prefix 将指向虚拟环境。Python 安装的值仍然可以通过 base_exec_prefix 获得。有关更多信息，请参阅 虚拟环境。

3.14 版中已更改: 在虚拟环境下运行时，prefix 和 exec_prefix 现在由路径初始化设置为虚拟环境前缀，而不是 site。这意味着 prefix 和 exec_prefix 始终指向虚拟环境，即使 site 被禁用 (-S) 也是如此。

sys.executable

一个字符串，给出 Python 解释器可执行二进制文件的绝对路径，在有意义的系统上。如果 Python 无法检索其可执行文件的真实路径，sys.executable 将为空字符串或 None。

sys.exit([arg])

引发 SystemExit 异常，表示意图退出解释器。

可选参数 *arg* 可以是整数，给出退出状态（默认为零），也可以是其他类型的对象。如果它是整数，零被 shell 等认为是“成功终止”，任何非零值都被认为是“异常终止”。大多数系统要求它在 0-127 范围内，否则会产生未定义的结果。有些系统约定为特定退出代码分配特定含义，但这些通常不完善；Unix 程序通常使用 2 表示命令行语法错误，使用 1 表示所有其他类型的错误。如果传递了其他类型的对象，None 等同于传递零，任何其他对象都会打印到 stderr 并导致退出代码为 1。特别是，sys.exit("some error message") 是一种在发生错误时快速退出程序的方法。

由于 exit() 最终“只”引发异常，因此它只有在从主线程调用且异常未被截获时才会退出进程。try 语句的 finally 子句指定的清理操作会得到执行，并且可以在更外层截获退出尝试。

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

sys.flags

命名元组 *flags* 暴露了命令行标志的状态。标志应仅通过名称访问，而不是通过索引访问。属性是只读的。

flags.debug	-d
flags.inspect	-i
flags.interactive	-i
flags.isolated	-I
flags.optimize	-O 或 -OO
flags.dont_write_bytecode	-B
flags.no_user_site	-s
flags.no_site	-S
flags.ignore_environment	-E
flags.verbose	-v
flags.bytes_warning	-b
flags.quiet	-q
flags.hash_randomization	-R
flags.dev_mode	-X dev （Python 开发模式）
flags.utf8_mode	-X utf8
flags.safe_path	-P
flags.int_max_str_digits	-X int_max_str_digits （整数字符串转换长度限制）
flags.warn_default_encoding	-X warn_default_encoding
flags.gil	-X gil 和 PYTHON_GIL
flags.thread_inherit_context	-X thread_inherit_context 和 PYTHON_THREAD_INHERIT_CONTEXT
flags.context_aware_warnings	-X context_aware_warnings 和 PYTHON_CONTEXT_AWARE_WARNINGS

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 属性。

3.10 版中已更改: 为 -X warn_default_encoding 标志添加了 warn_default_encoding 属性。

3.11 版中已更改: 为 -P 选项添加了 safe_path 属性。

3.11 版中已更改: 添加了 int_max_str_digits 属性。

3.13 版中已更改: 添加了 gil 属性。

3.14 版中已更改: 添加了 thread_inherit_context 属性。

3.14 版中已更改: 添加了 context_aware_warnings 属性。

sys.float_info

一个命名元组，包含有关浮点类型的信息。它包含有关精度和内部表示的低级信息。这些值对应于“C”编程语言的标准头文件 float.h 中定义的各种浮点常量；有关详细信息，请参阅 1999 年 ISO/IEC C 标准 [C99] 的 5.2.4.2.2 节“浮点类型的特性”。

float_info 命名元组的属性

属性	float.h 宏	解释
float_info.epsilon	DBL_EPSILON	1.0 和大于 1.0 且可表示为浮点数的最小浮点数之间的差值。 另请参见 math.ulp()。
float_info.dig	DBL_DIG	浮点数中可以忠实表示的最大十进制位数；见下文。
float_info.mant_dig	DBL_MANT_DIG	浮点精度：浮点数的有效数字中基数 radix 的位数。
float_info.max	DBL_MAX	可表示的最大正有限浮点数。
float_info.max_exp	DBL_MAX_EXP	最大整数 *e*，使得 radix**(e-1) 是一个可表示的有限浮点数。
float_info.max_10_exp	DBL_MAX_10_EXP	最大的整数 *e*，使得 10**e 落在可表示的有限浮点数范围内。
float_info.min	DBL_MIN	可表示的最小正 *规范化* 浮点数。 使用 math.ulp(0.0) 获取最小的正 *非规范化* 可表示浮点数。
float_info.min_exp	DBL_MIN_EXP	最小的整数 *e*，使得 radix**(e-1) 是一个规范化的浮点数。
float_info.min_10_exp	DBL_MIN_10_EXP	最小的整数 *e*，使得 10**e 是一个规范化的浮点数。
float_info.radix	FLT_RADIX	指数表示的基数。
float_info.rounds	FLT_ROUNDS	一个整数，表示浮点算术的舍入模式。这反映了解释器启动时系统 FLT_ROUNDS 宏的值。 -1: 不确定 0: 向零舍入 1: 四舍五入到最近的偶数 2: 向正无穷舍入 3: 向负无穷舍入 FLT_ROUNDS 的所有其他值表示实现定义的舍入行为。

属性 sys.float_info.dig 需要进一步解释。如果 s 是一个表示最多 sys.float_info.dig 有效数字的十进制数的任何字符串，那么将 s 转换为浮点数并再次转换回来将恢复表示相同十进制值的字符串。

>>> 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_internal_caches() 和 gc.collect() 才能获得更可预测的结果。

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

在 3.4 版本加入。

sys.getunicodeinternedsize()

返回已 intern 的 Unicode 对象的数量。

3.12 新版功能.

sys.getandroidapilevel()

返回 Android 的构建时 API 级别作为整数。这表示此 Python 版本可以运行的 Android 的最低版本。有关运行时版本信息，请参见 platform.android_ver()。

可用性: Android。

在 3.7 版本加入。

sys.getdefaultencoding()

返回 'utf-8'。这是默认字符串编码的名称，用于 str.encode() 等方法。

sys.getdlopenflags()

返回用于 dlopen() 调用的标志的当前值。标志值的符号名称可在 os 模块中找到（RTLD_xxx 常量，例如 os.RTLD_LAZY）。

可用性: Unix。

sys.getfilesystemencoding()

获取文件系统编码：与文件系统错误处理程序一起用于在 Unicode 文件名和字节文件名之间进行转换的编码。文件系统错误处理程序通过 getfilesystemencodeerrors() 返回。

为了获得最佳兼容性，在所有情况下都应使用 str 作为文件名，尽管也支持将文件名表示为字节。接受或返回文件名的函数应支持 str 或 bytes，并在内部转换为系统首选的表示形式。

应使用 os.fsencode() 和 os.fsdecode() 来确保使用正确的编码和错误模式。

文件系统编码和错误处理程序 在 Python 启动时由 PyConfig_Read() 函数配置：参见 filesystem_encoding 和 filesystem_errors 的成员 PyConfig。

3.2 版中已更改: getfilesystemencoding() 结果不再可以是 None。

3.6 版中已更改: Windows 不再保证返回 'mbcs'。有关更多信息，请参阅 PEP 529 和 _enablelegacywindowsfsencoding()。

3.7 版中已更改: 如果启用了 Python UTF-8 模式，则返回 'utf-8'。

sys.getfilesystemencodeerrors()

获取文件系统错误处理程序：与文件系统编码一起用于在 Unicode 文件名和字节文件名之间进行转换的错误处理程序。文件系统编码通过 getfilesystemencoding() 返回。

应使用 os.fsencode() 和 os.fsdecode() 来确保使用正确的编码和错误模式。

文件系统编码和错误处理程序 在 Python 启动时由 PyConfig_Read() 函数配置：参见 filesystem_encoding 和 filesystem_errors 的成员 PyConfig。

在 3.6 版本加入。

sys.get_int_max_str_digits()

返回整数字符串转换长度限制的当前值。另请参见 set_int_max_str_digits()。

在 3.11 版本中新增。

sys.getrefcount(object)

返回 *object* 的引用计数。返回的计数通常比您预期的要高一个，因为它包括作为 getrefcount() 参数的（临时）引用。

请注意，返回的值可能无法真正反映对象实际持有的引用数量。例如，某些对象是不朽的，并且具有非常高的引用计数，这并不反映实际的引用数量。因此，除了 0 或 1 的值外，不要依赖返回值的准确性。

CPython 实现细节: 具有大引用计数的不朽对象可以通过 _is_immortal() 来识别。

3.12 版中已更改: 不朽对象的引用计数非常大，与对象的实际引用数量不匹配。

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*，则返回比堆栈顶部低 *depth* 个调用的帧对象。如果深度超过调用堆栈，则会引发 ValueError。*depth* 的默认值为零，返回调用堆栈顶部的帧。

引发带有参数 frame 的审计事件 sys._getframe。

CPython 实现细节: 此函数仅应内部和特殊目的使用。它不保证在所有 Python 实现中都存在。

sys._getframemodulename([depth])

从调用栈返回模块名称。如果提供了可选整数 depth，则返回比栈顶多 depth 个调用的模块。如果超出调用栈深度，或者模块无法识别，则返回 None。depth 的默认值为零，返回调用栈顶部的模块。

引发一个带参数 depth 的 审计事件 sys._getframemodulename。

CPython 实现细节: 此函数仅应内部和特殊目的使用。它不保证在所有 Python 实现中都存在。

3.12 新版功能.

sys.getobjects(limit[, type])

此函数仅在 CPython 使用专门的配置选项 --with-trace-refs 构建时才存在。它仅用于调试垃圾回收问题。

返回最多 limit 个动态分配的 Python 对象的列表。如果给定了 type，则只包含该精确类型（不包括子类型）的对象。

列表中的对象不安全，请勿使用。具体来说，结果将包含所有共享对象分配器状态的解释器（即，使用 PyInterpreterConfig.use_main_obmalloc 设置为 1 或使用 Py_NewInterpreter() 创建的解释器，以及主解释器）中的对象。混合来自不同解释器的对象可能导致崩溃或其他意外行为。

CPython 实现细节： 此函数仅应用于特殊目的。它不保证在所有 Python 实现中都存在。

3.14 版本中的变化: 结果可能包含来自其他解释器的对象。

sys.getprofile()

获取由 setprofile() 设置的分析器函数。

sys.gettrace()

获取由 settrace() 设置的跟踪函数。

CPython 实现细节： 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 包含一个 3 元组，所有其他值都是整数。这些组件也可以通过名称访问，因此 sys.getwindowsversion()[0] 等同于 sys.getwindowsversion().major。为了与以前的版本兼容，只有前 5 个元素可以通过索引检索。

platform 将是 2 (VER_PLATFORM_WIN32_NT)。

product_type 可以是以下值之一

常量	含义
1 (VER_NT_WORKSTATION)	系统是工作站。
2 (VER_NT_DOMAIN_CONTROLLER)	系统是域控制器。
3 (VER_NT_SERVER)	系统是服务器，但不是域控制器。

此函数包装了 Win32 GetVersionEx() 函数；有关这些字段的更多信息，请参阅 Microsoft 文档中的 OSVERSIONINFOEX()。

platform_version 返回当前操作系统的主要版本、次要版本和构建号，而不是为进程模拟的版本。它旨在用于日志记录，而不是用于功能检测。

备注

platform_version 从 kernel32.dll 获取版本，该版本可能与 OS 版本不同。请使用 platform 模块来获取准确的操作系统版本。

可用性: Windows。

3.2 版本中的变化: 更改为命名元组，并添加了 service_pack_minor、service_pack_major、suite_mask 和 product_type。

3.6 版本中的变化: 添加了 platform_version

sys.get_asyncgen_hooks()

返回一个 asyncgen_hooks 对象，它类似于 (firstiter, finalizer) 形式的 namedtuple，其中 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

一个 命名元组，给出数字哈希实现的参数。有关数字类型哈希的更多详细信息，请参阅 数字类型的哈希。

hash_info.width

用于哈希值的位数宽度

hash_info.modulus

用于数字哈希方案的素数模 P

hash_info.inf

正无穷大的哈希值

hash_info.nan

（此属性不再使用）

hash_info.imag

用于复数虚部的乘数

hash_info.algorithm

用于 str、bytes 和 memoryview 的哈希算法名称

hash_info.hash_bits

哈希算法的内部输出大小

hash_info.seed_bits

哈希算法种子密钥的大小

在 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 实现 的版本。这与当前运行的解释器所遵循的 Python 语言 的特定版本有不同的含义，后者由 sys.version_info 表示。例如，对于 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，则表示应禁用模块缓存。

supports_isolated_interpreters 是一个布尔值，表示此实现是否支持多个隔离解释器。对于大多数平台上的 CPython，它为 True。支持此功能的平台实现了低级 _interpreters 模块。

参见

PEP 684、PEP 734 和 concurrent.interpreters。

sys.implementation 可能包含特定于 Python 实现的其他属性。这些非标准属性必须以下划线开头，此处不作描述。无论其内容如何，sys.implementation 在解释器运行期间或在实现版本之间都不会更改。（但是，它可能在 Python 语言版本之间发生更改。）有关更多信息，请参阅 PEP 421。

在 3.3 版本加入。

3.14 版本中的变化: 添加了 supports_isolated_interpreters 字段。

备注

添加新的必需属性必须通过正常的 PEP 流程。有关更多信息，请参阅 PEP 421。

sys.int_info

一个 命名元组，包含有关 Python 内部整数表示的信息。属性是只读的。

int_info.bits_per_digit

每个数字中包含的位数。Python 整数在内部以 2**int_info.bits_per_digit 为基数存储。

int_info.sizeof_digit

用于表示数字的 C 类型的大小（以字节为单位）。

int_info.default_max_str_digits

当未明确配置时，sys.get_int_max_str_digits() 的默认值。

int_info.str_digits_check_threshold

sys.set_int_max_str_digits()、PYTHONINTMAXSTRDIGITS 或 -X int_max_str_digits 的最小非零值。

在 3.1 版本加入。

3.11 版本中的变化: 添加了 default_max_str_digits 和 str_digits_check_threshold。

sys.__interactivehook__

当此属性存在时，当解释器以 交互模式 启动时，其值会自动调用（不带参数）。这在读取 PYTHONSTARTUP 文件之后进行，这样您就可以在那里设置此钩子。site 模块设置此项。

当钩子在启动时被调用时，引发一个带钩子对象作为参数的 审计事件 cpython.run_interactivehook。

在 3.4 版本加入。

sys.intern(string)

将 string 输入“驻留”字符串表并返回驻留字符串——即 string 本身或其副本。驻留字符串对于字典查找可以提高一点性能——如果字典中的键是驻留的，并且查找键也是驻留的，则键比较（在哈希之后）可以通过指针比较而不是字符串比较来完成。通常，Python 程序中使用的名称会自动驻留，并且用于保存模块、类或实例属性的字典具有驻留键。

驻留字符串不是 永恒的；您必须保留对 intern() 返回值的引用才能从中受益。

sys._is_gil_enabled()

如果 GIL 已启用，则返回 True；如果已禁用，则返回 False。

在 3.13 版本加入。

CPython 实现细节： 它不保证在所有 Python 实现中都存在。

sys.is_finalizing()

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

另请参阅 PythonFinalizationError 异常。

在 3.5 版本加入。

sys._jit

用于观察即时编译的实用工具。

CPython 实现细节： JIT 编译是 CPython 的一个 实验性实现细节。sys._jit 不保证在所有 Python 实现、版本或构建配置中都存在或以相同方式运行。

在 3.14 版本加入。

_jit.is_available()

如果当前的 Python 可执行文件支持 JIT 编译，则返回 True，否则返回 False。这可以通过在 Windows 上使用 --experimental-jit 选项，在所有其他平台上使用 --enable-experimental-jit 选项构建 CPython 来控制。

_jit.is_enabled()

如果当前 Python 进程已启用 JIT 编译（意味着 sys._jit.is_available()），则返回 True，否则返回 False。如果 JIT 编译可用，可以通过在解释器启动时将 PYTHON_JIT 环境变量设置为 0（禁用）或 1（启用）来控制。

_jit.is_active()

如果最顶层的 Python 帧当前正在执行 JIT 代码（意味着 sys._jit.is_enabled()），则返回 True，否则返回 False。

备注

此函数仅用于测试和调试 JIT 本身。应避免用于任何其他目的。

备注

由于追踪 JIT 编译器的特性，重复调用此函数可能会产生令人惊讶的结果。例如，根据其返回值进行分支很可能导致意外行为（如果这样做会导致 JIT 代码进入或退出）。

>>> for warmup in range(BIG_NUMBER):
...     # This line is "hot", and is eventually JIT-compiled:
...     if sys._jit.is_active():
...         # This line is "cold", and is run in the interpreter:
...         assert sys._jit.is_active()
...
Traceback (most recent call last):
  File "<stdin>", line 5, in <module>
    assert sys._jit.is_active()
           ~~~~~~~~~~~~~~~~~~^^
AssertionError

sys.last_exc

此变量并非总是定义；当异常未处理且解释器打印错误消息和栈回溯时，它被设置为异常实例。其目的是允许交互用户导入调试器模块并进行事后调试，而无需重新执行导致错误的命令。（典型用法是 import pdb; pdb.pm() 以进入事后调试器；有关更多信息，请参阅 pdb 模块。）

3.12 新版功能.

sys._is_immortal(op)

如果给定对象是 永恒的，则返回 True，否则返回 False。

备注

对于不朽对象（因此传递给此函数时返回 True），不保证在未来版本中仍然不朽，对于有限对象也是如此。

在 3.14 版本加入。

CPython 实现细节： 此函数仅应用于特殊目的。它不保证在所有 Python 实现中都存在。

sys._is_interned(string)

如果给定的字符串是“驻留的”，则返回 True，否则返回 False。

在 3.13 版本加入。

CPython 实现细节： 它不保证在所有 Python 实现中都存在。

sys.last_type

sys.last_value

sys.last_traceback

这三个变量已弃用；请改用 sys.last_exc。它们保存了 sys.last_exc 的旧版表示，如上文 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() 方法会被调用，以查看其中一个对象是否可以找到要导入的模块。默认情况下，它包含实现 Python 默认导入语义的条目。调用 find_spec() 方法时至少会传入要导入模块的绝对名称。如果被导入模块包含在一个包中，则父包的 __path__ 属性将作为第二个参数传入。该方法返回一个 模块规格，如果找不到模块则返回 None。

参见

importlib.abc.MetaPathFinder

定义 meta_path 上查找器对象接口的抽象基类。

importlib.machinery.ModuleSpec

find_spec() 应该返回其实例的具体类。

3.4 版本中的变化: 模块规格 在 Python 3.4 中由 PEP 451 引入。

3.12 版本中的变化: 如果 meta_path 条目没有 find_spec() 方法，则移除了寻找 find_module() 方法的备用方案。

sys.modules

这是一个字典，将模块名称映射到已加载的模块。它可以被操作以强制重新加载模块和其他技巧。然而，替换字典不一定会按预期工作，并且从字典中删除基本项可能导致 Python 失败。如果要遍历此全局字典，请始终使用 sys.modules.copy() 或 tuple(sys.modules) 以避免异常，因为其大小可能在迭代期间因代码或其他线程中的活动而更改。

sys.orig_argv

传递给 Python 可执行文件的原始命令行参数列表。

sys.orig_argv 的元素是 Python 解释器的参数，而 sys.argv 的元素是用户程序的参数。解释器本身消耗的参数将出现在 sys.orig_argv 中，并从 sys.argv 中缺失。

在 3.10 版本加入。

sys.path

一个字符串列表，指定模块的搜索路径。从环境变量 PYTHONPATH 以及一个与安装相关的默认值初始化。

默认情况下，在程序启动时初始化时，一个潜在不安全的路径会预置到 sys.path（在 因 PYTHONPATH 而插入的条目之前）

• python -m module 命令行：预置当前工作目录。

• python script.py 命令行：预置脚本的目录。如果是符号链接，则解析符号链接。

• python -c code 和 python (REPL) 命令行：预置空字符串，表示当前工作目录。

要不预置此潜在不安全的路径，请使用 -P 命令行选项或 PYTHONSAFEPATH 环境变量。

程序可以自由修改此列表以达到自己的目的。只有字符串应添加到 sys.path；所有其他数据类型在导入期间将被忽略。

参见

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

sys.path_hooks

一个可调用对象列表，它们接受一个路径参数，尝试为该路径创建一个 查找器。如果可以创建查找器，则由可调用对象返回，否则引发 ImportError。

最初在 PEP 302 中指定。

sys.path_importer_cache

一个字典，用作 查找器 对象的缓存。键是已传递给 sys.path_hooks 的路径，值是找到的查找器。如果路径是有效的文件系统路径，但在 sys.path_hooks 上没有找到查找器，则存储 None。

最初在 PEP 302 中指定。

sys.platform

一个包含平台标识符的字符串。已知的值如下：

系统	platform 值
AIX	'aix'
Android	'android'
Emscripten	'emscripten'
FreeBSD	'freebsd'
iOS	'ios'
Linux	'linux'
macOS	'darwin'
Windows	'win32'
Windows/Cygwin	'cygwin'
WASI	'wasi'

在表中未列出的 Unix 系统上，该值为 uname -s 返回的小写 OS 名称，并附加 uname -r 返回的版本的第一部分，例如 'sunos5'，在 Python 构建时。除非您想测试特定的系统版本，否则建议使用以下惯用法：

if sys.platform.startswith('sunos'):
    # SunOS-specific code here...

3.3 版本中的变化: 在 Linux 上，sys.platform 不再包含主版本号。它总是 'linux'，而不是 'linux2' 或 'linux3'。

3.8 版本中的变化: 在 AIX 上，sys.platform 不再包含主版本号。它总是 'aix'，而不是 'aix5' 或 'aix7'。

3.13 版本中的变化: 在 Android 上，sys.platform 现在返回 'android' 而不是 'linux'。

3.14 版本中的变化: 在 FreeBSD 上，sys.platform 不再包含主要版本号。它总是 'freebsd'，而不是 'freebsd13' 或 'freebsd14'。

参见

os.name 具有更粗的粒度。os.uname() 提供与系统相关的版本信息。

platform 模块提供了对系统身份的详细检查。

sys.platlibdir

平台特定库目录的名称。它用于构建标准库的路径和已安装扩展模块的路径。

在大多数平台上，它等于 "lib"。在 Fedora 和 SuSE 上，在 64 位平台上它等于 "lib64"，这会产生以下 sys.path 路径（其中 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 文件安装的站点特定目录前缀；在 Unix 上，默认值为 /usr/local。这可以在构建时使用 configure 脚本的 --prefix 参数进行设置。有关派生路径的信息，请参阅 安装路径。

备注

如果 虚拟环境 生效，此 prefix 将指向虚拟环境。Python 安装的值仍可通过 base_prefix 获得。有关更多信息，请参阅 虚拟环境。

3.14 版中已更改: 在虚拟环境下运行时，prefix 和 exec_prefix 现在由路径初始化设置为虚拟环境前缀，而不是 site。这意味着 prefix 和 exec_prefix 始终指向虚拟环境，即使 site 被禁用 (-S) 也是如此。

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.set_int_max_str_digits(maxdigits)

设置此解释器使用的 整数字符串转换长度限制。另请参见 get_int_max_str_digits()。

在 3.11 版本中新增。

sys.setprofile(profilefunc)

设置系统的配置文件函数，它允许您用 Python 实现一个 Python 源代码分析器。有关 Python 分析器的更多信息，请参阅 Python 分析器 一章。系统的配置文件函数的调用方式类似于系统的跟踪函数（参见 settrace()），但它是用不同的事件调用的，例如，它不会为每个执行的代码行调用（只在调用和返回时调用，但即使已设置异常，也会报告返回事件）。该函数是线程特定的，但分析器无法知道线程之间的上下文切换，因此在存在多个线程的情况下使用它没有意义。此外，它的返回值不使用，因此它可以简单地返回 None。配置文件函数中的错误将导致其自身取消设置。

备注

与 settrace() 相同，setprofile() 也使用相同的跟踪机制。要在跟踪函数（例如在调试器断点中）内部使用 setprofile() 跟踪调用，请参见 call_tracing()。

配置文件函数应有三个参数：frame、event 和 arg。frame 是当前栈帧。event 是一个字符串：'call'、'return'、'c_call'、'c_return' 或 'c_exception'。arg 取决于事件类型。

事件的含义如下

'call'

函数被调用（或进入其他代码块）。配置文件函数被调用；arg 为 None。

'return'

函数（或其他代码块）即将返回。配置文件函数被调用；arg 是将返回的值，如果事件是由引发异常引起的，则为 None。

'c_call'

C 函数即将被调用。这可能是扩展函数或内置函数。arg 是 C 函数对象。

'c_return'

C 函数已返回。arg 是 C 函数对象。

'c_exception'

C 函数已引发异常。arg 是 C 函数对象。

引发一个不带参数的 审计事件 sys.setprofile。

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 取决于事件类型。

每当进入新的局部作用域时，跟踪函数就会被调用（event 设置为 'call'）；它应该返回一个引用，指向用于新作用域的局部跟踪函数，或者如果该作用域不应被跟踪，则返回 None。

局部跟踪函数应返回对自身的引用，或返回对另一个函数的引用，该函数将用作该作用域的局部跟踪函数。

如果在跟踪函数中发生任何错误，它将被取消设置，就像调用了 settrace(None) 一样。

备注

在调用跟踪函数时（例如，通过 settrace() 设置的函数），跟踪功能被禁用。有关递归跟踪的信息，请参阅 call_tracing()。

事件的含义如下

'call'

调用函数（或进入其他代码块）。全局跟踪函数被调用；arg 为 None；返回值指定局部跟踪函数。

'line'

解释器即将执行一行新代码或重新执行循环条件。局部跟踪函数被调用；arg 为 None；返回值指定新的局部跟踪函数。有关其工作原理的详细解释，请参见 Objects/lnotab_notes.txt。可以通过将 f_trace_lines 设置为该 帧 上的 False 来禁用帧的逐行事件。

'return'

一个函数（或其它代码块）即将返回。局部跟踪函数被调用；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 实现细节： 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.activate_stack_trampoline(backend, /)

激活栈分析器跳板 backend。唯一支持的后端是 "perf"。

如果 JIT 处于活动状态，则无法激活栈跳板。

可用性: Linux。

3.12 新版功能.

参见

• Python 对 Linux perf 分析器的支持

• https://perf.wiki.kernel.org

sys.deactivate_stack_trampoline()

停用当前的栈分析器跳板后端。

如果未激活栈分析器，此函数无效。

可用性: Linux。

3.12 新版功能.

sys.is_stack_trampoline_active()

如果栈分析器跳板处于活动状态，则返回 True。

可用性: Linux。

3.12 新版功能.

sys.remote_exec(pid, script)

在给定 pid 的远程进程中执行包含 Python 代码的文件 script。

此函数立即返回，代码将在目标进程的主线程在下一个可用机会执行，类似于信号的处理方式。没有接口可以确定代码何时已执行。调用者负责确保文件在远程进程尝试读取时仍然存在，并且没有被覆盖。

远程进程必须运行与本地进程相同主要和次要版本的 CPython 解释器。如果本地或远程解释器是预发布版本（alpha、beta 或候选版本），则本地和远程解释器必须是完全相同的版本。

当代码在远程进程中执行时，会引发一个 审计事件 sys.remote_exec，带有 pid 和脚本文件的路径。此事件在调用 sys.remote_exec() 的进程中引发。

当脚本在远程进程中执行时，会引发一个 审计事件 cpython.remote_debugger_script，带有远程进程中的路径。此事件在远程进程中引发，而不是调用 sys.remote_exec() 的进程中引发。

可用性: Unix, Windows。

在 3.14 版本加入。

sys._enablelegacywindowsfsencoding()

将 文件系统编码和错误处理程序 分别更改为 'mbcs' 和 'replace'，以与 Python 3.6 之前的版本保持一致。

这相当于在启动 Python 之前定义 PYTHONLEGACYWINDOWSFSENCODING 环境变量。

另请参阅 sys.getfilesystemencoding() 和 sys.getfilesystemencodeerrors()。

可用性: Windows。

备注

Python 启动后更改文件系统编码有风险，因为旧的 fsencoding 或由旧的 fsencoding 编码的路径可能已缓存在某个地方。请改用 PYTHONLEGACYWINDOWSFSENCODING。

版本 3.6 新增: 有关详情，请参阅 PEP 529。

从 3.13 版本开始废弃，将在 3.16 版本移除: 请改用 PYTHONLEGACYWINDOWSFSENCODING。

sys.stdin

sys.stdout

sys.stderr

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

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

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

• 解释器自身的提示符及其错误消息输出到 stderr。

这些流是常规的文本文件，类似于 open() 函数返回的文件。它们的参数选择如下：

• 编码和错误处理通过 PyConfig.stdio_encoding 和 PyConfig.stdio_errors 进行初始化。

  在 Windows 上，控制台设备使用 UTF-8。非字符设备，例如磁盘文件和管道，使用系统区域设置编码（即 ANSI 代码页）。非控制台字符设备，例如 NUL（即 isatty() 返回 True 的情况），分别使用启动时的控制台输入和输出代码页的值作为 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 应用程序以及使用 pythonw 启动的 Python 应用程序。

sys.stdlib_module_names

一个包含标准库模块名称的冻结集合 (frozenset)。

它在所有平台上都是相同的。在某些平台上不可用的模块和在 Python 构建时禁用的模块也都会列出。列出了所有模块类型：纯 Python、内置、冻结和扩展模块。测试模块被排除在外。

对于包，只列出主包：子包和子模块不列出。例如，email 包被列出，但 email.mime 子包和 email.message 子模块不列出。

另请参阅 sys.builtin_module_names 列表。

在 3.10 版本加入。

sys.thread_info

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

thread_info.name

线程实现的名称

• "nt": Windows 线程

• "pthread": POSIX 线程

• "pthread-stubs": 存根 POSIX 线程 (在不支持线程的 WebAssembly 平台上)

• "solaris": Solaris 线程

thread_info.lock

锁实现的名称

• "semaphore": 锁使用信号量

• "mutex+cond": 锁使用互斥锁和条件变量

• 如果此信息未知，则为 None

thread_info.version

线程库的名称和版本。它是一个字符串，如果此信息未知，则为 None。

在 3.3 版本加入。

sys.tracebacklimit

当此变量设置为整数值时，它决定了当发生未处理异常时打印的回溯信息的最大层数。默认值为 1000。当设置为 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() 可以被覆盖以控制无法引发的异常如何处理。

参见

excepthook() 处理未捕获的异常。

警告

使用自定义钩子存储 exc_value 可能会创建引用循环。当不再需要异常时，应明确清除它以打破引用循环。

使用自定义钩子存储 object 可能会使其复活，如果它被设置为正在终结化的对象。为避免对象复活，请在自定义钩子完成后避免存储 object。

当发生无法处理的异常时，引发审计事件 sys.unraisablehook，参数为 hook, unraisable。unraisable 对象与将传递给钩子的对象相同。如果没有设置钩子，hook 可能为 None。

在 3.8 版本加入。

sys.version

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

sys.api_version

C API 版本，等同于 C 宏 PYTHON_API_VERSION。为向后兼容而定义。

目前，此常量在新的 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 存储。该值通常是正在运行的 Python 解释器的主版本号和次版本号。它在 sys 模块中提供以供信息参考；修改此值对 Python 使用的注册表键没有影响。

可用性: Windows。

sys.monitoring

包含用于注册回调和控制监视事件的函数和常量的命名空间。详见 sys.monitoring。

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 实现细节: 这是 CPython 特有的访问通过 -X 传递的选项的方式。其他实现可能通过其他方式导出它们，或者根本不导出。

在 3.2 版本加入。

引文

[C99]

ISO/IEC 9899:1999。“编程语言 – C。”该标准的公开草案可在 https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf 处获得。