sys —系统特定的参数和Function

该模块提供对解释器使用或维护的某些变量以及与解释器强烈交互的Function的访问。它始终可用。

在 3.8 版中进行了更改：默认标志变为空字符串(已删除 pymalloc 的m标志)。

3.2 版中的新Function。

passsys.audit()函数引发审核事件时，将按照添加事件名称和参数 Tuples 的 Sequences 调用每个钩子。首先调用由PySys_AddAuditHook()添加的本机钩子，然后再调用当前解释器中添加的钩子。

引发不带任何参数的审核事件sys.addaudithook。如果任何现有的钩子引发了从RuntimeError派生的异常，则不会添加新的钩子，并且将抑制该异常。如此一来，除非调用者控制所有现有的钩子，否则无法假定他们的钩子已添加。

3.8 版的新Function。

在版本 3.8.1 中进行了更改：不再禁止从Exception而非RuntimeError派生的异常。

CPython 实现细节： 启用跟踪(请参阅settrace())时，仅在可调用对象的__cantrace__成员设置为 true 值时才跟踪 Python 钩子。否则，跟踪Function将跳过该钩子。

要遍历标准 Importing 或命令行上给出的文件列表，请参阅fileinput模块。

Note

在 Unix 上，命令行参数由 OS 中的字节传递。 Python 使用文件系统编码和“ surrogateescape”错误处理程序对它们进行解码。当您需要原始字节时，可以pass[os.fsencode(arg) for arg in sys.argv]获得它。

此函数将引发任何钩子引发的第一个异常。通常，不应处理这些错误，而应尽快终止该过程。

钩子是使用sys.addaudithook()或PySys_AddAuditHook()函数添加的。

该函数的本机等效值为PySys_Audit()。尽可能使用本机函数。

有关 CPython 引发的所有事件，请参见审核事件表。

3.8 版的新Function。

版本 3.3 中的新Function。

版本 3.3 中的新Function。

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

这对于调试死锁最有用：此函数不需要死锁线程的配合，并且只要这些线程的调用堆栈保持死锁状态，它们就会被冻结。在调用代码检查帧时，为非死锁线程返回的框架可能与该线程的当前活动没有任何关系。

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

引发不带参数的auditing event sys._current_frames。

该函数的签名取决于其调用的内容。例如，默认绑定(例如pdb.set_trace())不包含任何参数，但是您可以将其绑定到需要附加参数(位置和/或关键字)的函数。内置的breakpoint()函数将其*args和**kws直接传递。 breakpointhooks()返回的所有内容均从breakpoint()返回。

默认实现首先查询环境变量 PYTHONBREAKPOINT。如果将其设置为"0"，则此函数立即返回；否则，返回 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 版中的新Function。

如果将 Python 配置为–with-pydebug，它还将执行一些昂贵的内部一致性检查。

版本 3.3 中的新Function。

CPython 实现细节： 此函数特定于 CPython。此处未定义确切的输出格式，并且可能会更改。

Availability: Windows.

评估在交互式 Python 会话中 Importing 的expression的结果将调用sys.displayhook。这些值的显示可以pass向sys.displayhook分配另一个单参数函数来定制。

Pseudo-code:

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'错误处理程序。

相对路径相对于当前工作目录进行解释。

最初基于-X pycache_prefix=PATH命令行选项或 PYTHONPYCACHEPREFIX环境变量的值(命令行优先)设置此值。如果两者均未设置，则为None。

3.8 版的新Function。

当引发并捕获异常时，解释器将调用带有三个参数的sys.excepthook，异常类，异常实例和回溯对象。在交互式会话中，这恰好在控制权返回到提示之前发生。在 Python 程序中，这恰好在程序退出之前发生。可以pass为sys.excepthook分配另一个三参数函数来定制此类顶级异常的处理。

