💫 科学Python INcantations (spin)

科学 Python 库的开发工具

开发者需要记住一大堆神秘的命令行咒语。这些咒语也可能随时间变化。通常，使用 Makefiles 来提供别名，但 Makefiles 可能很复杂，不是用 Python 编写的，且难以扩展。因此，spin 的目标是提供简单、用户友好、可扩展的通用开发任务界面。它自带一些常见的构建命令，但可以很容易地根据项目进行自定义。

作为一个有趣的事实：开发此工具的动机是科学 Python 库（SciPy、scikit-image、NumPy 等）在 distutils 被弃用后大量迁移到 Meson。当许多构建和安装命令发生变化时，抽象掉必须重新学习的烦恼是有意义的。

注意：我们现在有可编辑安装的实验性构建。下面列出的大多数 Meson 命令对于这些应该都能“直接使用”。

安装

pip install spin

配置

设置存储在 .spin.toml、spin.toml 或您的项目的 pyproject.toml 中。例如，请参阅 示例 pyproject.toml 中的 [tool.spin] 部分。

应包含 name 的 [project] 部分。应包含 [tool.spin] 部分的以下内容

package = "pkg_importname"  # name of your package
commands = [
  "spin.cmds.meson.build",
  "spin.cmds.meson.test"
]

参见下面的 命令选择。

命令部分

一旦你有了几个命令，将它们组织成部分可能很有用。在 pyproject.toml 中，不要将命令指定为列表，而是使用以下结构

[tool.spin.commands]
"Build" = [
  "spin.cmds.meson.build",
  "spin.cmds.meson.test"
]
"Environments" = [
  "spin.cmds.meson.ipython",
  "spin.cmds.meson.run"
]

这些命令将被渲染为

Build:
  build  🔧 Build package with Meson/ninja
  test   🔧 Run tests

Environments:
  ipython  💻 Launch IPython shell with PYTHONPATH set
  run      🏁 Run a shell command with PYTHONPATH set

运行

spin

或者

python -m spin

内置命令

Meson

作为 spin.cmds.meson.* 提供。

build      🔧 Build package with Meson/ninja
ipython    💻 Launch IPython shell with PYTHONPATH set
python     🐍 Launch Python shell with PYTHONPATH set
shell      💻 Launch shell with PYTHONPATH set
test       🔧 Run pytest
run        🏁 Run a shell command with PYTHONPATH set
docs       📖 Build Sphinx documentation
gdb        👾 Execute a Python snippet with GDB
lldb       👾 Execute a Python snippet with LLDB

构建（PEP 517 构建器）

作为 spin.cmds.build.* 提供。

sdist      📦 Build a source distribution in `dist/`

pip（Python 包安装器）

pip 允许进行可编辑安装，这是另一种常见的开发工作流程。

作为 spin.cmds.pip.* 提供。

install    💽 Build and install package using pip.

元（操作命令的命令）

作为 spin.cmds.meta.* 提供。

introspect 🔍 Print a command's location and source code

🧪 自定义命令

spin 可以调用自定义命令。这些命令定义了自己的参数，并且可以访问 pyproject.toml 文件进行进一步配置。

例如，请参阅 示例自定义命令。

按照以下方式将自定义命令添加到 pyproject.toml 的 [tool.spin] 部分的 commands 变量

commands = [..., '.spin/cmds.py:example']

在这里，命令存储在 .spin/cmds.py 中，函数名为 example。

配置

自定义命令可以按以下方式访问 pyproject.toml

from spin import util


@click.command()
def example():
    """Command that accesses `pyproject.toml` configuration"""
    config = util.get_config()
    print(config["tool.spin"])

参数覆盖

可以为任何命令覆盖默认参数。上面的自定义命令，例如，具有以下签名

@click.command()
@click.option("-f", "--flag")
@click.option("-t", "--test", default="not set")
def example(flag, test, default_kwd=None):
    """🧪 Example custom command.
    ...
    """

使用 [tool.spin.kwargs] 部分覆盖 click 选项或函数关键字的默认值

[tool.spin.kwargs]
".spin/cmds.py:example" = {"test" = "default override", "default_kwd" = 3}

高级：向内置命令添加参数

项目可能想要向内置的 spin 命令添加标志，或者可能需要做一些预处理或后处理。为此，我们必须使用一个名为 上下文 的 Click 内部概念。幸运的是，我们不需要了解上下文的其他内容，只需知道它们允许我们在命令中执行命令。

我们通过复制现有命令的函数头，并添加我们自己的标志来继续

from spin.cmds import meson

# Take this from the built-in implementation, in `spin.cmds.meson.build`:


@click.command()
@click.argument("meson_args", nargs=-1)
@click.option("-j", "--jobs", help="Number of parallel tasks to launch", type=int)
@click.option("--clean", is_flag=True, help="Clean build directory before build")
@click.option(
    "-v", "--verbose", is_flag=True, help="Print all build output, even installation"
)

# This is our new option
@click.option("--custom-arg/--no-custom-arg")

# This tells spin that we will need a context, which we
# can use to invoke the built-in command
@click.pass_context

# This is the original function signature, plus our new flag
def build(ctx, meson_args, jobs=None, clean=False, verbose=False, custom_arg=False):
    """Docstring goes here. You may want to copy and customize the original."""

    # Do something with the new option
    print("The value of custom arg is:", custom_arg)

    # The spin `build` command doesn't know anything about `custom_arg`,
    # so don't send it on.
    del ctx.params["custom_arg"]

    # Call the built-in `build` command, passing along
    # all arguments and options.
    ctx.forward(meson.build)

    # Also see:
    # - https://click.palletsprojects.com/en/8.1.x/api/#click.Context.forward
    # - https://click.palletsprojects.com/en/8.1.x/api/#click.Context.invoke

高级：覆盖 Meson CLI

一些包使用 Meson 的供应商版本。可以在 pyproject.toml 中设置自定义 Meson CLI 的路径。

[tool.spin.meson]
cli = 'path/to/custom/meson'

常见问题解答

• 运行 spin 时，命令列表中的表情符号没有显示。

您的终端字体可能不包含表情符号字符。例如，如果您在 Arch Linux 上使用 noto，则表情符号是单独安装的。

sudo pacman -S noto-fonts-emoji
fc-cache -f -v

对于贡献者

spin 的开发在 GitHub 上进行，网址为 scientific-python/spin。使用以下方式调用 spin 测试

nox -s test

其他示例

nox -s test -- -v
nox -s test -- -v spin/tests/test_meson.py

历史

《dev.py》工具是由Ralf Gommers提出的，并经Sayantika Banik、Eduardo Naufel Schettino和Ralf Gommers（还请参阅Sayantika的博客文章）实现，被纳入SciPy项目中（请参见SciPy GitHub问题和实现Pull Request）。受该实现启发，spin（本包）由Stéfan van der Walt进行最小化重写，旨在易于扩展，以便在整个生态系统库中使用。我们感谢Danila Bredikhin和Luca Marconato，他们慷慨地将spin名称捐赠给PyPi。