TLJH 插件#

TLJH 插件是使用 TLJH 作为基础创建定制化“版本”或“堆栈”的官方方式。例如,地球科学社区可以制作一个插件,安装常用的软件包,设置身份验证并预先下载有用的数据集。mybinder.org 社区可以制作一个插件,为您提供一个单节点、单存储库的 mybinder.org。插件功能非常强大,因此可能性是无限的。

设计#

pluggy 用于实现插件功能。TLJH 暴露了特定的钩子,您的插件可以提供实现。这允许我们在应用程序中拥有明确的钩子点,这些钩子点可以通过插件进行显式扩展,从而平衡未来更改 TLJH 内部的需要与良好插件生态系统所需的稳定性。

安装插件#

在安装程序脚本中包含 --plugin <install_name>。有关更多信息,请参阅自定义安装程序

编写一个简单插件#

我们将尝试编写一个安装几个库的简单插件,并用它来解释插件机制的工作原理。我们将把这个插件称为 tljh-simple

插件目录结构#

我们建议为您的插件创建一个新的 git 仓库。插件是普通的 python 包 - 但是,由于它们通常更简单,我们建议它们存在于一个文件中。

对于 tljh-simple,仓库的结构应该如下所示:

tljh_simple:
 - tljh_simple.py
 - setup.py
 - README.md
 - LICENSE

README.md(或 README.rst 文件)包含关于您的插件为用户做了什么的可读信息。LICENSE 指定了您的插件使用的许可证 - 我们推荐 3-Clause BSD 许可证,因为 TLJH 本身也使用该许可证。

setup.py - 元数据与注册#

setup.py 将此标记为一个 python 包,并包含有关包本身的元数据。它应该看起来像这样:

from setuptools import setup

setup(
    name="tljh-simple",
    author="YuviPanda",
    version="0.1",
    license="3-clause BSD",
    url='https://github.com/yuvipanda/tljh-simple',
    entry_points={"tljh": ["simple = tljh_simple"]},
    py_modules=["tljh_simple"],
)

这是一个大部分标准的 setup.py 文件。entry_points={"tljh": ["simple = tljh_simple]} 将模块 tljh_simple(在文件 tljh_simple.py 中)注册为 TLJH 的插件。

tljh_simple.py - 实现#

tljh_simple.py 中,您为您希望扩展的任何钩子提供实现。

钩子实现是一个具有以下特征的函数:

  1. 与钩子同名

  2. 接受为钩子定义的部分或所有参数

  3. hookimpl 装饰器函数装饰,该函数从 tljh.hooks 导入。

可以在源代码仓库的 tljh/hooks.py 中查看可用钩子的当前列表以及它们的调用时机。每个钩子的示例实现可以参考 integration-tests/plugins/simplest/tljh_simplest.py

这个例子提供了 tljh_extra_user_conda_packages 钩子的实现,它可以返回一个将在用户环境中从 conda-forge 安装的 conda 包列表。

from tljh.hooks import hookimpl

@hookimpl
def tljh_extra_user_conda_packages():
    return [
        'xarray',
        'iris',
        'dask',
    ]

发布插件#

插件是 Python 包,应发布到 PyPI。用户也可以直接从 GitHub 安装它们 - 尽管这不是一个好的长期实践。

Python 包应命名为 tljh-<pluginname>

已知插件列表#

如果您正在寻找扩展或自定义 TLJH 部署的方法,您可能希望查找现有插件。

以下是已知 TLJH 插件的非详尽列表:

如果您编写了插件,请提交 PR 将其添加到此列表中!

我们还建议在 GitHub 仓库中添加 tljh-plugin 主题,使其更容易被发现:topics/tljh-plugin