1from .object cimport PyObject
2
3cdef 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    dict 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    dict 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, const 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, const 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, const 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    list 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    list 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    list 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
166