蟒蛇启动器

示例 Python 项目，演示如何使用最新的 Python 测试和 linting 工具创建经过测试的 Python 包。该项目包含一个提供除法 ( ) 和命令行界面 ( )div的简单实现的包。div.libdiv.cli

要求

Python 3.6+。

笔记

由于Python 2.7 支持于 2020 年 1 月 1 日结束，因此新项目应考虑仅支持 Python 3，这比尝试同时支持两者要简单。因此，此示例项目中对 Python 2.7 的支持已被删除。

运行 CLI 应用程序

• export PYTHONPATH="${PYTHONPATH}:<path_to_directory>/python-starter/src"
• python cli.py -a 5 -b 2

依赖项

依赖项定义在：

• requirements.txt
• dev-requirements.txt

虚拟环境

开发期间的最佳实践是使用该 命令创建一个隔离的Python virtualenv 包装器。mkvirtualenv这将使依赖的 Python 包不会干扰系统上的其他 Python 项目。

在*尼克斯上：

$ mkvirtualenv -p python3.x venv

pip将核心打包工具（ 、setuptools和wheel）更新到最新版本是一种很好的做法。

(venv) $ python -m pip install --upgrade pip setuptools wheel

安装依赖

要更新依赖项：

(venv) $ pip install -r requirements.txt
(venv) $ pip install -r dev-requirements.txt

升级依赖项后，按照单元测试 部分所述运行单元测试，以确保没有任何更新的包导致当前项目不兼容。

打包

该项目被设计为一个 Python 包，这意味着它可以捆绑并重新分发为单个压缩文件。

打包配置如下：

• pyproject.toml
• setup.py
• MANIFEST.in

要将项目打包为 源分发和轮子：

(venv) $ python setup.py sdist bdist_wheel

这将生成dist/div-1.0.0.tar.gz和dist/div-1.0.0-py3-none-any.whl。

阅读有关车轮优势的更多信息，以了解为什么生成车轮分布很重要。

将分发上传到 PyPI

源和轮子可再发行包可以上传到 PyPI或使用pip.

要上传到 PyPI：

(venv) $ python -m pip install twine
(venv) $ twine upload dist/*

测试

使用tox执行自动化测试。tox 将自动创建基于tox.ini单元测试、PEP8 样式指南检查和文档生成的虚拟环境。

# Run all environments.
#   To only run a single environment, specify it like: -e lint
# command above.
(venv) $ tox

单元测试

使用pytest执行单元测试。pytest 已成为事实上的 Python 单元测试框架。与内置unittest模块相比的一些关键优势是：

1. 测试所需的样板显着减少。
2. 符合 PEP8 的名称（例如pytest.raises()，代替self.assertRaises()）。
3. 充满活力的插件生态系统。

pytest 将通过递归搜索.py 以.testtest

该tests文件夹被创建为一个 Python 包（即其中有一个__init__.py文件），因为这有助于pytest为测试文件提供唯一的命名空间。没有这个，两个测试文件不能被命名相同，即使它们在不同的子目录中。

代码覆盖率由pytest-cov插件提供。

在运行单元测试 tox 环境（例如tox -e py36）时，会在文件夹中生成 HTML 报告，htmlcov显示每个源文件以及在单元测试期间执行了哪些行。在 Web 浏览器中打开htmlcov/index.html以查看报告。代码覆盖率报告有助于识别当前未测试的项目区域。

代码覆盖率在pyproject.toml.

将参数传递给pytestthrough tox：

(venv) $ tox -e py36 -- -k invalid_divide

代码风格检查

PEP8是普遍接受的 Python 代码风格指南。使用flake8验证 PEP8 代码合规性。flake8 配置[flake8]在tox.ini. 额外的 flake8 插件也包括在内：

• pep8-naming：确保以正确的大小写命名函数、类和变量。

自动代码格式化

代码使用black自动格式化。导入使用isort自动排序和分组。

这些工具由以下人员配置：

• pyproject.toml

要自动格式化代码，请运行：

(venv) $ tox -e fmt

要验证代码是否已格式化，例如在 CI 作业中：

(venv) $ tox -e fmt-check

生成的 API 文档

生成一个新的 Sphinx 项目

要生成此项目中显示的 Sphinx 项目：

(venv) $ mkdir -p docs/api
(venv) $ cd docs/api
(venv) $ sphinx-quickstart --no-makefile --no-batchfile --extensions sphinx.ext.napoleon
# When prompted, select all defaults.

适当修改conf.py：

# Add the project's Python package to the path so that autodoc can find it.
import os
import sys
sys.path.insert(0, os.path.abspath("../../src"))

您可能还需要添加文件（参见第 13 行）apidoc/modules.rst。index.rst此项目已完成此操作，但如果您开始自己的项目，可能会有所帮助。

Python 项目模块的 API 文档div是使用Sphinx tox 环境自动生成的。Sphinx 是一个文档生成工具，它是 Python API 文档的事实上的工具。Sphinx 使用RST标记语言。

这个项目使用了用于 Sphinx 的拿破仑插件，它呈现谷歌风格的文档字符串。谷歌风格的文档字符串在代码中提供了易于阅读的文档字符串的良好组合以及渲染良好的输出。

"""Divides first input with the second input.

Args:
    a: Numerator
    b: Denominator

Raises:
    InvalidDivideError: If denominator is 0

Returns:
    Computed division.
"""

Sphinx 项目在docs/api/conf.py.

该项目使用furo狮身人面像主题，因为它优雅、易于使用、黑暗的主题。

docs-api使用tox 环境（例如tox或）构建文档tox -e docs-api。构建完成后，docs/api/_build/index.html在 Web 浏览器中打开。

要将 Sphinx 配置为在检测到更改时自动重建，请在浏览器中运行tox -e docs-api-serve 并打开http://127.0.0.1:8000 。