Caterva2：按需访问Blosc2数据存储库

这是什么？

Caterva2是一个用Python编写的分布式系统，旨在通过使用发布-订阅消息模式在不同的主机之间共享Blosc2数据集（无论是本地还是即时从HDF5转换的）。在这里，发布者将数据集分类到根组中，这些组被通知给代理并传播给订阅者。此外，每个订阅者都公开一个REST接口，允许客户端访问数据集。

Caterva2 订阅者通过本地缓存（适用于重新发布）进行按需数据访问，这对于本地高效共享远程数据集尤其有用，从而优化工作组内的通信和存储资源。

Caterva2 的组成部分

Caterva2 的部署包括

• 一个 经纪人 服务，用于实现发布者和订阅者之间的通信。
• 几个 发布者，每个发布者都为订阅者提供访问一个根目录及其包含的数据集的权限。根目录可以是带有 Blosc2 和普通文件的本地 Caterva2 目录，也可以是 HDF5 文件（可能还会添加对其他格式的支持）。
• 几个 订阅者，每个订阅者跟踪来自发布者的多个根目录和数据集的变化，并在本地缓存它们以实现高效重用。
• 几个 客户端，每个客户端都会要求订阅者跟踪根目录和数据集，并提供对它们数据和元数据的访问。

发布者和订阅者可能相隔甚远，在不同的网络中，它们之间可能存在有限或昂贵的连接，而订阅者和客户端通常会足够接近，以便具有快速且廉价的连接（例如本地网络）。

Caterva2 软件包包括上述所有组件，尽管其主要作用是提供一个非常简单且轻量级的库，用于构建自己的 Caterva2 客户端。

谨慎使用

尽管此项目处于高级测试阶段，但它尚未用于生产。如果您对 Caterva2 感兴趣，请通过 contact@blosc.org 联系我们。

安装

您可以通过几种方式安装 Caterva2：

• 来自 PyPI 的预构建 wheel

  python -m pip install caterva2
  

• 从源代码构建的 wheel

  git clone https://github.com/ironArray/Caterva2
  cd Caterva2
  python -m build
  python -m pip install dist/caterva2-*.whl
  

• 开发者设置

  git clone https://github.com/ironArray/Caterva2
  cd Caterva2
  python -m pip install -e .
  

无论如何，如果您打算运行 Caterva2 服务、客户端程序或测试套件，您需要通过在上述 pip 命令的最后一个参数后追加 [feature1,feature2...] 来启用适当的额外功能。以下是一些支持的功能：

• services 用于运行所有 Caterva2 服务（经纪人、发布者、订阅者）
• base-services 用于运行 Caterva2 经纪人或发布者服务（较轻，依赖较少）
• subscriber 用于专门运行 Caterva2 订阅者服务（较重，依赖较多）
• clients 用于使用 Caterva2 客户端程序（命令行或终端）
• hdf5 用于在发布者处将 HDF5 文件作为 Caterva2 根目录提供服务
• blosc2-plugins 用于启用额外的 Blosc2 功能，如 Btune 或 JPEG 2000 支持
• plugins 用于启用 Web 客户端功能，如断层扫描显示
• tools 用于其他实用工具，如 cat2import 和 cat2export（见下文）
• tests 如果您想运行 Caterva2 测试套件

测试

安装带有 [tests] 额外功能的 Caterva2 后，您可以通过运行测试套件（与软件包一起提供）来快速检查软件包是否正常。

python -m caterva2.tests -v

您还可以从源代码运行测试

cd Caterva2
python -m pytest -v

测试将使用 Caterva2 的 root-example 目录的副本。完成后，状态文件将留在 _caterva2_tests 目录下以供检查（如果再次运行测试，它将被重新创建）。

如果您想使用自己的运行中的守护程序运行测试，您可以这样做

env CATERVA2_USE_EXTERNAL=1 python -m caterva2.tests -v

在此情况下，将不会使用 root-example 或 _caterva2_tests。

快速入门

（有关更多详细的分步指南，请参阅 Caterva2 文档中的教程。）

为了快速入门的目的，让我们使用 root-example 文件夹中的数据集。

cd Caterva2
ls -F root-example/

