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

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

PyTypeObject PyDict_Type¶: Этот экземпляр PyTypeObject представляет тип словаря Python. В программах на Python он доступен как dict и types.DictType.

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

Изменено в версии 2.2: Разрешено принимать подтипы.

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

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

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

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

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

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

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

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

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

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

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*. Объект ключа создаётся с помощью PyString_FromString(key). Возвращает 0 при успехе или -1 при неудаче.

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

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

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

PyObject* PyDict_GetItemString(PyObject *p, const char *key)¶: Возвращаемое значение: заимствованная ссылка.
То же, что и PyDict_GetItem(), но key задаётся как char*, а не как PyObject*.

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

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

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

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

Изменено в версии 2.5: Эта функция возвращала тип int. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.

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 не должен изменяться во время итерации. Начиная с Python 2.1 безопасно изменять значения ключей в процессе итерации по словарю, но только до тех пор, пока набор ключей не меняется. Например:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    int i = PyInt_AS_LONG(value) + 1;
    PyObject *o = PyInt_FromLong(i);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}

Изменено в версии 2.5: Эта функция использовала тип int * для ppos. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.

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

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

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

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

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

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