PDS注册表客户端

这是用于与无服务器OpenSearch（AOSS）一起使用的请求签名实用程序的原型实现。它（目前）旨在提供类似于curl的界面，以Cognito用户身份查询PDS注册表的AOSS实例。

将来可能会添加更多功能。

先决条件

• Cognito用户的个人用户/密码凭据，该用户有权访问注册表AOSS
• Python >=3.9
• 环境变量（请联系开发人员获取值）

    export REQUEST_SIGNER_AWS_ACCOUNT=''
    export REQUEST_SIGNER_AWS_REGION=''
    export REQUEST_SIGNER_CLIENT_ID=''
    export REQUEST_SIGNER_USER_POOL_ID=''
    export REQUEST_SIGNER_IDENTITY_POOL_ID=''
    export REQUEST_SIGNER_AOSS_ENDPOINT=''
    export REQUEST_SIGNER_COGNITO_USER=''
    export REQUEST_SIGNER_COGNITO_PASSWORD=''
  

开发者快速入门

1. 克隆存储库

   git clone https://github.com/NASA-PDS/registry-client.git
   cd registry-client
   

2. 创建虚拟环境

   python -m venv venv
   source ./venv/bin/activate
   

3. 将工具安装到虚拟环境

   pip install --editable .[dev]
   

4. 直接运行工具

   registry-client --help
   

行为准则

所有NASA-PDS软件的用户和开发人员都应遵守我们的 行为准则。请阅读此准则以确保您了解我们社区的要求。

开发

要开发此项目，请使用您喜欢的文本编辑器，或具有Python支持的集成开发环境，例如 PyCharm。

贡献

有关如何为NASA-PDS代码库做出贡献的信息，请参阅我们的贡献指南。

安装

在您选择的虚拟环境中以可编辑模式安装，并包含额外的开发依赖项

pip install --editable '.[dev]'

在存储库中对任何秘密（电子邮件地址、密码、API密钥等）创建基线

detect-secrets scan . \
    --all-files \
    --disable-plugin AbsolutePathDetectorExperimental \
    --exclude-files '\.secrets..*' \
    --exclude-files '\.git.*' \
    --exclude-files '\.mypy_cache' \
    --exclude-files '\.pytest_cache' \
    --exclude-files '\.tox' \
    --exclude-files '\.venv' \
    --exclude-files 'venv' \
    --exclude-files 'dist' \
    --exclude-files 'build' \
    --exclude-files '.*\.egg-info' > .secrets.baseline

审查秘密以确定哪些应该被允许，哪些是误报

detect-secrets audit .secrets.baseline

请移除任何不应该被公众看到的秘密。然后，您可以将基线文件添加到提交中

git add .secrets.baseline

然后，配置pre-commit钩子

pre-commit install
pre-commit install -t pre-push
pre-commit install -t prepare-commit-msg
pre-commit install -t commit-msg

这些钩子将检查未来提交中是否包含任何秘密。它们还会检查代码格式、PEP8合规性、类型提示等。

👉 注意：需要一次性设置以支持detect-secrets以及您的全局Git配置。有关说明，请参阅wiki中的秘密条目。

打包

为了隔离并能够重新生成此软件包的环境，您应该使用Python虚拟环境。要这样做，请运行

python -m venv venv

然后，仅使用venv/bin/python、venv/bin/pip等。

如果您已安装tox并且希望它为您创建环境并安装依赖项，请运行

tox --devenv <name you'd like for env> -e dev

开发依赖项在setup.cfg中的dev extras_require中指定；它们以下列方式安装到虚拟环境中

pip install --editable '.[dev]'

所有源代码都位于src子目录下。

您应该使用以下内容更新setup.cfg文件：

• 模块名称
• 许可证，默认为Apache，如有需要则更新
• 描述
• 下载URL，当您在GitHub上发布软件包时，请在此处添加URL
• 关键词
• 分类器
• install_requires，添加您软件包的依赖项
• extras_require，添加您软件包的开发依赖项
• entry_points，当您的软件包可以在命令行中调用时，这有助于部署指向您软件包中脚本的命令行入口点

有关打包细节，请参阅https://packaging.pythonlang.cn/tutorials/packaging-projects/作为参考。

配置

使用ConfigParser包管理配置很方便。它允许默认配置，用户可以在其环境中特定文件中覆盖它。请参阅https://pymotw.com/2/ConfigParser/

