打包python项目

本教程将指导您如何打包一个简单的Python项目。它将向您展示如何添加创建包所需的文件和结构，如何构建包，以及如何将其上载到Python包索引。

一个简单的项目

本教程使用一个名为 example_pkg . 如果您不熟悉python的模块和 import packages ，花几分钟时间阅读 Python documentation for packages and modules . 即使您已经有了一个想要打包的项目，我们还是建议您按照使用这个示例包的方式来遵循本教程，然后尝试使用自己的包。

要在本地创建此项目，请创建以下文件结构：

packaging_tutorial/
  example_pkg/
    __init__.py

一旦您创建了这个结构，您将要在顶层文件夹中运行本教程中的所有命令-所以一定要 cd packaging_tutorial .

您还应该编辑 example_pkg/__init__.py 并在其中输入以下代码：

name = "example_pkg"

这只是为了让您可以在本教程的后面部分验证它是否正确安装，并且Pypi没有使用它。

创建包文件

现在您将创建一些文件来打包这个项目并准备分发它。创建下面列出的新文件-您将在以下步骤中向其添加内容。

packaging_tutorial/
  example_pkg/
    __init__.py
  setup.py
  LICENSE
  README.md

创建setup.py

setup.py 是的生成脚本 setuptools . 它告诉安装工具关于您的包（如名称和版本）以及要包括哪些代码文件。

正常开放 setup.py 并输入以下内容。更新包名称以包含您的用户名（例如， example-pkg-theacodes ，这可以确保您有一个唯一的包名称，并且您的包不会与其他人按照本教程上载的包冲突。

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="example-pkg-your-username",
    version="0.0.1",
    author="Example Author",
    author_email="author@example.com",
    description="A small example package",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/pypa/sampleproject",
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
)

setup() 接受几个参数。此示例包使用相对最小的集合：

  • name 是 分发名称 你的包裹。只要包含字母、数字和 _ 和 - . 它也不能在pypi.org上出现。 一定要用你的用户名更新这个， 因为这样可以确保您不会尝试上载与上载包时已存在的包同名的包。

  • version 包版本见 PEP 440 有关版本的详细信息。

  • author 和 author_email 用于标识包的作者。

  • description 是包的一个简短的一句话摘要。

  • long_description 是对包的详细描述。这在python包索引的包细节包中显示。在这种情况下，长描述从 README.md 这是一种常见的模式。

  • long_description_content_type 告诉索引用于长描述的标记类型。在这种情况下，是降价。

  • url 是项目主页的URL。对于许多项目，这只是到GitHub、Gitlab、BitBucket或类似的代码托管服务的链接。

  • packages 是所有python的列表 import packages 应该包括在 distribution package . 我们可以使用 find_packages() 自动发现所有包和子包。在这种情况下，程序包列表将 example_pkg 因为那是唯一的包裹。

  • classifiers 给出索引和 pip 关于您的包的一些附加元数据。在这种情况下，包只与python 3兼容，在MIT许可下获得许可，并且是独立于操作系统的。您应该始终至少包括您的包所使用的Python的哪个版本、包所使用的许可证以及包将使用的操作系统。有关分类器的完整列表，请参阅https://pypi.org/classifiers/。

这里提到的不止这些。见 包装配送项目 了解更多详细信息。

正在创建readme.md

正常开放 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.

创建许可证

对于上传到python包索引的每个包来说，包含一个许可证是很重要的。这会告诉安装您的软件包的用户可以使用您的软件包的条款。有关选择许可证的帮助，请参阅https://choosealelicense.com/。选择许可证后，打开 LICENSE 并输入许可证文本。例如，如果您选择了MIT许可证：

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.

生成分发档案

下一步是生成 distribution packages 为了这个包裹。这些是上载到包索引的存档文件，可以通过 pip .

确保您有最新版本的 setuptools 和 wheel 安装：

python3 -m pip install --user --upgrade setuptools wheel

小技巧

如果安装这些设备时遇到问题，请参阅 安装程序包 辅导的。

现在从同一个目录运行这个命令 setup.py 位于：

python3 setup.py sdist bdist_wheel

此命令应输出大量文本，完成后应在 dist 目录：

