偶尔手痒了会撸一个 Python 的项目打包发布到 PyPI 上，方便以后安装使用。即使不是打算发布的，如果考虑把文档写在代码的注释里然后用 Sphinx 生成的，通常也是打包安装到本地，然后在一个地方集中生成文档，方便管理。

今天就来记录一下 Python 项目打包的流程。（其实是怕自己又犯傻折腾半天找不到原因）官方文档 改了几次之后明显质量好多了。

组成

一个简单的项目，通常由以下几部分组成。

• setup.py ：核心配置文件
• setup.cfg ：wheel 配置相关
• README.rst ：PyPI 不支持 Markdown，必须用 reStructuredText ，不是必须的
• MANIFEST.in ：是否需要包含其他非必须文件，不是必须的
• LICENSE.txt ：不是必须的
• <your package> ：不是必须的，但不可能没有这个吧 : )
• .travis.yml ：集成测试配置，不是必须的
• .gitignore

setup.py

核心文件，感觉像 Sphinx 那样自动生成应该更好用。下面是一个 官方 缩略版的例子，复制粘贴大法好。

from setuptools import setup, find_packages
from codecs import open
from os import path

here = path.abspath(path.dirname(__file__))

# Get the long description from the README file
with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
long_description = f.read()

setup(
    name='sampleproject',  # Required
    version='1.2.0',  # Required
    description='A sample Python project',  # Required
    long_description=long_description,  # Optional
    url='https://github.com/pypa/sampleproject',  # Optional
    author='The Python Packaging Authority',  # Optional
    author_email='pypa-dev@googlegroups.com',  # Optional
    packages=find_packages(exclude=['contrib', 'docs', 'tests']),  # Required
    install_requires=['peppercorn'],  # Optional
    entry_points={
        'console_scripts': [
            'my_func=sampleproject:main',  # Optional
        ]
    }
)

看名字就知道是干嘛的了，就不多解释了。

如果需要包含模型数据之类的，或者需要在安装后执行一个脚本的，可以查阅文档看相关的配置。

version 是比较需要注意的，一定要按照规范的格式来。

entry_points 可以在安装的时候注册一个命令行函数，上面的例子中，函数名是 my_func，对应的执行函数是 sampleproject 下面的 main 函数。

setup.cfg

主要是关于项目是否支持 Python 2 和 Python 3 的，我已经弃用 Python 2 了，所以默认配置就够了。

[bdist_wheel]
universal=1

README.rst

不是很习惯这个格式，而且 PyPI 支持的 rst 跟 Sphinx 又不太一样。

不过没关系，反正这个文件仅仅是在 PyPI 页面上显示的，大家习惯了从 GitHub 上看详细介绍，然后去看文档，所以没有这个文件也没关系，或者直接用一些工具转一下。

当然熟悉这个格式的就直接用这个好了。

MANIFEST.in

如果你需要把协议，数据，文档等东西也打包进去的话，可以配置这个。

# Include the license file
include LICENSE.txt

# Include the data files
recursive-include data *

.travis.yml

一般把代码发布到 GitHub 的时候习惯性会用这个，可以获得一个测试通过的标志 d(`･∀･)b

language: python
python:
- "2.7"
- "3.5"
install:
- pip install -r requirements.txt
script:
- pytest

复制粘贴大法好。上次手误打错一个单词，然后测试的时候总是通不过，半天没找到原因 ( º﹃º )

打包

这个时候已经可以安装到本地了。

python setup.py install

或者安装到当前路径下，适合做调试的时候使用：

pip3 install -e .

执行之后会生成几个文件夹，暂时不用管。

这个时候有必要了解一下 Wheel 和 Egg 的区别了，详情看 官方 。

先说个坑，我提交 Egg 之后发现根本没法安装，总是报错：

Collecting plane-0.0.3-py3.5.egg
Could not find a version that satisfies the requirement plane-0.0.3-py3.5.egg (from versions: )
No matching distribution found for plane-0.0.3-py3.5.egg

搜一波反正是找不到一个合理的解释的。然后换到 Wheel 就一切正常了。

总之，用 Wheel 这个新的格式肯定没错了。

生成 wheel 文件：

python setup.py bdist_wheel --universal

如果你在 setup.cfg 中配置了，那么就可以省略后面的参数了。

发布

这时候要用到 twine 这个工具了，想起来几年前发布的时候各种奇怪的流程，现在真是精简多了。

首先你要在 PyPI 上注册账号。

为了不用每次提交都手动填账号密码，可以在本地写一个文件：$HOME/.pypirc

[pypi]
username = <username>
password = <password>

然后提交就可以了：

twine upload dist/<your-wheel-package>

提交后记得测试一下能不能用 PIP 安装。