`sipbuild` Module Reference

The sipbuild module implements the SIP build system. The module may be used by project-specific project.py scripts or extended by other build systems.

Note

Most of the classes described here have additional methods and attributes. Unless they are documented here they are not part of the public API and may be changed in any future release.

sipbuild.SIP_VERSION: int: The major.minor.patch version number encoded as an integer. For example v6.5.0 would be encoded as 0x060500.

sipbuild.SIP_VERSION_STR: str: The version number as it should be displayed to the user.

`AbstractBuilder`

class sipbuild.AbstractBuilder(project, **kwargs)

An abstract class that defines the API of a builder.

Parameters:

project (Project) – is the project.
**kwargs – are keyword arguments that define the initial values of any corresponding Option defined by the builder. An Option value set in this way cannot be overridden in the pyproject.toml file or by using a tool command line option.

abstract build(): Build the project but do not install it.

abstract build_sdist(sdist_directory)

Build an sdist for the project.

Parameters:: sdist_directory (str) – is the name of the directory in which the sdist is created.
Returns:: the name of the sdist file (excluding any path).

abstract build_wheel(wheel_directory)

Build a wheel for the project.

Parameters:: wheel_directory (str) – is the name of the directory in which the wheel is created.
Returns:: the name of the wheel file (excluding any path).

abstract install(): Build and install the project.

project: The Project object.

`AbstractProject`

class sipbuild.AbstractProject

An abstract class that defines the API of a project.

abstract build(): Build the project but do not install it.

abstract build_sdist(sdist_directory)

Build an sdist for the project.

Parameters:: sdist_directory (str) – is the name of the directory in which the sdist is created.
Returns:: the name of the sdist file (excluding any path).

abstract build_wheel(wheel_directory)

Build a wheel for the project.

Parameters:: wheel_directory (str) – is the name of the directory in which the wheel is created.
Returns:: the name of the wheel file (excluding any path).

static import_callable(name, base_type)

Import a callable from a script or module. The callable is identified either by its name (if specified) or its type.

Parameters:

name (str) – is a script (with a .py extension), a module or the name of an object in a module (specified as module:name).
base_type (type) – is the type of the callable and is ignored if the name of the callable is explicitly specified.

Returns:

the callable.

abstract install(): Build and install the project.

abstract setup(pyproject, tool, tool_description)

Setup the project from the pyproject.toml file.

Parameters:

pyproject (PyProject) – is the parsed pyproject.toml file.
tool (str) – is the name of the tool, either 'build', 'install', 'sdist' or 'wheel'.
tool_description (str) – is a short description of the tool.

`Bindings`

class sipbuild.Bindings(project, name, **kwargs)

The encapsulation of a set of bindings.

Parameters:

project (Project) – is the project.
name (str) – is the name of the bindings.
**kwargs – are keyword arguments that define the initial values of any corresponding Option defined by the bindings. An Option value set in this way cannot be overridden in the pyproject.toml file or by using a tool command line option.

apply_nonuser_defaults(tool)

Called by the bindings to set the default values of any non-user options (i.e. those that cannot be set from a tool command line). If it is re-implemented in a sub-class then the super-class version should be called.

Parameters:: tool (str) – is the name of the tool being used.

apply_user_defaults(tool)

Called by the bindings to set the default values of any user options (i.e. those that can be set from a tool command line). If it is re-implemented in a sub-class then the super-class version should be called.

Parameters:: tool (str) – is the name of the tool being used.

generate()

Called by the project to generate the source code of the bindings and return a BuildableBindings object containing the details needed by the builder to build the bindings.

Returns:: the BuildableBindings object.

get_options()

Called by the bindings to get the list of the bindings’s options. If it is re-implemented in a sub-class then the super-class version should be called.

Returns:: the list of Option objects.

is_buildable()

Called by the builder to determine if the bindings are buildable. This will not be called if the bindings have been explicitly enabled. The default implementation returns True.

Returns:: True if the bindings are buildable.

project: The Project object.

`Buildable`

class sipbuild.Buildable(project, name)

Encapsulate a generic buildable.

Parameters:

project (Project) – is the project.
name (str) – is the name of the buildable.

build_dir: The name of the buildable-specific build directory. This will be created automatically.

build_settings: A list of values that are passed to the builder. It is up to the builder to determine how these values are used.

installables: The list of Installable objects created by the builder to describe what was built.

name: The name of the buildable.

project: The Project object.

`BuildableBindings`

class sipbuild.BuildableBindings(bindings, fq_name, *, uses_limited_api=False)

