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

Руководство по 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 3.5, может оказаться полностью несовместимой и сломать весь ваш код.

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

Основная цель Argument Clinic – взять на себя всю работу по разбору аргументов внутри CPython. Это означает, что при переводе функции на работу с 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]*/
```
Вырежьте docstring и вставьте его между строками [clinic], удалив весь мусор, который делает из него правильно оформленную C-строку. Когда закончите, у вас должен остаться только текст, выровненный по левому краю, без строк длиннее 80 символов. (Argument Clinic сохранит отступы внутри docstring.)

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

Пример:
```
/*[clinic input]
Write a pickled representation of obj to the open file.
[clinic start generated code]*/
```
Если в строке документации нет строки «краткого описания», Argument Clinic выдаст предупреждение. Поэтому убедитесь, что она есть. Строка краткого описания должна представлять собой абзац из одной строки длиной до 80 символов в начале строки документации.

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

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

Write a pickled representation of obj to the open file.
[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

Write a pickled representation of obj to the open file.
[clinic start generated code]*/
```
Объявите каждый параметр функции. Каждый параметр должен быть на отдельной строке. Все строки параметров должны быть с отступом относительно имени функции и строки документации.

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

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

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

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

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

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

 /*[clinic input]
 _pickle.Pickler.dump

    obj: 'O'

Write a pickled representation of obj to the open file.
[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'
    /

Write a pickled representation of obj to the open file.
[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'
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/
```

Сохраните и закройте файл, затем запустите на нём Tools/clinic/clinic.py. Если повезёт, всё сработает, и в вашем блоке появится выходные данные! Откройте файл снова в текстовом редакторе, чтобы увидеть:

/*[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'
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[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]*/

Очевидно, если Argument Clinic не выдал никакого вывода, значит, он нашёл ошибку во входных данных. Исправляйте ошибки и повторяйте запуск, пока Argument Clinic не обработает файл без нареканий.

Перепроверьте, что сгенерированный 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'
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[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]*/
{
    /* Check whether the Pickler was initialized correctly (issue3664).
       Developers often forget to call __init__() in their subclasses, which
       would trigger a segfault without this check. */
    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}                /* sentinel */
};
```
Скомпилируйте, затем запустите соответствующие части набора регрессионных тестов. Это изменение не должно приводить к появлению новых предупреждений или ошибок во время компиляции, и не должно вызывать видимых извне изменений в поведении 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" в конец и использует его для имени impl-функции.

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

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

...

Базовая функция теперь будет называться pickler_dumper(), а impl-функция – 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-coordinate.
    y: int
      Y-coordinate.
    ]

    ch: object
      Character to add.

    [
    attr: long
      Attributes for the character.
    ]
    /

...

Примечания:

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

Использование настоящих конвертеров 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). См. раздел о значениях по умолчанию, чтобы узнать, как это использовать. Указывается в виде строки.

аннотация

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

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

bitwise

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

converter

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

encoding

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

length

Поддерживается только для строк. Если true, запрашивает передачу длины строки в impl-функцию сразу после параметра строки, в параметре с именем <parameter_name>_length.

nullable

Поддерживается только для строк. Если true, этот параметр также может быть установлен в None, и в этом случае C-параметр будет установлен в NULL.

subclass_of

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

types

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

types

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

zeroes

Поддерживается только для строк. Если true, внутри значения допускаются встроенные NUL-байты ('\\0').

Имейте в виду, что не любое сочетание аргументов будет работать. Часто эти аргументы реализованы внутри с помощью определённых PyArg_ParseTuple форматных символов с определённым поведением. Например, сейчас нельзя вызвать str и передать zeroes=True без указания encoding; хотя вполне разумно думать, что это сработает, такая семантика не соответствует ни одному существующему форматному символу. Поэтому Argument Clinic этого не поддерживает. (Или, по крайней мере, пока нет.)

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

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

В качестве примера приведём наш образец pickle.Pickler.dump, использующий правильный конвертер:

/*[clinic input]
pickle.Pickler.dump

    obj: object
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

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 возвращаемый тип – char *; возвращайте нулевой указатель для обозначения ошибки.

(Существует также экспериментальный конвертер 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

Docstring for new_function goes here.
[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
  /

Write a pickled representation of the given object to the open file.
[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
  /

Write a pickled representation of the given object to the open file.
[clinic start generated code]*/

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

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

Ваш класс конвертера должен называться *что-то*_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, когда значение по умолчанию отсутствует, но его отсутствие может привести к предупреждению «неинициализированная переменная». Это легко может произойти при использовании групп опций – хотя правильно написанный код никогда не будет использовать это значение, переменная всё равно передаётся в impl, и компилятор C будет жаловаться на «использование» неинициализированного значения. Это значение всегда должно быть непустой строкой.
converter: Имя функции-преобразователя C в виде строки.
impl_by_reference: Логическое значение. Если истинно, Argument Clinic добавит & перед именем переменной при передаче её в функцию impl.
parse_by_reference: Логическое значение. Если оно истинно, Argument Clinic добавит & перед именем переменной при передаче её в PyArg_ParseTuple().

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

/*[python input]

class uint_converter(CConverter):
    type = 'unsigned int'
    converter = 'uint_converter'

[python start generated code]*/
/*[python end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/

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

Более сложные пользовательские преобразователи могут вставлять собственный код C для инициализации и очистки. Дополнительные примеры пользовательских преобразователей можно найти в исходном коде CPython; поищите в 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 для преобразователя object для 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>" – это семантический объект (функция разбора, функция реализации, строка документации или структура methoddef), а "<b>" представляет собой тип оператора (statement). Имена полей, оканчивающиеся на "_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 file». Затем файл включается директивой #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» выше.

Подкоманда 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:...]*/