FM / c-api

/usr/share/doc/python3-docs/html/_sources/c-api/

/usr/share/doc/python3-docs/html/_sources/c-api

Name	Size	Mode	Actions
abstract.rst.txt	715	0644	edit dl rm
allocation.rst.txt	2653	0644	edit dl rm
apiabiversion.rst.txt	2242	0644	edit dl rm
arg.rst.txt	30651	0644	edit dl rm
bool.rst.txt	1200	0644	edit dl rm
buffer.rst.txt	22267	0644	edit dl rm
bytearray.rst.txt	2250	0644	edit dl rm
bytes.rst.txt	9211	0644	edit dl rm
capsule.rst.txt	5741	0644	edit dl rm
cell.rst.txt	1940	0644	edit dl rm
code.rst.txt	1666	0644	edit dl rm
codec.rst.txt	4799	0644	edit dl rm
complex.rst.txt	3946	0644	edit dl rm
concrete.rst.txt	2046	0644	edit dl rm
conversion.rst.txt	5516	0644	edit dl rm
coro.rst.txt	820	0644	edit dl rm
datetime.rst.txt	6415	0644	edit dl rm
descriptor.rst.txt	1111	0644	edit dl rm
dict.rst.txt	7952	0644	edit dl rm
exceptions.rst.txt	47814	0644	edit dl rm
file.rst.txt	3248	0644	edit dl rm
float.rst.txt	2243	0644	edit dl rm
function.rst.txt	3348	0644	edit dl rm
gcsupport.rst.txt	6057	0644	edit dl rm
gen.rst.txt	1301	0644	edit dl rm
import.rst.txt	12825	0644	edit dl rm
index.rst.txt	613	0644	edit dl rm
init.rst.txt	52383	0644	edit dl rm
intro.rst.txt	28751	0644	edit dl rm
iter.rst.txt	1129	0644	edit dl rm
iterator.rst.txt	1640	0644	edit dl rm
list.rst.txt	4735	0644	edit dl rm
long.rst.txt	10436	0644	edit dl rm
mapping.rst.txt	2871	0644	edit dl rm
marshal.rst.txt	3561	0644	edit dl rm
memory.rst.txt	21369	0644	edit dl rm
memoryview.rst.txt	2348	0644	edit dl rm
method.rst.txt	2818	0644	edit dl rm
module.rst.txt	18266	0644	edit dl rm
none.rst.txt	740	0644	edit dl rm
number.rst.txt	10583	0644	edit dl rm
objbuffer.rst.txt	2198	0644	edit dl rm
object.rst.txt	17420	0644	edit dl rm
objimpl.rst.txt	304	0644	edit dl rm
refcounting.rst.txt	2909	0644	edit dl rm
reflection.rst.txt	1417	0644	edit dl rm
sequence.rst.txt	6547	0644	edit dl rm
set.rst.txt	6144	0644	edit dl rm
slice.rst.txt	2404	0644	edit dl rm
stable.rst.txt	1969	0644	edit dl rm
structures.rst.txt	13787	0644	edit dl rm
sys.rst.txt	9944	0644	edit dl rm
tuple.rst.txt	8031	0644	edit dl rm
type.rst.txt	3963	0644	edit dl rm
typeobj.rst.txt	60184	0644	edit dl rm
unicode.rst.txt	68074	0644	edit dl rm
utilities.rst.txt	414	0644	edit dl rm
veryhigh.rst.txt	16655	0644	edit dl rm
weakref.rst.txt	2635	0644	edit dl rm

Edit: /usr/share/doc/python3-docs/html/_sources/c-api/set.rst.txt (6144B)

.. highlightlang:: c

.. _setobjects:

Set Objects
-----------

.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>

.. index::
   object: set
   object: frozenset

This section details the public API for :class:`set` and :class:`frozenset`
objects.  Any functionality not listed below is best accessed using the either
the abstract object protocol (including :c:func:`PyObject_CallMethod`,
:c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`,
:c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and
:c:func:`PyObject_GetIter`) or the abstract number protocol (including
:c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`,
:c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`,
:c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and
:c:func:`PyNumber_InPlaceXor`).

.. c:type:: PySetObject

This subtype of :c:type:`PyObject` is used to hold the internal data for both
   :class:`set` and :class:`frozenset` objects.  It is like a :c:type:`PyDictObject`
   in that it is a fixed size for small sets (much like tuple storage) and will
   point to a separate, variable sized block of memory for medium and large sized
   sets (much like list storage). None of the fields of this structure should be
   considered public and are subject to change.  All access should be done through
   the documented API rather than by manipulating the values in the structure.

.. c:var:: PyTypeObject PySet_Type

This is an instance of :c:type:`PyTypeObject` representing the Python
   :class:`set` type.

.. c:var:: PyTypeObject PyFrozenSet_Type

This is an instance of :c:type:`PyTypeObject` representing the Python
   :class:`frozenset` type.

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

.. c:function:: int PySet_Check(PyObject *p)

Return true if *p* is a :class:`set` object or an instance of a subtype.

.. c:function:: int PyFrozenSet_Check(PyObject *p)

Return true if *p* is a :class:`frozenset` object or an instance of a
   subtype.

.. c:function:: int PyAnySet_Check(PyObject *p)

Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
   instance of a subtype.

.. c:function:: int PyAnySet_CheckExact(PyObject *p)

Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
   not an instance of a subtype.

.. c:function:: int PyFrozenSet_CheckExact(PyObject *p)

Return true if *p* is a :class:`frozenset` object but not an instance of a
   subtype.

.. c:function:: PyObject* PySet_New(PyObject *iterable)

Return a new :class:`set` containing objects returned by the *iterable*.  The
   *iterable* may be *NULL* to create a new empty set.  Return the new set on
   success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is not
   actually iterable.  The constructor is also useful for copying a set
   (``c=set(s)``).

.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)

Return a new :class:`frozenset` containing objects returned by the *iterable*.
   The *iterable* may be *NULL* to create a new empty frozenset.  Return the new
   set on success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is
   not actually iterable.

The following functions and macros are available for instances of :class:`set`
or :class:`frozenset` or instances of their subtypes.

.. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)

.. index:: builtin: len

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

.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

Macro form of :c:func:`PySet_Size` without error checking.

.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)

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

.. c:function:: int PySet_Add(PyObject *set, PyObject *key)

Add *key* to a :class:`set` instance.  Also works with :class:`frozenset`
   instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values
   of brand new frozensets before they are exposed to other code).  Return ``0`` on
   success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is
   unhashable. Raise a :exc:`MemoryError` if there is no room to grow.  Raise a
   :exc:`SystemError` if *set* is not an instance of :class:`set` or its
   subtype.

The following functions are available for instances of :class:`set` or its
subtypes but not for instances of :class:`frozenset` or its subtypes.

.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)

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

.. c:function:: PyObject* PySet_Pop(PyObject *set)

Return a new reference to an arbitrary object in the *set*, and removes the
   object from the *set*.  Return *NULL* on failure.  Raise :exc:`KeyError` if the
   set is empty. Raise a :exc:`SystemError` if *set* is not an instance of
   :class:`set` or its subtype.

.. c:function:: int PySet_Clear(PyObject *set)

Empty an existing set of all elements.

.. c:function:: int PySet_ClearFreeList()

Clear the free list. Return the total number of freed items.

.. versionadded:: 3.3

cmd: