Inline Helpers

Inline Helper functions are static inline functions (written in C). Those functions are usually small convenience functions that everyone could write but in order to avoid duplicated effort, they are defined by HPy.

One category of inline helpers are functions that convert the commonly used but not fixed width C types, such as int, or long long, to HPy API. The HPy API always uses well-defined fixed width types like int32 or unsigned int8.

HPY_INLINE_HELPERS_H

HPy HPyErr_SetFromErrno(HPyContext *ctx, HPy h_type)

Same as HPyErr_SetFromErrnoWithFilenameObjects() but passes HPy_NULL to the optional arguments.

Parameters

• ctx – The execution context.

• h_type – The exception type to raise.

Returns

always returns HPy_NULL

HPy HPyErr_SetFromErrnoWithFilenameObject(HPyContext *ctx, HPy h_type, HPy filename)

Same as HPyErr_SetFromErrnoWithFilenameObjects() but passes HPy_NULL to the last (optional) argument.

Parameters

• ctx – The execution context.

• h_type – The exception type to raise.

• filename – a filename; may be HPy_NULL

Returns

always returns HPy_NULL

HPy HPyTuple_Pack(HPyContext *ctx, HPy_ssize_t n, ...)

Create a tuple from arguments.

A convenience function that will allocate a temporary array of HPy elements and use HPyTuple_FromArray() to create a tuple.

Parameters

• ctx – The execution context.

• n – The number of elements to pack into a tuple.

• ... – Variable number of HPy arguments.

Returns

A new tuple with n elements or HPy_NULL in case of an error occurred.

int HPy_DelAttr(HPyContext *ctx, HPy obj, HPy name)

Delete an attribute.

This is the equivalent of the Python statement del o.attr_name.

Parameters

• ctx – The execution context.

• obj – The object with the attribute.

• name – The name (an unicode object) of the attribute.

Returns

0 on success; -1 in case of an error.

int HPy_DelAttr_s(HPyContext *ctx, HPy obj, const char *utf8_name)

Delete an attribute.

This is the equivalent of the Python statement del o.attr_name.

Parameters

• ctx – The execution context.

• obj – The object with the attribute.

• utf8_name – The name (an UTF-8 encoded C string) of the attribute.

Returns

0 on success; -1 in case of an error.

HPy HPyLong_FromLong(HPyContext *ctx, long l)

Create a Python long object from a C long value.

Parameters

• ctx – The execution context.

• l – A C long value.

Returns

A Python long object with the value of l or HPy_NULL on failure.

HPy HPyLong_FromUnsignedLong(HPyContext *ctx, unsigned long l)

Create a Python long object from a C unsigned long value.

Parameters

• ctx – The execution context.

• l – A C unsigned long value.

Returns

A Python long object with the value of l or HPy_NULL on failure.

HPy HPyLong_FromLongLong(HPyContext *ctx, long long l)

Create a Python long object from a C long long value.

Parameters

• ctx – The execution context.

• l – A C long long value.

Returns

A Python long object with the value of l or HPy_NULL on failure.

HPy HPyLong_FromUnsignedLongLong(HPyContext *ctx, unsigned long long l)

Create a Python long object from a C unsigned long long value.

Parameters

• ctx – The execution context.

• l – A C unsigned long long value.

Returns

A Python long object with the value of l or HPy_NULL on failure.

long HPyLong_AsLong(HPyContext *ctx, HPy h)

Return a C long representation of the given Python long object. If the object is not an instance of Python long, the object’s __index__ method (if present) will be used to convert it to a Python long object.

This function will raise an OverflowError if the value of the object is out of range for a C long.

This function will raise a TypeError if:

• The object is neither an instance of Python long nor it provides an __index__ method.

• If the __index__ method does not return an instance of Python long.

Parameters

• ctx – The execution context.

• h – Either an instance of Python long or an object that provides an __index__ method (which returns a Python long).

Returns

A C long value. Errors will be indicated with return value -1. In this case, use HPyErr_Occurred() to disambiguate.

unsigned long HPyLong_AsUnsignedLong(HPyContext *ctx, HPy h)

Return a C unsigned long representation of the given Python long object.

This function will raise a TypeError if the object is not an instance of Python long and it will raise an OverflowError if the object’s value is negative or out of range for a C unsigned long.

Parameters

• ctx – The execution context.

• h – The object to convert to C unsigned long (must be an instance of Python long).

Returns

A C unsigned long value. Errors will be indicated with return value (unsigned long)-1. In this case, use HPyErr_Occurred() to disambiguate.

unsigned long HPyLong_AsUnsignedLongMask(HPyContext *ctx, HPy h)

Return a C unsigned long representation of the given Python long object. If the object is not an instance of Python long, the object’s __index__ method (if present) will be used to convert it to a Python long object.

If the object’s value is out of range for an unsigned long, return the reduction of that value modulo ULONG_MAX + 1. Therefore, this function will NOT raise an OverflowError if the value of the object is out of range for a C unsigned long.

