dict.md

1> **Источник:** https://python-all.ru/3.2/c-api/dict.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты словарей89**`PyDictObject`**1011Этот подтип [`PyObject`](https://python-all.ru/3.2/c-api/structures.html#PyObject) представляет объект словаря Python.1213**[PyTypeObject](https://python-all.ru/3.2/c-api/type.html#PyTypeObject) `PyDict_Type`**1415Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.2/c-api/type.html#PyTypeObject) представляет тип словаря Python. Это тот же объект, что и [`dict`](https://python-all.ru/3.2/library/stdtypes.html#dict) на уровне Python.1617#### `int PyDict_Check(PyObject *p)`1819Возвращает true, если *p* является объектом dict или экземпляром подтипа типа dict.2021#### `int PyDict_CheckExact(PyObject *p)`2223Возвращает true, если *p* является объектом dict, но не экземпляром подтипа tипа dict.2425#### `PyObject* PyDict_New()`2627*Возвращаемое значение: новая ссылка.*2829Возвращает новый пустой словарь или *NULL* в случае ошибки.3031#### `PyObject* PyDictProxy_New(PyObject *dict)`3233*Возвращаемое значение: новая ссылка.*3435Возвращает прокси-объект для отображения, которое обеспечивает поведение только для чтения. Обычно используется для создания прокси, предотвращающего изменение словаря для нединамических типов классов.3637#### `void PyDict_Clear(PyObject *p)`3839Очищает существующий словарь от всех пар ключ-значение.4041#### `int PyDict_Contains(PyObject *p, PyObject *key)`4243Определяет, содержит ли словарь *p* ключ *key*. Если элемент в *p* совпадает с *key*, возвращается `1`, в противном случае возвращается `0`. При ошибке возвращается `-1`. Это эквивалентно выражению Python `key in p`.4445#### `PyObject* PyDict_Copy(PyObject *p)`4647*Возвращаемое значение: новая ссылка.*4849Возвращает новый словарь, содержащий те же пары ключ-значение, что и *p*.5051#### `int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)`5253Вставляет значение *value* в словарь *p* с ключом *key*. Ключ *key* должен быть [*hashable*](https://python-all.ru/3.2/glossary.html#term-hashable); если нет, будет возбуждено исключение [`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError). При успехе возвращается `0`, при ошибке – `-1`.5455#### `int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)`5657Вставляет значение *value* в словарь *p*, используя *key* в качестве ключа. *key* должен быть `char*`. Объект ключа создаётся с помощью `PyUnicode_FromString(key)`. При успехе возвращается `0`, при ошибке – `-1`.5859#### `int PyDict_DelItem(PyObject *p, PyObject *key)`6061Удаляет запись из словаря *p* с ключом *key*. Ключ *key* должен быть хешируемым; если нет, возбуждается [`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError). При успехе возвращается `0`, при ошибке – `-1`.6263#### `int PyDict_DelItemString(PyObject *p, char *key)`6465Удаляет запись из словаря *p*, ключ которой задаётся строкой *key*. Возвращает `0` при успехе или `-1` при неудаче.6667#### `PyObject* PyDict_GetItem(PyObject *p, PyObject *key)`6869*Возвращаемое значение: заимствованная ссылка.*7071Возвращает объект из словаря *p* с ключом *key*. Возвращает *NULL* если ключ *key* отсутствует, но *без* установки исключения.7273#### `PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)`7475Вариант [`PyDict_GetItem()`](https://python-all.ru/3.2/c-api/dict.html#PyDict_GetItem), который не подавляет исключения. Возвращает *NULL* **с** установленным исключением, если произошла ошибка. Возвращает *NULL* **без** установленного исключения, если ключ отсутствовал.7677#### `PyObject* PyDict_GetItemString(PyObject *p, const char *key)`7879*Возвращаемое значение: заимствованная ссылка.*8081То же, что и [`PyDict_GetItem()`](https://python-all.ru/3.2/c-api/dict.html#PyDict_GetItem), но ключ *key* задаётся как `char*`, а не как [`PyObject*`](https://python-all.ru/3.2/c-api/structures.html#PyObject).8283#### `PyObject* PyDict_Items(PyObject *p)`8485*Возвращаемое значение: новая ссылка.*8687Возвращает [`PyListObject`](https://python-all.ru/3.2/c-api/list.html#PyListObject), содержащий все элементы из словаря.8889#### `PyObject* PyDict_Keys(PyObject *p)`9091*Возвращаемое значение: новая ссылка.*9293Возвращает [`PyListObject`](https://python-all.ru/3.2/c-api/list.html#PyListObject), содержащий все ключи из словаря.9495#### `PyObject* PyDict_Values(PyObject *p)`9697*Возвращаемое значение: новая ссылка.*9899Возвращает [`PyListObject`](https://python-all.ru/3.2/c-api/list.html#PyListObject), содержащий все значения из словаря *p*.100101#### `Py_ssize_t PyDict_Size(PyObject *p)`102103Возвращает количество элементов в словаре. Это эквивалентно `len(p)` для словаря.104105#### `int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)`106107Перебирает все пары ключ-значение в словаре *p*. Переменная `Py_ssize_t`, на которую ссылается *ppos*, должна быть инициализирована значением `0` до первого вызова этой функции для начала итерации; функция возвращает true для каждой пары в словаре и false, когда все пары были перебраны. Параметры *pkey* и *pvalue* должны либо указывать на переменные типа [`PyObject*`](https://python-all.ru/3.2/c-api/structures.html#PyObject), которые будут заполнены соответствующими ключом и значением, либо могут быть *NULL*. Любые ссылки, возвращаемые через них, являются заимствованными. *ppos* не должен изменяться во время итерации. Его значение представляет собой смещения во внутренней структуре словаря, и поскольку структура разрежена, смещения не являются последовательными.108109Например:110111```c112PyObject *key, *value;113Py_ssize_t pos = 0;114115while (PyDict_Next(self->dict, &pos, &key, &value)) {116    /* сделайте что-нибудь интересное со значениями... */117    ...118}119```120121Словарь *p* не должен изменяться во время итерации. Можно безопасно изменять значения ключей при переборе словаря, но только до тех пор, пока набор ключей не меняется. Например:122123```c124PyObject *key, *value;125Py_ssize_t pos = 0;126127while (PyDict_Next(self->dict, &pos, &key, &value)) {128    long i = PyLong_AsLong(value);129    if (i == -1 && PyErr_Occurred()) {130        return -1;131    }132    PyObject *o = PyLong_FromLong(i + 1);133    if (o == NULL)134        return -1;135    if (PyDict_SetItem(self->dict, key, o) < 0) {136        Py_DECREF(o);137        return -1;138    }139    Py_DECREF(o);140}141```142143#### `int PyDict_Merge(PyObject *a, PyObject *b, int override)`144145Перебирает объект отображения *b*, добавляя пары ключ-значение в словарь *a*. *b* может быть словарём или любым объектом, поддерживающим [`PyMapping_Keys()`](https://python-all.ru/3.2/c-api/mapping.html#PyMapping_Keys) и [`PyObject_GetItem()`](https://python-all.ru/3.2/c-api/object.html#PyObject_GetItem). Если *override* истинно, существующие пары в *a* будут заменены, если найден соответствующий ключ в *b*; в противном случае пары будут добавлены только при отсутствии соответствующего ключа в *a*. Возвращает `0` в случае успеха или `-1`, если было возбуждено исключение.146147#### `int PyDict_Update(PyObject *a, PyObject *b)`148149То же самое, что `PyDict_Merge(a, b, 1)` в C, или `a.update(b)` в Python. Возвращает `0` при успехе или `-1`, если было возбуждено исключение.150151#### `int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)`152153Обновляет или объединяет словарь *a*, используя пары ключ-значение из *seq2*. *seq2* должен быть итерируемым объектом, который возвращает итерируемые объекты длины 2, рассматриваемые как пары ключ-значение. При повторяющихся ключах последнее значение побеждает, если *override* истинно, иначе первое. Возвращает `0` при успехе или `-1`, если возникло исключение. Эквивалент на Python (за исключением возвращаемого значения):154155```c156def PyDict_MergeFromSeq2(a, seq2, override):157    for key, value in seq2:158        if override or key not in a:159            a[key] = value160```161