sys — 系统特定参数和函数


此模块提供对解释器使用或维护的一些变量的访问,以及与解释器强烈交互的函数。它始终可用。

sys.abiflags

在使用标准 configure 脚本构建 Python 的 POSIX 系统上,它包含由 PEP 3149 指定的 ABI 标志。

在版本 3.2 中添加。

在版本 3.8 中更改: 默认标志变为空字符串 (m 用于 pymalloc 的标志已删除)。

可用性: 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 上,命令行参数由 OS 从字节传递。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

在 Python 启动期间,在运行 site.py 之前,将其设置为与 exec_prefix 相同的值。如果不在 虚拟环境 中运行,则这些值将保持不变;如果 site.py 发现正在使用虚拟环境,则 prefixexec_prefix 的值将更改为指向虚拟环境,而 base_prefixbase_exec_prefix 将继续指向基础 Python 安装(创建虚拟环境的安装)。

在 3.3 版本中添加。

sys.base_prefix

在 Python 启动期间,在运行 site.py 之前,将其设置为与 prefix 相同的值。如果不在 虚拟环境 中运行,则这些值将保持不变;如果 site.py 发现正在使用虚拟环境,则 prefixexec_prefix 的值将更改为指向虚拟环境,而 base_prefixbase_exec_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()

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

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

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**kwsbreakpointhooks() 返回的内容将从 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 文件。此值最初设置为 TrueFalse,具体取决于 -B 命令行选项和 PYTHONDONTWRITEBYTECODE 环境变量,但您可以自行设置它来控制字节码文件的生成。

sys._emscripten_info

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

_emscripten_info.emscripten_version

