有用的宏

xhz

Python 头文件中定义了一些有用的宏。许多是在靠近它们被使用的地方定义的（例如 Py_RETURN_NONE）。其他更为通用的则定义在这里。这里所显示的并不是一个完整的列表。

PyMODINIT_FUNC
声明扩展模块 PyInit 初始化函数。 函数返回类型为 PyObject*。 该宏声明了平台所要求的任何特殊链接声明，并针对 C++ 将函数为声明为 extern "C"。

初始化函数必须命名为 PyInit_name，其中 name 是模块名称，并且应为在模块文件中定义的唯一非 static 项。 例如:

static struct PyModuleDef spam_module = {
    PyModuleDef_HEAD_INIT,
    .m_name = "spam",
    ...
};

PyMODINIT_FUNC
PyInit_spam(void)
{
    return PyModule_Create(&spam_module);
}
Py_ABS(x)
返回 x 的绝对值。

3.3 新版功能.

Py_ALWAYS_INLINE
让编译器始终内联静态的内联函数。 编译器可以忽略它并决定不内联该函数。

它可被用来在禁用函数内联的调试模式下构建 Python 时内联严重影响性能的静态内联函数。 例如，MSC 在调试模式下构建时就禁用了函数内联。

随意使用 Py_ALWAYS_INLINE 标记内联函数可能导致极差的性能（例如由于增加了代码量）。 对于成本/收益分析来说计算机通常都比开发者更聪明。

如果 Python 是 在调试模式下构建 (即定义了 Py_DEBUG 宏)，则 Py_ALWAYS_INLINE 宏将不做任何事情。

它必须在函数返回类型之前指明。 用法:

static inline Py_ALWAYS_INLINE int random(void) { return 4; }
3.11 新版功能.

Py_CHARMASK(c)
参数必须为 [-128, 127] 或 [0, 255] 范围内的字符或整数类型。这个宏将 c 强制转换为 unsigned char 返回。

Py_DEPRECATED(version)
弃用声明。该宏必须放置在符号名称前。

示例:

Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
在 3.8 版更改: 添加了 MSVC 支持。

Py_GETENV(s)
与 getenv(s) 类似，但是如果从命令行传入了 -E 则返回 NULL (参见 PyConfig.use_environment)。

Py_MAX(x, y)
返回 x 和 y 当中的最大值。

3.3 新版功能.

Py_MEMBER_SIZE(type, member)
返回结构 (type) member 的大小，以字节表示。

3.6 新版功能.

Py_MIN(x, y)
返回 x 和 y 当中的最小值。

3.3 新版功能.

Py_NO_INLINE
启用内联某个函数。 例如，它会减少 C 栈消耗：适用于大量内联代码的 LTO+PGO 编译版 (参见 bpo-33720)。

用法：

Py_NO_INLINE static int random(void) { return 4; }
3.11 新版功能.

Py_STRINGIFY(x)
将 x 转换为 C 字符串。例如 Py_STRINGIFY(123) 返回 "123"。

3.4 新版功能.

Py_UNREACHABLE()
这个可以在你有一个设计上无法到达的代码路径时使用。例如，当一个 switch 语句中所有可能的值都已被 case 子句覆盖了，就可将其用在 default: 子句中。当你非常想在某个位置放一个 assert(0) 或 abort() 调用时也可以用这个。

在 release 模式下，该宏帮助编译器优化代码，并避免发出不可到达代码的警告。例如，在 GCC 的 release 模式下，该宏使用 __builtin_unreachable() 实现。

Py_UNREACHABLE() 的一个用法是调用一个不会返回，但却没有声明 _Py_NO_RETURN 的函数之后。

如果一个代码路径不太可能是正常代码，但在特殊情况下可以到达，就不能使用该宏。例如，在低内存条件下，或者一个系统调用返回超出预期范围值，诸如此类，最好将错误报告给调用者。如果无法将错误报告给调用者，可以使用 Py_FatalError() 。

3.7 新版功能.

Py_UNUSED(arg)
用于函数定义中未使用的参数，从而消除编译器警告。例如： int func(int a, int Py_UNUSED(b)) { return a; } 。

3.4 新版功能.

PyDoc_STRVAR(name, str)
创建一个可以在文档字符串中使用的，名字为 name 的变量。如果不和文档字符串一起构建 Python，该值将为空。

如 PEP 7 所述，使用 PyDoc_STRVAR 作为文档字符串，以支持不和文档字符串一起构建 Python 的情况。

示例:

PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");

static PyMethodDef deque_methods[] = {
    // ...
    {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
    // ...
}
PyDoc_STR(str)
为给定的字符串输入创建一个文档字符串，或者当文档字符串被禁用时，创建一个空字符串。

如 PEP 7 所述，使用 PyDoc_STR 指定文档字符串，以支持不和文档字符串一起构建 Python 的情况。

示例:

static PyMethodDef pysqlite_row_methods[] = {
    {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
        PyDoc_STR("Returns the keys of the row.")},
    {NULL, NULL}
};