`dict.md`

361 строк · 13.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/c-api/dict.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты словарей89**`PyDictObject`**1011Этот подтип1213[`PyObject`](https://python-all.ru/3.1/c-api/structures.html#PyObject)1415представляет объект словаря Python.1617**[PyTypeObject](https://python-all.ru/3.1/c-api/type.html#PyTypeObject) `PyDict_Type`**1819Этот экземпляр2021[`PyTypeObject`](https://python-all.ru/3.1/c-api/type.html#PyTypeObject)2223представляет тип словаря Python. Это тот же объект, что и2425[`dict`](https://python-all.ru/3.1/library/stdtypes.html#dict)2627на уровне Python.2829**int `PyDict_Check`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**3031Возвращает true, если3233*p*3435является объектом dict или экземпляром подтипа типа dict.3637**int `PyDict_CheckExact`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**3839Возвращает true, если4041*p*4243является объектом dict, но не экземпляром подтипа tипа dict.4445**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_New`()**4647*Возвращаемое значение: новая ссылка.*4849Возвращает новый пустой словарь или *NULL* в случае ошибки.5051**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDictProxy_New`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*dict*)**5253*Возвращаемое значение: новая ссылка.*5455Возвращает прокси-объект для отображения, которое обеспечивает поведение только для чтения. Обычно используется для создания прокси, предотвращающего изменение словаря для нединамических типов классов.5657**void `PyDict_Clear`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**5859Очищает существующий словарь от всех пар ключ-значение.6061**int `PyDict_Contains`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*key*)**6263Определяет, содержит ли словарь6465*p*6667ключ6869*key*7071. Если элемент в7273*p*7475совпадает с7677*key*7879, возвращается8081`1`8283, в противном случае возвращается8485`0`8687. При ошибке возвращается8889`-1`9091. Это эквивалентно выражению Python9293`key in p`9495.9697**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_Copy`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**9899*Возвращаемое значение: новая ссылка.*100101Возвращает новый словарь, содержащий те же пары ключ-значение, что и *p*.102103**int `PyDict_SetItem`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*key*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*val*)**104105Вставляет значение106107*value*108109в словарь110111*p*112113с ключом114115*key*116117. Ключ118119*key*120121должен быть122123[*hashable*](https://python-all.ru/3.1/glossary.html#term-hashable)124125; если нет, будет возбуждено исключение126127[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)128129. При успехе возвращается130131`0`132133, при ошибке –134135`-1`136137.138139**int `PyDict_SetItemString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, const char *\*key*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*val*)**140141Вставляет значение *value* в словарь *p*, используя *key* в качестве ключа. *key* должен быть `char*`. Объект ключа создаётся с помощью `PyUnicode_FromString(key)`. При успехе возвращается `0`, при ошибке – `-1`.142143**int `PyDict_DelItem`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*key*)**144145Удаляет запись из словаря146147*p*148149с ключом150151*key*152153. Ключ154155*key*156157должен быть хешируемым; если нет, возбуждается158159[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)160161. При успехе возвращается162163`0`164165, при ошибке –166167`-1`168169.170171**int `PyDict_DelItemString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, char *\*key*)**172173Удаляет запись из словаря174175*p*176177, ключ которой задаётся строкой178179*key*180181. Возвращает182183`0`184185при успехе или186187`-1`188189при неудаче.190191**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_GetItem`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*key*)**192193*Возвращаемое значение: заимствованная ссылка.*194195Возвращает объект из словаря *p* с ключом *key*. Возвращает *NULL* если ключ *key* отсутствует, но *без* установки исключения.196197**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_GetItemWithError`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*key*)**198199Вариант200201[`PyDict_GetItem()`](https://python-all.ru/3.1/c-api/dict.html#PyDict_GetItem)202203, который не подавляет исключения. Возвращает204205*NULL*206207**с**208209установленным исключением, если произошла ошибка. Возвращает210211*NULL*212213**без**214215установленного исключения, если ключ отсутствовал.216217**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_GetItemString`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, const char *\*key*)**218219*Возвращаемое значение: заимствованная ссылка.*220221То же, что и [`PyDict_GetItem()`](https://python-all.ru/3.1/c-api/dict.html#PyDict_GetItem), но ключ *key* задаётся как `char*`, а не как [`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject).222223**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_Items`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**224225*Возвращаемое значение: новая ссылка.*226227Возвращает [`PyListObject`](https://python-all.ru/3.1/c-api/list.html#PyListObject), содержащий все элементы из словаря.228229**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_Keys`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**230231*Возвращаемое значение: новая ссылка.*232233Возвращает [`PyListObject`](https://python-all.ru/3.1/c-api/list.html#PyListObject), содержащий все ключи из словаря.234235**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyDict_Values`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**236237*Возвращаемое значение: новая ссылка.*238239Возвращает [`PyListObject`](https://python-all.ru/3.1/c-api/list.html#PyListObject), содержащий все значения из словаря *p*.240241**Py\_ssize\_t `PyDict_Size`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**242243Возвращает количество элементов в словаре. Это эквивалентно `len(p)` для словаря.244245**int `PyDict_Next`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*, Py\_ssize\_t *\*ppos*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*\*pkey*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*\*pvalue*)**246247Перебирает все пары ключ-значение в словаре *p*. Переменная `Py_ssize_t`, на которую ссылается *ppos*, должна быть инициализирована значением `0` до первого вызова этой функции для начала итерации; функция возвращает true для каждой пары в словаре и false, когда все пары были перебраны. Параметры *pkey* и *pvalue* должны либо указывать на переменные типа [`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject), которые будут заполнены соответствующими ключом и значением, либо могут быть *NULL*. Любые ссылки, возвращаемые через них, являются заимствованными. *ppos* не должен изменяться во время итерации. Его значение представляет собой смещения во внутренней структуре словаря, и поскольку структура разрежена, смещения не являются последовательными.248249Например:250251```c252PyObject *key, *value;253Py_ssize_t pos = 0;254255while (PyDict_Next(self->dict, &pos, &key, &value)) {256    /* сделайте что-нибудь интересное со значениями... */257    ...258}259```260261Словарь *p* не должен изменяться во время итерации. Можно безопасно изменять значения ключей при переборе словаря, но только до тех пор, пока набор ключей не меняется. Например:262263```c264PyObject *key, *value;265Py_ssize_t pos = 0;266267while (PyDict_Next(self->dict, &pos, &key, &value)) {268    long i = PyLong_AsLong(value);269    if (i == -1 && PyErr_Occurred()) {270        return -1;271    }272    PyObject *o = PyLong_FromLong(i + 1);273    if (o == NULL)274        return -1;275    if (PyDict_SetItem(self->dict, key, o) < 0) {276        Py_DECREF(o);277        return -1;278    }279    Py_DECREF(o);280}281```282283**int `PyDict_Merge`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*b*, int *override*)**284285Перебирает объект отображения286287*b*288289, добавляя пары ключ-значение в словарь290291*a*292293.294295*b*296297может быть словарём или любым объектом, поддерживающим298299[`PyMapping_Keys()`](https://python-all.ru/3.1/c-api/mapping.html#PyMapping_Keys)300301и302303[`PyObject_GetItem()`](https://python-all.ru/3.1/c-api/object.html#PyObject_GetItem)304305. Если306307*override*308309истинно, существующие пары в310311*a*312313будут заменены, если найден соответствующий ключ в314315*b*316317; в противном случае пары будут добавлены только при отсутствии соответствующего ключа в318319*a*320321. Возвращает322323`0`324325в случае успеха или326327`-1`328329, если было возбуждено исключение.330331**int `PyDict_Update`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*b*)**332333То же самое, что334335`PyDict_Merge(a, b, 1)`336337в C, или338339`a.update(b)`340341в Python. Возвращает342343`0`344345при успехе или346347`-1`348349, если было возбуждено исключение.350351**int `PyDict_MergeFromSeq2`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*seq2*, int *override*)**352353Обновляет или объединяет словарь *a*, используя пары ключ-значение из *seq2*. *seq2* должен быть итерируемым объектом, который возвращает итерируемые объекты длины 2, рассматриваемые как пары ключ-значение. При повторяющихся ключах последнее значение побеждает, если *override* истинно, иначе первое. Возвращает `0` при успехе или `-1`, если возникло исключение. Эквивалент на Python (за исключением возвращаемого значения):354355```c356def PyDict_MergeFromSeq2(a, seq2, override):357    for key, value in seq2:358        if override or key not in a:359            a[key] = value360```361