当发生未捕获的异常时，使用参数hook，type，value，traceback引发审核事件sys.excepthook。如果未设置任何钩子，则hook可能是None。如果任何钩子引发了从RuntimeError派生的异常，则将禁止对该钩子的调用。否则，审计钩子异常将被报告为无法举报，并将调用sys.excepthook。

See also

sys.unraisablehook()函数处理无法提出的异常，而threading.excepthook()函数处理由threading.Thread.run()引发的异常。

3.7 版中的新Function：breakpointhook

3.8 版的新Function：unraisablehook

如果堆栈上任何地方都没有异常处理，则返回包含三个None值的 Tuples。否则，返回的值为(type, value, traceback)。它们的含义是：* type *获取正在处理的异常的类型(BaseException的子类)； * value *获取异常实例(异常类型的实例)； * traceback *得到一个traceback object，该traceback object在最初发生异常的位置封装了调用堆栈。

Note

如果virtual environment有效，则此值将在site.py中更改为指向虚拟环境。passbase_exec_prefix，Python 安装的值仍然可用。

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

由于exit()finally“仅”引发异常，因此它仅在从主线程调用时才退出进程，并且不会拦截该异常。

在版本 3.6 中进行了更改：如果 Python 解释器捕获到SystemExit之后清除过程中发生错误(例如错误清除标准流中的缓冲数据)，则退出状态将更改为 120.

attribute flag
debug -d
inspect -i
interactive -i
isolated -I
optimize -O或-OO
dont_write_bytecode -B
no_user_site -s
no_site -S
ignore_environment -E
verbose -v
bytes_warning -b
quiet -q
hash_randomization -R
dev_mode -X dev
utf8_mode -X utf8

在版本 3.2 中进行了更改：为新的-q标志添加了quiet属性。

版本 3.2.3 中的新Function：hash_randomization属性。

在版本 3.3 中更改：删除了过时的division_warning属性。

在版本 3.4 中进行了更改：为-I isolated标志添加了isolated属性。

在版本 3.7 中进行了更改：为新的-X dev标志添加了dev_mode属性，为新的-X utf8标志添加了utf8_mode属性。

attribute float.h macro explanation
epsilon DBL_EPSILON 1.0 和大于 1.0 的最小值之间的差，可以表示为浮点数
dig DBL_DIG 浮点数中可以如实表示的最大十进制数字；见下文
mant_dig DBL_MANT_DIG 浮点数精度：浮点数有效位数的基数radix
max DBL_MAX 可表示的最大正有限浮点数
max_exp DBL_MAX_EXP 最大整数* e *，使得radix**(e-1)是可表示的有限浮点数
max_10_exp DBL_MAX_10_EXP 最大整数* e *，以使10**e在可表示的有限浮点数范围内
min DBL_MIN 最小可表示正标准化浮点数
min_exp DBL_MIN_EXP 最小整数* e *，使得radix**(e-1)是规范化的浮点数
min_10_exp DBL_MIN_10_EXP 最小整数* e *，使得10**e是规范化的浮点数
radix FLT_RADIX 指数表示基数
rounds FLT_ROUNDS 整数常数，表示用于算术运算的舍入模式。这反映了解释器启动时系统 FLT_ROUNDS 宏的值。有关可能的值及其含义的说明，请参见 C99 标准的 5.2.4.2.2 节。

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

3.1 版中的新Function。

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

3.4 版的新Function。

Availability: Android.

3.7 版中的新Function。

从 3.2 版开始不推荐使用：改为使用getswitchinterval()。

Availability: Unix.

此编码始终是 ASCII 兼容的。

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

在版本 3.2 中更改：getfilesystemencoding()结果不能再None。

在版本 3.6 中进行了更改：不再保证 Windows 返回'mbcs'。有关更多信息，请参见 PEP 529和_enablelegacywindowsfsencoding()。

在 3.7 版中进行了更改：以 UTF-8 模式返回“ utf-8”。

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

3.6 版的新Function。

仅考虑直接归因于对象的内存消耗，而不考虑它所引用的对象的内存消耗。

