pygcdm

一个用于使用通用数据模型 (CDM)文件通过远程过程调用传输的Python API。

• 安装
• 用法
  • 使用gRPC传输文件
  • 编码/解码API
  • 消息类型
  • variable_spec 定义
• 实用工具
  • 在本地重建包
  • 将包提交到PyPi
  • 从proto文件生成Python源代码
  • 在本地运行测试

安装

使用conda创建一个新的虚拟环境。如果您机器上没有安装conda，请按照以下说明进行安装。请注意，pygcdm需要python>=3.9，所以我们明确指定。然后，在激活conda环境后，我们可以使用pip进行安装。

conda create --name [environment name] python=3.9
conda activate [environment name]
pip install pygcdm

用法

使用gRPC传输文件

这演示了如何实现Python编码/解码API并通过gRPC传输netCDF文件。首先，在终端中打开两个独立的标签页。确保您安装要求的Python环境在两个标签页中都是激活的。导航到本存储库中的examples文件夹。

在第一个标签页中，通过运行以下命令启动 gRPC 服务器：

python grpc_netcdf_server.py

如果一切正常，你应该会看到类似 starting server... 的信息。

在第二个标签页中，通过运行以下命令发起客户端请求：

python grpc_netcdf_client.py

如果一切正常，终端应该会打印出类似 xarray 数据集的内容。你可以修改 grpc_netcdf_client.py 中的 loc 和 variable_spec 变量来修改传输的数据。

编码/解码 API

这演示了如何在 Python 脚本中编码/解码 gRPC 消息。

# import/instantiate encoder object
from pygcdm.netcdf_encode import netCDF_Encode
encoder = netCDF_Encode()

# import and define header request
import pygcdm.protogen.gcdm_netcdf_pb2 as grpc_msg
file_loc = "test/data/test3.nc"
header_request = grpc_msg.HeaderRequest(location=file_loc)
header_response = encoder.generate_header_from_request(header_request)

# define data request
var_spec = "analysed_sst"
data_request = grpc_msg.DataRequest(location=file_loc, variable_spec=var_spec)
data_response = encoder.generate_data_from_request(data_request)

# decode header/data into xarray object
from pygcdm.netcdf_decode import netCDF_Decode
decoder = netCDF_Decode()
ds = decoder.generate_file_from_response(header_response, data_response)

消息类型

pygcdm 有两种消息类型 HeaderRequest 和 DataRequest，它们分别对应响应类型 HeaderResponse 和 DataResponse。这些消息类型可以在 这里 了解，并在 protos/pygcdm/protogen/gcdm_netcdf.proto 中定义。主要思想是，你将包含所需信息的请求消息打包，并将响应消息解包（pygcdm 会为你完成打包/解包）。.proto 消息的阅读性相当好，但这里也提供了描述。

HeaderRequest:

• location（字符串）：响应机上的 netCDF 文件所在的文件位置。

DataRequest:

• location（字符串）：响应机上的 netCDF 文件所在的文件位置。
• variable_spec（字符串）：描述你想要请求的 netCDF 变量/变量切片（参见本 README 中的 variable_spec 部分）。

variable_spec 定义

variable_spec 是定义你想要从远程 netCDF 文件中获取哪些变量/数据切片的方式。它遵循以下定义的 Backus-Naur 形式，该定义借鉴自 netcdf-java，其文档可在 这里 查看。

section specification := selector | selector '.' selector
selector := varName ['(' dims ')']
varName := ESCAPED_STRING


dims := dim | dim, dims
dim := ':' | slice | start ':' end | start ':' end ':' stride
slice := INTEGER
start := INTEGER
stride := INTEGER
end := INTEGER
ESCAPED_STRING : must escape characters = ".("

在实践中，这意味着 variable_spec 可能看起来像以下示例。切片表示法类似于 numpy 切片（但并不相同）。

• analysed_sst
• analysed_sst(:, :, :)
• analysed_sst(0,0:719:10,0:1439:10)
• analysed_sst(0,200:700:10,1300:1400:10)

请注意，这些示例是从 test/ 中的某些测试中派生出来的。

工具

在本地重建包

如果你在本地修改了包并想重建包以进行测试，可以从根目录运行以下命令：

pip install .

（你可以通过运行 pip show -f pygcdm 验证安装）。

将包提交到 PyPi

如果你有权限这样做，可以在根目录中运行以下命令将包提交到 PyPi：

python setup.py upload

这将提示你选择上传类型：test 或 real，其中 test 会上传到 https://test.pypi.org/project/pygcdm/，而 real 会上传到 https://pypi.ac.cn/project/pygcdm/。然后你会被提示输入登录凭证。

从 proto 文件生成 Python 源代码

为了从 protos/src/protogen 中的 .proto 文件生成 grpc python 源代码，我们需要使用 protoc 编译器（奇怪子文件夹结构的原因是为了让 protoc 生成具有正确导入命名空间的文件）。可以通过以下说明安装带有 protoc 的 Python 包：这里。

要编译我们的代码，并将结果函数放入 src/protogen/ 中，我们可以使用以下命令（从包含此 README 的根目录中）：

$ python -m grpc_tools.protoc -I protos/ --python_out=. --grpc_python_out=. protos/pygcdm/protogen/*.proto

有关 protoc 编译器的更多信息，可以通过在 Python 中加载模块并使用 help 命令来获取。

$ python
>>> import grpc_tools.protoc
>>> help(grpc_tools.protoc)

本地运行测试

如果您想在本地运行测试，请确保已安装 pytest 模块。然后，从根目录运行以下命令

pytest test/*.py

如果您正在测试以验证任何更改，请确保使用上述说明在本地重新构建软件包。