Parameters

• ctx – The execution context.

• h – Either an instance of Python long or an object that provides an __index__ method (which returns a Python long).

Returns

A C unsigned long value. Errors will be indicated with return value (unsigned long)-1. In this case, use HPyErr_Occurred() to disambiguate.

long long HPyLong_AsLongLong(HPyContext *ctx, HPy h)

Return a C long long representation of the given Python long object. If the object is not an instance of Python long, the object’s __index__ method (if present) will be used to convert it to a Python long object.

This function will raise an OverflowError if the value of the object is out of range for a C long long.

This function will raise a TypeError if:

• The object is neither an instance of Python long nor it provides an __index__ method.

• If the __index__ method does not return an instance of Python long.

Parameters

• ctx – The execution context.

• h – Either an instance of Python long or an object that provides an __index__ method (which returns a Python long).

Returns

A C long long value. Errors will be indicated with return value -1. In this case, use HPyErr_Occurred() to disambiguate.

unsigned long long HPyLong_AsUnsignedLongLong(HPyContext *ctx, HPy h)

Return a C unsigned long long representation of the given Python long object.

This function will raise a TypeError if the object is not an instance of Python long and it will raise an OverflowError if the object’s value is negative or out of range for a C unsigned long.

Parameters

• ctx – The execution context.

• h – The object to convert to C unsigned long long (must be an instance of Python long).

Returns

A C unsigned long long value. Errors will be indicated with return value (unsigned long long)-1. In this case, use HPyErr_Occurred() to disambiguate.

unsigned long long HPyLong_AsUnsignedLongLongMask(HPyContext *ctx, HPy h)

Return a C unsigned long long representation of the given Python long object. If the object is not an instance of Python long, the object’s __index__ method (if present) will be used to convert it to a Python long object.

If the object’s value is out of range for an unsigned long long, return the reduction of that value modulo ULLONG_MAX + 1. Therefore, this function will NOT raise an OverflowError if the value of the object is out of range for a C unsigned long long.

Parameters

• ctx – The execution context.

• h – Either an instance of Python long or an object that provides an __index__ method (which returns a Python long).

Returns

A C unsigned long value. Errors will be indicated with return value (unsigned long long)-1. In this case, use HPyErr_Occurred() to disambiguate.

HPy HPyBool_FromLong(HPyContext *ctx, long v)

Returns Python True or False depending on the truth value of v.

Parameters

• ctx – The execution context.

• v – A C long value.

Returns

Python True if v != 0; Python False otherwise.

HPy_ssize_t HPySlice_AdjustIndices(HPyContext *_HPy_UNUSED_ARG(ctx), HPy_ssize_t length, HPy_ssize_t *start, HPy_ssize_t *stop, HPy_ssize_t step, )

Adjust start/end slice indices assuming a sequence of the specified length.

Out of bounds indices are clipped in a manner consistent with the handling of normal slices. This function cannot fail and does not call interpreter routines.

Parameters

• ctx – The execution context.

• length – The length of the sequence that should be assumed for adjusting the indices.

• start – Pointer to the start value (must not be NULL).

• stop – Pointer to the stop value (must not be NULL).

• step – The step value of the slice (must not be 0)

Returns

Return the length of the slice. Always successful. Doesn’t call Python code.

HPy HPy_CallMethodTupleDict_s(HPyContext *ctx, const char *utf8_name, HPy receiver, HPy args, HPy kw)

Call a method of a Python object.

This is a convenience function for calling a method. It uses HPy_GetAttr_s() and HPy_CallTupleDict() to perform the method call.

Parameters

• ctx – The execution context.

• utf8_name – The name (UTF-8 encoded C string) of the method. Must not be NULL.

• receiver – A handle to the receiver of the call (i.e. the self). Must not be HPy_NULL.

• args – A handle to a tuple containing the positional arguments (must not be HPy_NULL but can, of course, be empty).

• kw – A handle to a Python dictionary containing the keyword arguments (may be HPy_NULL).

Returns

The result of the call on success, or HPy_NULL in case of an error.

HPy HPy_CallMethodTupleDict(HPyContext *ctx, HPy name, HPy receiver, HPy args, HPy kw)

Call a method of a Python object.

This is a convenience function for calling a method. It uses HPy_GetAttr() and HPy_CallTupleDict() to perform the method call.

Parameters

• ctx – The execution context.

• name – A handle to the name (a Unicode object) of the method. Must not be HPy_NULL.

• receiver – A handle to the receiver of the call (i.e. the self). Must not be HPy_NULL.

• args – A handle to a tuple containing the positional arguments (must not be HPy_NULL but can, of course, be empty).

• kw – A handle to a Python dictionary containing the keyword arguments (may be HPy_NULL).

Returns

The result of the call on success, or HPy_NULL in case of an error.