如何扩展NumPy

功能没有关键字参数¶

不接受关键字参数的函数应写为：

static PyObject*
nokeyword_cfunc (PyObject *dummy, PyObject *args)
{
    /* convert Python arguments */
    /* do function */
    /* return something */
}

在此上下文中不使用dummy参数，可以安全地将其忽略。该ARGS参数包含所有的到的功能作为一个元组传递的参数。您可以在此时进行任何操作，但是通常，管理输入参数的最简单方法是调用PyArg_ParseTuple（args，format_string，addresss_to_C_variables…）或PyArg_UnpackTuple（元组，“名称”，最小，最大...）。Python C-API参考手册中的5.5节（解析参数和构建值）中包含有关如何使用第一个函数的详细说明。您应该特别注意“ O＆”格式，该格式使用转换器函数在Python对象和C对象之间移动。所有其他格式功能都可以（通常）视为该通用规则的特殊情况。在NumPy C-API中定义了一些可能有用的转换器函数。特别是，该PyArray_DescrConverter 功能对于支持任意数据类型规范非常有用。此函数将任何有效的数据类型Python对象转换为一个 对象。请记住传递应该填写的C变量的地址。PyArray_Descr *

关于如何在PyArg_ParseTuple 整个NumPy源代码中使用的示例很多。标准用法是这样的：

PyObject *input;
PyArray_Descr *dtype;
if (!PyArg_ParseTuple(args, "OO&", &input,
                      PyArray_DescrConverter,
                      &dtype)) return NULL;

重要的是要记住，你会得到一个很重要借来使用“O”格式字符串时参考的对象。但是，转换器功能通常需要某种形式的内存处理。在此示例中，如果转换成功，则dtype将保存对对象的新引用，而input将保存借用的引用。因此，如果此转换与另一个转换（例如，转换为整数）混合在一起，并且数据类型转换成功，但是整数转换失败，那么您需要在返回之前将引用计数释放到数据类型对象。一种典型的方法是 在调用之前将dtype设置为，然后 在dtype上使用PyArray_Descr *NULLPyArg_ParseTuplePy_XDECREF 返回之前。

在处理完输入参数之后，将编写实际完成工作的代码（可能会根据需要调用其他函数）。C函数的最后一步是返回一些东西。如果遇到错误，NULL则应返回（确保已实际设置了错误）。如果不返回任何内容，则递增 Py_None并返回。如果应该返回单个对象，则将其返回（确保您首先拥有对该对象的引用）。如果应该返回多个对象，则需要返回一个元组。的Py_BuildValue（format_string，c_variables…）函数使从C变量构建Python对象的元组变得容易。请特别注意格式字符串中“ N”和“ O”之间的区别，否则您很容易造成内存泄漏。“ O”格式字符串会增加其对应的C变量的引用计数，而“ N”格式字符串会窃取对相应C变量的引用。如果已经为对象创建了引用，并且只想将该引用提供给元组，则应使用“ N”。如果您仅借用了一个对象的引用，并且需要创建一个对象来提供元组，则应使用“ O”。PyObject *PyObject *

与关键字参数的函数¶

这些功能与没有关键字参数的功能非常相似。唯一的区别是函数签名是：

static PyObject*
keyword_cfunc (PyObject *dummy, PyObject *args, PyObject *kwds)
{
...
}

kwds参数包含一个Python字典，其字典的键是关键字参数的名称，其值是相应的关键字参数值。可以处理此词典，但您认为合适。但是，最简单的处理方法是将 PyArg_ParseTuple（args，format_string PyArg_ParseTupleAndKeywords，addresss ...）函数替换为对（args，kwds，format_string，char * kwlist []，addresss ...）的调用。此函数的kwlist参数是一个NULL以字符串结尾的字符串，提供了预期的关键字参数。format_string中的每个条目应该有一个字符串。如果传入无效的关键字参数，则使用此函数将引发TypeError。

有关此功能的更多帮助，请参见Python文档中“扩展和嵌入”教程的第1.8节（扩展功能的关键字参数）。

参考计数¶

编写扩展模块时最大的困难是引用计数。这是f2py，weave，Cython，ctypes等流行的重要原因。如果您错误地处理了引用计数，则可能会遇到从内存泄漏到分段错误的问题。我知道正确处理参考计数的唯一策略是血液，汗水和眼泪。首先，您必须让每个Python变量都有一个引用计数。然后，您可以准确地了解每个函数对对象的引用计数的作用，以便在需要它们时可以正确使用DECREF和INCREF。引用计数可以真正测试您对编程技巧的耐心和勤奋程度。尽管描述严峻，大多数引用计数情况非常简单，最常见的困难是由于某些错误，在从例程中提前退出之前不对对象使用DECREF。其次，常见的错误是在传递给要窃取引用的函数或宏的对象上不拥有引用（例如 PyTuple_SET_ITEM，以及大多数带有PyArray_Descr对象的函数）。

