sys — 系统特定的参数和函数 — Python 文档
sys — 系统特定的参数和函数
该模块提供对解释器使用或维护的一些变量以及与解释器强烈交互的函数的访问。 它始终可用。
- sys.abiflags
在使用标准
configure
脚本构建 Python 的 POSIX 系统上,这包含 PEP 3149 指定的 ABI 标志。3.2 版中的新功能。
- sys.argv
传递给 Python 脚本的命令行参数列表。
argv[0]
是脚本名称(它是否为完整路径名取决于操作系统)。 如果使用解释器的 -c 命令行选项执行命令,则argv[0]
设置为字符串'-c'
。 如果没有将脚本名称传递给 Python 解释器,则argv[0]
是空字符串。要循环标准输入或命令行上给出的文件列表,请参阅 fileinput 模块。
笔记
在 Unix 上,命令行参数是从操作系统按字节传递的。 Python 使用文件系统编码和“surrogateescape”错误处理程序对它们进行解码。 当需要原始字节时,可以通过
[os.fsencode(arg) for arg in sys.argv]
获取。
- sys.base_exec_prefix
在 Python 启动期间,在运行
site.py
之前,设置为与 exec_prefix 相同的值。 如果不在 虚拟环境 中运行,则值将保持不变; 如果site.py
发现虚拟环境正在使用中,prefix 和 exec_prefix 的值将更改为指向虚拟环境,而 base_prefix[ X269X] 和 base_exec_prefix 将继续指向基础 Python 安装(创建虚拟环境的那个安装)。3.3 版中的新功能。
- sys.base_prefix
在 Python 启动期间,在运行
site.py
之前,设置为与 prefix 相同的值。 如果不在 虚拟环境 中运行,则值将保持不变; 如果site.py
发现虚拟环境正在使用中,prefix 和 exec_prefix 的值将更改为指向虚拟环境,而 base_prefix[ X269X] 和 base_exec_prefix 将继续指向基础 Python 安装(创建虚拟环境的那个安装)。3.3 版中的新功能。
- sys.byteorder
- 本机字节顺序的指示符。 这将在 big-endian(最重要的字节在前)平台上具有值
'big'
,在 little-endian(最不重要的字节在前)平台上具有'little'
。
- sys.builtin_module_names
- 一个字符串元组,给出了编译到这个 Python 解释器中的所有模块的名称。 (此信息无法通过任何其他方式获得 —
modules.keys()
仅列出导入的模块。)
- sys.call_tracing(func, args)
- 在启用跟踪时调用
func(*args)
。 跟踪状态被保存,然后恢复。 这旨在从检查点的调试器中调用,以递归调试其他一些代码。
- sys.copyright
- 包含与 Python 解释器相关的版权的字符串。
- sys._clear_type_cache()
清除内部类型缓存。 类型缓存用于加速属性和方法查找。 在引用泄漏调试期间使用函数 only 删除不必要的引用。
此功能应仅用于内部和专门用途。
- sys._current_frames()
返回一个字典,将每个线程的标识符映射到调用函数时当前在该线程中处于活动状态的最顶层堆栈帧。 请注意,traceback 模块中的函数可以在给定这样的框架的情况下构建调用堆栈。
这对于调试死锁最有用:这个函数不需要死锁线程的合作,只要它们保持死锁,这些线程的调用堆栈就会被冻结。 在调用代码检查帧时,为非死锁线程返回的帧可能与该线程的当前活动无关。
此功能应仅用于内部和专门用途。
- sys.breakpointhook()
这个钩子函数由内置的 breakpoint() 调用。 默认情况下,它会让您进入 pdb 调试器,但它可以设置为任何其他功能,以便您可以选择使用哪个调试器。
此函数的签名取决于它调用的内容。 例如,默认绑定(例如
pdb.set_trace()
) 不需要参数,但您可以将其绑定到需要附加参数(位置和/或关键字)的函数。 内置的breakpoint()
函数将其*args
和**kws
直通。 无论breakpointhooks()
返回什么,都会从breakpoint()
返回。默认实现首先参考环境变量 PYTHONBREAKPOINT。 如果设置为
"0"
则该函数立即返回; IE 这是一个空操作。 如果未设置环境变量,或设置为空字符串,则调用pdb.set_trace()
。 否则这个变量应该命名一个要运行的函数,使用 Python 的 dotted-import 命名法,例如package.subpackage.module.function
。 在这种情况下,将导入package.subpackage.module
并且生成的模块必须有一个名为function()
的可调用对象。 这是运行,传入*args
和**kws
,无论function()
返回什么,sys.breakpointhook()
返回到内置的 breakpoint() ] 功能。请注意,如果导入由 PYTHONBREAKPOINT 命名的可调用对象时出现任何问题,则会报告 RuntimeWarning 并忽略断点。
另请注意,如果
sys.breakpointhook()
以编程方式被覆盖,则 PYTHONBREAKPOINT 是 not。3.7 版中的新功能。
- sys._debugmallocstats()
将有关 CPython 内存分配器状态的低级信息打印到 stderr。
如果 Python 配置了 –with-pydebug,它还会执行一些昂贵的内部一致性检查。
3.3 版中的新功能。
- sys.dllhandle
- 指定 Python DLL 句柄的整数。
- sys.displayhook(value)
如果 value 不是
None
,则该函数将repr(value)
打印到sys.stdout
,并将 value 保存在builtins._
. 如果repr(value)
无法使用sys.stdout.errors
错误处理程序(可能是'strict'
)编码为sys.stdout.encoding
,请使用'backslashreplace'
错误处理程序。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
文件。 此值最初设置为True
或False
,具体取决于 -B 命令行选项和 PYTHONDONTWRITEBYTECODE 环境变量,但你可以自己设置它来控制字节码文件的生成。
- sys.excepthook(type, value, traceback)
此函数将给定的回溯和异常打印到
sys.stderr
。当异常被引发并未被捕获时,解释器使用三个参数调用
sys.excepthook
,异常类、异常实例和回溯对象。 在交互式会话中,这发生在控制返回到提示之前; 在 Python 程序中,这发生在程序退出之前。 可以通过将另一个三参数函数分配给sys.excepthook
来自定义此类顶级异常的处理。
- sys.__breakpointhook__
sys.__displayhook__
sys.__excepthook__ 这些对象包含程序开始时的
breakpointhook
、displayhook
和excepthook
的原始值。 它们被保存,以便breakpointhook
、displayhook
和excepthook
可以在它们碰巧被损坏的或替代的对象替换时恢复。3.7 新功能:__breakpointhook__
- sys.exc_info()
此函数返回一个包含三个值的元组,这些值提供有关当前正在处理的异常的信息。 返回的信息特定于当前线程和当前堆栈帧。 如果当前堆栈帧未处理异常,则从调用堆栈帧或其调用者中获取信息,依此类推,直到找到正在处理异常的堆栈帧。 这里,“处理异常”被定义为“执行一个except子句”。 对于任何堆栈帧,只能访问有关当前正在处理的异常的信息。
如果堆栈上的任何地方都没有处理异常,则返回一个包含三个
None
值的元组。 否则,返回的值为(type, value, traceback)
。 它们的含义是: type 获取正在处理的异常的类型(BaseException 的子类); value 获取异常实例(异常类型的一个实例); traceback 获取一个回溯对象(参见参考手册),它封装了最初发生异常的点的调用堆栈。
- sys.exec_prefix
一个字符串,给出安装依赖于平台的 Python 文件的站点特定目录前缀; 默认情况下,这也是
'/usr/local'
。 这可以在构建时使用 configure 脚本的--exec-prefix
参数进行设置。 具体来说,所有配置文件(例如pyconfig.h
头文件)安装在exec_prefix/lib/pythonX.Y/config
目录,共享库模块安装在exec_prefix/lib/pythonX.Y/lib-dynload
,其中XY为Python版本号,例如3.2
。笔记
如果 虚拟环境 生效,则该值将在
site.py
中更改为指向虚拟环境。 Python 安装的值仍然可用,通过 base_exec_prefix。
- sys.executable
- 在有意义的系统上,给出 Python 解释器的可执行二进制文件的绝对路径的字符串。 如果 Python 无法检索其可执行文件的真实路径,则 sys.executable 将是一个空字符串或
None
。
- sys.exit([arg])
退出 Python。 这是通过引发 SystemExit 异常来实现的,因此由 try 语句的 finally 子句指定的清理操作得到遵守,并且可以在外部级别拦截退出尝试。
可选参数 arg 可以是一个整数,给出退出状态(默认为零)或其他类型的对象。 如果它是一个整数,零被认为是“成功终止”,任何非零值都被壳等认为是“异常终止”。 大多数系统要求它在 0-127 的范围内,否则会产生未定义的结果。 一些系统有为特定退出代码分配特定含义的约定,但这些通常不完善; Unix 程序通常使用 2 表示命令行语法错误,使用 1 表示所有其他类型的错误。 如果传递了另一种类型的对象,则
None
等效于传递零,任何其他对象都会打印到 stderr 并导致退出代码为 1。 特别是,sys.exit("some error message")
是一种在发生错误时退出程序的快捷方式。由于exit()最终“只”抛出异常,所以只有从主线程调用时才会退出进程,不会拦截异常。
3.6 版本变更: 如果 Python 解释器捕获到 SystemExit 后在清理中发生错误(例如在标准流中刷新缓冲数据时出错),则退出状态更改到 120。
- sys.flags
named tuple flags 暴露了命令行标志的状态。 属性是只读的。
属性
旗帜
debug
interactive
isolated
optimize
no_user_site
no_site
ignore_environment
verbose
bytes_warning
quiet
hash_randomization
dev_mode
-X
dev
utf8_mode
-X
utf8
3.2 版更改: 为新的 -q 标志添加了
quiet
属性。3.2.3 新功能:
hash_randomization
属性。3.3 版更改: 删除了过时的
division_warning
属性。3.4 版更改: 为 -I
isolated
标志添加了isolated
属性。在 3.7 版更改:为新的 -X
dev
标志和新的 添加了dev_mode
属性和utf8_mode
属性]-Xutf8
标志。
- sys.float_info
一个 命名的元组 保存有关浮点类型的信息。 它包含有关精度和内部表示的低级信息。 这些值对应于“C”编程语言的标准头文件
float.h
中定义的各种浮点常量; 有关详细信息,请参阅 1999 ISO/IEC C 标准 [C99] 的第 5.2.4.2.2 节“浮动类型的特征”。属性
float.h 宏
解释
epsilon
DBL_EPSILON
1.0 与可表示为浮点数的大于 1.0 的最小值之间的差值
dig
DBL_DIG
可以在浮点数中忠实表示的最大十进制位数; 见下文
mant_dig
DBL_MANT_DIG
浮点精度:浮点数有效数中基数为
radix
的位数DBL_MAX
最大可表示正有限浮点数
max_exp
DBL_MAX_EXP
最大整数 e 使得
radix**(e-1)
是可表示的有限浮点数max_10_exp
DBL_MAX_10_EXP
最大整数 e 使得
10**e
在可表示的有限浮点数范围内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'
,那么对于有限浮点数x
,repr(x)
旨在生成具有float(repr(x)) == x
属性的短字符串。 这是 Python 3.1 及更高版本中的常见行为。 否则,float_repr_style
的值为'legacy'
并且repr(x)
的行为方式与 Python 3.1 之前的版本相同。3.1 版中的新功能。
- sys.getallocatedblocks()
返回解释器当前分配的内存块的数量,而不管它们的大小。 该函数主要用于跟踪和调试内存泄漏。 由于解释器的内部缓存,结果可能因调用而异; 您可能需要调用 _clear_type_cache() 和 gc.collect() 以获得更可预测的结果。
如果 Python 构建或实现无法合理计算此信息,则允许 getallocatedblocks() 改为返回 0。
3.4 版中的新功能。
- sys.getandroidapilevel()
以整数形式返回 Android 的构建时间 API 版本。
3.7 版中的新功能。
- sys.getcheckinterval()
返回解释器的“检查间隔”; 参见 setcheckinterval()。
自 3.2 版起已弃用: 改用 getswitchinterval()。
- sys.getdefaultencoding()
- 返回 Unicode 实现使用的当前默认字符串编码的名称。
- sys.getdlopenflags()
- 返回用于
dlopen()
调用的标志的当前值。 标志值的符号名称可以在 os 模块中找到(RTLD_xxx
常量,例如 os.RTLD_LAZY)。
- sys.getfilesystemencoding()
返回用于在 Unicode 文件名和字节文件名之间转换的编码名称。 为了获得最佳兼容性,在所有情况下都应将 str 用于文件名,尽管也支持将文件名表示为字节。 接受或返回文件名的函数应该支持 str 或 bytes 并在内部转换为系统的首选表示。
此编码始终与 ASCII 兼容。
应该使用 os.fsencode() 和 os.fsdecode() 来确保使用正确的编码和错误模式。
在UTF-8模式下,任何平台的编码都是
utf-8
。在 Mac OS X 上,编码为
'utf-8'
。在 Unix 上,编码是语言环境编码。
在 Windows 上,编码可能是
'utf-8'
或'mbcs'
,具体取决于用户配置。
在 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 版中的新功能。
- sys.getrefcount(object)
- 返回 对象 的引用计数。 返回的计数通常比您预期的要高 1,因为它包含(临时)引用作为 getrefcount() 的参数。
- sys.getrecursionlimit()
- 返回递归限制的当前值,Python解释器堆栈的最大深度。 此限制可防止无限递归导致 C 堆栈溢出和 Python 崩溃。 可以通过 setrecursionlimit() 设置。
- sys.getsizeof(object[, default])
以字节为单位返回对象的大小。 对象可以是任何类型的对象。 所有内置对象都将返回正确的结果,但对于第三方扩展,这不一定适用,因为它是特定于实现的。
只考虑直接归因于对象的内存消耗,而不是它所引用的对象的内存消耗。
如果给定,如果对象不提供检索大小的方法,则将返回 default。 否则会引发 TypeError。
getsizeof() 调用对象的
__sizeof__
方法,如果对象由垃圾收集器管理,则会增加额外的垃圾收集器开销。有关使用 getsizeof() 递归查找容器大小及其所有内容的示例,请参阅 recursive sizeof recipe。
- sys.getswitchinterval()
返回解释器的“线程切换间隔”; 参见 setswitchinterval()。
3.2 版中的新功能。
- sys._getframe([depth])
- 从调用堆栈返回一个框架对象。 如果给定了可选整数 depth,则返回在堆栈顶部以下调用多次的框架对象。 如果这比调用堆栈更深,则会引发 ValueError。 depth 的默认值为零,返回调用堆栈顶部的帧。
- sys.getprofile()
- 获取由 setprofile() 设置的分析器函数。
- sys.gettrace()
- 获取由 settrace() 设置的跟踪函数。
- sys.getwindowsversion()
返回描述当前运行的 Windows 版本的命名元组。 命名元素为 major、minor、build、platform、service_pack、service_pack_minor[X13X] ]、service_pack_major、suite_mask、product_type和platform_version。 service_pack 包含一个字符串,platform_version 一个三元组,所有其他值都是整数。 组件也可以通过名称访问,因此
sys.getwindowsversion()[0]
等价于sys.getwindowsversion().major
。 为了与以前的版本兼容,只能通过索引检索前 5 个元素。平台将是
2 (VER_PLATFORM_WIN32_NT)
。product_type 可以是以下值之一:
持续的
意义
1 (VER_NT_WORKSTATION)
该系统是一个工作站。
2 (VER_NT_DOMAIN_CONTROLLER)
该系统是一个域控制器。
3 (VER_NT_SERVER)
系统是服务器,但不是域控制器。
该函数封装了Win32
GetVersionEx()
函数; 有关这些字段的更多信息,请参阅关于OSVERSIONINFOEX()
的 Microsoft 文档。platform_version 返回当前操作系统的准确主要版本、次要版本和内部版本号,而不是为进程模拟的版本。 它旨在用于记录而不是用于特征检测。
3.2 版本变更: 改为命名元组并添加 service_pack_minor、service_pack_major、suite_mask 和 .
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.get_coroutine_wrapper()
返回
None
,或由 set_coroutine_wrapper() 设置的包装器。3.5 版新功能:更多细节见PEP 492。
笔记
此功能已临时添加(有关详细信息,请参阅 PEP 411。)仅将其用于调试目的。
3.7 版本后已弃用:协程包装器功能已弃用,将在 3.8 中删除。 有关详细信息,请参阅 :issue:`32591`。
- sys.hash_info
一个 命名的元组 给出了数字哈希实现的参数。 有关数值类型散列的更多详细信息,请参阅 数值类型的散列 。
属性
解释
width
用于哈希值的位宽度
modulus
用于数字散列方案的素数模 P
inf
为正无穷大返回的哈希值
nan
为 nan 返回的哈希值
imag
用于复数虚部的乘数
algorithm
用于对 str、bytes 和 memoryview 进行散列的算法的名称
hash_bits
哈希算法的内部输出大小
seed_bits
哈希算法的种子密钥的大小
3.2 版中的新功能。
3.4 版更改: 添加 算法、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 language 的特定版本具有不同的含义,
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
,表示模块缓存应该关闭。sys.implementation 可能包含特定于 Python 实现的附加属性。 这些非标准属性必须以下划线开头,这里不做介绍。 无论其内容如何,sys.implementation 不会在解释器运行期间更改,也不会在实现版本之间更改。 (然而,它可能会在 Python 语言版本之间发生变化。)有关更多信息,请参阅 PEP 421。
3.3 版中的新功能。
笔记
添加新的必需属性必须经过正常的 PEP 流程。 有关更多信息,请参阅 PEP 421。
- sys.int_info
一个 命名的元组 ,它保存有关 Python 内部整数表示的信息。 属性是只读的。
属性
解释
bits_per_digit
每个数字中保存的位数。 Python 整数内部存储在基数
2**int_info.bits_per_digit
中sizeof_digit
用于表示数字的 C 类型的大小(以字节为单位)
3.1 版中的新功能。
- sys.__interactivehook__
当此属性存在时,当解释器以 交互模式 启动时,它的值会被自动调用(不带参数)。 这是在读取 PYTHONSTARTUP 文件后完成的,以便您可以在那里设置此钩子。 site模块设置这个。
3.4 版中的新功能。
- sys.intern(string)
在“interned”字符串表中输入string并返回interned字符串——它是string本身或副本。 实习字符串对于在字典查找中获得一点性能很有用 - 如果字典中的键是实习的,并且查找键是实习的,则键比较(散列后)可以通过指针比较而不是字符串比较来完成。 通常,Python 程序中使用的名称会自动插入,用于保存模块、类或实例属性的字典具有插入键。
实习字符串不是不朽的; 您必须保留对 intern() 的返回值的引用才能从中受益。
- sys.last_type
sys.last_value
sys.last_traceback 这三个变量并不总是被定义; 它们在未处理异常并且解释器打印错误消息和堆栈回溯时设置。 它们的预期用途是允许交互式用户导入调试器模块并进行事后调试,而无需重新执行导致错误的命令。 (典型使用是
import pdb; pdb.pm()
进入事后调试器;有关更多信息,请参阅 pdb 模块。)变量的含义与上面exc_info()的返回值相同。
- sys.maxsize
- 一个整数,给出
Py_ssize_t
类型的变量可以采用的最大值。 在 32 位平台上通常是2**31 - 1
,在 64 位平台上通常是2**63 - 1
。
- sys.maxunicode
给出最大 Unicode 代码点值的整数,即
1114111
(十六进制的0x10FFFF
)。在 3.3 版中更改:在 PEP 393、
sys.maxunicode
之前是0xFFFF
或0x10FFFF
,取决于指定 Unicode 字符是存储为 UCS-2 还是 UCS-4 的配置选项。
- sys.meta_path
元路径查找器 对象的列表,这些对象的 find_spec() 方法被调用以查看其中一个对象是否可以找到要导入的模块。 find_spec() 方法至少使用被导入模块的绝对名称来调用。 如果要导入的模块包含在包中,则父包的 __path__ 属性作为第二个参数传入。 如果找不到模块,该方法将返回 模块规范 或
None
。也可以看看
importlib.abc.MetaPathFinder
定义 meta_path 上的 finder 对象接口的抽象基类。
importlib.machinery.ModuleSpec
find_spec() 应该返回其实例的具体类。
3.4 版更改:模块规范 由 PEP 451 在 Python 3.4 中引入。 早期版本的 Python 寻找一种名为 find_module() 的方法。 如果 meta_path 条目没有 find_spec() 方法,这仍然被称为回退。
- sys.modules
- 这是一个将模块名称映射到已加载模块的字典。 这可以被操纵以强制重新加载模块和其他技巧。 但是,替换字典不一定会按预期工作,并且从字典中删除重要项目可能会导致 Python 失败。
- sys.path
指定模块搜索路径的字符串列表。 从环境变量 PYTHONPATH 初始化,加上依赖于安装的默认值。
在程序启动时初始化,此列表的第一项
path[0]
是包含用于调用 Python 解释器的脚本的目录。 如果脚本目录不可用(例如 如果解释器是交互式调用的,或者脚本是从标准输入中读取的),则path[0]
是空字符串,它指示 Python 首先搜索当前目录中的模块。 请注意,脚本目录插入 之前 作为 PYTHONPATH 的结果插入的条目。程序可以出于自己的目的自由修改此列表。 sys.path中只需要添加字符串和字节; 导入期间将忽略所有其他数据类型。
- sys.path_hooks
接受路径参数以尝试为路径创建 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 上,这是由
uname -s
返回的小写操作系统名称,并附加由uname -r
返回的版本的第一部分,例如'sunos5'
或'freebsd8'
,在 Python 构建时。 除非您想测试特定的系统版本,否则建议使用以下习语:if sys.platform.startswith('freebsd'): # FreeBSD-specific code here... elif sys.platform.startswith('linux'): # Linux-specific code here...
对于其他系统,这些值是:
系统
platform
值Linux
'linux'
视窗
'win32'
Windows/Cygwin
'cygwin'
Mac OS X
'darwin'
3.3 版更改: 在 Linux 上,sys.platform 不再包含主要版本。 它始终是
'linux'
,而不是'linux2'
或'linux3'
。 由于较旧的 Python 版本包含版本号,因此建议始终使用上述startswith
习语。
- sys.prefix
一个字符串,给出安装平台无关 Python 文件的站点特定目录前缀; 默认情况下,这是字符串
'/usr/local'
。 这可以在构建时使用 configure 脚本的--prefix
参数进行设置。 Python 库模块的主要集合安装在目录prefix/lib/pythonX.Y
中,而平台无关的头文件(除pyconfig.h
外的所有)存储在prefix/include/pythonX.Y
中,其中 XY[ X191X]是Python的版本号,例如3.2
。笔记
如果 虚拟环境 生效,则该值将在
site.py
中更改为指向虚拟环境。 Python 安装的值仍然可用,通过 base_prefix。
- sys.ps1
sys.ps2
- 指定解释器的主要和次要提示的字符串。 这些仅在解释器处于交互模式时才定义。 在这种情况下,它们的初始值是
'>>> '
和'... '
。 如果将非字符串对象分配给任一变量,则每次解释器准备读取新的交互式命令时,都会重新评估其 str(); 这可用于实现动态提示。
- sys.setcheckinterval(interval)
设置解释器的“检查间隔”。 这个整数值决定了解释器检查周期性事物(例如线程切换和信号处理程序)的频率。 默认值为
100
,表示每 100 条 Python 虚拟指令执行一次检查。 将其设置为更大的值可能会提高使用线程的程序的性能。 将其设置为值<=
0 会检查每个虚拟指令,从而最大限度地提高响应速度和开销。Deprecated since version 3.2: 此功能不再起作用,因为线程切换和异步任务的内部逻辑已被重写。 请改用 setswitchinterval()。
- sys.setdlopenflags(n)
- 设置解释器用于
dlopen()
调用的标志,例如当解释器加载扩展模块时。 除此之外,这将在导入模块时启用符号的延迟解析,如果调用为sys.setdlopenflags(0)
。 要在扩展模块之间共享符号,请调用sys.setdlopenflags(os.RTLD_GLOBAL)
。 标志值的符号名称可以在 os 模块中找到(RTLD_xxx
常量,例如 os.RTLD_LAZY)。
- sys.setprofile(profilefunc)
设置系统的profile函数,可以在Python中实现一个Python源码分析器。 有关 Python 探查器的更多信息,请参阅 一章 Python 探查器 。 系统的配置文件函数的调用方式与系统的跟踪函数类似(参见 settrace()),但它是用不同的事件调用的,例如它不会为每个执行的代码行调用(仅在调用时调用)并返回,但即使设置了异常也会报告返回事件)。 该函数是特定于线程的,但是分析器无法知道线程之间的上下文切换,因此在存在多个线程的情况下使用它没有意义。 另外,它的返回值没有被使用,所以它可以简单地返回
None
。 profile 函数中的错误将导致自身未设置。配置文件函数应具有三个参数:frame、event 和 arg。 frame 是当前堆栈帧。 event 是一个字符串:
'call'
、'return'
、'c_call'
、'c_return'
或'c_exception'
。 arg 取决于事件类型。这些事件具有以下含义:
'call'
调用了一个函数(或输入了一些其他代码块)。 profile 函数被调用; arg 是
None
。'return'
一个函数(或其他代码块)即将返回。 profile 函数被调用; arg 是将返回的值,如果事件是由引发的异常引起的,则为
None
。'c_call'
AC 函数即将被调用。 这可能是扩展功能或内置功能。 arg 是 C 函数对象。
'c_return'
AC 功能已返回。 arg 是 C 函数对象。
'c_exception'
AC 函数引发了异常。 arg 是 C 函数对象。
- sys.setrecursionlimit(limit)
将 Python 解释器堆栈的最大深度设置为 limit。 此限制可防止无限递归导致 C 堆栈溢出和 Python 崩溃。
可能的最高限制取决于平台。 当用户有需要深度递归的程序和支持更高限制的平台时,他们可能需要将限制设置得更高。 这应该小心完成,因为过高的限制会导致崩溃。
如果当前递归深度的新限制太低,则会引发 RecursionError 异常。
在 3.5.1 版更改:A RecursionError 如果新限制在当前递归深度下太低,现在会引发异常。
- sys.setswitchinterval(interval)
设置解释器的线程切换间隔(以秒为单位)。 这个浮点值决定了分配给并发运行的 Python 线程的“时间片”的理想持续时间。 请注意,实际值可能更高,尤其是在使用长时间运行的内部函数或方法时。 此外,在间隔结束时调度哪个线程是操作系统的决定。 解释器没有自己的调度程序。
3.2 版中的新功能。
- sys.settrace(tracefunc)
设置系统的trace功能,可以在Python中实现一个Python源码调试器。 该函数是线程特定的; 对于支持多线程的调试器,它必须使用 settrace() 为每个被调试的线程注册一个跟踪函数,或者使用 threading.settrace()。
跟踪函数应具有三个参数:frame、event 和 arg。 frame 是当前堆栈帧。 event 是一个字符串:
'call'
、'line'
、'return'
、'exception'
或'opcode'
。 arg 取决于事件类型。每当进入新的本地范围时,都会调用跟踪函数(将 event 设置为
'call'
); 它应该返回对用于新范围的本地跟踪函数的引用,或者如果不应该跟踪范围,则返回None
。本地跟踪函数应该返回对自身(或另一个函数以在该范围内进一步跟踪)的引用,或
None
以关闭该范围内的跟踪。如果trace函数有任何错误发生,它将被取消设置,就像调用
settrace(None)
一样。这些事件具有以下含义:
'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
以在每个帧上立即禁用自身)。有关代码和框架对象的更多信息,请参阅 标准类型层次结构 。
3.7 版本更改:添加了
'opcode'
事件类型;f_trace_lines
和f_trace_opcodes
属性添加到框架
- sys.set_asyncgen_hooks(firstiter, finalizer)
接受两个可选的关键字参数,它们是接受 异步生成器迭代器 作为参数的可调用对象。 firstiter callable 在异步生成器第一次迭代时会被调用。 finalizer 将在异步生成器即将被垃圾收集时被调用。
3.6 版新功能:参见 PEP 525 了解更多细节,finalizer 方法的参考示例参见 [ X162X] in :source:`Lib/asyncio/base_events.py`
笔记
此功能已临时添加(有关详细信息,请参阅 PEP 411。)
- sys.set_coroutine_origin_tracking_depth(depth)
允许启用或禁用协程源跟踪。 启用后,协程对象上的
cr_origin
属性将包含一个元组(文件名、行号、函数名)元组,描述创建协程对象的回溯,最近的调用在前。 禁用时,cr_origin
将为无。要启用,请传递一个大于零的 depth 值; 这将设置其信息将被捕获的帧数。 要禁用,请将 depth 设置为零。
此设置是特定于线程的。
3.7 版中的新功能。
笔记
此功能已临时添加(有关详细信息,请参阅 PEP 411。)仅将其用于调试目的。
- sys.set_coroutine_wrapper(wrapper)
允许拦截创建 coroutine 对象(仅由 async def 函数创建的对象;用 types.coroutine() 或 asyncio 修饰的生成器。 coroutine() 不会被拦截)。
wrapper 参数必须是:
一个接受一个参数的可调用对象(一个协程对象);
None
,重置包装器。
如果调用两次,新包装器将替换前一个。 该函数是线程特定的。
wrapper callable 不能直接或间接定义新的协程:
def wrapper(coro): async def wrap(coro): return await coro return wrap(coro) sys.set_coroutine_wrapper(wrapper) async def foo(): pass # The following line will fail with a RuntimeError, because # ``wrapper`` creates a ``wrap(coro)`` coroutine: foo()
3.5 版新功能:更多细节见PEP 492。
笔记
此功能已临时添加(有关详细信息,请参阅 PEP 411。)仅将其用于调试目的。
3.7 版本后已弃用:协程包装器功能已弃用,将在 3.8 中删除。 有关详细信息,请参阅 :issue:`32591`。
- sys._enablelegacywindowsfsencoding()
将默认文件系统编码和错误模式分别更改为 'mbcs' 和 'replace',以与 3.6 之前的 Python 版本保持一致。
这相当于在启动 Python 之前定义 PYTHONLEGACYWINDOWSFSENCODING 环境变量。
3.6 版新功能: 有关更多详细信息,请参阅 PEP 529。
- sys.stdin
sys.stdout
sys.stderr -
stdin
用于所有交互式输入(包括对 input() 的调用);stdout
用于 print() 和 expression 语句的输出和 input() 的提示;解释器自己的提示及其错误消息转到
stderr
。
这些流是常规的 文本文件 ,类似于 open() 函数返回的那些。 它们的参数选择如下:
字符编码是平台相关的。 非 Windows 平台使用区域设置编码(请参阅 locale.getpreferredencoding())。
在 Windows 上,UTF-8 用于控制台设备。 非字符设备如磁盘文件和管道使用系统区域设置编码(即 ANSI 代码页)。 非控制台字符设备,例如 NUL(即 其中
isatty()
返回True
) 使用启动时控制台输入和输出代码页的值,分别用于 stdin 和 stdout/stderr。 如果进程最初未连接到控制台,则默认为系统区域设置编码。控制台的特殊行为可以通过在启动 Python 之前设置环境变量 PYTHONLEGACYWINDOWSSTDIO 来覆盖。 在这种情况下,控制台代码页用作任何其他字符设备。
在所有平台下,您可以通过在启动 Python 之前设置 PYTHONIOENCODING 环境变量或使用新的 -X
utf8
来覆盖字符编码命令行选项和 PYTHONUTF8 环境变量。 但是,对于 Windows 控制台,这仅适用于还设置了 PYTHONLEGACYWINDOWSSTDIO 的情况。交互时,
stdout
和stderr
流是行缓冲的。 否则,它们像常规文本文件一样被块缓冲。 您可以使用 -u 命令行选项覆盖此值。
笔记
要从/向标准流写入或读取二进制数据,请使用底层二进制 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
以及原始值 [X88X]、__stdout__
和__stderr__
可以为None
。 对于未连接到控制台的 Windows GUI 应用程序和以 pythonw 开头的 Python 应用程序,通常是这种情况。
- sys.thread_info
一个 命名的元组 保存有关线程实现的信息。
属性
解释
name
线程实现的名称:
'nt'
:Windows 线程'pthread'
:POSIX 线程'solaris'
:Solaris 线程
lock
锁实现的名称:
'semaphore'
:锁使用信号量'mutex+cond'
:锁使用互斥锁和条件变量None
如果此信息未知
线程库的名称和版本。 它是一个字符串,如果此信息未知,则为
None
。3.3 版中的新功能。
- sys.tracebacklimit
- 当此变量设置为整数值时,它确定发生未处理的异常时打印的回溯信息的最大级别数。 默认值为
1000
。 当设置为0
或更少时,所有回溯信息都被抑制,只打印异常类型和值。
- sys.version
- 一个字符串,其中包含 Python 解释器的版本号以及有关所用版本号和编译器的附加信息。 该字符串在交互式解释器启动时显示。 不要从中提取版本信息,而是使用 version_info 和 platform 模块提供的功能。
- sys.api_version
- 此解释器的 C API 版本。 程序员在调试 Python 和扩展模块之间的版本冲突时可能会发现这很有用。
- sys.version_info
包含版本号五个组成部分的元组:major、minor、micro、releaselevel和serial ]。 除 releaselevel 之外的所有值都是整数; 发布级别为
'alpha'
、'beta'
、'candidate'
或'final'
。 Python 2.0版本对应的version_info
值为(2, 0, 0, 'final', 0)
。 组件也可以通过名称访问,所以sys.version_info[0]
等价于sys.version_info.major
等等。3.1 版更改: 添加命名组件属性。
- sys.warnoptions
- 这是警告框架的实现细节; 不要修改这个值。 有关警告框架的更多信息,请参阅 warnings 模块。
- sys.winver
- 用于在 Windows 平台上形成注册表项的版本号。 这在 Python DLL 中存储为字符串资源 1000。 该值通常是 version 的前三个字符。 它在 sys 模块中提供,用于提供信息; 修改此值对 Python 使用的注册表项没有影响。
- 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}
3.2 版中的新功能。
引文
- C99
- ISO/IEC 9899:1999。 “编程语言——C。” 该标准的公开草案可从 http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf 获得。