Словари объектов

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

PyTypeObject PyDict_Type: Эта instance of PyTypeObject представляет тип словаря Python. Это тот же объект, что и dict в слое Python.

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

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

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

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

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

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

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

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

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

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

int PyDict_DelItemString(PyObject *p, const char *key): Удаляет запись в словаре p, у которой ключ задан строкой key. Если key не в словаре, возникает KeyError. Возвращает 0 при успехе или -1 при ошибке.

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

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

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

Обратите внимание, что исключения, которые возникают при вызове методов __hash__() и __eq__(), будут подавлены. Чтобы получить отчет об ошибках, используйте PyDict_GetItemWithError() вместо этого.

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

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

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

Это то же самое, что и PyDict_GetItem(), но key указан как const char*, а не как PyObject*.

Обратите внимание, что исключения, которые возникают при вызове методов __hash__() и __eq__(), и создании временного строкового объекта, будут подавлены. Чтобы получить отчет об ошибках, используйте PyDict_GetItemWithError() вместо этого.

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

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

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

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

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

Py_ssize_t PyDict_Size(PyObject *p): Возвращает количество элементов в словаре. Это эквивалентно len(p) в словаре.

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

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

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

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

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