Содержание страницы

Руководство по Argument Clinic¶Argument Clinic How-To

автор: Larry Hastings

Аннотация

Argument Clinic – это препроцессор для C-файлов CPython. Его цель – автоматизировать всю шаблонную работу, связанную с написанием кода разбора аргументов для «встроенных функций». Этот документ показывает, как преобразовать первую C-функцию для работы с Argument Clinic, а затем знакомит с некоторыми продвинутыми темами по использованию Argument Clinic.

В настоящее время Argument Clinic считается внутренним инструментом только для CPython. Его использование не поддерживается для файлов вне CPython, и никаких гарантий обратной совместимости в будущих версиях не даётся. Иными словами: если вы поддерживаете внешнее C-расширение для CPython, вы можете экспериментировать с Argument Clinic в своём коде. Но версия Argument Clinic, которая поставляется со следующей версией CPython, может оказаться полностью несовместимой и сломать весь ваш код.

Цели Argument Clinic¶The Goals Of Argument Clinic

Основная цель Argument Clinic – взять на себя ответственность за весь код разбора аргументов внутри CPython. Это означает, что при преобразовании функции для работы с Argument Clinic эта функция больше не должна выполнять собственный разбор аргументов – сгенерированный Argument Clinic код должен быть для вас «чёрным ящиком», где CPython вызывает его сверху, а ваш код вызывается снизу, а PyObject *args (и, возможно, PyObject *kwargs) магически преобразуются в нужные вам C-переменные и типы.

Чтобы Argument Clinic достиг своей основной цели, он должен быть прост в использовании. Сейчас работа с библиотекой разбора аргументов CPython – это рутина, требующая поддержания избыточной информации в удивительно большом количестве мест. При использовании Argument Clinic вам не нужно повторяться.

Очевидно, никто не захочет использовать Argument Clinic, если он не решает их проблему – и при этом не создаёт новых. Поэтому крайне важно, чтобы Argument Clinic генерировал корректный код. Было бы хорошо, если бы код был ещё и быстрее, но, по крайней мере, он не должен приводить к серьёзному снижению производительности. (В конечном итоге Argument Clinic должен сделать возможным значительное ускорение – мы могли бы переписать его генератор кода для создания специализированного кода разбора аргументов вместо вызова универсальной библиотеки разбора аргументов CPython. Это позволило бы добиться максимально быстрого разбора аргументов!)

Кроме того, Argument Clinic должен быть достаточно гибким, чтобы работать с любым подходом к разбору аргументов. В Python есть функции с очень странным поведением при разборе; цель Argument Clinic – поддерживать все из них.

Наконец, изначальной мотивацией для Argument Clinic было предоставление «сигнатур» для интроспекции встроенных функций CPython. Раньше функции запросов интроспекции выбрасывали исключение, если передать встроенную функцию. С Argument Clinic это осталось в прошлом!

Одна идея, которую стоит помнить при работе с Argument Clinic: чем больше информации вы ему дадите, тем лучше он сможет выполнить свою работу. Argument Clinic, безусловно, сейчас относительно прост. Но по мере развития он будет становиться всё более сложным и сможет делать много интересных и умных вещей со всей предоставленной информацией.

Основные концепции и использование¶Basic Concepts And Usage

Argument Clinic поставляется с CPython; вы найдёте его в Tools/clinic/clinic.py. Если запустить этот скрипт, указав C-файл в качестве аргумента:

$ python3 Tools/clinic/clinic.py foo.c

Argument Clinic будет сканировать файл в поисках строк, которые выглядят точно так же:

/*[clinic input]

Когда он находит такую строку, он читает всё до строки, которая выглядит точно так же:

[clinic start generated code]*/

Всё, что находится между этими двумя строками, является входными данными для Argument Clinic. Все эти строки, включая начальную и конечную строки комментариев, вместе называются «блоком» Argument Clinic.

Когда Argument Clinic анализирует один из таких блоков, он генерирует выходные данные. Эти выходные данные перезаписываются в C-файл сразу после блока, за которыми следует комментарий с контрольной суммой. Блок Argument Clinic теперь выглядит так:

/*[clinic input]
... clinic input goes here ...
[clinic start generated code]*/
... clinic output goes here ...
/*[clinic end generated code: checksum=...]*/

Если запустить Argument Clinic на том же файле повторно, он отбросит старые выходные данные и запишет новые с новой строкой контрольной суммы. Однако если входные данные не изменились, выходные данные тоже не изменятся.

Никогда не следует изменять выходную часть блока Argument Clinic. Вместо этого меняйте входные данные, пока они не начнут давать нужный вам вывод. (В этом и заключается назначение контрольной суммы – обнаруживать, если кто-то изменил выходные данные, поскольку эти правки будут потеряны при следующей записи новых выходных данных Argument Clinic.)

Для ясности приведём терминологию, которую мы будем использовать с Argument Clinic:

Первая строка комментария (/*[clinic input]) – это начальная строка.
Последняя строка исходного комментария ([clinic start generated code]*/) – это конечная строка.
Последняя строка (/*[clinic end generated code: checksum=...]*/) – это строка контрольной суммы.
Между начальной строкой и конечной строкой находится входные данные.
Между конечной строкой и строкой контрольной суммы находится выходные данные.
Весь текст в совокупности, от начальной строки до строки контрольной суммы включительно, является блоком. (Блок, который ещё не был успешно обработан Argument Clinic, не имеет выходных данных или строки контрольной суммы, но всё равно считается блоком.)

Преобразование вашей первой функции¶Converting Your First Function

Лучший способ понять, как работает Argument Clinic, – преобразовать функцию для работы с ним. Итак, ниже приведены минимальные шаги, которые необходимо выполнить для преобразования функции для работы с Argument Clinic. Обратите внимание, что для кода, который вы планируете включить в CPython, стоит пойти дальше, используя некоторые продвинутые концепции, которые вы увидите далее в документе (например, «конвертеры возврата» и «конвертеры self»). Но в этом пошаговом руководстве мы будем придерживаться простого подхода, чтобы вы могли освоиться.

Приступим!

Убедитесь, что вы работаете со свежеобновлённой копией основной ветки CPython.
Найдите встроенную функцию Python, которая вызывает либо PyArg_ParseTuple(), либо PyArg_ParseTupleAndKeywords(), и ещё не была преобразована для работы с Argument Clinic. В своём примере я использую _pickle.Pickler.dump().
Если вызов функции PyArg_Parse использует один из следующих форматных юнитов:
```
O&
O!
es
es#
et
et#
```
или если в ней несколько вызовов PyArg_ParseTuple(), следует выбрать другую функцию. Argument Clinic поддерживает все эти сценарии. Но это продвинутые темы – для первой функции лучше сделать что-то попроще.

Кроме того, если функция содержит несколько вызовов PyArg_ParseTuple() или PyArg_ParseTupleAndKeywords() с разными типами для одного и того же аргумента, или если для разбора аргументов используются не функции PyArg_Parse, то, вероятно, она не подходит для преобразования в Argument Clinic. Argument Clinic не поддерживает обобщённые функции или полиморфные параметры.
Добавьте следующий шаблонный код над функцией, создав наш блок:
```
/*[clinic input]
[clinic start generated code]*/
```
Вырежьте строку документации и вставьте её между строками [clinic], убрав всё, что делает её правильно оформленной строкой C. Когда закончите, у вас должен остаться только текст, выровненный по левому краю, без строк длиннее 80 символов. (Argument Clinic сохранит отступы внутри строки документации.)

