Объекты множеств¶Set Objects

В этом разделе описывается публичный API для объектов set и frozenset. Любую функциональность, не перечисленную ниже, лучше использовать через абстрактный протокол объектов (включая PyObject_CallMethod(), PyObject_RichCompareBool(), PyObject_Hash(), PyObject_Repr(), PyObject_IsTrue(), PyObject_Print() и PyObject_GetIter()) или абстрактный числовой протокол (включая PyNumber_And(), PyNumber_Subtract(), PyNumber_Or(), PyNumber_Xor(), PyNumber_InPlaceAnd(), PyNumber_InPlaceSubtract(), PyNumber_InPlaceOr() и PyNumber_InPlaceXor()).

type PySetObject¶

Этот подтип PyObject используется для хранения внутренних данных как для объектов set, так и для frozenset. Он похож на PyDictObject: для небольших множеств имеет фиксированный размер (наподобие хранилища кортежей), а для множеств среднего и большого размера указывает на отдельный блок памяти переменного размера (наподобие хранилища списков). Ни одно из полей этой структуры не следует считать публичным, все они могут измениться. Весь доступ должен осуществляться через документированный API, а не через манипуляции значениями в структуре.

PyTypeObject PySet_Type¶

Часть Stable ABI.

Это экземпляр PyTypeObject, представляющий тип set Python.

PyTypeObject PyFrozenSet_Type¶

Часть Stable ABI.

Это экземпляр PyTypeObject, представляющий тип frozenset Python.

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

int PySet_Check(PyObject *p)¶

Возвращает true, если p является объектом set или экземпляром подтипа. Эта функция всегда завершается успешно.

int PyFrozenSet_Check(PyObject *p)¶

Возвращает true, если p является объектом frozenset или экземпляром подтипа. Эта функция всегда завершается успешно.

int PyAnySet_Check(PyObject *p)¶

Возвращает true, если p является объектом set, объектом frozenset или экземпляром подтипа. Эта функция всегда завершается успешно.

int PySet_CheckExact(PyObject *p)¶

Возвращает true, если p является объектом set, но не экземпляром подтипа. Эта функция всегда завершается успешно.

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

int PyAnySet_CheckExact(PyObject *p)¶

Возвращает true, если p является объектом set или объектом frozenset, но не экземпляром подтипа. Эта функция всегда завершается успешно.

int PyFrozenSet_CheckExact(PyObject *p)¶

Возвращает true, если p является объектом frozenset, но не экземпляром подтипа. Эта функция всегда завершается успешно.

PyObject *PySet_New(PyObject *iterable)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI. Потокобезопасность: Безопасно для одновременного использования на одном объекте.

Возвращает новый set, содержащий объекты, полученные из iterable. iterable может быть NULL для создания нового пустого множества. При успехе возвращает новое множество, при неудаче – NULL. Возбуждает TypeError, если iterable на самом деле не итерируем. Конструктор также удобен для копирования множества (c=set(s)).

Примечание

Операция атомарна на free threading, когда iterable является set, frozenset, dict или frozendict.

PyObject *PyFrozenSet_New(PyObject *iterable)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI. Потокобезопасность: Безопасно для одновременного использования на одном объекте.

Возвращает новый frozenset, содержащий объекты, полученные из iterable. iterable может быть NULL для создания нового пустого frozenset. При успехе возвращает новое множество, при неудаче – NULL. Возбуждает TypeError, если iterable на самом деле не итерируем.

Примечание

Операция атомарна на free threading, когда iterable является set, frozenset, dict или frozendict.

Следующие функции и макросы доступны для экземпляров set или frozenset, или экземпляров их подтипов.

Py_ssize_t PySet_Size(PyObject *anyset)¶

Часть Stable ABI.Потокобезопасность: Атомарно.

Возвращает длину объекта set или frozenset. Эквивалентно len(anyset). Возбуждает SystemError, если anyset не является set, frozenset или экземпляром подтипа.

Py_ssize_t PySet_GET_SIZE(PyObject *anyset)¶

Потокобезопасность: атомарно.

Макроформа PySet_Size() без проверки ошибок.

int PySet_Contains(PyObject *anyset, PyObject *key)¶

Часть Stable ABI. Потокобезопасность: Безопасно для одновременного использования на одном объекте.

Возвращает 1, если элемент найден, 0, если не найден, и -1, если произошла ошибка. В отличие от метода __contains__() в Python, эта функция не преобразует автоматически нехэшируемые множества во временные замороженные множества. Возбуждает TypeError, если ключ нехэшируем. Возбуждает SystemError, если любой набор не является set, frozenset или экземпляром подтипа.

Примечание

Операция является атомарной в сборке со свободной многопоточностью когда key является str, int, float, bool или bytes.

int PySet_Add(PyObject *set, PyObject *key)¶

Часть Stable ABI. Потокобезопасность: Безопасно для одновременного использования на одном объекте.

Добавляет ключ в экземпляр set. Также работает с экземплярами frozenset (как и PyTuple_SetItem(), может использоваться для заполнения значений новых неизменяемых множеств до того, как они будут открыты другому коду). Возвращает 0 в случае успеха или -1 при неудаче. Возбуждает TypeError, если ключ нехэшируем. Возбуждает MemoryError, если нет места для роста. Возбуждает SystemError, если set не является экземпляром set или его подтипа.

Примечание

Операция является атомарной в сборке со свободной многопоточностью когда key является str, int, float, bool или bytes.

Следующие функции доступны для экземпляров set или его подтипов, но не для экземпляров frozenset или его подтипов.

int PySet_Discard(PyObject *set, PyObject *key)¶

Часть Stable ABI. Потокобезопасность: Безопасно для одновременного использования на одном объекте.

Возвращает 1, если элемент найден и удалён, 0, если не найден (действие не выполняется), и -1, если произошла ошибка. Не возбуждает KeyError для отсутствующих ключей. Возбуждает TypeError, если ключ нехэшируем. В отличие от метода discard() в Python, эта функция не преобразует автоматически нехэшируемые множества во временные замороженные множества. Возбуждает SystemError, если множество не является экземпляром set или его подтипа.

Примечание

Операция является атомарной в сборке со свободной многопоточностью когда key является str, int, float, bool или bytes.

PyObject *PySet_Pop(PyObject *set)¶

Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.

Возвращает новую ссылку на произвольный объект в множестве и удаляет этот объект из множества. Возвращает NULL при неудаче. Возбуждает KeyError, если множество пусто. Возбуждает SystemError, если set не является экземпляром set или его подтипа.

int PySet_Clear(PyObject *set)¶

Часть Stable ABI.Потокобезопасность: Атомарно.

Опустошает существующее множество, удаляя все элементы. Возвращает 0 в случае успеха. Возвращает -1 и возбуждает SystemError, если set не является экземпляром set или его подтипа.

Примечание

В сборке со свободными потоками множество опустошается до очистки своих записей, поэтому другие потоки увидят пустое множество, а не промежуточные состояния.