# Набір об’єктів

У цьому розділі детально описано публічний 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
  Part of the Stable ABI.

  Це екземпляр `PyTypeObject`, що представляє тип `set` Python.

PyTypeObject PyFrozenSet_Type
  Part of the 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`, але не екземпляром підтипу. Ця функція завжди успішна.

  Added in version 3.10.

int PyAnySet_CheckExact(PyObject *p)

  Повертає true, якщо p є об’єктом `set` або об’єктом `frozenset`, але не екземпляром підтипу. Ця функція завжди успішна.

int PyFrozenSet_CheckExact(PyObject *p)

  Повертає true, якщо p є об’єктом `frozenset`, але не є екземпляром підтипу. Ця функція завжди успішна.

PyObject *PySet_New(PyObject *iterable)
  Return value: New reference. Part of the Stable ABI. Thread safety: Safe for concurrent use on the same object.

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

  Примітка

  The operation is atomic on free threading when iterable is a `set`, `frozenset`, `dict` or `frozendict`.

PyObject *PyFrozenSet_New(PyObject *iterable)
  Return value: New reference. Part of the Stable ABI. Thread safety: Safe for concurrent use on the same object.

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

  Примітка

  The operation is atomic on free threading when iterable is a `set`, `frozenset`, `dict` or `frozendict`.

Наступні функції та макроси доступні для екземплярів `set` або `frozenset` або екземплярів їхніх підтипів.

Py_ssize_t PySet_Size(PyObject *anyset)
  Part of the Stable ABI. Thread safety: Atomic.

  Return the length of a `set` or `frozenset` object. Equivalent to `len(anyset)`. Raises a `SystemError` if anyset is not a `set`, `frozenset`, or an instance of a subtype.

Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
  Thread safety: Atomic.

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

int PySet_Contains(PyObject *anyset, PyObject *key)
  Part of the Stable ABI. Thread safety: Safe for concurrent use on the same object.

  Return `1` if found, `0` if not found, and `-1` if an error is encountered. Unlike the Python `__contains__()` method, this function does not automatically convert unhashable sets into temporary frozensets. Raise a `TypeError` if the key is unhashable. Raise `SystemError` if anyset is not a `set`, `frozenset`, or an instance of a subtype.

  Примітка

  The operation is atomic on free threading when key is `str`, `int`, `float`, `bool` or `bytes`.

int PySet_Add(PyObject *set, PyObject *key)
  Part of the Stable ABI. Thread safety: Safe for concurrent use on the same object.

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

  Примітка

  The operation is atomic on free threading when key is `str`, `int`, `float`, `bool` or `bytes`.

Наступні функції доступні для екземплярів `set` або його підтипів, але не для екземплярів `frozenset` або його підтипів.

int PySet_Discard(PyObject *set, PyObject *key)
  Part of the Stable ABI. Thread safety: Safe for concurrent use on the same object.

  Return `1` if found and removed, `0` if not found (no action taken), and `-1` if an error is encountered. Does not raise `KeyError` for missing keys. Raise a `TypeError` if the key is unhashable. Unlike the Python `discard()` method, this function does not automatically convert unhashable sets into temporary frozensets. Raise `SystemError` if set is not an instance of `set` or its subtype.

  Примітка

  The operation is atomic on free threading when key is `str`, `int`, `float`, `bool` or `bytes`.

PyObject *PySet_Pop(PyObject *set)
  Return value: New reference. Part of the Stable ABI. Thread safety: Atomic.

  Повертає нове посилання на довільний об’єкт у set та видаляє об’єкт із set. Повертає `NULL` у разі помилки. Викликати `KeyError`, якщо набір порожній. Викликати `SystemError`, якщо set не є екземпляром `set` або його підтипу.

int PySet_Clear(PyObject *set)
  Part of the Stable ABI. Thread safety: Atomic.

  Empty an existing set of all elements. Return `0` on success. Return `-1` and raise `SystemError` if set is not an instance of `set` or its subtype.

  Примітка

  In the free-threaded build, the set is emptied before its entries are cleared, so other threads will observe an empty set rather than intermediate states.

## Deprecated API

PySet_MINSIZE

  A constant representing the size of an internal preallocated table inside `PySetObject` instances.

  This is documented solely for completeness, as there are no guarantees that a given version of CPython uses preallocated tables with a fixed size. In code that does not deal with unstable set internals, `PySet_MINSIZE` can be replaced with a small constant like `8`.

  If looking for the size of a set, use `PySet_Size()` instead.

  Soft deprecated since version 3.14.