系统功能

xhz

这些是使来自 sys 模块的功能可以让 C 代码访问的工具函数。 它们都可用于当前解释器线程的 sys 模块的字典，该字典包含在内部线程状态结构体中。

PyObject *PySys_GetObject(const char *name)
返回值：借入的引用。 属于 稳定 ABI.
返回来自 sys 模块的对象 name 或者如果它不存在则返回 NULL，并且不会设置异常。

int PySys_SetObject(const char *name, PyObject *v)
属于 稳定 ABI.
将 sys 模块中的 name 设为 v 除非 v 为 NULL，在此情况下 name 将从 sys 模块中被删除。 成功时返回 0，发生错误时返回 -1。

void PySys_ResetWarnOptions()
属于 稳定 ABI.
将 sys.warnoptions 重置为空列表。 此函数可在 Py_Initialize() 之前被调用。

void PySys_AddWarnOption(const wchar_t *s)
属于 稳定 ABI.
此 API 被保留用于向下兼容：应当改为采用设置 PyConfig.warnoptions，参见 Python 初始化配置。

将 s 添加到 sys.warnoptions。 此函数必须在 Py_Initialize() 之前被调用以便影响警告过滤器列表。

自 3.11 版本弃用.

void PySys_AddWarnOptionUnicode(PyObject *unicode)
属于 稳定 ABI.
此 API 被保留用于向下兼容：应当改为采用设置 PyConfig.warnoptions，参见 Python 初始化配置。

将 unicode 添加到 sys.warnoptions。

注意：目前此函数不可在 CPython 实现之外使用，因为它必须在 Py_Initialize() 中的 warnings 显式导入之前被调用，但是要等运行时已初始化到足以允许创建 Unicode 对象时才能被调用。

自 3.11 版本弃用.

void PySys_SetPath(const wchar_t *path)
属于 稳定 ABI.
此 API 被保留用于向下兼容：应当改为采用设置 PyConfig.module_search_paths 和 PyConfig.module_search_paths_set，参见 Python 初始化配置。

将 sys.path 设为由在 path 中找到的路径组成的列表对象，该参数应为使用特定平台的搜索路径分隔符 (在 Unix 上为 :，在 Windows 上为 ;) 分隔的路径的列表。

自 3.11 版本弃用.

void PySys_WriteStdout(const char *format, ...)
属于 稳定 ABI.
将以 format 描述的输出字符串写入到 sys.stdout。 不会引发任何异常，即使发生了截断（见下文）。

format 应当将已格式化的输出字符串的总大小限制在 1000 字节以下 -- 超过 1000 字节后，输出字符串会被截断。 特别地，这意味着不应出现不受限制的 "%s" 格式；它们应当使用 "%.<N>s" 来限制，其中 <N> 是一个经计算使得 <N> 与其他已格式化文本的最大尺寸之和不会超过 1000 字节的十进制数字。 还要注意 "%f"，它可能为非常大的数字打印出数以百计的数位。

如果发生了错误，sys.stdout 会被清空，已格式化的消息将被写入到真正的 (C 层级) stdout。

void PySys_WriteStderr(const char *format, ...)
属于 稳定 ABI.
类似 PySys_WriteStdout()，但改为写入到 sys.stderr 或 stderr。

void PySys_FormatStdout(const char *format, ...)
属于 稳定 ABI.
类似 PySys_WriteStdout() 的函数将会使用 PyUnicode_FromFormatV() 来格式化消息并且不会将消息截短至任意长度。

在 3.2 版本加入.

void PySys_FormatStderr(const char *format, ...)
属于 稳定 ABI.
类似 PySys_FormatStdout()，但改为写入到 sys.stderr 或 stderr。

在 3.2 版本加入.

void PySys_AddXOption(const wchar_t *s)
属于 稳定 ABI 自 3.7 版开始.
此 API 被保留用于向下兼容：应当改为采用设置 PyConfig.xoptions，参见 Python 初始化配置。

将 s 解析为一个由 -X 选项组成的集合并将它们添加到 PySys_GetXOptions() 所返回的当前选项映射。 此函数可以在 Py_Initialize() 之前被调用。

在 3.2 版本加入.

自 3.11 版本弃用.

PyObject *PySys_GetXOptions()
返回值：借入的引用。 属于 稳定 ABI 自 3.7 版开始.
返回当前 -X 选项的字典，类似于 sys._xoptions。 发生错误时，将返回 NULL 并设置一个异常。

在 3.2 版本加入.

int PySys_Audit(const char *event, const char *format, ...)
引发一个审计事件并附带任何激活的钩子。 成功时返回零值或在失败时返回非零值并设置一个异常。

如果已添加了任何钩子，则将使用 format 和其他参数来构造一个用入传入的元组。 除 N 以外，在 Py_BuildValue() 中使用的格式字符均可使用。 如果构建的值不是一个元组，它将被添加到一个单元素元组中。 （格式选项 N 会消耗一个引用，但是由于没有办法知道此函数的参数是否将被消耗，因此使用它可能导致引用泄漏。）

请注意 # 格式字符应当总是被当作 Py_ssize_t 来处理，无论是否定义了 PY_SSIZE_T_CLEAN。

sys.audit() 会执行与来自 Python 代码的函数相同的操作。

在 3.8 版本加入.

在 3.8.2 版本发生变更: 要求 Py_ssize_t 用于 # 格式字符。 在此之前，会引发一个不可避免的弃用警告。

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)
将可调用对象 hook 添加到激活的审计钩子列表。 在成功时返回零而在失败时返回非零值。 如果运行时已经被初始化，还会在失败时设置一个错误。 通过此 API 添加的钩子会针对在运行时创建的所有解释器被调用。

userData 指针会被传入钩子函数。 因于钩子函数可能由不同的运行时调用，该指针不应直接指向 Python 状态。

此函数可在 Py_Initialize() 之前被安全地调用。 如果在运行时初始化之后被调用，现有的审计钩子将得到通知并可能通过引发一个从 Exception 子类化的错误静默地放弃操作（其他错误将不会被静默）。

这个钩子函数的类型为 int (*)(const char *event, PyObject *args, void *userData)，其中 args 会保证为 PyTupleObject。 这个钩子函数总是会附带引发该事件的 Python 解释器所持有的 GIL 来调用。

请参阅 PEP 578 了解有关审计的详细描述。 在运行时和标准库中会引发审计事件的函数清单见 审计事件表。 更多细节见每个函数的文档。

如果解释器已被初始化，此函数将引发审计事件 sys.addaudithook 且不附带任何参数。 如果有任何现存的钩子引发了一个派生自 Exception 的异常，新的钩子将不会被添加且该异常会被清除。 因此，调用方不可假定他们的钩子已被添加除非他们能控制所有现存的钩子。

在 3.8 版本加入.