| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _setobjects: |
| 4 |
|
| 5 |
Set Objects |
| 6 |
----------- |
| 7 |
|
| 8 |
.. sectionauthor:: Raymond D. Hettinger <[email protected]> |
| 9 |
|
| 10 |
|
| 11 |
.. index:: |
| 12 |
pair: object; set |
| 13 |
pair: object; frozenset |
| 14 |
|
| 15 |
This section details the public API for :class:`set` and :class:`frozenset` |
| 16 |
objects. Any functionality not listed below is best accessed using either |
| 17 |
the abstract object protocol (including :c:func:`PyObject_CallMethod`, |
| 18 |
:c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`, |
| 19 |
:c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and |
| 20 |
:c:func:`PyObject_GetIter`) or the abstract number protocol (including |
| 21 |
:c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`, |
| 22 |
:c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`, |
| 23 |
:c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and |
| 24 |
:c:func:`PyNumber_InPlaceXor`). |
| 25 |
|
| 26 |
|
| 27 |
.. c:type:: PySetObject |
| 28 |
|
| 29 |
This subtype of :c:type:`PyObject` is used to hold the internal data for both |
| 30 |
:class:`set` and :class:`frozenset` objects. It is like a :c:type:`PyDictObject` |
| 31 |
in that it is a fixed size for small sets (much like tuple storage) and will |
| 32 |
point to a separate, variable sized block of memory for medium and large sized |
| 33 |
sets (much like list storage). None of the fields of this structure should be |
| 34 |
considered public and all are subject to change. All access should be done through |
| 35 |
the documented API rather than by manipulating the values in the structure. |
| 36 |
|
| 37 |
|
| 38 |
.. c:var:: PyTypeObject PySet_Type |
| 39 |
|
| 40 |
This is an instance of :c:type:`PyTypeObject` representing the Python |
| 41 |
:class:`set` type. |
| 42 |
|
| 43 |
|
| 44 |
.. c:var:: PyTypeObject PyFrozenSet_Type |
| 45 |
|
| 46 |
This is an instance of :c:type:`PyTypeObject` representing the Python |
| 47 |
:class:`frozenset` type. |
| 48 |
|
| 49 |
The following type check macros work on pointers to any Python object. Likewise, |
| 50 |
the constructor functions work with any iterable Python object. |
| 51 |
|
| 52 |
|
| 53 |
.. c:function:: int PySet_Check(PyObject *p) |
| 54 |
|
| 55 |
Return true if *p* is a :class:`set` object or an instance of a subtype. |
| 56 |
This function always succeeds. |
| 57 |
|
| 58 |
.. c:function:: int PyFrozenSet_Check(PyObject *p) |
| 59 |
|
| 60 |
Return true if *p* is a :class:`frozenset` object or an instance of a |
| 61 |
subtype. This function always succeeds. |
| 62 |
|
| 63 |
.. c:function:: int PyAnySet_Check(PyObject *p) |
| 64 |
|
| 65 |
Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an |
| 66 |
instance of a subtype. This function always succeeds. |
| 67 |
|
| 68 |
.. c:function:: int PySet_CheckExact(PyObject *p) |
| 69 |
|
| 70 |
Return true if *p* is a :class:`set` object but not an instance of a |
| 71 |
subtype. This function always succeeds. |
| 72 |
|
| 73 |
.. versionadded:: 3.10 |
| 74 |
|
| 75 |
.. c:function:: int PyAnySet_CheckExact(PyObject *p) |
| 76 |
|
| 77 |
Return true if *p* is a :class:`set` object or a :class:`frozenset` object but |
| 78 |
not an instance of a subtype. This function always succeeds. |
| 79 |
|
| 80 |
|
| 81 |
.. c:function:: int PyFrozenSet_CheckExact(PyObject *p) |
| 82 |
|
| 83 |
Return true if *p* is a :class:`frozenset` object but not an instance of a |
| 84 |
subtype. This function always succeeds. |
| 85 |
|
| 86 |
|
| 87 |
.. c:function:: PyObject* PySet_New(PyObject *iterable) |
| 88 |
|
| 89 |
Return a new :class:`set` containing objects returned by the *iterable*. The |
| 90 |
*iterable* may be ``NULL`` to create a new empty set. Return the new set on |
| 91 |
success or ``NULL`` on failure. Raise :exc:`TypeError` if *iterable* is not |
| 92 |
actually iterable. The constructor is also useful for copying a set |
| 93 |
(``c=set(s)``). |
| 94 |
|
| 95 |
.. note:: |
| 96 |
|
| 97 |
The operation is atomic on :term:`free threading <free-threaded build>` |
| 98 |
when *iterable* is a :class:`set`, :class:`frozenset` or :class:`dict`. |
| 99 |
|
| 100 |
|
| 101 |
.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable) |
| 102 |
|
| 103 |
Return a new :class:`frozenset` containing objects returned by the *iterable*. |
| 104 |
The *iterable* may be ``NULL`` to create a new empty frozenset. Return the new |
| 105 |
set on success or ``NULL`` on failure. Raise :exc:`TypeError` if *iterable* is |
| 106 |
not actually iterable. |
| 107 |
|
| 108 |
.. note:: |
| 109 |
|
| 110 |
The operation is atomic on :term:`free threading <free-threaded build>` |
| 111 |
when *iterable* is a :class:`set`, :class:`frozenset` or :class:`dict`. |
| 112 |
|
| 113 |
|
| 114 |
The following functions and macros are available for instances of :class:`set` |
| 115 |
or :class:`frozenset` or instances of their subtypes. |
| 116 |
|
| 117 |
|
| 118 |
.. c:function:: Py_ssize_t PySet_Size(PyObject *anyset) |
| 119 |
|
| 120 |
.. index:: pair: built-in function; len |
| 121 |
|
| 122 |
Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to |
| 123 |
``len(anyset)``. Raises a :exc:`SystemError` if *anyset* is not a |
| 124 |
:class:`set`, :class:`frozenset`, or an instance of a subtype. |
| 125 |
|
| 126 |
|
| 127 |
.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset) |
| 128 |
|
| 129 |
Macro form of :c:func:`PySet_Size` without error checking. |
| 130 |
|
| 131 |
|
| 132 |
.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key) |
| 133 |
|
| 134 |
Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike |
| 135 |
the Python :meth:`~object.__contains__` method, this function does not automatically |
| 136 |
convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if |
| 137 |
the *key* is unhashable. Raise :exc:`SystemError` if *anyset* is not a |
| 138 |
:class:`set`, :class:`frozenset`, or an instance of a subtype. |
| 139 |
|
| 140 |
.. note:: |
| 141 |
|
| 142 |
The operation is atomic on :term:`free threading <free-threaded build>` |
| 143 |
when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`. |
| 144 |
|
| 145 |
.. c:function:: int PySet_Add(PyObject *set, PyObject *key) |
| 146 |
|
| 147 |
Add *key* to a :class:`set` instance. Also works with :class:`frozenset` |
| 148 |
instances (like :c:func:`PyTuple_SetItem` it can be used to fill in the values |
| 149 |
of brand new frozensets before they are exposed to other code). Return ``0`` on |
| 150 |
success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is |
| 151 |
unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a |
| 152 |
:exc:`SystemError` if *set* is not an instance of :class:`set` or its |
| 153 |
subtype. |
| 154 |
|
| 155 |
.. note:: |
| 156 |
|
| 157 |
The operation is atomic on :term:`free threading <free-threaded build>` |
| 158 |
when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`. |
| 159 |
|
| 160 |
|
| 161 |
|
| 162 |
The following functions are available for instances of :class:`set` or its |
| 163 |
subtypes but not for instances of :class:`frozenset` or its subtypes. |
| 164 |
|
| 165 |
|
| 166 |
.. c:function:: int PySet_Discard(PyObject *set, PyObject *key) |
| 167 |
|
| 168 |
Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an |
| 169 |
error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a |
| 170 |
:exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard` |
| 171 |
method, this function does not automatically convert unhashable sets into |
| 172 |
temporary frozensets. Raise :exc:`SystemError` if *set* is not an |
| 173 |
instance of :class:`set` or its subtype. |
| 174 |
|
| 175 |
.. note:: |
| 176 |
|
| 177 |
The operation is atomic on :term:`free threading <free-threaded build>` |
| 178 |
when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`. |
| 179 |
|
| 180 |
|
| 181 |
.. c:function:: PyObject* PySet_Pop(PyObject *set) |
| 182 |
|
| 183 |
Return a new reference to an arbitrary object in the *set*, and removes the |
| 184 |
object from the *set*. Return ``NULL`` on failure. Raise :exc:`KeyError` if the |
| 185 |
set is empty. Raise a :exc:`SystemError` if *set* is not an instance of |
| 186 |
:class:`set` or its subtype. |
| 187 |
|
| 188 |
|
| 189 |
.. c:function:: int PySet_Clear(PyObject *set) |
| 190 |
|
| 191 |
Empty an existing set of all elements. Return ``0`` on |
| 192 |
success. Return ``-1`` and raise :exc:`SystemError` if *set* is not an instance of |
| 193 |
:class:`set` or its subtype. |
| 194 |
|
| 195 |
.. note:: |
| 196 |
|
| 197 |
In the :term:`free-threaded build`, the set is emptied before its entries |
| 198 |
are cleared, so other threads will observe an empty set rather than |
| 199 |
intermediate states. |
| 200 |
|
| 201 |
|
| 202 |
Deprecated API |
| 203 |
^^^^^^^^^^^^^^ |
| 204 |
|
| 205 |
.. c:macro:: PySet_MINSIZE |
| 206 |
|
| 207 |
A :term:`soft deprecated` constant representing the size of an internal |
| 208 |
preallocated table inside :c:type:`PySetObject` instances. |
| 209 |
|
| 210 |
This is documented solely for completeness, as there are no guarantees |
| 211 |
that a given version of CPython uses preallocated tables with a fixed |
| 212 |
size. |
| 213 |
In code that does not deal with unstable set internals, |
| 214 |
:c:macro:`!PySet_MINSIZE` can be replaced with a small constant like ``8``. |
| 215 |
|
| 216 |
If looking for the size of a set, use :c:func:`PySet_Size` instead. |