HEPData-CLI

关于

命令行界面（CLI）和应用程序接口（API），允许用户搜索、从HEPData下载和上传。

代码与Python 2和Python 3兼容。灵感来自arxiv-cli。

安装（对于用户）

使用pip从PyPI安装

$ pip install --user hepdata-cli
$ hepdata-cli --help

对于Python 3（<3.7），如果未设置LANG环境变量，您可能会得到如下错误

RuntimeError: Click will abort further execution because Python 3 was configured to use ASCII as encoding for the environment. Consult https://click.palletsprojects.com/python3/ for mitigation steps.

在这种情况下，您需要按照Click文档中描述的方法导出一个Unicode区域设置。

安装（对于开发者）

在虚拟环境中从GitHub安装

$ git clone https://github.com/HEPData/hepdata-cli.git
$ cd hepdata-cli
$ python3 -m venv ~/venv/hepdata-cli
$ source ~/venv/hepdata-cli/bin/activate
(hepdata-cli) $ pip install -e '.[tests]'
(hepdata-cli) $ hepdata-cli --help
(hepdata-cli) $ pytest --cov=hepdata_cli

用法

您可以使用HEPData-CLI作为命令行界面（CLI）来搜索、下载和上传HEPData数据库中的记录，或者作为Python库通过其应用程序接口（API）执行相同的操作。

CLI

$ hepdata-cli [-v/--version, --help]
$ hepdata-cli [--verbose] find [QUERY] [-kw/--keyword KEYWORD] [-i/--ids IDTYPE]
$ hepdata-cli [--verbose] download [IDS] [-f/--file-format FORMAT] [-i/--ids IDTYPE] [-t/--table-name TABLE-NAME] [-d/--download-dir DOWNLOAD-DIR]
$ hepdata-cli [--verbose] fetch-names [IDS] [-i/--ids IDTYPE]
$ hepdata-cli [--verbose] upload [PATH-TO-FILE-ARCHIVE] [-e/--email YOUR-EMAIL] [-r/--recid RECORD-ID] [-i/--invitation-cookie COOKIE] [-s/--sandbox TRUE/FALSE] [-p/--password PASSWORD]

find命令在HEPData数据库中搜索与QUERY匹配的内容。可以使用网站的高级搜索语法。

download命令从数据库中下载记录（见下文选项）。

fetch-names命令返回具有提供ID的记录中的数据表名称。

upload命令将文件上传到HEPData网站作为沙盒或普通记录。

参数[-kw/--keyword KEYWORD]将搜索结果字典过滤为特定关键字。首先尝试关键字精确匹配，否则接受部分匹配。

参数 [-i/--ids IDTYPE] 接受等于 arxiv、hepdata 或 inspire 的 IDTYPE。

参数 [-f/--file-format FORMAT] 接受等于 csv、root、yaml、yoda、yoda1 或 json 的 FORMAT。在前四种情况下，将下载并解压缩为一个目录的 .tar.gz 归档，而在最后一种情况下，将下载 .json 文件。

参数 [-t/--table-name TABLE-NAME] 接受一个字符串，给出输入的表名。在这种情况下，只下载指定的表为 .csv、.root、.yaml、.yoda、.yoda1 或 .json 文件。

参数 [-d/--download-dir DOWNLOAD-DIR] 指定下载文件的目录。如果未指定，则默认下载目录为 ./hepdata-downloads。

参数 [-e/--email YOUR-EMAIL] 是上传者的电子邮件，需要将提交与他们的 HEPData 账户关联。

参数 [-i/--invitation-cookie COOKIE] 必须为非沙盒提交提供。这可以在提交过程开始时收到的上传者邀请电子邮件中找到。

参数 [-s/--sandbox TRUE/FALSE] 是一个布尔值，用于决定是否上传到沙盒。

参数 [-p/--password PASSWORD] 是上传者 HEPData 账户的密码（如果未指定，则提示输入）。警告：不要在用于共享的任何代码中以未加密的形式存储您的密码。

可以将 hepdata-cli download/fetch-names 和 hepdata-cli find 命令连接，如果为 find 指定了 IDTYPE。如果使用 arxiv 作为 IDTYPE，还可以将 arxiv download，来自 pypi/arxiv-cli 的命令，与 hepdata-cli find 连接。

API

与上述内容等效，这些命令可以通过 API 调用（实际上，CLI 只是 API 的包装器）。

