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

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.

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

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().

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)

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

Аналогично PyDict_GetItemRef(), но key задаётся как строка байтов в кодировке UTF-8 типа const char*, а не как PyObject*.

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

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

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

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

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

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

Вставляет default_value в словарь p с ключом key, если этого ключа ещё нет в словаре. Если result не равен NULL, то *result получает сильную ссылку либо на default_value, если ключ отсутствовал, либо на существующее значение, если key уже был в словаре. Возвращает 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)

Удаляет key из словаря 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(), но key задаётся как строка байтов в кодировке 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.

В языке 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.