clinic.md
1> **Источник:** https://python-all.ru/3.8/howto/clinic.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Руководство по Argument Clinic89**автор**1011Larry Hastings1213Аннотация1415Argument Clinic – это препроцессор для C-файлов CPython. Его цель – автоматизировать всю шаблонную работу, связанную с написанием кода разбора аргументов для «встроенных функций». Этот документ показывает, как преобразовать первую C-функцию для работы с Argument Clinic, а затем знакомит с некоторыми продвинутыми темами по использованию Argument Clinic.1617В настоящее время Argument Clinic считается внутренним инструментом только для CPython. Его использование не поддерживается для файлов вне CPython, и никаких гарантий обратной совместимости в будущих версиях не даётся. Иными словами: если вы поддерживаете внешнее C-расширение для CPython, вы можете экспериментировать с Argument Clinic в своём коде. Но версия Argument Clinic, которая поставляется со следующей версией CPython, *может* оказаться полностью несовместимой и сломать весь ваш код.1819## Цели Argument Clinic2021Основная цель Argument Clinic – взять на себя ответственность за весь код разбора аргументов внутри CPython. Это означает, что при преобразовании функции для работы с Argument Clinic эта функция больше не должна выполнять собственный разбор аргументов – сгенерированный Argument Clinic код должен быть для вас «чёрным ящиком», где CPython вызывает его сверху, а ваш код вызывается снизу, а `PyObject *args` (и, возможно, `PyObject *kwargs`) магически преобразуются в нужные вам C-переменные и типы.2223Чтобы Argument Clinic достиг своей основной цели, он должен быть прост в использовании. Сейчас работа с библиотекой разбора аргументов CPython – это рутина, требующая поддержания избыточной информации в удивительно большом количестве мест. При использовании Argument Clinic вам не нужно повторяться.2425Очевидно, никто не захочет использовать Argument Clinic, если он не решает их проблему – и при этом не создаёт новых. Поэтому крайне важно, чтобы Argument Clinic генерировал корректный код. Было бы хорошо, если бы код был ещё и быстрее, но, по крайней мере, он не должен приводить к серьёзному снижению производительности. (В конечном итоге Argument Clinic *должен* сделать возможным значительное ускорение – мы могли бы переписать его генератор кода для создания специализированного кода разбора аргументов вместо вызова универсальной библиотеки разбора аргументов CPython. Это позволило бы добиться максимально быстрого разбора аргументов!)2627Кроме того, Argument Clinic должен быть достаточно гибким, чтобы работать с любым подходом к разбору аргументов. В Python есть функции с очень странным поведением при разборе; цель Argument Clinic – поддерживать все из них.2829Наконец, изначальной мотивацией для Argument Clinic было предоставление «сигнатур» для интроспекции встроенных функций CPython. Раньше функции запросов интроспекции выбрасывали исключение, если передать встроенную функцию. С Argument Clinic это осталось в прошлом!3031Одна идея, которую стоит помнить при работе с Argument Clinic: чем больше информации вы ему дадите, тем лучше он сможет выполнить свою работу. Argument Clinic, безусловно, сейчас относительно прост. Но по мере развития он будет становиться всё более сложным и сможет делать много интересных и умных вещей со всей предоставленной информацией.3233## Основные концепции и использование3435Argument Clinic поставляется с CPython; вы найдёте его в `Tools/clinic/clinic.py`. Если запустить этот скрипт, указав C-файл в качестве аргумента:3637```console38$ python3 Tools/clinic/clinic.py foo.c39```4041Argument Clinic будет сканировать файл в поисках строк, которые выглядят точно так же:4243```text44/*[clinic input]45```4647Когда он находит такую строку, он читает всё до строки, которая выглядит точно так же:4849```text50[clinic start generated code]*/51```5253Всё, что находится между этими двумя строками, является входными данными для Argument Clinic. Все эти строки, включая начальную и конечную строки комментариев, вместе называются «блоком» Argument Clinic.5455Когда Argument Clinic анализирует один из таких блоков, он генерирует выходные данные. Эти выходные данные перезаписываются в C-файл сразу после блока, за которыми следует комментарий с контрольной суммой. Блок Argument Clinic теперь выглядит так:5657```text58/*[clinic input]59... clinic input goes here ...60[clinic start generated code]*/61... clinic output goes here ...62/*[clinic end generated code: checksum=...]*/63```6465Если запустить Argument Clinic на том же файле повторно, он отбросит старые выходные данные и запишет новые с новой строкой контрольной суммы. Однако если входные данные не изменились, выходные данные тоже не изменятся.6667Никогда не следует изменять выходную часть блока Argument Clinic. Вместо этого меняйте входные данные, пока они не начнут давать нужный вам вывод. (В этом и заключается назначение контрольной суммы – обнаруживать, если кто-то изменил выходные данные, поскольку эти правки будут потеряны при следующей записи новых выходных данных Argument Clinic.)6869Для ясности приведём терминологию, которую мы будем использовать с Argument Clinic:7071- Первая строка комментария (`/*[clinic input]`) – это *начальная строка*.72- Последняя строка исходного комментария (`[clinic start generated code]*/`) – это *конечная строка*.73- Последняя строка (`/*[clinic end generated code: checksum=...]*/`) – это *строка контрольной суммы*.74- Между начальной строкой и конечной строкой находится *входные данные*.75- Между конечной строкой и строкой контрольной суммы находится *выходные данные*.76- Весь текст в совокупности, от начальной строки до строки контрольной суммы включительно, является *блоком*. (Блок, который ещё не был успешно обработан Argument Clinic, не имеет выходных данных или строки контрольной суммы, но всё равно считается блоком.)7778## Преобразование вашей первой функции7980Лучший способ понять, как работает Argument Clinic, – преобразовать функцию для работы с ним. Итак, ниже приведены минимальные шаги, которые необходимо выполнить для преобразования функции для работы с Argument Clinic. Обратите внимание, что для кода, который вы планируете включить в CPython, стоит пойти дальше, используя некоторые продвинутые концепции, которые вы увидите далее в документе (например, «конвертеры возврата» и «конвертеры self»). Но в этом пошаговом руководстве мы будем придерживаться простого подхода, чтобы вы могли освоиться.8182Приступим!83840. Убедитесь, что вы работаете со свежеобновлённой копией основной ветки CPython.851. Найдите встроенную функцию Python, которая вызывает либо [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple), либо [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTupleAndKeywords), и ещё не была преобразована для работы с Argument Clinic. В своём примере я использую `_pickle.Pickler.dump()`.862. Если вызов функции `PyArg_Parse` использует один из следующих форматных юнитов:8788 ```text89 O&90 O!91 es92 es#93 et94 et#95 ```9697 или если в ней несколько вызовов [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple), следует выбрать другую функцию. Argument Clinic *поддерживает* все эти сценарии. Но это продвинутые темы – для первой функции лучше сделать что-то попроще.9899 Кроме того, если функция содержит несколько вызовов [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple) или [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) с разными типами для одного и того же аргумента, или если для разбора аргументов используются не функции PyArg\_Parse, то, вероятно, она не подходит для преобразования в Argument Clinic. Argument Clinic не поддерживает обобщённые функции или полиморфные параметры.1003. Добавьте следующий шаблонный код над функцией, создав наш блок:101102 ```c103 /*[clinic input]104 [clinic start generated code]*/105 ```1064. Вырежьте строку документации и вставьте её между строками `[clinic]`, убрав всё, что делает её правильно оформленной строкой C. Когда закончите, у вас должен остаться только текст, выровненный по левому краю, без строк длиннее 80 символов. (Argument Clinic сохранит отступы внутри строки документации.)107108 Если старая строка документации содержала первую строку, похожую на сигнатуру функции, удалите её. (Она больше не нужна – когда вы в будущем будете использовать `help()` для встроенной функции, первая строка будет сгенерирована автоматически на основе сигнатуры функции.)109110 Пример:111112 ```c113 /*[clinic input]114 Записывает сериализованное представление obj в открытый файл.115 [clinic start generated code]*/116 ```1175. Если в строке документации нет строки «краткого описания», Argument Clinic выдаст предупреждение. Поэтому убедитесь, что она есть. Строка краткого описания должна представлять собой абзац из одной строки длиной до 80 символов в начале строки документации.118119 (В нашем примере строка документации состоит только из строки краткого описания, поэтому образец кода не нужно менять на этом шаге.)1206. Над строкой документации укажите имя функции, затем пустую строку. Это должно быть Python-имя функции, полный путь с точками – начиная с имени модуля, включая все подмодули, и если функция является методом класса, то также имя класса.121122 Пример:123124 ```c125 /*[clinic input]126 _pickle.Pickler.dump127128 Записывает сериализованное представление obj в открытый файл.129 [clinic start generated code]*/130 ```1317. Если этот модуль или класс впервые используются с Argument Clinic в данном C-файле, необходимо объявить модуль и/или класс. Правила гигиены Argument Clinic рекомендуют объявлять их в отдельном блоке где-нибудь ближе к началу C-файла, так же как файлы включений и статические переменные размещаются в начале. (В нашем примере мы просто покажем два блока рядом.)132133 Имя класса и модуля должно совпадать с тем, которое видит Python. Проверьте имя, определённое в [`PyModuleDef`](https://python-all.ru/3.8/c-api/module.html#c.PyModuleDef) или [`PyTypeObject`](https://python-all.ru/3.8/c-api/type.html#c.PyTypeObject), в зависимости от ситуации.134135 При объявлении класса необходимо также указать два аспекта его типа в C: объявление типа для указателя на экземпляр этого класса и указатель на [`PyTypeObject`](https://python-all.ru/3.8/c-api/type.html#c.PyTypeObject) для этого класса.136137 Пример:138139 ```c140 /*[clinic input]141 module _pickle142 class _pickle.Pickler "PicklerObject *" "&Pickler_Type"143 [clinic start generated code]*/144145 /*[clinic input]146 _pickle.Pickler.dump147148 Записывает сериализованное представление obj в открытый файл.149 [clinic start generated code]*/150 ```1518. Объявите каждый параметр функции. Каждый параметр должен быть на отдельной строке. Все строки параметров должны быть с отступом относительно имени функции и строки документации.152153 Общий вид этих строк параметров следующий:154155 ```text156 name_of_parameter: converter157 ```158159 Если у параметра есть значение по умолчанию, добавьте его после конвертера:160161 ```text162 name_of_parameter: converter = default_value163 ```164165 Поддержка значений по умолчанию в Argument Clinic довольно сложная; обратитесь к [разделу ниже о значениях по умолчанию](https://python-all.ru/3.8/howto/clinic.html#default-values) для получения дополнительной информации.166167 Добавьте пустую строку под параметрами.168169 Что такое «конвертер»? Он определяет как тип переменной, используемый в C, так и метод преобразования значения Python в значение C во время выполнения. Сейчас вы будете использовать так называемый «унаследованный конвертер» – удобный синтаксис, предназначенный для упрощения переноса старого кода в Argument Clinic.170171 Для каждого параметра скопируйте «форматный юнит» этого параметра из аргумента формата `PyArg_Parse()` и укажите *его* в качестве конвертера, в виде строки в кавычках. («Форматный юнит» – это официальное название подстроки из одного-трёх символов параметра `format`, которая сообщает функции разбора аргументов тип переменной и способ её преобразования. Подробнее о форматных юнитах см. [«Разбор аргументов и сборка значений»](https://python-all.ru/3.8/c-api/arg.html#arg-parsing).)172173 Для многозначных форматных юнитов, таких как `z#`, используйте всю строку из двух или трёх символов.174175 Пример:176177 ```c178 /*[clinic input]179 module _pickle180 class _pickle.Pickler "PicklerObject *" "&Pickler_Type"181 [clinic start generated code]*/182183 /*[clinic input]184 _pickle.Pickler.dump185186 obj: 'O'187188 Записывает сериализованное представление obj в открытый файл.189 [clinic start generated code]*/190 ```1919. Если в строке формата вашей функции есть `|`, что означает, что некоторые параметры имеют значения по умолчанию, можете игнорировать его. Argument Clinic определяет, какие параметры необязательны, на основе наличия значений по умолчанию.192193 Если в строке формата вашей функции есть `$`, что означает, что она принимает только именованные аргументы, укажите `*` на отдельной строке перед первым именованным аргументом, с отступом, как у строк параметров.194195 (У `_pickle.Pickler.dump` нет ни того, ни другого, поэтому наш образец не меняется.)19610. Если существующая C-функция вызывает [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple) (в отличие от [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTupleAndKeywords)), то все её аргументы являются только позиционными.197198 Чтобы пометить все параметры как только позиционные в Argument Clinic, добавьте `/` на отдельной строке после последнего параметра, с отступом, как у строк параметров.199200 Сейчас это работает по принципу «всё или ничего»: либо все параметры только позиционные, либо ни один. (В будущем Argument Clinic может ослабить это ограничение.)201202 Пример:203204 ```c205 /*[clinic input]206 module _pickle207 class _pickle.Pickler "PicklerObject *" "&Pickler_Type"208 [clinic start generated code]*/209210 /*[clinic input]211 _pickle.Pickler.dump212213 obj: 'O'214 /215216 Записывает сериализованное представление obj в открытый файл.217 [clinic start generated code]*/218 ```21911. Полезно писать докстринг на каждый параметр. Но такие докстринги необязательны – при желании этот шаг можно пропустить.220221 Вот как добавить докстринг для параметра. Первая строка этого докстринга должна иметь отступ больше, чем определение параметра. Левый отступ этой первой строки задаёт левый отступ для всего докстринга параметра; весь написанный текст будет сдвинут влево на эту величину. Можно писать сколько угодно текста, в том числе на нескольких строках.222223 Пример:224225 ```c226 /*[clinic input]227 module _pickle228 class _pickle.Pickler "PicklerObject *" "&Pickler_Type"229 [clinic start generated code]*/230231 /*[clinic input]232 _pickle.Pickler.dump233234 obj: 'O'235 Объект для сериализации.236 /237238 Записывает сериализованное представление obj в открытый файл.239 [clinic start generated code]*/240 ```24112. Сохраните и закройте файл, затем запустите на нём `Tools/clinic/clinic.py`. Если повезёт, всё сработало – теперь у вашего блока есть вывод, а также сгенерирован файл `.c.h`! Снова откройте файл в текстовом редакторе, чтобы увидеть:242243 ```c244 /*[clinic input]245 _pickle.Pickler.dump246247 obj: 'O'248 Объект для сериализации.249 /250251 Записывает сериализованное представление obj в открытый файл.252 [clinic start generated code]*/253254 static PyObject *255 _pickle_Pickler_dump(PicklerObject *self, PyObject *obj)256 /*[clinic end generated code: output=87ecad1261e02ac7 input=552eb1c0f52260d9]*/257 ```258259 Очевидно, если Argument Clinic не выдал никакого вывода, значит, он нашёл ошибку во входных данных. Исправляйте ошибки и повторяйте запуск, пока Argument Clinic не обработает файл без нареканий.260261 Для удобства чтения большая часть связующего кода сгенерирована в файл `.c.h`. Этот файл нужно включить в исходный файл `.c`, как правило, сразу после блока модуля clinic:262263 ```c264 #include "clinic/_pickle.c.h"265 ```26613. Перепроверьте, что сгенерированный Argument Clinic код разбора аргументов в основном совпадает с существующим кодом.267268 Во-первых, убедитесь, что в обоих местах используется одна и та же функция разбора аргументов. Существующий код должен вызывать либо [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple), либо [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTupleAndKeywords); добейтесь, чтобы код, сгенерированный Argument Clinic, вызывал *ту же самую* функцию.269270 Во-вторых, строка формата, передаваемая в [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple) или [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTupleAndKeywords), должна быть *в точности* такой же, как написанная вручную в существующей функции, вплоть до двоеточия или точки с запятой.271272 (Argument Clinic всегда генерирует строки формата с `:`, за которым следует имя функции. Если строка формата существующего кода заканчивается на `;` для вывода справки по использованию, это изменение безвредно – не беспокойтесь об этом.)273274 В-третьих, для параметров, единицы формата которых требуют двух аргументов (например, переменная длины, строка кодировки или указатель на функцию преобразования), убедитесь, что второй аргумент *в точности* одинаков в обоих вызовах.275276 В-четвёртых, внутри выходной части блока вы найдёте макрос препроцессора, определяющий соответствующую статическую структуру [`PyMethodDef`](https://python-all.ru/3.8/c-api/structures.html#c.PyMethodDef) для этой встроенной функции:277278 ```c279 #define __PICKLE_PICKLER_DUMP_METHODDEF \280 {"dump", (PyCFunction)__pickle_Pickler_dump, METH_O, __pickle_Pickler_dump__doc__},281 ```282283 Эта статическая структура должна быть *в точности* такой же, как существующая статическая структура [`PyMethodDef`](https://python-all.ru/3.8/c-api/structures.html#c.PyMethodDef) для этой встроенной функции.284285 Если какой-либо из этих элементов *хоть в чём-то* отличается, измените спецификацию функции в Argument Clinic и повторно запустите `Tools/clinic/clinic.py`, пока они не *станут* одинаковыми.28614. Обратите внимание, что последняя строка вывода – это объявление вашей функции «impl». Сюда помещается реализация встроенной функции. Удалите существующий прототип изменяемой функции, но оставьте открывающую фигурную скобку. Затем удалите код разбора её аргументов и объявления всех переменных, в которые они помещались. Обратите внимание, что аргументы Python теперь стали аргументами этой функции impl; если в реализации использовались другие имена для этих переменных, исправьте это.287288 Повторим ещё раз, просто потому что это необычно. Теперь ваш код должен выглядеть так:289290 ```c291 static return_type292 your_function_impl(...)293 /*[clinic end generated code: checksum=...]*/294 {295 ...296 ```297298 Argument Clinic сгенерировал строку контрольной суммы и прототип функции прямо над ней. Вам нужно написать открывающую (и закрывающую) фигурные скобки для функции и реализацию внутри.299300 Пример:301302 ```c303 /*[clinic input]304 module _pickle305 class _pickle.Pickler "PicklerObject *" "&Pickler_Type"306 [clinic start generated code]*/307 /*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/308309 /*[clinic input]310 _pickle.Pickler.dump311312 obj: 'O'313 Объект для сериализации.314 /315316 Записывает сериализованное представление obj в открытый файл.317 [clinic start generated code]*/318319 PyDoc_STRVAR(__pickle_Pickler_dump__doc__,320 "Write a pickled representation of obj to the open file.\n"321 "\n"322 ...323 static PyObject *324 _pickle_Pickler_dump_impl(PicklerObject *self, PyObject *obj)325 /*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/326 {327 /* Проверяет, был ли Pickler инициализирован корректно (issue3664).328 Разработчики часто забывают вызывать __init__() в своих подклассах, что329 привело бы к segfault без этой проверки. */330 if (self->write == NULL) {331 PyErr_Format(PicklingError,332 "Pickler.__init__() was not called by %s.__init__()",333 Py_TYPE(self)->tp_name);334 return NULL;335 }336337 if (_Pickler_ClearBuffer(self) < 0)338 return NULL;339340 ...341 ```34215. Помните макрос со структурой [`PyMethodDef`](https://python-all.ru/3.8/c-api/structures.html#c.PyMethodDef) для этой функции? Найдите существующую структуру [`PyMethodDef`](https://python-all.ru/3.8/c-api/structures.html#c.PyMethodDef) для этой функции и замените её ссылкой на макрос. (Если встроенная функция находится на уровне модуля, это, скорее всего, будет почти в конце файла; если это метод класса, то, вероятно, ниже, но относительно рядом с реализацией.)343344 Обратите внимание, что тело макроса содержит завершающую запятую. Поэтому при замене существующей статической структуры [`PyMethodDef`](https://python-all.ru/3.8/c-api/structures.html#c.PyMethodDef) на макрос *не* добавляйте запятую в конце.345346 Пример:347348 ```c349 static struct PyMethodDef Pickler_methods[] = {350 __PICKLE_PICKLER_DUMP_METHODDEF351 __PICKLE_PICKLER_CLEAR_MEMO_METHODDEF352 {NULL, NULL} /* сторожевое значение */353 };354 ```35516. Скомпилируйте, затем запустите соответствующие части набора регрессионных тестов. Это изменение не должно приводить к появлению новых предупреждений или ошибок во время компиляции, и не должно вызывать видимых извне изменений в поведении Python.356357 Ну, за одним исключением: `inspect.signature()`, запущенная на вашей функции, теперь должна выдавать корректную сигнатуру!358359 Поздравляем, вы портировали свою первую функцию для работы с Argument Clinic!360361## Продвинутые темы362363Теперь, когда у вас есть некоторый опыт работы с Argument Clinic, пора перейти к продвинутым темам.364365### Символические значения по умолчанию366367Значение по умолчанию для параметра не может быть произвольным выражением. В настоящее время явно поддерживаются следующие:368369- Числовые константы (целые и с плавающей запятой)370- Строковые константы371- `True`, `False` и `None`372- Простые символические константы, такие как `sys.maxsize`, должны начинаться с имени модуля373374Если вам интересно, это реализовано в `from_builtin()` в `Lib/inspect.py`.375376(В будущем это может потребовать ещё большей доработки, чтобы разрешить полноценные выражения вроде `CONSTANT - 1`.)377378### Переименование C-функций и переменных, сгенерированных Argument Clinic379380Argument Clinic автоматически присваивает имена сгенерированным функциям. Иногда это может вызывать проблему, если сгенерированное имя совпадает с именем существующей C-функции. Есть простое решение: переопределите имена, используемые для C-функций. Просто добавьте ключевое слово `"as"` в строку объявления функции, а затем укажите желаемое имя функции. Argument Clinic будет использовать это имя для базовой (сгенерированной) функции, после чего добавит `"_impl"` в конец и будет использовать его для имени функции реализации.381382Например, если бы мы захотели переименовать C-функции, сгенерированные для `pickle.Pickler.dump`, это выглядело бы так:383384```c385/*[clinic input]386pickle.Pickler.dump as pickler_dumper387388...389```390391Теперь базовая функция будет называться `pickler_dumper()`, а функция реализации – `pickler_dumper_impl()`.392393Аналогично, может возникнуть ситуация, когда нужно дать параметру конкретное имя Python, но это имя может быть неудобным в C. Argument Clinic позволяет задать параметру разные имена в Python и C, используя тот же синтаксис `"as"`:394395```c396/*[clinic input]397pickle.Pickler.dump398399 obj: object400 file as file_obj: object401 протокол: object = NULL402 *403 fix_imports: bool = True404```405406Здесь имя, используемое в Python (в сигнатуре и массиве `keywords`), будет `file`, а C-переменная будет называться `file_obj`.407408Это можно использовать и для переименования параметра `self`!409410### Преобразование функций, использующих PyArg\_UnpackTuple411412Чтобы преобразовать функцию, которая разбирает свои аргументы с помощью [`PyArg_UnpackTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_UnpackTuple), просто перечислите все аргументы, указав каждый как `object`. Можно указать аргумент `type` для приведения типа по необходимости. Все аргументы должны быть помечены как только позиционные (добавьте `/` на отдельной строке после последнего аргумента).413414Сейчас сгенерированный код будет использовать [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple), но это скоро изменится.415416### Опциональные группы417418Некоторые устаревшие функции используют хитрый подход к разбору своих аргументов: они подсчитывают количество позиционных аргументов, затем с помощью оператора `switch` вызывают один из нескольких разных вызовов [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple) в зависимости от количества позиционных аргументов. (Эти функции не могут принимать только ключевые аргументы.) Этот подход использовался для имитации опциональных аргументов до того, как был создан [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTupleAndKeywords).419420Хотя функции, использующие этот подход, часто можно преобразовать для использования [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTupleAndKeywords), опциональных аргументов и значений по умолчанию, это не всегда возможно. Некоторые из этих устаревших функций имеют поведение, которое [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) напрямую не поддерживает. Самый очевидный пример – встроенная функция `range()`, у которой есть опциональный аргумент с *левой* стороны от обязательного аргумента! Другой пример – `curses.window.addch()`, у которой есть группа из двух аргументов, которые всегда должны указываться вместе. (Аргументы называются `x` и `y`; если вы вызываете функцию, передавая `x`, вы также должны передать `y` – а если вы не передаёте `x`, то нельзя передавать и `y`.)421422В любом случае, цель Argument Clinic – поддерживать разбор аргументов для всех существующих встроенных функций CPython без изменения их семантики. Поэтому Argument Clinic поддерживает этот альтернативный подход к разбору, используя так называемые *опциональные группы*. Опциональные группы – это группы аргументов, которые должны передаваться вместе. Они могут находиться слева или справа от обязательных аргументов. Их можно использовать *только* с только позиционными параметрами.423424> **Примечание**425>426> Опциональные группы *предназначены только* для использования при преобразовании функций, которые выполняют несколько вызовов [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple)! Функции, использующие *любой другой* подход для разбора аргументов, *почти никогда* не должны преобразовываться в Argument Clinic с использованием опциональных групп. Функции, использующие опциональные группы, в настоящее время не могут иметь точные сигнатуры в Python, потому что Python просто не понимает эту концепцию. Пожалуйста, по возможности избегайте использования опциональных групп.427428Чтобы указать опциональную группу, добавьте `[` на отдельной строке перед параметрами, которые нужно сгруппировать, и `]` на отдельной строке после этих параметров. В качестве примера, вот как `curses.window.addch` использует опциональные группы, чтобы сделать первые два параметра и последний параметр опциональными:429430```c431/*[clinic input]432433curses.window.addch434435 [436 x: int437 Координата X.438 y: int439 Координата Y.440 ]441442 ch: object443 Добавляемый символ.444445 [446 attr: long447 Атрибуты для символа.448 ]449 /450451...452```453454Примечания:455456- Для каждой опциональной группы в функцию реализации будет передан один дополнительный параметр, представляющий группу. Параметр будет иметь тип int и имя `group_{direction}_{number}`, где `{direction}` – это либо `right`, либо `left` в зависимости от того, находится ли группа до или после обязательных параметров, а `{number}` – монотонно возрастающее число (начиная с 1), указывающее, насколько далеко группа находится от обязательных параметров. Когда вызывается функция реализации, этот параметр будет установлен в ноль, если группа не использовалась, и в ненулевое значение, если группа использовалась. (Под использованием или неиспользованием я имею в виду, получили ли параметры аргументы в этом вызове.)457- Если обязательных аргументов нет, опциональные группы будут вести себя так, как если бы они находились справа от обязательных аргументов.458- В случае неоднозначности код разбора аргументов отдаёт предпочтение параметрам слева (перед обязательными параметрами).459- Опциональные группы могут содержать только позиционные параметры.460- Опциональные группы *предназначены только* для устаревшего кода. Пожалуйста, не используйте опциональные группы в новом коде.461462### Использование настоящих конвертеров Argument Clinic вместо «устаревших конвертеров»463464Чтобы сэкономить время и минимизировать объём знаний, необходимых для первого переноса кода на Argument Clinic, в приведённом выше пошаговом руководстве рекомендуется использовать «устаревшие конвертеры». «Устаревшие конвертеры» – это удобство, созданное специально для упрощения переноса существующего кода на Argument Clinic. И, чтобы было понятно, их использование допустимо при переносе кода для Python 3.4.465466Однако в долгосрочной перспективе, вероятно, желательно, чтобы все наши блоки использовали настоящий синтаксис конвертеров Argument Clinic. Почему? Несколько причин:467468- Правильные конвертеры гораздо легче читать, и их назначение понятнее.469- Существуют некоторые форматные единицы, которые не поддерживаются в качестве «устаревших конвертеров», поскольку они требуют аргументов, а синтаксис устаревших конвертеров не поддерживает указание аргументов.470- В будущем у нас может появиться новая библиотека для разбора аргументов, которая не будет ограничена тем, что поддерживает [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple); эта гибкость не будет доступна параметрам, использующим устаревшие конвертеры.471472Поэтому, если вы не против небольшого дополнительного усилия, пожалуйста, используйте обычные конвертеры вместо устаревших.473474В двух словах, синтаксис (неустаревших) конвертеров Argument Clinic выглядит как вызов функции Python. Однако, если у функции нет явных аргументов (все функции принимают свои значения по умолчанию), скобки можно опустить. Таким образом, `bool` и `bool()` – это абсолютно одинаковые конвертеры.475476Все аргументы конвертеров Argument Clinic являются только ключевыми (keyword-only). Все конвертеры Argument Clinic принимают следующие аргументы:477478> **`c_default`**479>480> Значение по умолчанию для этого параметра при определении в C. А именно, это будет инициализатор переменной, объявленной в «функции разбора» (parse function). См. [раздел о значениях по умолчанию](https://python-all.ru/3.8/howto/clinic.html#default-values), чтобы узнать, как это использовать. Указывается в виде строки.481>482> **`annotation`**483>484> Значение аннотации для этого параметра. В настоящее время не поддерживается, поскольку [**PEP 8**](https://python-all.ru/3.8/howto/clinic.html) предписывает, что библиотека Python не должна использовать аннотации.485486Кроме того, некоторые конвертеры принимают дополнительные аргументы. Вот список этих аргументов с их значениями:487488> **`accept`**489>490> Набор типов Python (и, возможно, псевдотипов); это ограничивает допустимые аргументы Python значениями этих типов. (Это не универсальный механизм; как правило, он поддерживает только конкретные списки типов, как показано в таблице устаревших конвертеров.)491>492> Чтобы принимать `None`, добавьте `NoneType` в этот набор.493>494> **`bitwise`**495>496> Поддерживается только для беззнаковых целых чисел. Собственное целочисленное значение этого аргумента Python будет записано в параметр без какой-либо проверки диапазона, даже для отрицательных значений.497>498> **`converter`**499>500> Поддерживается только конвертером `object`. Указывает имя [C-«функции-конвертера»](https://python-all.ru/3.8/c-api/arg.html#o-ampersand), используемой для преобразования этого объекта в собственный тип.501>502> **`encoding`**503>504> Поддерживается только для строк. Указывает кодировку, используемую при преобразовании этой строки из значения Python str (Unicode) в значение C `char *`.505>506> **`subclass_of`**507>508> Поддерживается только для конвертера `object`. Требует, чтобы значение Python было подклассом типа Python, как это выражается в C.509>510> **`type`**511>512> Поддерживается только для конвертеров `object` и `self`. Указывает тип C, который будет использоваться для объявления переменной. Значение по умолчанию: `"PyObject *"`.513>514> **`zeroes`**515>516> Поддерживается только для строк. Если true, внутри значения допускаются встроенные NUL-байты (`'\\0'`). Длина строки будет передана в функцию impl сразу после строкового параметра как параметр с именем `<parameter_name>_length`.517518Пожалуйста, учтите: не любая комбинация аргументов будет работать. Обычно эти аргументы реализуются конкретными `PyArg_ParseTuple` *форматными единицами* с определённым поведением. Например, в настоящее время нельзя вызвать `unsigned_short`, не указав также `bitwise=True`. Хотя вполне разумно предположить, что это сработает, такая семантика не соответствует ни одной существующей форматной единице. Поэтому Argument Clinic это не поддерживает (или, по крайней мере, пока нет).519520Ниже приведена таблица, показывающая соответствие устаревших конвертеров настоящим конвертерам Argument Clinic. Слева – устаревший конвертер, справа – текст, на который его следует заменить.521522| `'B'` | `unsigned_char(bitwise=True)` |523| --- | --- |524| `'b'` | `unsigned_char` |525| `'c'` | `char` |526| `'C'` | `int(accept={str})` |527| `'d'` | `double` |528| `'D'` | `Py_complex` |529| `'es'` | `str(encoding='name_of_encoding')` |530| `'es#'` | `str(encoding='name_of_encoding', zeroes=True)` |531| `'et'` | `str(encoding='name_of_encoding', accept={bytes, bytearray, str})` |532| `'et#'` | `str(encoding='name_of_encoding', accept={bytes, bytearray, str}, zeroes=True)` |533| `'f'` | `float` |534| `'h'` | `short` |535| `'H'` | `unsigned_short(bitwise=True)` |536| `'i'` | `int` |537| `'I'` | `unsigned_int(bitwise=True)` |538| `'k'` | `unsigned_long(bitwise=True)` |539| `'K'` | `unsigned_long_long(bitwise=True)` |540| `'l'` | `long` |541| `'L'` | `long long` |542| `'n'` | `Py_ssize_t` |543| `'O'` | `object` |544| `'O!'` | `object(subclass_of='&PySomething_Type')` |545| `'O&'` | `object(converter='name_of_c_function')` |546| `'p'` | `bool` |547| `'S'` | `PyBytesObject` |548| `'s'` | `str` |549| `'s#'` | `str(zeroes=True)` |550| `'s*'` | `Py_buffer(accept={buffer, str})` |551| `'U'` | `unicode` |552| `'u'` | `Py_UNICODE` |553| `'u#'` | `Py_UNICODE(zeroes=True)` |554| `'w*'` | `Py_buffer(accept={rwbuffer})` |555| `'Y'` | `PyByteArrayObject` |556| `'y'` | `str(accept={bytes})` |557| `'y#'` | `str(accept={robuffer}, zeroes=True)` |558| `'y*'` | `Py_buffer` |559| `'Z'` | `Py_UNICODE(accept={str, NoneType})` |560| `'Z#'` | `Py_UNICODE(accept={str, NoneType}, zeroes=True)` |561| `'z'` | `str(accept={str, NoneType})` |562| `'z#'` | `str(accept={str, NoneType}, zeroes=True)` |563| `'z*'` | `Py_buffer(accept={buffer, str, NoneType})` |564565В качестве примера – наш образец `pickle.Pickler.dump` с использованием правильного конвертера:566567```c568/*[clinic input]569pickle.Pickler.dump570571 obj: object572 Объект для сериализации.573 /574575Записывает сериализованное представление obj в открытый файл.576[clinic start generated code]*/577```578579Одно из преимуществ настоящих конвертеров – они более гибкие, чем устаревшие. Например, конвертер `unsigned_int` (и все конвертеры `unsigned_`) можно указать без `bitwise=True`. Их поведение по умолчанию выполняет проверку диапазона значения, и они не принимают отрицательные числа. С устаревшим конвертером так не получится!580581Argument Clinic покажет все доступные конвертеры. Для каждого конвертера будут показаны все принимаемые параметры и значения по умолчанию. Просто запустите `Tools/clinic/clinic.py --converters`, чтобы увидеть полный список.582583### Py\_buffer584585При использовании конвертера `Py_buffer` (или устаревших конвертеров `'s*'`, `'w*'`, `'*y'`, `'z*'`) *не* вызывайте [`PyBuffer_Release()`](https://python-all.ru/3.8/c-api/buffer.html#c.PyBuffer_Release) для предоставленного буфера. Argument Clinic генерирует код, который делает это за вас (в функции разбора).586587### Продвинутые конвертеры588589Помните те форматные единицы, которые вы пропустили в первый раз, потому что они были сложными? Вот как с ними работать.590591Секрет в том, что все эти форматные единицы принимают аргументы – либо функции преобразования, либо типы, либо строки с указанием кодировки. (Но «устаревшие конвертеры» не поддерживают аргументы. Поэтому мы пропустили их для вашей первой функции.) Аргумент, который вы указывали для форматной единицы, теперь является аргументом конвертера; этот аргумент может быть `converter` (для `O&`), `subclass_of` (для `O!`) или `encoding` (для всех форматных единиц, начинающихся с `e`).592593При использовании `subclass_of` вы также можете использовать другой пользовательский аргумент для `object()`: `type`, который позволяет задать фактический тип, используемый для параметра. Например, если вы хотите гарантировать, что объект является подклассом `PyUnicode_Type`, вероятно, стоит использовать конвертер `object(type='PyUnicodeObject *', subclass_of='&PyUnicode_Type')`.594595Одна из возможных проблем при использовании Argument Clinic: он лишает некоторой гибкости форматные единицы, начинающиеся с `e`. При написании вызова `PyArg_Parse` вручную можно было теоретически на этапе выполнения решить, какую строку кодировки передать в [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple). Но теперь эта строка должна быть жестко задана на этапе предварительной обработки Argument Clinic. Это ограничение намеренное: оно значительно упростило поддержку этой форматной единицы и может позволить будущие оптимизации. Такое ограничение не кажется необоснованным; сам CPython всегда передает статические жестко заданные строки кодировки для параметров, чьи форматные единицы начинаются с `e`.596597### Значения по умолчанию параметров598599Значения по умолчанию параметров могут быть различными. В простейшем случае это могут быть строковые, целочисленные литералы или литералы с плавающей точкой:600601```text602foo: str = "abc"603bar: int = 123604bat: float = 45.6605```606607Также могут использоваться любые встроенные константы Python:608609```text610yep: bool = True611nope: bool = False612nada: object = None613```614615Также есть специальная поддержка значения по умолчанию `NULL` и простых выражений, описанная в следующих разделах.616617### Значение по умолчанию `NULL`618619Для строковых параметров и параметров-объектов можно установить их в `None`, чтобы указать отсутствие значения по умолчанию. Однако это означает, что переменная C будет инициализирована значением `Py_None`. Для удобства существует специальное значение `NULL` как раз для этого: с точки зрения Python оно ведёт себя как значение по умолчанию `None`, но переменная C инициализируется значением `NULL`.620621### Выражения, задаваемые как значения по умолчанию622623Значение по умолчанию для параметра может быть не просто литералом. Это может быть целое выражение, использующее математические операторы и обращающееся к атрибутам объектов. Однако эта поддержка не совсем проста из-за некоторых неочевидных семантических нюансов.624625Рассмотрим следующий пример:626627```text628foo: Py_ssize_t = sys.maxsize - 1629```630631`sys.maxsize` может принимать разные значения на разных платформах. Поэтому Argument Clinic не может просто вычислить это выражение локально и жёстко закодировать его в C. Вместо этого он сохраняет значение по умолчанию так, чтобы оно вычислялось во время выполнения, когда пользователь запрашивает сигнатуру функции.632633Какое пространство имён доступно при вычислении выражения? Оно вычисляется в контексте модуля, из которого происходит встроенная функция. Поэтому, если в модуле есть атрибут с именем «`max_widgets`», его можно просто использовать:634635```text636foo: Py_ssize_t = max_widgets637```638639Если символ не найден в текущем модуле, поиск продолжается в `sys.modules`. Именно так, например, можно найти `sys.maxsize`. (Поскольку заранее неизвестно, какие модули пользователь загрузит в интерпретатор, лучше ограничиться модулями, которые предварительно загружает сам Python.)640641Вычисление значений по умолчанию только во время выполнения означает, что Argument Clinic не может вычислить правильное эквивалентное значение C по умолчанию. Поэтому необходимо указать его явно. При использовании выражения нужно также указать эквивалентное выражение на C с помощью параметра `c_default` конвертера:642643```text644foo: Py_ssize_t(c_default="PY_SSIZE_T_MAX - 1") = sys.maxsize - 1645```646647Ещё одно осложнение: Argument Clinic не может заранее узнать, является ли предоставленное выражение корректным. Он разбирает его, чтобы убедиться, что оно выглядит допустимым, но не может *на самом деле* знать. Нужно быть очень осторожным при использовании выражений для указания значений, которые гарантированно будут корректными во время выполнения!648649Наконец, поскольку выражения должны быть представимы как статические значения C, на допустимые выражения накладывается много ограничений. Вот список возможностей Python, которые использовать запрещено:650651- Вызовы функций.652- Условные выражения (`3 if foo else 5`).653- Автоматическая распаковка последовательностей (`*[1, 2, 3]`).654- Генераторы списков, множеств, словарей и выражения-генераторы.655- Литералы кортежей, списков, множеств, словарей.656657### Использование конвертера возвращаемого значения658659По умолчанию функция impl, генерируемая Argument Clinic, возвращает `PyObject *`. Но C-функция часто вычисляет некоторый тип C, а затем преобразует его в `PyObject *` в последний момент. Argument Clinic занимается преобразованием входных данных из типов Python в нативные типы C – почему бы не поручить ему также преобразование возвращаемого значения из нативного типа C в тип Python?660661Именно это и делает «конвертер возвращаемого значения». Он изменяет функцию impl так, чтобы она возвращала некоторый тип C, а затем добавляет код в сгенерированную (не-impl) функцию для преобразования этого значения в соответствующий `PyObject *`.662663Синтаксис конвертеров возвращаемого значения аналогичен синтаксису конвертеров параметров. Конвертер возвращаемого значения указывается как аннотация возврата самой функции. Конвертеры возвращаемого значения ведут себя почти так же, как конвертеры параметров: они принимают аргументы, все аргументы являются только ключевыми, и если ни один из аргументов по умолчанию не изменяется, скобки можно опустить.664665(Если используются и `"as"`, *и* конвертер возвращаемого значения для функции, то `"as"` должен идти перед конвертером возвращаемого значения.)666667При использовании конвертеров возвращаемого значения есть ещё одно осложнение: как указать, что произошла ошибка? Обычно функция возвращает корректный (не `NULL`) указатель при успехе и `NULL` при неудаче. Но если используется целочисленный конвертер возвращаемого значения, все целые числа являются корректными. Как Argument Clinic может обнаружить ошибку? Его решение: каждый конвертер возвращаемого значения неявно ищет специальное значение, указывающее на ошибку. Если возвращается это значение и ошибка была установлена (`PyErr_Occurred()` возвращает истинное значение), то сгенерированный код распространит ошибку. В противном случае он закодирует возвращённое значение как обычно.668669В настоящее время Argument Clinic поддерживает лишь несколько конвертеров возвращаемого значения:670671```text672bool673int674unsigned int675long676unsigned int677size_t678Py_ssize_t679float680double681DecodeFSDefault682```683684Ни один из них не принимает параметров. Для первых трёх возвращайте -1 для указания ошибки. Для `DecodeFSDefault` тип возвращаемого значения – `const char *`; возвращайте нулевой `NULL` указатель, чтобы указать на ошибку.685686(Существует также экспериментальный конвертер `NoneType`, который позволяет возвращать `Py_None` при успехе или `NULL` при неудаче, без необходимости увеличивать счётчик ссылок на `Py_None`. Не уверен, что он добавляет достаточно ясности, чтобы его стоило использовать.)687688Чтобы увидеть все конвертеры возвращаемого значения, поддерживаемые Argument Clinic, вместе с их параметрами (если они есть), просто запустите `Tools/clinic/clinic.py --converters` для получения полного списка.689690### Клонирование существующих функций691692Если есть несколько функций, которые выглядят похоже, можно воспользоваться функцией «клонирования» в Clinic. При клонировании существующей функции повторно используются:693694- её параметры, включая695696 - их имена,697 - их конвертеры, со всеми параметрами,698 - их значения по умолчанию,699 - их документирующие строки для каждого параметра,700 - их *вид* (являются ли они только позиционными, позиционными или ключевыми, или только ключевыми), и701- её конвертер возвращаемого значения.702703Единственное, что не копируется из исходной функции, – это её документирующая строка; синтаксис позволяет указать новую документирующую строку.704705Вот синтаксис клонирования функции:706707```c708/*[clinic input]709module.class.new_function [as c_basename] = module.class.existing_function710711Докстринг для new_function.712[clinic start generated code]*/713```714715(Функции могут находиться в разных модулях или классах. Я написал `module.class` в примере просто для иллюстрации того, что необходимо использовать полный путь к *обеим* функциям.)716717К сожалению, нет синтаксиса для частичного клонирования функции или клонирования функции с последующим её изменением. Клонирование – это принцип «всё или ничего».718719Также функция, с которой производится клонирование, должна быть ранее определена в текущем файле.720721### Вызов кода Python722723Для остальных продвинутых тем требуется написать код Python, который находится внутри C-файла и изменяет состояние времени выполнения Argument Clinic. Это просто: нужно всего лишь определить блок Python.724725Блок Python использует другие строки-разделители, нежели блок функции Argument Clinic. Выглядит это так:726727```c728/*[python input]729# Сюда помещается код Python.730[python start generated code]*/731```732733Весь код внутри блока Python выполняется в момент его разбора. Весь текст, выводимый в stdout внутри блока, перенаправляется в «вывод» после блока.734735В качестве примера приведён блок Python, который добавляет статическую целочисленную переменную в код C:736737```c738/*[python input]739print('static int __ignored_unused_variable__ = 0;')740[python start generated code]*/741static int __ignored_unused_variable__ = 0;742/*[python checksum:...]*/743```744745### Использование «конвертера self»746747Argument Clinic автоматически добавляет параметр «self» с помощью конвертера по умолчанию. Он автоматически устанавливает `type` этого параметра на «указатель на экземпляр», указанный вами при объявлении типа. Однако вы можете переопределить конвертер Argument Clinic и указать свой собственный. Просто добавьте собственный параметр `self` в качестве первого параметра в блоке и убедитесь, что его конвертер является экземпляром `self_converter` или его подкласса.748749В чём смысл? Это позволяет переопределить тип `self` или задать ему другое имя по умолчанию.750751Как указать пользовательский тип, к которому нужно привести `self`? Если у вас всего одна или две функции с одинаковым типом для `self`, можно напрямую использовать существующий конвертер `self` в Argument Clinic, передав нужный тип в качестве параметра `type`:752753```c754/*[clinic input]755756_pickle.Pickler.dump757758 self: self(type="PicklerObject *")759 obj: object760 /761762Записывает сериализованное представление данного объекта в открытый файл.763[clinic start generated code]*/764```765766С другой стороны, если у вас много функций, использующих один и тот же тип для `self`, лучше создать свой собственный конвертер, унаследовав его от `self_converter`, но переопределив член `type`:767768```c769/*[python input]770class PicklerObject_converter(self_converter):771 type = "PicklerObject *"772[python start generated code]*/773774/*[clinic input]775776_pickle.Pickler.dump777778 self: PicklerObject779 obj: object780 /781782Записывает сериализованное представление данного объекта в открытый файл.783[clinic start generated code]*/784```785786### Создание пользовательского конвертера787788Как мы намекнули в предыдущем разделе… вы можете писать свои собственные конвертеры! Конвертер – это просто класс Python, наследующий от `CConverter`. Основная цель пользовательского конвертера – наличие параметра, использующего единицу формата `O&` – разбор этого параметра означает вызов функции-конвертера [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple).789790Ваш класс конвертера должен называться `*something*_converter`. Если имя соответствует этому соглашению, класс конвертера будет автоматически зарегистрирован в Argument Clinic; его именем станет имя вашего класса без суффикса `_converter`. (Это достигается с помощью метакласса.)791792Не следует наследовать `CConverter.__init__`. Вместо этого нужно написать функцию `converter_init()`. `converter_init()` всегда принимает параметр `self`; после этого все дополнительные параметры *должны* быть только ключевыми. Любые аргументы, переданные конвертеру в Argument Clinic, будут переданы вашей `converter_init()`.793794Существуют некоторые дополнительные члены `CConverter`, которые вы, возможно, захотите указать в вашем подклассе. Вот текущий список:795796**`type`**797798Тип C, используемый для этой переменной. `type` должен быть строкой Python, задающей тип, например, `int`. Если это тип указателя, строка типа должна заканчиваться на `' *'`.799800**`default`**801802Значение по умолчанию для этого параметра в Python, в виде значения Python. Или магическое значение `unspecified`, если значения по умолчанию нет.803804**`py_default`**805806`default` в том виде, в котором он должен отображаться в коде Python, в виде строки. Или `None`, если значения по умолчанию нет.807808**`c_default`**809810`default` в том виде, в котором он должен отображаться в коде C, в виде строки. Или `None`, если значения по умолчанию нет.811812**`c_ignored_default`**813814Значение по умолчанию, используемое для инициализации переменной C, если значение по умолчанию не задано. Однако отсутствие значения по умолчанию может привести к предупреждению о «неинициализированной переменной». Это может легко произойти при использовании групп опций – хотя корректно написанный код никогда не будет использовать это значение, переменная всё равно передаётся в функцию impl, и компилятор C выдаст предупреждение об «использовании» неинициализированного значения. Это значение всегда должно быть непустой строкой.815816**`converter`**817818Имя функции-преобразователя C в виде строки.819820**`impl_by_reference`**821822Логическое значение. Если истинно, Argument Clinic добавит `&` перед именем переменной при передаче её в функцию impl.823824**`parse_by_reference`**825826Логическое значение. Если истинно, Argument Clinic добавит `&` перед именем переменной при передаче её в [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple).827828Вот простейший пример пользовательского преобразователя из `Modules/zlibmodule.c`:829830```c831/*[python input]832833class ssize_t_converter(CConverter):834 type = 'Py_ssize_t'835 converter = 'ssize_t_converter'836837[python start generated code]*/838/*[python end generated code: output=da39a3ee5e6b4b0d input=35521e4e733823c7]*/839```840841Этот блок добавляет в Argument Clinic преобразователь с именем `ssize_t`. Параметры, объявленные как `ssize_t`, будут объявлены как тип `Py_ssize_t` и будут разобраны форматным элементом `'O&'`, который вызовет функцию-преобразователь `ssize_t_converter`. Переменные `ssize_t` автоматически поддерживают значения по умолчанию.842843Более сложные пользовательские преобразователи могут вставлять собственный код C для обработки инициализации и очистки. Дополнительные примеры пользовательских преобразователей можно найти в исходном коде CPython; выполните grep по файлам C для строки `CConverter`.844845### Написание пользовательского преобразователя возвращаемого значения846847Написание пользовательского преобразователя возвращаемого значения во многом похоже на написание обычного пользовательского преобразователя, только несколько проще, потому что сами преобразователи возвращаемых значений намного проще.848849Преобразователи возвращаемых значений должны быть подклассами `CReturnConverter`. Примеров пользовательских преобразователей возвращаемых значений пока нет, поскольку они ещё не получили широкого распространения. Если вы хотите написать свой собственный преобразователь возвращаемого значения, прочтите `Tools/clinic/clinic.py`, в частности реализацию `CReturnConverter` и всех его подклассов.850851### METH\_O и METH\_NOARGS852853Чтобы преобразовать функцию, использующую `METH_O`, убедитесь, что её единственный аргумент использует преобразователь `object`, и пометьте аргументы как позиционные:854855```c856/*[clinic input]857meth_o_sample858859 argument: object860 /861[clinic start generated code]*/862```863864Чтобы преобразовать функцию, использующую `METH_NOARGS`, просто не указывайте никаких аргументов.865866По-прежнему можно использовать преобразователь self, преобразователь возвращаемого значения и указать аргумент `type` для преобразователя объекта `METH_O`.867868### Функции tp\_new и tp\_init869870Вы можете преобразовывать функции `tp_new` и `tp_init`. Просто назовите их `__new__` или `__init__` соответственно. Примечания:871872- Сгенерированное имя функции для `__new__` не заканчивается на `__new__`, как было бы по умолчанию. Это просто имя класса, преобразованное в корректный идентификатор C.873- Для этих функций не генерируется `PyMethodDef` `#define`.874- Функции `__init__` возвращают `int`, а не `PyObject *`.875- Используйте строку документации как строку документации класса.876- Хотя функции `__new__` и `__init__` всегда должны принимать оба объекта `args` и `kwargs`, при преобразовании вы можете указать для этих функций любую сигнатуру. (Если ваша функция не поддерживает ключевые слова, сгенерированная функция разбора вызовет исключение при их получении.)877878### Изменение и перенаправление вывода Clinic879880Может быть неудобно, когда вывод Clinic перемежается с вашим обычным кодом C, отредактированным вручную. К счастью, Clinic настраивается: можно буферизовать его вывод для печати позже (или раньше!) или записывать вывод в отдельный файл. Также можно добавить префикс или суффикс к каждой строке сгенерированного вывода Clinic.881882Хотя такое изменение вывода Clinic может улучшить читаемость, это может привести к тому, что код Clinic будет использовать типы до их определения, или ваш код будет пытаться использовать сгенерированный Clinic код до его определения. Эти проблемы легко решаются перестановкой объявлений в файле или перемещением места, куда помещается сгенерированный код Clinic. (Именно поэтому поведение Clinic по умолчанию – выводить всё в текущий блок; хотя многие считают, что это затрудняет чтение, это никогда не потребует перестановки кода для исправления проблем использования до определения.)883884Начнём с определения некоторых терминов:885886***поле***887888Поле в данном контексте – это подраздел вывода Clinic. Например, `#define` для структуры `PyMethodDef` является полем, называемым `methoddef_define`. Clinic может выводить семь различных полей для каждого определения функции:889890```text891docstring_prototype892docstring_definition893methoddef_define894impl_prototype895parser_prototype896parser_definition897impl_definition898```899900Все имена имеют вид `"<a>_<b>"`, где `"<a>"` – это представляемый семантический объект (функция разбора, функция impl, строка документации или структура methoddef), а `"<b>"` обозначает, какой тип оператора представляет поле. Имена полей, заканчивающиеся на `"_prototype"`, представляют предварительные объявления этой сущности без фактического тела/данных; имена полей, заканчивающиеся на `"_definition"`, представляют фактическое определение сущности с телом/данными. (`"methoddef"` особое, это единственное, заканчивающееся на `"_define"`, что означает, что это директива препроцессора #define.)901902***назначение***903904Назначение – это место, куда Clinic может записывать вывод. Существует пять встроенных назначений:905906**`block`**907908Назначение по умолчанию: выводится в секции вывода текущего блока Clinic.909910**`buffer`**911912Текстовый буфер, в котором можно сохранить текст для последующего использования. Текст, отправленный сюда, добавляется в конец любого существующего текста. Ошибка – оставить какой-либо текст в буфере после завершения обработки файла Clinic.913914**`file`**915916Отдельный «файл clinic», который будет автоматически создан Clinic. Выбранное имя файла – `{basename}.clinic{extension}`, где `basename` и `extension` получили вывод от `os.path.splitext()`, запущенного на текущем файле. (Пример: назначение `file` для `_pickle.c` будет записано в `_pickle.clinic.c`.)917918**Важно: при использовании** `file` **назначения** *обязательно проверьте* **сгенерированный файл!**919920**`two-pass`**921922Буфер, подобный `buffer`. Однако буфер двойного прохода можно сбросить только один раз, и он выводит весь текст, отправленный ему во время всей обработки, даже из блоков Clinic *после* точки сброса.923924**`suppress`**925926Текст подавляется – отбрасывается.927928Clinic определяет пять новых директив, позволяющих перенастроить его вывод.929930Первая новая директива – `dump`:931932```text933dump <destination>934```935936Эта директива сбрасывает текущее содержимое указанного назначения в вывод текущего блока и очищает его. Она работает только с назначениями `buffer` и `two-pass`.937938Вторая новая директива – `output`. Самая простая форма `output` выглядит так:939940```text941output <field> <destination>942```943944Эта директива указывает Clinic выводить *поле* в *назначение*. `output` также поддерживает специальное мета-назначение под названием `everything`, которое указывает Clinic выводить *все* поля в это *назначение*.945946`output` имеет ряд других функций:947948```text949output push950output pop951output preset <preset>952```953954`output push` и `output pop` позволяют помещать и извлекать конфигурации со внутреннего стека конфигураций, чтобы можно было временно изменить конфигурацию вывода, а затем легко восстановить предыдущую конфигурацию. Просто поместите текущую конфигурацию в стек перед изменением, чтобы сохранить её, а затем извлеките, когда потребуется восстановить предыдущую конфигурацию.955956`output preset` устанавливает вывод Clinic в одну из нескольких встроенных предустановленных конфигураций следующим образом:957958> **`block`**959>960> Исходная начальная конфигурация Clinic. Пишет всё сразу после входного блока.961>962> Подавляет `parser_prototype` и `docstring_prototype`, всё остальное записывает в `block`.963>964> **`file`**965>966> Предназначен для записи всего, что возможно, в «clinic-файл». Затем этот файл `#include` ближе к началу вашего файла. Возможно, потребуется перестроить файл, чтобы это заработало, но обычно для этого достаточно создать прямые объявления для различных определений `typedef` и `PyTypeObject`.967>968> Подавляет `parser_prototype` и `docstring_prototype`, записывает `impl_definition` в `block`, а всё остальное – в `file`.969>970> Имя файла по умолчанию – `"{dirname}/clinic/{basename}.h"`.971>972> **`buffer`**973>974> Сохраняет большую часть вывода Clinic для последующей записи в файл ближе к концу. Для файлов Python, реализующих модули или встроенные типы, рекомендуется сбрасывать буфер непосредственно перед статическими структурами для модуля или встроенного типа; обычно они находятся ближе к концу. Использование `buffer` может потребовать даже больше правок, чем `file`, если в файле есть статические массивы `PyMethodDef`, определённые в середине файла.975>976> Подавляет `parser_prototype`, `impl_prototype` и `docstring_prototype`, записывает `impl_definition` в `block`, а всё остальное – в `file`.977>978> **`two-pass`**979>980> Аналогичен предустановке `buffer`, но записывает прямые объявления в буфер `two-pass`, а определения – в `buffer`. Это похоже на предустановку `buffer`, но может потребовать меньше правок, чем `buffer`. Сбросьте буфер `two-pass` ближе к началу файла, а буфер `buffer` – ближе к концу, как при использовании предустановки `buffer`.981>982> Подавляет `impl_prototype`, записывает `impl_definition` в `block`, записывает `docstring_prototype`, `methoddef_define` и `parser_prototype` в `two-pass`, всё остальное записывает в `buffer`.983>984> **`partial-buffer`**985>986> Аналогичен предустановке `buffer`, но записывает больше вещей в `block`, а действительно большие фрагменты сгенерированного кода – только в `buffer`. Это полностью исключает проблему «определение до использования» предустановки `buffer`, ценой немного большего количества материала в выводе блока. Сбросьте буфер `buffer` ближе к концу, как при использовании предустановки `buffer`.987>988> Подавляет `impl_prototype`, записывает `docstring_definition` и `parser_definition` в `buffer`, всё остальное записывает в `block`.989990Третья новая директива – `destination`:991992```text993destination <name> <command> [...]994```995996Эта директива выполняет операцию над назначением с именем `name`.997998Определены две подкоманды: `new` и `clear`.9991000Подкоманда `new` работает следующим образом:10011002```text1003destination <name> new <type>1004```10051006Это создаёт новое назначение с именем `<name>` и типом `<type>`.10071008Существует пять типов назначений:10091010> **`suppress`**1011>1012> Отбрасывает текст.1013>1014> **`block`**1015>1016> Записывает текст в текущий блок. Именно так Clinic работал изначально.1017>1018> **`buffer`**1019>1020> Простой текстовый буфер, как встроенное назначение «buffer» выше.1021>1022> **`file`**1023>1024> Текстовый файл. Назначение «файл» принимает дополнительный аргумент – шаблон для построения имени файла, например:1025>1026> > назначение \<имя\> new \<тип\> \<шаблон\_файла\>1027>1028> Внутри шаблона можно использовать три строки, которые будут заменены на части имени файла:1029>1030> > **{path}**1031> >1032> > Полный путь к файлу, включая каталог и полное имя файла.1033> >1034> > **{dirname}**1035> >1036> > Имя каталога, в котором находится файл.1037> >1038> > **{basename}**1039> >1040> > Просто имя файла, без каталога.1041> >1042> > **{basename\_root}**1043> >1044> > Базовое имя без расширения (всё до последней точки, но не включая её).1045> >1046> > **{basename\_extension}**1047> >1048> > Последняя точка и всё после неё. Если в базовом имени нет точки, будет пустая строка.1049>1050> Если в имени файла нет точек, {basename} и {filename} совпадают, а {extension} пуст. «{basename}{extension}» всегда совпадает с «{filename}».1051>1052> **`two-pass`**1053>1054> Буфер двухпроходной обработки, как встроенное назначение «two-pass» выше.10551056Подкоманда `clear` работает следующим образом:10571058```text1059destination <name> clear1060```10611062Она удаляет весь накопленный текст до этой точки в назначении. (Не знаю, для чего это может понадобиться, но подумал, что может быть полезно для экспериментов.)10631064Четвёртая новая директива – `set`:10651066```text1067set line_prefix "string"1068set line_suffix "string"1069```10701071`set` позволяет задать две внутренние переменные в Clinic. `line_prefix` – строка, которая будет добавляться перед каждой строкой вывода Clinic; `line_suffix` – строка, которая будет добавляться после каждой строки вывода Clinic.10721073Обе поддерживают две строки формата:10741075> **`{block comment start}`**1076>1077> Превращается в строку `/*`, последовательность символов начала комментария для C-файлов.1078>1079> **`{block comment end}`**1080>1081> Превращается в строку `*/`, последовательность символов конца комментария для C-файлов.10821083Последняя новая директива – та, которую не нужно использовать напрямую, называется `preserve`:10841085```text1086preserve1087```10881089Это говорит Clinic, что текущее содержимое вывода следует оставить без изменений. Внутренне Clinic использует это при выгрузке вывода в файлы `file`; оборачивание в блок Clinic позволяет Clinic использовать существующую функциональность контрольных сумм, чтобы гарантировать, что файл не был изменён вручную перед его перезаписью.10901091### Трюк с #ifdef10921093При преобразовании функции, которая доступна не на всех платформах, можно воспользоваться трюком, чтобы немного упростить жизнь. Существующий код, вероятно, выглядит так:10941095```c1096#ifdef HAVE_FUNCTIONNAME1097static module_functionname(...)1098{1099...1100}1101#endif /* HAVE_FUNCTIONNAME */1102```11031104И затем в структуре `PyMethodDef` в нижней части существующий код будет содержать:11051106```text1107#ifdef HAVE_FUNCTIONNAME1108{'functionname', ... },1109#endif /* HAVE_FUNCTIONNAME */1110```11111112В этом случае тело функции impl нужно заключить внутрь `#ifdef`, вот так:11131114```c1115#ifdef HAVE_FUNCTIONNAME1116/*[clinic input]1117module.functionname1118...1119[clinic start generated code]*/1120static module_functionname(...)1121{1122...1123}1124#endif /* HAVE_FUNCTIONNAME */1125```11261127Затем удалите эти три строки из структуры `PyMethodDef`, заменив их макросом, сгенерированным Argument Clinic:11281129```text1130MODULE_FUNCTIONNAME_METHODDEF1131```11321133(Настоящее имя этого макроса можно найти в сгенерированном коде. Или можно вычислить его самостоятельно: это имя вашей функции, как оно определено в первой строке вашего блока, но с заменой точек на подчёркивания, в верхнем регистре и с добавлением `"_METHODDEF"` в конец.)11341135Возможно, вы задаётесь вопросом: что если `HAVE_FUNCTIONNAME` не определён? Тогда макрос `MODULE_FUNCTIONNAME_METHODDEF` тоже не будет определён!11361137Вот где Argument Clinic проявляет смекалку. Он обнаруживает, что блок Argument Clinic может быть деактивирован директивой `#ifdef`. Когда это происходит, он генерирует небольшой дополнительный код, который выглядит так:11381139```c1140#ifndef MODULE_FUNCTIONNAME_METHODDEF1141 #define MODULE_FUNCTIONNAME_METHODDEF1142#endif /* !defined(MODULE_FUNCTIONNAME_METHODDEF) */1143```11441145Это означает, что макрос всегда работает. Если функция определена, это превращается в правильную структуру, включая завершающую запятую. Если функция не определена, это превращается в ничто.11461147Однако это вызывает одну деликатную проблему: куда Argument Clinic должен поместить этот дополнительный код при использовании пресета вывода "block"? Его нельзя поместить в выходной блок, потому что он может быть деактивирован `#ifdef`. (В этом вся суть!)11481149В этой ситуации Argument Clinic записывает дополнительный код в назначение "buffer". Это может означать, что Argument Clinic выдаст предупреждение:11501151```text1152Warning in file "Modules/posixmodule.c" on line 12357:1153Destination buffer 'buffer' not empty at end of file, emptying.1154```11551156Если это произошло, просто откройте файл, найдите блок `dump buffer`, который Argument Clinic добавил в файл (он будет в самом низу), и переместите его выше структуры `PyMethodDef`, где используется этот макрос.11571158### Использование Argument Clinic в файлах Python11591160На самом деле Argument Clinic можно использовать для предварительной обработки файлов Python. Конечно, использовать блоки Argument Clinic нет смысла, так как интерпретатор Python не поймёт вывод. Но использование Argument Clinic для выполнения блоков Python позволяет использовать Python в качестве препроцессора для Python!11611162Поскольку комментарии в Python отличаются от комментариев в C, блоки Argument Clinic, встроенные в файлы Python, выглядят немного иначе. Они выглядят так:11631164```python1165#/*[python input]1166#print("def foo(): pass")1167#[python start generated code]*/1168def foo(): pass1169#/*[python checksum:...]*/1170```1171