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 v5.4.0 would be encoded as 0x050400.
AbstractBuilder¶
-
class
sipbuild.AbstractBuilder(project, \*\*kwargs)¶ An abstract class that defines the API of a builder.
- Parameters
-
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.
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.
-
abstract
install()¶ Build and install the project.
-
abstract
setup(pyproject, tool, tool_description)¶ Setup the project from the
pyproject.tomlfile.
-
abstract
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
Optiondefined by the bindings. AnOptionvalue set in this way cannot be overridden in thepyproject.tomlfile 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
BuildableBindingsobject containing the details needed by the builder to build the bindings.- Returns
the
BuildableBindingsobject.
-
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
Optionobjects.
-
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
Trueif the bindings are buildable.
Buildable¶
-
class
sipbuild.Buildable(project, name)¶ Encapsulate a generic 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
Installableobjects created by the builder to describe what was built.
-
name¶ The name of the buildable.
-
BuildableBindings¶
-
class
sipbuild.BuildableBindings(bindings, fq_name, \*, uses_limited_api=False)¶ A
BuildableModulesub-class that encapsulates the Python extension module for a set of bindings.- Parameters
BuildableExecutable¶
-
class
sipbuild.BuildableExecutable(project, name, target, \*, uses_limited_api=False)¶ A
BuildableFromSourcessub-class that encapsulates an executable.
BuildableFromSources¶
-
class
sipbuild.BuildableFromSources(project, name, target, \*, uses_limited_api=False)¶ A
Buildablesub-class that encapsulates a target that is built from source code.- Parameters
-
debug¶ Trueif a build with debugging symbols should be performed.
-
define_macros¶ The list of
#definenames and values in the form"NAME"or"NAME=VALUE".
-
headers¶ The list of
.hheader files.
-
include_dirs¶ The list of directories that will be searched, in additional to the standard system directores, for
.hheader 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¶ Trueif the source code uses only the limited Python API.
BuildableModule¶
-
class
sipbuild.BuildableModule(project, name, fq_name, \*, uses_limited_api=False)¶ A
BuildableFromSourcessub-class that encapsulates a Python extension module.- Parameters
-
exceptions¶ Trueif 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¶ Trueif the module should be built as a static library.
Builder¶
-
class
sipbuild.Builder(project, \*\*kwargs)¶ The default base implementation of a builder.
- Parameters
-
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
Trueif aUserExceptionshould 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.
DistutilsBuilder¶
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
-
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
Trueif 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.tomlfile 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.tomlkey or a command line option.option_type (type) – is the type of the value, either
bool,int,listorstr(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
Trueif, when used as a tool command line option, the name should be preceded byno-.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', 'pep517', '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
Optiondefined by the project. AnOptionvalue set in this way cannot be overridden in thepyproject.tomlfile 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
OrderedDictofBindingsobjects keyed by the name of the bindings.
-
bindings_factories¶ The list of bindings factories which when called will return a
Bindingsobject. There may or may not be a corresponding section in thepyproject.tomlfile.
-
builder¶ The
AbstractBuilderimplementation that the project uses to build buildables.
-
get_distinfo_dir(target_dir)¶ Get the path name of the project’s
.dist-infodirectory.- Parameters
target_dir (str) – is the name of the directory that should contain the
.dist-infodirectory.- Returns
the path name of the
.dist-infodirectory.
-
get_dunder_init()¶ Called by the project to get the contents of of the top-level
__init__.pyfile to install. The default implementation returns an empty string.- Returns
the contents of the
__init__.pyfile.
-
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
Optionobjects.
-
get_requires_dists()¶ Get the list of any implicit
requires-distexpressions that should be added to any explicit expressions specified in the[tool.sip.metadata]section of thepyproject.tomlfile.- Returns
the list of
requires-distexpressions.
-
get_sip_distinfo_command_line(sip_distinfo, inventory, generator=None, wheel_tag=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-rootandsip-distinfo --requires-distcommand line options are handled automatically. The arguments do not contain the name of the :file:.dist-infodirectory to create.- Parameters
sip_distinfo (str) – is the name of the sip-distinfo executable.
inventory (str) – is the value of the
sip-distinfo --inventorycommand line option.generator (str) – is the value of the
sip-distinfo --generatorcommand line option.wheel_tag (str) – is the value of the
sip-distinfo --wheel-tagcommand line option.
- Returns
the sequence of command line arguments.
-
installables¶ The list of
Installableobjects 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
stdoutif 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.
-
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
Trueif the output fromstderrshould be included.fatal (bool) – is
Trueif aUserExceptionshould 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
stdoutorstderrif verbose progress messages are enabled.- Parameters
args (list[str]) – is the list of arguments that make up the command.
fatal (bool) – is
Trueif aUserExceptionshould be raised if the command returns a non-zero exit code.
-
root_dir¶ The name of the directory containing the
pyproject.tomlfile.
-
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.
PyProject¶
-
class
sipbuild.PyProject¶ An encapsulation of a parsed
pyproject.tomlfile.-
get_metadata()¶ Get an
OrderedDictcontaining the contents of the[tool.sip.metadata]section. Thename,version,metadata-versionandrequires-pythonkeys 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 alistif the section is a list.
-
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.tomlfile.
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.tomlfile has not been defined.