python / 3.7.2rc1 / all / library-sys.html

sys —系统特定的参数和Function


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

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

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

3.2 版中的新Function。

  • sys. addaudithook(* hook *)
    • 将可调用的* hook *附加到当前解释器的活动审核钩子列表中。

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

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

3.8 版的新Function。

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

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

  • sys. argv
    • 传递给 Python 脚本的命令行参数列表。 argv[0]是脚本名称(是否为完整路径名取决于 os)。如果使用解释器的-c命令行选项执行了命令,则argv[0]设置为字符串'-c'。如果没有脚本名称传递给 Python 解释器,则argv[0]是空字符串。

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

Note

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

  • sys. audit(* event * args *)
    • 使用任何活动的钩子引发审核事件。事件名称是一个字符串,用于标识事件及其关联的模式,即参数的数量和类型。给定事件的模式被认为是公共且稳定的 API,并且不应在版本之间进行修改。

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

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

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

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

3.8 版的新Function。

  • sys. base_exec_prefix

版本 3.3 中的新Function。

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

版本 3.3 中的新Function。

  • sys. byteorder

    • 本机字节 Sequences 的指示符。在 big-endian(最高有效字节在前)平台上,该值将为'big',在 little-endian(最低有效字节在前)平台上的值为'little'
  • sys. builtin_module_names

    • 字符串的 Tuples,给出了编译到此 Python 解释器中的所有模块的名称。 (此信息无法pass其他任何方式获得,modules.keys()仅列出了导入的模块.)
  • sys. call_tracing(* func args *)

    • 启用跟踪时,请致电func(*args)。跟踪状态已保存,然后恢复。它旨在从检查点的调试器中调用,以递归方式调试其他一些代码。
  • sys. copyright

    • 一个字符串,其中包含与 Python 解释器有关的版权。
  • sys. _clear_type_cache ( )

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

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

  • sys. _current_frames ( )
    • 返回一个字典,该字典将每个线程的标识符 Map 到调用该函数时该线程中当前活动的最顶层堆栈帧。请注意,traceback模块中的函数可以在给定这样的框架的情况下构建调用堆栈。

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

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

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

  • sys. breakpointhook ( )
    • 此钩子函数由内置breakpoint()调用。默认情况下,它将带您进入pdb调试器,但可以将其设置为任何其他函数,以便您选择使用哪个调试器。