Emscripten 版本,作为整数元组 (major, minor, micro),例如 (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__ 目录将被忽略,并在 pycache 前缀内写入新的 .pyc 文件。因此,如果您使用 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 的审计事件,其参数为 hooktypevaluetraceback。如果未设置任何钩子,hook 可能为 None。如果任何钩子引发了从 RuntimeError 派生的异常,则对钩子的调用将被抑制。否则,审计钩子异常将被报告为不可引发,并且将调用 sys.excepthook

另请参阅

sys.unraisablehook() 函数处理不可引发异常,而 threading.excepthook() 函数处理由 threading.Thread.run() 引发的异常。

sys.__breakpointhook__
sys.__displayhook__
sys.__excepthook__
sys.__unraisablehook__

这些对象包含程序开始时 breakpointhookdisplayhookexcepthookunraisablehook 的原始值。它们被保存下来,以便在 breakpointhookdisplayhookexcepthookunraisablehook 被替换为损坏或替代对象时,可以恢复它们。

在版本 3.7 中添加: __breakpointhook__

在版本 3.8 中添加: __unraisablehook__

sys.exception()

当在异常处理程序执行时(例如 exceptexcept* 子句)调用此函数时,它将返回此处理程序捕获的异常实例。当异常处理程序相互嵌套时,只有最内层处理程序处理的异常是可访问的。

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

在 3.11 版中添加。

sys.exc_info()

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

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

在版本 3.11 中更改: 现在 typetraceback 字段是从 value(异常实例)派生的,因此当异常在处理时被修改时,这些更改会反映在后续对 exc_info() 的调用结果中。

sys.exec_prefix

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

注意

如果 虚拟环境 生效,此值将在 site.py 中更改为指向虚拟环境。Python 安装的值仍然可以通过 base_exec_prefix 获得。

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

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

sys.float_info

一个 命名元组,保存有关浮点类型的信息。它包含有关精度和内部表示的低级信息。这些值对应于标准头文件 float.h 中为 ‘C’ 编程语言定义的各种浮点常量;有关详细信息,请参阅 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',那么对于有限浮点数 xrepr(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.getunicodeinternedsize()

返回已进行内部化的 Unicode 对象的数量。

在 3.12 版本中添加。

sys.getandroidapilevel()

以整数形式返回 Android 的构建时 API 版本。

可用性: Android。

在 3.7 版本中添加。

sys.getdefaultencoding()

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

sys.getdlopenflags()

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

可用性: Unix。

sys.getfilesystemencoding()

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

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

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

文件系统编码和错误处理程序 在 Python 启动时由 PyConfig_Read() 函数配置:请参阅 filesystem_encodingfilesystem_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_encodingfilesystem_errors 成员 PyConfig

在 3.6 版本中添加。

sys.get_int_max_str_digits()

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

在 3.11 版中添加。

sys.getrefcount(object)

返回 object 的引用计数。返回的计数通常比您预期的要高 1,因为它包括作为 getrefcount() 参数的(临时)引用。

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

在 3.12 版本中更改: 永生对象具有非常大的引用计数,这与对该对象的实际引用数量不匹配。

sys.getrecursionlimit()

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

sys.getsizeof(object[, default])

以字节为单位返回对象的尺寸。该对象可以是任何类型的对象。所有内置对象都将返回正确的结果,但这对于第三方扩展可能并不成立,因为它与实现有关。

仅考虑直接归因于该对象的内存消耗,不考虑其引用的对象的内存消耗。

如果给出,如果对象没有提供检索尺寸的方法,则将返回 default。否则将引发 TypeError

getsizeof() 调用对象的 __sizeof__ 方法,如果该对象由垃圾收集器管理,则还会添加额外的垃圾收集器开销。

有关使用 getsizeof() 递归地查找容器及其所有内容大小的示例,请参见 递归 sizeof 食谱

sys.getswitchinterval()

返回解释器的“线程切换间隔”;请参见 setswitchinterval()

在版本 3.2 中添加。

sys._getframe([depth])

从调用堆栈中返回一个帧对象。如果给出了可选的整数 depth,则返回堆栈顶端下方调用次数的帧对象。如果比调用堆栈更深,则会引发 ValueErrordepth 的默认值为零,返回调用堆栈顶部的帧。

引发 审计事件 sys._getframe,参数为 frame

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

sys._getframemodulename([depth])

从调用堆栈中返回模块的名称。如果给出了可选的整数 depth,则返回堆栈顶端下方调用次数的模块。如果比调用堆栈更深,或者模块无法识别,则返回 Nonedepth 的默认值为零,返回调用堆栈顶部的模块。

引发 审计事件 sys._getframemodulename,参数为 depth

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

sys.getprofile()

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

sys.gettrace()

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

CPython 实现细节:gettrace() 函数仅用于实现调试器、分析器、覆盖工具等。其行为是实现平台的一部分,而不是语言定义的一部分,因此可能并非所有 Python 实现中都可用。

sys.getwindowsversion()

返回一个命名元组,描述当前运行的 Windows 版本。命名元素为 majorminorbuildplatformservice_packservice_pack_minorservice_pack_majorsuite_maskproduct_typeplatform_versionservice_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 返回当前操作系统的 major 版本、minor 版本和 build 号,而不是为进程模拟的版本。它旨在用于日志记录,而不是用于功能检测。

注意

platform_version 从 kernel32.dll 中获取版本,该版本可能与 OS 版本不同。请使用 platform 模块来获取准确的 OS 版本。

可用性: Windows。

版本 3.2 中的变更: 更改为命名元组,并添加了 service_pack_minorservice_pack_majorsuite_maskproduct_type

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

sys.get_asyncgen_hooks()

返回一个 asyncgen_hooks 对象,它类似于 namedtuple,形式为 (firstiter, finalizer),其中 firstiterfinalizer 预计为 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 中的变更: 添加了 algorithmhash_bitsseed_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 表示的是 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 内部整数表示的信息。这些属性是只读的。

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 版本中添加。

Changed in version 3.11: 添加了 default_max_str_digitsstr_digits_check_threshold.

sys.__interactivehook__

当此属性存在时,其值会在解释器以 交互模式 启动时自动调用(不带参数)。这在读取 PYTHONSTARTUP 文件之后完成,因此您可以在其中设置此钩子。 site 模块 设置了这个

在启动时调用钩子时,会引发一个 审计事件 cpython.run_interactivehook,钩子对象作为参数。

在 3.4 版本中添加。

sys.intern(string)

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

内部字符串并非永生不灭;您必须保留对 intern() 返回值的引用才能从中获益。

sys.is_finalizing()

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

Added in version 3.5.

sys.last_exc

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

在 3.12 版本中添加。

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 的值为 0xFFFF0x10FFFF,取决于配置选项,该选项指定 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 codepython(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

此字符串包含一个平台标识符,可用于将平台特定的组件附加到 sys.path,例如。

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

对于其他系统,值是

系统

platform

AIX

'aix'

Emscripten

'emscripten'

Linux

'linux'

WASI

'wasi'

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 习惯用法。

另请参阅

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。这可以在构建时使用 --prefix 参数设置到 configure 脚本。有关派生路径,请参阅 安装路径

注意

如果 虚拟环境 生效,此值将在 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.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()

配置文件函数应具有三个参数:frameeventargframe 是当前堆栈帧。event 是一个字符串:'call''return''c_call''c_return''c_exception'arg 取决于事件类型。

这些事件具有以下含义:

'call'

调用函数(或进入其他代码块)。调用配置文件函数;argNone

'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()

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

每当进入新的本地范围时,都会调用跟踪函数(event 设置为 'call');它应该返回对将用于新范围的本地跟踪函数的引用,或者如果该范围不应被跟踪,则返回 None

本地跟踪函数应返回对自身的引用,或返回对另一个函数的引用,该函数将用作该范围的本地跟踪函数。

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

注意

在调用跟踪函数(例如,由 settrace() 设置的函数)时,跟踪被禁用。有关递归跟踪,请参见 call_tracing()

这些事件具有以下含义:

'call'

调用函数(或进入其他代码块)。调用全局跟踪函数;argNone;返回值指定本地跟踪函数。

'line'

解释器即将执行新代码行或重新执行循环条件。调用本地跟踪函数;argNone;返回值指定新的本地跟踪函数。有关其工作原理的详细说明,请参见 Objects/lnotab_notes.txt。可以通过将 f_trace_lines 设置为 False 在该 上来禁用每行事件。

'return'

函数(或其他代码块)即将返回。调用本地跟踪函数;arg 是将要返回的值,如果事件是由异常引发,则为 None。跟踪函数的返回值被忽略。

'exception'

发生了异常。调用本地跟踪函数;arg 是一个元组 (exception, value, traceback);返回值指定新的本地跟踪函数。

'opcode'

解释器即将执行新的操作码(有关操作码详细信息,请参见 dis)。调用本地跟踪函数;argNone;返回值指定新的本地跟踪函数。默认情况下不会发出每个操作码事件:必须通过将 f_trace_opcodes 设置为 True 在该 上来显式请求它们。

请注意,当异常在调用者链中传播时,在每个级别都会生成一个 'exception' 事件。

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

有关代码和帧对象的更多信息,请参阅 标准类型层次结构

引发 审计事件 sys.settrace,不带参数。

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

在版本 3.7 中更改:添加了 'opcode' 事件类型;向帧添加了 f_trace_linesf_trace_opcodes 属性

在版本 3.12 中更改:仅当至少一个帧的 f_trace_opcodes 在调用 settrace() 之前被设置为 True 时,才会发出 'opcode' 事件。此行为将在 3.13 中更改回与以前版本一致。

sys.set_asyncgen_hooks([firstiter] [, finalizer])

接受两个可选的关键字参数,它们是可调用对象,接受一个异步生成器迭代器作为参数。当第一次迭代异步生成器时,将调用firstiter可调用对象。当异步生成器即将被垃圾回收时,将调用finalizer

引发一个审计事件 sys.set_asyncgen_hooks_firstiter,不带参数。

引发一个审计事件 sys.set_asyncgen_hooks_finalizer,不带参数。

引发两个审计事件,因为底层 API 由两个调用组成,每个调用都必须引发自己的事件。

在 3.6 版本中添加: 有关更多详细信息,请参见PEP 525,有关finalizer方法的参考示例,请参见asyncio.Loop.shutdown_asyncgens的实现,位于Lib/asyncio/base_events.py

注意

此函数已在临时基础上添加(有关详细信息,请参见PEP 411)。

sys.set_coroutine_origin_tracking_depth(depth)

允许启用或禁用协程来源跟踪。启用后,协程对象上的cr_origin属性将包含一个元组,其中包含(文件名、行号、函数名)元组,描述创建协程对象的回溯,最近的调用排在最前面。禁用后,cr_origin将为None

要启用,请传递一个大于零的depth值;这将设置要捕获其信息的帧数。要禁用,请将depth设置为零。

此设置是特定于线程的。

在 3.7 版本中添加。

注意

此函数已在临时基础上添加(有关详细信息,请参见PEP 411)。仅将其用于调试目的。

sys.activate_stack_trampoline(backend, /)

激活堆栈分析器蹦床backend。唯一支持的后台是"perf"

可用性: Linux。

在 3.12 版本中添加。

sys.deactivate_stack_trampoline()

停用当前堆栈分析器蹦床后台。

如果没有激活堆栈分析器,则此函数无效。

可用性: Linux。

在 3.12 版本中添加。

sys.is_stack_trampoline_active()

如果堆栈分析器蹦床处于活动状态,则返回True

可用性: Linux。

在 3.12 版本中添加。

sys._enablelegacywindowsfsencoding()

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

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

另请参见sys.getfilesystemencoding()sys.getfilesystemencodeerrors()

可用性: Windows。

在 3.6 版本中添加: 有关更多详细信息,请参见PEP 529

sys.stdin
sys.stdout
sys.stderr

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

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

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

  • 解释器自己的提示及其错误消息将发送到stderr

这些流是常规的文本文件,类似于open()函数返回的文本文件。它们的參數如下選擇

  • 编码和错误处理从PyConfig.stdio_encodingPyConfig.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__

这些对象包含程序开始时 stdinstderrstdout 的原始值。它们在最终化期间使用,并且可能有助于将信息打印到实际的标准流,无论 sys.std* 对象是否已被重定向。

它还可以用于将实际文件恢复到已知的正常工作文件对象,以防它们被损坏的对象覆盖。但是,首选的方法是在替换之前显式保存先前的流,并恢复保存的对象。

注意

在某些情况下,stdinstdoutstderr 以及原始值 __stdin____stdout____stderr__ 可以是 None。对于未连接到控制台的 Windows GUI 应用程序和使用 pythonw 启动的 Python 应用程序,通常是这种情况。

sys.stdlib_module_names

一个包含标准库模块名称的字符串的冻结集。

它在所有平台上都是相同的。在某些平台上不可用的模块和在 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_msgobject 格式化为:f'{err_msg}: {object!r}';如果 err_msgNone,则使用“异常在”中被忽略的错误消息。

sys.unraisablehook() 可以被覆盖以控制如何处理不可引发异常。

另请参阅

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

警告

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

使用自定义钩子存储 object 会在它被设置为正在完成的对象时使它复活。避免在自定义钩子完成后存储 object 以避免使对象复活。

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

在版本 3.8 中添加。

sys.version

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

sys.api_version

此解释器的 C API 版本。程序员在调试 Python 和扩展模块之间的版本冲突时可能会发现这很有用。

sys.version_info

一个包含版本号的五个组成部分的元组:majorminormicroreleaselevelserial。除 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 实现细节: 这是访问通过 -X 传递的选项的 CPython 特定方式。其他实现可能通过其他方式导出它们,或者根本不导出。

在版本 3.2 中添加。

引用

[C99]

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