# `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.