该函数的签名取决于其调用的内容。例如,默认绑定(例如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。

  • sys. _debugmallocstats ( )
    • 将有关 CPython 内存分配器状态的低级信息打印到 stderr。

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

版本 3.3 中的新Function。

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

  • sys. dllhandle
    • 指定 Python DLL 句柄的整数。

Availability: Windows.

  • sys. displayhook(* value *)
    • 如果* value 不是None,则此函数将repr(value)打印到sys.stdout,并将 value *保存在builtins._中。如果使用sys.stdout.errors错误处理程序(可能是'strict')无法将repr(value)编码为sys.stdout.encoding,则使用'backslashreplace'错误处理程序将其编码为sys.stdout.encoding

评估在交互式 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'错误处理程序。

  • sys. dont_write_bytecode

    • 如果是这样,Python 将不会try在导入源模块时写入.pyc文件。根据-B命令行选项和 PYTHONDONTWRITEBYTECODE环境变量,该值最初设置为TrueFalse,但是您可以自己设置以控制字节码文件的生成。
  • sys. pycache_prefix

    • 如果设置了该值(不是None),Python 会将字节码缓存.pyc文件写入到以该目录为根的并行目录树中(并从中读取),而不是从源代码树中的__pycache__目录中写入。源代码树中的所有__pycache__目录都将被忽略,并将在 pycache 前缀内写入新的.pyc 文件。因此,如果您使用compileall作为预构建步骤,则必须确保使用与运行时相同的 pycache 前缀(如果有)运行它。

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

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

3.8 版的新Function。

  • sys. excepthook(* type value traceback *)
    • 此函数将给定的 traceback 和异常打印到sys.stderr

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

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

See also

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

  • sys. __breakpointhook__
  • sys. __displayhook__
  • sys. __excepthook__
  • sys. __unraisablehook__
    • 这些对象在程序开始时包含breakpointhookdisplayhookexcepthookunraisablehook的原始值。将它们保存起来,以便可以恢复breakpointhookdisplayhookexcepthookunraisablehook,以防它们碰巧被损坏的或替代的对象所代替。

3.7 版中的新Function:breakpointhook

3.8 版的新Function:unraisablehook

  • sys. exc_info ( )
    • 此函数返回三个值的 Tuples,它们给出有关当前正在处理的异常的信息。返回的信息特定于当前线程和当前堆栈帧。如果当前堆栈帧未处理异常,则从调用堆栈帧或其调用者等获取信息,依此类推,直到找到处理异常的堆栈帧为止。这里,“处理异常”被定义为“执行 except 子句”。对于任何堆栈帧,只能访问有关当前正在处理的异常的信息。

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

  • 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

Note

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

  • sys. executable

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

    • 从 Python 退出。这是pass引发SystemExit异常来实现的,因此可以接受try语句的 finally 子句指定的清除操作,并且有可能在外部级别拦截 Export try。

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

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

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

  • sys. flags
    • named tuple * flags *显示命令行标志的状态。这些属性是只读的。
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属性。

  • sys. float_info
    • named tuple保存有关浮点类型的信息。它包含有关精度和内部表示的低级信息。这些值对应于在标准头文件float.h中为“ C”编程语言定义的各种浮点常量。有关详细信息,请参见 1999 ISO/IEC C 标准[C99]的 5.2.4.2.2 节“浮点类型的特性”。
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'
  • sys. float_repr_style
    • 一个字符串,指示repr()函数对浮点数的行为。如果字符串的值是'short',那么对于有限浮点数xrepr(x)的目标是产生一个具有float(repr(x)) == x属性的短字符串。这是 Python 3.1 及更高版本中的常见行为。否则,float_repr_style的值为'legacy',并且repr(x)的行为与在 3.1 之前的 Python 版本中相同。

3.1 版中的新Function。

  • sys. getallocatedblocks ( )
    • 返回解释器当前分配的内存块数,无论其大小如何。此Function主要用于跟踪和调试内存泄漏。由于解释器的内部缓存,结果可能因调用而异。您可能必须致电_clear_type_cache()gc.collect()以获得更可预测的结果。

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

3.4 版的新Function。

  • sys. getandroidapilevel ( )
    • 以整数形式返回 Android 的构建时间 API 版本。

Availability: Android.

3.7 版中的新Function。

  • sys. getcheckinterval ( )

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

  • sys. getdefaultencoding ( )

    • 返回 Unicode 实现使用的当前默认字符串编码的名称。
  • sys. getdlopenflags ( )

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

Availability: Unix.

  • sys. getfilesystemencoding ( )
    • 返回用于在 Unicode 文件名和字节文件名之间转换的编码的名称。为了获得最佳兼容性,在所有情况下都应将 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 文件名和字节文件名之间转换的错误模式的名称。编码名称从getfilesystemencoding()返回。

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

3.6 版的新Function。

  • sys. getrefcount(* object *)

    • 返回* object *的引用计数。返回的计数通常比您预期的高一,因为它包含(临时)引用作为getrefcount()的参数。
  • sys. getrecursionlimit ( )

    • 返回递归限制的当前值,即 Python 解释器堆栈的最大深度。此限制可防止无限递归导致 C 堆栈溢出和 Python 崩溃。可以由setrecursionlimit()设置。
  • sys. getsizeof(* object * [,* default *])

    • 返回对象的大小(以字节为单位)。该对象可以是任何类型的对象。所有内置对象都将返回正确的结果,但是对于第三方扩展,这不一定成立,因为它是特定于实现的。

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

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

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

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

  • sys. getswitchinterval ( )

3.2 版中的新Function。

  • sys. _getframe([深度])
    • 从调用堆栈返回一个框架对象。如果给定了可选的整数* depth *,则返回在堆栈顶部下方多次调用的帧对象。如果那比调用堆栈深,则引发ValueError。 * depth *的默认值为零,返回调用堆栈顶部的帧。

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

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

  • sys. getprofile ( )
  • sys. gettrace ( )

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

  • sys. getwindowsversion ( )
    • 返回描述当前运行的 Windows 版本的命名 Tuples。命名的元素是* major minor build platform service_pack service_pack_minor service_pack_major suite_mask product_type platform_version *。 * service_pack 包含一个字符串, platform_version *一个三 Tuples,所有其他值都是整数。也可以pass名称访问组件,因此sys.getwindowsversion()[0]等效于sys.getwindowsversion().major。为了与以前的版本兼容,只能pass索引检索前 5 个元素。

平台将为2 (VER_PLATFORM_WIN32_NT)

  • product_type *可能是以下值之一:
Constant Meaning
1 (VER_NT_WORKSTATION) 该系统是工作站。
2 (VER_NT_DOMAIN_CONTROLLER) 该系统是域控制器。
3 (VER_NT_SERVER) 系统是服务器,而不是域控制器。

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

  • platform_version *返回当前 os 的准确的主要版本,次要版本和内部版本号,而不是为该进程仿真的版本。它旨在用于日志记录,而不是用于Function检测。

Availability: Windows.

在版本 3.2 中更改:更改为命名 Tuples,并添加了* 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或以异步生成器迭代器作为参数的函数,用于pass事件循环安排异步生成器的完成。

3.6 版的新Function:有关更多详细信息,请参见 PEP 525

Note

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

3.7 版中的新Function。

Note

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

  • sys. hash_info
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 *

  • 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()函数时,它看上去才有意义。 named tuple sys.version_info可用于对相同信息进行更人性化的编码。

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

  • sys. implementation
    • 一个对象,包含有关当前运行的 Python 解释器的实现的信息。所有 Python 实现中都必须存在以下属性。
  • name *是实现的标识符,例如'cpython'。实际的字符串由 Python 实现定义,但可以保证小写。

  • version *是一个命名 Tuples,格式与sys.version_info相同。它表示 Python * implementation *的版本。这与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 中的新Function。

Note

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

  • sys. int_info
    • named tuple,其中包含有关 Python 内部整数表示形式的信息。这些属性是只读的。
Attribute Explanation
bits_per_digit 每个数字中保留的位数。 Python 整数内部存储在基本2**int_info.bits_per_digit
sizeof_digit 用于表示数字的 C 类型的字节大小

3.1 版中的新Function。

  • sys. __interactivehook__
    • 如果存在此属性,则在interactive mode中启动解释器时,将自动调用其值(不带参数)。这是在读取 PYTHONSTARTUP文件之后完成的,因此您可以在此处设置此钩子。 site模块sets this

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

3.4 版的新Function。

  • sys. intern(* string *)
    • 在“ interned”字符串表中 Importing* string 并返回该 interned 字符串–它本身就是 string *或副本。插入字符串对于提高字典查找的性能很有用–如果字典中的键被插入,并且查找键被插入,则键比较(散列后)可以pass指针比较而不是字符串比较来完成。通常,Python 程序中使用的名称会被自动插入,而用于保存模块,类或实例属性的字典则具有插入键。

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

3.5 版中的新Function。

  • 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以前是0xFFFF0x10FFFF,具体取决于指定将 Unicode 字符存储为 UCS-2 还是 UCS-4 的配置选项。

  • sys. meta_path
    • 调用了find_spec()方法的元路径查找器对象的列表,以查看其中一个对象是否可以找到要导入的模块。至少使用要导入的模块的绝对名称调用find_spec()方法。如果要导入的模块包含在包中,则将父包的path属性作为第二个参数传递。如果找不到模块,则该方法返回module specNone

See also

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

  • sys. modules

    • 这是将模块名称 Map 到已经加载的模块的字典。可以对其进行操作以强制重新加载模块和其他技巧。但是,替换字典不一定能按预期工作,并且从字典中删除必要项目可能会导致 Python 失败。
  • sys. path

    • 字符串列表,用于指定模块的搜索路径。从环境变量 PYTHONPATH初始化,再加上一个依赖于安装的默认值。

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

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

See also

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

  • sys. path_hooks
    • 带有路径参数以try为路径创建finder的可调用项列表。如果可以创建查找程序,则该查找程序将由可调用方返回,否则引发ImportError

最初在 PEP 302中指定。

  • sys. path_importer_cache
    • 充当finder个对象的缓存的字典。键是已传递到sys.path_hooks的路径,值是找到的查找器。如果路径是有效的文件系统路径,但在sys.path_hooks上找不到查找程序,则将存储None

最初在 PEP 302中指定。

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

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

对于其他系统,值是:

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模块提供对系统身份的详细检查。

  • sys. prefix
    • 一个字符串,提供特定于站点的目录前缀,在其中安装了平台无关的 Python 文件;默认情况下,这是字符串'/usr/local'。可以在构建时使用 configure 脚本的--prefix参数进行设置。 Python 库模块的主要集合安装在目录prefix/lib/pythonX.Y中,而平台无关的头文件(除pyconfig.h以外的所有文件)存储在prefix/include/pythonX.Y中,其中* X.Y *是 Python 的版本号,例如3.2

Note

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

  • sys. ps1
  • sys. ps2
    • 指定解释器的主要和辅助提示的字符串。仅当解释器处于交互模式时才定义它们。在这种情况下,它们的初始值为'>>> ''... '。如果将非字符串对象分配给任何一个变量,则每次解释器准备读取新的交互式命令时,都会重新评估其str()。这可以用来实现动态提示。
  • sys. setcheckinterval(* interval *)
    • 设置 Interpreter 的“检查间隔”。该整数值确定解释器多长时间检查一次周期性事件,例如线程切换和 signal 处理程序。默认值为100,这意味着每 100 条 Python 虚拟指令执行一次检查。将其设置为较大的值可能会提高使用线程的程序的性能。将其设置为值<=0 会检查每条虚拟指令,从而最大限度地提高响应速度和开销。

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

  • sys. setdlopenflags(* n *)
    • 设置解释器用于dlopen()调用的标志,例如当解释器加载扩展模块时。除其他外,这将在导入模块(如果称为sys.setdlopenflags(0))时实现符号的延迟解析。要在扩展模块之间共享符号,请调用sys.setdlopenflags(os.RTLD_GLOBAL)。标志值的符号名称可以在os模块(RTLD_xxx常量,例如os.RTLD_LAZY)中找到。

Availability: Unix.

  • sys. setprofile(* profilefunc *)
    • 设置系统的概要文件Function,该Function允许您在 Python 中实现 Python 源代码概要文件。有关 Python 分析器的更多信息,请参见第Python Profilers章。系统的配置文件函数的调用方式与系统的跟踪函数类似(请参见settrace()),但是它是pass不同的事件调用的,例如,并非针对每一行已执行的代码都调用它(仅在调用和返回时才调用,但 return 事件为即使设置了 exception 也会报告)。该函数是特定于线程的,但探查器无法了解线程之间的上下文切换,因此在存在多个线程的情况下使用此Function没有任何意义。同样,不使用其返回值,因此可以简单地返回None。配置文件Function中的错误将导致其自身未设置。

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

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

这些事件具有以下含义:

  • 'call'

    • 调用一个函数(或 Importing 其他代码块)。配置文件Function被调用; * arg *是None

    • 'return'

      • 一个函数(或其他代码块)即将返回。配置文件Function被调用; * arg *是将返回的值;如果事件是由引发异常引起的,则返回None
    • 'c_call'

      • C 函数即将被调用。这可能是扩展Function,也可能是内置Function。 * 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 线程的“时间片”的理想持续时间。请注意,实际值可能会更高,尤其是在使用长时间运行的内部函数或方法的情况下。同样,在间隔结束时调度哪个线程是 os 的决定。解释器没有自己的调度程序。

3.2 版中的新Function。

  • sys. settrace(* tracefunc *)
    • 设置系统的跟踪Function,该Function允许您在 Python 中实现 Python 源代码调试器。该函数是特定于线程的;为了使调试器支持多个线程,它必须为每个要调试的线程使用settrace()或使用threading.settrace()注册跟踪Function。

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

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

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

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

这些事件具有以下含义:

  • 'call'

    • 调用一个函数(或 Importing 其他代码块)。全局跟踪函数称为; * arg *是None;返回值指定本地跟踪函数。

    • 'line'

      • 解释器将要执行新的代码行或重新执行循环条件。局部跟踪函数被调用; * arg *是None;返回值指定新的本地跟踪函数。有关此工作原理的详细说明,请参见Objects/lnotab_notes.txt。pass在该帧上将f_trace_lines设置为False,可以禁用该帧的每行事件。
    • 'return'

      • 一个函数(或其他代码块)即将返回。局部跟踪函数被调用; * arg *是将返回的值;如果事件是由引发异常引起的,则返回None。跟踪函数的返回值将被忽略。
    • 'exception'

      • 发生异常。局部跟踪函数被调用; * arg *是一个 Tuples(exception, value, traceback);返回值指定新的本地跟踪函数。
    • 'opcode'

      • 解释程序将要执行新的操作码(有关操作码的详细信息,请参见dis)。局部跟踪函数被调用; * arg *是None;返回值指定新的本地跟踪函数。每个操作码事件默认情况下都不发出:必须pass在帧上将f_trace_opcodes设置为True来显式请求它们。

请注意,由于异常是在调用者链中传播的,因此在每个级别都会生成'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_linesf_trace_opcodes属性已添加到框架

  • sys. set_asyncgen_hooks(* firstiter finalizer *)
    • 接受两个可选的关键字参数,它们是接受异步生成器迭代器作为参数的可调用对象。首次迭代异步生成器时,将调用* firstiter 可调用对象。当将要异步收集异步生成器时,将调用 finalizer *。

引发不带参数的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.pyasyncio.Loop.shutdown_asyncgens的实现

Note

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

  • sys. set_coroutine_origin_tracking_depth(深度)
    • 允许启用或禁用协程起源跟踪。启用后,协程对象上的cr_origin属性将包含(文件名,行号,函数名)Tuples,该 Tuples 描述创建协程对象的回溯,最近一次调用在前。禁用后,cr_origin将为“无”。

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

此设置是特定于线程的。

3.7 版中的新Function。

Note

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

  • sys. _enablelegacywindowsfsencoding ( )
    • 将默认文件系统编码和错误模式分别更改为“ mbcs”和“替换”,以与 3.6 之前的 Python 版本保持一致。

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

Availability: Windows.

3.6 版的新Function:有关更多详细信息,请参见 PEP 529

  • sys. stdin

  • sys. stdout

  • sys. stderr

    • File objects由解释器用于标准 Importing,输出和错误:
  • stdin用于所有交互式 Importing(包括对input()的调用);

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

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

这些流是常规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时适用。

  • 交互式时,stdoutstderr流是行缓冲的。否则,它们将像常规文本文件一样被块缓冲。您可以使用-u命令行选项覆盖此值。

Note

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

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

  • sys. __stdin__
  • sys. __stdout__
  • sys. __stderr__
    • 这些对象在程序开始时包含stdinstderrstdout的原始值。它们在完成过程中使用,并且无论sys.std*对象是否已重定向,都可以打印到实际的标准流。

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

Note

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

  • sys. thread_info
Attribute Explanation
name 线程实现的名称:


Note





'nt':Windows 线程

> 'pthread':POSIX 线程

> 'solaris':Solaris 线程



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

> [!NOTE]




'semaphore':锁使用 signal 量

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

> None(如果此信息未知)



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

版本 3.3 中的新Function。

  • 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,请使用“忽略异常中”错误消息。

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

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

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

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

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

3.8 版的新Function。

  • sys. version

    • 一个字符串,其中包含 Python 解释器的版本号以及有关内部版本号和使用的编译器的其他信息。启动交互式解释器时,将显示此字符串。不要从中提取版本信息,而是使用version_infoplatform模块提供的Function。
  • sys. api_version

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

    • 一个 Tuples,包含版本号的五个组成部分:* major minor micro releaselevel serial 。除 releaselevel *外的所有值都是整数;发布级别为'alpha''beta''candidate''final'。对应于 Python 2.0 版的version_info值为(2, 0, 0, 'final', 0)。也可以pass名称访问组件,因此sys.version_info[0]等效于sys.version_info.major,依此类推。

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

  • sys. warnoptions

    • 这是警告框架的实现细节。请勿修改此值。有关警告框架的更多信息,请参考warnings模块。
  • sys. winver

    • Windows 平台上用于形成注册表项的版本号。这作为字符串资源 1000 存储在 Python DLL 中。该值通常是version的前三个字符。 sys模块中提供了此信息,仅供参考;修改此值不会影响 Python 使用的注册表项。

Availability: Windows.

  • sys. _xoptions
    • pass-X命令行选项传递的各种特定于实现的标志的词典。选项名称将 Map 到其值(如果已明确指定)或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 的方式。其他实现可能pass其他方式或根本不导出。

3.2 版中的新Function。

Citations