A BuildableModule sub-class that encapsulates the Python extension module for a set of bindings.

Parameters:

bindings (Bindings) – is the bindings.
fq_name (str) – is the fully qualified name of the bindings module.
uses_limited_api (bool) – is True if the source code uses only the limited Python API.

bindings: The Bindings object.

`BuildableExecutable`

class sipbuild.BuildableExecutable(project, name, target, *, uses_limited_api=False)

A BuildableFromSources sub-class that encapsulates an executable.

Parameters:

project (Project) – is the project.
name (str) – is the name of the buildable.
target (str) – is the platform-independent name of the executable being built.
uses_limited_api (bool) – is True if the source code uses only the limited Python API.

`BuildableFromSources`

class sipbuild.BuildableFromSources(project, name, target, *, uses_limited_api=False)

A Buildable sub-class that encapsulates a target that is built from source code.

Parameters:

project (Project) – is the project.
name (str) – is the name of the buildable.
target (str) – is the name of the target being built.
uses_limited_api (bool) – is True if the source code uses only the limited Python API.

debug: True if a build with debugging symbols should be performed.

define_macros: The list of #define names and values in the form "NAME" or "NAME=VALUE".

headers: The list of .h header files.

include_dirs: The list of directories that will be searched, in additional to the standard system directores, for .h header files.

libraries: The list of libraries to link the source code with.

library_dirs: The list of directories that will be searched, in addition to the standard system directories, for any libraries.

make_names_relative(): Make all the file names relative to the build directory. This isn’t necessary but can make any build files easier to read by the user.

sources: The list of source files.

target: The name of the target being built.

uses_limited_api: True if the source code uses only the limited Python API.

`BuildableModule`

class sipbuild.BuildableModule(project, name, fq_name, *, uses_limited_api=False)

A BuildableFromSources sub-class that encapsulates a Python extension module.

Parameters:

project (Project) – is the project.
name (str) – is the name of the buildable.
fq_name (str) – is the fully qualified name of the module.
uses_limited_api (bool) – is True if the source code uses only the limited Python API.

exceptions: True if the module should be built with support for C++ exceptions.

fq_name: The fully qualified name of the module.

get_install_subdir()

Get the name of the sub-directory (relative to any future target installation directory) that the module should be installed in.

Returns:: the name of the sub-directory.

get_module_extension()

Get the platform-specific file name extension that a module should have.

Returns:: the extension.

static: True if the module should be built as a static library.

`Builder`

class sipbuild.Builder(project, **kwargs)

The default base implementation of a builder.

Parameters:

project (Project) – is the project
**kwargs – are keyword arguments that define the initial values of any corresponding Option defined by the builder. An Option value set in this way cannot be overridden in the pyproject.toml file or by using a tool command line option.

apply_nonuser_defaults(tool)

Called by the builder to set the default values of any non-user options (i.e. those that cannot be set from a tool command line). If it is re-implemented in a sub-class then the super-class version should be called.

Parameters:: tool (str) – is the name of the tool being used.

apply_user_defaults(tool)

Called by the builder to set the default values of any user options (i.e. those that can be set from a tool command line). If it is re-implemented in a sub-class then the super-class version should be called.

Parameters:: tool (str) – is the name of the tool being used.

abstract build_executable(buildable, *, fatal=True)

Build an executable from a buildable.

Parameters:

buildable (BuildableExecutable) – is the buildable.
fatal (bool) – is True if a UserException should be raised if the build failed.

Returns:

the relative path name of the built executable.

abstract build_project(target_dir, *, wheel_tag=None)

Build the project either to be installed for use or to create a wheel.

Parameters:

target_dir (str) – is the directory in which the project will be installed in.
wheel_tag (str) – is the wheel tag if a wheel is being created.

get_options()

Called by the builder to get the list of the builder’s options. If it is re-implemented in a sub-class then the super-class version should be called.

Returns:: the list of Option objects.

abstract install_project(target_dir, *, wheel_tag=None)

Install a built project either for use or to create a wheel.

Parameters:

target_dir (str) – is the directory in which the project will be installed in.
wheel_tag (str) – is the wheel tag if a wheel is being created.

`DistutilsBuilder`

class sipbuild.DistutilsBuilder(project, **kwargs)

A Builder that uses the Python distutils package to perform builds. This is the default builder for Python v3.9 and earlier.

Parameters:

project (Project) – is the project.
**kwargs – are keyword arguments that define the initial values of any corresponding Option defined by the builder. An Option value set in this way cannot be overridden in the pyproject.toml file or by using a tool command line option.

`handle_exception()`

sipbuild.handle_exception(e)

Handle an exception by displaying an appropriate error message to stdout. The process is then terminated with a non-zero exit code.

Parameters:: e (exception) – is the exception to be handled.

`Installable`

class sipbuild.Installable(name, *, target_subdir=None)

Encapsulate a list of files that will be installed in the same directory.

Parameters:

name (str) – is the name of the installable.
target_subdir (str) – is the relative path name of a sub-directory in which the installable’s files will be installed. If it is an absolute path name then it is used as the eventual full target directory.

files: The list of file names to be installed.

get_full_target_dir(target_dir)

Get the full path name of the directory where the installable’s file will be installed.

Parameters:: target_dir (str) – is the name of target directory.
Returns:: the full path name of the sub-directory within the target directory where the files will be installed.

install(target_dir, installed, *, do_install=True)

Install the installable’s files in a target directory.

Parameters:

target_dir (str) – is the name of the target directory.
installed (list[str]) – is a list of installed files which is updated with the newly installed files. The list is always updated even if the files are not actually installed.
do_install (bool) – is True if the files are actually to be installed.

name: The name of the installable.

target_subdir: The name of the target sub-directory.

`Option`

class sipbuild.Option(name, *, option_type=str, choices=None, default=None, help=None, metavar=None, inverted=False, tools=None)

Encapsulate a configurable option. Option values may be specified in code, in the pyproject.toml file or on the command line of SIP’s tools. The value of an option is accessed as an attribute of the object for which the option is defined.

Parameters:

name (str) – is the name of the option. Any ‘_’ in the name will be replaced by ‘-’ in the context of a pyproject.toml key or a command line option.
option_type (type) – is the type of the value, either bool, int, list or str (the default).
choices (list) – is a list of values that are the valid for the option.
default – is the default value.
help (str) – is the short help text. This must be specified if the option is to be used as a tool command line option.
metavar (str) – is the name of the option’s value when used in tool usage messages.
inverted (bool) – is True if, when used as a tool command line option, the name should be preceded by no-.
tools (list[str]) – is the list of tools that use the option as a command line option. If it isn’t specified then the list of build tools is used, i.e. ['build', 'install', 'wheel'].

`Project`

class sipbuild.Project(**kwargs)

The default implementation of a project. It has an associated builder which it uses to build a set of buildables. Building a buildable may create one or more installables.

Parameters:: **kwargs – are keyword arguments that define the initial values of any corresponding Option defined by the project. An Option value set in this way cannot be overridden in the pyproject.toml file or by using a tool command line option.

apply_nonuser_defaults(tool)

Called by the project to set the default values of any non-user options (i.e. those that cannot be set from a tool command line). If it is re-implemented in a sub-class then the super-class version should be called.

Parameters:: tool (str) – is the name of the tool being used.

apply_user_defaults(tool)

Called by the project to set the default values of any user options (i.e. those that can be set from a tool command line). If it is re-implemented in a sub-class then the super-class version should be called.

Parameters:: tool (str) – is the name of the tool being used.

bindings: The OrderedDict of Bindings objects keyed by the name of the bindings.

bindings_factories: The list of bindings factories which when called will return a Bindings object. There may or may not be a corresponding section in the pyproject.toml file.

builder: The AbstractBuilder implementation that the project uses to build buildables.

buildables: The list of Buildable objects that the project will use the builder to build.

get_distinfo_dir(target_dir)

Get the path name of the project’s .dist-info directory.

Parameters:: target_dir (str) – is the name of the directory that should contain the .dist-info directory.
Returns:: the path name of the .dist-info directory.

get_dunder_init()

Called by the project to get the contents of of the top-level __init__.py file to install. The default implementation returns an empty string.

Returns:: the contents of the __init__.py file.

get_metadata_overrides()

Called by the project to get a mapping of PEP 566 metadata names and values that will override any corresponding values defined in the pyproject.toml file. A typical use is to determine a project’s version dynamically.

Returns:: the mapping.

get_options()

Called by the project to get the list of the project’s options. If it is re-implemented in a sub-class then the super-class version should be called.

Returns:: the list of Option objects.

get_platform_tag()

Get the platform tag to use in a wheel name. This default implementation uses the platform name and applies PEP defined conventions depending on OS version and GLIBC version as appropriate.

Returns:: the platform tag.

get_requires_dists()

Get the list of any implicit requires-dist expressions that should be added to any explicit expressions specified in the [tool.sip.metadata] section of the pyproject.toml file.

Returns:: the list of requires-dist expressions.

