/* Abstract Object Interface (many thanks to Jim Fulton) */

#ifndef Py_ABSTRACTOBJECT_H

#define Py_ABSTRACTOBJECT_H

#ifdef __cplusplus

extern "C" {

#endif

Print an object 'o' on file 'fp'. Returns -1 on error. The flags argument

is used to enable certain printing options. The only option currently

supported is Py_PRINT_RAW. By default (flags=0), PyObject_Print() formats

the object by calling PyObject_Repr(). If flags equals to Py_PRINT_RAW, it

formats the object by calling PyObject_Str(). */

int PyObject_HasAttrString(PyObject *o, const char *attr_name);

Returns 1 if object 'o' has the attribute attr_name, and 0 otherwise.

Retrieve an attributed named attr_name form object o.

Returns the attribute value on success, or NULL on failure.

This is the equivalent of the Python expression: o.attr_name. */

Retrieve an attributed named 'attr_name' form object 'o'.

Returns the attribute value on success, or NULL on failure.

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v);

Set the value of the attribute named attr_name, for object 'o',

to the value 'v'. Raise an exception and return -1 on failure; return 0 on

success.

Set the value of the attribute named attr_name, for object 'o', to the value

'v'. an exception and return -1 on failure; return 0 on success.

Delete attribute named attr_name, for object o. Returns

-1 on failure.

int PyObject_DelAttr(PyObject *o, PyObject *attr_name);

Delete attribute named attr_name, for object o. Returns -1

on failure. This is the equivalent of the Python

statement: del o.attr_name. */

PyObject *PyObject_Repr(PyObject *o);

Compute the string representation of object 'o'. Returns the

string representation on success, NULL on failure.

Compute the string representation of object, o. Returns the

string representation on success, NULL on failure.

PyAPI_FUNC(int) PyCallable_Check(PyObject *o);

Determine if the object, o, is callable. Return 1 if the object is callable

and 0 otherwise.

This function always succeeds. */

#ifdef PY_SSIZE_T_CLEAN

# define PyObject_CallFunction _PyObject_CallFunction_SizeT

# define PyObject_CallMethod _PyObject_CallMethod_SizeT

#endif

#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000

/* Call a callable Python object without any arguments */

PyAPI_FUNC(PyObject *) PyObject_CallNoArgs(PyObject *func);

#endif

/* Call a callable Python object 'callable' with arguments given by the

tuple 'args' and keywords arguments given by the dictionary 'kwargs'.

This is the equivalent of the Python expression:

callable(*args, **kwargs). */

PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable,

PyObject *args, PyObject *kwargs);

PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable,

PyObject *args);

/* Call a callable Python object, callable, with a variable number of C

arguments. The C arguments are described using a mkvalue-style format

string.

PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable,

const char *format, ...);

/* Call the method named 'name' of object 'obj' with a variable number of

C arguments. The C arguments are described by a mkvalue format string.

Returns the result of the call on success, or NULL on failure.

This is the equivalent of the Python expression:

PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *obj,

const char *name,

const char *format, ...);

PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,

const char *format,

...);

PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *obj,

const char *name,

const char *format,

...);

/* Call a callable Python object 'callable' with a variable number of C

arguments. The C arguments are provided as PyObject* values, terminated

by a NULL.

PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,

...);

/* Call the method named 'name' of object 'obj' with a variable number of

C arguments. The C arguments are provided as PyObject* values, terminated

by NULL.

Returns the result of the call on success, or NULL on failure.

This is the equivalent of the Python expression: obj.name(*args). */

PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(

PyObject *obj,

PyObject *name,

...);

/* Given a vectorcall nargsf argument, return the actual number of arguments.

* (For use outside the limited API, this is re-defined as a static inline

* function in cpython/abstract.h)

*/

PyAPI_FUNC(Py_ssize_t) PyVectorcall_NARGS(size_t nargsf);

/* Call "callable" (which must support vectorcall) with positional arguments

"tuple" and keyword arguments "dict". "dict" may also be NULL */

PyAPI_FUNC(PyObject *) PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict);

#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000

#define PY_VECTORCALL_ARGUMENTS_OFFSET \

(_Py_STATIC_CAST(size_t, 1) << (8 * sizeof(size_t) - 1))

/* Perform a PEP 590-style vector call on 'callable' */

PyAPI_FUNC(PyObject *) PyObject_Vectorcall(

PyObject *callable,

PyObject *const *args,

size_t nargsf,

PyObject *kwnames);

