NASA PDS DOI 服务

行星数据系统（PDS）数字对象标识符（DOI）服务为PDS操作员提供创建DOI的工具。

先决条件

• Python 3.9或更高版本
• 登录到DOI服务提供方端点服务器（目前为DataCite）

用户文档

请访问以下文档：https://nasa-pds.github.io/doi-service/

开发者

JPL内部维基

获取代码并在分支上工作

git clone ...
git checkout -b "#<issue number>"

在venv目录下安装Python虚拟环境

python3 -m venv venv
source venv/bin/activate

在虚拟环境中安装开发和依赖包

pip install --editable '.[dev]'

如果您遇到以下错误

src/types.h:36:2: error: You need a compatible libgit2 version (1.1.x)

那么您可能正在使用brew.sh的Python 3.10。请使用他们的Python 3.9。

更新您的本地配置以访问DOI服务提供方的测试服务器。

在项目的根目录中创建一个名为pds_doi_service.ini的文件；以下内容可以用作模板

[SERVICE]
# Should be set to DataCite (case-insensitive)
provider = datacite

[DATACITE]
# Select the appropriate URL endpoint for either a test or production deployment
url = https://api.test.datacite.org/dois
#url = https://api.datacite.org/dois
user = <contact [PDS Help Desk](https://pds.nasa.gov/?feedback=true)>
password = <contact [PDS Help Desk](https://pds.nasa.gov/?feedback=true)>
doi_prefix = 10.17189
validate_against_schema = True

[OSTI]
# This section is kept for posterity, but should be ignored as OSTI is no longer a supported endpoint
url = https://www.osti.gov/iad2test/api/records
#url = https://www.osti.gov/iad2/api/records
user = <contact [PDS Help Desk](https://pds.nasa.gov/?feedback=true)>
password = <contact [PDS Help Desk](https://pds.nasa.gov/?feedback=true)>
doi_prefix = 10.17189
validate_against_schema = True

[PDS4_DICTIONARY]
url = https://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_JSON_1D00.JSON
pds_node_identifier = 0001_NASA_PDS_1.pds.Node.pds.name

[API_AUTHENTICATION]
# Add the issuer of the oauth tokens, for cognito https://cognito-idp.<aws-region>.amazonaws.com/<userpoolID>
jwt_issuer =
# Add the entire content of the JSON file at https://cognito-idp.<aws-region>.amazonaws.com/<userpoolID>/.well-known/jwks.json
json_web_key_set =
jwt_lifetime_seconds = 3600
jwt_algorithm = RS256

[OTHER]
logging_level = INFO
doi_publisher = NASA Planetary Data System
global_keyword_values = PDS,PDS4
pds_uri = https://pds.nasa.gov/pds4/pds/v1/
transaction_dir = ./transaction_history
db_file = doi.db
db_table = doi
api_host = 0.0.0.0
api_port = 8080
api_valid_referrers =
emailer_local_host = localhost
emailer_port       = 25
emailer_sender     = pdsen-doi-test@jpl.nasa.gov
emailer_receivers  = pdsen-doi-test@jpl.nasa.gov

启动API服务器

要运行DOI API服务器，请尝试

$ pip install pds-doi-service
$ pds-doi-api

启动的服务文档可在http://localhost:8080/PDS_APIs/pds_doi_api/0.2/ui/找到

👉 注意：当在pds_doi_service.ini中设置api_valid_referrers选项时，此服务文档UI将不可用。

使用Docker运行

要在Docker容器上运行服务器，请从包目录执行以下命令

$ # building the image
$ docker image build --tag pds-doi-service .
$ # starting up a container
$ docker container run --publish 8080:8080 pds-doi-service

但是请注意，当通过docker container run启动容器时，所有配置值均来自与存储库捆绑的默认INI文件。要覆盖配置，建议通过Docker Composition启动服务

$ # Make a copy of the docker composition environment template:
$ cp doi_service.env.in doi_service.env
$ # Edit the environment file, setting the credentials within:
$ vi doi_service.env
$ # Start the composition; on some systems, `docker compose` is `docker-compose`:
$ docker compose up

这将使用顶层的docker-compose.yml文件启动DOI服务容器，该文件指定从doi_service.env导入环境变量。修改doi_service.env（在从doi_service.env.in复制后）以定义在服务启动时要覆盖的任何配置值。

测试

测试细节在本节中详细说明。

Tox（针对开发者）

注意。pip依赖项的更新不会自动应用于现有的tox虚拟环境，以保持单元测试快速。传播依赖项更新的最简单方法是删除./.tox并再次运行tox。

tox在pip install --editable .[dev]期间自动安装，并为以下提供虚拟环境和运行配置

• 单元/功能测试
• 代码审查
• 构建丰富的文档。

要运行完整的测试套件，只需运行

tox

您也可以单独运行组件

$ tox -e tests  # Run unit, functional, and integration tests
$ tox -e lint  # Run flake8, mypy, and black code reformatting
$ tox -e docs  # Build the documentation to see if that works

强烈建议将tox -e lint添加到您的pre-commit git钩子，并将tox -e tests添加到pre-push钩子中，因为只有经过审查和测试通过的项目才会被合并。

以下是一个用于方便使用的代码审查示例

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep ".py$")

echo "Linting files"
tox -e lint
git add $STAGED_FILES  # add any lint-related changes to the current commit

if [ $? -ne 0 ]
then
    echo "Initial lint detected errors, re-linting to determine whether errors remain"
    tox -e lint
    if [ $? -ne 0 ]
    then
      exit 1
    fi
fi

exit 0

如果您愿意，也可以运行pytest、sphinx-build、mypy等。

行为测试（针对集成与测试）

行为测试也在您运行pip install --editable .[dev]时预安装在Python虚拟环境中。通过运行以下命令启动它们

behave

注意这将下载参考测试数据。如果需要更新，您必须首先删除本地参考数据的副本（test/aaDOI_production_submitted_labels）

您也可以以更美观的格式运行它们

behave -f allure_behave.formatter:AllureFormatter -o ./allure ./features
allure service allure

👉 注意：这假设您已安装Allure测试报告框架。

Testrail报告

测试报告可以推送到Testrail

项目：行星数据系统（PDS）测试套件：pds-doi-service

设置您的环境

export TESTRAIL_USER=<your email in testrail>
export TESTRAIL_KEY=<your API key in tesrail>

运行测试

behave

在https://cae-testrail.jpl.nasa.gov/testrail/index.php?/projects/overview/168查看结果

👉 注意： 这假设您有权访问喷气推进实验室的Testrail安装。

文档管理

关于文档的文档在本节中描述。

设计

在此存储库中查看

https://github.com/NASA-PDS/pds-doi-service/tree/main/docs

或在源包中的docs目录。

用户文档

用户文档由Sphinx管理，当您运行pip install --editable .[dev]时，Sphinx也会安装在您的Python虚拟环境中。您可以像上面描述的那样使用tox来制作文档，或者随时手动运行

sphinx-build -ab html docs/source docs/build

构建与发布

构建和发布过程由GitHub Actions和Roundup管理。