Skip to content

Commit

Permalink
clarify that hatchling plugins can build extension modules
Browse files Browse the repository at this point in the history
  • Loading branch information
ucodery committed Apr 9, 2024
1 parent e9f1018 commit 0c367f3
Showing 1 changed file with 8 additions and 5 deletions.
13 changes: 8 additions & 5 deletions package-structure-code/complex-python-package-builds.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ back-end tools.

1. **Pure-python packages:** these are packages that only rely on Python to function. Building a pure Python package is simpler. As such, you can chose a tool below that has the features that you want and be done with your decision!

2. **Python packages with non-Python extensions:** These packages have additional components called extensions written in other languages (such as C or C++). If you have a package with non-python extensions, then you need to select a build back-end tool that allows you to add additional build steps needed to compile your extension code. Further, if you wish to use a front-end tool to support your workflow, you will need to select a tool that supports additional build setups. We suggest that you chose build tool that supports custom build steps like Hatch.
2. **Python packages with non-Python extensions:** These packages have additional components called extensions written in other languages (such as C or C++). If you have a package with non-Python extensions, then you need to select a build back-end tool that allows additional build steps needed to compile your extension code. Further, if you wish to use a front-end tool to support your workflow, you will need to select a tool that supports additional build setups. We suggest that you chose build tool that supports custom build steps like Hatch.

3. **Python packages that have extensions written in different languages (e.g. Fortran and C++) or that have non Python dependencies that are difficult to install (e.g. GDAL)** These packages often have complex build steps (more complex than a package with just a few C extensions for instance). As such, these packages require tools such as [scikit-build](https://scikit-build.readthedocs.io/en/latest/)
or [meson-python](https://mesonbuild.com/Python-module.html) to build. NOTE: you can use meson-python with PDM.
Expand All @@ -26,10 +26,13 @@ Other back-ends (`hatch`) have a preferred back-end (`hatchling`) but allow the
some back-ends (`poetry`) only work with a single back-end (`poetry-core`). Refer to (#python-package-build-tools) for
more information about front-end and back-end compatibility.

In this packaging guide we recommend using `hatch` along with it's preferred back-end `hatchling`. While this will be suitable for most packages, an alternate back-end may be used with Hatch if needed when creating an extension module.
hatch with an alternate back-end is for creating an extension module. A Python extension module is one that is made up,
either in part or entirely, of compiled code. In this case the back-end chosen (such as `meson-python`) must know how to
compile the extension language and bind it to Python since `hatchling` is only capable of building pure Python modules.
In this packaging guide we recommend using `hatch` along with its preferred back-end `hatchling`. While this will be
suitable for most packages, an alternate back-end may be used with Hatch if needed when creating an extension module.
A Python extension module is one that is made up, either in part or entirely, of compiled code. In this case the
back-end chosen (such as `meson-python`) must know how to compile the extension language and bind it to Python.
`hatchling` does not know how to do this all on its own and must either make use of
[plugins](https://hatch.pypa.io/1.9/plugins/about/) or be replaced by a backend that is already capable of building
extension modules.

In order to use a different back-end you will need to edit your project's `pyproject.toml`. If you have a
`pyproject.toml` generated by the `hatch` command, or from following the packaging tutorial, you may have
Expand Down

0 comments on commit 0c367f3

Please sign in to comment.