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

---

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

#### `type PyDictObject`

Этот подтип [`PyObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyObject) представляет объект словаря Python.

#### `PyTypeObject PyDict_Type`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.10/c-api/type.html#c.PyTypeObject) представляет тип словаря Python. Это тот же объект, что и [`dict`](https://python-all.ru/3.10/library/stdtypes.html#dict) на уровне Python.

#### `int PyDict_Check(PyObject *p)`

Возвращает True, если *p* – объект dict или экземпляр подтипа типа dict. Эта функция всегда завершается успешно.

#### `int PyDict_CheckExact(PyObject *p)`

Возвращает True, если *p* – объект dict, но не экземпляр подтипа типа dict. Эта функция всегда завершается успешно.

#### `PyObject *PyDict_New()`

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

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

#### `PyObject *PyDictProxy_New(PyObject *mapping)`

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

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

Возвращает объект [`types.MappingProxyType`](https://python-all.ru/3.10/library/types.html#types.MappingProxyType) для отображения, которое принудительно обеспечивает режим только для чтения. Обычно используется для создания представления, предотвращающего изменение словаря для нединамических типов классов.

#### `void PyDict_Clear(PyObject *p)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

#### `int PyDict_Contains(PyObject *p, PyObject *key)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

Определяет, содержит ли словарь *p* ключ *key*. Если элемент в *p* совпадает с *key*, возвращает `1`, иначе возвращает `0`. В случае ошибки возвращает `-1`. Это эквивалентно выражению Python `key in p`.

#### `PyObject *PyDict_Copy(PyObject *p)`

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

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

#### `int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

Вставляет *val* в словарь *p* с ключом *key*. *key* должен быть [хешируемым](https://python-all.ru/3.10/glossary.html#term-hashable); в противном случае будет возбуждено [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError). Возвращает `0` в случае успеха или `-1` при неудаче. Эта функция *не* похищает ссылку на *val*.

#### `int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

#### `int PyDict_DelItem(PyObject *p, PyObject *key)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

Удаляет запись из словаря *p* с ключом *key*. *key* должен быть [хэшируемым](https://python-all.ru/3.10/glossary.html#term-hashable); если нет, возбуждается [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError). Если *key* отсутствует в словаре, возбуждается [`KeyError`](https://python-all.ru/3.10/library/exceptions.html#KeyError). Возвращает `0` при успехе или `-1` при неудаче.

#### `int PyDict_DelItemString(PyObject *p, const char *key)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

Удаляет запись из словаря *p*, ключ которой задаётся строкой *key*. Если *key* нет в словаре, возбуждается исключение [`KeyError`](https://python-all.ru/3.10/library/exceptions.html#KeyError). Возвращает `0` в случае успеха или `-1` в случае ошибки.

#### `PyObject *PyDict_GetItem(PyObject *p, PyObject *key)`

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

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

Обратите внимание, что исключения, возникающие при вызове методов `__hash__()` и `__eq__()`, подавляются. Для получения сообщений об ошибках используйте вместо этого [`PyDict_GetItemWithError()`](https://python-all.ru/3.10/c-api/dict.html#c.PyDict_GetItemWithError).

Изменено в версии 3.10: Вызов этого API без удержания [GIL](https://python-all.ru/3.10/glossary.html#term-GIL) ранее допускался по историческим причинам. Теперь это не допускается.

#### `PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)`

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

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

Вариант [`PyDict_GetItem()`](https://python-all.ru/3.10/c-api/dict.html#c.PyDict_GetItem), который не подавляет исключения. Возвращает `NULL` **с** установленным исключением, если произошло исключение. Возвращает `NULL` **без** установленного исключения, если ключ отсутствовал.

#### `PyObject *PyDict_GetItemString(PyObject *p, const char *key)`

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

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

Обратите внимание, что исключения, возникающие при вызове методов `__hash__()` и `__eq__()` и при создании временного строкового объекта, подавляются. Для получения сообщений об ошибках используйте вместо этого [`PyDict_GetItemWithError()`](https://python-all.ru/3.10/c-api/dict.html#c.PyDict_GetItemWithError).

#### `PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)`

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

Это то же самое, что и функция [`dict.setdefault()`](https://python-all.ru/3.10/library/stdtypes.html#dict.setdefault) на уровне Python. Если значение присутствует, она возвращает значение, соответствующее *key*, из словаря *p*. Если ключ отсутствует в словаре, он вставляется со значением *defaultobj* и возвращается *defaultobj*. Эта функция вычисляет хеш-функцию для *key* только один раз, вместо того чтобы вычислять её отдельно для поиска и вставки.

Новое в версии 3.4.

#### `PyObject *PyDict_Items(PyObject *p)`

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

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

#### `PyObject *PyDict_Keys(PyObject *p)`

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

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

#### `PyObject *PyDict_Values(PyObject *p)`

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

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

#### `Py_ssize_t PyDict_Size(PyObject *p)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

#### `int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

Перебирает объект отображения *b*, добавляя пары ключ-значение в словарь *a*. *b* может быть словарем или любым объектом, поддерживающим [`PyMapping_Keys()`](https://python-all.ru/3.10/c-api/mapping.html#c.PyMapping_Keys) и [`PyObject_GetItem()`](https://python-all.ru/3.10/c-api/object.html#c.PyObject_GetItem). Если *override* равно true, существующие пары в *a* будут заменены, если найден совпадающий ключ в *b*; в противном случае пары будут добавлены только если нет совпадающего ключа в *a*. Возвращает `0` при успехе или `-1`, если было возбуждено исключение.

#### `int PyDict_Update(PyObject *a, PyObject *b)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

То же самое, что и `PyDict_Merge(a, b, 1)` в C, и похоже на `a.update(b)` в Python, за исключением того, что [`PyDict_Update()`](https://python-all.ru/3.10/c-api/dict.html#c.PyDict_Update) не переходит к итерации по последовательности пар ключ-значение, если у второго аргумента нет атрибута “keys”. Возвращает `0` при успехе или `-1`, если было возбуждено исключение.

#### `int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

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