fsspec-reference-maker

为 ReferenceFileSystem 创建参考描述的功能

版本 0

ReferenceFileSystem 所需结构的原型规范

{
  "key0": "data",
  "key1": ["protocol://target_url", 10000, 100]
}

其中

• key0 包含原始数据（以文本形式存储）
• key1 指向数据文件 URL、文件中的偏移量（以字节为单位）和数据项的长度（以字节为单位）。

例如，本规范中提出的 Zarr 数据可能表示为

{
  ".zgroup": "{\n    \"zarr_format\": 2\n}",
  ".zattrs": "{\n    \"Conventions\": \"UGRID-0.9.0\n\"}",
  "x/.zattrs": "{\n    \"_ARRAY_DIMENSIONS\": [\n        \"node\"\n ...",
  "x/.zarray": "{\n    \"chunks\": [\n        9228245\n    ],\n    \"compressor\": null,\n    \"dtype\": \"<f8\",\n  ...",
  "x/0": ["s3://bucket/path/file.nc", 294094376, 73825960]
}

版本 1

元数据结构在 JSON 中。我们注意到，对于未来可能的二进制存储，应将“版本”、“gen”和“templates”视为属性，而“refs”作为应主导存储大小的数据。先前定义的版本 0 与“refs”条目兼容，但在此我们添加了新功能。还将有可能将此新增强规范扩展到版本 0 格式。

{
  "version": (required, must be equal to) 1,
  "templates": (optional, zero or more arbitrary keys) {
    "template_name": jinja-str
  },
  "gen": (optional, zero or more items) [
    "key": (required) jinja-str,
    "url": (required) jinja-str,
    "offset": (optional, required with "length") jinja-str,
    "length": (optional, required with "offset") jinja-str,
    "dimensions": (required, one or more arbitrary keys) {
      "variable_name": (required) 
        {"start": (optional) int, "stop": (required) int, "step": (optional) int}
        OR
        [int, ...]
    }
  ],
  "refs": (optional, zero or more arbitrary keys) {
    "key_name": (required) str OR [url(jinja-str)] OR [url(jinja-str), offset(int), length(int)]
  }
}

其中

• jinja-str 是将被 jinja2 或其非 Python 等效物渲染的字符串；即，它可以是文本字符串，也可以包括 "{{..}}" 注释，其中
  • 对于与模板名称关联的值，变量是通过使用此模板的引用 URL 字符串传递的
  • 对于“gen”对象内的值，变量来自“dimensions”和“templates”
• 引用值的字符串格式可以是
  • 以 "base64:" 开头的字符串，它将被解码为二进制
  • 任何其他字符串，解释为 ascii 数据
• 引用值的字符串版本表示数据，一个元素的数组表示整个 URL，而三个元素的版本表示 URL 的一个二进制部分

以下是一个示例

{
    "version": 1,
    "templates": {
        "u": "server.domain/path",
        "f": "{{c}}"
    },
    "gen": [
        {
            "key": "gen_key{{i}}",
            "url": "http://{{u}}_{{i}}",
            "offset": "{{(i + 1) * 1000}}",
            "length": "1000",
            "dimensions": 
              {
                "i": {"stop":  5}
              }
        }   
    ],
    "refs": {
      "key0": "data",
      "key1": ["http://target_url", 10000, 100],
      "key2": ["http://{{u}}", 10000, 100],
      "key3": ["http://{{f(c='text')}}", 10000, 100]
    }
}

在此，变量 i 取 [0, 1, 2, 3, 4] 的值，这可以以数组形式提供。如果有多个变量，将形成笛卡尔积。

此示例计算为版本 0 等价物

{
  "key0": "data",
  "key1": ["http://target_url", 10000, 100],
  "key2": ["http://server.domain/path", 10000, 100],
  "key3": ["http://text", 10000, 100],
  "gen_key0": ["http://server.domain/path_0", 1000, 1000],
  "gen_key1": ["http://server.domain/path_1", 2000, 1000],
  "gen_key2": ["http://server.domain/path_2", 3000, 1000],
  "gen_key3": ["http://server.domain/path_3", 4000, 1000],
  "gen_key4": ["http://server.domain/path_4", 5000, 1000]
}

例如，访问“key0”返回 b"data"，访问“gen_key0”则从指定的URL返回1000字节的偏移量1000。

示例

运行一个笔记本示例，比较使用此方法读取HDF5与原生Zarr格式