dist/
  example_pkg_your_username-0.0.1-py3-none-any.whl
  example_pkg_your_username-0.0.1.tar.gz

注解

如果您在这里遇到问题，请复制输出并在上提交问题 packaging problems 我们会尽力帮助你的！

这个 tar.gz 文件是 source archive 鉴于 .whl 文件是 built distribution . 更新的 pip 版本优先安装构建的发行版，但如果需要，将返回到源文件。您应该总是上传一个源归档文件，并为您的项目兼容的平台提供构建的归档文件。在这种情况下，我们的示例包与任何平台上的python都兼容，因此只需要一个构建的发行版。

上传发行档案

最后，是时候将包上传到python包索引了！

你要做的第一件事就是在 Test PyPI . 测试pypi是用于测试和实验的包索引的单独实例。对于像本教程这样不需要上传到真正索引的内容来说，这很好。要注册帐户，请转到https://test.pypi.org/account/register/并完成该页上的步骤。您还需要验证您的电子邮件地址，然后才能上载任何包。有关测试pypi的更多详细信息，请参见 使用testpypi .

现在您已经注册，可以使用 twine 上载分发包。您需要安装绳线：

python3 -m pip install --user --upgrade twine

安装后，运行捆绳以上载下面的所有存档 dist ：

python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

系统将提示您输入在test pypi中注册的用户名和密码。命令完成后，您将看到类似以下内容的输出：

Uploading distributions to https://test.pypi.org/legacy/
Enter your username: [your username]
Enter your password:
Uploading example_pkg_your_username-0.0.1-py3-none-any.whl
100%|█████████████████████| 4.65k/4.65k [00:01<00:00, 2.88kB/s]
Uploading example_pkg_your_username-0.0.1.tar.gz
100%|█████████████████████| 4.25k/4.25k [00:01<00:00, 3.05kB/s]

上传后，您的包应该可以在test pypi上查看，例如，https://test.pypi.org/project/example-pkg-your-username

安装新上载的包

你可以使用 pip 安装软件包并验证它是否正常工作。新建 virtualenv （见 安装程序包 有关详细说明），请从testpypi安装包：

python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-pkg-your-username

确保在包名称中指定您的用户名！

pip应该从test pypi安装包，输出应该如下所示：

Collecting example-pkg-your-username
  Downloading https://test-files.pythonhosted.org/packages/.../example-pkg-your-username-0.0.1-py3-none-any.whl
Installing collected packages: example-pkg-your-username
Successfully installed example-pkg-your-username-0.0.1

注解

此示例使用 --index-url 用于指定testpypi而不是live pypi的标志。此外，它还规定 --no-deps . 由于testpypi与live pypi不具有相同的包，因此尝试安装依赖项可能会失败或安装意外的内容。虽然我们的示例包没有任何依赖项，但是在使用testpypi时避免安装依赖项是一个很好的实践。

通过导入模块并引用 name 你投入的财产 __init__.py 早期的。

运行python解释器（确保您仍在virtualenv中）：

python

然后导入模块并打印出 name 属性。不管你叫什么名字， distribution package 在里面 setup.py （在这种情况下， example-pkg-your-username ）因为你的 import package 是 example_pkg .

>>> import example_pkg
>>> example_pkg.name
'example_pkg'

下一步

恭喜您，您已经打包并分发了一个Python项目！ _

请记住，本教程向您展示了如何将包上载到测试pypi，它不是永久存储。测试系统偶尔会删除包和帐户。最好使用测试pypi进行测试和实验，如本教程所示。

当您准备好将一个真正的包上载到python包索引时，您可以像本教程中所做的那样做，但有以下重要区别：

  • 为您的包裹选择一个难忘且独特的名字。您不必像在教程中那样附加用户名。

  • 在https://pypi.org上注册一个帐户-请注意，这是两个独立的服务器，来自测试服务器的登录详细信息不会与主服务器共享。

  • 使用 twine upload dist/* 要上传您的包并输入您在真实的PYPI上注册的帐户的凭据。

  • 从真实的pypi安装包，使用 pip install [your-package] .

现在，如果您想了解更多关于打包python库的内容，可以执行以下操作：