PDS4子模型管理

此存储库包含管理PDS4子模型（以前称为数据词典）所需的工具和软件

先决条件

包括任何系统级要求（如brew install、apt-get install、yum install等），但请确保使用Python 3，因为Python 2于2020年1月1日达到生命终点。

用户快速入门

使用以下方法进行安装

pip install my_pds_module

如果可能，让您的程序无需额外配置即可正常工作，但请参阅配置部分以获取详细信息。

要执行，请运行

(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，如有需要则更新
• 描述
• 下载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文件：

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管道的信息，请参阅工具部分。

❗注意：对于模板用户❗包含的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范围内，对于最常用的库，我们应该使用

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

测试

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

通过以下方式执行完整的“构建”，包括测试执行、linting（mypy、black、flake8等）和文档构建：

tox

单元测试

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

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

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

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

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自动发布，该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/*

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

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

CI/CD

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