操作系统实用工具

PyObject *PyOS_FSPath(PyObject *path)
返回值:新引用。自 3.6 版本起成为 稳定 ABI 的一部分。

返回 path 的文件系统表示形式。如果对象是 strbytes 对象,则返回新的 强引用。如果对象实现了 os.PathLike 接口,则只要它是 strbytes 对象,就会返回 __fspath__()。否则,会引发 TypeError 并返回 NULL

在 3.6 版本中添加。

int Py_FdIsInteractive(FILE *fp, const char *filename)

如果标准 I/O 文件 fp 的名称 filename 被认为是交互式的,则返回 true(非零)。对于满足 isatty(fileno(fp)) 为 true 的文件是这种情况。如果 PyConfig.interactive 为非零,则如果 filename 指针为 NULL 或者名称等于字符串 '<stdin>''???' 之一,此函数也会返回 true。

此函数不得在 Python 初始化之前调用。

void PyOS_BeforeFork()
自 3.7 版本起,在具有 fork() 的平台上成为 稳定 ABI 的一部分。

在进程 fork 之前准备一些内部状态的函数。这应该在调用 fork() 或任何类似的克隆当前进程的函数之前调用。仅在定义了 fork() 的系统上可用。

警告

C fork() 调用应仅从 “主”线程“主”解释器)调用。PyOS_BeforeFork() 也是如此。

在 3.7 版本中添加。

void PyOS_AfterFork_Parent()
自 3.7 版本起,在具有 fork() 的平台上成为 稳定 ABI 的一部分。

在进程 fork 之后更新一些内部状态的函数。这应该在调用 fork() 或任何类似的克隆当前进程的函数之后,从父进程调用,无论进程克隆是否成功。仅在定义了 fork() 的系统上可用。

警告

C fork() 调用应仅从 “主”线程“主”解释器)调用。PyOS_AfterFork_Parent() 也是如此。

在 3.7 版本中添加。

void PyOS_AfterFork_Child()
自 3.7 版本起,在具有 fork() 的平台上成为 稳定 ABI 的一部分。

在进程 fork 之后更新内部解释器状态的函数。如果在进程中有任何可能调用回 Python 解释器的情况,则必须在调用 fork() 或任何类似的克隆当前进程的函数之后,从子进程调用此函数。仅在定义了 fork() 的系统上可用。

警告

C fork() 调用应仅从 “主”线程“主”解释器)调用。PyOS_AfterFork_Child() 也是如此。

在 3.7 版本中添加。

另请参阅

os.register_at_fork() 允许注册由 PyOS_BeforeFork()PyOS_AfterFork_Parent()PyOS_AfterFork_Child() 调用的自定义 Python 函数。

void PyOS_AfterFork()
在具有 fork() 的平台上成为 稳定 ABI 的一部分。

在进程 fork 之后更新一些内部状态的函数;如果 Python 解释器将继续使用,则应在新进程中调用此函数。如果新进程中加载了新的可执行文件,则无需调用此函数。

自 3.7 版本起弃用: 此函数被 PyOS_AfterFork_Child() 取代。

int PyOS_CheckStack()
自 3.7 版本起,在具有 USE_STACKCHECK 的平台上成为 稳定 ABI 的一部分。

当解释器耗尽堆栈空间时返回 true。这是一个可靠的检查,但仅在定义了 USE_STACKCHECK 时可用(目前在使用 Microsoft Visual C++ 编译器的某些 Windows 版本上)。USE_STACKCHECK 将自动定义;您绝不应在自己的代码中更改定义。

typedef void (*PyOS_sighandler_t)(int)
属于 稳定 ABI 的一部分。
PyOS_sighandler_t PyOS_getsig(int i)
属于 稳定 ABI 的一部分。

返回信号 i 的当前信号处理程序。这是对 sigaction()signal() 的一个简单封装。请不要直接调用这些函数!

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
属于 稳定 ABI 的一部分。

将信号 i 的信号处理程序设置为 h;返回旧的信号处理程序。这是对 sigaction()signal() 的一个简单封装。请不要直接调用这些函数!

wchar_t *Py_DecodeLocale(const char *arg, size_t *size)
自 3.7 版本起成为 稳定 ABI 的一部分。

警告

不应直接调用此函数:请使用 PyConfig API 和 PyConfig_SetBytesString() 函数,以确保 Python 已被预初始化

