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

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.
Это то же самое, что 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. Возвращает 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 задаётся как строка байтов UTF-8 const char*, а не как PyObject*.

Примечание

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

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

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

END_OF_DOCUMENT_MARKER

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

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

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

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