通常，创建变量时它会得到一个新的引用，或者它是某个函数的返回值（但是，有一些突出的例外情况，例如从元组或字典中删除项目）。当您拥有引用时，您有责任确保Py_DECREF在不再需要该变量（并且没有其他函数“窃取”其引用）时调用（var）。另外，如果将Python对象传递给将“窃取”引用的函数，则需要确保自己拥有该Py_INCREF引用（或用于获取自己的引用）。您还将遇到借用参考的概念。借用引用的函数不会更改对象的引用计数，并且不会期望“保留”该引用。只是临时使用该对象。使用时PyArg_ParseTuple否则， PyArg_UnpackTuple您会收到对元组中的对象的借用引用，并且不应在函数中更改它们的引用计数。通过实践，您可以学习正确地进行引用计数，但是起初可能会感到沮丧。

Py_BuildValue 函数是引用计数错误的一种常见来源。请注意“ N”格式字符和“ O”格式字符之间的区别。如果您在子例程（例如输出数组）中创建了一个新对象，并且将其以返回值的元组传递回去，那么您很可能应该在其中使用'N'格式字符Py_BuildValue。“ O”字符会将引用计数增加一。这将为调用者提供一个全新数组的两个引用计数。当删除该变量并将引用计数减一时，仍然会有额外的引用计数，并且该数组将永远不会被释放。您将有一个引用计数导致的内存泄漏。使用'N'字符可以避免这种情况，因为它将返回给调用方一个具有单个引用计数的对象（在元组内部）。

转换的任意序列对象¶

从任何可以转换为数组的Python对象获取数组的主要例程是PyArray_FromAny。该函数非常灵活，具有许多输入参数。几个宏使使用基本功能更加容易。PyArray_FROM_OTF对于最常见的用途，可以说是最有用的宏。它允许您在指定一组特定要求（例如连续，对齐和可写）的同时，将任意Python对象转换为特定内置数据类型（例如 float）的数组。语法是

PyArray_FROM_OTF

从任何Python对象obj返回一个ndarray，该对象可以转换为数组。返回数组中的维数由对象确定。返回的数组的所需数据类型以typenum提供，该类型应为枚举类型之一。返回数组的要求可以是标准数组标志的任意组合。这些论点中的每一个将在下面更详细地说明。成功时，您将收到对该阵列的新引用。失败时，NULL将返回并设置异常。

对象

该对象可以是可转换为ndarray的任何Python对象。如果对象已经是满足要求的ndarray（的子类），则返回新的引用。否则，将构造一个新的数组。 除非使用数组接口，否则obj的内容将被复制到新数组中，从而不必复制数据。可以转换为数组的对象包括：1）任何嵌套序列对象，2）任何暴露数组接口的对象，3）任何带有__array__方法的对象（应返回ndarray），以及4）任何标量对象（成为a）零维数组）。否则将通过ndarray的子​​类满足要求。如果要确保基类ndarray，请使用NPY_ARRAY_ENSUREARRAY在需求标记中。仅在必要时进行复制。如果要保证副本，请传递NPY_ARRAY_ENSURECOPY 到需求标记。

Typenum

枚举类型之一，或者NPY_NOTYPE是否应从对象本身确定数据类型。可以使用基于C的名称：

NPY_BOOL，NPY_BYTE，NPY_UBYTE， NPY_SHORT，NPY_USHORT，NPY_INT， NPY_UINT，NPY_LONG，NPY_ULONG， NPY_LONGLONG，NPY_ULONGLONG，NPY_DOUBLE， NPY_LONGDOUBLE，NPY_CFLOAT，NPY_CDOUBLE， NPY_CLONGDOUBLE，NPY_OBJECT。

或者，可以使用平台上支持的位宽名称。例如：

NPY_INT8，NPY_INT16，NPY_INT32， NPY_INT64，NPY_UINT8， NPY_UINT16，NPY_UINT32， NPY_UINT64，NPY_FLOAT32， NPY_FLOAT64，NPY_COMPLEX64， NPY_COMPLEX128。

仅在不损失精度的情况下，对象才会转换为所需的类型。否则NULL将返回并引发错误。使用NPY_ARRAY_FORCECAST在要求标志覆盖此行为。

要求