必须在 Python 被预初始化 之后才能调用此函数,以便正确配置 LC_CTYPE 区域设置:请参阅 Py_PreInitialize() 函数。

文件系统编码和错误处理程序解码字节字符串。如果错误处理程序是 surrogateescape 错误处理程序,则不可解码的字节将解码为 U+DC80..U+DCFF 范围内的字符;如果一个字节序列可以解码为代理字符,则将使用 surrogateescape 错误处理程序来转义字节,而不是解码它们。

返回指向新分配的宽字符字符串的指针,使用 PyMem_RawFree() 来释放内存。如果 size 不为 NULL,则将不包括空字符的宽字符数写入 *size

在解码错误或内存分配错误时返回 NULL。如果 size 不为 NULL,则在内存错误时将 *size 设置为 (size_t)-1,或在解码错误时设置为 (size_t)-2

文件系统编码和错误处理程序PyConfig_Read() 选择:请参阅 filesystem_encodingfilesystem_errorsPyConfig 成员。

除非 C 库中存在错误,否则不应发生解码错误。

使用 Py_EncodeLocale() 函数将字符字符串编码回字节字符串。

在 3.5 版本中添加。

在 3.7 版本中更改: 该函数现在在 Python UTF-8 模式中使用 UTF-8 编码。

在 3.8 版本中更改: 如果 PyPreConfig.legacy_windows_fs_encoding 为零,则该函数现在在 Windows 上使用 UTF-8 编码;

char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
自 3.7 版本起成为 稳定 ABI 的一部分。

将宽字符字符串编码为 文件系统编码和错误处理程序。如果错误处理程序是 surrogateescape 错误处理程序,则 U+DC80..U+DCFF 范围内的代理字符将转换为字节 0x80..0xFF。

返回指向新分配的字节字符串的指针,使用 PyMem_Free() 来释放内存。在编码错误或内存分配错误时返回 NULL

如果 error_pos 不为 NULL,则在成功时将 *error_pos 设置为 (size_t)-1,或在编码错误时设置为无效字符的索引。

文件系统编码和错误处理程序PyConfig_Read() 选择:请参阅 filesystem_encodingfilesystem_errorsPyConfig 成员。

使用 Py_DecodeLocale() 函数将字节字符串解码回宽字符字符串。

警告

必须在 Python 被预初始化 之后才能调用此函数,以便正确配置 LC_CTYPE 区域设置:请参阅 Py_PreInitialize() 函数。

另请参阅

请参考 PyUnicode_EncodeFSDefault()PyUnicode_EncodeLocale() 函数。

在 3.5 版本中添加。

在 3.7 版本中更改: 该函数现在在 Python UTF-8 模式中使用 UTF-8 编码。

在 3.8 版本中更改: 如果 PyPreConfig.legacy_windows_fs_encoding 为零,则该函数现在在 Windows 上使用 UTF-8 编码。

系统函数

这些是实用函数,使 C 代码可以访问 sys 模块的功能。 它们都使用当前解释器线程的 sys 模块的 dict,该 dict 包含在内部线程状态结构中。

PyObject *PySys_GetObject(const char *name)
返回值:借来的引用。 稳定 ABI 的一部分。

sys 模块返回对象 name,如果该对象不存在,则返回 NULL,而不设置异常。

int PySys_SetObject(const char *name, PyObject *v)
属于 稳定 ABI 的一部分。

sys 模块中的 name 设置为 v,除非 vNULL,在这种情况下,将从 sys 模块中删除 name。 成功时返回 0,错误时返回 -1

void PySys_ResetWarnOptions()
属于 稳定 ABI 的一部分。

sys.warnoptions 重置为空列表。此函数可以在 Py_Initialize() 之前调用。

自 3.13 版本起已弃用,将在 3.15 版本中移除: 请改为清除 sys.warnoptionswarnings.filters

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

void PySys_FormatStdout(const char *format, ...)
属于 稳定 ABI 的一部分。

函数类似于 PySys_WriteStdout(),但使用 PyUnicode_FromFormatV() 格式化消息,并且不会将消息截断为任意长度。

在 3.2 版本中添加。

void PySys_FormatStderr(const char *format, ...)
属于 稳定 ABI 的一部分。