Если старая строка документации содержала первую строку, похожую на сигнатуру функции, удалите её. (Она больше не нужна – когда вы в будущем будете использовать help() для встроенной функции, первая строка будет сгенерирована автоматически на основе сигнатуры функции.)

Пример:
```
/*[clinic input]
Записывает представление объекта в формате pickle в открытый файл.
[clinic start generated code]*/
```
Если в строке документации нет строки «краткого описания», Argument Clinic выдаст предупреждение. Поэтому убедитесь, что она есть. Строка краткого описания должна представлять собой абзац из одной строки длиной до 80 символов в начале строки документации.

(В нашем примере строка документации состоит только из строки краткого описания, поэтому образец кода не нужно менять на этом шаге.)
Над строкой документации укажите имя функции, затем пустую строку. Это должно быть Python-имя функции, полный путь с точками – начиная с имени модуля, включая все подмодули, и если функция является методом класса, то также имя класса.

Пример:
```
/*[clinic input]
_pickle.Pickler.dump

Записывает представление объекта в формате pickle в открытый файл.
[clinic start generated code]*/
```
Если этот модуль или класс впервые используются с Argument Clinic в данном C-файле, необходимо объявить модуль и/или класс. Правила гигиены Argument Clinic рекомендуют объявлять их в отдельном блоке где-нибудь ближе к началу C-файла, так же как файлы включений и статические переменные размещаются в начале. (В нашем примере мы просто покажем два блока рядом.)

Имя класса и модуля должно совпадать с тем, которое видит Python. Проверьте имя, определённое в PyModuleDef или PyTypeObject, в зависимости от ситуации.

При объявлении класса необходимо также указать два аспекта его типа в C: объявление типа для указателя на экземпляр этого класса и указатель на PyTypeObject для этого класса.

Пример:
```
/*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/

/*[clinic input]
_pickle.Pickler.dump

Записывает представление объекта в формате pickle в открытый файл.
[clinic start generated code]*/
```
Объявите каждый параметр функции. Каждый параметр должен быть на отдельной строке. Все строки параметров должны быть с отступом относительно имени функции и строки документации.

Общий вид этих строк параметров следующий:
```
name_of_parameter: converter
```
Если у параметра есть значение по умолчанию, добавьте его после конвертера:
```
name_of_parameter: converter = default_value
```
Поддержка значений по умолчанию в Argument Clinic довольно сложная; обратитесь к разделу ниже о значениях по умолчанию для получения дополнительной информации.

Добавьте пустую строку под параметрами.

Что такое «конвертер»? Он определяет как тип переменной, используемый в C, так и метод преобразования значения Python в значение C во время выполнения. Сейчас вы будете использовать так называемый «унаследованный конвертер» – удобный синтаксис, предназначенный для упрощения переноса старого кода в Argument Clinic.

Для каждого параметра скопируйте «форматный юнит» этого параметра из аргумента формата PyArg_Parse() и укажите его в качестве конвертера, в виде строки в кавычках. («Форматный юнит» – это официальное название подстроки из одного-трёх символов параметра format, которая сообщает функции разбора аргументов тип переменной и способ её преобразования. Подробнее о форматных юнитах см. «Разбор аргументов и сборка значений».)

Для многозначных форматных юнитов, таких как z#, используйте всю строку из двух или трёх символов.

Пример:
```
 /*[clinic input]
 module _pickle
 class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
 [clinic start generated code]*/

 /*[clinic input]
 _pickle.Pickler.dump

    obj: 'O'

Записывает сериализованное представление obj в открытый файл.
[clinic start generated code]*/
```
Если в строке формата вашей функции есть |, что означает, что некоторые параметры имеют значения по умолчанию, можете игнорировать его. Argument Clinic определяет, какие параметры необязательны, на основе наличия значений по умолчанию.

Если в строке формата вашей функции есть $, что означает, что она принимает только именованные аргументы, укажите * на отдельной строке перед первым именованным аргументом, с отступом, как у строк параметров.

(У _pickle.Pickler.dump нет ни того, ни другого, поэтому наш образец не меняется.)
Если существующая C-функция вызывает PyArg_ParseTuple() (в отличие от PyArg_ParseTupleAndKeywords()), то все её аргументы являются только позиционными.

Чтобы пометить все параметры как только позиционные в Argument Clinic, добавьте / на отдельной строке после последнего параметра, с отступом, как у строк параметров.

Сейчас это работает по принципу «всё или ничего»: либо все параметры только позиционные, либо ни один. (В будущем Argument Clinic может ослабить это ограничение.)

Пример:
```
/*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/

/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
    /

Записывает сериализованное представление obj в открытый файл.
[clinic start generated code]*/
```
Полезно писать докстринг на каждый параметр. Но такие докстринги необязательны – при желании этот шаг можно пропустить.

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

Пример:
```
/*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/

/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
        Сериализуемый объект.
    /

Записывает сериализованное представление obj в открытый файл.
[clinic start generated code]*/
```
Сохраните и закройте файл, затем запустите на нём Tools/clinic/clinic.py. Если повезёт, всё сработало – теперь у вашего блока есть вывод, а также сгенерирован файл .c.h! Снова откройте файл в текстовом редакторе, чтобы увидеть:
```
/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
        Сериализуемый объект.
    /

Записывает сериализованное представление obj в открытый файл.
[clinic start generated code]*/

static PyObject *
_pickle_Pickler_dump(PicklerObject *self, PyObject *obj)
/*[clinic end generated code: output=87ecad1261e02ac7 input=552eb1c0f52260d9]*/
```
Очевидно, если Argument Clinic не выдал никакого вывода, значит, он нашёл ошибку во входных данных. Исправляйте ошибки и повторяйте запуск, пока Argument Clinic не обработает файл без нареканий.

Для удобства чтения большая часть связующего кода сгенерирована в файл .c.h. Этот файл нужно включить в исходный файл .c, как правило, сразу после блока модуля clinic:
```
#include "clinic/_pickle.c.h"
```
Перепроверьте, что сгенерированный Argument Clinic код разбора аргументов в основном совпадает с существующим кодом.

Во-первых, убедитесь, что в обоих местах используется одна и та же функция разбора аргументов. Существующий код должен вызывать либо PyArg_ParseTuple(), либо PyArg_ParseTupleAndKeywords(); добейтесь, чтобы код, сгенерированный Argument Clinic, вызывал ту же самую функцию.

Во-вторых, строка формата, передаваемая в PyArg_ParseTuple() или PyArg_ParseTupleAndKeywords(), должна быть в точности такой же, как написанная вручную в существующей функции, вплоть до двоеточия или точки с запятой.

(Argument Clinic всегда генерирует строки формата с :, за которым следует имя функции. Если строка формата существующего кода заканчивается на ; для вывода справки по использованию, это изменение безвредно – не беспокойтесь об этом.)

В-третьих, для параметров, единицы формата которых требуют двух аргументов (например, переменная длины, строка кодировки или указатель на функцию преобразования), убедитесь, что второй аргумент в точности одинаков в обоих вызовах.

В-четвёртых, внутри выходной части блока вы найдёте макрос препроцессора, определяющий соответствующую статическую структуру PyMethodDef для этой встроенной функции:
```
#define __PICKLE_PICKLER_DUMP_METHODDEF    \
{"dump", (PyCFunction)__pickle_Pickler_dump, METH_O, __pickle_Pickler_dump__doc__},
```
Эта статическая структура должна быть в точности такой же, как существующая статическая структура PyMethodDef для этой встроенной функции.