get_sip_distinfo_command_line(sip_distinfo, inventory, generator=None, wheel_tag=None, generator_version=None)

Get a sequence of command line arguments to invoke sip-distinfo. The sip-distinfo --console-script, sip-distinfo --gui-script, sip-distinfo --metadata, sip-distinfo --prefix, sip-distinfo --project-root and sip-distinfo --requires-dist command line options are handled automatically. The arguments do not contain the name of the .dist-info directory to create.

Parameters:

sip_distinfo (str) – is the name of the sip-distinfo executable.
inventory (str) – is the value of the sip-distinfo --inventory command line option.
generator (str) – is the value of the sip-distinfo --generator command line option.
wheel_tag (str) – is the value of the sip-distinfo --wheel-tag command line option.
generator_version (str) – is the value of the sip-distinfo --generator-version command line option.

Returns:

the sequence of command line arguments.

installables: The list of Installable objects that the project will use the builder to install.

static open_for_writing(fname)

Open a text file for writing. This is a wrapper around open() that handles common user errors.

Parameters:: fname (str) – is the name of the file.
Returns:: the open file object.

progress(message)

A progress message is written to stdout if progress messages have not been disabled. If the message does not end with . then ... is appended.

Parameters:: message (str) – is the text of the message.

project_path(path, relative_to=None)

A file or directory path, possibly using POSIX separators and possibly relative to another directory is converted to an absolute path with native separators.

Parameters:

path (str) – is the path.
relative_to (str) – is the absolute path of a directory that the supplied path is relative to. The default is the project directory.

Returns:

the converted path.

read_command_pipe(args, *, and_stderr=False, fatal=True)

Create a generator that will return each line of a command’s stdout.

Parameters:

args (list[str]) – is the list of arguments that make up the command.
and_stderr (bool) – is True if the output from stderr should be included.
fatal (bool) – is True if a UserException should be raised if the command returns a non-zero exit code.

Returns:

the generator.

run_command(args, *, fatal=True)

Run a command and display any output from stdout or stderr if verbose progress messages are enabled.

Parameters:

args (list[str]) – is the list of arguments that make up the command.
fatal (bool) – is True if a UserException should be raised if the command returns a non-zero exit code.

root_dir: The name of the directory containing the pyproject.toml file.

update(tool)

Called by the project to carry out any required updates to the project. The current directory will be the build directory. The default implementation will call update_buildable_bindings() if the tool is a build tool.

Parameters:: tool (str) – is the name of the tool being used.

update_buildable_bindings(): Update bindings to ensure all bindings are buildable or have been explicitly enabled.

`PyProject`

class sipbuild.PyProject

An encapsulation of a parsed pyproject.toml file.

get_metadata()

Get an OrderedDict containing the contents of the [tool.sip.metadata] section. The name, version, metadata-version and requires-python keys will be defined.

Returns:: the meta-data.

get_section(section_name: str, *, required=False)

Get a section as either an OrderedDict, if the section is a table, or a list if the section is a list.

Parameters:

section_name (str) – is the name of the section.
required (bool) – is True if the section must be defined.

Returns:

the section.

`PyProjectOptionException`

exception sipbuild.PyProjectOptionException(name, text, *, section_name=None, detail=None)

The exception raised to describe an error with a particular option (i.e. key/value) in a particular section of a pyproject.toml file.

Parameters:

name (str) – is the name of the option.
text (str) – is the text describing the error.
section_name (str) – is the name of the section, defaulting to [tool.sip.project].
detail (str) – is additional detail about the error.

`PyProjectUndefinedOptionException`

exception sipbuild.PyProjectUndefinedOptionException(name, *, section_name=None)

The exception raised to when a particular option (i.e. key/value) in a particular section of a pyproject.toml file has not been defined.

Parameters:

name (str) – is the name of the option.
section_name (str) – is the name of the section, defaulting to [tool.sip.project].

`SetuptoolsBuilder`

class sipbuild.SetuptoolsBuilder(project, **kwargs)

A Builder that uses the Python setuptools package to perform builds. This is the default builder for Python v3.10 and later.

Parameters:

project (Project) – is the project.
**kwargs – are keyword arguments that define the initial values of any corresponding Option defined by the builder. An Option value set in this way cannot be overridden in the pyproject.toml file or by using a tool command line option.

`UserException`

exception sipbuild.UserException(text, *, detail=None)

The exception raised to describe an anticipated error to the user.

Parameters:

text (str) – is the text describing the error.
detail (str) – is additional detail about the error.

sipbuild Module Reference

`sipbuild` Module Reference