操作系统实用工具¶
-
PyObject *PyOS_FSPath(PyObject *path)¶
- 返回值:新引用。自 3.6 版本起成为 稳定 ABI 的一部分。
返回 path 的文件系统表示形式。如果对象是
str
或bytes
对象,则返回新的 强引用。如果对象实现了os.PathLike
接口,则只要它是str
或bytes
对象,就会返回__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()
的系统上可用。在 3.7 版本中添加。
-
void PyOS_AfterFork_Parent()¶
- 自 3.7 版本起,在具有 fork() 的平台上成为 稳定 ABI 的一部分。
在进程 fork 之后更新一些内部状态的函数。这应该在调用
fork()
或任何类似的克隆当前进程的函数之后,从父进程调用,无论进程克隆是否成功。仅在定义了fork()
的系统上可用。在 3.7 版本中添加。
-
void PyOS_AfterFork_Child()¶
- 自 3.7 版本起,在具有 fork() 的平台上成为 稳定 ABI 的一部分。
在进程 fork 之后更新内部解释器状态的函数。如果在进程中有任何可能调用回 Python 解释器的情况,则必须在调用
fork()
或任何类似的克隆当前进程的函数之后,从子进程调用此函数。仅在定义了fork()
的系统上可用。在 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
将自动定义;您绝不应在自己的代码中更改定义。
-
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_encoding
和filesystem_errors
的PyConfig
成员。除非 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_encoding
和filesystem_errors
的PyConfig
成员。使用
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,除非 v 为NULL
,在这种情况下,将从 sys 模块中删除 name。 成功时返回0
,错误时返回-1
。
-
void PySys_ResetWarnOptions()¶
- 属于 稳定 ABI 的一部分。
将
sys.warnoptions
重置为空列表。此函数可以在Py_Initialize()
之前调用。自 3.13 版本起已弃用,将在 3.15 版本中移除: 请改为清除
sys.warnoptions
和warnings.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.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 版本中添加。
-
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 保证是一个PyTupleObject
。userData 是传递给 PySys_AddAuditHook() 的参数。
在 3.8 版本中添加。
-
typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)¶
进程控制¶
-
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
参数。