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.toml
file.
-
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
Option
defined by the bindings. AnOption
value set in this way cannot be overridden in thepyproject.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.
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
Installable
objects 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
BuildableModule
sub-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
BuildableFromSources
sub-class that encapsulates an executable.
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
-
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
-
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
-
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 aUserException
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.
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
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
orstr
(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 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
Option
defined by the project. AnOption
value set in this way cannot be overridden in thepyproject.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
ofBindings
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 thepyproject.toml
file.
-
builder
¶ The
AbstractBuilder
implementation that the project uses to build buildables.
-
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_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 thepyproject.toml
file.- Returns
the list of
requires-dist
expressions.
-
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-root
andsip-distinfo --requires-dist
command line options are handled automatically. The arguments do not contain the name of the :file:.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.
- 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.
-
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 fromstderr
should be included.fatal (bool) – is
True
if aUserException
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
orstderr
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 aUserException
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.
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. Thename
,version
,metadata-version
andrequires-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 alist
if 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.toml
file.
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.