赞
踩
原文链接: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
现在我们来为分发包对我们的文件做填充。完成后的文件结构应该像这个一样
- packaging_tutorial/
- ├── LICENSE
- ├── pyproject.toml
- ├── README.md
- ├── src/
- │ └── example_package_YOUR_USERNAME_HERE/
- │ ├── __init__.py
- │ └── example.py
- └── tests/
tests/ 文件夹用于存放测试程序,现在可以为空
这个文件负责告知前端工具,像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"
配置元数据
打开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"
创建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
Copyright © 2003-2013 www.wpsshop.cn 版权所有,并保留所有权利。