Словари¶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()¶

Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.

Возвращает новый пустой словарь или NULL в случае ошибки.

PyObject *PyDictProxy_New(PyObject *mapping)¶

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

Возвращает объект types.MappingProxyType для отображения, которое принудительно обеспечивает режим только для чтения. Обычно используется для создания представления, предотвращающего изменение словаря для нединамических типов классов.

Первый аргумент может быть dict, frozendict или отображением.

Изменено в версии 3.15: также принимает frozendict.

PyTypeObject PyDictProxy_Type¶

Часть Stable ABI.

Объект типа для прокси-объектов отображения, создаваемых PyDictProxy_New(), и для атрибута __dict__ только для чтения многих встроенных типов. Экземпляр PyDictProxy_Type предоставляет динамическое представление только для чтения базового словаря: изменения в базовом словаре отражаются в прокси, но сам прокси не поддерживает операции изменения. Это соответствует types.MappingProxyType в Python.

void PyDict_Clear(PyObject *p)¶

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

Очищает существующий словарь от всех пар ключ-значение.

Ничего не делает, если аргумент не является dict или подклассом dict.

int PyDict_Contains(PyObject *p, PyObject *key)¶

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

Определяет, содержит ли словарь p ключ key. Если элемент в p соответствует key, возвращает 1, в противном случае возвращает 0. В случае ошибки возвращает -1. Это эквивалентно выражению Python key in p.

Первым аргументом может быть dict или frozendict.

Примечание

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

Изменено в версии 3.15: также принимает frozendict.

int PyDict_ContainsString(PyObject *p, const char *key)¶

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

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

Первым аргументом может быть dict или frozendict.

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

Изменено в версии 3.15: также принимает frozendict.

PyObject *PyDict_Copy(PyObject *p)¶

Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.

Возвращает новый словарь, содержащий те же пары ключ-значение, что и p.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)¶

Часть Stable 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)¶

Часть 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 при неудаче.

Примечание

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

int PyDict_DelItemString(PyObject *p, const char *key)¶

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

То же, что и PyDict_DelItem(), но key задаётся как const char* строка байтов в кодировке UTF-8, а не как PyObject*.

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

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

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

• Если ключ присутствует, устанавливает *result в новую сильную ссылку на значение и возвращает 1.

• Если ключ отсутствует, устанавливает *result в NULL и возвращает 0.

• При ошибке возбуждает исключение, устанавливает *result в NULL и возвращает -1.

Первым аргументом может быть dict или frozendict.

Примечание

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

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

Изменено в версии 3.15: также принимает frozendict.

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

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

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

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

Первым аргументом может быть dict или frozendict.

Примечание

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

Примечание

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

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

Изменено в версии 3.15: также принимает frozendict.

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

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

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

Примечание

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

Изменено в версии 3.15: также принимает frozendict.

PyObject *PyDict_GetItemString(PyObject *p, const char *key)¶

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

Это то же самое, что и PyDict_GetItem(), но key задается как const char* строка байтов в кодировке UTF-8, а не PyObject*.

Примечание

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

Примечание

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

Изменено в версии 3.15: также принимает frozendict.

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

Часть стабильного ABI начиная с версии 3.13. Потокобезопасность: Атомарно.

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

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

Изменено в версии 3.15: также принимает frozendict.

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

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

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

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

Примечание

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

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

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

Вставляет 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 задается как const char* строка байтов в кодировке UTF-8, а не PyObject*.

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

PyObject *PyDict_Items(PyObject *p)¶

Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.

Возвращает PyListObject, содержащий все элементы из словаря.

Первым аргументом может быть dict или frozendict.

Изменено в версии 3.15: также принимает frozendict.

PyObject *PyDict_Keys(PyObject *p)¶

Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.

Возвращает PyListObject, содержащий все ключи из словаря.

Первым аргументом может быть dict или frozendict.

Изменено в версии 3.15: также принимает frozendict.

PyObject *PyDict_Values(PyObject *p)¶

Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.

Возвращает PyListObject, содержащий все значения из словаря p.

Первым аргументом может быть dict или frozendict.

Изменено в версии 3.15: также принимает frozendict.

Py_ssize_t PyDict_Size(PyObject *p)¶

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

Возвращает количество элементов в словаре. Это эквивалентно вызову len(p) для словаря.

Аргументом может быть dict или frozendict.

Изменено в версии 3.15: также принимает frozendict.

Py_ssize_t PyDict_GET_SIZE(PyObject *p)¶

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

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

Изменено в версии 3.15: также принимает frozendict.

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

Первым аргументом может быть dict или frozendict.

Например:

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);
}

Функция не является потокобезопасной в сборке со свободными потоками без внешней синхронизации для изменяемого dict. Можно использовать Py_BEGIN_CRITICAL_SECTION для блокировки словаря во время итерации по нему:

Py_BEGIN_CRITICAL_SECTION(self->dict);
while (PyDict_Next(self->dict, &pos, &key, &value)) {
    ...
}
Py_END_CRITICAL_SECTION();

Функция потокобезопасна для frozendict.

Примечание

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

Изменено в версии 3.15: также принимает frozendict.

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, если было возбуждено исключение.

Примечание

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

int PyDict_Update(PyObject *a, PyObject *b)¶

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

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

Примечание

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

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

Примечание

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

int PyDict_AddWatcher(PyDict_WatchCallback callback)¶

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

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