例如

candidates = ['my_pds_module.ini', 'my_pds_module.ini.default']
found = parser.read(candidates)

日志

您不应该使用print()在代码中用于记录执行信息。根据代码运行的位置，这些信息可能会被重定向到特定的日志文件。

为此，在每个Python文件开头启动

"""My module."""
import logging

logger = logging.getLogger(__name__)

记录消息

logger.info("my message")

在您的main程序中包含

logging.basicConfig(level=logging.INFO)

以配置基本的日志系统。

工具

模板存储库中包含的dev extras_require安装了black、flake8（以及一些插件）和mypy，并为所有这些提供了默认配置。您可以使用以下命令运行所有这些（以及更多！）

tox -e lint

代码风格

为了使您的代码可读，您应该遵守PEP8风格指南。我们的代码风格通过black和flake8自动强制执行。请参阅工具部分以获取有关调用linting管道的信息。

❗重要提示：模板用户请注意❗包含的预提交配置文件将在整个src文件夹中执行flake8（以及mypy），而不仅仅是更改的文件。如果您正在将现有的代码库转换为该模板，可能会导致大量错误，而这些错误您可能还没有准备好处理。

您可以通过修改pre-commit的entry行来仅对当前所做的更改的diff执行flake8。

entry: git diff -u | flake8 --diff

或者，您可以更改pre-commit配置，使得flake8仅在匹配特定筛选标准的更改文件上调用。

-   repo: local
    hooks:
    -   id: flake8
        name: flake8
        entry: flake8
        files: ^src/|tests/
        language: system

推荐库

Python提供了大量的库。在PDS范围内，对于最常用的用途，我们应该使用

库	用法
configparser	管理和解析配置文件
argparse	命令行参数文档和解析
requests	与Web API交互
lxml	读取/写入XML文件
json	读取/写入JSON文件
pyyaml	读取/写入YAML文件
pystache	从模板生成文件

其中一些是Python 3内置的；其他的是开源附加组件，您可以将它们包含在您的requirements.txt中。

测试

本节描述了您软件包的测试。

包括测试执行、代码风格检查（mypy、black、flake8等）和文档构建的完整“构建”过程是通过以下方式执行的

tox

单元测试

您的项目应该包含内置的单元测试、功能测试、验证测试、验收测试等。

对于单元测试，请查看Python 3内置的unittest模块。

测试对象应位于test包模块中，或者最好位于项目'测试'目录中，该目录反映了项目包结构。

我们使用以下命令启动单元测试

pytest

如果您希望在做出更改时自动运行测试，请使用以下命令在监视模式下启动pytest

ptw

集成/行为测试

应使用behave包并将测试结果推送到“testrail”。

请参阅示例

文档

您的项目应使用Sphinx来构建其文档。PDS的文档模板已作为默认构建的一部分进行配置。您可以使用以下命令构建项目文档

python setup.py build_sphinx

您可以在以下目录中访问相对项目根目录的构建文件

build/sphinx/html/

构建

pip install wheel
python setup.py sdist bdist_wheel

发布

NASA PDS软件包可以使用Roundup Action自动发布，该工具利用GitHub Actions执行自动化的持续集成和持续交付。默认工作流程中已提供包含Roundup的内容，位于.github/workflows/unstable-cicd.yaml文件中。（这里的“不稳定”表示中间版本。）

手动发布

创建软件包

python setup.py bdist_wheel

将其作为GitHub发布。

在PyPI上发布（您需要一个PyPI账户并配置$HOME/.pypirc）

pip install twine
twine upload dist/*

或在Test PyPI上发布（您需要一个Test PyPI账户并配置$HOME/.pypirc）

pip install twine
twine upload --repository testpypi dist/*

CI/CD

模板存储库附带我们两个“标准”的CI/CD工作流程，即stable-cicd和unstable-cicd。不稳定的构建在向main推送时运行（±忽略特定文件的更改），而稳定的构建在推送形式为release/<发布版本>的发布分支时运行。这两个都使用了我们的GitHub动作构建步骤，即Roundup。不稳定的cicd将生成（并不断更新）一个快照发布。如果您没有进行正式的软件发布，您将得到一个v0.0.0-SNAPSHOT发布（有关详细信息，请参阅NASA-PDS/roundup-action#56）。