Словарные объекты¶
-
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.