| single |
# 💫 Scientific Python INcantations (`spin`)
## A developer tool for scientific Python libraries
Developers need to memorize a whole bunch of magic command-line
incantations.
These incantations may also change over time.
Often, Makefiles are used to provide aliases, but Makefiles can be
convoluted, are not written in Python, and are hard to extend.
The goal of `spin` is therefore to provide a simple, user-friendly,
extendable interface for common development tasks.
It comes with a few common build commands out the box, but can easily be
customized per project.
As a curiosity: the impetus behind developing the tool was the mass
migration of scientific Python libraries (SciPy, scikit-image, and NumPy,
etc.) to Meson, after distutils was deprecated.
When many of the build and installation commands changed, it made sense to
abstract away the nuisance of having to re-learn them.
_Note:_ We now have experimental builds for editable installs.
Most of the Meson commands listed below should work "out of the box" for
those.
- [Installation]
- [Configuration]
- [Command sections]
- [Running]
- [Built-in commands]
- [Meson]
- [Build (PEP 517 builder)]
- [pip (Package Installer for Python)]
- [Meta (commands that operate on commands)]
- [🧪 Custom commands]
- [Configuration]
- [Argument overrides]
- [Advanced: adding arguments to built-in commands]
- [Advanced: override Meson CLI]
- [Auto-completion]
- [FAQ]
- [For contributors]
- [History]
## Installation
`
pip install spin
`
## Configuration
Settings are stored in `.spin.toml`, `spin.toml`, or your project's
`pyproject.toml`.
As an example, see the `[tool.spin]` section of [an example
`pyproject.toml`].
The `[project]` section should contain `name`.
The `[tool.spin]` section should contain:
```
package = "pkg_importname" # name of your package
commands = [
"spin.cmds.meson.build",
"spin.cmds.meson.test"
]
```
See [the command selection] below.
### Command sections
Once you have several commands, it may be useful to organize them into
sections.
In `pyproject.toml`, instead of specifying the commands as a list, use the
following structure:
```toml
[tool.spin.commands]
"Build" = [
"spin.cmds.meson.build",
"spin.cmds.meson.test"
]
"Environments" = [
"spin.cmds.meson.ipython",
"spin.cmds.meson.run"
]
```
These commands will then be rendered as:
```
Build:
build 🔧 Build package with Meson/ninja
test 🔧 Run tests
Environments:
|