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

---

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

**`PyDictObject`**

Этот подтип

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

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

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

Этот экземпляр

[`PyTypeObject`](https://python-all.ru/3.1/c-api/type.html#PyTypeObject)

представляет тип словаря Python. Это тот же объект, что и

[`dict`](https://python-all.ru/3.1/library/stdtypes.html#dict)

на уровне Python.

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

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

*p*

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

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

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

*p*

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

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

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

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

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDictProxy_New`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*dict*)**

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

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

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

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

**int `PyDict_Contains`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*key*)**

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

*p*

ключ

*key*

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

*p*

совпадает с

*key*

, возвращается

`1`

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

`0`

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

`-1`

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

`key in p`

.

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_Copy`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**

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

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

**int `PyDict_SetItem`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*key*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*val*)**

Вставляет значение

*value*

в словарь

*p*

с ключом

*key*

. Ключ

*key*

должен быть

[*hashable*](https://python-all.ru/3.1/glossary.html#term-hashable)

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

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

. При успехе возвращается

`0`

, при ошибке –

`-1`

.

**int `PyDict_SetItemString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, const char *\*key*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*val*)**

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

**int `PyDict_DelItem`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*key*)**

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

*p*

с ключом

*key*

. Ключ

*key*

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

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

. При успехе возвращается

`0`

, при ошибке –

`-1`

.

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

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

*p*

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

*key*

. Возвращает

`0`

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

`-1`

при неудаче.

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_GetItem`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*key*)**

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

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

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_GetItemWithError`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*key*)**

Вариант

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

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

*NULL*

**с**

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

*NULL*

**без**

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

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_GetItemString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, const char *\*key*)**

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

То же, что и [`PyDict_GetItem()`](https://python-all.ru/3.1/c-api/dict.html#PyDict_GetItem), но ключ *key* задаётся как `char*`, а не как [`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject).

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_Items`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**

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

Возвращает [`PyListObject`](https://python-all.ru/3.1/c-api/list.html#PyListObject), содержащий все элементы из словаря.

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_Keys`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**

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

Возвращает [`PyListObject`](https://python-all.ru/3.1/c-api/list.html#PyListObject), содержащий все ключи из словаря.

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_Values`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**

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

Возвращает [`PyListObject`](https://python-all.ru/3.1/c-api/list.html#PyListObject), содержащий все значения из словаря *p*.

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

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

**int `PyDict_Next`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, Py\_ssize\_t *\*ppos*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*\*pkey*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*\*pvalue*)**

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

**int `PyDict_Merge`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*b*, int *override*)**

Перебирает объект отображения

*b*

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

*a*

.

*b*

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

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

и

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

. Если

*override*

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

*a*

будут заменены, если найден соответствующий ключ в

*b*

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

*a*

. Возвращает

`0`

в случае успеха или

`-1`

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

**int `PyDict_Update`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*b*)**

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

`PyDict_Merge(a, b, 1)`

в C, или

`a.update(b)`

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

`0`

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

`-1`

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

**int `PyDict_MergeFromSeq2`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/3.1/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
```