Python每日读01-分发python模块
原文链接：Packaging Python Projects — Python Packaging User Guide
这个指导将讲解如何打包一个简单的python项目，它将会展示你如何去添加那些必须的文件和结构用于创建项目包，如何去构建项目包，和如何去上传它到python package index。
某些命令需要最新版本的pip，因此请确定你已安装了最新版本的pip:
Unix/macOS：
python3 -m pip install --upgrade pip
windows:
py -m pip install --upgrade pip
一个简单的项目
本指南使用 example_packages_YUOR_USERNAME_HERE.作为文件的名称，将自己的名字替换YUOR_USERNAME_HERE的部分即可，我的名字DeliciousPotato因此我的文件名就是example_packages_DeliciousPotato.如此命名可以保证不会与已经上传了的其他也遵循这个指南的人的名称产生冲突。我们推荐遵循这个指导的原样构建你自己的文件结构。
在本地构建如下的文件结构：
packaging_tutorial/
└── src/
└── example_package_YOUR_USERNAME_HERE/
├── __init__.py
└── example.py- 包含 Python 文件的目录应与项目名称匹配。这简化了配置，对于安装包的用户来说更为明显。
- __init__.py 是必须的，将目录作为一个包导入，并且必须为空
- example.py 包含实现模块功能的逻辑。
创建包文件夹
现在我们来为分发包对我们的文件做填充。完成后的文件结构应该像这个一样
packaging_tutorial/
├── LICENSE
├── pyproject.toml
├── README.md
├── src/
│ └── example_package_YOUR_USERNAME_HERE/
│ ├── __init__.py
│ └── example.py
└── tests/创建tests文件夹
tests/ 文件夹用于存放测试程序，现在可以为空
创建pyproject.toml
这个文件负责告知前端工具，像pip和build，哪些后端工具将会在为你的项目创建分发包的时候用到。可以从很多后端工具中选择；本指导使用Hatchling作为默认，它和 setuptools, Flit, PDM以及其他的支持元数据包平台的后端一样。
打开pyproject.toml并且输入这些[build-system]（创建系统）的平台：
使用Hacthing请输入
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
使用setuptools请输入
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
使用Flit请输入
[build-system]
requires = ["flit_core>=3.2"]
build-backend = "flit_core.buildapi"
使用PDM请输入
[build-system]
requires = ["pdm-pep517"]
build-backend = "pdm.pep517.api"
- requires 是创建你的包所需要的包列表。你不需要去安装他们，构造前端像pip将会自动的安装他们，在一个为了在构造进程时使用而建立的临时的孤立的环境里面
- build-backend是前端将会用于运行构造的Python对象的名字
配置元数据
打开pyproject.toml并且输入以下的字段。改变其中的“name”使得包含使用者的名字。这个保证你的包名字与遵循这个教程上传文件的人不会产生冲突
[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
{ name="Example Author", email="author@example.com" },
]
description = "A small example package"
readme = "README.md"
license = { file="LICENSE" }
requires-python = ">=3.7"
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
[project.urls]
"Homepage" = "https://github.com/pypa/sampleproject"
"Bug Tracker" = "https://github.com/pypa/sampleproject/issues"- name ：分发包的名称。可以为含有字母，数字，'.','_'和‘-’。并且不能够已经被PyPi使用。请务必更新上面指导中的名称，以保证不会和已将上传到PyPi的包产生冲突
- vision ：包的版本。详细见Version specifiers — Python Packaging User Guide此说明文档。
- authors：作者名称。这个将会被展示在PyPI的细节菜单上，为每一个作者填写明确的名称和email。也可以以同样的格式列出维护人员名单
- description：包概要描述，一句话足矣
- readme：包详细描述文件的地址。将会被显示PyPI的“包的相关细节”页面。在本指导中，包的详细被记载在README.md文件中。
- license：LICENSE文件的地址
- requires-python：提供支持你的项目的python版本。安装器比如pip将会回顾旧的python安装包指导找到匹配的python版本
- classifiers：提供给index和pip 一些附加的关于你的包的元数据。在这个指导中，这个包仅仅与python3兼容。应该总是至少包含你的包应该架构在哪个python版本上，和你的包在哪些许可的条件下运行。详尽的classifiers，请访问Classifiers · PyPI
- urls：允许您列出要在 PyPI 上显示的任意数量的额外链接。通常，这可能是源，文档，问题跟踪器等。
创建README.md
打开并输入以下文本，你可以稍作修改
# Example Package
This is a simple example package. You can use
[Github-flavored Markdown](https://guides.github.com/features/mastering-markdown/)
to write your content.创建LICENSE（许可）
对任每一个上传到PyPI的包，包含至少一个许可是十分重要的。许可将会告诉安装你的包的使用者在什么情况下他们可以使用你的包。一旦你已经选择了一个许可，打开并且输入许可文本。比如，你已经选择了MIT许可
关于打包许可的帮助，请访问 Choose an open source license | Choose a License.
Copyright (c) 2018 The Python Packaging Authority
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. 添加其它文件
以上的文件列表将会被自动的包含在你的贡献资源中。如果你希望去包含一些附加的文件，请查看针对你的后端的说明文档。
生成分发档案
接下来的步骤就是去为你的包生成分发档案，这些是上传到PythonPackageIndes并且可以被pip安装
请确保已经安装了最新版的PyPA's，安装与更新命令如下：
Unix/macOS
python3 -m pip install --upgrade build
windowos：
py -m pip install --upgrade build现在在与pyproject.toml相同的文件夹下运行如下的命令：
Unix/macOS
python3 -m build
windowos：
py -m build 此命令应输出大量文本，完成后应在目录中生成两个文件：dist
dist/
example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz 该文件是源分发版，而该文件是构建版分发版。较新的 pip 版本优先安装构建的发行版，但如果需要，将回退到源代码发行版。您应该始终上传源代码分发版，并为项目兼容的平台提供构建的分发版。在这种情况下，我们的示例包在任何平台上都与Python兼容，因此只需要一个构建的发行版。tar.gz.whl
上传分发存档
最后，是时候将你的包上传到Python包索引了！
您需要做的第一件事是在TestPyPI上注册一个帐户，这是用于测试和实验的包索引的单独实例。对于像本教程这样我们不一定想上传到真实索引的东西来说，这非常有用。要注册帐户，请转到 Create an account · TestPyPI 并完成该页面上的步骤。您还需要验证您的电子邮件地址，然后才能上传任何包裹。有关更多详细信息，请参阅使用 TestPyPI。
要安全地上传项目，您需要一个 PyPI API 令牌。Log in · TestPyPI 创建一个，将“范围”设置为“整个帐户”。在复制并保存令牌之前，不要关闭页面 - 您将不会再次看到该令牌。
注册后，您可以使用 twine 上传分发包。您需要安装 Twine：
Unix/macOS
python3 -m pip install --upgrade twine
windows
py -m pip install --upgrade twine安装完成后，运行Twine以上传以下所有存档：dist
Unix/macOS
python3 -m twine upload --repository testpypi dist/*
windows
py -m twine upload --repository testpypi dist/*系统将提示您输入用户名和密码。对于用户名，请使用 。对于密码，请使用令牌值，包括前缀。__token__pypi-
命令完成后，您应该会看到类似于以下内容的输出：
Uploading distributions to https://test.pypi.org/legacy/
Enter your username: [your username]
Enter your password:
Uploading example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
100%|█████████████████████| 4.65k/4.65k [00:01<00:00, 2.88kB/s]
Uploading example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz
100%|█████████████████████| 4.25k/4.25k [00:01<00:00, 3.05kB/s]上传后，您的软件包应该在TestPyPI上可见;例如：。https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE