`mapping.md`

130 строк · 10.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.14/c-api/mapping.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Протокол отображения89См. также [`PyObject_GetItem()`](https://python-all.ru/3.14/c-api/object.html#c.PyObject_GetItem), [`PyObject_SetItem()`](https://python-all.ru/3.14/c-api/object.html#c.PyObject_SetItem) и [`PyObject_DelItem()`](https://python-all.ru/3.14/c-api/object.html#c.PyObject_DelItem).1011#### `int PyMapping_Check(PyObject *o)`1213*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*1415Возвращает `1`, если объект предоставляет протокол отображения или поддерживает срезы, и `0` в противном случае. Обратите внимание, что возвращает `1` для классов Python с методом [`__getitem__()`](https://python-all.ru/3.14/reference/datamodel.html#object.__getitem__), поскольку в общем случае невозможно определить, какой тип ключей поддерживает класс. Эта функция всегда завершается успешно.1617#### `Py_ssize_t PyMapping_Size(PyObject *o)`1819#### `Py_ssize_t PyMapping_Length(PyObject *o)`2021*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*2223В случае успеха возвращает количество ключей в объекте *o*, а в случае ошибки – `-1`. Это эквивалентно выражению Python `len(o)`.2425#### `PyObject *PyMapping_GetItemString(PyObject *o, const char *key)`2627*Возвращаемое значение: новая ссылка.*2829*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*3031То же, что и [`PyObject_GetItem()`](https://python-all.ru/3.14/c-api/object.html#c.PyObject_GetItem), но *key* задаётся как const char\* строка байтов в кодировке UTF-8, а не как [PyObject](https://python-all.ru/3.14/c-api/structures.html#c.PyObject)\*.3233#### `int PyMapping_GetOptionalItem(PyObject *obj, PyObject *key, PyObject **result)`3435*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable), начиная с версии 3.13.*3637Вариант [`PyObject_GetItem()`](https://python-all.ru/3.14/c-api/object.html#c.PyObject_GetItem), который не вызывает [`KeyError`](https://python-all.ru/3.14/library/exceptions.html#KeyError), если ключ не найден.3839Если ключ найден, возвращает `1` и присваивает *\*result* новую [сильную ссылку](https://python-all.ru/3.14/glossary.html#term-strong-reference) на соответствующее значение. Если ключ не найден, возвращает `0` и присваивает *\*result* значение `NULL`; исключение [`KeyError`](https://python-all.ru/3.14/library/exceptions.html#KeyError) подавляется. Если возникла ошибка, отличная от `KeyError`, возвращается `-1` и присваивается *\*result* значение `NULL`.4041Добавлено в версии 3.13.4243#### `int PyMapping_GetOptionalItemString(PyObject *obj, const char *key, PyObject **result)`4445*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable), начиная с версии 3.13.*4647То же, что и [`PyMapping_GetOptionalItem()`](https://python-all.ru/3.14/c-api/mapping.html#c.PyMapping_GetOptionalItem), но *key* задаётся как const char\* строка байтов в кодировке UTF-8, а не как [PyObject](https://python-all.ru/3.14/c-api/structures.html#c.PyObject)\*.4849Добавлено в версии 3.13.5051#### `int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)`5253*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*5455То же, что и [`PyObject_SetItem()`](https://python-all.ru/3.14/c-api/object.html#c.PyObject_SetItem), но *key* задаётся как const char\* строка байтов в кодировке UTF-8, а не как [PyObject](https://python-all.ru/3.14/c-api/structures.html#c.PyObject)\*.5657#### `int PyMapping_DelItem(PyObject *o, PyObject *key)`5859Это псевдоним [`PyObject_DelItem()`](https://python-all.ru/3.14/c-api/object.html#c.PyObject_DelItem).6061#### `int PyMapping_DelItemString(PyObject *o, const char *key)`6263То же, что и [`PyObject_DelItem()`](https://python-all.ru/3.14/c-api/object.html#c.PyObject_DelItem), но *key* задаётся как const char\* строка байтов в кодировке UTF-8, а не как [PyObject](https://python-all.ru/3.14/c-api/structures.html#c.PyObject)\*.6465#### `int PyMapping_HasKeyWithError(PyObject *o, PyObject *key)`6667*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable), начиная с версии 3.13.*6869Возвращает `1`, если объект отображения имеет ключ *key*, и `0` в противном случае. Это эквивалентно выражению Python `key in o`. При ошибке возвращает `-1`.7071Добавлено в версии 3.13.7273#### `int PyMapping_HasKeyStringWithError(PyObject *o, const char *key)`7475*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable), начиная с версии 3.13.*7677То же, что и [`PyMapping_HasKeyWithError()`](https://python-all.ru/3.14/c-api/mapping.html#c.PyMapping_HasKeyWithError), но *key* задаётся как const char\* строка байтов в кодировке UTF-8, а не как [PyObject](https://python-all.ru/3.14/c-api/structures.html#c.PyObject)\*.7879Добавлено в версии 3.13.8081#### `int PyMapping_HasKey(PyObject *o, PyObject *key)`8283*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*8485Возвращает `1`, если объект отображения имеет ключ *key*, и `0` в противном случае. Это эквивалентно выражению Python `key in o`. Эта функция всегда завершается успешно.8687> **Примечание**88>89> Исключения, возникающие при вызове метода [`__getitem__()`](https://python-all.ru/3.14/reference/datamodel.html#object.__getitem__), молча игнорируются. Для правильной обработки ошибок используйте [`PyMapping_HasKeyWithError()`](https://python-all.ru/3.14/c-api/mapping.html#c.PyMapping_HasKeyWithError), [`PyMapping_GetOptionalItem()`](https://python-all.ru/3.14/c-api/mapping.html#c.PyMapping_GetOptionalItem) или [`PyObject_GetItem()`](https://python-all.ru/3.14/c-api/object.html#c.PyObject_GetItem).9091#### `int PyMapping_HasKeyString(PyObject *o, const char *key)`9293*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*9495То же, что и [`PyMapping_HasKey()`](https://python-all.ru/3.14/c-api/mapping.html#c.PyMapping_HasKey), но *key* задаётся как const char\* строка байтов в кодировке UTF-8, а не как [PyObject](https://python-all.ru/3.14/c-api/structures.html#c.PyObject)\*.9697> **Примечание**98>99> Исключения, возникающие при вызове метода [`__getitem__()`](https://python-all.ru/3.14/reference/datamodel.html#object.__getitem__) или при создании временного объекта [`str`](https://python-all.ru/3.14/library/stdtypes.html#str), молча игнорируются. Для правильной обработки ошибок используйте [`PyMapping_HasKeyStringWithError()`](https://python-all.ru/3.14/c-api/mapping.html#c.PyMapping_HasKeyStringWithError), [`PyMapping_GetOptionalItemString()`](https://python-all.ru/3.14/c-api/mapping.html#c.PyMapping_GetOptionalItemString) или [`PyMapping_GetItemString()`](https://python-all.ru/3.14/c-api/mapping.html#c.PyMapping_GetItemString).100101#### `PyObject *PyMapping_Keys(PyObject *o)`102103*Возвращаемое значение: новая ссылка.*104105*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*106107В случае успеха возвращает список ключей в объекте *o*. В случае ошибки возвращает `NULL`.108109Изменено в версии 3.7: Ранее функция возвращала список или кортеж.110111#### `PyObject *PyMapping_Values(PyObject *o)`112113*Возвращаемое значение: новая ссылка.*114115*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*116117В случае успеха возвращает список значений в объекте *o*. В случае ошибки возвращает `NULL`.118119Изменено в версии 3.7: Ранее функция возвращала список или кортеж.120121#### `PyObject *PyMapping_Items(PyObject *o)`122123*Возвращаемое значение: новая ссылка.*124125*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*126127В случае успеха возвращает список элементов объекта *o*, где каждый элемент – это кортеж, содержащий пару ключ-значение. В случае неудачи возвращает `NULL`.128129Изменено в версии 3.7: Ранее функция возвращала список или кортеж.130