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

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