如果给定，如果对象不提供检索大小的方法，则将返回* default *。否则将引发TypeError。

getsizeof()调用对象的__sizeof__方法，如果该对象由垃圾收集器 Management，则会增加额外的垃圾收集器开销。

有关以递归方式使用getsizeof()查找容器大小及其所有内容的示例，请参见配方的递归大小。

3.2 版中的新Function。

引发不带参数的auditing event sys._getframe。

CPython 实现细节： 此函数应仅用于内部和专用目的。不能保证它在所有 Python 实现中都存在。

CPython 实现细节： gettrace()函数仅用于实现调试器，事件探查器，覆盖率工具等。它的行为是实现平台的一部分，而不是语言定义的一部分，因此可能并非在所有 Python 实现中都可用。

平台将为2 (VER_PLATFORM_WIN32_NT)。

Constant Meaning
1 (VER_NT_WORKSTATION) 该系统是工作站。
2 (VER_NT_DOMAIN_CONTROLLER) 该系统是域控制器。
3 (VER_NT_SERVER) 系统是服务器，而不是域控制器。

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

Availability: Windows.

在版本 3.2 中更改：更改为命名 Tuples，并添加了* service_pack_minor ， service_pack_major ， suite_mask 和 product_type *。

在版本 3.6 中更改：添加了* platform_version *

3.6 版的新Function：有关更多详细信息，请参见 PEP 525。

Note

此Function已临时添加(有关详细信息，请参见 PEP 411。)

3.7 版中的新Function。

Note

此Function是临时添加的(有关详细信息，请参见 PEP 411。)仅将其用于调试目的。

attribute explanation
width 用于哈希值的位宽
modulus 用于数值哈希方案的素数模数 P
inf 返回正整数的哈希值
nan 为 nan 返回的哈希值
imag 用于复数虚部的乘数
algorithm 散列 str，字节和 memoryview 的算法的名称
hash_bits 哈希算法的内部输出大小
seed_bits 哈希算法的种子密钥的大小

3.2 版中的新Function。

在版本 3.4 中更改：添加了* algorithm ， hash_bits 和 seed_bits *

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

之所以称为hexversion，是因为将其传递给内置的hex()函数时，它看上去才有意义。 named tuple sys.version_info可用于对相同信息进行更人性化的编码。

有关hexversion的更多详细信息，请参见API 和 ABI 版本控制。

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

版本 3.3 中的新Function。

Note

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

Attribute Explanation
bits_per_digit 每个数字中保留的位数。 Python 整数内部存储在基本2**int_info.bits_per_digit中
sizeof_digit 用于表示数字的 C 类型的字节大小

3.1 版中的新Function。

在启动时调用钩子时，以钩子对象作为参数引发auditing event cpython.run_interactivehook。

3.4 版的新Function。

实习弦不是不朽的。您必须保留对返回值intern()的引用才能从中受益。

3.5 版中的新Function。

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

在版本 3.3 中进行了更改： PEP 393之前的sys.maxunicode以前是0xFFFF或0x10FFFF，具体取决于指定将 Unicode 字符存储为 UCS-2 还是 UCS-4 的配置选项。

See also

在版本 3.4 中进行了更改： PEP 451在 python 3.4 中引入了Module specs。早期版本的 Python 寻找一种名为find_module()的方法。如果meta_path条目没有find_spec()方法，则仍称为备用。

在程序启动时初始化，此列表的第一项path[0]是包含用于调用 Python 解释器的脚本的目录。如果脚本目录不可用(例如，如果交互式调用解释器或从标准 Importing 中读取脚本)，则path[0]为空字符串，它将引导 Python 首先搜索当前目录中的模块。请注意，脚本目录是在 PYTHONPATH结果插入的条目之前*插入的。

程序可以出于自己的目的随意修改此列表。仅字符串和字节应添加到sys.path；导入期间将忽略所有其他数据类型。

See also

模块site介绍了如何使用.pth 文件扩展sys.path。