ndarray的内存模型允许在每个维度上任意步长前进到数组的下一个元素。但是，通常，您需要与需要C连续或Fortran连续内存布局的代码交互。此外，ndarray可能未对齐（元素的地址不是该元素的大小的整数倍），如果您尝试取消对指针的引用，可能会导致程序崩溃（或至少运行得更慢）。数组数据。通过将Python对象转换成对您的特定用法更“规范”的数组，可以解决这两个问题。

需求标志允许指定可接受的数组类型。如果传入的对象不满足此要求，则进行复制，以使返回的对象满足要求。这些ndarray可以使用非常通用的内存指针。该标志允许指定返回数组对象的所需属性。在详细的API章节中说明了所有标志。最常用的标志是NPY_ARRAY_IN_ARRAY， NPY_OUT_ARRAY和NPY_ARRAY_INOUT_ARRAY：

NPY_ARRAY_IN_ARRAY

该标志对于必须为C连续顺序并对齐的数组很有用。这些数组通常是某些算法的输入数组。

NPY_ARRAY_OUT_ARRAY

此标志对于指定C连续顺序，已对齐并且也可以写入的数组很有用。这样的数组通常作为输出返回（尽管通常这样的输出数组是从头开始创建的）。

NPY_ARRAY_INOUT_ARRAY

该标志对于指定将用于输入和输出的数组很有用。PyArray_ResolveWritebackIfCopy 必须Py_DECREF在接口例程末尾之前调用，以将临时数据写回到传入的原始数组中。使用NPY_ARRAY_WRITEBACKIFCOPY或 NPY_ARRAY_UPDATEIFCOPY标志要求输入对象已经是一个数组（因为其他对象无法以这种方式自动更新） 。如果发生错误，请PyArray_DiscardWritebackIfCopy在设置了这些标志的数组上使用（obj）。这将使基础基本数组设置为可写，而不会导致将内容复制回原始数组。

可以根据其他要求进行“或”运算的其他有用标志包括：

NPY_ARRAY_FORCECAST

强制转换为所需的类型，即使不丢失信息也无法完成。

NPY_ARRAY_ENSURECOPY

确保结果数组是原始数组的副本。

NPY_ARRAY_ENSUREARRAY

确保结果对象是实际的ndarray而不是子类。

创建一个全新的ndarray ¶

通常，必须从扩展模块代码中创建新数组。也许需要一个输出数组，而您不希望调用者必须提供它。也许只需要一个临时数组即可进行中间计算。无论需要什么，都有简单的方法来获取需要的任何数据类型的ndarray对象。最通用的功能是PyArray_NewFromDescr。所有数组创建功能都通过此大量重复使用的代码进行。由于其灵活性，使用起来可能有些混乱。结果，存在更易于使用的更简单形式。这些形式是PyArray_SimpleNew功能家族的一部分 ，它们通过提供常见用例的默认值来简化界面。

到达ndarray内存并访问ndarray的元素¶

如果obj是一个ndarray（），则ndarray 的数据区域由void *指针（obj）或char *指针（obj）指向。请记住，（通常）此数据区域可能未根据数据类型对齐，可能表示字节交换数据，并且/或者可能不可写。如果数据区域是对齐的并且是本机字节顺序，则如何获取数组的特定元素仅由npy_intp变量（obj）的数组确定。特别是，此整数c数组显示必须将多少个字节添加到当前元素指针才能到达每个维度中的下一个元素。对于小于4维的数组，有PyArrayObject *PyArray_DATAPyArray_BYTESPyArray_STRIDESPyArray_GETPTR{k} （obj，…）宏，其中{k}是整数1、2、3或4，这使得使用数组的步幅更容易。争论...。表示数组中的{k}个非负整数索引。例如，假设E是3维ndarray。指向元素的（void *）指针E[i,j,k] 作为PyArray_GETPTR3（E，i，j，k）获得。

如前所述，C样式的连续数组和Fortran样式的连续数组具有特定的跨步模式。两个数组标志（NPY_ARRAY_C_CONTIGUOUS和NPY_ARRAY_F_CONTIGUOUS）指示特定数组的跨步模式是否与C风格的连续或Fortran风格的连续匹配或两者都不匹配。跨步模式是否与标准C或Fortran匹配，可以使用PyArray_IS_C_CONTIGUOUS（obj）和 PyArray_ISFORTRAN（obj）。大多数第三方库都希望使用连续数组。但是，通常不难支持通用跨步。我鼓励您尽可能在您自己的代码中使用跨步信息，并保留用于包装第三方代码的单段需求。使用ndarray提供的跨步信息，而不是要求连续跨步，可以减少原本必须进行的复制。