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

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.

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

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.

Удаляет запись в словаре p, имеющую ключ, заданный строкой key. Если key отсутствует в словаре, возбуждается KeyError. Возвращает 0 при успехе или -1 при неудаче.

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 задается как const char*, а не как PyObject*.

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

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

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

Это то же самое, что и dict.setdefault() на уровне Python. Если присутствует, возвращает значение, соответствующее 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