> **Источник:** https://python-all.ru/3/c-api/set.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Объекты множеств

В этом разделе описывается публичный API для объектов [`set`](https://python-all.ru/3/library/stdtypes.html#set) и [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset). Любую функциональность, не перечисленную ниже, лучше использовать через абстрактный протокол объектов (включая [`PyObject_CallMethod()`](https://python-all.ru/3/c-api/call.html#c.PyObject_CallMethod), [`PyObject_RichCompareBool()`](https://python-all.ru/3/c-api/object.html#c.PyObject_RichCompareBool), [`PyObject_Hash()`](https://python-all.ru/3/c-api/object.html#c.PyObject_Hash), [`PyObject_Repr()`](https://python-all.ru/3/c-api/object.html#c.PyObject_Repr), [`PyObject_IsTrue()`](https://python-all.ru/3/c-api/object.html#c.PyObject_IsTrue), [`PyObject_Print()`](https://python-all.ru/3/c-api/object.html#c.PyObject_Print) и [`PyObject_GetIter()`](https://python-all.ru/3/c-api/object.html#c.PyObject_GetIter)) или абстрактный числовой протокол (включая [`PyNumber_And()`](https://python-all.ru/3/c-api/number.html#c.PyNumber_And), [`PyNumber_Subtract()`](https://python-all.ru/3/c-api/number.html#c.PyNumber_Subtract), [`PyNumber_Or()`](https://python-all.ru/3/c-api/number.html#c.PyNumber_Or), [`PyNumber_Xor()`](https://python-all.ru/3/c-api/number.html#c.PyNumber_Xor), [`PyNumber_InPlaceAnd()`](https://python-all.ru/3/c-api/number.html#c.PyNumber_InPlaceAnd), [`PyNumber_InPlaceSubtract()`](https://python-all.ru/3/c-api/number.html#c.PyNumber_InPlaceSubtract), [`PyNumber_InPlaceOr()`](https://python-all.ru/3/c-api/number.html#c.PyNumber_InPlaceOr) и [`PyNumber_InPlaceXor()`](https://python-all.ru/3/c-api/number.html#c.PyNumber_InPlaceXor)).

#### `type PySetObject`

Этот подтип [`PyObject`](https://python-all.ru/3/c-api/structures.html#c.PyObject) используется для хранения внутренних данных как для объектов [`set`](https://python-all.ru/3/library/stdtypes.html#set), так и для [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset). Он похож на [`PyDictObject`](https://python-all.ru/3/c-api/dict.html#c.PyDictObject): для небольших множеств имеет фиксированный размер (наподобие хранилища кортежей), а для множеств среднего и большого размера указывает на отдельный блок памяти переменного размера (наподобие хранилища списков). Ни одно из полей этой структуры не следует считать публичным, все они могут измениться. Весь доступ должен осуществляться через документированный API, а не через манипуляции значениями в структуре.

#### `PyTypeObject PySet_Type`

*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*

Это экземпляр [`PyTypeObject`](https://python-all.ru/3/c-api/type.html#c.PyTypeObject), представляющий тип [`set`](https://python-all.ru/3/library/stdtypes.html#set) Python.

#### `PyTypeObject PyFrozenSet_Type`

*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*

Это экземпляр [`PyTypeObject`](https://python-all.ru/3/c-api/type.html#c.PyTypeObject), представляющий тип [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset) Python.

Следующие макросы проверки типа работают с указателями на любой объект Python. Аналогично, функции-конструкторы работают с любым итерируемым объектом Python.

#### `int PySet_Check(PyObject *p)`

Возвращает true, если *p* является объектом [`set`](https://python-all.ru/3/library/stdtypes.html#set) или экземпляром подтипа. Эта функция всегда завершается успешно.

#### `int PyFrozenSet_Check(PyObject *p)`

Возвращает true, если *p* является объектом [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset) или экземпляром подтипа. Эта функция всегда завершается успешно.

#### `int PyAnySet_Check(PyObject *p)`

Возвращает true, если *p* является объектом [`set`](https://python-all.ru/3/library/stdtypes.html#set), объектом [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset) или экземпляром подтипа. Эта функция всегда завершается успешно.

#### `int PySet_CheckExact(PyObject *p)`

Возвращает true, если *p* является объектом [`set`](https://python-all.ru/3/library/stdtypes.html#set), но не экземпляром подтипа. Эта функция всегда завершается успешно.

Добавлено в версии 3.10.

#### `int PyAnySet_CheckExact(PyObject *p)`

Возвращает true, если *p* является объектом [`set`](https://python-all.ru/3/library/stdtypes.html#set) или объектом [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset), но не экземпляром подтипа. Эта функция всегда завершается успешно.

#### `int PyFrozenSet_CheckExact(PyObject *p)`

Возвращает true, если *p* является объектом [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset), но не экземпляром подтипа. Эта функция всегда завершается успешно.

#### `PyObject *PySet_New(PyObject *iterable)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*

*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3/library/threadsafety.html#threadsafety-level-shared).*

Возвращает новый [`set`](https://python-all.ru/3/library/stdtypes.html#set), содержащий объекты, полученные из *iterable*. *iterable* может быть `NULL` для создания нового пустого множества. При успехе возвращает новое множество, при неудаче – `NULL`. Возбуждает [`TypeError`](https://python-all.ru/3/library/exceptions.html#TypeError), если *iterable* на самом деле не итерируем. Конструктор также удобен для копирования множества (`c=set(s)`).

> **Примечание**
>
> Операция атомарна в [free threading](https://python-all.ru/3/glossary.html#term-free-threaded-build) когда *iterable* является [`set`](https://python-all.ru/3/library/stdtypes.html#set), [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset) или [`dict`](https://python-all.ru/3/library/stdtypes.html#dict).

#### `PyObject *PyFrozenSet_New(PyObject *iterable)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*

*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3/library/threadsafety.html#threadsafety-level-shared).*

Возвращает новый [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset), содержащий объекты, полученные из *iterable*. *iterable* может быть `NULL` для создания нового пустого frozenset. При успехе возвращает новое множество, при неудаче – `NULL`. Возбуждает [`TypeError`](https://python-all.ru/3/library/exceptions.html#TypeError), если *iterable* на самом деле не итерируем.

> **Примечание**
>
> Операция атомарна в [free threading](https://python-all.ru/3/glossary.html#term-free-threaded-build) когда *iterable* является [`set`](https://python-all.ru/3/library/stdtypes.html#set), [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset) или [`dict`](https://python-all.ru/3/library/stdtypes.html#dict).

Следующие функции и макросы доступны для экземпляров [`set`](https://python-all.ru/3/library/stdtypes.html#set) или [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset), или экземпляров их подтипов.

#### `Py_ssize_t PySet_Size(PyObject *anyset)`

*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*

*Потокобезопасность: [Атомарно](https://python-all.ru/3/library/threadsafety.html#threadsafety-level-atomic).*

Возвращает длину объекта [`set`](https://python-all.ru/3/library/stdtypes.html#set) или [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset). Эквивалентно `len(anyset)`. Возбуждает [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError), если *anyset* не является `set`, `frozenset` или экземпляром подтипа.

#### `Py_ssize_t PySet_GET_SIZE(PyObject *anyset)`

*Потокобезопасность: [атомарно](https://python-all.ru/3/library/threadsafety.html#threadsafety-level-atomic).*

Макроформа [`PySet_Size()`](https://python-all.ru/3/c-api/set.html#c.PySet_Size) без проверки ошибок.

#### `int PySet_Contains(PyObject *anyset, PyObject *key)`

*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*

*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3/library/threadsafety.html#threadsafety-level-shared).*

Возвращает `1`, если элемент найден, `0`, если не найден, и `-1`, если произошла ошибка. В отличие от метода [`__contains__()`](https://python-all.ru/3/reference/datamodel.html#object.__contains__) в Python, эта функция не преобразует автоматически нехэшируемые множества во временные замороженные множества. Возбуждает [`TypeError`](https://python-all.ru/3/library/exceptions.html#TypeError), если *ключ* нехэшируем. Возбуждает [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError), если *любой набор* не является [`set`](https://python-all.ru/3/library/stdtypes.html#set), [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset) или экземпляром подтипа.

> **Примечание**
>
> Операция является атомарной в [сборке со свободной многопоточностью](https://python-all.ru/3/glossary.html#term-free-threaded-build) когда *key* является [`str`](https://python-all.ru/3/library/stdtypes.html#str), [`int`](https://python-all.ru/3/library/functions.html#int), [`float`](https://python-all.ru/3/library/functions.html#float), [`bool`](https://python-all.ru/3/library/functions.html#bool) или [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes).

#### `int PySet_Add(PyObject *set, PyObject *key)`

*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*

*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3/library/threadsafety.html#threadsafety-level-shared).*

Добавляет *ключ* в экземпляр [`set`](https://python-all.ru/3/library/stdtypes.html#set). Также работает с экземплярами [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset) (как и [`PyTuple_SetItem()`](https://python-all.ru/3/c-api/tuple.html#c.PyTuple_SetItem), может использоваться для заполнения значений новых неизменяемых множеств до того, как они будут открыты другому коду). Возвращает `0` в случае успеха или `-1` при неудаче. Возбуждает [`TypeError`](https://python-all.ru/3/library/exceptions.html#TypeError), если *ключ* нехэшируем. Возбуждает [`MemoryError`](https://python-all.ru/3/library/exceptions.html#MemoryError), если нет места для роста. Возбуждает [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError), если *set* не является экземпляром `set` или его подтипа.

> **Примечание**
>
> Операция является атомарной в [сборке со свободной многопоточностью](https://python-all.ru/3/glossary.html#term-free-threaded-build) когда *key* является [`str`](https://python-all.ru/3/library/stdtypes.html#str), [`int`](https://python-all.ru/3/library/functions.html#int), [`float`](https://python-all.ru/3/library/functions.html#float), [`bool`](https://python-all.ru/3/library/functions.html#bool) или [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes).

Следующие функции доступны для экземпляров [`set`](https://python-all.ru/3/library/stdtypes.html#set) или его подтипов, но не для экземпляров [`frozenset`](https://python-all.ru/3/library/stdtypes.html#frozenset) или его подтипов.

#### `int PySet_Discard(PyObject *set, PyObject *key)`

*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*

*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3/library/threadsafety.html#threadsafety-level-shared).*

Возвращает `1`, если элемент найден и удалён, `0`, если не найден (действие не выполняется), и `-1`, если произошла ошибка. Не возбуждает [`KeyError`](https://python-all.ru/3/library/exceptions.html#KeyError) для отсутствующих ключей. Возбуждает [`TypeError`](https://python-all.ru/3/library/exceptions.html#TypeError), если *ключ* нехэшируем. В отличие от метода [`discard()`](https://python-all.ru/3/library/stdtypes.html#set.discard) в Python, эта функция не преобразует автоматически нехэшируемые множества во временные замороженные множества. Возбуждает [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError), если *множество* не является экземпляром [`set`](https://python-all.ru/3/library/stdtypes.html#set) или его подтипа.

> **Примечание**
>
> Операция является атомарной в [сборке со свободной многопоточностью](https://python-all.ru/3/glossary.html#term-free-threaded-build) когда *key* является [`str`](https://python-all.ru/3/library/stdtypes.html#str), [`int`](https://python-all.ru/3/library/functions.html#int), [`float`](https://python-all.ru/3/library/functions.html#float), [`bool`](https://python-all.ru/3/library/functions.html#bool) или [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes).

#### `PyObject *PySet_Pop(PyObject *set)`

*Возвращаемое значение: новая ссылка.*

*Часть [стабильного ABI](https://python-all.ru/3/c-api/stable.html#stable).*

*Потокобезопасность: [атомарно](https://python-all.ru/3/library/threadsafety.html#threadsafety-level-atomic).*

Возвращает новую ссылку на произвольный объект в *множестве* и удаляет этот объект из *множества*. Возвращает `NULL` при неудаче. Возбуждает [`KeyError`](https://python-all.ru/3/library/exceptions.html#KeyError), если множество пусто. Возбуждает [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError), если *set* не является экземпляром [`set`](https://python-all.ru/3/library/stdtypes.html#set) или его подтипа.

#### `int PySet_Clear(PyObject *set)`

*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*

*Потокобезопасность: [Атомарно](https://python-all.ru/3/library/threadsafety.html#threadsafety-level-atomic).*

Опустошает существующее множество, удаляя все элементы. Возвращает `0` в случае успеха. Возвращает `-1` и возбуждает [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError), если *set* не является экземпляром [`set`](https://python-all.ru/3/library/stdtypes.html#set) или его подтипа.

> **Примечание**
>
> В [сборке со свободными потоками](https://python-all.ru/3/glossary.html#term-free-threaded-build) множество опустошается до очистки своих записей, поэтому другие потоки увидят пустое множество, а не промежуточные состояния.

## Устаревший API

#### `PySet_MINSIZE`

Константа, представляющая размер внутренней предварительно выделенной таблицы в экземплярах [`PySetObject`](https://python-all.ru/3/c-api/set.html#c.PySetObject).

Она задокументирована исключительно для полноты, поскольку нет гарантий, что данная версия CPython использует предварительно выделенные таблицы фиксированного размера. В коде, который не работает с нестабильными внутренностями множеств, `PySet_MINSIZE` можно заменить небольшой константой, например `8`.

Если нужно узнать размер множества, используйте [`PySet_Size()`](https://python-all.ru/3/c-api/set.html#c.PySet_Size).

[Soft deprecated](https://python-all.ru/3/glossary.html#term-soft-deprecated) since version 3.14.