`dict.md`

353 строк · 14.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/c-api/dict.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты словарей89**\[PyDictObject\]`PyDictObject`**1011Этот подтип1213[`PyObject`](https://python-all.ru/3.0/c-api/structures.html#PyObject)1415представляет объект словаря Python.1617**\[PyDict\_Type\][PyTypeObject](https://python-all.ru/3.0/c-api/type.html#PyTypeObject) `PyDict_Type`**1819Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.0/c-api/type.html#PyTypeObject) представляет тип словаря Python. Он доступен программам на Python как `dict` и `types.DictType`.2021**\[PyDict\_Check\]int `PyDict_Check`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**2223Возвращает true, если2425*p*2627является объектом dict или экземпляром подтипа типа dict.2829**\[PyDict\_CheckExact\]int `PyDict_CheckExact`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**3031Возвращает истину, если3233*p*3435является объектом словаря, но не экземпляром подтипа типа dict.3637**\[PyDict\_New\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyDict_New`()**3839*Возвращаемое значение: новая ссылка.*4041Возвращает новый пустой словарь или *NULL* в случае ошибки.4243**\[PyDictProxy\_New\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyDictProxy_New`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*dict*)**4445*Возвращаемое значение: новая ссылка.*4647Возвращает прокси-объект для отображения, обеспечивающий доступ только для чтения. Обычно используется для создания прокси, предотвращающего изменение словаря для нединамических типов классов.4849**\[PyDict\_Clear\]void `PyDict_Clear`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**5051Очищает существующий словарь от всех пар ключ-значение.5253**\[PyDict\_Contains\]int `PyDict_Contains`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*key*)**5455Определяет, содержит ли словарь5657*p*5859ключ6061*key*6263. Если элемент в6465*p*6667совпадает с6869*key*7071, возвращает7273`1`7475, в противном случае возвращает7677`0`7879. При ошибке возвращает8081`-1`8283. Эквивалентно выражению Python8485`key in p`8687.8889**\[PyDict\_Copy\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyDict_Copy`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**9091*Возвращаемое значение: новая ссылка.*9293Возвращает новый словарь, содержащий те же пары ключ-значение, что и *p*.9495**\[PyDict\_SetItem\]int `PyDict_SetItem`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*key*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*val*)**9697Вставляет9899*value*100101в словарь102103*p*104105с ключом106107*key*108109.110111*key*112113должен быть114115[*хэшируемым*](https://python-all.ru/3.0/glossary.html#term-hashable)116117; если это не так, возбуждается118119[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)120121. Возвращает122123`0`124125при успехе или126127`-1`128129при неудаче.130131**\[PyDict\_SetItemString\]int `PyDict_SetItemString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*, const char *\*key*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*val*)**132133Вставляет *value* в словарь *p*, используя *key* в качестве ключа. *key* должен быть типа `char*`. Объект ключа создаётся с помощью `PyString_FromString(key)`. Возвращает `0` при успехе или `-1` при неудаче.134135**\[PyDict\_DelItem\]int `PyDict_DelItem`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*key*)**136137Удаляет запись из словаря138139*p*140141с ключом142143*key*144145.146147*key*148149должен быть хэшируемым; если это не так, возбуждается150151[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)152153. Возвращает154155`0`156157при успехе или158159`-1`160161при неудаче.162163**\[PyDict\_DelItemString\]int `PyDict_DelItemString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*, char *\*key*)**164165Удаляет запись из словаря166167*p*168169, ключ которой задаётся строкой170171*key*172173. Возвращает174175`0`176177при успехе или178179`-1`180181при неудаче.182183**\[PyDict\_GetItem\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyDict_GetItem`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*key*)**184185*Возвращаемое значение: заимствованная ссылка.*186187Возвращает объект из словаря *p*, имеющий ключ *key*. Возвращает *NULL*, если ключ *key* отсутствует, но *без* установки исключения.188189**\[PyDict\_GetItemWithError\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyDict_GetItemWithError`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*key*)**190191Вариант192193[`PyDict_GetItem`](https://python-all.ru/3.0/c-api/dict.html#PyDict_GetItem)194195, который не подавляет исключения. Возвращает196197*NULL*198199**с**200201установленным исключением, если произошла ошибка. Возвращает202203*NULL*204205**без**206207установленного исключения, если ключ отсутствовал.208209**\[PyDict\_GetItemString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyDict_GetItemString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*, const char *\*key*)**210211*Возвращаемое значение: заимствованная ссылка.*212213То же самое, что [`PyDict_GetItem`](https://python-all.ru/3.0/c-api/dict.html#PyDict_GetItem), но *key* задаётся как `char*`, а не как [`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject).214215**\[PyDict\_Items\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyDict_Items`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**216217*Возвращаемое значение: новая ссылка.*218219Возвращает [`PyListObject`](https://python-all.ru/3.0/c-api/list.html#PyListObject), содержащий все элементы словаря, как и метод словаря [`dict.items()`](https://python-all.ru/3.0/library/stdtypes.html#dict.items).220221**\[PyDict\_Keys\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyDict_Keys`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**222223*Возвращаемое значение: новая ссылка.*224225Возвращает [`PyListObject`](https://python-all.ru/3.0/c-api/list.html#PyListObject), содержащий все ключи словаря, как и метод словаря [`dict.keys()`](https://python-all.ru/3.0/library/stdtypes.html#dict.keys).226227**\[PyDict\_Values\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyDict_Values`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**228229*Возвращаемое значение: новая ссылка.*230231Возвращает [`PyListObject`](https://python-all.ru/3.0/c-api/list.html#PyListObject), содержащий все значения из словаря *p*, как в методе словаря [`dict.values()`](https://python-all.ru/3.0/library/stdtypes.html#dict.values).232233**\[PyDict\_Size\]Py\_ssize\_t `PyDict_Size`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**234235Возвращает количество элементов в словаре. Это эквивалентно `len(p)` для словаря.236237**\[PyDict\_Next\]int `PyDict_Next`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*, Py\_ssize\_t *\*ppos*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*\*pkey*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*\*pvalue*)**238239Проходит по всем парам ключ-значение в словаре *p*. Переменная типа `int`, на которую ссылается *ppos*, должна быть инициализирована значением `0` до первого вызова этой функции для начала итерации; функция возвращает true для каждой пары в словаре и false после того, как все пары были выданы. Параметры *pkey* и *pvalue* должны либо указывать на переменные типа [`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject), которые будут заполнены ключом и значением соответственно, либо могут быть *NULL*. Любые возвращаемые через них ссылки являются заимствованными. *ppos* не должен изменяться во время итерации. Его значение представляет смещения во внутренней структуре словаря, и, поскольку структура разреженная, эти смещения не являются последовательными.240241Например:242243```c244PyObject *key, *value;245Py_ssize_t pos = 0;246247while (PyDict_Next(self->dict, &pos, &key, &value)) {248    /* сделайте что-нибудь интересное со значениями... */249    ...250}251```252253Словарь *p* не должен изменяться во время итерации. Можно безопасно изменять значения ключей в процессе итерации, но только при условии, что набор ключей не меняется. Например:254255```c256PyObject *key, *value;257Py_ssize_t pos = 0;258259while (PyDict_Next(self->dict, &pos, &key, &value)) {260    long i = PyLong_AsLong(value);261    if (i == -1 && PyErr_Occurred()) {262        return -1;263    }264    PyObject *o = PyLong_FromLong(i + 1);265    if (o == NULL)266        return -1;267    if (PyDict_SetItem(self->dict, key, o) < 0) {268        Py_DECREF(o);269        return -1;270    }271    Py_DECREF(o);272}273```274275**\[PyDict\_Merge\]int `PyDict_Merge`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*b*, int *override*)**276277Проходит по объекту отображения278279*b*280281, добавляя пары ключ-значение в словарь282283*a*284285.286287*b*288289может быть словарём или любым объектом, поддерживающим290291[`PyMapping_Keys()`](https://python-all.ru/3.0/c-api/mapping.html#PyMapping_Keys)292293и294295[`PyObject_GetItem()`](https://python-all.ru/3.0/c-api/object.html#PyObject_GetItem)296297. Если298299*override*300301истинно, существующие пары в302303*a*304305будут заменены при нахождении совпадающего ключа в306307*b*308309; в противном случае пары будут добавлены, только если нет совпадающего ключа в310311*a*312313. Возвращает314315`0`316317при успехе или318319`-1`320321, если было возбуждено исключение.322323**\[PyDict\_Update\]int `PyDict_Update`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*b*)**324325То же самое, что326327`PyDict_Merge(a, b, 1)`328329в C, или330331`a.update(b)`332333в Python. Возвращает334335`0`336337при успехе или338339`-1`340341, если было возбуждено исключение.342343**\[PyDict\_MergeFromSeq2\]int `PyDict_MergeFromSeq2`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*seq2*, int *override*)**344345Обновляет или сливает словарь *a* из пар ключ-значение в *seq2*. *seq2* должен быть итерируемым объектом, который порождает итерируемые объекты длины 2, рассматриваемые как пары ключ-значение. В случае дублирования ключей последний побеждает, если *override* истинно, иначе побеждает первый. Возвращает `0` при успехе или `-1`, если было возбуждено исключение. Эквивалентный код Python (за исключением возвращаемого значения):346347```c348def PyDict_MergeFromSeq2(a, seq2, override):349    for key, value in seq2:350        if override or key not in a:351            a[key] = value352```353