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

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.

int PyDict_ContainsString(PyObject *p, const char *key): Это то же самое, что и PyDict_Contains(), но key задаётся как строка UTF-8 кодированных байтов const char*, а не как PyObject*.

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

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*.

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)

Часть Стабильного ABI с версии 3.13.

Возвращает новую сильную ссылку на объект из словаря p, имеющий ключ key:

Если ключ присутствует, установить *result в новую сильную ссылку на значение и вернуть 1.
Если ключ отсутствует, установить *result в NULL и вернуть 0.
В случае ошибки поднять исключение и вернуть -1.

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

См. также функцию PyObject_GetItem().

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 без установленного исключения, если ключ отсутствовал.

END_OF_DOCUMENT_MARKER

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

Примечание

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

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result): Часть Стабильной ABI с версии 3.13.
Аналогично PyDict_GetItemRef(), но ключ задаётся как строка UTF-8, закодированная в const char*, а не как PyObject*.

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

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

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

int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)

Вставляет default_value в словарь p с ключом key, если ключ ещё не присутствует в словаре. Если result не NULL, то *result устанавливается на сильную ссылку либо на default_value, если ключ отсутствовал, либо на существующее значение, если ключ уже присутствовал в словаре. Возвращает 1 если ключ был найден и default_value не вставлялся, или 0 если ключ не был найден и default_value был вставлен. В случае ошибки, возвращает -1, устанавливает исключение и устанавливает *result в NULL.

Для ясности: если у вас есть сильная ссылка на default_value перед вызовом этой функции, то после её возвращения у вас есть сильная ссылка как на default_value, так и на *result (если это не NULL). Они могут ссылаться на один и тот же объект: в этом случае у вас две отдельные ссылки на него.

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

int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)

Удаляет ключ из словаря p и, при необходимости, возвращает удалённое значение. Не поднимает KeyError, если ключ отсутствует.

Если ключ присутствует, устанавливает *result на новую ссылку на удалённое значение, если result не NULL, и возвращает 1.
Если ключ отсутствует, устанавливает *result на NULL , если result не NULL, и возвращает 0.
В случае ошибки, поднимает исключение и возвращает -1.

Это аналогично dict.pop(), но без значения по умолчанию и не поднимает KeyError, если ключ отсутствует.

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

int PyDict_PopString(PyObject *p, const char *key, PyObject **result): Аналогично PyDict_Pop(), но ключ задаётся как строка UTF-8, закодированная в const char*, а не как PyObject*.

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

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);
}

Функция не является потокобезопасной в сборке с свободными потоками без внешней синхронизации. Можно использовать Py_BEGIN_CRITICAL_SECTION для блокировки словаря во время итерации:

Py_BEGIN_CRITICAL_SECTION(self->dict);
while (PyDict_Next(self->dict, &pos, &key, &value)) {
    ...
}
Py_END_CRITICAL_SECTION();

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 истина, иначе — первая. Возвращает 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 как наблюдателя за словарем. Возвращает ненулевое целое число ID, которое необходимо передавать в последующие вызовы PyDict_Watch(). В случае ошибки (например, закончились доступные ID наблюдателей) возвращает -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.