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

type PyDictObject: Этот подтип PyObject представляет собой объект словаря Python.

PyTypeObject PyDict_Type: Часть Стабильной ABI.
Этот экземпляр PyTypeObject представляет собой тип словаря Python. Это тот же объект, что и dict на уровне Python.

int PyDict_Check(PyObject *p): Возвращает true, если p является объектом словаря или экземпляром подтипа типа словаря. Эта функция всегда выполняется успешно.

int PyDict_CheckExact(PyObject *p): Возвращает true, если p является объектом словаря, но не экземпляром подтипа типа словаря. Эта функция всегда выполняется успешно.

PyObject *PyDict_New(): Возвращаемое значение: новая ссылка. Часть Стабильной ABI.
Возвращает новый пустой словарь или NULL в случае ошибки.

PyObject *PyDictProxy_New(PyObject *mapping): Возвращаемое значение: новая ссылка. Часть Стабильной ABI.
Возвращает объект types.MappingProxyType для отображения, который обеспечивает поведение только для чтения. Обычно используется для создания представления, чтобы предотвратить изменение словаря для типов классов, не требующих динамики.

void PyDict_Clear(PyObject *p): Часть Стабильной ABI.
Очищает существующий словарь от всех пар ключ-значение.

int PyDict_Contains(PyObject *p, PyObject *key): Часть Стабильной ABI.
Определяет, содержит ли словарь p ключ key. Если элемент в p соответствует key, возвращает 1, в противном случае возвращает 0. В случае ошибки возвращает -1. Эквивалентно выражению Python key in p.

PyObject *PyDict_Copy(PyObject *p): Возвращаемое значение: новая ссылка. Часть Стабильной ABI.
Возвращает новый словарь, содержащий те же пары ключ-значение, что и p.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val): Часть Стабильной ABI.
Вставляет val в словарь p с ключом key. key должен быть хешируемым; если нет, будет поднято исключение TypeError. Возвращает 0 при успехе или -1 при ошибке. Эта функция не заимствует ссылку на val.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val): Часть Стабильной ABI.
Это то же самое, что и PyDict_SetItem(), но key задаётся как строка UTF-8 const char*, а не PyObject*.

int PyDict_DelItem(PyObject *p, PyObject *key): Часть Стабильной ABI.
Удаляет запись в словаре p с ключом key. key должен быть хешируемым; если нет, поднимается исключение TypeError. Если key отсутствует в словаре, поднимается исключение KeyError. Возвращает 0 при успехе или -1 при ошибке.

int PyDict_DelItemString(PyObject *p, const char *key): Часть Стабильной ABI.
Это то же самое, что и PyDict_DelItem(), но key задаётся как строка UTF-8 const char*, а не PyObject*.

PyObject *PyDict_GetItem(PyObject *p, PyObject *key): Возвращаемое значение: заимствованная ссылка. Часть Стабильной ABI.
Возвращает объект из словаря p, имеющий ключ key. Возвращает NULL если ключ key отсутствует, но без установки исключения.

Примечание

Исключения, возникающие при вызове методов __hash__() и __eq__(), игнорируются. Вместо этого используйте функцию PyDict_GetItemWithError().

Изменено в версии 3.10: Доступ к этому API без удержания GIL был разрешен по историческим причинам. Сейчас это запрещено.

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key): Возвращаемое значение: заимствованная ссылка. Часть Стабильной ABI.
Вариант PyDict_GetItem(), который не подавляет исключения. Возвращает NULL с установленным исключением, если произошла ошибка. Возвращает NULL без установленного исключения, если ключ отсутствовал.

PyObject *PyDict_GetItemString(PyObject *p, const char *key): Возвращаемое значение: заимствованная ссылка. Часть Стабильной ABI.
Это то же самое, что и PyDict_GetItem(), но key задаётся как строка UTF-8 const char*, а не PyObject*.

Примечание

Исключения, возникающие при вызове методов __hash__() и __eq__(), или при создании временного объекта str, игнорируются. Вместо этого используйте функцию PyDict_GetItemWithError() с собственным PyUnicode_FromString() key.

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj): Возвращаемое значение: заимствованная ссылка.
Это эквивалентно выражению Python-уровня dict.setdefault(). Если ключ key присутствует, возвращает соответствующее значение из словаря p. Если ключа нет, вставляет его со значением defaultobj и возвращает defaultobj. Эта функция вычисляет хеш-функцию key только один раз, а не независимо для поиска и вставки.

Добавлено в версии 3.4.

PyObject *PyDict_Items(PyObject *p): Значение возврата: Новая ссылка. Часть Стабильной ABI.
Возвращает PyListObject содержащий все элементы из словаря.

PyObject *PyDict_Keys(PyObject *p): Значение возврата: Новая ссылка. Часть Стабильной ABI.
Возвращает PyListObject содержащий все ключи из словаря.

PyObject *PyDict_Values(PyObject *p): Значение возврата: Новая ссылка. Часть Стабильной ABI.
Возвращает PyListObject содержащий все значения из словаря p.

Py_ssize_t PyDict_Size(PyObject *p): Часть Стабильной ABI.
Возвращает количество элементов в словаре. Это эквивалентно len(p) для словаря.

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

Часть Стабильной ABI.

Перебирает все пары ключ-значение в словаре p. Py_ssize_t, на который ссылается ppos, должен быть инициализирован значением 0 перед первым вызовом этой функции для начала итерации; функция возвращает true для каждой пары в словаре и false, когда все пары были обработаны. Параметры pkey и pvalue должны указывать на переменные PyObject*, которые будут заполнены соответствующим ключом и значением соответственно, или могут быть NULL. Любые ссылки, возвращаемые через них, берутся напрокат. ppos не следует изменять во время итерации. Его значение представляет смещения внутри внутренней структуры словаря, а поскольку структура разреженная, смещения не являются последовательными.

Например:

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

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* do something interesting with the values... */
    ...
}

Словарь p не должен изменяться во время итерации. Безопасно изменять значения ключей во время итерации по словарю, но только до тех пор, пока множество ключей не изменится. Например:

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): Часть Стабильной ABI.
Итерируется по отображаемому объекту b, добавляя пары ключ-значение в словарь a. b может быть словарем или любым объектом, поддерживающим PyMapping_Keys() и PyObject_GetItem(). Если override равно true, существующие пары в a будут заменены, если в b найден соответствующий ключ; в противном случае пары будут добавлены только в том случае, если в a нет соответствующего ключа. Возвращает 0 при успехе или -1 если произошла ошибка.

int PyDict_Update(PyObject *a, PyObject *b): Часть Стабильной ABI.
Это то же самое, что PyDict_Merge(a, b, 1) в C и похоже на a.update(b) в Python, за исключением того, что PyDict_Update() не возвращается к итерации по последовательности пар ключ-значение, если у второго аргумента нет атрибута «keys». Возвращает 0 при успехе или -1 при возникновении ошибки.

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

Часть Стабильной ABI.

Обновляет или объединяет словарь a из пар ключ-значение в seq2. seq2 должен быть итерируемым объектом, производящим итерируемые объекты длины 2, рассматриваемые как пары ключ-значение. В случае дублирования ключей последний побеждает, если override равно true, иначе побеждает первый. Возвращает 0 при успехе или -1 при возникновении ошибки. Эквивалентный Python (кроме значения возврата):

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value