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

PyDictObject

Подтип PyObject представляет объект словаря Python.

PyTypeObject PyDict_Type

Сущность PyTypeObject представляет тип словаря Python. Это тот же объект, что и dict в Python слое.

int PyDict_Check(PyObject *p)

Возвращает true, если p является объектом словарем или сущностью подтипа типа словарь.

int PyDict_CheckExact(PyObject *p)

Возвращает true, если p является объектом словарья, но не сущностью подтипа типа словарь.

PyObject* PyDict_New()
Return value: New reference.

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

PyObject* PyDictProxy_New(PyObject *mapping)
Return value: New reference.

Возвращает объект 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)
Return value: New reference.

Возвращает новый словарь, содержащий те же ключ-значение пары, что и 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)
Return value: Borrowed reference.

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

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

PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
Return value: Borrowed reference.

Вариант PyDict_GetItem(), который не подавляет исключения. Возвращает NULL с исключением, если возникло исключение. Возвращает NULL без набора исключений, если ключ отсутствует.

PyObject* PyDict_GetItemString(PyObject *p, const char *key)
Return value: Borrowed reference.

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

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

PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
Return value: Borrowed reference.

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

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

PyObject* PyDict_Items(PyObject *p)
Return value: New reference.

Возвращает PyListObject, содержащий все элементы словаря.

PyObject* PyDict_Keys(PyObject *p)
Return value: New reference.

Возвращает PyListObject, содержащий все ключи из словаря.

PyObject* PyDict_Values(PyObject *p)
Return value: New reference.

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

Не следует изменять 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() не возвращается к итерации по последовательности пар ключевых значений, если второй аргумент не имеет атрибут «keys». Возвращает 0 при успехе или -1, если возникло исключение.

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

Обновление или объединение в словаре 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
int PyDict_ClearFreeList()

Очистить свободный список. Возвращает общее количество освобожденных элементов.

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