Add: text on Hatch backend compatibility #228
Conversation
|
|
||
| In this packaging guide we recommend using `hatch` along with it's preferred back-end `hatchling`. One reason to use | ||
| hatch with an alternate back-end is for creating an extension module. A Python extension module is one that is make up, | ||
| either in part or entirely, of compiled code. In this case the back-end chosen (such as `meson-python`) must know how to |
There was a problem hiding this comment.
oooh this is good @ucodery have you actually tested this by chance? i know a while back i tested pdm but i haven't had a change to test out hatch with meson-python (which a lot of the scientific community is using). but this is a really excellent addition to this page!!
There was a problem hiding this comment.
I did no testing for this PR 🙈. I've built extension modules with setuptools or maturin but never coupled with hatch, and never used meson-Python for anything.
There was a problem hiding this comment.
Alright, I think I tested that everything works as expected. It's a little meta, but meson-python the project uses mesonpy as it's own backend. So I cloned the repo, set up a new virtualenv with only hatch in it, and built meson-python with no change to its pyproject.toml.
There was a problem hiding this comment.
wow thank you!! you rock!
i'm curious - did your pyproject.toml look something like this:
https://github.com/pyOpenSci/examplePy/blob/main/example6_pdm_meson/pyproject.toml
essentially that was my playing around with building using meson-python / mesonpy and pdm. please also note that i've only worked on pure python packages so my knowledge of complex builds is minimal!
There was a problem hiding this comment.
I used the pyproject.toml exactly as it came down from git - so it looked like this https://github.com/mesonbuild/meson-python/blob/main/pyproject.toml.
Using hatch only as a front-end means that it is in my python environment, but not necessarily defined in project code at all. (Not at all in this case. If the project was making use of hatch environments but not using hatchling, then the pyproject.toml would have a reference to both build tools).
| @@ -13,7 +13,32 @@ 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. In this case, you could use setuptools. However, we suggest that you chose build tool that supports custom build steps such as Hatch with Hatchling or PDM. PDM is an excellent choice as it allows you to also select your build back-end of choice. We will discuss this at a high level on the complex builds page. | |||
| 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. | |||
There was a problem hiding this comment.
| 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 backend tool that allows additional build steps needed to compile your extension code. Further, if you wish to use a front-end tool (such as JavaScript) 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. |
There was a problem hiding this comment.
A small nit (@lwasser): what is our preferred spelling of front-end and back-end?
There was a problem hiding this comment.
FWIW I was following the style in this file which was consistently -end.
Also not sure why you added JavaScript? Can JS build python projects and is this common? I was referring to frontends like build and pip.
There was a problem hiding this comment.
i think i tend to use the - as @ucodery this would be another good place to have that vale style checker. as many including Jeremiah have pointed out I often forget which style we prefer.
There was a problem hiding this comment.
I think I've made all the requested changes, except everything still uses"-end".
(except that one time build-backend is used. A reason for a style change @lwasser ? "build-back-end" is probably not what we want 🤣 )
There was a problem hiding this comment.
Ah @ucodery ...I was thinking about JupyterLab and how we distribute JS code and Python code. All looks good to me.
There was a problem hiding this comment.
@ucodery i think build-backend is good ... i'm sorry i think i missed that it was spelled build-back-end 😆 agreed that is not what we want. let me actually look at the text here ...
|
@ofek I know you are really busy but do you by chance have a bit of time to review this PR adding information about using hatch with other build backends (meson being the one the scientific community prefers). The only time we'd advise someone to do this would be if they have extensions as hatchling has nice defaults. |
| In this packaging guide we recommend using `hatch` along with it's preferred back-end `hatchling`. One reason to use | ||
| hatch with an alternate back-end is for creating an extension module. A Python extension module is one that is make 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 but `hatchling` is only capable of building pure Python modules. |
There was a problem hiding this comment.
Not strictly true; there is no built-in functionality but you can build extension modules with plugins. For example, a major one is coming very soon: scikit-build/scikit-build-core#637
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
| @@ -13,7 +13,35 @@ 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. In this case, you could use setuptools. However, we suggest that you chose build tool that supports custom build steps such as Hatch with Hatchling or PDM. PDM is an excellent choice as it allows you to also select your build back-end of choice. We will discuss this at a high level on the complex builds page. | |||
| 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. | |||
There was a problem hiding this comment.
There was a problem hiding this comment.
@ucodery this looks good to me!!
@ofek @willingc thank you so so much for the input!!
Jeremy i think we can make a call on how to spell out backend / back-end / back end 😆 and go with it. should we just write backend and then open a issue that someone else could tackle to make it consistent throughout?
i'm approving this however so you have two approvals! Feel free to merge!
|
Happy to help! FYI I prefer the non-hyphenated version. |
|
I went ahead and remove the extra |
closes #111