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

本页内容
在 GitHub 上编辑
显示源代码