/* Call the method 'name' on args[0] with arguments in args[1..nargsf-1]. */

PyAPI_FUNC(PyObject *) PyObject_VectorcallMethod(

PyObject *name, PyObject *const *args,

size_t nargsf, PyObject *kwnames);

#endif

Compute and return the hash, hash_value, of an object, o. On

failure, return -1.

This is the equivalent of the Python expression: hash(o). */

int PyObject_IsTrue(PyObject *o);

Returns 1 if the object, o, is considered to be true, 0 if o is

considered to be false and -1 on failure.

This is equivalent to the Python expression: not not o. */

int PyObject_Not(PyObject *o);

Returns 0 if the object, o, is considered to be true, 1 if o is

considered to be false and -1 on failure.

/* Get the type of an object.

On success, returns a type object corresponding to the object type of object

'o'. On failure, returns NULL.

This is equivalent to the Python expression: type(o) */

/* Return the size of object 'o'. If the object 'o' provides both sequence and

mapping protocols, the sequence size is returned.

On error, -1 is returned.

This is the equivalent to the Python expression: len(o) */

#define PyObject_Length PyObject_Size

/* Return element of 'o' corresponding to the object 'key'. Return NULL

on failure.

/* Map the object 'key' to the value 'v' into 'o'.

Raise an exception and return -1 on failure; return 0 on success.

This is the equivalent of the Python statement: o[key]=v. */

/* Delete the mapping for the object 'key' from the object 'o'.

Returns -1 on failure.

/* === Old Buffer API ============================================ */

/* FIXME: usage of these should all be replaced in Python itself

but for backwards compatibility we will implement them.

Their usage without a corresponding "unlock" mechanism

may create issues (but they would already be there). */

/* Takes an arbitrary object which must support the (character, single segment)

buffer interface and returns a pointer to a read-only memory location

Return 0 on success. buffer and buffer_len are only set in case no error

occurs. Otherwise, -1 is returned and an exception set. */

Py_DEPRECATED(3.0)

PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,

const char **buffer,

Py_ssize_t *buffer_len);

/* Checks whether an arbitrary object supports the (character, single segment)

buffer interface.

Returns 1 on success, 0 on failure. */

Py_DEPRECATED(3.0) PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);

/* Same as PyObject_AsCharBuffer() except that this API expects (readable,

single segment) buffer interface and returns a pointer to a read-only memory

location which can contain arbitrary data.

0 is returned on success. buffer and buffer_len are only set in case no

error occurs. Otherwise, -1 is returned and an exception set. */

Py_DEPRECATED(3.0)

PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,

const void **buffer,

Py_ssize_t *buffer_len);

/* Takes an arbitrary object which must support the (writable, single segment)

buffer interface and returns a pointer to a writable memory location in

buffer of size 'buffer_len'.

Return 0 on success. buffer and buffer_len are only set in case no error

occurs. Otherwise, -1 is returned and an exception set. */

Py_DEPRECATED(3.0)

PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,

void **buffer,

Py_ssize_t *buffer_len);

/* Takes an arbitrary object and returns the result of calling

obj.__format__(format_spec). */

PyAPI_FUNC(PyObject *) PyObject_Format(PyObject *obj,

/* ==== Iterators ================================================ */

/* Takes an object and returns an iterator for it.

This is typically a new iterator but if the argument is an iterator, this

returns itself. */

/* Takes an AsyncIterable object and returns an AsyncIterator for it.

This is typically a new iterator but if the argument is an AsyncIterator,

this returns itself. */

This function always succeeds. */

/* Returns non-zero if the object 'obj' provides AsyncIterator protocols, and 0 otherwise.

This function always succeeds. */

/* Takes an iterator object and calls its tp_iternext slot,

returning the next value.

If the iterator is exhausted, this returns NULL without setting an

exception.

NULL with an exception means an error occurred. */

/* Takes generator, coroutine or iterator object and sends the value into it.

Returns:

- PYGEN_RETURN (0) if generator has returned.

'result' parameter is filled with return value

- PYGEN_ERROR (-1) if exception was raised.

'result' parameter is NULL

- PYGEN_NEXT (1) if generator has yielded.

'result' parameter is filled with yielded value. */

PyAPI_FUNC(PySendResult) PyIter_Send(PyObject *, PyObject *, PyObject **);