最初在 PEP 302中指定。

最初在 PEP 302中指定。

在版本 3.3 中更改：未找到查找器时，将存储None而不是imp.NullImporter。

对于 Unix 系统，除了 Linux 和 AIX 以外，这是uname -s返回的小写 os 名称，并附加了uname -r返回的版本的第一部分，例如。 'sunos5'或'freebsd8'，在构建 Python 时。除非您要测试特定的系统版本，否则建议使用以下习惯用法：

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...

对于其他系统，值是：

System platform值
AIX 'aix'
Linux 'linux'
Windows 'win32'
Windows/Cygwin 'cygwin'
macOS 'darwin'

在版本 3.3 中进行了更改：在 Linux 上，sys.platform不再包含主版本。它始终是'linux'，而不是'linux2'或'linux3'。由于旧的 Python 版本包含版本号，因此建议始终使用上面介绍的startswith习惯用法。

在 3.8 版中进行了更改：在 AIX 上，sys.platform不再包含主版本。它始终是'aix'，而不是'aix5'或'aix7'。由于旧的 Python 版本包含版本号，因此建议始终使用上面介绍的startswith习惯用法。

See also

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

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

Note

如果virtual environment有效，则此值将在site.py中更改为指向虚拟环境。passbase_prefix，Python 安装的值仍然可用。

从版本 3.2 开始不推荐使用：此Function不再起作用，因为用于线程切换和异步任务的内部逻辑已被重写。请改用setswitchinterval()。

Availability: Unix.

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

引发不带参数的auditing event sys.setprofile。

这些事件具有以下含义：

可能的最高限制取决于平台。当用户拥有需要深度递归的程序和支持更高限制的平台时，他们可能需要将限制设置为更高。这应该谨慎进行，因为过高的限制可能会导致崩溃。

如果在当前递归深度下新的限制太低，则会引发RecursionError异常。

在版本 3.5.1 中进行了更改：如果在当前递归深度下新的限制太低，则会引发RecursionError异常。

3.2 版中的新Function。

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

每当 Importing 新的本地范围时，都会调用 trace 函数(* event *设置为'call')。它应该返回对要用于新范围的本地跟踪函数的引用；如果不应该跟踪该范围，则应返回None。

本地跟踪函数应返回对自身的引用(或对另一个函数的引用，以在该范围内进行进一步的跟踪)，或者返回None以关闭该范围内的跟踪。

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

这些事件具有以下含义：

请注意，由于异常是在调用者链中传播的，因此在每个级别都会生成'exception'事件。

对于更细粒度的用法，可以pass显式分配frame.f_trace = tracefunc来设置跟踪函数，而不是依赖于pass已安装的跟踪函数的返回值间接设置它。这对于激活当前帧上的跟踪Function也是必需的，而settrace()则不行。请注意，为了使它起作用，必须启用settrace()来安装全局跟踪Function才能启用运行时跟踪机制，但是它不必是相同的跟踪Function(例如，它可以是开销较低的跟踪Function只需返回None即可在每个帧上立即禁用自身)。

有关代码和框架对象的更多信息，请参见标准类型层次结构。

引发不带参数的auditing event sys.settrace。

CPython 实现细节： settrace()函数仅用于实现调试器，事件探查器，覆盖率工具等。它的行为是实现平台的一部分，而不是语言定义的一部分，因此可能并非在所有 Python 实现中都可用。

在 3.7 版中进行了更改：添加了'opcode'事件类型； f_trace_lines和f_trace_opcodes属性已添加到框架

引发不带参数的auditing event sys.set_asyncgen_hooks_firstiter。

引发不带参数的auditing event sys.set_asyncgen_hooks_finalizer。

引发两个审核事件，因为基础 API 由两个调用组成，每个调用必须引发自己的事件。

3.6 版的新Function：有关更多详细信息，请参见 PEP 525，有关* finalizer *方法的参考示例，请参见Lib/asyncio/base_events.py中asyncio.Loop.shutdown_asyncgens的实现

