Объекты словарей¶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 должен быть hashable; если нет, будет возбуждено исключение 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 истинно, существующие пары в a будут заменены, если найден соответствующий ключ в b; в противном случае пары будут добавлены только при отсутствии соответствующего ключа в a. Возвращает 0 в случае успеха или -1, если было возбуждено исключение.

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

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

То же самое, что PyDict_Merge(a, b, 1) в C, или a.update(b) в Python. Возвращает 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.