PDS4本地数据字典管理

此存储库包含管理PDS4本地数据字典所需的工具和软件

先决条件

包含任何系统级需求（brew install，apt-get install，yum install，…）Python 3应该被使用，因为Python 2已于2020年1月1日达到生命终结。

用户快速入门

安装方式

pip install pds.ldd-manager

如果可能，使您的程序无需任何额外配置即可直接运行——但请参阅配置部分以获取详细信息。

要执行，请运行

(put your run commands here)

行为准则

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

开发

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

贡献

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

安装

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

pip install --editable '.[dev]'

配置pre-commit钩子

pre-commit install && pre-commit install -t pre-push

打包

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

python -m venv venv

然后仅使用venv/bin/python，venv/bin/pip等（不再建议使用venv/bin/activate）。

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

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

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

pip install --editable '.[dev]'

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

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

• 模块名称
• 许可证，默认为apache，如有必要则更新
• 描述
• 下载网址，当您在GitHub上发布您的包时，请在此处添加网址
• 关键字
• 分类器
• 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文件开始

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 自动强制执行。有关调用代码检查管道的信息，请参阅工具部分。

❗请注意，对于模板用户❗包含的 pre-commit 配置文件 会执行整个 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 包模块中，或者最好位于项目 'tests' 目录中，该目录反映了项目包结构。

我们的单元测试通过以下命令启动：

pytest

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

ptw

集成/行为测试

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

请参阅https://github.com/NASA-PDS/pds-doi-service#behavioral-testing-for-integration--testing 的示例。

文档

您的项目应使用 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 执行自动化的持续集成和持续交付。在 .github/workflows/unstable-cicd.yaml 文件中提供了包含 Roundup 的默认工作流程。（这里的 "不稳定" 指的是中间版本。）

手动发布

创建包

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/<release version>的发布分支时运行。这两个都使用了我们的GitHub动作构建步骤，即Roundup。unstable-cicd将生成（并持续更新）一个快照版本。如果您没有进行正式的软件发布，最终将得到一个v0.0.0-SNAPSHOT版本（有关详细信息，请参阅NASA-PDS/roundup-action#56）。