Словарные объекты¶

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 ключ. Если элемент в p соответствует ключу, верните 1, иначе верните 0. При ошибке возвращается -1. Это эквивалентно выражению key in p в языке Python.

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

Added in version 3.13.

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

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

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

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

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

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

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

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

Если ключ присутствует, установите *результат в новое значение strong reference и верните 1.
Если ключ отсутствует, установите *результат в NULL и верните 0.
При ошибке вызываем исключение и возвращаем -1.

Added in version 3.13.

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

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)¶: Возвращаемое значение: Заимствованная ссылка. Часть Стабильный ABI.
Возвращает borrowed reference объекту из словаря 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 указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.

Примечание

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

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

Added in version 3.13.

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

Added in version 3.4.

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

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

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

Added in version 3.13.

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

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

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

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

Added in version 3.13.

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

Added in version 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);
}

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 равно 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 и установите исключение.

Added in version 3.12.

int PyDict_ClearWatcher(int watcher_id)¶: Очистить наблюдателя, идентифицированного watcher_id, ранее возвращенного из PyDict_AddWatcher(). Возвращает 0 при успехе, -1 при ошибке (например, если данный watcher_id никогда не был зарегистрирован).

Added in version 3.12.

int PyDict_Watch(int watcher_id, PyObject *dict)¶: Пометить словарь dict как наблюдаемый. Обратный вызов, присвоенный watcher_id по PyDict_AddWatcher(), будет вызываться при изменении или деаллокации dict. Возвращает 0 при успехе или -1 при ошибке.

Added in version 3.12.

int PyDict_Unwatch(int watcher_id, PyObject *dict)¶: Пометьте словарь dict как больше не наблюдаемый. Обратный вызов, присвоенный watcher_id по PyDict_AddWatcher(), больше не будет вызываться при изменении или удалении dict. Диктант должен быть ранее просмотрен этим наблюдателем. Возвращает 0 при успехе или -1 при ошибке.

Added in version 3.12.

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

Added in version 3.12.

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

Тип функции обратного вызова dict watcher.

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

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

Обратный вызов может проверять, но не должен изменять dict; это может привести к непредсказуемым последствиям, включая бесконечную рекурсию. Не запускайте выполнение кода Python в обратном вызове, так как это может привести к побочному эффекту - изменению dict.

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

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

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

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

Added in version 3.12.

Словарные объекты¶

Предыдущий раздел

Следующий раздел