from hepdata_cli.api import Client
client = Client(verbose=True)
client.find(query, keyword, ids)
client.download(id_list, file_format, ids, table_name, download_dir)
client.fetch_names(id_list, ids)
client.upload(path_to_file, email, recid, invitation_cookie, sandbox, password)

示例

示例 1 - 普通搜索

$ hepdata-cli --verbose find 'reactions:"P P--> LQ LQ X"'

或等效地

client.find('reactions:"P P--> LQ LQ X"')

匹配单个条目并返回完整的元数据字典。

示例 2 - 带有关键字的搜索

$ hepdata-cli --verbose find 'reactions:"P P--> LQ LQ"' -kw year

或等效地

client.find('reactions:"P P--> LQ LQ"', keyword='year')

匹配四个条目并返回它们的出版年份，作为一个字典。

示例 3 - 搜索记录的 ids

$ hepdata-cli --verbose find 'reactions:"P P--> LQ LQ"' -i hepdata

或等效地

client.find('reactions:"P P--> LQ LQ"', ids='hepdata')

匹配四个条目并返回它们的 hepdata ids，作为一个普通列表。

示例 4 - 使用 inspire ids 连接搜索和下载

$ hepdata-cli --verbose download $(hepdata-cli find 'reactions:"P P--> LQ LQ"' -i inspire) -i inspire -f csv

或等效地

id_list = client.find('reactions:"P P--> LQ LQ"', ids='inspire')
client.download(id_list, ids='inspire', file_format='csv')

下载包含 csv 文件的四个 .tar.gz 归档，并在默认的 ./hepdata-downloads 目录中解压缩。

示例 5 - 在记录中查找表名

$ hepdata-cli fetch-names $(hepdata-cli find 'reactions:"P P--> LQ LQ"' -i hepdata) -i hepdata

或等效地

id_list = client.find('reactions:"P P--> LQ LQ"', ids='hepdata')
client.fetch_names(id_list, ids='hepdata')

返回四个匹配记录中的所有表名。

示例 6 - 使用 arxiv-cli 连接搜索和下载

此示例需要安装 arxiv-cli，这可以通过以下方式轻松完成：

$ pip install --user arxiv-cli

请注意，arxiv-cli 安装了一个较旧的版本 click，这将上述示例 5 中的 CLI 命令从 fetch-names 更改为 fetch_names。

然后：

$ arxiv download $(hepdata-cli find 'reactions:"P P--> LQ LQ"' -i arxiv)

或等效地

import arxiv_cli
import hepdata_cli
arxiv_client = arxiv_cli.Client()
hepdata_client = hepdata_cli.Client()
id_list = hepdata_client.find('reactions:"P P--> LQ LQ"', ids='arxiv')
arxiv_client.download(id_list)

从 arXiv 下载两个 pdf。

示例 7 - 将记录上传到沙盒

$ hepdata-cli upload /path/to/TestHEPSubmission.tar.gz -e my@email.com -s True

或等效地

client.upload('/path/to/TestHEPSubmission.tar.gz', email='my@email.com', sandbox=True)

然后可以从您的 沙盒 中找到上传的提交。您将被提示输入与您的 HEPData 账户关联的密码。如果您使用 CERN 或 ORCID 身份验证创建了账户，您将首先需要 设置密码。

示例 8 - 替换沙盒中的记录

$ hepdata-cli upload /path/to/TestHEPSubmission.tar.gz -e my@email.com -r 1234567890 -s True

或等效地

client.upload('/path/to/TestHEPSubmission.tar.gz', email='my@email.com', recid='1234567890', sandbox=True)

请注意，您必须自己上传原始沙盒记录，并且您将被提示输入密码。

示例 9 - 上传非沙盒记录

$ hepdata-cli upload /path/to/TestHEPSubmission.tar.gz -e my@email.com -r 123456 -i 8232e07f-d1d8-4883-bb1d-77fd9994ce4f -s False 

或等效地

client.upload('/path/to/TestHEPSubmission.tar.gz', email='my@email.com', recid='123456', invitation_cookie='8232e07f-d1d8-4883-bb1d-77fd9994ce4f', sandbox=False)

上传的提交可以从您的仪表板中找到。邀请cookie包含在您最初的邀请电子邮件中。您必须已经通过点击电子邮件中的链接或从您的仪表板中声明了权限。再次提醒，您将被提示输入密码，如果使用CERN/ORCID登录，则必须设置密码。密码可以作为CLI（-p PASSWORD）或API（password=PASSWORD）的参数传递。但是，请注意保护您的密码安全，例如，通过为CI/CD工作流程定义加密的环境变量。