Python版PDS模板存储库

这是PDS Python项目的模板存储库。

这个存储库旨在成为PDS中用于新python存储库的基础。它指导开发者简化项目的初始化，并推荐首选选项以标准化开发和简化维护。只需点击 使用此模板 按钮↑（或使用 此超链接）。

🏃 使用此模板开始

有关设置您的新存储库的更多信息，请参阅我们的维基页面。一旦完成必要的启动步骤，您可以删除本节。

https://github.com/NASA-PDS/nasa-pds.github.io/wiki/Git-and-Github-Guide#creating-a-new-repo

👉 重要！ 您必须分配上面维基页面上提到的团队！至少，这些包括

团队	权限
@NASA-PDS/pds-software-committers	写入
@NASA-PDS/pds-software-pmc	管理员
@NASA-PDS/pds-operations	管理员

---

我的项目

这是XYZ，为行星数据系统做这件事，那件事和另一件事。

请访问我们的网站： https://nasa-pds.github.io/pds-my-project

它包含对开发人员和最终用户有用的信息。

先决条件

包括任何系统级要求（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
pre-commit install -t prepare-commit-msg
pre-commit install -t commit-msg

这些钩子检查代码格式，并阻止包含密码或API密钥等机密信息的提交。然而，您需要在全局Git配置中进行一次性设置。有关如何操作的说明，请参阅 Git机密维基条目。

打包

为了隔离并能够重新生成此包的环境，您应该使用 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，如有需要则更新
• 描述
• 下载网址，当您在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范围内，对于当前的使用，我们应该使用

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

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

测试

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

完整的“构建”，包括测试执行、linting（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/<发布版本>的发布分支时运行。这两个工作流程都使用了我们的GitHub actions构建步骤，即Roundup。不稳定的CI/CD将生成（并持续更新）一个快照发布。如果您尚未进行正式的软件发布，您将得到一个v0.0.0-SNAPSHOT发布（有关详细信息，请参阅NASA-PDS/roundup-action#56）。