Struct Sequences

Struct sequences are subclasses of tuple. Similar to the API for creating tuples, HPy provides an API to create struct sequences. This is a builder API such that the struct sequence is guaranteed not to be written after it is created.

Note

There is no specific getter function for struct sequences. Just use one of HPy_GetItem(), HPy_GetItem_i(), or HPy_GetItem_s().

struct HPyStructSequence_Field

Describes a field of a struct sequence.

const char *name

Name (UTF-8 encoded) for the field or NULL to end the list of named fields. Set the name to HPyStructSequence_UnnamedField to leave it unnamed.

const char *doc

Docstring of the field (UTF-8 encoded); may be NULL.

struct HPyStructSequence_Desc

Contains the meta information of a struct sequence type to create. Struct sequences are subclasses of tuple. The index in the fields array of the descriptor determines which field of the struct sequence is described.

const char *name

Name of the struct sequence type (UTF-8 encoded; must not be NULL).

const char *doc

Docstring of the type (UTF-8 encoded); may be NULL.

HPyStructSequence_Field *fields

Pointer to NULL-terminated array with field names of the new type (must not be NULL).

extern const char *const HPyStructSequence_UnnamedField

A marker that can be used as struct sequence field name to indicate that a field should be anonymous (i.e. cannot be accessed by a name but only by numeric index).

HPy HPyStructSequence_NewType(HPyContext *ctx, HPyStructSequence_Desc *desc)

Create a new struct sequence type from a descriptor. Instances of the resulting type can be created with HPyStructSequence_New().

Parameters

• ctx – The execution context.

• desc – The descriptor of the struct sequence type to create (must not be NULL):

Returns

A handle to the new struct sequence type or HPy_NULL in case of errors.

HPy HPyStructSequence_New(HPyContext *ctx, HPy type, HPy_ssize_t nargs, HPy *args)

Creates a new instance of type initializing it with the given arguments.

Since struct sequences are immutable objects, they need to be initialized at instantiation. This function will create a fresh instance of the provided struct sequence type. The type must have been created with HPyStructSequence_NewType().

Parameters

• ctx – The execution context.

• type – A struct sequence type (must not be HPy_NULL). If the passed object is not a type, the behavior is undefined. If the given type is not appropriate, a TypeError will be raised.

• nargs – The number of arguments in args. If this argument is not exactly the number of fields of the struct sequence, a TypeError will be raised.

• args – An array of HPy handles to Python objects to be used for initializing the struct sequence. If nargs > 0 then this argument must not be NULL.

Returns

A new instance of type or HPy_NULL if an error occurred.