Note

此Function已临时添加(有关详细信息，请参见 PEP 411。)

要启用，请传递大于零的* depth *值；这设置了将捕获其信息的帧数。要禁用，请将“深度”设置为零。

此设置是特定于线程的。

3.7 版中的新Function。

Note

此Function是临时添加的(有关详细信息，请参见 PEP 411。)仅将其用于调试目的。

这等效于启动 Python 之前定义 PYTHONLEGACYWINDOWSFSENCODING环境变量。

Availability: Windows.

3.6 版的新Function：有关更多详细信息，请参见 PEP 529。

这些流是常规text files，就像open()函数返回的一样。它们的参数选择如下：

在 Windows 上，UTF-8 用于控制台设备。非字符设备(例如磁盘文件和管道)使用系统区域设置编码(即 ANSI 代码页)。非控制台字符设备(例如 NUL(即isatty()返回True的地方))在启动时分别使用控制台 Importing 和输出代码页的值(分别用于 stdin 和 stdout/stderr)。如果进程最初未附加到控制台，则默认为系统区域设置编码。

可以pass在启动 Python 之前设置环境变量 PYTHONLEGACYWINDOWSSTDIO 来覆盖控制台的特殊行为。在这种情况下，控制台代码页将与其他任何字符设备一样使用。

在所有平台上，您可以pass在启动 Python 之前设置 PYTHONIOENCODING环境变量或使用新的-X utf8命令行选项和 PYTHONUTF8环境变量来覆盖字符编码。但是，对于 Windows 控制台，这仅在还设置了 PYTHONLEGACYWINDOWSSTDIO时适用。

Note

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

但是，如果您正在编写一个库(并且不控制在哪个上下文中执行其代码)，请注意，标准流可能被不支持buffer属性的类似文件的对象如io.StringIO代替。

如果实际文件已被损坏的对象覆盖，它也可以用于将实际文件还原到已知的工作文件对象。但是，执行此操作的首选方法是在替换之前的流之前显式保存它，并还原保存的对象。

Note

在某些情况下stdin，stdout和stderr以及原始值__stdin__，__stdout__和__stderr__可以是None。对于未连接到控制台的 Windows GUI 应用程序以及以 pythonw 开头的 Python 应用程序，通常是这种情况。

Attribute Explanation
name 线程实现的名称：


Note





'nt'：Windows 线程

> 'pthread'：POSIX 线程

> 'solaris'：Solaris 线程



|
| lock |锁定实现的名称：

> [!NOTE]




'semaphore'：锁使用 signal 量

> 'mutex+cond'：锁使用互斥锁和条件变量

> None(如果此信息未知)



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

版本 3.3 中的新Function。

当发生异常但 Python 无法处理它时调用。例如，当析构函数引发异常时或在垃圾回收期间(gc.collect())。

默认的钩子格式* err_msg 和 object 为：f'{err_msg}: {object!r}';如果 err_msg *为None，请使用“忽略异常中”错误消息。

可以重写sys.unraisablehook()来控制如何处理无法提出的异常。

使用自定义钩子存储* exc_value *可以创建参考周期。当不再需要异常时，应明确清除它以 break 参考周期。

如果将* object 设置为finally确定的对象，则使用自定义钩子存储 object 可以使它复活。避免在自定义钩子完成后存储 object *，以免复活对象。

另请参见excepthook()处理未捕获的异常。

当发生无法处理的异常时，使用参数hook，unraisable引发审核事件sys.unraisablehook。 unraisable对象与将传递给该钩子的对象相同。如果未设置任何钩子，则hook可能是None。

3.8 版的新Function。

在版本 3.1 中进行了更改：添加了命名组件属性。

Availability: Windows.

$ ./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 实现细节： 这是访问-X传递的选项的特定于 CPython 的方式。其他实现可能pass其他方式或根本不导出。

3.2 版中的新Function。

Citations

首页