`dict.md`

250 строк · 14.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.6/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/2.6/c-api/structures.html#PyObject)1415представляет объект словаря Python.1617**[PyTypeObject](https://python-all.ru/2.6/c-api/type.html#PyTypeObject) `PyDict_Type`**1819Этот экземпляр [`PyTypeObject`](https://python-all.ru/2.6/c-api/type.html#PyTypeObject) представляет тип Python-словаря. Он доступен программам на Python как `dict` и `types.DictType`.2021**int `PyDict_Check`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**2223Возвращает true, если *p* является объектом dict или экземпляром подтипа типа dict.2425Изменено в версии 2.2: Теперь допускаются подтипы.2627**int `PyDict_CheckExact`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**2829Возвращает true, если *p* является объектом dict, но не экземпляром подтипа tипа dict.3031Новое в версии 2.4.3233**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_New`()**3435*Возвращаемое значение: новая ссылка.*3637Возвращает новый пустой словарь или *NULL* в случае ошибки.3839**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDictProxy_New`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*dict*)**4041*Возвращаемое значение: новая ссылка.*4243Возвращает прокси-объект для отображения, которое обеспечивает поведение только для чтения. Обычно используется для создания прокси, предотвращающего изменение словаря для нединамических типов классов.4445Новое в версии 2.2.4647**void `PyDict_Clear`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**4849Очищает существующий словарь от всех пар ключ-значение.5051**int `PyDict_Contains`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*key*)**5253Определяет, содержит ли словарь *p* ключ *key*. Если элемент в *p* совпадает с *key*, возвращается `1`, в противном случае возвращается `0`. При ошибке возвращается `-1`. Это эквивалентно выражению Python `key in p`.5455Новое в версии 2.4.5657**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_Copy`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**5859*Возвращаемое значение: новая ссылка.*6061Возвращает новый словарь, содержащий те же пары ключ-значение, что и *p*.6263Новое в версии 1.6.6465**int `PyDict_SetItem`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*key*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*val*)**6667Вставляет значение6869*value*7071в словарь7273*p*7475с ключом7677*key*7879. Ключ8081*key*8283должен быть8485[*hashable*](https://python-all.ru/2.6/glossary.html#term-hashable)8687; если нет, будет возбуждено исключение8889[`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError)9091. При успехе возвращается9293`0`9495, при ошибке –9697`-1`9899.100101**int `PyDict_SetItemString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, const char *\*key*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*val*)**102103Вставляет *value* в словарь *p* по ключу *key*. *key* должен быть типа `char*`. Объект ключа создаётся с помощью `PyString_FromString(key)`. Возвращает `0` в случае успеха или `-1` в случае ошибки.104105**int `PyDict_DelItem`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*key*)**106107Удаляет запись из словаря108109*p*110111с ключом112113*key*114115. Ключ116117*key*118119должен быть хешируемым; если нет, возбуждается120121[`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError)122123. При успехе возвращается124125`0`126127, при ошибке –128129`-1`130131.132133**int `PyDict_DelItemString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, char *\*key*)**134135Удаляет запись из словаря136137*p*138139, ключ которой задаётся строкой140141*key*142143. Возвращает144145`0`146147при успехе или148149`-1`150151при неудаче.152153**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_GetItem`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*key*)**154155*Возвращаемое значение: заимствованная ссылка.*156157Возвращает объект из словаря *p* с ключом *key*. Возвращает *NULL* если ключ *key* отсутствует, но *без* установки исключения.158159**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_GetItemString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, const char *\*key*)**160161*Возвращаемое значение: заимствованная ссылка.*162163То же, что и [`PyDict_GetItem()`](https://python-all.ru/2.6/c-api/dict.html#PyDict_GetItem), но ключ *key* задаётся как `char*`, а не как [`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject).164165**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_Items`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**166167*Возвращаемое значение: новая ссылка.*168169Возвращает [`PyListObject`](https://python-all.ru/2.6/c-api/list.html#PyListObject), содержащий все элементы из словаря, как и метод словаря [`dict.items()`](https://python-all.ru/2.6/library/stdtypes.html#dict.items).170171**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_Keys`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**172173*Возвращаемое значение: новая ссылка.*174175Возвращает [`PyListObject`](https://python-all.ru/2.6/c-api/list.html#PyListObject), содержащий все ключи из словаря, как и метод словаря [`dict.keys()`](https://python-all.ru/2.6/library/stdtypes.html#dict.keys).176177**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyDict_Values`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**178179*Возвращаемое значение: новая ссылка.*180181Возвращает [`PyListObject`](https://python-all.ru/2.6/c-api/list.html#PyListObject), содержащий все значения из словаря *p*, как и метод словаря [`dict.values()`](https://python-all.ru/2.6/library/stdtypes.html#dict.values).182183**Py\_ssize\_t `PyDict_Size`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**184185Возвращает количество элементов в словаре. Это эквивалентно `len(p)` для словаря.186187Изменено в версии 2.5: Ранее эта функция возвращала тип `int`. Это может потребовать изменений в вашем коде для корректной поддержки 64-разрядных систем.188189**int `PyDict_Next`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, Py\_ssize\_t *\*ppos*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*pkey*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*pvalue*)**190191Перебирает все пары ключ-значение в словаре *p*. Переменная `Py_ssize_t`, на которую ссылается *ppos*, должна быть инициализирована значением `0` до первого вызова этой функции для начала итерации; функция возвращает true для каждой пары в словаре и false, когда все пары были перебраны. Параметры *pkey* и *pvalue* должны либо указывать на переменные типа [`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject), которые будут заполнены соответствующими ключом и значением, либо могут быть *NULL*. Любые ссылки, возвращаемые через них, являются заимствованными. *ppos* не должен изменяться во время итерации. Его значение представляет собой смещения во внутренней структуре словаря, и поскольку структура разрежена, смещения не являются последовательными.192193Например:194195```c196PyObject *key, *value;197Py_ssize_t pos = 0;198199while (PyDict_Next(self->dict, &pos, &key, &value)) {200    /* сделайте что-нибудь интересное со значениями... */201    ...202}203```204205Словарь *p* не должен изменяться во время итерации. Начиная с Python 2.1 безопасно изменять значения ключей в процессе итерации по словарю, но только до тех пор, пока набор ключей не меняется. Например:206207```c208PyObject *key, *value;209Py_ssize_t pos = 0;210211while (PyDict_Next(self->dict, &pos, &key, &value)) {212    int i = PyInt_AS_LONG(value) + 1;213    PyObject *o = PyInt_FromLong(i);214    if (o == NULL)215        return -1;216    if (PyDict_SetItem(self->dict, key, o) < 0) {217        Py_DECREF(o);218        return -1;219    }220    Py_DECREF(o);221}222```223224Изменено в версии 2.5: Ранее эта функция использовала тип `int *` для *ppos*. Это может потребовать изменений в вашем коде для корректной поддержки 64-разрядных систем.225226**int `PyDict_Merge`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*b*, int *override*)**227228Перебирает объект отображения *b*, добавляя пары ключ-значение в словарь *a*. *b* может быть словарём или любым объектом, поддерживающим [`PyMapping_Keys()`](https://python-all.ru/2.6/c-api/mapping.html#PyMapping_Keys) и [`PyObject_GetItem()`](https://python-all.ru/2.6/c-api/object.html#PyObject_GetItem). Если *override* истинно, существующие пары в *a* будут заменены, если найден соответствующий ключ в *b*; в противном случае пары будут добавлены только при отсутствии соответствующего ключа в *a*. Возвращает `0` в случае успеха или `-1`, если было возбуждено исключение.229230Новое в версии 2.2.231232**int `PyDict_Update`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*b*)**233234То же самое, что `PyDict_Merge(a, b, 1)` в C, или `a.update(b)` в Python. Возвращает `0` при успехе или `-1`, если было возбуждено исключение.235236Новое в версии 2.2.237238**int `PyDict_MergeFromSeq2`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*a*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*seq2*, int *override*)**239240Обновляет или объединяет словарь *a*, используя пары ключ-значение из *seq2*. *seq2* должен быть итерируемым объектом, который возвращает итерируемые объекты длины 2, рассматриваемые как пары ключ-значение. При повторяющихся ключах последнее значение побеждает, если *override* истинно, иначе первое. Возвращает `0` при успехе или `-1`, если возникло исключение. Эквивалент на Python (за исключением возвращаемого значения):241242```c243def PyDict_MergeFromSeq2(a, seq2, override):244    for key, value in seq2:245        if override or key not in a:246            a[key] = value247```248249Новое в версии 2.2.250