Объекты словарей¶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)¶

Вставляет value в словарь p с ключом key. key должен быть хэшируемым; в противном случае будет возбуждено TypeError. Возвращает 0 при успехе или -1 при неудаче.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)¶

Вставляет value в словарь p, используя key в качестве ключа. key должен быть char*. Объект ключа создаётся с помощью PyUnicode_FromString(key). Возвращает 0 при успехе или -1 при неудаче.

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

Удаляет запись из словаря p с ключом key. key должен быть хэшируемым; в противном случае возбуждается TypeError. Возвращает 0 при успехе или -1 при неудаче.

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

Удаляет запись из словаря p, ключ которой задаётся строкой key. Возвращает 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 задаётся как char*, а не как PyObject*.

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

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

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

Это то же самое, что и функция 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.