Python/C API 实用函数（部分）

1 操作系统Utility

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

  若fp、filename关联的文件是交互式终端，则返回非0值（true），isatty(fileno(fp))。若全局变量Py_InteractiveFlag 为true，该函数在fp为NULL或filename为stdin或“???”的情况下也返回非0（true）。

• void PyOS_AfterFork()

  该函数会在一个进程fork后更新一些内部状态，若在fork的新进程中Python解析器继续使用，则该函数会被调用。如果新进程执行了新的可执行文件，这该函数不会执行。

• int PyOS_CheckStack()

  当Python解释器超出栈空间时返回true。当启用宏USE_STACKCHECK 时，该函数的检查是可信的。该宏默认是开启的，用户最好不要在自己的代码中关闭。

• PyOS_sighandler_t PyOS_getsig(int i)

  返回信号i当前的处理函数。该函数对函数sigaction() 或signal() 进行的简单的封装，所以不要直接调用这两个函数。PyOS_sighandler_t 是void (*)(int)的别名。

• PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

  为信号i设置信号处理函数h，并返回旧的信号处理函数。该函数是对函数sigaction() 或signal() 的封装，所以不要直接调用这两个函数。PyOS_sighandler_t 是void (*)(int)的别名。

2 系统函数

该类函数的功能与Python的sys模块的功能相同。

• PyObject * PySys_GetObject(const char *name)

  返回borrowed引用，该引用是sys模块中名字为name的模块对象，若没有该模块则返回NULL，不会设置异常。

• int PySys_SetObject(const char *name, PyObject *v)

  若v不为NULL，并且sys模块中名字为name的模块已经删除，则将sys模块中名字为name的模块设置为v。成功返回0，失败返回-1。

• void PySys_ResetWarnOptions()

  将sys.warnoptions 设置到一个空list中。

• void PySys_AddWarnOption(wchar_t *s)

  将s加入sys.warnoptions。

• void PySys_AddWarnOptionUnicode(PyObject *unicode)

  将unicode加入sys.warnoptions。

• void PySys_SetPath(wchar_t *path)

  将sys.path 设置为参数path转换成的list对象，参数是一个路径列表，Unix系统中使用“:”分割，windows中使用“;”分割。

• void PySys_WriteStdout(const char *format, …)

  将信息写到sys.stdout，不会抛出异常。如果有问题出现或sys.stdout没有设置，格式化的信息会被输出至C语言级的stdout。

  注意：输出有长度限制，格式化输出的字符串不得超过1000字节。

• void PySys_WriteStderr(const char *format, …)

  类似于PySys_WriteStdout()，区别仅在于输出至stderr。

• void PySys_FormatStdout(const char *format, …)

  类似PySys_WriteStdout()，区别在于该函数的信息使用PyUnicode_FromFormatV()，并且不会因长度原因被截断。

• void PySys_FormatStderr(const char *format, …)

  类似与PySys_FormatStdout()，区别在于输出值stderr。

3 进程控制

• void Py_FatalError(const char *message)

  打印一个严重错误信息并kill当前进程，不会执行cleanup过程。当出现异常并无法继续执行Python解释器时，可调用此函数。在Unix系统中，C标准库函数abort()会被调用以生成core文件。

• void Py_Exit(int status)

  退出当前进程，该函数首先调用Py_Finalize()然后调用C标准库函数exit(status)。

• int Py_AtExit(void(*func)())

  注册cleanup函数，这些函数会被Py_Finalize()调用。最多可注册32个cleanup函数。函数注册成功返回0，注册失败返回-1。最后注册的函数会首先执行，每个注册的函数只执行一次。这些被注册的函数会在Py_Finalize()执行之后在执行，所以在被注册的函数不能调用Python API。

4 导入模块

• PyObject * PyImport_ImportModule(const char *name)

• PyObject * PyImport_Import(PyObject *name)

  该函数会返回被导入模块的一个新引用，失败返回NULL。后者的参数是Unicode对象。

