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)", 200);
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中使用小括号。