Overview

The pipcl package provides Python build backend operations (including PEP 517 support), for use by a setup.py script.

• Designed to help build complex Python extension packages.

• Can also be used to build simple pure-python packages.

• Works on Linux, Windows, MacOS and OpenBSD.

• Is a python module, not a framework, so does not impose any restrictions on usage.

• Can be used with any external build system by running commands, for example with subprocess.run() or enhanced wrapper pipcl.run().

The intention is to allow a setup.py script to use the full power of Python to do everything that is specific to the package, without having to worry about generic Python packaging issues such wheel formats etc (see https://packaging.python.org/en/latest/specifications/).

Basic usage

To build a pure-python package:

• Create a setup.py file that imports pipcl and uses it to specify and build a package:

  import pipcl
  
  def build():
      # Creates a module called `mymodule`.
      return [
              ('src/foo.py', 'mymodule/__init__.py'),
              ]
  def sdist():
      return pipcl.git_items('.')
  p = pipcl.Package(
          'mypackage',    # Name of package.
          '1.2.3',        # Package version.
          pure=True,      # Pure python package.
          summary = 'My package',
          description = 'README.md',
          fn_build = build,
          fn_sdist = sdist,
          )
  # PEP 517 support.
  build_wheel = p.build_wheel
  build_sdist = p.build_sdist

• Create a pyproject.toml that tells pip (and other build frontends) to use setup.py:

  [build-system]
      requires = ['pipcl']
      build-backend = 'setup' # Use setup.py
      backend-path = ['.']    # in top-level of the checkout.

To build a package containing a SWIG extension module, the build() function can be modified to use pipcl.build_extension():

import pipcl

def build():
    so_leaf = pipcl.build_extension(
            name = 'mymodule',      # Name of extension module.
            path_i = 'src/foo.i',   # SWIG input file.
            outdir = 'build',
            )
    # <so_leaf> will be '_mymodule.so' or similar.
    return [
            ('build/foo.py', 'mymodule/__init__.py'),
            (f'build/{so_leaf}', 'mymodule/'),
            ]
def sdist():
    return pipcl.git_items('.')
p = pipcl.Package(
        'mypackage',    # Name of package.
        '1.2.3',        # Package version.
        summary = 'My package',
        description = 'README.md',
        fn_build = build,
        fn_sdist = sdist,
        )
# PEP 517 support.
build_wheel = p.build_wheel
build_sdist = p.build_sdist

For more details, see doctest examples in file:src/pipcl.py.

Documentation

• Detailed documentation is in doc comments in Python code.

  • Convert into HTML with sphinx:

    pip install sphinx
    sphinx-build -M html docs docs/_build

    View at: file:docs/_build/html/index.html

• Convert README.rst to html with:

  pip install docutils
  docutils -gdst --halt=3 --pep-references README.rst README.rst.html

  View at: file:README.rst.html

API overview

Changelog

Version 10

• Fixed pipcl.git_info_py() in a non-git-checkout.

Version 9 (2026-06-18)

• Added added git_info_py().

• Added version_to_tuple().

Version 8 (2026-06-17)

• Improve support for PIPCL_CHANGE_VERSIONS:

  • Convert package name to lower case before matching with PIPCL_CHANGE_VERSIONS.

  • Provide pipcl.version_override() for use by a setup.py’s get_requires_for_build_wheel().

Version 7 (2026-06-05)

• Override matching package version numbers if PIPCL_CHANGE_VERSIONS is set.

Version 6 (2026-05-21)

• In build_extension(), added new arg compiler_extra_cpp.

Version 5 (2026-05-18)

• Automatically compile extension source with cc or c++ depending on suffix.

Version 4 (2026-05-08)

• Ignore encoding errors in pipcl.log(), e.g. on Windows if default is not utf8.

Version 3 (2026-05-02):

• Avoid unhelpful assert failures on Windows if paths differ only in upper/lower case.

Version 2 (2026-04-18):

• Fixed bug in zip file generation on python<3.13.

• Moved Python code into src/.

• Don’t attempt to be usable in raw checkout.

• Fixed doctest’s to work on Windows.

• Added python_version_tuple().

• Avoid spurious differences between wheels built on different systems:

  • Sort lines in generated RECORD file.

  • Use --global core.autocrlf input when running git clone.

Version 1 (2026-04-16):

• First release to pypi.org