Как написать модуль на c для python

Оригинал статьи: Building a Python C Extension Module

Есть несколько способов расширить функциональность Python. Одним из них является написание собственного модуля на C или C++. Этот процесс может привести к повышению производительности и улучшению доступа к функциям библиотеки C и системным вызовам. В этом руководстве вы узнаете, как использовать API Python для написания модулей расширения Python C.

Вы узнаете, как:

• Вызывать функции C из Python.
• Передавать аргументы из Python в C и анализировать их.
• Вызывать исключения из кода C и создавать собственные исключения Python в C.
• Определять глобальные константы в C и делать их доступными в Python.

Расширение вашей программы Python

Есть много языков, из которых вы можете выбрать для расширения функциональности Python. Итак, почему вы должны использовать C? Вот несколько причин, почему вы можете решить создать модуль расширения на C:

1. Для реализации новых встроенных типов объектов: можно написать класс Python на C, а затем создать и расширить этот класс из самого Python. Для этого может быть много причин, но чаще всего именно производительность побуждает разработчиков обращаться к C. Такая ситуация встречается редко, но хорошо знать, в какой степени Python может быть расширен.

2. Для вызова функций библиотеки C и системных вызовов: Многие языки программирования предоставляют интерфейсы для наиболее часто используемых системных вызовов. Тем не менее, могут быть другие менее используемые системные вызовы, которые доступны только через C. Модуль os в Python является одним из примеров.

Это не исчерпывающий список, но он дает вам представление о том, что можно сделать при расширении Python с использованием C или любого другого языка.

Чтобы писать модули Python на C, вам нужно использовать API Python, который определяет различные функции, макросы и переменные, которые позволяют интерпретатору Python вызывать ваш код на C. Все эти и другие инструменты собраны в заголовочном файле Python.h.

Написание интерфейса Python на C

В этом руководстве вы напишете небольшую оболочку для функции библиотеки C, которую затем будете вызывать из Python. Реализация оболочки самостоятельно даст вам лучшее представление о том, когда и как использовать C для расширения вашего модуля Python.

Понимание fputs()

fputs() — это функция библиотеки C, которую вы будете оборачивать:

int fputs(const char *, FILE *)

Эта функция принимает два аргумента:

• const char * — это массив символов.
• FILE * — указатель на файловый поток.

fputs() записывает массив символов в файл, указанный потоком файлов, и возвращает неотрицательное значение. Если операция прошла успешно, то это значение будет обозначать количество байтов, записанных в файл. Если произошла ошибка, возвращается EOF. Вы можете прочитать больше об этой функции библиотеки C и ее других вариантах в разделе руководства.

Написание функции C для fputs()

Это базовая программа на C, которая использует fputs() для записи строки в файловый поток:

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

int main() {
    FILE *fp = fopen("write.txt", "w");
    fputs("Real Python!", fp);
    fclose(fp);
    return 1;
}

Этот фрагмент кода можно обобщить следующим образом:

1. Откройте файл write.txt.
2. Запишите строку Real Python! в файл.

В следующем разделе вы напишите обертку для этой функции C.

Может показаться немного странным увидеть полный код перед объяснением того, как он работает. Однако если вы потратите немного времени на проверку конечного продукта, вы поймете это в следующих разделах. Блок кода ниже показывает окончательную упакованную версию вашего кода C:

#include <Python.h>

static PyObject *method_fputs(PyObject *self, PyObject *args) {
    char *str, *filename = NULL;
    int bytes_copied = -1;

    /* Parse arguments */
    if(!PyArg_ParseTuple(args, "ss", &str, &filename)) 
        return NULL;
    
    FILE *fp = fopen(filename, "w");
    bytes_copied = fputs(str, fp);
    fclose(fp);

    return PyLong_FromLong(bytes_copied);
}

Этот фрагмент кода ссылается на три объектные структуры, которые определены в Python.h:

1. PyObject
2. PyArg_ParseTuple()
3. PyLong_FromLong()

