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 包列表，这些包将从 conda-forge 安装到用户的环境中。

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 将其添加到此列表中！

我们还建议将 tljh-plugin 主题添加到 GitHub 存储库，以使其更容易被发现：topics/tljh-plugin

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