PyPI简介

Python Package Index, 缩写为PyPI, 是Python的官方第三方软件存储库. PyPI主要以称为sdist(源代码发行版)或预编译“wheel”的归档形式托管Python包. PyPI推荐使用pip包管理器来下载第三方库. pip可正常工作在Windows, Mac OS, Unix/Linux等操作系统上. 这里我们要说的是如何将python包发布到PyPi.

规范项目结构

这里建议按以下规格规范项目结构:

1
2
3
4
5
6
7
8
myProject/
  myproject/
    __init__.py
  tests/
  setup.py
  LICENSE.txt
  requirements.txt
  README.md

详情可以转到 Python项目目录结构.

编辑 setup.py

setup.py 是 setuptools 的构建脚本. 它能告诉 setuptools 有关你的包的信息(如名称和版本)以及要包括哪些代码文件.
打开setup.py并输入以下内容. 更改包名称以确保你有一个唯一的包名称, 不会与其他人上传的包名称冲突.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import setuptools

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

setuptools.setup(
    name="example_name",  # 你的包名称
    version="0.0.1",  # 你的包版本    
    author="Example Author",  # 作者
    author_email="author@example.com",  # 作者邮箱
    description="A small example package",  # 一句话形容包
    long_description=long_description,  # 是对该包的详细说明. 详细描述一般是从readme.md加载的
    long_description_content_type="text/markdown",  # readme的格式
    url="https://github.com/pypa/sampleproject",  # 项目地址
    packages=setuptools.find_packages(),  # 是应该包含在发行包中的所有Python导入包的列表. 这样写是自动发现.
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',  # 需要的python版本
)

setup()有很多参数, 下面来详细介绍:

  • name: 你的包名称. 可以包含字母, 数字, _ , 和 -. 必须没有和别人上传的包名称冲突.
  • version: 你的包版本, 可以在 PEP 440 上看到更多详细介绍.
  • author 和 author_email: 作者名和作者邮箱.
  • description: 一句话形容这个包.
  • long_description: 对该包的详细介绍, 这会展示在 PyPI 网页上. long description 默认会从 README.md 里加载.
  • long_description_content_type: 加载详细介绍的格式. 这里是 Markdown.
  • url: 项目的网址.
  • packages: 是应该包含在发行包中的所有Python导入包的列表. 除了手动列出各个依赖包外, 我们可以使用 find_packages() 去自动寻找依赖包列表.
  • classifiers: 关于你的包的额外参数. 在这个例子里, 这个包只能运行在Python3环境中, 使用的是 MIT 项目许可声明, 可以在任意操作系统运行. 关于 classifiers 更详细的介绍, 可以浏览 https://pypi.org/classifiers/ .

安装发布依赖包并打包你的项目

确保安装 setuptools 和 wheel 两个包.

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

在 setup.py 所在的文件夹内运行以下命令:

python3 setup.py sdist bdist_wheel

这个命令会在 dist 目录创建两个文件:

1
2
3
dist/
  example_name-0.0.1-py3-none-any.whl
  example_name-0.0.1.tar.gz

tar.gz文件是源代码包, 而.whl文件是构建的发行版. 较新的pip版本优先安装已构建的发行版, 但如果需要, 将退回到源代码包.

上传你的发行包到PyPI

现在, 你应该创建一个PyPI账号, 以便能够安全地上传项目 https://pypi.org/account/register/ .

你现在需要安装 twine 包来上传你的包.

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

安装完成后你可以用以下命令上传 dist 目录下的所有文件:

python3 -m twine upload dist/*

twine会默认上传到 https://pypi.org/ .

接着会让你输入你的PyPI的账号和密码, 确认无误后就会上传到 PyPI 了.

之后可以用 pip install your_package_name 安装你上传的包了.

你在 PyPI官网 上登陆账号后, 也可以在线管理你的包.

参考文献

1. Python Packaging User Guide