> **Источник:** https://python-all.ru/3.0/c-api/dict.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Объекты словарей

**\[PyDictObject\]`PyDictObject`**

Этот подтип

[`PyObject`](https://python-all.ru/3.0/c-api/structures.html#PyObject)

представляет объект словаря Python.

**\[PyDict\_Type\][PyTypeObject](https://python-all.ru/3.0/c-api/type.html#PyTypeObject) `PyDict_Type`**

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.0/c-api/type.html#PyTypeObject) представляет тип словаря Python. Он доступен программам на Python как `dict` и `types.DictType`.

**\[PyDict\_Check\]int `PyDict_Check`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**

Возвращает true, если

*p*

является объектом dict или экземпляром подтипа типа dict.

**\[PyDict\_CheckExact\]int `PyDict_CheckExact`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**

Возвращает истину, если

*p*

является объектом словаря, но не экземпляром подтипа типа dict.

**\[PyDict\_New\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyDict_New`()**

*Возвращаемое значение: новая ссылка.*

Возвращает новый пустой словарь или *NULL* в случае ошибки.

**\[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*)**

*Возвращаемое значение: новая ссылка.*

Возвращает прокси-объект для отображения, обеспечивающий доступ только для чтения. Обычно используется для создания прокси, предотвращающего изменение словаря для нединамических типов классов.

**\[PyDict\_Clear\]void `PyDict_Clear`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**

Очищает существующий словарь от всех пар ключ-значение.

**\[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*)**

Определяет, содержит ли словарь

*p*

ключ

*key*

. Если элемент в

*p*

совпадает с

*key*

, возвращает

`1`

, в противном случае возвращает

`0`

. При ошибке возвращает

`-1`

. Эквивалентно выражению Python

`key in p`

.

**\[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*)**

*Возвращаемое значение: новая ссылка.*

Возвращает новый словарь, содержащий те же пары ключ-значение, что и *p*.

**\[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*)**

Вставляет

*value*

в словарь

*p*

с ключом

*key*

.

*key*

должен быть

[*хэшируемым*](https://python-all.ru/3.0/glossary.html#term-hashable)

; если это не так, возбуждается

[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)

. Возвращает

`0`

при успехе или

`-1`

при неудаче.

**\[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*)**

Вставляет *value* в словарь *p*, используя *key* в качестве ключа. *key* должен быть типа `char*`. Объект ключа создаётся с помощью `PyString_FromString(key)`. Возвращает `0` при успехе или `-1` при неудаче.

**\[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*)**

Удаляет запись из словаря

*p*

с ключом

*key*

.

*key*

должен быть хэшируемым; если это не так, возбуждается

[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)

. Возвращает

`0`

при успехе или

`-1`

при неудаче.

**\[PyDict\_DelItemString\]int `PyDict_DelItemString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*, char *\*key*)**

Удаляет запись из словаря

*p*

, ключ которой задаётся строкой

*key*

. Возвращает

`0`

при успехе или

`-1`

при неудаче.

**\[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*)**

*Возвращаемое значение: заимствованная ссылка.*

Возвращает объект из словаря *p*, имеющий ключ *key*. Возвращает *NULL*, если ключ *key* отсутствует, но *без* установки исключения.

**\[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*)**

Вариант

[`PyDict_GetItem`](https://python-all.ru/3.0/c-api/dict.html#PyDict_GetItem)

, который не подавляет исключения. Возвращает

*NULL*

**с**

установленным исключением, если произошла ошибка. Возвращает

*NULL*

**без**

установленного исключения, если ключ отсутствовал.

**\[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*)**

*Возвращаемое значение: заимствованная ссылка.*

То же самое, что [`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).

**\[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*)**

*Возвращаемое значение: новая ссылка.*

Возвращает [`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).

**\[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*)**

*Возвращаемое значение: новая ссылка.*

Возвращает [`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).

**\[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*)**

*Возвращаемое значение: новая ссылка.*

Возвращает [`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).

**\[PyDict\_Size\]Py\_ssize\_t `PyDict_Size`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*p*)**

Возвращает количество элементов в словаре. Это эквивалентно `len(p)` для словаря.

**\[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*)**

Проходит по всем парам ключ-значение в словаре *p*. Переменная типа `int`, на которую ссылается *ppos*, должна быть инициализирована значением `0` до первого вызова этой функции для начала итерации; функция возвращает true для каждой пары в словаре и false после того, как все пары были выданы. Параметры *pkey* и *pvalue* должны либо указывать на переменные типа [`PyObject*`](https://python-all.ru/3.0/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* не должен изменяться во время итерации. Можно безопасно изменять значения ключей в процессе итерации, но только при условии, что набор ключей не меняется. Например:

```c
PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    long i = PyLong_AsLong(value);
    if (i == -1 && PyErr_Occurred()) {
        return -1;
    }
    PyObject *o = PyLong_FromLong(i + 1);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}
```

**\[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*)**

Проходит по объекту отображения

*b*

, добавляя пары ключ-значение в словарь

*a*

.

*b*

может быть словарём или любым объектом, поддерживающим

[`PyMapping_Keys()`](https://python-all.ru/3.0/c-api/mapping.html#PyMapping_Keys)

и

[`PyObject_GetItem()`](https://python-all.ru/3.0/c-api/object.html#PyObject_GetItem)

. Если

*override*

истинно, существующие пары в

*a*

будут заменены при нахождении совпадающего ключа в

*b*

; в противном случае пары будут добавлены, только если нет совпадающего ключа в

*a*

. Возвращает

`0`

при успехе или

`-1`

, если было возбуждено исключение.

**\[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*)**

То же самое, что

`PyDict_Merge(a, b, 1)`

в C, или

`a.update(b)`

в Python. Возвращает

`0`

при успехе или

`-1`

, если было возбуждено исключение.

**\[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*)**

Обновляет или сливает словарь *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
```