README.md               dir2/                   ds-1d-fields.b2nd       ds-2d-fields.b2nd       ds-sc-attr.b2nd
dir1/                   ds-1d-b.b2nd            ds-1d.b2nd              ds-hello.b2frame

首先，创建一个虚拟环境，并使用上述 [services,clients] 额外功能安装 Caterva2。然后启动经纪人，使用 root-example 数据集启动名为 foo 的根目录的发布，并创建一个订阅者。

cat2bro &  # broker
cat2pub foo root-example &  # publisher
cat2sub &  # subscriber

(稍后停止时，使用 fg 将每个文件带到前台，并按 Ctrl+C.)

HDF5 根目录

如果您想尝试发布自己的 HDF5 文件作为根目录，您需要将 Caterva2 安装中的 hdf5 扩展包含在内。然后您可以运行

cat2pub foo /path/to/your-file.h5 &

您还可以通过运行以下命令获取包含一些数据集的示例 HDF5 文件

python -m caterva2.services.hdf5root root-example.h5

您可能想测试与 silx 的 HDF5 示例 的兼容性（epics.h5 和 grove.h5 非常具有说明性）。

命令行客户端

现在服务正在运行，我们可以使用 cat2cli 客户端与订阅者通信。在另一个 shell 中，让我们列出系统中所有可用的根目录

cat2cli roots

foo

我们只有我们开始发布的 foo 根目录。如果有其他发布者在运行，我们也会在这里看到它们。

让我们让我们的本地订阅者订阅 foo 根目录

cat2cli subscribe foo  # -> Ok

现在，可以列出 foo 根目录中的数据集

cat2cli list foo

foo/README.md
...
foo/ds-hello.b2frame
...
foo/dir2/ds-4d.b2nd

让我们请求订阅者提供有关 foo/dir2/ds-4d.b2nd 数据集的更多信息

cat2cli info foo/dir2/ds-4d.b2nd

{
    'shape': [2, 3, 4, 5],
    'chunks': [1, 2, 3, 4],
    'blocks': [1, 2, 2, 2],
    'dtype': 'complex128',
    'schunk': {
        # ...
    }
}

让我们从指定的数据集中打印数据

cat2cli show foo/ds-hello.b2frame[:12]  # -> Hello world!

它还允许打印切片而不是整个数据集

cat2cli show foo/dir2/ds-4d.b2nd[1,2,3]

[115.+115.j 116.+116.j 117.+117.j 118.+118.j 119.+119.j]

最后，我们可以让订阅者下载数据集

cat2cli download foo/dir2/ds-4d.b2nd

Dataset saved to foo/dir2/ds-4d.b2nd

使用配置文件

上述所有服务（以及客户端，在一定程度上）都可以从当前目录中的 caterva2.toml 文件（或使用 --conf 选项提供的替代文件）获取其配置。Caterva2 源代码包含一个完全文档化的 caterva2.sample.toml 文件（有关更多信息，请参阅 Caterva2 指南中的 caterva2.toml）。

实验性用户身份验证

Caterva2 订阅者包括一些初始和未完成的对用户身份验证的支持。要启用它，请在设置环境变量 CATERVA2_AUTH_SECRET 为某个非空、安全的字符串后运行订阅者，该字符串将用于各种用户管理操作。之后，只有在登录电子邮件地址和密码后才能访问订阅者的 Web 客户端。可以注册新帐户，但它们的地址未经验证。密码恢复也不起作用。

要告知命令行客户端对订阅者进行身份验证，请添加 --username 和 --password 选项

cat2cli --user "user@example.com" --pass "foobar" info foo/README.md

工具

尽管 Caterva2 允许直接将 HDF5 文件发布为根目录（数据集在实时转换为 Blosc2 数组），但它还包括一个简单的脚本，可以将完整层次结构导入新的 Caterva2 根目录。您可以使用它如下

cat2import existing-hdf5-file.h5 new-caterva2-root

此工具在支持的输入和生成的输出方面仍然相当有限，请使用 --help 获取更多信息（有关更多信息，请参阅 Caterva2 工具文档中的 cat2import）。

Caterva2 还提供了一种将 Caterva 根目录导出为 HDF5 文件的互补工具；有关更多信息，请参阅 Caterva2 工具文档中的 cat2export。

cat2export existing-caterva2-root new-hdf5-file.h5

就是这样！