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
中,您为您希望扩展的任何钩子提供实现。
钩子实现是一个具有以下特征的函数:
与钩子同名
接受为钩子定义的部分或所有参数
用
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 插件的非详尽列表:
tljh-pangeo:用于设置 Pangeo 堆栈的 TLJH 插件。
tljh-voila-gallery:安装 Voilà 仪表板画廊的 TLJH 插件。
tljh-repo2docker:TLJH 插件,用于使用 repo2docker 构建多个用户环境。
tljh-shared-directory:TLJH 插件,在
/srv/scratch
中为 Hub 用户设置一个共享目录。tljh-db:用于处理 mysql 数据库的 TLJH 插件。
如果您编写了插件,请提交 PR 将其添加到此列表中!
我们还建议在 GitHub 仓库中添加 tljh-plugin
主题,使其更容易被发现:topics/tljh-plugin