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

type PyDictObject¶: Этот подтип PyObject представляет объект словаря Python.

PyTypeObject PyDict_Type¶: Часть Stable 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()¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Возвращает новый пустой словарь или NULL в случае ошибки.

PyObject *PyDictProxy_New(PyObject *mapping)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Возвращает объект types.MappingProxyType для отображения, которое принудительно обеспечивает режим только для чтения. Обычно используется для создания представления, предотвращающего изменение словаря для нединамических типов классов.

void PyDict_Clear(PyObject *p)¶: Часть Stable ABI.
Очищает существующий словарь от всех пар ключ-значение.

int PyDict_Contains(PyObject *p, PyObject *key)¶: Часть Stable ABI.
Определяет, содержит ли словарь p ключ key. Если элемент в p совпадает с key, возвращает 1, иначе возвращает 0. В случае ошибки возвращает -1. Это эквивалентно выражению Python key in p.

PyObject *PyDict_Copy(PyObject *p)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Возвращает новый словарь, содержащий те же пары ключ-значение, что и p.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)¶: Часть Stable ABI.
Вставляет val в словарь p с ключом key. key должен быть хешируемым; в противном случае будет возбуждено TypeError. Возвращает 0 в случае успеха или -1 при неудаче. Эта функция не похищает ссылку на val.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)¶: Часть Stable ABI.
То же, что и PyDict_SetItem(), но key задаётся как const char* строка байтов в кодировке UTF-8, а не как PyObject*.

int PyDict_DelItem(PyObject *p, PyObject *key)¶: Часть Stable ABI.
Удаляет запись из словаря p с ключом key. key должен быть хэшируемым; если нет, возбуждается TypeError. Если key отсутствует в словаре, возбуждается KeyError. Возвращает 0 при успехе или -1 при неудаче.

int PyDict_DelItemString(PyObject *p, const char *key)¶: Часть Stable ABI.
То же, что и PyDict_DelItem(), но key задаётся как const char* строка байтов в кодировке UTF-8, а не как PyObject*.

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)¶: Возвращаемое значение: заимствованная ссылка. Часть Stable ABI.
Возвращает объект из словаря p по ключу key. Возвращает NULL, если ключ key отсутствует, но без установки исключения.

Примечание

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

Изменено в версии 3.10: Вызов этого API без удержания GIL ранее допускался по историческим причинам. Теперь это не допускается.

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)¶: Возвращаемое значение: заимствованная ссылка. Часть Stable ABI.
Вариант PyDict_GetItem(), который не подавляет исключения. Возвращает NULL с установленным исключением, если произошло исключение. Возвращает NULL без установленного исключения, если ключ отсутствовал.

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

Примечание

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

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

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

PyObject *PyDict_Items(PyObject *p)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Возвращает PyListObject, содержащий все элементы из словаря.

PyObject *PyDict_Keys(PyObject *p)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Возвращает PyListObject, содержащий все ключи из словаря.

PyObject *PyDict_Values(PyObject *p)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Возвращает PyListObject, содержащий все значения из словаря p.

Py_ssize_t PyDict_Size(PyObject *p)¶: Часть Stable ABI.
Возвращает количество элементов в словаре. Это эквивалентно вызову len(p) для словаря.

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)¶

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

Словарь 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)¶: Часть Stable ABI.
Перебирает объект отображения b, добавляя пары ключ-значение в словарь a. b может быть словарем или любым объектом, поддерживающим PyMapping_Keys() и PyObject_GetItem(). Если override равно true, существующие пары в a будут заменены, если найден совпадающий ключ в b; в противном случае пары будут добавлены только если нет совпадающего ключа в a. Возвращает 0 при успехе или -1, если было возбуждено исключение.

int PyDict_Update(PyObject *a, PyObject *b)¶: Часть Stable 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)¶

Часть Stable 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)¶: Регистрирует колбэк в качестве наблюдателя словаря. Возвращает неотрицательное целое 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 в колбэке, так как это может изменить словарь в качестве побочного эффекта.

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

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

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

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

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