Set Objects¶

This section details the public API forset andfrozensetobjects. Any functionality not listed below is best accessed using eitherthe abstract object protocol (includingPyObject_CallMethod(),PyObject_RichCompareBool(),PyObject_Hash(),PyObject_Repr(),PyObject_IsTrue(),PyObject_Print(), andPyObject_GetIter()) or the abstract number protocol (includingPyNumber_And(),PyNumber_Subtract(),PyNumber_Or(),PyNumber_Xor(),PyNumber_InPlaceAnd(),PyNumber_InPlaceSubtract(),PyNumber_InPlaceOr(), andPyNumber_InPlaceXor()).

typePySetObject¶

This subtype ofPyObject is used to hold the internal data for bothset andfrozenset objects. It is like aPyDictObjectin that it is a fixed size for small sets (much like tuple storage) and willpoint to a separate, variable sized block of memory for medium and large sizedsets (much like list storage). None of the fields of this structure should beconsidered public and all are subject to change. All access should be done throughthe documented API rather than by manipulating the values in the structure.

PyTypeObjectPySet_Type¶

Part of theStable ABI.

This is an instance ofPyTypeObject representing the Pythonset type.

PyTypeObjectPyFrozenSet_Type¶

Part of theStable ABI.

This is an instance ofPyTypeObject representing the Pythonfrozenset type.

The following type check macros work on pointers to any Python object. Likewise,the constructor functions work with any iterable Python object.

intPySet_Check(PyObject*p)¶

Return true ifp is aset object or an instance of a subtype.This function always succeeds.

intPyFrozenSet_Check(PyObject*p)¶

Return true ifp is afrozenset object or an instance of asubtype. This function always succeeds.

intPyAnySet_Check(PyObject*p)¶

Return true ifp is aset object, afrozenset object, or aninstance of a subtype. This function always succeeds.

intPySet_CheckExact(PyObject*p)¶

Return true ifp is aset object but not an instance of asubtype. This function always succeeds.

Added in version 3.10.

intPyAnySet_CheckExact(PyObject*p)¶

Return true ifp is aset object or afrozenset object butnot an instance of a subtype. This function always succeeds.

intPyFrozenSet_CheckExact(PyObject*p)¶

Return true ifp is afrozenset object but not an instance of asubtype. This function always succeeds.

PyObject*PySet_New(PyObject*iterable)¶

Return value: New reference. Part of theStable ABI.

Return a newset containing objects returned by theiterable. Theiterable may beNULL to create a new empty set. Return the new set onsuccess orNULL on failure. RaiseTypeError ifiterable is notactually iterable. The constructor is also useful for copying a set(c=set(s)).

PyObject*PyFrozenSet_New(PyObject*iterable)¶

Return value: New reference. Part of theStable ABI.

Return a newfrozenset containing objects returned by theiterable.Theiterable may beNULL to create a new empty frozenset. Return the newset on success orNULL on failure. RaiseTypeError ifiterable isnot actually iterable.

The following functions and macros are available for instances ofsetorfrozenset or instances of their subtypes.

Py_ssize_tPySet_Size(PyObject*anyset)¶

Part of theStable ABI.

Return the length of aset orfrozenset object. Equivalent tolen(anyset). Raises aSystemError ifanyset is not aset,frozenset, or an instance of a subtype.

Py_ssize_tPySet_GET_SIZE(PyObject*anyset)¶

Macro form ofPySet_Size() without error checking.

intPySet_Contains(PyObject*anyset,PyObject*key)¶

Part of theStable ABI.

Return1 if found,0 if not found, and-1 if an error is encountered. Unlikethe Python__contains__() method, this function does not automaticallyconvert unhashable sets into temporary frozensets. Raise aTypeError ifthekey is unhashable. RaiseSystemError ifanyset is not aset,frozenset, or an instance of a subtype.

intPySet_Add(PyObject*set,PyObject*key)¶

Part of theStable ABI.

Addkey to aset instance. Also works withfrozensetinstances (likePyTuple_SetItem() it can be used to fill in the valuesof brand new frozensets before they are exposed to other code). Return0 onsuccess or-1 on failure. Raise aTypeError if thekey isunhashable. Raise aMemoryError if there is no room to grow. Raise aSystemError ifset is not an instance ofset or itssubtype.

The following functions are available for instances ofset or itssubtypes but not for instances offrozenset or its subtypes.

intPySet_Discard(PyObject*set,PyObject*key)¶

Part of theStable ABI.

Return1 if found and removed,0 if not found (no action taken), and-1 if anerror is encountered. Does not raiseKeyError for missing keys. Raise aTypeError if thekey is unhashable. Unlike the Pythondiscard()method, this function does not automatically convert unhashable sets intotemporary frozensets. RaiseSystemError ifset is not aninstance ofset or its subtype.

PyObject*PySet_Pop(PyObject*set)¶

Return value: New reference. Part of theStable ABI.

Return a new reference to an arbitrary object in theset, and removes theobject from theset. ReturnNULL on failure. RaiseKeyError if theset is empty. Raise aSystemError ifset is not an instance ofset or its subtype.

intPySet_Clear(PyObject*set)¶

Part of theStable ABI.

Empty an existing set of all elements. Return0 onsuccess. Return-1 and raiseSystemError ifset is not an instance ofset or its subtype.