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

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

PyTypeObject PyDict_Type¶: Часть Stable ABI.
Этот экземпляр PyTypeObject представляет тип словаря Python. Это тот же объект, что и 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.
Возвращает новый пустой словарь или NULL в случае ошибки.

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

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

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

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

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

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

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

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

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

Примечание

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

Изменено в версии 3.10: Вызов этого API без удержания GIL ранее допускался по историческим причинам. Теперь это не допускается.

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

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

Примечание

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

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

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

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

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

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

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

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

Часть Stable 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)) {
    /* сделайте что-нибудь интересное со значениями... */
    ...
}

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

int PyDict_Update(PyObject *a, PyObject *b)¶: Часть Stable 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)¶

Часть Stable ABI.

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

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