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

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 для отображения, обеспечивающего доступ только для чтения. Обычно это используется для создания представления, предотвращающего изменение словаря для нединамических типов классов.

PyTypeObject PyDictProxy_Type

Входит в стабильный ABI.

Объект типа для объектов proxy отображения, создаваемых с помощью PyDictProxy_New(), а также для атрибута __dict__, доступного только для чтения, у многих встроенных типов. Экземпляр PyDictProxy_Type предоставляет динамическое представление базового словаря только для чтения: изменения базового словаря отражаются в proxy, но сам proxy не поддерживает операции изменения. В Python этому соответствует 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.

Примечание

Операция атомарна при сборке со свободной многопоточностью, если key имеет тип str, int, float, bool или bytes.

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.

Примечание

Операция атомарна при сборке со свободной многопоточностью, если key имеет тип str, int, float, bool или bytes.

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.

Примечание

Операция атомарна при сборке со свободной многопоточностью, если key имеет тип str, int, float, bool или bytes.

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.
• В случае ошибки вызывает исключение, устанавливает *result в NULL и возвращает -1.

Примечание

Операция атомарна при сборке со свободной многопоточностью, если key имеет тип str, int, float, bool или bytes.

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

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

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)

Возвращаемое значение: заимствованная ссылка. Входит в стабильный ABI.Потокобезопасность: безопасно вызывать из нескольких потоков только при внешней синхронизации.

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

Примечание

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

Примечание

В сборке со свободной многопоточностью возвращённая заимствованная ссылка может стать недействительной, если другой поток одновременно изменит словарь. Предпочтительно использовать PyDict_GetItemRef(), которая возвращает сильную ссылку.

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

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)

Возвращаемое значение: заимствованная ссылка. Входит в стабильный ABI.Потокобезопасность: безопасно вызывать из нескольких потоков только при внешней синхронизации.

Вариант PyDict_GetItem(), который не подавляет исключения. Возвращает NULL при установленном исключении, если произошло исключение. Возвращает NULL без установленного исключения, если ключ отсутствовал.

Примечание

В сборке со свободной многопоточностью возвращённая заимствованная ссылка может стать недействительной, если другой поток одновременно изменит словарь. Предпочтительно использовать PyDict_GetItemRef(), которая возвращает сильную ссылку.

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

Примечание

В сборке со свободной многопоточностью возвращённая заимствованная ссылка может стать недействительной, если другой поток одновременно изменит словарь. Предпочтительно использовать PyDict_GetItemStringRef(), которая возвращает сильную ссылку.

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. Если ключа нет в словаре, он добавляется со значением defaultobj, и возвращается defaultobj. Эта функция вычисляет хеш-функцию key только один раз, а не отдельно при поиске и вставке.

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

Примечание

В сборке со свободной многопоточностью возвращённая заимствованная ссылка может стать недействительной, если другой поток одновременно изменит словарь. Предпочтительно использовать PyDict_SetDefaultRef(), которая возвращает сильную ссылку.

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). Они могут указывать на один и тот же объект; в этом случае у вас будут две отдельные ссылки на него.

Примечание

Операция атомарна при сборке со свободной многопоточностью, если key имеет тип str, int, float, bool или bytes.

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

Примечание

Операция атомарна при сборке со свободной многопоточностью, если key имеет тип str, int, float, bool или bytes.

Добавлено в версии 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) для словаря.

Py_ssize_t PyDict_GET_SIZE(PyObject *p)

Потокобезопасность: атомарно.

Аналогично PyDict_Size(), но без проверки ошибок.

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

Часть стабильного ABI. Потокобезопасность: безопасно вызывать из нескольких потоков только при внешней синхронизации.

Перебирает все пары «ключ — значение» в словаре p. Указатель Py_ssize_t, на который ссылается ppos, необходимо инициализировать значением 0 перед первым вызовом этой функции, чтобы начать перебор; функция возвращает истину для каждой пары в словаре и ложь, когда все пары уже обработаны. Параметры 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();

Примечание

В сборке без глобальной блокировки интерпретатора эту функцию можно безопасно использовать внутри критической секции. Однако ссылки, возвращаемые для pkey и pvalue, являются заимствованными и действительны только пока удерживается критическая секция. Если эти объекты нужны за пределами критической секции или критическая секция может быть приостановлена, создайте сильную ссылку (например, с помощью Py_NewRef()).

int PyDict_Merge(PyObject *a, PyObject *b, int override)

Часть стабильного ABI. Потокобезопасность: безопасно для параллельного использования одного и того же объекта.

Перебирает объект-отображение b, добавляя пары «ключ — значение» в словарь a. b может быть словарём или любым объектом, поддерживающим PyMapping_Keys() и PyObject_GetItem(). Если override имеет значение true, существующие пары в a будут заменены при обнаружении совпадающего ключа в b; в противном случае пары будут добавлены, только если соответствующего ключа нет в a. В случае успеха возвращает 0, а если возникло исключение — -1.

Примечание

В сборке без глобальной блокировки интерпретатора, если b является dict (со стандартным итератором), оба объекта, a и b, блокируются на время операции. Если b является отображением, отличным от словаря, блокируется только a; другой поток может одновременно изменять b.

int PyDict_Update(PyObject *a, PyObject *b)

Часть стабильного ABI. Потокобезопасность: безопасно для параллельного использования одного и того же объекта.

В C это то же самое, что PyDict_Merge(a, b, 1), а в Python аналогично a.update(b), за исключением того, что PyDict_Update() не переключается на перебор последовательности пар «ключ — значение», если у второго аргумента нет атрибута «keys». В случае успеха возвращает 0, а если возникло исключение — -1.

Примечание

В сборке без глобальной блокировки интерпретатора, если b является dict (со стандартным итератором), оба объекта, a и b, блокируются на время операции. Если b является отображением, отличным от словаря, блокируется только a; другой поток может одновременно изменять b.

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

Примечание

В сборке без глобальной блокировки интерпретатора блокируется только a. Перебор seq2 не синхронизирован; другой поток может одновременно изменять seq2.

int PyDict_AddWatcher(PyDict_WatchCallback callback)

Потокобезопасность: безопасно вызывать из нескольких потоков только при внешней синхронизации.

Регистрирует callback в качестве наблюдателя словаря. Возвращает неотрицательный целочисленный идентификатор, который необходимо передавать в последующие вызовы PyDict_Watch(). В случае ошибки (например, если больше нет доступных идентификаторов наблюдателей) возвращает -1 и устанавливает исключение.

Примечание

Эта функция не синхронизируется внутри себя. В сборке без глобальной блокировки интерпретатора вызывающий код должен гарантировать, что параллельно не выполняются вызовы PyDict_AddWatcher() или PyDict_ClearWatcher().

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

int PyDict_ClearWatcher(int watcher_id)

Потокобезопасность: безопасно вызывать из нескольких потоков только при внешней синхронизации.

Удаляет наблюдателя с идентификатором watcher_id, ранее возвращённым PyDict_AddWatcher(). В случае успеха возвращает 0, в случае ошибки — -1 (например, если указанный watcher_id никогда не регистрировался).

Примечание

Эта функция не синхронизируется внутри себя. В сборке без глобальной блокировки интерпретатора вызывающий код должен гарантировать, что параллельно не выполняются вызовы PyDict_AddWatcher() или PyDict_ClearWatcher().

Добавлено в версии 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.