python3.12/cpython/abstract.h

0001 #ifndef Py_CPYTHON_ABSTRACTOBJECT_H
0002 #  error "this header file must not be included directly"
0003 #endif
0004
0005 /* === Object Protocol ================================================== */
0006
0007 #ifdef PY_SSIZE_T_CLEAN
0008 #  define _PyObject_CallMethodId _PyObject_CallMethodId_SizeT
0009 #endif
0010
0011 /* Convert keyword arguments from the FASTCALL (stack: C array, kwnames: tuple)
0012    format to a Python dictionary ("kwargs" dict).
0013
0014    The type of kwnames keys is not checked. The final function getting
0015    arguments is responsible to check if all keys are strings, for example using
0016    PyArg_ParseTupleAndKeywords() or PyArg_ValidateKeywordArguments().
0017
0018    Duplicate keys are merged using the last value. If duplicate keys must raise
0019    an exception, the caller is responsible to implement an explicit keys on
0020    kwnames. */
0021 PyAPI_FUNC(PyObject *) _PyStack_AsDict(
0022     PyObject *const *values,
0023     PyObject *kwnames);
0024
0025 /* Suggested size (number of positional arguments) for arrays of PyObject*
0026    allocated on a C stack to avoid allocating memory on the heap memory. Such
0027    array is used to pass positional arguments to call functions of the
0028    PyObject_Vectorcall() family.
0029
0030    The size is chosen to not abuse the C stack and so limit the risk of stack
0031    overflow. The size is also chosen to allow using the small stack for most
0032    function calls of the Python standard library. On 64-bit CPU, it allocates
0033    40 bytes on the stack. */
0034 #define _PY_FASTCALL_SMALL_STACK 5
0035
0036 PyAPI_FUNC(PyObject *) _Py_CheckFunctionResult(
0037     PyThreadState *tstate,
0038     PyObject *callable,
0039     PyObject *result,
0040     const char *where);
0041
0042 /* === Vectorcall protocol (PEP 590) ============================= */
0043
0044 /* Call callable using tp_call. Arguments are like PyObject_Vectorcall()
0045    or PyObject_FastCallDict() (both forms are supported),
0046    except that nargs is plainly the number of arguments without flags. */
0047 PyAPI_FUNC(PyObject *) _PyObject_MakeTpCall(
0048     PyThreadState *tstate,
0049     PyObject *callable,
0050     PyObject *const *args, Py_ssize_t nargs,
0051     PyObject *keywords);
0052
0053 // PyVectorcall_NARGS() is exported as a function for the stable ABI.
0054 // Here (when we are not using the stable ABI), the name is overridden to
0055 // call a static inline function for best performance.
0056 #define PyVectorcall_NARGS(n) _PyVectorcall_NARGS(n)
0057 static inline Py_ssize_t
0058 _PyVectorcall_NARGS(size_t n)
0059 {
0060     return n & ~PY_VECTORCALL_ARGUMENTS_OFFSET;
0061 }
0062
0063 PyAPI_FUNC(vectorcallfunc) PyVectorcall_Function(PyObject *callable);
0064
0065 // Backwards compatibility aliases for API that was provisional in Python 3.8
0066 #define _PyObject_Vectorcall PyObject_Vectorcall
0067 #define _PyObject_VectorcallMethod PyObject_VectorcallMethod
0068 #define _PyObject_FastCallDict PyObject_VectorcallDict
0069 #define _PyVectorcall_Function PyVectorcall_Function
0070 #define _PyObject_CallOneArg PyObject_CallOneArg
0071 #define _PyObject_CallMethodNoArgs PyObject_CallMethodNoArgs
0072 #define _PyObject_CallMethodOneArg PyObject_CallMethodOneArg
0073
0074 /* Same as PyObject_Vectorcall except that keyword arguments are passed as
0075    dict, which may be NULL if there are no keyword arguments. */
0076 PyAPI_FUNC(PyObject *) PyObject_VectorcallDict(
0077     PyObject *callable,
0078     PyObject *const *args,
0079     size_t nargsf,
0080     PyObject *kwargs);
0081
0082 // Same as PyObject_Vectorcall(), except without keyword arguments
0083 PyAPI_FUNC(PyObject *) _PyObject_FastCall(
0084     PyObject *func,
0085     PyObject *const *args,
0086     Py_ssize_t nargs);
0087
0088 PyAPI_FUNC(PyObject *) PyObject_CallOneArg(PyObject *func, PyObject *arg);
0089
0090 static inline PyObject *
0091 PyObject_CallMethodNoArgs(PyObject *self, PyObject *name)
0092 {
0093     size_t nargsf = 1 | PY_VECTORCALL_ARGUMENTS_OFFSET;
0094     return PyObject_VectorcallMethod(name, &self, nargsf, _Py_NULL);
0095 }
0096
0097 static inline PyObject *
0098 PyObject_CallMethodOneArg(PyObject *self, PyObject *name, PyObject *arg)
0099 {
0100     PyObject *args[2] = {self, arg};
0101     size_t nargsf = 2 | PY_VECTORCALL_ARGUMENTS_OFFSET;
0102     assert(arg != NULL);
0103     return PyObject_VectorcallMethod(name, args, nargsf, _Py_NULL);
0104 }
0105
0106 PyAPI_FUNC(PyObject *) _PyObject_CallMethod(PyObject *obj,
0107                                             PyObject *name,
0108                                             const char *format, ...);
0109
0110 /* Like PyObject_CallMethod(), but expect a _Py_Identifier*
0111    as the method name. */
0112 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId(PyObject *obj,
0113                                               _Py_Identifier *name,
0114                                               const char *format, ...);
0115
0116 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId_SizeT(PyObject *obj,
0117                                                     _Py_Identifier *name,
0118                                                     const char *format,
0119                                                     ...);
0120
0121 PyAPI_FUNC(PyObject *) _PyObject_CallMethodIdObjArgs(
0122     PyObject *obj,
0123     _Py_Identifier *name,
0124     ...);
0125
0126 static inline PyObject *
0127 _PyObject_VectorcallMethodId(
0128     _Py_Identifier *name, PyObject *const *args,
0129     size_t nargsf, PyObject *kwnames)
0130 {
0131     PyObject *oname = _PyUnicode_FromId(name); /* borrowed */
0132     if (!oname) {
0133         return _Py_NULL;
0134     }
0135     return PyObject_VectorcallMethod(oname, args, nargsf, kwnames);
0136 }
0137
0138 static inline PyObject *
0139 _PyObject_CallMethodIdNoArgs(PyObject *self, _Py_Identifier *name)
0140 {
0141     size_t nargsf = 1 | PY_VECTORCALL_ARGUMENTS_OFFSET;
0142     return _PyObject_VectorcallMethodId(name, &self, nargsf, _Py_NULL);
0143 }
0144
0145 static inline PyObject *
0146 _PyObject_CallMethodIdOneArg(PyObject *self, _Py_Identifier *name, PyObject *arg)
0147 {
0148     PyObject *args[2] = {self, arg};
0149     size_t nargsf = 2 | PY_VECTORCALL_ARGUMENTS_OFFSET;
0150     assert(arg != NULL);
0151     return _PyObject_VectorcallMethodId(name, args, nargsf, _Py_NULL);
0152 }
0153
0154 PyAPI_FUNC(int) _PyObject_HasLen(PyObject *o);
0155
0156 /* Guess the size of object 'o' using len(o) or o.__length_hint__().
0157    If neither of those return a non-negative value, then return the default
0158    value.  If one of the calls fails, this function returns -1. */
0159 PyAPI_FUNC(Py_ssize_t) PyObject_LengthHint(PyObject *o, Py_ssize_t);
0160
0161 /* === Sequence protocol ================================================ */
0162
0163 /* Assume tp_as_sequence and sq_item exist and that 'i' does not
0164    need to be corrected for a negative index. */
0165 #define PySequence_ITEM(o, i)\
0166     ( Py_TYPE(o)->tp_as_sequence->sq_item((o), (i)) )
0167
0168 #define PY_ITERSEARCH_COUNT    1
0169 #define PY_ITERSEARCH_INDEX    2
0170 #define PY_ITERSEARCH_CONTAINS 3
0171
0172 /* Iterate over seq.
0173
0174    Result depends on the operation:
0175
0176    PY_ITERSEARCH_COUNT:  return # of times obj appears in seq; -1 if
0177      error.
0178    PY_ITERSEARCH_INDEX:  return 0-based index of first occurrence of
0179      obj in seq; set ValueError and return -1 if none found;
0180      also return -1 on error.
0181    PY_ITERSEARCH_CONTAINS:  return 1 if obj in seq, else 0; -1 on
0182      error. */
0183 PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
0184                                               PyObject *obj, int operation);
0185
0186 /* === Mapping protocol ================================================= */
0187
0188 PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls);
0189
0190 PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls);
0191
0192 PyAPI_FUNC(char *const *) _PySequence_BytesToCharpArray(PyObject* self);
0193
0194 PyAPI_FUNC(void) _Py_FreeCharPArray(char *const array[]);
0195
0196 /* For internal use by buffer API functions */
0197 PyAPI_FUNC(void) _Py_add_one_to_index_F(int nd, Py_ssize_t *index,
0198                                         const Py_ssize_t *shape);
0199 PyAPI_FUNC(void) _Py_add_one_to_index_C(int nd, Py_ssize_t *index,
0200                                         const Py_ssize_t *shape);
0201
0202 /* Convert Python int to Py_ssize_t. Do nothing if the argument is None. */
0203 PyAPI_FUNC(int) _Py_convert_optional_to_ssize_t(PyObject *, void *);
0204
0205 /* Same as PyNumber_Index but can return an instance of a subclass of int. */
0206 PyAPI_FUNC(PyObject *) _PyNumber_Index(PyObject *o);