Если какой-либо из этих элементов хоть в чём-то отличается, измените спецификацию функции в Argument Clinic и повторно запустите Tools/clinic/clinic.py, пока они не станут одинаковыми.

Обратите внимание, что последняя строка вывода – это объявление вашей функции «impl». Сюда помещается реализация встроенной функции. Удалите существующий прототип изменяемой функции, но оставьте открывающую фигурную скобку. Затем удалите код разбора её аргументов и объявления всех переменных, в которые они помещались. Обратите внимание, что аргументы Python теперь стали аргументами этой функции impl; если в реализации использовались другие имена для этих переменных, исправьте это.

Повторим ещё раз, просто потому что это необычно. Теперь ваш код должен выглядеть так:

static return_type
your_function_impl(...)
/*[clinic end generated code: checksum=...]*/
{
...

Argument Clinic сгенерировал строку контрольной суммы и прототип функции прямо над ней. Вам нужно написать открывающую (и закрывающую) фигурные скобки для функции и реализацию внутри.

Пример:

/*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/
/*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/

/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
        Объект для сериализации.
    /

Записывает сериализованное представление obj в открытый файл.
[clinic start generated code]*/

PyDoc_STRVAR(__pickle_Pickler_dump__doc__,
"Write a pickled representation of obj to the open file.\n"
"\n"
...
static PyObject *
_pickle_Pickler_dump_impl(PicklerObject *self, PyObject *obj)
/*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/
{
    /* Проверяет, был ли Pickler инициализирован корректно (issue3664).
       Разработчики часто забывают вызывать __init__() в своих подклассах, что
       привело бы к segfault без этой проверки. */
    if (self->write == NULL) {
        PyErr_Format(PicklingError,
                     "Pickler.__init__() was not called by %s.__init__()",
                     Py_TYPE(self)->tp_name);
        return NULL;
    }

    if (_Pickler_ClearBuffer(self) < 0)
        return NULL;

    ...

Помните макрос со структурой PyMethodDef для этой функции? Найдите существующую структуру PyMethodDef для этой функции и замените её ссылкой на макрос. (Если встроенная функция находится на уровне модуля, это, скорее всего, будет почти в конце файла; если это метод класса, то, вероятно, ниже, но относительно рядом с реализацией.)

Обратите внимание, что тело макроса содержит завершающую запятую. Поэтому при замене существующей статической структуры PyMethodDef на макрос не добавляйте запятую в конце.

Пример:
```
static struct PyMethodDef Pickler_methods[] = {
    __PICKLE_PICKLER_DUMP_METHODDEF
    __PICKLE_PICKLER_CLEAR_MEMO_METHODDEF
    {NULL, NULL}                /* сторожевое значение */
};
```
Скомпилируйте, затем запустите соответствующие части набора регрессионных тестов. Это изменение не должно вызывать новых предупреждений или ошибок времени компиляции, а также не должно быть внешне заметных изменений в поведении Python.

Ну, за одним исключением: inspect.signature(), запущенная на вашей функции, теперь должна выдавать корректную сигнатуру!

Поздравляем, вы портировали свою первую функцию для работы с Argument Clinic!

Продвинутые темы¶Advanced Topics

Теперь, когда у вас есть некоторый опыт работы с Argument Clinic, пора перейти к продвинутым темам.

Символические значения по умолчанию¶Symbolic default values

Значение по умолчанию для параметра не может быть произвольным выражением. В настоящее время явно поддерживаются следующие:

Числовые константы (целые и с плавающей запятой)
Строковые константы
True, False и None
Простые символические константы, такие как sys.maxsize, должны начинаться с имени модуля

Если вам интересно, это реализовано в from_builtin() в Lib/inspect.py.

(В будущем это может потребовать ещё большей доработки, чтобы разрешить полноценные выражения вроде CONSTANT - 1.)

Переименование C-функций и переменных, сгенерированных Argument Clinic¶Renaming the C functions and variables generated by Argument Clinic

Argument Clinic автоматически присваивает имена сгенерированным функциям. Иногда это может вызывать проблему, если сгенерированное имя совпадает с именем существующей C-функции. Есть простое решение: переопределите имена, используемые для C-функций. Просто добавьте ключевое слово "as" в строку объявления функции, а затем укажите желаемое имя функции. Argument Clinic будет использовать это имя для базовой (сгенерированной) функции, после чего добавит "_impl" в конец и будет использовать его для имени функции реализации.

Например, если бы мы захотели переименовать C-функции, сгенерированные для pickle.Pickler.dump, это выглядело бы так:

/*[clinic input]
pickle.Pickler.dump as pickler_dumper

...

Теперь базовая функция будет называться pickler_dumper(), а функция реализации – pickler_dumper_impl().

Аналогично, может возникнуть ситуация, когда нужно дать параметру конкретное имя Python, но это имя может быть неудобным в C. Argument Clinic позволяет задать параметру разные имена в Python и C, используя тот же синтаксис "as":

/*[clinic input]
pickle.Pickler.dump

    obj: object
    file as file_obj: object
    protocol: object = NULL
    *
    fix_imports: bool = True

Здесь имя, используемое в Python (в сигнатуре и массиве keywords), будет file, а C-переменная будет называться file_obj.

Это можно использовать и для переименования параметра self!

Преобразование функций, использующих PyArg_UnpackTuple¶Converting functions using PyArg_UnpackTuple

Чтобы преобразовать функцию, которая разбирает свои аргументы с помощью PyArg_UnpackTuple(), просто перечислите все аргументы, указав каждый как object. Можно указать аргумент type для приведения типа по необходимости. Все аргументы должны быть помечены как только позиционные (добавьте / на отдельной строке после последнего аргумента).

Сейчас сгенерированный код будет использовать PyArg_ParseTuple(), но это скоро изменится.

Опциональные группы¶Optional Groups

Некоторые устаревшие функции используют хитрый подход к разбору своих аргументов: они подсчитывают количество позиционных аргументов, затем с помощью оператора switch вызывают один из нескольких разных вызовов PyArg_ParseTuple() в зависимости от количества позиционных аргументов. (Эти функции не могут принимать только ключевые аргументы.) Этот подход использовался для имитации опциональных аргументов до того, как был создан PyArg_ParseTupleAndKeywords().

Хотя функции, использующие этот подход, часто можно преобразовать для использования PyArg_ParseTupleAndKeywords(), опциональных аргументов и значений по умолчанию, это не всегда возможно. Некоторые из этих устаревших функций имеют поведение, которое PyArg_ParseTupleAndKeywords() напрямую не поддерживает. Самый очевидный пример – встроенная функция range(), у которой есть опциональный аргумент с левой стороны от обязательного аргумента! Другой пример – curses.window.addch(), у которой есть группа из двух аргументов, которые всегда должны указываться вместе. (Аргументы называются x и y; если вы вызываете функцию, передавая x, вы также должны передать y – а если вы не передаёте x, то нельзя передавать и y.)

В любом случае, цель Argument Clinic – поддерживать разбор аргументов для всех существующих встроенных функций CPython без изменения их семантики. Поэтому Argument Clinic поддерживает этот альтернативный подход к разбору, используя так называемые опциональные группы. Опциональные группы – это группы аргументов, которые должны передаваться вместе. Они могут находиться слева или справа от обязательных аргументов. Их можно использовать только с только позиционными параметрами.

Примечание

Опциональные группы предназначены только для использования при преобразовании функций, которые выполняют несколько вызовов PyArg_ParseTuple()! Функции, использующие любой другой подход для разбора аргументов, почти никогда не должны преобразовываться в Argument Clinic с использованием опциональных групп. Функции, использующие опциональные группы, в настоящее время не могут иметь точные сигнатуры в Python, потому что Python просто не понимает эту концепцию. Пожалуйста, по возможности избегайте использования опциональных групп.

Чтобы указать опциональную группу, добавьте [ на отдельной строке перед параметрами, которые нужно сгруппировать, и ] на отдельной строке после этих параметров. В качестве примера, вот как curses.window.addch использует опциональные группы, чтобы сделать первые два параметра и последний параметр опциональными:

/*[clinic input]

curses.window.addch

    [
    x: int
      Координата X.
    y: int
      Координата Y.
    ]

    ch: object
      Добавляемый символ.

    [
    attr: long
      Атрибуты для символа.
    ]
    /

...

Примечания:

Для каждой опциональной группы в функцию реализации будет передан один дополнительный параметр, представляющий группу. Параметр будет иметь тип int и имя group_{direction}_{number}, где {direction} – это либо right, либо left в зависимости от того, находится ли группа до или после обязательных параметров, а {number} – монотонно возрастающее число (начиная с 1), указывающее, насколько далеко группа находится от обязательных параметров. Когда вызывается функция реализации, этот параметр будет установлен в ноль, если группа не использовалась, и в ненулевое значение, если группа использовалась. (Под использованием или неиспользованием я имею в виду, получили ли параметры аргументы в этом вызове.)
Если обязательных аргументов нет, опциональные группы будут вести себя так, как если бы они находились справа от обязательных аргументов.
В случае неоднозначности код разбора аргументов отдаёт предпочтение параметрам слева (перед обязательными параметрами).
Опциональные группы могут содержать только позиционные параметры.
Опциональные группы предназначены только для устаревшего кода. Пожалуйста, не используйте опциональные группы в новом коде.

Использование настоящих конвертеров Argument Clinic вместо «устаревших конвертеров»¶Using real Argument Clinic converters, instead of “legacy converters”

Чтобы сэкономить время и минимизировать объём знаний, необходимых для первого переноса кода на Argument Clinic, в приведённом выше пошаговом руководстве рекомендуется использовать «устаревшие конвертеры». «Устаревшие конвертеры» – это удобство, созданное специально для упрощения переноса существующего кода на Argument Clinic. И, чтобы было понятно, их использование допустимо при переносе кода для Python 3.4.

Однако в долгосрочной перспективе, вероятно, желательно, чтобы все наши блоки использовали настоящий синтаксис конвертеров Argument Clinic. Почему? Несколько причин:

Правильные конвертеры гораздо легче читать, и их назначение понятнее.
Существуют некоторые форматные единицы, которые не поддерживаются в качестве «устаревших конвертеров», поскольку они требуют аргументов, а синтаксис устаревших конвертеров не поддерживает указание аргументов.
В будущем у нас может появиться новая библиотека для разбора аргументов, которая не будет ограничена тем, что поддерживает PyArg_ParseTuple(); эта гибкость не будет доступна параметрам, использующим устаревшие конвертеры.

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

В двух словах, синтаксис (неустаревших) конвертеров Argument Clinic выглядит как вызов функции Python. Однако, если у функции нет явных аргументов (все функции принимают свои значения по умолчанию), скобки можно опустить. Таким образом, bool и bool() – это абсолютно одинаковые конвертеры.

Все аргументы конвертеров Argument Clinic являются только ключевыми (keyword-only). Все конвертеры Argument Clinic принимают следующие аргументы:

c_default
Значение по умолчанию для этого параметра при определении в C. А именно, это будет инициализатор переменной, объявленной в «функции разбора» (parse function). См. раздел о значениях по умолчанию, чтобы узнать, как это использовать. Указывается в виде строки.

annotation
Значение аннотации для этого параметра. В настоящее время не поддерживается, поскольку PEP 8 предписывает, что библиотека Python не должна использовать аннотации.

Кроме того, некоторые конвертеры принимают дополнительные аргументы. Вот список этих аргументов с их значениями:

accept
Набор типов Python (и, возможно, псевдотипов); это ограничивает допустимые аргументы Python значениями этих типов. (Это не универсальный механизм; как правило, он поддерживает только конкретные списки типов, как показано в таблице устаревших конвертеров.)

Чтобы принимать None, добавьте NoneType в этот набор.

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

converter
Поддерживается только конвертером object. Указывает имя C-«функции-конвертера», используемой для преобразования этого объекта в собственный тип.

encoding
Поддерживается только для строк. Указывает кодировку, используемую при преобразовании этой строки из значения Python str (Unicode) в значение C char *.

subclass_of
Поддерживается только для конвертера object. Требует, чтобы значение Python было подклассом типа Python, как это выражается в C.

type
Поддерживается только для конвертеров object и self. Указывает тип C, который будет использоваться для объявления переменной. Значение по умолчанию: "PyObject *".

zeroes
Поддерживается только для строк. Если true, внутри значения допускаются встроенные NUL-байты ('\\0'). Длина строки будет передана в функцию impl сразу после строкового параметра как параметр с именем <parameter_name>_length.

Пожалуйста, учтите: не любая комбинация аргументов будет работать. Обычно эти аргументы реализуются конкретными PyArg_ParseTuple форматными единицами с определённым поведением. Например, в настоящее время нельзя вызвать unsigned_short, не указав также bitwise=True. Хотя вполне разумно предположить, что это сработает, такая семантика не соответствует ни одной существующей форматной единице. Поэтому Argument Clinic это не поддерживает (или, по крайней мере, пока нет).

Ниже приведена таблица, показывающая соответствие устаревших конвертеров настоящим конвертерам Argument Clinic. Слева – устаревший конвертер, справа – текст, на который его следует заменить.

`'B'`	`unsigned_char(bitwise=True)`
`'b'`	`unsigned_char`
`'c'`	`char`
`'C'`	`int(accept={str})`
`'d'`	`double`
`'D'`	`Py_complex`
`'es'`	`str(encoding='name_of_encoding')`
`'es#'`	`str(encoding='name_of_encoding', zeroes=True)`
`'et'`	`str(encoding='name_of_encoding', accept={bytes, bytearray, str})`
`'et#'`	`str(encoding='name_of_encoding', accept={bytes, bytearray, str}, zeroes=True)`
`'f'`	`float`
`'h'`	`short`
`'H'`	`unsigned_short(bitwise=True)`
`'i'`	`int`
`'I'`	`unsigned_int(bitwise=True)`
`'k'`	`unsigned_long(bitwise=True)`
`'K'`	`unsigned_long_long(bitwise=True)`
`'l'`	`long`
`'L'`	`long long`
`'n'`	`Py_ssize_t`
`'O'`	`object`
`'O!'`	`object(subclass_of='&PySomething_Type')`
`'O&'`	`object(converter='name_of_c_function')`
`'p'`	`bool`
`'S'`	`PyBytesObject`
`'s'`	`str`
`'s#'`	`str(zeroes=True)`
`'s*'`	`Py_buffer(accept={buffer, str})`
`'U'`	`unicode`
`'u'`	`Py_UNICODE`
`'u#'`	`Py_UNICODE(zeroes=True)`
`'w*'`	`Py_buffer(accept={rwbuffer})`
`'Y'`	`PyByteArrayObject`
`'y'`	`str(accept={bytes})`
`'y#'`	`str(accept={robuffer}, zeroes=True)`
`'y*'`	`Py_buffer`
`'Z'`	`Py_UNICODE(accept={str, NoneType})`
`'Z#'`	`Py_UNICODE(accept={str, NoneType}, zeroes=True)`
`'z'`	`str(accept={str, NoneType})`
`'z#'`	`str(accept={str, NoneType}, zeroes=True)`
`'z*'`	`Py_buffer(accept={buffer, str, NoneType})`

В качестве примера – наш образец pickle.Pickler.dump с использованием правильного конвертера:

/*[clinic input]
pickle.Pickler.dump

    obj: object
        Объект для сериализации.
    /

Записывает сериализованное представление obj в открытый файл.
[clinic start generated code]*/

Одно из преимуществ настоящих конвертеров – они более гибкие, чем устаревшие. Например, конвертер unsigned_int (и все конвертеры unsigned_) можно указать без bitwise=True. Их поведение по умолчанию выполняет проверку диапазона значения, и они не принимают отрицательные числа. С устаревшим конвертером так не получится!

Argument Clinic покажет все доступные конвертеры. Для каждого конвертера будут показаны все принимаемые параметры и значения по умолчанию. Просто запустите Tools/clinic/clinic.py --converters, чтобы увидеть полный список.

Py_buffer¶

При использовании конвертера Py_buffer (или устаревших конвертеров 's*', 'w*', '*y', 'z*') не вызывайте PyBuffer_Release() для предоставленного буфера. Argument Clinic генерирует код, который делает это за вас (в функции разбора).

Продвинутые конвертеры¶Advanced converters

Помните те форматные единицы, которые вы пропустили в первый раз, потому что они были сложными? Вот как с ними работать.

Секрет в том, что все эти форматные единицы принимают аргументы – либо функции преобразования, либо типы, либо строки с указанием кодировки. (Но «устаревшие конвертеры» не поддерживают аргументы. Поэтому мы пропустили их для вашей первой функции.) Аргумент, который вы указывали для форматной единицы, теперь является аргументом конвертера; этот аргумент может быть converter (для O&), subclass_of (для O!) или encoding (для всех форматных единиц, начинающихся с e).

При использовании subclass_of вы также можете использовать другой пользовательский аргумент для object(): type, который позволяет задать фактический тип, используемый для параметра. Например, если вы хотите гарантировать, что объект является подклассом PyUnicode_Type, вероятно, стоит использовать конвертер object(type='PyUnicodeObject *', subclass_of='&PyUnicode_Type').

Одна из возможных проблем при использовании Argument Clinic: он лишает некоторой гибкости форматные единицы, начинающиеся с e. При написании вызова PyArg_Parse вручную можно было теоретически на этапе выполнения решить, какую строку кодировки передать в PyArg_ParseTuple(). Но теперь эта строка должна быть жестко задана на этапе предварительной обработки Argument Clinic. Это ограничение намеренное: оно значительно упростило поддержку этой форматной единицы и может позволить будущие оптимизации. Такое ограничение не кажется необоснованным; сам CPython всегда передает статические жестко заданные строки кодировки для параметров, чьи форматные единицы начинаются с e.

Значения по умолчанию параметров¶Parameter default values

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

foo: str = "abc"
bar: int = 123
bat: float = 45.6

Также могут использоваться любые встроенные константы Python:

yep:  bool = True
nope: bool = False
nada: object = None

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

Значение по умолчанию `NULL`¶The NULL default value

Для строковых параметров и параметров-объектов можно установить их в None, чтобы указать отсутствие значения по умолчанию. Однако это означает, что переменная C будет инициализирована значением Py_None. Для удобства существует специальное значение NULL как раз для этого: с точки зрения Python оно ведёт себя как значение по умолчанию None, но переменная C инициализируется значением NULL.

Выражения, задаваемые как значения по умолчанию¶Expressions specified as default values

Значение по умолчанию для параметра может быть не просто литералом. Это может быть целое выражение, использующее математические операторы и обращающееся к атрибутам объектов. Однако эта поддержка не совсем проста из-за некоторых неочевидных семантических нюансов.

Рассмотрим следующий пример:

foo: Py_ssize_t = sys.maxsize - 1

sys.maxsize может принимать разные значения на разных платформах. Поэтому Argument Clinic не может просто вычислить это выражение локально и жёстко закодировать его в C. Вместо этого он сохраняет значение по умолчанию так, чтобы оно вычислялось во время выполнения, когда пользователь запрашивает сигнатуру функции.

Какое пространство имён доступно при вычислении выражения? Оно вычисляется в контексте модуля, из которого происходит встроенная функция. Поэтому, если в модуле есть атрибут с именем «max_widgets», его можно просто использовать:

foo: Py_ssize_t = max_widgets

Если символ не найден в текущем модуле, поиск продолжается в sys.modules. Именно так, например, можно найти sys.maxsize. (Поскольку заранее неизвестно, какие модули пользователь загрузит в интерпретатор, лучше ограничиться модулями, которые предварительно загружает сам Python.)

Вычисление значений по умолчанию только во время выполнения означает, что Argument Clinic не может вычислить правильное эквивалентное значение C по умолчанию. Поэтому необходимо указать его явно. При использовании выражения нужно также указать эквивалентное выражение на C с помощью параметра c_default конвертера:

foo: Py_ssize_t(c_default="PY_SSIZE_T_MAX - 1") = sys.maxsize - 1

Ещё одно осложнение: Argument Clinic не может заранее узнать, является ли предоставленное выражение корректным. Он разбирает его, чтобы убедиться, что оно выглядит допустимым, но не может на самом деле знать. Нужно быть очень осторожным при использовании выражений для указания значений, которые гарантированно будут корректными во время выполнения!

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

Вызовы функций.
Условные выражения (3 if foo else 5).
Автоматическая распаковка последовательностей (*[1, 2, 3]).
Генераторы списков, множеств, словарей и выражения-генераторы.
Литералы кортежей, списков, множеств, словарей.

Использование конвертера возвращаемого значения¶Using a return converter

По умолчанию функция impl, генерируемая Argument Clinic, возвращает PyObject *. Но C-функция часто вычисляет некоторый тип C, а затем преобразует его в PyObject * в последний момент. Argument Clinic занимается преобразованием входных данных из типов Python в нативные типы C – почему бы не поручить ему также преобразование возвращаемого значения из нативного типа C в тип Python?

Именно это и делает «конвертер возвращаемого значения». Он изменяет функцию impl так, чтобы она возвращала некоторый тип C, а затем добавляет код в сгенерированную (не-impl) функцию для преобразования этого значения в соответствующий PyObject *.

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

(Если используются и "as", и конвертер возвращаемого значения для функции, то "as" должен идти перед конвертером возвращаемого значения.)

При использовании конвертеров возвращаемого значения есть ещё одно осложнение: как указать, что произошла ошибка? Обычно функция возвращает корректный (не NULL) указатель при успехе и NULL при неудаче. Но если используется целочисленный конвертер возвращаемого значения, все целые числа являются корректными. Как Argument Clinic может обнаружить ошибку? Его решение: каждый конвертер возвращаемого значения неявно ищет специальное значение, указывающее на ошибку. Если возвращается это значение и ошибка была установлена (PyErr_Occurred() возвращает истинное значение), то сгенерированный код распространит ошибку. В противном случае он закодирует возвращённое значение как обычно.

В настоящее время Argument Clinic поддерживает лишь несколько конвертеров возвращаемого значения:

bool
int
unsigned int
long
unsigned int
size_t
Py_ssize_t
float
double
DecodeFSDefault

Ни один из них не принимает параметров. Для первых трёх возвращайте -1 для указания ошибки. Для DecodeFSDefault тип возвращаемого значения – const char *; возвращайте нулевой NULL указатель, чтобы указать на ошибку.

(Существует также экспериментальный конвертер NoneType, который позволяет возвращать Py_None при успехе или NULL при неудаче, без необходимости увеличивать счётчик ссылок на Py_None. Не уверен, что он добавляет достаточно ясности, чтобы его стоило использовать.)

Чтобы увидеть все конвертеры возвращаемого значения, поддерживаемые Argument Clinic, вместе с их параметрами (если они есть), просто запустите Tools/clinic/clinic.py --converters для получения полного списка.

Клонирование существующих функций¶Cloning existing functions

Если есть несколько функций, которые выглядят похоже, можно воспользоваться функцией «клонирования» в Clinic. При клонировании существующей функции повторно используются:

её параметры, включая
- их имена,
- их конвертеры, со всеми параметрами,
- их значения по умолчанию,
- их документирующие строки для каждого параметра,
- их вид (являются ли они только позиционными, позиционными или ключевыми, или только ключевыми), и
её конвертер возвращаемого значения.

Единственное, что не копируется из исходной функции, – это её документирующая строка; синтаксис позволяет указать новую документирующую строку.

Вот синтаксис клонирования функции:

/*[clinic input]
module.class.new_function [as c_basename] = module.class.existing_function

Докстринг для new_function.
[clinic start generated code]*/

(Функции могут находиться в разных модулях или классах. Я написал module.class в примере просто для иллюстрации того, что необходимо использовать полный путь к обеим функциям.)

Извините, нет синтаксиса для частичного клонирования функции или для клонирования функции с последующим её изменением. Клонирование – это принцип «всё или ничего».

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

Вызов кода Python¶Calling Python code

Для остальных продвинутых тем требуется написать код Python, который находится внутри C-файла и изменяет состояние времени выполнения Argument Clinic. Это просто: нужно всего лишь определить блок Python.

Блок Python использует другие строки-разделители, нежели блок функции Argument Clinic. Выглядит это так:

/*[python input]
# Сюда помещается код Python.
[python start generated code]*/

Весь код внутри блока Python выполняется в момент его разбора. Весь текст, выводимый в stdout внутри блока, перенаправляется в «вывод» после блока.

В качестве примера приведён блок Python, который добавляет статическую целочисленную переменную в код C:

/*[python input]
print('static int __ignored_unused_variable__ = 0;')
[python start generated code]*/
static int __ignored_unused_variable__ = 0;
/*[python checksum:...]*/

Использование «конвертера self»¶Using a “self converter”

Argument Clinic автоматически добавляет параметр «self» с помощью конвертера по умолчанию. Он автоматически устанавливает type этого параметра на «указатель на экземпляр», указанный вами при объявлении типа. Однако вы можете переопределить конвертер Argument Clinic и указать свой собственный. Просто добавьте собственный параметр self в качестве первого параметра в блоке и убедитесь, что его конвертер является экземпляром self_converter или его подкласса.

В чём смысл? Это позволяет переопределить тип self или задать ему другое имя по умолчанию.

Как указать пользовательский тип, к которому нужно привести self? Если у вас всего одна или две функции с одинаковым типом для self, можно напрямую использовать существующий конвертер self в Argument Clinic, передав нужный тип в качестве параметра type:

/*[clinic input]

_pickle.Pickler.dump

  self: self(type="PicklerObject *")
  obj: object
  /

Записывает сериализованное представление данного объекта в открытый файл.
[clinic start generated code]*/

С другой стороны, если у вас много функций, использующих один и тот же тип для self, лучше создать свой собственный конвертер, унаследовав его от self_converter, но переопределив член type:

/*[python input]
class PicklerObject_converter(self_converter):
    type = "PicklerObject *"
[python start generated code]*/

/*[clinic input]

_pickle.Pickler.dump

  self: PicklerObject
  obj: object
  /

Записывает сериализованное представление данного объекта в открытый файл.
[clinic start generated code]*/

Использование конвертера «определяющего класса»¶Using a “defining class” converter

Argument Clinic упрощает получение доступа к определяющему классу метода. Это полезно для методов кучного типа, которым нужно получать состояние на уровне модуля. Используйте PyType_FromModuleAndSpec() для связывания нового кучного типа с модулем. Теперь можно использовать PyType_GetModuleState() на определяющем классе для получения состояния модуля, например, из метода модуля.

Пример из Modules/zlibmodule.c. Сначала defining_class добавляется во входные данные clinic:

/*[clinic input]
zlib.Compress.compress

  cls: defining_class
  data: Py_buffer
    Бинарные данные для сжатия.
  /

После запуска инструмента Argument Clinic генерируется следующая сигнатура функции:

/*[clinic start generated code]*/
static PyObject *
zlib_Compress_compress_impl(compobject *self, PyTypeObject *cls,
                            Py_buffer *data)
/*[clinic end generated code: output=6731b3f0ff357ca6 input=04d00f65ab01d260]*/

Теперь следующий код может использовать PyType_GetModuleState(cls) для получения состояния модуля:

zlibstate *state = PyType_GetModuleState(cls);

Каждый метод может иметь только один аргумент с этим конвертером, и он должен располагаться после self, или, если self не используется, в качестве первого аргумента. Аргумент будет иметь тип PyTypeObject *. Этот аргумент не будет отображаться в __text_signature__.

Конвертер defining_class несовместим с методами __init__ и __new__, которые не могут использовать соглашение METH_METHOD.

Невозможно использовать defining_class со слотами методов. Чтобы получить состояние модуля из таких методов, используйте _PyType_GetModuleByDef для поиска модуля, а затем PyModule_GetState() для получения состояния модуля. Пример из слота setattro в Modules/_threadmodule.c:

static int
local_setattro(localobject *self, PyObject *name, PyObject *v)
{
    PyObject *module = _PyType_GetModuleByDef(Py_TYPE(self), &thread_module);
    thread_module_state *state = get_thread_state(module);
    ...
}

См. также PEP 573.

Создание пользовательского конвертера¶Writing a custom converter

Как мы намекнули в предыдущем разделе… вы можете писать свои собственные конвертеры! Конвертер – это просто класс Python, наследующий от CConverter. Основная цель пользовательского конвертера – наличие параметра, использующего единицу формата O& – разбор этого параметра означает вызов функции-конвертера PyArg_ParseTuple().

Ваш класс конвертера должен называться *something*_converter. Если имя соответствует этому соглашению, класс конвертера будет автоматически зарегистрирован в Argument Clinic; его именем станет имя вашего класса без суффикса _converter. (Это достигается с помощью метакласса.)

Не следует наследовать CConverter.__init__. Вместо этого нужно написать функцию converter_init(). converter_init() всегда принимает параметр self; после этого все дополнительные параметры должны быть только ключевыми. Любые аргументы, переданные конвертеру в Argument Clinic, будут переданы вашей converter_init().

Существуют некоторые дополнительные члены CConverter, которые вы, возможно, захотите указать в вашем подклассе. Вот текущий список:

type: Тип C, используемый для этой переменной. type должен быть строкой Python, задающей тип, например, int. Если это тип указателя, строка типа должна заканчиваться на ' *'.
default: Значение по умолчанию для этого параметра в Python, в виде значения Python. Или магическое значение unspecified, если значения по умолчанию нет.
py_default: default в том виде, в котором он должен отображаться в коде Python, в виде строки. Или None, если значения по умолчанию нет.
c_default: default в том виде, в котором он должен отображаться в коде C, в виде строки. Или None, если значения по умолчанию нет.
c_ignored_default: Значение по умолчанию, используемое для инициализации переменной C, когда нет значения по умолчанию, но его неуказание может привести к предупреждению «неинициализированная переменная». Это легко может произойти при использовании групп опций – хотя правильно написанный код никогда не будет использовать это значение, переменная всё равно передаётся в реализацию, и компилятор C выдаст предупреждение об «использовании» неинициализированного значения. Это значение всегда должно быть непустой строкой.
converter: Имя функции-преобразователя C в виде строки.
impl_by_reference: Логическое значение. Если истинно, Argument Clinic добавит & перед именем переменной при передаче её в функцию impl.
parse_by_reference: Логическое значение. Если истинно, Argument Clinic добавит & перед именем переменной при передаче её в PyArg_ParseTuple().

Вот простейший пример пользовательского преобразователя из Modules/zlibmodule.c:

/*[python input]

class ssize_t_converter(CConverter):
    type = 'Py_ssize_t'
    converter = 'ssize_t_converter'

[python start generated code]*/
/*[python end generated code: output=da39a3ee5e6b4b0d input=35521e4e733823c7]*/

Этот блок добавляет в Argument Clinic преобразователь с именем ssize_t. Параметры, объявленные как ssize_t, будут объявлены как тип Py_ssize_t и будут разобраны форматным элементом 'O&', который вызовет функцию-преобразователь ssize_t_converter. Переменные ssize_t автоматически поддерживают значения по умолчанию.

Более сложные пользовательские преобразователи могут вставлять собственный код C для обработки инициализации и очистки. Дополнительные примеры пользовательских преобразователей можно найти в исходном коде CPython; выполните grep по файлам C для строки CConverter.

Написание пользовательского преобразователя возвращаемого значения¶Writing a custom return converter

Написание пользовательского преобразователя возвращаемого значения во многом похоже на написание обычного пользовательского преобразователя, только несколько проще, потому что сами преобразователи возвращаемых значений намного проще.

Преобразователи возвращаемых значений должны быть подклассами CReturnConverter. Примеров пользовательских преобразователей возвращаемых значений пока нет, поскольку они ещё не получили широкого распространения. Если вы хотите написать свой собственный преобразователь возвращаемого значения, прочтите Tools/clinic/clinic.py, в частности реализацию CReturnConverter и всех его подклассов.

METH_O и METH_NOARGS¶METH_O and METH_NOARGS

Чтобы преобразовать функцию, использующую METH_O, убедитесь, что её единственный аргумент использует преобразователь object, и пометьте аргументы как позиционные:

/*[clinic input]
meth_o_sample

     argument: object
     /
[clinic start generated code]*/

Чтобы преобразовать функцию, использующую METH_NOARGS, просто не указывайте никаких аргументов.

По-прежнему можно использовать преобразователь self, преобразователь возвращаемого значения и указать аргумент type для преобразователя объекта METH_O.

Функции tp_new и tp_init¶tp_new and tp_init functions

Вы можете преобразовывать функции tp_new и tp_init. Просто назовите их __new__ или __init__ соответственно. Примечания:

Сгенерированное имя функции для __new__ не заканчивается на __new__, как было бы по умолчанию. Это просто имя класса, преобразованное в корректный идентификатор C.
Для этих функций не генерируется PyMethodDef #define.
Функции __init__ возвращают int, а не PyObject *.
Используйте строку документации как строку документации класса.
Хотя функции __new__ и __init__ всегда должны принимать оба объекта args и kwargs, при преобразовании вы можете указать для этих функций любую сигнатуру. (Если ваша функция не поддерживает ключевые слова, сгенерированная функция разбора вызовет исключение при их получении.)

Изменение и перенаправление вывода Clinic¶Changing and redirecting Clinic’s output

Может быть неудобно, когда вывод Clinic перемежается с вашим обычным кодом C, отредактированным вручную. К счастью, Clinic настраивается: можно буферизовать его вывод для печати позже (или раньше!) или записывать вывод в отдельный файл. Также можно добавить префикс или суффикс к каждой строке сгенерированного вывода Clinic.

Хотя такое изменение вывода Clinic может улучшить читаемость, это может привести к тому, что код Clinic будет использовать типы до их определения, или ваш код будет пытаться использовать сгенерированный Clinic код до его определения. Эти проблемы легко решаются перестановкой объявлений в файле или перемещением места, куда помещается сгенерированный код Clinic. (Именно поэтому поведение Clinic по умолчанию – выводить всё в текущий блок; хотя многие считают, что это затрудняет чтение, это никогда не потребует перестановки кода для исправления проблем использования до определения.)

Начнём с определения некоторых терминов:

поле

Поле в данном контексте – это подраздел вывода Clinic. Например, #define для структуры PyMethodDef является полем, называемым methoddef_define. Clinic может выводить семь различных полей для каждого определения функции:

docstring_prototype
docstring_definition
methoddef_define
impl_prototype
parser_prototype
parser_definition
impl_definition

Все имена имеют вид "<a>_<b>", где "<a>" – это представляемый семантический объект (функция разбора, функция impl, строка документации или структура methoddef), а "<b>" обозначает, какой тип оператора представляет поле. Имена полей, заканчивающиеся на "_prototype", представляют предварительные объявления этой сущности без фактического тела/данных; имена полей, заканчивающиеся на "_definition", представляют фактическое определение сущности с телом/данными. ("methoddef" особое, это единственное, заканчивающееся на "_define", что означает, что это директива препроцессора #define.)

назначение

Назначение – это место, куда Clinic может записывать вывод. Существует пять встроенных назначений:

block

Назначение по умолчанию: выводится в секции вывода текущего блока Clinic.

buffer

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

file

Отдельный «файл clinic», который будет автоматически создан Clinic. Выбранное имя файла – {basename}.clinic{extension}, где basename и extension получили вывод от os.path.splitext(), запущенного на текущем файле. (Пример: назначение file для _pickle.c будет записано в _pickle.clinic.c.)

Важно: при использовании file назначения обязательно проверьте сгенерированный файл!

two-pass

Буфер, подобный buffer. Однако буфер двойного прохода можно сбросить только один раз, и он выводит весь текст, отправленный ему во время всей обработки, даже из блоков Clinic после точки сброса.

suppress

Текст подавляется – отбрасывается.

Clinic определяет пять новых директив, позволяющих перенастроить его вывод.

Первая новая директива – dump:

dump <destination>

Эта директива сбрасывает текущее содержимое указанного назначения в вывод текущего блока и очищает его. Она работает только с назначениями buffer и two-pass.

Вторая новая директива – output. Самая простая форма output выглядит так:

output <field> <destination>

Эта директива указывает Clinic выводить поле в назначение. output также поддерживает специальное мета-назначение под названием everything, которое указывает Clinic выводить все поля в это назначение.

output имеет ряд других функций:

output push
output pop
output preset <preset>

output push и output pop позволяют помещать и извлекать конфигурации со внутреннего стека конфигураций, чтобы можно было временно изменить конфигурацию вывода, а затем легко восстановить предыдущую конфигурацию. Просто поместите текущую конфигурацию в стек перед изменением, чтобы сохранить её, а затем извлеките, когда потребуется восстановить предыдущую конфигурацию.

output preset устанавливает вывод Clinic в одну из нескольких встроенных предустановленных конфигураций следующим образом:

block
Исходная начальная конфигурация Clinic. Пишет всё сразу после входного блока.

Подавляет parser_prototype и docstring_prototype, всё остальное записывает в block.

file
Предназначен для записи всего, что возможно, в «clinic-файл». Затем этот файл #include ближе к началу вашего файла. Возможно, потребуется перестроить файл, чтобы это заработало, но обычно для этого достаточно создать прямые объявления для различных определений typedef и PyTypeObject.

Подавляет parser_prototype и docstring_prototype, записывает impl_definition в block, а всё остальное – в file.

Имя файла по умолчанию – "{dirname}/clinic/{basename}.h".

buffer
Сохраняет большую часть вывода Clinic для последующей записи в файл ближе к концу. Для файлов Python, реализующих модули или встроенные типы, рекомендуется сбрасывать буфер непосредственно перед статическими структурами для модуля или встроенного типа; обычно они находятся ближе к концу. Использование buffer может потребовать даже больше правок, чем file, если в файле есть статические массивы PyMethodDef, определённые в середине файла.

Подавляет parser_prototype, impl_prototype и docstring_prototype, записывает impl_definition в block, а всё остальное – в file.

two-pass
Аналогичен предустановке buffer, но записывает прямые объявления в буфер two-pass, а определения – в buffer. Это похоже на предустановку buffer, но может потребовать меньше правок, чем buffer. Сбросьте буфер two-pass ближе к началу файла, а буфер buffer – ближе к концу, как при использовании предустановки buffer.

Подавляет impl_prototype, записывает impl_definition в block, записывает docstring_prototype, methoddef_define и parser_prototype в two-pass, всё остальное записывает в buffer.

partial-buffer
Аналогичен предустановке buffer, но записывает больше вещей в block, а действительно большие фрагменты сгенерированного кода – только в buffer. Это полностью исключает проблему «определение до использования» предустановки buffer, ценой немного большего количества материала в выводе блока. Сбросьте буфер buffer ближе к концу, как при использовании предустановки buffer.

Подавляет impl_prototype, записывает docstring_definition и parser_definition в buffer, всё остальное записывает в block.

Третья новая директива – destination:

destination <name> <command> [...]

Эта директива выполняет операцию над назначением с именем name.

Определены две подкоманды: new и clear.

Подкоманда new работает следующим образом:

destination <name> new <type>

Это создаёт новое назначение с именем <name> и типом <type>.

Существует пять типов назначений:

suppress
Отбрасывает текст.

block
Записывает текст в текущий блок. Именно так Clinic работал изначально.

buffer
Простой текстовый буфер, как встроенное назначение «buffer» выше.

file
Текстовый файл. Назначение «файл» принимает дополнительный аргумент – шаблон для построения имени файла, например:

назначение <имя> new <тип> <шаблон_файла>

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

{path}
Полный путь к файлу, включая каталог и полное имя файла.

{dirname}
Имя каталога, в котором находится файл.

{basename}
Просто имя файла, без каталога.

{basename_root}
Базовое имя без расширения (всё до последней точки, но не включая её).

{basename_extension}
Последняя точка и всё после неё. Если в базовом имени нет точки, будет пустая строка.

Если в имени файла нет точек, {basename} и {filename} совпадают, а {extension} пуст. «{basename}{extension}» всегда совпадает с «{filename}».

two-pass
Буфер двухпроходной обработки, как встроенное назначение «two-pass» выше.

Подкоманда clear работает следующим образом:

destination <name> clear

Она удаляет весь накопленный текст до этой точки в назначении. (Не знаю, для чего это может понадобиться, но подумал, что может быть полезно для экспериментов.)

Четвёртая новая директива – set:

set line_prefix "string"
set line_suffix "string"

set позволяет задать две внутренние переменные в Clinic. line_prefix – строка, которая будет добавляться перед каждой строкой вывода Clinic; line_suffix – строка, которая будет добавляться после каждой строки вывода Clinic.

Обе поддерживают две строки формата:

{block comment start}
Превращается в строку /*, последовательность символов начала комментария для C-файлов.

{block comment end}
Превращается в строку */, последовательность символов конца комментария для C-файлов.

Последняя новая директива – та, которую не нужно использовать напрямую, называется preserve:

preserve

Это говорит Clinic, что текущее содержимое вывода следует оставить без изменений. Внутренне Clinic использует это при выгрузке вывода в файлы file; оборачивание в блок Clinic позволяет Clinic использовать существующую функциональность контрольных сумм, чтобы гарантировать, что файл не был изменён вручную перед его перезаписью.

Трюк с #ifdef¶The #ifdef trick

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

#ifdef HAVE_FUNCTIONNAME
static module_functionname(...)
{
...
}
#endif /* HAVE_FUNCTIONNAME */

И затем в структуре PyMethodDef в нижней части существующий код будет содержать:

#ifdef HAVE_FUNCTIONNAME
{'functionname', ... },
#endif /* HAVE_FUNCTIONNAME */

В этом случае тело функции impl нужно заключить внутрь #ifdef, вот так:

#ifdef HAVE_FUNCTIONNAME
/*[clinic input]
module.functionname
...
[clinic start generated code]*/
static module_functionname(...)
{
...
}
#endif /* HAVE_FUNCTIONNAME */

Затем удалите эти три строки из структуры PyMethodDef, заменив их макросом, сгенерированным Argument Clinic:

MODULE_FUNCTIONNAME_METHODDEF

(Настоящее имя этого макроса можно найти в сгенерированном коде. Или можно вычислить его самостоятельно: это имя вашей функции, как оно определено в первой строке вашего блока, но с заменой точек на подчёркивания, в верхнем регистре и с добавлением "_METHODDEF" в конец.)

Возможно, вы задаётесь вопросом: что если HAVE_FUNCTIONNAME не определён? Тогда макрос MODULE_FUNCTIONNAME_METHODDEF тоже не будет определён!

Вот где Argument Clinic проявляет смекалку. Он обнаруживает, что блок Argument Clinic может быть деактивирован директивой #ifdef. Когда это происходит, он генерирует небольшой дополнительный код, который выглядит так:

#ifndef MODULE_FUNCTIONNAME_METHODDEF
    #define MODULE_FUNCTIONNAME_METHODDEF
#endif /* !defined(MODULE_FUNCTIONNAME_METHODDEF) */

Это означает, что макрос всегда работает. Если функция определена, это превращается в правильную структуру, включая завершающую запятую. Если функция не определена, это превращается в ничто.

Однако это вызывает одну деликатную проблему: куда Argument Clinic должен поместить этот дополнительный код при использовании пресета вывода "block"? Его нельзя поместить в выходной блок, потому что он может быть деактивирован #ifdef. (В этом вся суть!)

В этой ситуации Argument Clinic записывает дополнительный код в назначение "buffer". Это может означать, что Argument Clinic выдаст предупреждение:

Warning in file "Modules/posixmodule.c" on line 12357:
Destination buffer 'buffer' not empty at end of file, emptying.

Если это произошло, просто откройте файл, найдите блок dump buffer, который Argument Clinic добавил в файл (он будет в самом низу), и переместите его выше структуры PyMethodDef, где используется этот макрос.

Использование Argument Clinic в файлах Python¶Using Argument Clinic in Python files

На самом деле Argument Clinic можно использовать для предварительной обработки файлов Python. Конечно, использовать блоки Argument Clinic нет смысла, так как интерпретатор Python не поймёт вывод. Но использование Argument Clinic для выполнения блоков Python позволяет использовать Python в качестве препроцессора для Python!

Поскольку комментарии в Python отличаются от комментариев в C, блоки Argument Clinic, встроенные в файлы Python, выглядят немного иначе. Они выглядят так:

#/*[python input]
#print("def foo(): pass")
#[python start generated code]*/
def foo(): pass
#/*[python checksum:...]*/