Updart，Ur Planetary Data Art

从行星数据系统访问行星数据集

先决条件

N/A

用户快速入门

使用以下方式安装

pip install updart

行为准则

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

开发

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

贡献

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

安装

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

pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp
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

这些钩子将检查可能包含机密的任何未来的提交。它们还检查代码格式、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下的子目录中。

配置

我们使用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管道的信息。

❗重要提示：模板用户❗所包含的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包模块中，或者最好位于与项目包结构相匹配的项目'测试'目录中。

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

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 执行自动持续集成和持续交付。默认工作流程包括 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 actions 构建步骤，Roundup。unstable-cicd 将生成（并不断更新）一个快照发布。如果您尚未进行正式的软件发布，您将最终得到一个 v0.0.0-SNAPSHOT 发布（有关详细信息，请参阅 NASA-PDS/roundup-action#56）。