1#ifndef Py_CPYTHON_ABSTRACTOBJECT_H
2# error "this header file must not be included directly"
3#endif
4
5/* === Object Protocol ================================================== */
6
7#ifdef PY_SSIZE_T_CLEAN
8# define _PyObject_CallMethodId _PyObject_CallMethodId_SizeT
9#endif
10
11/* Convert keyword arguments from the FASTCALL (stack: C array, kwnames: tuple)
12 format to a Python dictionary ("kwargs" dict).
13
14 The type of kwnames keys is not checked. The final function getting
15 arguments is responsible to check if all keys are strings, for example using
16 PyArg_ParseTupleAndKeywords() or PyArg_ValidateKeywordArguments().
17
18 Duplicate keys are merged using the last value. If duplicate keys must raise
19 an exception, the caller is responsible to implement an explicit keys on
20 kwnames. */
21PyAPI_FUNC(PyObject *) _PyStack_AsDict(
22 PyObject *const *values,
23 PyObject *kwnames);
24
25/* Suggested size (number of positional arguments) for arrays of PyObject*
26 allocated on a C stack to avoid allocating memory on the heap memory. Such
27 array is used to pass positional arguments to call functions of the
28 PyObject_Vectorcall() family.
29
30 The size is chosen to not abuse the C stack and so limit the risk of stack
31 overflow. The size is also chosen to allow using the small stack for most
32 function calls of the Python standard library. On 64-bit CPU, it allocates
33 40 bytes on the stack. */
34#define _PY_FASTCALL_SMALL_STACK 5
35
36PyAPI_FUNC(PyObject *) _Py_CheckFunctionResult(
37 PyThreadState *tstate,
38 PyObject *callable,
39 PyObject *result,
40 const char *where);
41
42/* === Vectorcall protocol (PEP 590) ============================= */
43
44/* Call callable using tp_call. Arguments are like PyObject_Vectorcall()
45 or PyObject_FastCallDict() (both forms are supported),
46 except that nargs is plainly the number of arguments without flags. */
47PyAPI_FUNC(PyObject *) _PyObject_MakeTpCall(
48 PyThreadState *tstate,
49 PyObject *callable,
50 PyObject *const *args, Py_ssize_t nargs,
51 PyObject *keywords);
52
53#define PY_VECTORCALL_ARGUMENTS_OFFSET ((size_t)1 << (8 * sizeof(size_t) - 1))
54
55static inline Py_ssize_t
56PyVectorcall_NARGS(size_t n)
57{
58 return n & ~PY_VECTORCALL_ARGUMENTS_OFFSET;
59}
60
61static inline vectorcallfunc
62PyVectorcall_Function(PyObject *callable)
63{
64 PyTypeObject *tp;
65 Py_ssize_t offset;
66 vectorcallfunc ptr;
67
68 assert(callable != NULL);
69 tp = Py_TYPE(callable);
70 if (!PyType_HasFeature(type: tp, Py_TPFLAGS_HAVE_VECTORCALL)) {
71 return NULL;
72 }
73 assert(PyCallable_Check(callable));
74 offset = tp->tp_vectorcall_offset;
75 assert(offset > 0);
76 memcpy(dest: &ptr, src: (char *) callable + offset, n: sizeof(ptr));
77 return ptr;
78}
79
80/* Call the callable object 'callable' with the "vectorcall" calling
81 convention.
82
83 args is a C array for positional arguments.
84
85 nargsf is the number of positional arguments plus optionally the flag
86 PY_VECTORCALL_ARGUMENTS_OFFSET which means that the caller is allowed to
87 modify args[-1].
88
89 kwnames is a tuple of keyword names. The values of the keyword arguments
90 are stored in "args" after the positional arguments (note that the number
91 of keyword arguments does not change nargsf). kwnames can also be NULL if
92 there are no keyword arguments.
93
94 keywords must only contain strings and all keys must be unique.
95
96 Return the result on success. Raise an exception and return NULL on
97 error. */
98static inline PyObject *
99_PyObject_VectorcallTstate(PyThreadState *tstate, PyObject *callable,
100 PyObject *const *args, size_t nargsf,
101 PyObject *kwnames)
102{
103 vectorcallfunc func;
104 PyObject *res;
105
106 assert(kwnames == NULL || PyTuple_Check(kwnames));
107 assert(args != NULL || PyVectorcall_NARGS(nargsf) == 0);
108
109 func = PyVectorcall_Function(callable);
110 if (func == NULL) {
111 Py_ssize_t nargs = PyVectorcall_NARGS(n: nargsf);
112 return _PyObject_MakeTpCall(tstate, callable, args, nargs, keywords: kwnames);
113 }
114 res = func(callable, args, nargsf, kwnames);
115 return _Py_CheckFunctionResult(tstate, callable, result: res, NULL);
116}
117
118static inline PyObject *
119PyObject_Vectorcall(PyObject *callable, PyObject *const *args,
120 size_t nargsf, PyObject *kwnames)
121{
122 PyThreadState *tstate = PyThreadState_Get();
123 return _PyObject_VectorcallTstate(tstate, callable,
124 args, nargsf, kwnames);
125}
126
127// Backwards compatibility aliases for API that was provisional in Python 3.8
128#define _PyObject_Vectorcall PyObject_Vectorcall
129#define _PyObject_VectorcallMethod PyObject_VectorcallMethod
130#define _PyObject_FastCallDict PyObject_VectorcallDict
131#define _PyVectorcall_Function PyVectorcall_Function
132#define _PyObject_CallOneArg PyObject_CallOneArg
133#define _PyObject_CallMethodNoArgs PyObject_CallMethodNoArgs
134#define _PyObject_CallMethodOneArg PyObject_CallMethodOneArg
135
136/* Same as PyObject_Vectorcall except that keyword arguments are passed as
137 dict, which may be NULL if there are no keyword arguments. */
138PyAPI_FUNC(PyObject *) PyObject_VectorcallDict(
139 PyObject *callable,
140 PyObject *const *args,
141 size_t nargsf,
142 PyObject *kwargs);
143
144/* Call "callable" (which must support vectorcall) with positional arguments
145 "tuple" and keyword arguments "dict". "dict" may also be NULL */
146PyAPI_FUNC(PyObject *) PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict);
147
148static inline PyObject *
149_PyObject_FastCallTstate(PyThreadState *tstate, PyObject *func, PyObject *const *args, Py_ssize_t nargs)
150{
151 return _PyObject_VectorcallTstate(tstate, callable: func, args, nargsf: (size_t)nargs, NULL);
152}
153
154/* Same as PyObject_Vectorcall except without keyword arguments */
155static inline PyObject *
156_PyObject_FastCall(PyObject *func, PyObject *const *args, Py_ssize_t nargs)
157{
158 PyThreadState *tstate = PyThreadState_Get();
159 return _PyObject_FastCallTstate(tstate, func, args, nargs);
160}
161
162/* Call a callable without any arguments
163 Private static inline function variant of public function
164 PyObject_CallNoArgs(). */
165static inline PyObject *
166_PyObject_CallNoArg(PyObject *func) {
167 PyThreadState *tstate = PyThreadState_Get();
168 return _PyObject_VectorcallTstate(tstate, callable: func, NULL, nargsf: 0, NULL);
169}
170
171static inline PyObject *
172PyObject_CallOneArg(PyObject *func, PyObject *arg)
173{
174 PyObject *_args[2];
175 PyObject **args;
176 PyThreadState *tstate;
177 size_t nargsf;
178
179 assert(arg != NULL);
180 args = _args + 1; // For PY_VECTORCALL_ARGUMENTS_OFFSET
181 args[0] = arg;
182 tstate = PyThreadState_Get();
183 nargsf = 1 | PY_VECTORCALL_ARGUMENTS_OFFSET;
184 return _PyObject_VectorcallTstate(tstate, callable: func, args, nargsf, NULL);
185}
186
187PyAPI_FUNC(PyObject *) PyObject_VectorcallMethod(
188 PyObject *name, PyObject *const *args,
189 size_t nargsf, PyObject *kwnames);
190
191static inline PyObject *
192PyObject_CallMethodNoArgs(PyObject *self, PyObject *name)
193{
194 return PyObject_VectorcallMethod(name, args: &self,
195 nargsf: 1 | PY_VECTORCALL_ARGUMENTS_OFFSET, NULL);
196}
197
198static inline PyObject *
199PyObject_CallMethodOneArg(PyObject *self, PyObject *name, PyObject *arg)
200{
201 PyObject *args[2] = {self, arg};
202
203 assert(arg != NULL);
204 return PyObject_VectorcallMethod(name, args,
205 nargsf: 2 | PY_VECTORCALL_ARGUMENTS_OFFSET, NULL);
206}
207
208/* Like PyObject_CallMethod(), but expect a _Py_Identifier*
209 as the method name. */
210PyAPI_FUNC(PyObject *) _PyObject_CallMethodId(PyObject *obj,
211 _Py_Identifier *name,
212 const char *format, ...);
213
214PyAPI_FUNC(PyObject *) _PyObject_CallMethodId_SizeT(PyObject *obj,
215 _Py_Identifier *name,
216 const char *format,
217 ...);
218
219PyAPI_FUNC(PyObject *) _PyObject_CallMethodIdObjArgs(
220 PyObject *obj,
221 struct _Py_Identifier *name,
222 ...);
223
224static inline PyObject *
225_PyObject_VectorcallMethodId(
226 _Py_Identifier *name, PyObject *const *args,
227 size_t nargsf, PyObject *kwnames)
228{
229 PyObject *oname = _PyUnicode_FromId(name); /* borrowed */
230 if (!oname) {
231 return NULL;
232 }
233 return PyObject_VectorcallMethod(name: oname, args, nargsf, kwnames);
234}
235
236static inline PyObject *
237_PyObject_CallMethodIdNoArgs(PyObject *self, _Py_Identifier *name)
238{
239 return _PyObject_VectorcallMethodId(name, args: &self,
240 nargsf: 1 | PY_VECTORCALL_ARGUMENTS_OFFSET, NULL);
241}
242
243static inline PyObject *
244_PyObject_CallMethodIdOneArg(PyObject *self, _Py_Identifier *name, PyObject *arg)
245{
246 PyObject *args[2] = {self, arg};
247
248 assert(arg != NULL);
249 return _PyObject_VectorcallMethodId(name, args,
250 nargsf: 2 | PY_VECTORCALL_ARGUMENTS_OFFSET, NULL);
251}
252
253PyAPI_FUNC(int) _PyObject_HasLen(PyObject *o);
254
255/* Guess the size of object 'o' using len(o) or o.__length_hint__().
256 If neither of those return a non-negative value, then return the default
257 value. If one of the calls fails, this function returns -1. */
258PyAPI_FUNC(Py_ssize_t) PyObject_LengthHint(PyObject *o, Py_ssize_t);
259
260/* === New Buffer API ============================================ */
261
262/* Return 1 if the getbuffer function is available, otherwise return 0. */
263PyAPI_FUNC(int) PyObject_CheckBuffer(PyObject *obj);
264
265/* This is a C-API version of the getbuffer function call. It checks
266 to make sure object has the required function pointer and issues the
267 call.
268
269 Returns -1 and raises an error on failure and returns 0 on success. */
270PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
271 int flags);
272
273/* Get the memory area pointed to by the indices for the buffer given.
274 Note that view->ndim is the assumed size of indices. */
275PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);
276
277/* Return the implied itemsize of the data-format area from a
278 struct-style description. */
279PyAPI_FUNC(Py_ssize_t) PyBuffer_SizeFromFormat(const char *format);
280
281/* Implementation in memoryobject.c */
282PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,
283 Py_ssize_t len, char order);
284
285PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf,
286 Py_ssize_t len, char order);
287
288/* Copy len bytes of data from the contiguous chunk of memory
289 pointed to by buf into the buffer exported by obj. Return
290 0 on success and return -1 and raise a PyBuffer_Error on
291 error (i.e. the object does not have a buffer interface or
292 it is not working).
293
294 If fort is 'F', then if the object is multi-dimensional,
295 then the data will be copied into the array in
296 Fortran-style (first dimension varies the fastest). If
297 fort is 'C', then the data will be copied into the array
298 in C-style (last dimension varies the fastest). If fort
299 is 'A', then it does not matter and the copy will be made
300 in whatever way is more efficient. */
301PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
302
303/* Copy the data from the src buffer to the buffer of destination. */
304PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort);
305
306/*Fill the strides array with byte-strides of a contiguous
307 (Fortran-style if fort is 'F' or C-style otherwise)
308 array of the given shape with the given number of bytes
309 per element. */
310PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
311 Py_ssize_t *shape,
312 Py_ssize_t *strides,
313 int itemsize,
314 char fort);
315
316/* Fills in a buffer-info structure correctly for an exporter
317 that can only share a contiguous chunk of memory of
318 "unsigned bytes" of the given length.
319
320 Returns 0 on success and -1 (with raising an error) on error. */
321PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
322 Py_ssize_t len, int readonly,
323 int flags);
324
325/* Releases a Py_buffer obtained from getbuffer ParseTuple's "s*". */
326PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
327
328/* === Sequence protocol ================================================ */
329
330/* Assume tp_as_sequence and sq_item exist and that 'i' does not
331 need to be corrected for a negative index. */
332#define PySequence_ITEM(o, i)\
333 ( Py_TYPE(o)->tp_as_sequence->sq_item(o, i) )
334
335#define PY_ITERSEARCH_COUNT 1
336#define PY_ITERSEARCH_INDEX 2
337#define PY_ITERSEARCH_CONTAINS 3
338
339/* Iterate over seq.
340
341 Result depends on the operation:
342
343 PY_ITERSEARCH_COUNT: return # of times obj appears in seq; -1 if
344 error.
345 PY_ITERSEARCH_INDEX: return 0-based index of first occurrence of
346 obj in seq; set ValueError and return -1 if none found;
347 also return -1 on error.
348 PY_ITERSEARCH_CONTAINS: return 1 if obj in seq, else 0; -1 on
349 error. */
350PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
351 PyObject *obj, int operation);
352
353/* === Mapping protocol ================================================= */
354
355PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls);
356
357PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls);
358
359PyAPI_FUNC(char *const *) _PySequence_BytesToCharpArray(PyObject* self);
360
361PyAPI_FUNC(void) _Py_FreeCharPArray(char *const array[]);
362
363/* For internal use by buffer API functions */
364PyAPI_FUNC(void) _Py_add_one_to_index_F(int nd, Py_ssize_t *index,
365 const Py_ssize_t *shape);
366PyAPI_FUNC(void) _Py_add_one_to_index_C(int nd, Py_ssize_t *index,
367 const Py_ssize_t *shape);
368
369/* Convert Python int to Py_ssize_t. Do nothing if the argument is None. */
370PyAPI_FUNC(int) _Py_convert_optional_to_ssize_t(PyObject *, void *);
371
372/* Same as PyNumber_Index but can return an instance of a subclass of int. */
373PyAPI_FUNC(PyObject *) _PyNumber_Index(PyObject *o);
374

source code of include/python3.10/cpython/abstract.h