Using extension-helpersΒΆ
To use extension-helpers in your package, you will need to make sure your
package uses a pyproject.toml
file as described in PEP 518.
You can then add extension-helpers to the build-time dependencies in your
pyproject.toml
file:
[build-system]
requires = ["setuptools",
"wheel",
"extension-helpers==1.*"]
If you have Cython extensions, you will need to make sure cython
is included
in the above list too.
Note
It is highly recommended to pin the version of extension-helpers
to a major version, such as 1.*
, since extension-helpers uses
semantic versioning
and there will therefore likely be breaking changes when the major version is bumped.
If you do not specify any pinning, then old versions of your package that are already
on PyPI may no longer be installable on source without disabling the build isolation
and installing build dependencies manually.
The main functionality in extension-helpers is the
get_extensions()
function which can be
used to collect package extensions. Defining functions is then done in two ways:
For simple Cython extensions,
get_extensions()
will automatically generate extension modules with no further work.For other extensions, you can create
setup_package.py
files anywhere in your package, and these files can then include aget_extensions
function that returns a list ofsetuptools.Extension
objects.
In the second case, the idea is that for large packages, extensions can be defined
in the relevant sub-packages rather than having to all be listed in the main
setup.py
file.
To use this, you should modify your setup.py
file to use
get_extensions()
as follows:
from extension_helpers import get_extensions
...
setup(..., ext_modules=get_extensions())
Note that if you use this, extension-helpers will also we create a
packagename.compiler_version
submodule that contain information about the
compilers used.
It is also possible to enable extension-helpers in setup.cfg
instead of
setup.py
by adding the following configuration to the setup.cfg
file:
[extension-helpers]
use_extension_helpers = true
Moreover, one can also enable extension-helpers in pyproject.toml
by adding
the following configuration to the pyproject.toml
file:
[tool.extension-helpers]
use_extension_helpers = true
Note
For backwards compatibility, the setting of use_extension_helpers
in
setup.cfg
will override any setting of it in pyproject.toml
.