> **Источник:** https://python-all.ru/2.6/c-api/dict.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # Объекты словарей **`PyDictObject`** Этот подтип [`PyObject`](https://python-all.ru/2.6/c-api/structures.html#PyObject) представляет объект словаря Python. **[PyTypeObject](https://python-all.ru/2.6/c-api/type.html#PyTypeObject) `PyDict_Type`** Этот экземпляр [`PyTypeObject`](https://python-all.ru/2.6/c-api/type.html#PyTypeObject) представляет тип Python-словаря. Он доступен программам на Python как `dict` и `types.DictType`. **int `PyDict_Check`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)** Возвращает true, если *p* является объектом dict или экземпляром подтипа типа dict. Изменено в версии 2.2: Теперь допускаются подтипы. **int `PyDict_CheckExact`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)** Возвращает true, если *p* является объектом dict, но не экземпляром подтипа tипа dict. Новое в версии 2.4. **[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_New`()** *Возвращаемое значение: новая ссылка.* Возвращает новый пустой словарь или *NULL* в случае ошибки. **[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDictProxy_New`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*dict*)** *Возвращаемое значение: новая ссылка.* Возвращает прокси-объект для отображения, которое обеспечивает поведение только для чтения. Обычно используется для создания прокси, предотвращающего изменение словаря для нединамических типов классов. Новое в версии 2.2. **void `PyDict_Clear`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)** Очищает существующий словарь от всех пар ключ-значение. **int `PyDict_Contains`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*key*)** Определяет, содержит ли словарь *p* ключ *key*. Если элемент в *p* совпадает с *key*, возвращается `1`, в противном случае возвращается `0`. При ошибке возвращается `-1`. Это эквивалентно выражению Python `key in p`. Новое в версии 2.4. **[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_Copy`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)** *Возвращаемое значение: новая ссылка.* Возвращает новый словарь, содержащий те же пары ключ-значение, что и *p*. Новое в версии 1.6. **int `PyDict_SetItem`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*key*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*val*)** Вставляет значение *value* в словарь *p* с ключом *key* . Ключ *key* должен быть [*hashable*](https://python-all.ru/2.6/glossary.html#term-hashable) ; если нет, будет возбуждено исключение [`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError) . При успехе возвращается `0` , при ошибке – `-1` . **int `PyDict_SetItemString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, const char *\*key*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*val*)** Вставляет *value* в словарь *p* по ключу *key*. *key* должен быть типа `char*`. Объект ключа создаётся с помощью `PyString_FromString(key)`. Возвращает `0` в случае успеха или `-1` в случае ошибки. **int `PyDict_DelItem`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*key*)** Удаляет запись из словаря *p* с ключом *key* . Ключ *key* должен быть хешируемым; если нет, возбуждается [`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError) . При успехе возвращается `0` , при ошибке – `-1` . **int `PyDict_DelItemString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, char *\*key*)** Удаляет запись из словаря *p* , ключ которой задаётся строкой *key* . Возвращает `0` при успехе или `-1` при неудаче. **[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_GetItem`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*key*)** *Возвращаемое значение: заимствованная ссылка.* Возвращает объект из словаря *p* с ключом *key*. Возвращает *NULL* если ключ *key* отсутствует, но *без* установки исключения. **[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_GetItemString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, const char *\*key*)** *Возвращаемое значение: заимствованная ссылка.* То же, что и [`PyDict_GetItem()`](https://python-all.ru/2.6/c-api/dict.html#PyDict_GetItem), но ключ *key* задаётся как `char*`, а не как [`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject). **[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_Items`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)** *Возвращаемое значение: новая ссылка.* Возвращает [`PyListObject`](https://python-all.ru/2.6/c-api/list.html#PyListObject), содержащий все элементы из словаря, как и метод словаря [`dict.items()`](https://python-all.ru/2.6/library/stdtypes.html#dict.items). **[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_Keys`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)** *Возвращаемое значение: новая ссылка.* Возвращает [`PyListObject`](https://python-all.ru/2.6/c-api/list.html#PyListObject), содержащий все ключи из словаря, как и метод словаря [`dict.keys()`](https://python-all.ru/2.6/library/stdtypes.html#dict.keys). **[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_Values`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)** *Возвращаемое значение: новая ссылка.* Возвращает [`PyListObject`](https://python-all.ru/2.6/c-api/list.html#PyListObject), содержащий все значения из словаря *p*, как и метод словаря [`dict.values()`](https://python-all.ru/2.6/library/stdtypes.html#dict.values). **Py\_ssize\_t `PyDict_Size`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)** Возвращает количество элементов в словаре. Это эквивалентно `len(p)` для словаря. Изменено в версии 2.5: Ранее эта функция возвращала тип `int`. Это может потребовать изменений в вашем коде для корректной поддержки 64-разрядных систем. **int `PyDict_Next`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, Py\_ssize\_t *\*ppos*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*pkey*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*pvalue*)** Перебирает все пары ключ-значение в словаре *p*. Переменная `Py_ssize_t`, на которую ссылается *ppos*, должна быть инициализирована значением `0` до первого вызова этой функции для начала итерации; функция возвращает true для каждой пары в словаре и false, когда все пары были перебраны. Параметры *pkey* и *pvalue* должны либо указывать на переменные типа [`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject), которые будут заполнены соответствующими ключом и значением, либо могут быть *NULL*. Любые ссылки, возвращаемые через них, являются заимствованными. *ppos* не должен изменяться во время итерации. Его значение представляет собой смещения во внутренней структуре словаря, и поскольку структура разрежена, смещения не являются последовательными. Например: ```c PyObject *key, *value; Py_ssize_t pos = 0; while (PyDict_Next(self->dict, &pos, &key, &value)) { /* сделайте что-нибудь интересное со значениями... */ ... } ``` Словарь *p* не должен изменяться во время итерации. Начиная с Python 2.1 безопасно изменять значения ключей в процессе итерации по словарю, но только до тех пор, пока набор ключей не меняется. Например: ```c PyObject *key, *value; Py_ssize_t pos = 0; while (PyDict_Next(self->dict, &pos, &key, &value)) { int i = PyInt_AS_LONG(value) + 1; PyObject *o = PyInt_FromLong(i); if (o == NULL) return -1; if (PyDict_SetItem(self->dict, key, o) < 0) { Py_DECREF(o); return -1; } Py_DECREF(o); } ``` Изменено в версии 2.5: Ранее эта функция использовала тип `int *` для *ppos*. Это может потребовать изменений в вашем коде для корректной поддержки 64-разрядных систем. **int `PyDict_Merge`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*b*, int *override*)** Перебирает объект отображения *b*, добавляя пары ключ-значение в словарь *a*. *b* может быть словарём или любым объектом, поддерживающим [`PyMapping_Keys()`](https://python-all.ru/2.6/c-api/mapping.html#PyMapping_Keys) и [`PyObject_GetItem()`](https://python-all.ru/2.6/c-api/object.html#PyObject_GetItem). Если *override* истинно, существующие пары в *a* будут заменены, если найден соответствующий ключ в *b*; в противном случае пары будут добавлены только при отсутствии соответствующего ключа в *a*. Возвращает `0` в случае успеха или `-1`, если было возбуждено исключение. Новое в версии 2.2. **int `PyDict_Update`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*b*)** То же самое, что `PyDict_Merge(a, b, 1)` в C, или `a.update(b)` в Python. Возвращает `0` при успехе или `-1`, если было возбуждено исключение. Новое в версии 2.2. **int `PyDict_MergeFromSeq2`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*seq2*, int *override*)** Обновляет или объединяет словарь *a*, используя пары ключ-значение из *seq2*. *seq2* должен быть итерируемым объектом, который возвращает итерируемые объекты длины 2, рассматриваемые как пары ключ-значение. При повторяющихся ключах последнее значение побеждает, если *override* истинно, иначе первое. Возвращает `0` при успехе или `-1`, если возникло исключение. Эквивалент на Python (за исключением возвращаемого значения): ```c def PyDict_MergeFromSeq2(a, seq2, override): for key, value in seq2: if override or key not in a: a[key] = value ``` Новое в версии 2.2.