third_party/cython/src/Cython/Includes/cpython/dict.pxd

   1 from cpython.ref cimport PyObject
   2
   3 cdef extern from "Python.h":
   4
   5     ############################################################################
   6     # 7.4.1 Dictionary Objects
   7     ############################################################################
   8
   9     # PyDictObject
  10     #
  11     # This subtype of PyObject represents a Python dictionary object
  12     # (i.e. the 'dict' type).
  13
  14     # PyTypeObject PyDict_Type
  15     #
  16     # This instance of PyTypeObject represents the Python dictionary
  17     # type. This is exposed to Python programs as dict and
  18     # types.DictType.
  19
  20     bint PyDict_Check(object p)
  21     # Return true if p is a dict object or an instance of a subtype of
  22     # the dict type.
  23
  24     bint PyDict_CheckExact(object p)
  25     # Return true if p is a dict object, but not an instance of a
  26     # subtype of the dict type.
  27
  28     object PyDict_New()
  29     # Return value: New reference.
  30     # Return a new empty dictionary, or NULL on failure.
  31
  32     object PyDictProxy_New(object dict)
  33     # Return value: New reference.
  34     # Return a proxy object for a mapping which enforces read-only
  35     # behavior. This is normally used to create a proxy to prevent
  36     # modification of the dictionary for non-dynamic class types.
  37
  38     void PyDict_Clear(object p)
  39     # Empty an existing dictionary of all key-value pairs.
  40
  41     int PyDict_Contains(object p, object key) except -1
  42     # Determine if dictionary p contains key. If an item in p is
  43     # matches key, return 1, otherwise return 0. On error, return
  44     # -1. This is equivalent to the Python expression "key in p".
  45
  46     object PyDict_Copy(object p)
  47     # Return value: New reference.
  48     # Return a new dictionary that contains the same key-value pairs as p.
  49
  50     int PyDict_SetItem(object p, object key, object val) except -1
  51     # Insert value into the dictionary p with a key of key. key must
  52     # be hashable; if it isn't, TypeError will be raised. Return 0 on
  53     # success or -1 on failure.
  54
  55     int PyDict_SetItemString(object p, char *key, object val) except -1
  56     # Insert value into the dictionary p using key as a key. key
  57     # should be a char*. The key object is created using
  58     # PyString_FromString(key). Return 0 on success or -1 on failure.
  59
  60     int PyDict_DelItem(object p, object key) except -1
  61     # Remove the entry in dictionary p with key key. key must be
  62     # hashable; if it isn't, TypeError is raised. Return 0 on success
  63     # or -1 on failure.
  64
  65     int PyDict_DelItemString(object p, char *key) except -1
  66     # Remove the entry in dictionary p which has a key specified by
  67     # the string key. Return 0 on success or -1 on failure.
  68
  69     PyObject* PyDict_GetItem(object p, object key)
  70     # Return value: Borrowed reference.
  71     # Return the object from dictionary p which has a key key. Return
  72     # NULL if the key key is not present, but without setting an
  73     # exception.
  74
  75     PyObject* PyDict_GetItemString(object p, char *key)
  76     # Return value: Borrowed reference.
  77     # This is the same as PyDict_GetItem(), but key is specified as a
  78     # char*, rather than a PyObject*.
  79
  80     object PyDict_Items(object p)
  81     # Return value: New reference.
  82     # Return a PyListObject containing all the items from the
  83     # dictionary, as in the dictionary method items() (see the Python
  84     # Library Reference).
  85
  86     object PyDict_Keys(object p)
  87     # Return value: New reference.
  88     # Return a PyListObject containing all the keys from the
  89     # dictionary, as in the dictionary method keys() (see the Python
  90     # Library Reference).
  91
  92     object PyDict_Values(object p)
  93     # Return value: New reference.
  94     # Return a PyListObject containing all the values from the
  95     # dictionary p, as in the dictionary method values() (see the
  96     # Python Library Reference).
  97
  98     Py_ssize_t PyDict_Size(object p) except -1
  99     # Return the number of items in the dictionary. This is equivalent
 100     # to "len(p)" on a dictionary.
 101
 102     int PyDict_Next(object p, Py_ssize_t *ppos, PyObject* *pkey, PyObject* *pvalue)
 103     # Iterate over all key-value pairs in the dictionary p. The int
 104     # referred to by ppos must be initialized to 0 prior to the first
 105     # call to this function to start the iteration; the function
 106     # returns true for each pair in the dictionary, and false once all
 107     # pairs have been reported. The parameters pkey and pvalue should
 108     # either point to PyObject* variables that will be filled in with
 109     # each key and value, respectively, or may be NULL. Any references
 110     # returned through them are borrowed. ppos should not be altered
 111     # during iteration. Its value represents offsets within the
 112     # internal dictionary structure, and since the structure is
 113     # sparse, the offsets are not consecutive.
 114     # For example:
 115     #
 116     #object key, *value;
 117     #int pos = 0;
 118     #
 119     #while (PyDict_Next(self->dict, &pos, &key, &value)) {
 120     #   /* do something interesting with the values... */
 121     #    ...
 122     #}
 123     # The dictionary p should not be mutated during iteration. It is
 124     # safe (since Python 2.1) to modify the values of the keys as you
 125     # iterate over the dictionary, but only so long as the set of keys
 126     # does not change. For example:
 127     # object key, *value;
 128     # int pos = 0;
 129     # while (PyDict_Next(self->dict, &pos, &key, &value)) {
 130     #    int i = PyInt_AS_LONG(value) + 1;
 131     #    object o = PyInt_FromLong(i);
 132     #    if (o == NULL)
 133     #        return -1;
 134     #    if (PyDict_SetItem(self->dict, key, o) < 0) {
 135     #        Py_DECREF(o);
 136     #        return -1;
 137     #    }
 138     #    Py_DECREF(o);
 139     # }
 140
 141     int PyDict_Merge(object a, object b, int override) except -1
 142     # Iterate over mapping object b adding key-value pairs to
 143     # dictionary a. b may be a dictionary, or any object supporting
 144     # PyMapping_Keys() and PyObject_GetItem(). If override is true,
 145     # existing pairs in a will be replaced if a matching key is found
 146     # in b, otherwise pairs will only be added if there is not a
 147     # matching key in a. Return 0 on success or -1 if an exception was
 148     # raised.
 149
 150     int PyDict_Update(object a, object b) except -1
 151     # This is the same as PyDict_Merge(a, b, 1) in C, or a.update(b)
 152     # in Python. Return 0 on success or -1 if an exception was raised.
 153
 154     int PyDict_MergeFromSeq2(object a, object seq2, int override) except -1
 155     # Update or merge into dictionary a, from the key-value pairs in
 156     # seq2. seq2 must be an iterable object producing iterable objects
 157     # of length 2, viewed as key-value pairs. In case of duplicate
 158     # keys, the last wins if override is true, else the first
 159     # wins. Return 0 on success or -1 if an exception was
 160     # raised. Equivalent Python (except for the return value):
 161     #
 162     #def PyDict_MergeFromSeq2(a, seq2, override):
 163     #    for key, value in seq2:
 164     #        if override or key not in a:
 165     #            a[key] = value