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

PyDictObject¶: Этот подтип PyObject представляет объект словаря Python.

PyTypeObject PyDict_Type¶: Этот экземпляр PyTypeObject представляет тип словаря Python. Это тот же объект, что и dict на уровне Python.

int PyDict_Check(PyObject *p)¶: Возвращает true, если p является объектом dict или экземпляром подтипа типа dict.

int PyDict_CheckExact(PyObject *p)¶: Возвращает true, если p является объектом dict, но не экземпляром подтипа tипа dict.

PyObject* PyDict_New()¶: Возвращаемое значение: новая ссылка.
Возвращает новый пустой словарь или NULL в случае ошибки.

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

void PyDict_Clear(PyObject *p)¶: Очищает существующий словарь от всех пар ключ-значение.

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

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

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

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)¶: Вставляет val в словарь p, используя key в качестве ключа. key должен быть const char*. Объект ключа создаётся с помощью PyUnicode_FromString(key). Возвращает 0 в случае успеха или -1 в случае ошибки. Эта функция не крадёт ссылку на val.

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

int PyDict_DelItemString(PyObject *p, const char *key)¶: Удаляет запись из словаря p, ключ которой задаётся строкой key. Если key нет в словаре, возбуждается исключение KeyError. Возвращает 0 в случае успеха или -1 в случае ошибки.

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

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

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

Обратите внимание, что исключения, возникающие при вызове методов __hash__() и __eq__(), подавляются. Для получения сообщений об ошибках используйте вместо этого PyDict_GetItemWithError().

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

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

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

То же, что и PyDict_GetItem(), но key задаётся как const char*, а не как PyObject*.

Обратите внимание, что исключения, возникающие при вызове методов __hash__() и __eq__() и при создании временного строкового объекта, подавляются. Для получения сообщений об ошибках используйте вместо этого PyDict_GetItemWithError().

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

Новое в версии 3.4.

PyObject* PyDict_Items(PyObject *p)¶: Возвращаемое значение: новая ссылка.
Возвращает PyListObject, содержащий все элементы из словаря.

PyObject* PyDict_Keys(PyObject *p)¶: Возвращаемое значение: новая ссылка.
Возвращает PyListObject, содержащий все ключи из словаря.

PyObject* PyDict_Values(PyObject *p)¶: Возвращаемое значение: новая ссылка.
Возвращает PyListObject, содержащий все значения из словаря p.

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

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

Перебирает все пары ключ-значение в словаре 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)) {
    /* сделайте что-нибудь интересное со значениями... */
    ...
}

Словарь 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)¶: Перебирает объект отображения b, добавляя пары ключ-значение в словарь a. b может быть словарем или любым объектом, поддерживающим PyMapping_Keys() и PyObject_GetItem(). Если override равно true, существующие пары в a будут заменены, если найден совпадающий ключ в b; в противном случае пары будут добавлены только если нет совпадающего ключа в a. Возвращает 0 при успехе или -1, если было возбуждено исключение.

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

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)¶

Обновляет или объединяет словарь 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

int PyDict_ClearFreeList()¶: Очищает список свободных блоков. Возвращает общее количество освобождённых элементов.

Новое в версии 3.3.