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

type PyDictObject

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

PyTypeObject PyDict_Type

Часть стабильного 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()

Возвращаемое значение: новая ссылка.Часть стабильного 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. Если ключ key отсутствует, возвращает NULL, но не устанавливает исключение.

Примечание

Исключения, возникающие при вызове этой функцией методов __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() с собственным ключом key, созданным с помощью PyUnicode_FromString().

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

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

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

В языке C эта функция работает так же, как PyDict_Merge(a, b, 1), а в Python похожа на a.update(b), за исключением того, что 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

int PyDict_AddWatcher(PyDict_WatchCallback callback)

Регистрирует callback как функцию обратного вызова — наблюдателя словаря. Возвращает неотрицательный целочисленный идентификатор, который необходимо передавать в последующие вызовы PyDict_Watch(). В случае ошибки (например, если идентификаторы наблюдателей закончились) возвращает -1 и устанавливает исключение.

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

int PyDict_ClearWatcher(int watcher_id)

Удаляет наблюдателя с идентификатором watcher_id, ранее возвращённым функцией PyDict_AddWatcher(). При успешном выполнении возвращает 0, при ошибке — -1 (например, если указанный watcher_id никогда не регистрировался).

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

int PyDict_Watch(int watcher_id, PyObject *dict)

Помечает словарь dict как отслеживаемый. Функция обратного вызова, назначенная идентификатору watcher_id функцией PyDict_AddWatcher(), будет вызвана при изменении или освобождении dict. При успешном выполнении возвращает 0, при ошибке — -1.

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

int PyDict_Unwatch(int watcher_id, PyObject *dict)

Снимает с dict отметку об отслеживании. Функция обратного вызова, назначенная идентификатору watcher_id функцией PyDict_AddWatcher(), больше не будет вызываться при изменении или освобождении dict. Ранее этот наблюдатель должен был начать отслеживать словарь. При успешном выполнении возвращает 0, при ошибке — -1.

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

type PyDict_WatchEvent

Перечисление возможных событий наблюдателя словаря: PyDict_EVENT_ADDED, PyDict_EVENT_MODIFIED, PyDict_EVENT_DELETED, PyDict_EVENT_CLONED, PyDict_EVENT_CLEARED или PyDict_EVENT_DEALLOCATED.

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

typedef int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)

Тип функции обратного вызова наблюдателя словаря.

Если event имеет значение PyDict_EVENT_CLEARED или PyDict_EVENT_DEALLOCATED, и key, и new_value будут равны NULL. Если event имеет значение PyDict_EVENT_ADDED или PyDict_EVENT_MODIFIED, new_value будет новым значением для key. Если event имеет значение PyDict_EVENT_DELETED, ключ key удаляется из словаря, а new_value будет равен NULL.

Событие PyDict_EVENT_CLONED возникает, когда dict ранее был пуст, а в него объединяется другой словарь. Для повышения эффективности этой операции в таком случае не генерируются события PyDict_EVENT_ADDED для отдельных ключей; вместо этого генерируется одно событие PyDict_EVENT_CLONED, а в качестве key передаётся исходный словарь.

Функция обратного вызова может просматривать dict, но не должна его изменять: это может привести к непредсказуемым последствиям, в том числе к бесконечной рекурсии. Не запускайте выполнение кода Python в функции обратного вызова, поскольку такой код может изменить словарь как побочный эффект.

Если event имеет значение PyDict_EVENT_DEALLOCATED, создание в функции обратного вызова новой ссылки на словарь, который собираются уничтожить, воскресит его и не позволит освободить в этот момент. Когда воскресший объект будет уничтожен позднее, будут вызваны все наблюдатели, активные в этот момент.

Функции обратного вызова вызываются до внесения уведомляемого изменения в dict, поэтому можно просмотреть предыдущее состояние dict.

Если функция обратного вызова устанавливает исключение, она должна вернуть -1; это исключение будет выведено как необрабатываемое с помощью PyErr_WriteUnraisable(). В противном случае она должна вернуть 0.

При входе в функцию обратного вызова уже может быть установлено ожидающее исключение. В этом случае функция должна вернуть 0, оставив то же исключение установленным. Это означает, что функция обратного вызова не может вызывать другие API, способные установить исключение, если сначала не сохранит и не сбросит состояние исключения и не восстановит его перед возвратом.

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