PySys_FormatStdout() 类似,但写入 sys.stderrstderr

在 3.2 版本中添加。

PyObject *PySys_GetXOptions()
返回值:借用的引用。 自 3.7 版本以来是 稳定 ABI 的一部分。

返回当前 -X 选项的字典,类似于 sys._xoptions。如果发生错误,则返回 NULL 并设置异常。

在 3.2 版本中添加。

int PySys_Audit(const char *event, const char *format, ...)
自 3.13 版本以来是 稳定 ABI 的一部分。

使用任何活动钩子引发审计事件。成功返回零,失败返回非零并设置异常。

event 字符串参数不得为 NULL

如果已添加任何钩子,则将使用 format 和其他参数来构造一个元组来传递。除了 N,还提供与 Py_BuildValue() 中使用的相同的格式字符。如果构建的值不是元组,则将其添加到单元素元组中。

不得使用 N 格式选项。它会消耗一个引用,但由于无法知道此函数的参数是否会被消耗,因此使用它可能会导致引用泄漏。

请注意,# 格式字符应始终被视为 Py_ssize_t,无论是否定义了 PY_SSIZE_T_CLEAN

sys.audit() 从 Python 代码执行相同的功能。

另请参见 PySys_AuditTuple()

在 3.8 版本中添加。

在 3.8.2 版本中更改: # 格式字符需要 Py_ssize_t。 以前,会引发不可避免的弃用警告。

int PySys_AuditTuple(const char *event, PyObject *args)
自 3.13 版本以来是 稳定 ABI 的一部分。

类似于 PySys_Audit(),但将参数作为 Python 对象传递。args 必须是 tuple。要传递不带参数,args 可以为 NULL

在 3.13 版本中添加。

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

将可调用 hook 附加到活动审计钩子的列表。成功返回零,失败返回非零。如果运行时已初始化,则在失败时也设置错误。通过此 API 添加的钩子将为运行时创建的所有解释器调用。

userData 指针将传递到钩子函数中。由于可以从不同的运行时调用钩子函数,因此此指针不应直接引用 Python 状态。

此函数在 Py_Initialize() 之前调用是安全的。在运行时初始化之后调用时,会通知现有的审计钩子,并且可能会通过引发 Exception 的错误子类来静默中止操作(其他错误不会被静默)。

钩子函数始终在引发事件的 Python 解释器持有 GIL 的情况下调用。

有关审计的详细说明,请参见 PEP 578。 运行时和标准库中引发事件的函数在 审计事件表 中列出。 详细信息在每个函数的文档中。

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

typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)

钩子函数的类型。event 是传递给 PySys_Audit()PySys_AuditTuple() 的 C 字符串事件参数。args 保证是一个 PyTupleObjectuserData 是传递给 PySys_AddAuditHook() 的参数。

在 3.8 版本中添加。

进程控制

void Py_FatalError(const char *message)
属于 稳定 ABI 的一部分。

打印一个致命错误消息并终止进程。不执行清理操作。只有在检测到继续使用 Python 解释器会很危险的情况下才应调用此函数;例如,当对象管理似乎已损坏时。在 Unix 上,将调用标准 C 库函数 abort(),它将尝试生成一个 core 文件。

除非定义了 Py_LIMITED_API 宏,否则 Py_FatalError() 函数会被一个自动记录当前函数名称的宏替换。

在 3.9 版本中更改: 自动记录函数名称。

void Py_Exit(int status)
属于 稳定 ABI 的一部分。

退出当前进程。此函数调用 Py_FinalizeEx(),然后调用标准 C 库函数 exit(status)。如果 Py_FinalizeEx() 指示有错误,则退出状态设置为 120。

在 3.6 版本中更改: 不再忽略来自最终化的错误。

int Py_AtExit(void (*func)())
属于 稳定 ABI 的一部分。

注册一个由 Py_FinalizeEx() 调用的清理函数。清理函数将在不带参数的情况下调用,并且不应返回值。最多可以注册 32 个清理函数。当注册成功时,Py_AtExit() 返回 0;失败时,它返回 -1。最后注册的清理函数将首先被调用。每个清理函数最多只会被调用一次。由于 Python 的内部最终化将在清理函数之前完成,因此 func 不应调用任何 Python API。

另请参阅

使用 PyUnstable_AtExit() 传递 void *data 参数。