sipbuild.plugin Module Reference

The sipbuild.plugin module implements the SIP plugin API. This API allows bindings authors to add functionality to SIP (for example new directives and annotations) and to generate additional code to meet the needs of a particular use case.

The API is not intended to be comprehensive but it will be added to as required to meet the needs of new use cases. If you, as a bindings author, need additions to be made then raise an issue specifying the changes you would like to see.

The API consists of the Plugin class whose methods you can reimplement to add new behaviours. There are additional classes that model various SIP objects such as Class and MappedType.

The simplest way to add a plugin to a project is to create a project.py file containing a sub-class of Project and the implementation of the plugin (which will be a sub-class of Plugin. In the __init__ method of the project sub-class call install_plugin() passing an instance of the plugin.

If you want other bindings authors to be able to extend your own bindings then it gets a little more complicated as they need to sub-class from your Project sub-class. To do this create a separate Python package (uploaded to PyPI) that contains your Project sub-class and your plugin implementation. In your pyproject.toml file add the package as a dependency using the requires value in the [build-system] section and specify the full import path of the Project sub-class as the value of project-factory in the [tool.sip] section. There is no need for a project.py file.

class sipbuild.plugin.AnnotationContext

An enum that specifies the context of annotations passed to sip_handle_annotations().

ARGUMENT

The annotations relate to an argument.

CLASS

The annotations relate to a class.

CONSTRUCTOR

The annotations relate to a constructor.

DESTRUCTOR

The annotations relate to a destructor.

ENUM

The annotations relate to an enum.

ENUM_MEMBER

The annotations relate to a member of an enum.

EXCEPTION

The annotations relate to an exception.

FUNCTION

The annotations relate to a function or overload.

MAPPED_TYPE

The annotations relate to a mapped type.

TYPEDEF

The annotations relate to a typedef.

VARIABLE

The annotations relate to a variable.

sipbuild.plugin.AnnotationNoValue

A value that is return by parse_annotation() to indicate that an annotation was specified but without a value.

class sipbuild.plugin.AnnotationType

An enum that specifies the data type of an annotation passed to parse_annotation().

BOOLEAN

The value is True if the annotation is specified and False if not.

DOTTED_NAME

The value is a str compatible with an identifier preceded by a Python scope.

DOTTED_NAME_OPTIONAL

The value is a str compatible with an identifier preceded by a Python scope or AnnotationNoValue if the value part was omitted.

INTEGER

The value is a signed int.

INTEGER_OPTIONAL

The value is a signed int or AnnotationNoValue if the value part was omitted.

NAME

The value is a str compatible with a C/C++ identifier.

NAME_OPTIONAL

The value is a str compatible with a C/C++ identifier or AnnotationNoValue if the value part was omitted.

STRING

The value is a str extracted from a quoted string with embedded selectors or None if no selector evaluated to True.

STRING_LIST

The value is a list[str] extracted from a quoted string.

STRING_OPTIONAL

The value is a str extracted from a quoted string with embedded selectors, None if no selector evaluated to True or AnnotationNoValue if the value part was omitted.

class sipbuild.plugin.Argument

This represents an argument. Instances are created by the API and should not be created by a plugin.

get_declaration(*, nr_of_scopes_stripped=None)

Get the declaration of the argument as a string.

Parameters:

nr_of_scopes_stripped (int) – is the number of scopes that will be be removed from the arguments type. By default only the global scope (ie. the leading ::) is stripped.

Returns:

the declaration.

get_plugin_attribute(plugin, name, default=None)

Get the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • default – is the optional default value of the attribute.

Returns:

the value of the attribute.

property is_const

True if the argument is const.

property is_optional

True if the argument is optional (i.e. has a default value). It cannot be set.

property is_reference

True if the argument is a C++ reference.

property nr_of_dereferences

The number of pointer dereferences.

set_plugin_attribute(plugin, name, value)

Set the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • value – is the value to set.

class sipbuild.plugin.Class

This represents a class. Instances are created by the API and should not be created by a plugin.

property cpp_name

The fully scoped C++ name of the class. It cannot be set.

property cpp_name_as_word

The fully scoped C++ name of the class transformed so that it can be used as a C++ identifier. It cannot be set.

property dtor_is_public

True if the class has a public destructor. It cannot be set.

property functions

A sequence of Function instances of the class’s functions. Note that this is based on the Python name and not the C++ name. It cannot be set.

get_plugin_attribute(plugin, name, default=None)

Get the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • default – is the optional default value of the attribute.

Returns:

the value of the attribute.

property needs_derived_class

True if the class needs a derived class to be generated.

property py_name_as_str

The Python name of the class as a string literal (i.e. enclosed in double quotes). It cannot be set.

set_plugin_attribute(plugin, name, value)

Set the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • value – is the value to set.

property unscoped_cpp_name

The unscoped C++ name of the class. It cannot be set.

class sipbuild.plugin.Constructor

This represents a constructor. Instances are created by the API and should not be created by a plugin.

get_plugin_attribute(plugin, name, default=None)

Get the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • default – is the optional default value of the attribute.

Returns:

the value of the attribute.

set_plugin_attribute(plugin, name, value)

Set the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • value – is the value to set.

class sipbuild.plugin.Enum

This represents an enum. Instances are created by the API and should not be created by a plugin.

property cpp_name

The fully scoped C/C++ name of the enum. It will be None if the enum is anonymous. It cannot be set.

get_plugin_attribute(plugin, name, default=None)

Get the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • default – is the optional default value of the attribute.

Returns:

the value of the attribute.

property is_public

True if the enum is public. It cannot be set.

property scope

The enclosing scope of the enum or None if it is global. It cannot be set.

set_plugin_attribute(plugin, name, value)

Set the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • value – is the value to set.

class sipbuild.plugin.EnumMember

This represents a member of an enum. Instances are created by the API and should not be created by a plugin.

get_plugin_attribute(plugin, name, default=None)

Get the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • default – is the optional default value of the attribute.

Returns:

the value of the attribute.

set_plugin_attribute(plugin, name, value)

Set the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • value – is the value to set.

class sipbuild.plugin.Function

This represents a function (i.e a collection of overloads which have the same Python name). Instances are created by the API and should not be created by a plugin.

get_plugin_attribute(plugin, name, default=None)

Get the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • default – is the optional default value of the attribute.

Returns:

the value of the attribute.

property impl_reference

An ABI-specific reference to the implementation of a function. It cannot be set.

property overloads

A sequence of Overload instances of the function’s overloads. Note that this is based on the Python name and not the C++ name. It cannot be set.

property py_name_as_str

The Python name of the class as a string literal (i.e. enclosed in double quotes). It cannot be set.

set_plugin_attribute(plugin, name, value)

Set the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • value – is the value to set.

class sipbuild.plugin.MappedType

This represents a mapped type. Instances are created by the API and should not be created by a plugin.

property cpp_name

The C++ name of the mapped type. It cannot be set.

property cpp_name_as_word

The C++ name of the mapped type transformed so that it can be used as a C++ identifier. It cannot be set.

get_plugin_attribute(plugin, name, default=None)

Get the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • default – is the optional default value of the attribute.

Returns:

the value of the attribute.

set_plugin_attribute(plugin, name, value)

Set the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • value – is the value to set.

class sipbuild.plugin.Overload

This represents a function overload. Instances are created by the API and should not be created by a plugin.

property cpp_signature

The overload’s C/C++ signature. It cannot be set.

property docstring

The overload’s docstring. It is None if the %Docstring directive wasn’t specified. It cannot be set.

generate_signature_parser(writer, *, overload_nr, simple_call=False)

Generate the code to parse the overload’s signature.

Parameters:

  • writer – is an object with a write() method.

  • overload_nr (int) – is the index of the overload in the sequence of the function’s callable overloads.

  • simple_call (bool) – is True in order to generate a simple call, i.e. one that doesn’t allow self being passed as the first argument and doesn’t support keyword arguments.

generate_call_arguments(writer)

Generate the arguments to a call that were produced from a parsed signature.

Parameters:

writer – is an object with a write() method.

generate_signature_parser_tidy_up(writer)

Generate the code to tidy up after a signature parser.

Parameters:

writer – is an object with a write() method.

get_plugin_attribute(plugin, name, default=None)

Get the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • default – is the optional default value of the attribute.

Returns:

the value of the attribute.

property is_callable

True if the overload is callable. Overloads are callable by default.

property is_public

True if the overload is public. It cannot be set.

property is_static

True if the overload is static. It cannot be set.

property py_name

The Python name of the overload. It cannot be set.

set_plugin_attribute(plugin, name, value)

Set the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • value – is the value to set.

property type_hint

The overload’s type hint. It cannot be set.

property unscoped_cpp_name

The unscoped C/C++ name of the overload. It cannot be set.

class sipbuild.plugin.Plugin

This is the base class for plugins. Its methods are called at various points in the bindings generation process and sub-classes can reimplement these methods to add new features.

If multiple plugins are installed then each will be called. If a plugin method returns a value then SIP will check that those values do not conflict.

The prefix sip_ in the names of method and attribute names is reserved.

sip_key

A string that uniquely identifies the plugin. A value based on the PyPI name is recommended.

sip_class_generate_derived_class_decl(writer, spec, klass)

Generate code to be included in the declaration of a class’s derived class. By default this will be placed in a private section.

Parameters:

  • writer – is an object with a write() method.

  • spec (Specification) – is the specification.

  • klass (Class) – is the class.

sip_class_generate_derived_class_impl(writer, spec, klass)

Generate code to be included in the implementation of a class’s derived class.

Parameters:

  • writer – is an object with a write() method.

  • spec (Specification) – is the specification.

  • klass (Class) – is the class.

sip_class_generate_impl(writer, spec, klass)

Generate code that implements support for a class, usually in the form of a type-specific data structure.

Parameters:

  • writer – is an object with a write() method.

  • spec (Specification) – is the specification.

  • klass (Class) – is the class.

Returns:

the name of the plugin-specific data structure or None.

sip_class_generate_release_code(writer, spec, klass)

Generate the body of a class’s release function. True is returned if the plugin generated something to replace the default implementation.

Parameters:

  • writer – is an object with a write() method.

  • spec (Specification) – is the specification.

  • klass (Class) – is the class.

Returns:

True if something was generated.

sip_class_get_access_specifiers(spec)

Return a sequence of non-standard strings that can appear in a plugin-specific access specifier.

Parameters:

spec (Specification) – is the specification.

Returns:

the sequence of access specifiers.

sip_class_parsed(spec, scope, klass)

This is called when a class has been parsed.

Parameters:

  • spec (Specification) – is the specification.

  • scope (Class|None) – is the enclosing scope of the class.

  • klass (Class) – is the class.

sip_class_superclass_set(spec, klass, superclass)

This called when a class’s superclass has been set.

Parameters:

  • spec (Specification) – is the specification.

  • klass (Class) – is the class.

  • superclass (Class) – is the class’s superclass.

sip_handle_access_specifier(spec, klass, primary, secondary)

Parse a primary and optional secondary class access specifier. If it was parsed return the C++ standard access specifier (ie. public, protected or private) to use, otherwise return None.

Parameters:

  • spec (Specification) – is the specification.

  • klass (Class) – is the class.

  • primary (str) – is the primary access specifier.

  • secondary (str|None) – is the optional secondary access specifier.

Returns:

the standard access specifier or None.

sip_handle_annotations(spec, item, annotations, annotation_context)

Handle any context-specific annotations. All supported annotations must be handled.

Parameters:

  • spec (Specification) – is the specification.

  • item – is the item that is annotated.

  • annotations – is an opaque annotations object that can be passed to parse_annotation().

  • annotation_context (AnnotationContext) – is the context of the annotations (implying the type of item).

sip_handle_class_function_prefix(spec, overload, prefix)

This is called to handle a class function prefix.

Parameters:

  • spec (Specification) – is the specification.

  • overload (Overload) – is the overload.

  • prefix (str) – is the prefix.

Returns:

True if the prefix was handled.

sip_handle_directive(spec, name, args)

This is called to handle a directive.

Parameters:

  • spec (Specification) – is the specification.

  • name (str) – is the name of the directive.

  • args (list[str]) – is a list of the directive’s arguments.

Returns:

True if the directive was handled.

sip_instantiated_class_resolved(spec, klass, template_class, template_arguments)

This is called when a class created by instantiating a template with arguments has been resolved.

Parameters:

  • spec (Specification) – is the specification.

  • klass (Class) – is the class.

  • template_class (Class) – is the prototype template class.

  • template_arguments (dict[str, str]) – is the dictionary of name/value pairs that are the template arguments.

sip_instantiated_mapped_type_resolved(spec, mapped_type, template_mapped_type, template_arguments)

This is called when a mapped type created by instantiating a template with arguments has been resolved.

Parameters:

  • spec (Specification) – is the specification.

  • mapped_type (MappedType) – is the mapped type.

  • template_mapped_type (MappedType) – is the prototype template mapped type.

  • template_arguments (dict[str, str]) – is the dictionary of name/value pairs that are the template arguments.

sip_mapped_type_generate_impl(writer, spec, mapped_type)

Generate code that implements support for a mapped type. The name of an optional plugin-specific data structure can be returned. This is used by ABIs v12 and v13 but ignored by v14.

Parameters:

  • writer – is an object with a write() method.

  • spec (Specification) – is the specification.

  • mapped_type (MappedType) – is the mapped type.

Returns:

the name of a plugin-specific data structure or None.

sip_module_generate_code(writer, spec)

Generate code to declare and/or initialise any module-specific data.

Parameters:

  • writer – is an object with a write() method.

  • spec (Specification) – is the specification.

sip_module_generate_header_code(writer, spec)

Generate code to be included in the internal module API .h file.

Parameters:

  • writer – is an object with a write() method.

  • spec (Specification) – is the specification.

sip_module_generate_initialisation_code(writer, spec)

Generate code included in the module initialisation code.

Parameters:

  • writer – is an object with a write() method.

  • spec (Specification) – is the specification.

sip_overload_resolved(spec, scope, overload)

This is called when an overload has been resolved.

Parameters:
sip_overload_get_prefixes(spec)

Return a sequence of non-standard strings that can appear in a plugin-specific overload prefix.

Parameters:

spec (Specification) – is the specification.

Returns:

the sequence of prefixes.

sip_overload_get_typing(spec, overload)

Return a 2-tuple of the typing entry for an overload to be included in the module’s .pyi file and a flag that is True if other overloads of the same function should be ignored. If None is returned then a default is used.

Parameters:
Returns:

the 2-tuple of typing entry and flag.

sip_overload_parsed(spec, scope, overload)

This is called when an overload has been parsed.

Parameters:
sip_specification_resolved(spec)

This is called when a specification has been resolved.

Parameters:

spec (Specification) – is the specification.

class sipbuild.plugin.Signature

This represents an overload’s signature. Instances are created by the API and should not be created by a plugin.

property arguments

A sequence of Argument instances of the signature’s arguments. It cannot be set.

get_plugin_attribute(plugin, name, default=None)

Get the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • default – is the optional default value of the attribute.

Returns:

the value of the attribute.

set_plugin_attribute(plugin, name, value)

Set the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • value – is the value to set.

class sipbuild.plugin.Specification

This represents a complete specification of a module and its contents. Instances are created by the API and should not be created by a plugin.

property abi_major_version

The major version number of the target ABI. It cannot be set.

property abi_minor_version

The minor version number of the target ABI. It cannot be set.

add_declaration(klass)

The header file that declares a class is added to those #included by the generated module code.

Parameters:

klass (Class) – is the class.

property all_enums

The sequence of all enums defined in the module. It cannot be set.

property all_mapped_types

The sequence of all mapped types defined in the module. It cannot be set.

static apply_template_arguments(proto_string, template_arguments)

Applies the arguments of a template to a prototype string and return the expanded result.

Parameters:

  • proto_string (str) – is the prototype string.

  • template_arguments (dict[str, str]) – is the dictionary of name/value pairs that are the template arguments.

Returns:

the expanded result.

property c_bindings

True if C (rather than C++) bindings are being generated. It cannot be set.

property docstrings

True if docstrings should be generated. It cannot be set.

error(message, *, annotation=None, overload=None)

Report an error, possibly related to a particular context.

Parameters:

  • message (str) – is the text of the error message.

  • annotation (str) – is the name of an annotation to be passed if the error occurred in an implementation of sip_handle_annotations().

  • overload (Overload) – is the overload to be passed if the error occurred in an implementation of sip_overload_resolved().

get_plugin_attribute(plugin, name, default=None)

Get the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • default – is the optional default value of the attribute.

Returns:

the value of the attribute.

get_type_specification(wrapped_object)

Get the name of the type specification of a wrapped object.

Parameters:

wrapped_object (Class|Enum|MappedType) – is the wrapped object.

Returns:

the type specification.

static is_class(wrapped_object)

Check if a wrapped object is a class.

Parameters:

wrapped_object – is the wrapped object.

Returns:

True if the wrapped object is a class.

static is_namespace(wrapped_object)

Check if a wrapped object is a namespace.

Parameters:

wrapped_object – is the wrapped object.

Returns:

True if the wrapped object is a namespace.

property module_name

The name of the module. It cannot be set.

static parse_annotation(annotations, name, annotation_type)

Parse an annotation of a particular type and return its value.

Parameters:

  • annotations – is an opaque annotations object passed to sip_handle_annotations().

  • name (str) – is the name of the annotation.

  • annotation_type (AnnotationType) – is the expected type of the annotation’s value.

Returns:

the value of the annotation or None if it wasn’t specified.

set_plugin_attribute(plugin, name, value)

Set the value of a plugin-specific attribute.

Parameters:

  • plugin (Plugin) – is the plugin.

  • name (str) – is the name of the attribute.

  • value – is the value to set.