PDS模板存储库用于Python

这是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

打包

为了隔离并能够重新生成此包的环境，您应使用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 范围内，对于最常用的功能，我们应该使用

库	用法
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"。

请参阅 此处 的示例。

文档

您的项目应使用 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。不稳定构建将生成（并不断更新）快照发布。如果您没有正式发布软件，最终将得到一个 v0.0.0-SNAPSHOT 发布（有关详细信息，请参阅 NASA-PDS/roundup-action#56）。