Они используются для определения типа данных для языка Python.

PyObject

PyObject — это структура объектов, которую вы используете для определения типов объектов для Python. Все объекты Python имеют небольшое количество полей, определенных с помощью структуры PyObject. Все остальные типы объектов являются расширениями этого типа.

PyObject говорит интерпретатору Python обрабатывать указатель на объект как объект. Например, установка типа возврата вышеуказанной функции как PyObject определяет общие поля, которые требуются интерпретатору Python для распознавания его как допустимого типа Python.

Взгляните еще раз на первые несколько строк вашего C-кода:

static PyObject *method_fputs(PyObject *self, PyObject *args) {
    char *str, *filename = NULL;
    int bytes_copied = -1;

    /* Snip */

В строке 2 вы объявляете типы аргументов, которые хотите получить из кода Python:

1. char * str — это строка, которую вы хотите записать в файловый поток.
2. char * filename — это имя файла для записи.

PyArg_ParseTuple()

PyArg_ParseTuple() анализирует аргументы, которые вы получите от вашей программы Python, в локальные переменные:

static PyObject *method_fputs(PyObject *self, PyObject *args) {
    char *str, *filename = NULL;
    int bytes_copied = -1;

    /* Parse arguments */
    if(!PyArg_ParseTuple(args, "ss", &str, &filename)) 
        return NULL;
    
    /* Snip */

Если вы посмотрите на строку 6, то увидите, что PyArg_ParseTuple() принимает следующие аргументы:

• args имеют тип PyObject.

• "ss" — это спецификатор формата, который определяет тип данных аргументов для анализа. (Вы можете проверить официальную документацию для полной справки.)

• &str и &filename являются указателями на локальные переменные, которым будут назначены проанализированные значения.

PyArg_ParseTuple() оценивается как ложное в случае ошибки. Если произойдет сбой, функция вернет NULL и больше не будет работать.

fputs()

Как вы видели ранее, fputs() принимает два аргумента, один из которых — объект FILE *. Поскольку вы не можете анализировать объект Python textIOwrapper с помощью Python API в C, вам придется использовать обходной путь:

static PyObject *method_fputs(PyObject *self, PyObject *args) {
    char *str, *filename = NULL;
    int bytes_copied = -1;

    /* Parse arguments */
    if(!PyArg_ParseTuple(args, "ss", &str, &filename)) 
        return NULL;
    
    FILE *fp = fopen(filename, "w");
    bytes_copied = fputs(str, fp);
    fclose(fp);

    return PyLong_FromLong(bytes_copied);
}

Вот разбор того, что делает этот код:

• В строке 10 вы передаете имя файла, который будете использовать для создания объекта FILE * и передачи его функции.
• В строке 11 вы вызываете fputs() со следующими аргументами:
  — str — строка, которую вы хотите записать в файл.
  — fp — это объект FILE *, который вы определили в строке 10.

Затем вы сохраняете возвращаемое значение fputs() в bytes_copied. Эта целочисленная переменная будет возвращена вызову fputs() в интерпретаторе Python.

PyLong_FromLong (bytes_copied)

PyLong_FromLong() возвращает PyLongObject, который представляет целочисленный объект в Python. Вы можете найти его в самом конце вашего C-кода:

static PyObject *method_fputs(PyObject *self, PyObject *args) {
    char *str, *filename = NULL;
    int bytes_copied = -1;

    /* Parse arguments */
    if(!PyArg_ParseTuple(args, "ss", &str, &filename)) 
        return NULL;
    
    FILE *fp = fopen(filename, "w");
    bytes_copied = fputs(str, fp);
    fclose(fp);

    return PyLong_FromLong(bytes_copied);
}

Строка 14 генерирует PyLongObject для bytes_copied, переменная, которая возвращается, когда функция вызывается в Python. Вы должны вернуть PyObject * из вашего модуля расширения Python C обратно в интерпретатор Python.

Написание функции инициализации

Вы написали код, который составляет основную функциональность вашего модуля расширения Python. Тем не менее, есть еще несколько дополнительных функций, которые необходимы для запуска вашего модуля. Вам нужно будет написать определения вашего модуля и методов, которые он содержит, например:

static PyMethodDef FputsMethods[] = {
    {"fputs", method_fputs, METH_VARARGS, "Python interface for fputs C library function"},
    {NULL, NULL, 0, NULL}
};

static struct PyModuleDef fputsmodule = {
    PyModuleDef_HEAD_INIT,
    "fputs",
    "Python interface for the fputs C library function",
    -1,
    FputsMethods
};

Эти функции включают метаинформацию о вашем модуле, которая будет использоваться интерпретатором Python. Давайте рассмотрим каждую из вышеперечисленных структур, чтобы увидеть, как они работают.

PyMethodDef

Чтобы вызвать методы, определенные в вашем модуле, вам нужно сначала сообщить о них интерпретатору Python. Для этого вы можете использовать PyMethodDef. Это структура с 4 членами, представляющими один метод в вашем модуле.

В идеале в вашем модуле расширения Python C должно быть несколько методов, которые вы хотите вызывать из интерпретатора Python. Вот почему вам нужно определить массив структур PyMethodDef:

static PyMethodDef FputsMethods[] = {
    {"fputs", method_fputs, METH_VARARGS, "Python interface for fputs C library function"},
    {NULL, NULL, 0, NULL}
};

Каждый отдельный член структуры содержит следующую информацию:

• "fputs" — это имя, которое напишет пользователь для вызова функции из кода на Python.

• method_fputs — это имя C функции для вызова.

• METH_VARARGS — это флаг, который сообщает интерпретатору, что функция будет принимать два аргумента типа PyObject *:

1. self — это объект модуля.
2. args — это кортеж, содержащий фактические аргументы вашей функции. Как объяснялось ранее, эти аргументы распаковываются с использованием PyArg_ParseTuple().

• Последняя строка представляет собой значение, представляющее метод docstring.

PyModuleDef

Так же, как PyMethodDef содержит информацию о методах в вашем модуле расширения Python, структура PyModuleDef содержит информацию о самом модуле. Это не массив структур, а единственная структура, которая используется для определения модуля:

static struct PyModuleDef fputsmodule = {
    PyModuleDef_HEAD_INIT,
    "fputs",
    "Python interface for the fputs C library function",
    -1,
    FputsMethods
};

Всего в этой структуре 9 членов, но не все они обязательны. В приведенном выше блоке кода вы инициализируете следующие пять:

1. PyModuleDef_HEAD_INIT является членом типа PyModuleDef_Base, который рекомендуется иметь только это одно значение.

2. "fputs" — это название вашего модуля расширения Python C.

3. Строка — это значение, представляющее строку документации вашего модуля. Вы можете использовать NULL, чтобы не иметь строки документации, или вы можете указать строку документации, передав const char *, как показано во фрагменте выше. Он имеет тип Py_ssize_t. Вы также можете использовать PyDoc_STRVAR(), чтобы определить строку документации для вашего модуля.

4. -1 — объем памяти, необходимый для хранения состояния вашей программы. Это полезно, когда ваш модуль используется в нескольких суб-интерпретаторах, и может иметь следующие значения:

— Отрицательное значение указывает, что этот модуль не поддерживает суб-переводчиков.
— Неотрицательное значение позволяет повторно инициализировать ваш модуль. Он также определяет требования к памяти вашего модуля, которые должны быть выделены на каждом сеансе суб-интерпретатора.

1. FputsMethods — это ссылка на таблицу методов. Это массив структур PyMethodDef, которые вы определили ранее.

Для получения дополнительной информации ознакомьтесь с официальной документацией Python по PyModuleDef (документация).

PyMODINIT_FUNC

Теперь, когда вы определили свой модуль расширения Python и структуры методов, пришло время использовать их. Когда программа Python импортирует ваш модуль в первый раз, она вызовет PyInit_fputs():

PyMODINIT_FUNC PyInit_fputs(void) {
    return PyModule_Create(&fputsmodule);
}

PyMODINIT_FUNC неявно делает 3 вещи, если указано как возвращаемый функцией тип:

1. Он неявно устанавливает тип возвращаемого значения функции как PyObject *.
2. Он объявляет любые специальные связи.
3. Он объявляет функцию как extern «C.» В случае, если вы используете C++, он говорит компилятору C++ не выполнять манипулирование именами на символах.

PyModule_Create() вернет новый объект модуля типа PyObject *. В качестве аргумента вы передадите адрес структуры метода, который вы уже определили ранее, fputsmodule.

Собираем все вместе

Теперь, когда вы написали необходимые части вашего модуля расширения Python, давайте сделаем шаг назад, чтобы увидеть, как все это сочетается. На следующей диаграмме показаны компоненты вашего модуля и их взаимодействие с интерпретатором Python:

Когда вы импортируете свой модуль расширения Python, PyInit_fputs() является первым методом, который будет вызван. Однако перед тем, как ссылка возвращается интерпретатору Python, функция выполняет последующий вызов PyModule_Create(). Это инициализирует структуры PyModuleDef и PyMethodDef, которые содержат метаинформацию о вашем модуле. Имеет смысл подготовить их, так как вы будете использовать их в своей функции инициализации.

Как только это завершится, ссылка на объект модуля наконец возвращается интерпретатору Python. Следующая диаграмма показывает внутренний поток вашего модуля:

Объект модуля, возвращаемый PyModule_Create(), имеет ссылку на структуру модуля PyModuleDef, которая, в свою очередь, имеет ссылку на таблицу методов PyMethodDef. Когда вы вызываете метод, определенный в вашем модуле расширения Python, интерпретатор Python использует объект модуля и все ссылки, которые он несет, для выполнения определенного метода. (Хотя это не совсем то, как интерпретатор Python обрабатывает вещи под капотом, он даст вам представление о том, как это работает.)

Точно так же вы можете получить доступ к различным другим методам и свойствам вашего модуля, таким как docstring модуля или docstring метода. Они определены внутри их соответствующих структур.

Теперь у вас есть представление о том, что происходит, когда вы вызываете fputs() из интерпретатора Python. Интерпретатор использует объект вашего модуля, а также ссылки на модуль и метод для вызова метода. Наконец, давайте посмотрим, как интерпретатор обрабатывает фактическое выполнение вашего модуля расширения Python C:

После вызова метода method_fputs() программа выполняет следующие шаги:

1. Разобрать аргументы, которые вы передали от интерпретатора Python, с помощью PyArg_ParseTuple()
2. Передайте эти аргументы в fputs(), библиотечную функцию C, которая формирует суть вашего модуля
3. Используйте PyLong_FromLong, чтобы вернуть значение из fputs()

Чтобы увидеть эти же шаги в коде, еще раз взгляните на method_fputs():

static PyObject *method_fputs(PyObject *self, PyObject *args) {
    char *str, *filename = NULL;
    int bytes_copied = -1;

    /* Parse arguments */
    if(!PyArg_ParseTuple(args, "ss", &str, &filename)) 
        return NULL;
    
    FILE *fp = fopen(filename, "w");
    bytes_copied = fputs(str, fp);
    fclose(fp);

    return PyLong_FromLong(bytes_copied);
}

Напомним, что ваш метод проанализирует аргументы, переданные вашему модулю, отправит их в fputs() и вернет результаты.

Упаковка вашего модуля расширения Python C

Прежде чем вы сможете импортировать новый модуль, вам сначала нужно его собрать. Вы можете сделать это, используя пакет дистрибутивов Python.

Для установки приложения вам понадобится файл с именем setup.py. В этом руководстве вы сосредоточитесь на части, специфичной для модуля расширения Python C. Чтобы ознакомиться с полным учебником, ознакомьтесь с публикацией пакета Python с открытым исходным кодом в PyPI.

Минимальный файл setup.py для вашего модуля должен выглядеть так:

from distutils.core import setup, Extension

def main():
    setup(name="fputs",
          version="1.0.0",
          description="Python interface for the fputs C library function",
          author="<your name>",
          author_email="your_email@gmail.com",
          ext_modules=[Extension("fputs", ["fputsmodule.c"])])

if __name__ == "__main__":
    main()

Блок кода выше показывает стандартные аргументы, которые передаются в setup(). Присмотритесь к последнему позиционному аргументу ext_modules. Это берет список объектов класса Extensions. Объект класса Extensions описывает отдельный модуль расширения C или C++ в сценарии установки. Здесь вы передаете два аргумента ключевого слова в его конструктор, а именно:

• name это имя модуля.
• [filename] представляет собой список путей к файлам с исходным кодом относительно сценария установки.

Сборка вашего модуля

Теперь, когда у вас есть файл setup.py, вы можете использовать его для сборки модуля расширения Python C. Настоятельно рекомендуется использовать виртуальную среду, чтобы избежать конфликтов с вашей средой Python.

Перейдите в каталог, содержащий setup.py и выполните следующую команду:

$ python3 setup.py install

Эта команда скомпилирует и установит ваш модуль расширения Python в текущем каталоге. Если есть какие-либо ошибки или предупреждения, то ваша программа их сейчас выбросит. Убедитесь, что вы исправили их, прежде чем пытаться импортировать свой модуль.

По умолчанию интерпретатор Python использует clang для компиляции кода на C. Если вы хотите использовать gcc или любой другой компилятор C для этой работы, то вам необходимо соответствующим образом установить переменную среды CC, либо внутри сценария установки, либо непосредственно в командной строке. Например, вы можете указать интерпретатору Python использовать gcc для компиляции и сборки вашего модуля следующим образом:

$ CC=gcc python3 setup.py install

Однако интерпретатор Python автоматически вернется к gcc, если clang недоступен.

Запуск вашего модуля

Теперь, когда все готово, пришло время увидеть ваш модуль в действии! Как только он будет успешно собран, запустите интерпретатор, чтобы протестировать запуск модуля:

>>> import fputs
>>> fputs.__doc__
'Python interface for the fputs C library function'
>>> fputs.__name__
'fputs'
>>> # Write to an empty file named `write.txt`
>>> fputs.fputs("Real Python!", "write.txt")
13
>>> with open("write.txt", "r") as f:
>>>     print(f.read())
'Real Python!'

Ваша функция работает как ожидалось! Вы передаете строку "Real Python!" и файл для записи этой строки, write.txt. Вызов fputs() возвращает количество байтов, записанных в файл. Вы можете убедиться в этом, распечатав содержимое файла.

Также вспомните, как вы передавали определенные аргументы в структуры PyModuleDef и PyMethodDef. Из этого вывода видно, что Python использовал эти структуры для назначения таких вещей, как имя функции и строка документации.

Теперь у вас есть готовая базовая версия модуля, но вы можете сделать гораздо больше! Вы можете улучшить свой модуль, добавив такие вещи, как пользовательские исключения и константы.

Возбуждение исключений

Исключения Python сильно отличаются от исключений C++. Если вы хотите вызвать исключения Python из вашего модуля расширения C, то можете использовать Python API для этого. Вот некоторые функции, предоставляемые Python API для вызова исключений:

PyErr_SetString(PyObject *type, const char *message)

Принимает два аргумента: аргумент типа PyObject *, указывающий тип исключения, и настраиваемое сообщение для отображения пользователю.

PyErr_Format(PyObject *type, const char *format)

Принимает два аргумента: аргумент типа PyObject *, указывающий тип исключения, и отформатированное настраиваемое сообщение для отображения пользователю

PyErr_SetObject(PyObject *type, PyObject *value)

Принимает два аргумента, оба типа PyObject *: первый указывает тип исключения, а второй устанавливает произвольный объект Python в качестве значения исключения

Вы можете использовать любой из них, чтобы вызвать исключение. Однако, что использовать и когда зависит полностью от ваших требований. В Python API есть все стандартные исключения, предварительно определенные как типы PyObject.

Возникновение исключений из кода C

Хотя вы не можете вызывать исключения в C, Python API позволит вам вызывать исключения из вашего модуля расширения Python C. Давайте проверим эту функциональность, добавив PyErr_SetString() в ваш код. Это вызовет исключение, если длина записываемой строки меньше 10 символов:

static PyObject *method_fputs(PyObject *self, PyObject *args) {
    char *str, *filename = NULL;
    int bytes_copied = -1;

    /* Parse arguments */
    if(!PyArg_ParseTuple(args, "ss", &str, &fd)) 
        return NULL;
    
    if (strlen(str) < 10) {
        PyErr_SetString(PyExc_ValueError, "String length must be greater than 10");
        return NULL;
    }

    fp = fopen(filename, "w");
    bytes_copied = fputs(str, fp);
    fclose(fp);

    return PyLong_FromLong(bytes_copied);
}

Здесь вы проверяете длину входной строки сразу после разбора аргументов и перед вызовом fputs(). Если строка, переданная пользователем, короче 10 символов, то ваша программа вызовет ошибку ValueError с пользовательским сообщением. Выполнение программы прекращается, как только возникает исключение.

Обратите внимание, как method_fputs() возвращает NULL после вызова исключения. Это связано с тем, что всякий раз, когда вы вызываете исключение с помощью PyErr_*(), он автоматически устанавливает внутреннюю запись в таблице исключений и возвращает ее. Вызывающая функция не обязана впоследствии устанавливать запись снова. По этой причине вызывающая функция возвращает значение, которое указывает на ошибку, обычно NULL или -1. (Это также должно объяснить, почему возникла необходимость возвращать NULL при разборе аргументов в method_fputs() с использованием PyArg_ParseTuple().)

Возбуждение пользовательских исключений

Вы также можете вызывать пользовательские исключения в вашем модуле расширения Python. Однако все немного по-другому. Ранее в PyMODINIT_FUNC вы просто возвращали экземпляр, возвращенный PyModule_Create, и вызывали его в течение дня. Но чтобы пользовательское исключение было доступно пользователю вашего модуля, вам нужно добавить свое пользовательское исключение в экземпляр вашего модуля, прежде чем вы его вернете:

static PyObject *StringTooShortError = NULL;

PyMODINIT_FUNC PyInit_fputs(void) {
    /* Assign module value */
    PyObject *module = PyModule_Create(&fputsmodule);

    /* Initialize new exception object */
    StringTooShortError = PyErr_NewException("fputs.StringTooShortError", NULL, NULL);

    /* Add exception object to your module */
    PyModule_AddObject(module, "StringTooShortError", StringTooShortError);

    return module;
}

Как и прежде, вы начинаете с создания объекта модуля. Затем вы создаете новый объект исключения, используя PyErr_NewException. Это принимает строку вида module.classname как имя класса исключения, который вы хотите создать. Выберите что-то описательное, чтобы пользователю было легче интерпретировать то, что на самом деле пошло не так.

Затем вы добавляете это к своему объекту модуля, используя PyModule_AddObject. Он принимает объект вашего модуля, имя добавляемого нового объекта и сам объект пользовательского исключения в качестве аргументов. Наконец, вы возвращаете объект вашего модуля.

Теперь, когда вы определили настраиваемое исключение для вашего модуля, вам нужно обновить method_fputs(), чтобы оно вызывало соответствующее исключение:

static PyObject *method_fputs(PyObject *self, PyObject *args) {
    char *str, *filename = NULL;
    int bytes_copied = -1;

    /* Parse arguments */
    if(!PyArg_ParseTuple(args, "ss", &str, &fd)) 
        return NULL;
    
    if (strlen(str) < 10) {
        /* Passing custom exception */
        PyErr_SetString(StringTooShortError, "String length must be greater than 10");
        return NULL;
    }

    fp = fopen(filename, "w");
    bytes_copied = fputs(str, fp);
    fclose(fp);

    return PyLong_FromLong(bytes_copied);
}

После создания модуля с новыми изменениями вы можете проверить, что ваше пользовательское исключение работает должным образом, попытавшись написать строку длиной менее 10 символов:

>>> import fputs
>>> # Custom exception
>>> fputs.fputs("RP!", fp.fileno())
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
fputs.StringTooShortError: String length must be greater than 10

Когда вы пытаетесь написать строку длиной менее 10 символов, ваше пользовательское исключение вызывается сообщением, объясняющим, что пошло не так.

Определение констант

В некоторых случаях вы захотите использовать или определить константы в модуле расширения Python. Это очень похоже на то, как вы определили пользовательские исключения в предыдущем разделе. Вы можете определить новую константу и добавить ее в свой экземпляр модуля, используя PyModule_AddIntConstant():

PyMODINIT_FUNC PyInit_fputs(void) {
    /* Assign module value */
    PyObject *module = PyModule_Create(&fputsmodule);

    /* Add int constant by name */
    PyModule_AddIntConstant(module, "FPUTS_FLAG", 64);

    /* Define int macro */
    #define FPUTS_MACRO 256

    /* Add macro to module */
    PyModule_AddIntMacro(module, FPUTS_MACRO);

    return module;
}

Эта функция Python API принимает следующие аргументы:

• Экземпляр вашего модуля.
• Наименование константы.
• Значение константы.

Вы можете сделать то же самое для макросов, используя PyModule_AddIntMacro():

PyMODINIT_FUNC PyInit_fputs(void) {
    /* Assign module value */
    PyObject *module = PyModule_Create(&fputsmodule);

    /* Add int constant by name */
    PyModule_AddIntConstant(module, "FPUTS_FLAG", 64);

    /* Define int macro */
    #define FPUTS_MACRO 256

    /* Add macro to module */
    PyModule_AddIntMacro(module, FPUTS_MACRO);

    return module;
}

Эта функция принимает следующие аргументы:

• Экземпляр вашего модуля.
• Имя макроса, который уже был определен.

Примечание. Если вы хотите добавить строковые константы или макросы в свой модуль, вы можете использовать PyModule_AddStringConstant() и PyModule_AddStringMacro() соответственно.

Откройте интерпретатор Python и посмотрите, работают ли ваши константы и макросы так, как ожидается:

>>> import fputs
>>> # Constants
>>> fputs.FPUTS_FLAG
64
>>> fputs.FPUTS_MACRO
256

Здесь вы можете видеть, что константы доступны из интерпретатора Python.

Тестирование вашего модуля

Вы можете протестировать свой модуль расширения Python так же, как и любой другой модуль Python. Это можно продемонстрировать, написав небольшую тестовую функцию для pytest:

import fputs

def test_copy_data():
    content_to_copy = "Real Python!"
    bytes_copied = fputs.fputs(content_to_copy, 'test_write.txt')

    with open('test_write.txt', 'r') as f:
        content_copied = f.read()

    assert content_copied == content_to_copy

В приведенном выше тестовом сценарии вы используете fputs.fputs(), чтобы записать строку «Real Python!» в пустой файл с именем test_write.txt. Затем вы читаете содержимое этого файла и используете утверждение assert, чтобы сравнить его с тем, что вы изначально написали.

Вы можете запустить этот набор тестов, чтобы убедиться, что ваш модуль работает должным образом:

$ pytest -q
test_fputs.py                                                 [100%]
1 passed in 0.03 seconds

Для более подробного ознакомления ознакомьтесь с разделом Начало работы с тестированием в Python.

Литература для дополнительного чтения:

• Менеджер памяти
• Pandas
• Реализация словаря
• Реализация целого типа в CPython
• Реализация строкового типа в CPython