`dict.md`

174 строк · 12.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/c-api/dict.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты словарей89**`PyDictObject`**1011Этот подтип [`PyObject`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject) представляет объект словаря Python.1213**[PyTypeObject](https://python-all.ru/2.7/c-api/type.html#c.PyTypeObject) `PyDict_Type`**1415Этот экземпляр [`PyTypeObject`](https://python-all.ru/2.7/c-api/type.html#c.PyTypeObject) представляет тип словаря Python. В программах на Python он доступен как `dict` и `types.DictType`.1617#### `int PyDict_Check(PyObject *p)`1819Возвращает true, если *p* является объектом dict или экземпляром подтипа типа dict.2021Изменено в версии 2.2: Разрешено принимать подтипы.2223#### `int PyDict_CheckExact(PyObject *p)`2425Возвращает true, если *p* является объектом dict, но не экземпляром подтипа tипа dict.2627Новое в версии 2.4.2829#### `PyObject* PyDict_New()`3031*Возвращаемое значение: новая ссылка.*3233Возвращает новый пустой словарь или *NULL* в случае ошибки.3435#### `PyObject* PyDictProxy_New(PyObject *dict)`3637*Возвращаемое значение: новая ссылка.*3839Возвращает прокси-объект для отображения, которое обеспечивает поведение только для чтения. Обычно используется для создания прокси, предотвращающего изменение словаря для нединамических типов классов.4041Новое в версии 2.2.4243#### `void PyDict_Clear(PyObject *p)`4445Очищает существующий словарь от всех пар ключ-значение.4647#### `int PyDict_Contains(PyObject *p, PyObject *key)`4849Определяет, содержит ли словарь *p* ключ *key*. Если элемент в *p* совпадает с *key*, возвращает `1`, иначе возвращает `0`. В случае ошибки возвращает `-1`. Это эквивалентно выражению Python `key in p`.5051Новое в версии 2.4.5253#### `PyObject* PyDict_Copy(PyObject *p)`5455*Возвращаемое значение: новая ссылка.*5657Возвращает новый словарь, содержащий те же пары ключ-значение, что и *p*.5859Новое в версии 1.6.6061#### `int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)`6263Вставляет *value* в словарь *p* с ключом *key*. *key* должен быть [хэшируемым](https://python-all.ru/2.7/glossary.html#term-hashable); в противном случае будет возбуждено [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError). Возвращает `0` при успехе или `-1` при неудаче.6465#### `int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)`6667Вставляет *value* в словарь *p*, используя *key* в качестве ключа. *key* должен быть `char*`. Объект ключа создаётся с помощью `PyString_FromString(key)`. Возвращает `0` при успехе или `-1` при неудаче.6869#### `int PyDict_DelItem(PyObject *p, PyObject *key)`7071Удаляет запись из словаря *p* с ключом *key*. *key* должен быть хэшируемым; в противном случае возбуждается [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError). Возвращает `0` при успехе или `-1` при неудаче.7273#### `int PyDict_DelItemString(PyObject *p, char *key)`7475Удаляет запись из словаря *p*, ключ которой задаётся строкой *key*. Возвращает `0` при успехе или `-1` при неудаче.7677#### `PyObject* PyDict_GetItem(PyObject *p, PyObject *key)`7879*Возвращаемое значение: заимствованная ссылка.*8081Возвращает объект из словаря *p* с ключом *key*. Возвращает *NULL* если ключ *key* отсутствует, но *без* установки исключения.8283#### `PyObject* PyDict_GetItemString(PyObject *p, const char *key)`8485*Возвращаемое значение: заимствованная ссылка.*8687То же, что и [`PyDict_GetItem()`](https://python-all.ru/2.7/c-api/dict.html#c.PyDict_GetItem), но *key* задаётся как `char*`, а не как [`PyObject*`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject).8889#### `PyObject* PyDict_Items(PyObject *p)`9091*Возвращаемое значение: новая ссылка.*9293Возвращает [`PyListObject`](https://python-all.ru/2.7/c-api/list.html#c.PyListObject), содержащий все элементы словаря, как и метод словаря [`dict.items()`](https://python-all.ru/2.7/library/stdtypes.html#dict.items).9495#### `PyObject* PyDict_Keys(PyObject *p)`9697*Возвращаемое значение: новая ссылка.*9899Возвращает [`PyListObject`](https://python-all.ru/2.7/c-api/list.html#c.PyListObject), содержащий все ключи словаря, как и метод словаря [`dict.keys()`](https://python-all.ru/2.7/library/stdtypes.html#dict.keys).100101#### `PyObject* PyDict_Values(PyObject *p)`102103*Возвращаемое значение: новая ссылка.*104105Возвращает [`PyListObject`](https://python-all.ru/2.7/c-api/list.html#c.PyListObject), содержащий все значения из словаря *p*, как и метод словаря [`dict.values()`](https://python-all.ru/2.7/library/stdtypes.html#dict.values).106107#### `Py_ssize_t PyDict_Size(PyObject *p)`108109Возвращает количество элементов в словаре. Это эквивалентно вызову `len(p)` для словаря.110111Изменено в версии 2.5: Эта функция возвращала тип `int`. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.112113#### `int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)`114115Проходит по всем парам ключ-значение в словаре *p*. Переменная `Py_ssize_t`, на которую ссылается *ppos*, должна быть инициализирована значением `0` перед первым вызовом этой функции для запуска итерации; функция возвращает true для каждой пары в словаре и false, когда все пары были переданы. Параметры *pkey* и *pvalue* должны указывать на переменные [`PyObject*`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject), в которые будут записаны ключ и значение соответственно, или могут быть *NULL*. Любые ссылки, возвращаемые через них, являются заимствованными. *ppos* не следует изменять во время итерации. Его значение представляет собой смещения во внутренней структуре словаря, и, поскольку структура разреженная, смещения не являются последовательными.116117Например:118119```c120PyObject *key, *value;121Py_ssize_t pos = 0;122123while (PyDict_Next(self->dict, &pos, &key, &value)) {124    /* сделайте что-нибудь интересное со значениями... */125    ...126}127```128129Словарь *p* не должен изменяться во время итерации. Начиная с Python 2.1 безопасно изменять значения ключей в процессе итерации по словарю, но только до тех пор, пока набор ключей не меняется. Например:130131```c132PyObject *key, *value;133Py_ssize_t pos = 0;134135while (PyDict_Next(self->dict, &pos, &key, &value)) {136    int i = PyInt_AS_LONG(value) + 1;137    PyObject *o = PyInt_FromLong(i);138    if (o == NULL)139        return -1;140    if (PyDict_SetItem(self->dict, key, o) < 0) {141        Py_DECREF(o);142        return -1;143    }144    Py_DECREF(o);145}146```147148Изменено в версии 2.5: Эта функция использовала тип `int *` для *ppos*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.149150#### `int PyDict_Merge(PyObject *a, PyObject *b, int override)`151152Перебирает объект отображения *b*, добавляя пары ключ-значение в словарь *a*. *b* может быть словарем или любым объектом, поддерживающим [`PyMapping_Keys()`](https://python-all.ru/2.7/c-api/mapping.html#c.PyMapping_Keys) и [`PyObject_GetItem()`](https://python-all.ru/2.7/c-api/object.html#c.PyObject_GetItem). Если *override* равно true, существующие пары в *a* будут заменены, если найден совпадающий ключ в *b*; в противном случае пары будут добавлены только если нет совпадающего ключа в *a*. Возвращает `0` при успехе или `-1`, если было возбуждено исключение.153154Новое в версии 2.2.155156#### `int PyDict_Update(PyObject *a, PyObject *b)`157158То же самое, что и `PyDict_Merge(a, b, 1)` в C, и похоже на `a.update(b)` в Python, за исключением того, что [`PyDict_Update()`](https://python-all.ru/2.7/c-api/dict.html#c.PyDict_Update) не переходит к итерации по последовательности пар ключ-значение, если у второго аргумента нет атрибута “keys”. Возвращает `0` при успехе или `-1`, если было возбуждено исключение.159160Новое в версии 2.2.161162#### `int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)`163164Обновляет или объединяет словарь *a*, используя пары ключ-значение из *seq2*. *seq2* должен быть итерируемым объектом, который возвращает итерируемые объекты длины 2, рассматриваемые как пары ключ-значение. При повторяющихся ключах последнее значение побеждает, если *override* истинно, иначе первое. Возвращает `0` при успехе или `-1`, если возникло исключение. Эквивалент на Python (за исключением возвращаемого значения):165166```c167def PyDict_MergeFromSeq2(a, seq2, override):168    for key, value in seq2:169        if override or key not in a:170            a[key] = value171```172173Новое в версии 2.2.174