• PyObject * PyImport_ReloadModule(PyObject *m)

  重新加载一个模块，返回该模块的一个新引用，失败返回NULL。

• PyObject * PyImport_AddModuleObject(PyObject *name)

  返回参数name关联的模块对象，参数name可能是“package.module”的形式。该函数首先检查模块目录，如果目录不存在，就创建该目录并将该目录加入模块dictionary中。当出错时返回NULL。参数name为Unicode对象。

• PyObject * PyImport_AddModule(const char *name)

  返回borrowed引用，类似于PyImport_AddModuleObject()，只是参数name是UTF8编码的字符串而不是Unicode对象。

• long PyImport_GetMagicNumber()

  返回Python字节码文件（.pyc或.pyo文件）的magic数字，该魔法数是字节码文件的前四个字节，小端字节序。出错时返回-1。

• PyObject * PyImport_GetModuleDict()

  返回borrowed引用。返回值是模块管理器的字典（即：sys.modules），注意：每个解释器都有一个该字典。

• void PyImport_Cleanup()

  清空the module table。

5 数据序列化

用于本节函数读写的文件，需以二进制方式打开。

数值变量会被保存在尽量少的字节中。

宏Py_MARSHAL_VERSION，决定的序列化的格式。

• void PyMarshal_WriteLongToFile(long value, int version)

  This will only write the least-significant 32 bits of value; regardless of the size of the native long type。

• void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
• PyObject * PyMarshal_WriteObjectToString(PyObject *value, int version)

• long PyMarshal_ReadLongFromFile(FILE *file)

  Only a 32-bit value can be read in using this function, regardless of the native size of long。失败返回-1。

• int PyMarshal_ReadShortFromFile(FILE *file)

  失败返回-1。

• PyObject * PyMarshal_ReadObjectFromFile(FILE *file)

  成功返回一个新的引用，失败返回NULL。

• PyObject * PyMarshal_ReadObjectFromString(const char *string, Py_ssize_t len)

  参数string为地址，len为buffer的长度；成功返回一个新引用，失败返回NULL。

6 解析参数、创建变量

6.1 格式化字符

• s Unicode对象<–>C语言风格的UTF8编码字符串，Unicode对象一定不能以NULL结尾，C风格字符串需以NULL结尾。
• b Python integar<–>unsigned char
• B Python integar<–>unsigned char，无溢出检查
• h Python integar<–>short
• H Python integar<–>unsigned short，无溢出检查
• i Python integar<–>int
• I Python integar<–>unsigned int，无溢出检查
• l Python integar<–>long
• k Python integar<–>unsigned long，无溢出检查
• L Python integar<–>long long
• K Python integar<–>unsigned long long
• n Python integar<–>Py_ssize_t
• c Python byte<–>char
• C Python charactor<–>char
• f Python float<–>float
• d Python float<–>double
• D Python complex<–>Py_complex
• o Store a Python object (without any conversion) in a C object pointer.
• p bool<–>int(1表示true，0表示false)

6.2 解析函数

• int PyArg_ParseTuple(PyObject *args, const char *format, …)

• int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)

  成功返回true，失败返回false

PyObject *pval = Py_BuildValue("(i)", );
int a;
PyArg_ParseTuple(pval, "i", &a);
printf("%d\n", a);
           

6.3 构建函数

• PyObject* Py_BuildValue(const char *format, …)

• PyObject* Py_VaBuildValue(const char *format, va_list vargs)

  成功返回构建对象的一个新的引用，失败返回NULL

  (items) 构建元组

  [items] 构建tuple

  {items} 构建dict

  该函数的参数format包含多余两个以上的unit时，该函数会构建一个元组。若参数format字符串为空，该函数返回None。当且仅当参数format只包含一个unit时，该函数才会构建对应的对象。若欲构建空元组或只包含一个元素的元组，则需要在参数format中使用小括号。