怎么将自己写的包打包上传到PyPi供其他人下载

我们先装好依赖的包

打包和上传依赖wheel和twine这两个包。

pip install whell

pip install twine

先准备好项目

比方说我们想写这样一个包，这个包只有一个功能，那就是打印程序员佛祖字符画。

image.png

# __init__.py
buddha = ...

def print_buddha():
    print(buddha)

这个包就提供了一个佛祖字符画和一个打印函数。

# __main__.py
from . import print_buddha
print_buddha()

__main__.py让这个包可以被python -m直接运行，而__main__.py其实也就只干了一件事，那就是调用print_buddha打印字符画。

打包项目

打包项目你需要学习以下知识

1. 创建setup.py
2. 打包wheel
3. 用twine上传的PyPi

一个标准的包的目录结构

packaging_tutorial
├── LICENSE # 开源协议证书
├── README.md # 说明文件
├── * your_pkg1
│ └── __init__.py
├── * your_pkg2
│ └── __init__.py
├──*setup.py # 顾名思义了
└── tests # 单元测试

加星的是必须的，其他的可有可无不影响打包和上传PyPi，就是不规范而已。

创建setup.py

setup.py是setuptools的构建脚本。它告诉setuptools有关您的软件包（例如名称和版本）以及要包括的代码文件的信息。

最基本的setup.py

# -*- coding: utf-8 -*-
from setuptools import setup, find_packages

try:
    long_description = open("README.md").read()
except IOError:
    long_description = ""

setup(
    name="Buddha",
    version="0.1.0",
    description="A pip package",
    license="MIT",
    author="你的名字",
    packages=find_packages(),
    long_description=long_description,
    classifiers=[
        "Programming Language :: Python",
        "Programming Language :: Python :: 3.6",
    ]
)

然后我们试一下打包：

 python setup.py sdist bdist_wheel

这是个组合命令，意思是先打sdist，再打bdist_wheel。

image.png

sdist打出来的是tar.gz格式压缩包，里面就是包源文件，可以供直接解压然后python setup.py install安装。

bdist_wheel打出来的是whl格式文件，这是pip官方安装包文件格式。

注意：egg格式已经过时了，现在PyPi的包都是用whl格式。

什么是egg？
Wheel和Egg都是打包格式，旨在支持不需要构建或编译的安装工件的用例，这在测试和生产工作流程中可能会耗费大量成本。
python setup.py bdist_egg 就可以打出egg格式的包。
Egg格式由setuptools于2004年推出，而Wheel格式由PEP 427于2012年推出。
目前，Wheel被认为是Python构建和二进制打包的标准。
这是Wheel和Egg之间重要区别的细分。

PiPy上传规范是同时要tar.gz和whl两个格式的包。

setup.py参数详解

注意：打了星的是必须参数

描述性参数 —— 提供包信息，供PiPy识别管理。

描述性参数只是作为PKG_INFO用的，没有什么特殊作用，就是描述用的，用来供pip和PyPi管理的，因此看上面就可以了。

包文件搜集 —— 设置包的哪些文件需要打包，怎么找这些文件。（很重要）

setup.py 需要提供以上参数数据用来搜集需要打到包里的文件:
注意：打了星的是重要参数

根据上面的说明，我们来演练一下。首先项目要做些修改和添加一些功能。

image.png

• 我们把包的源码都放到src目录下了。
• 在buddha模块里增加一个buddha.txt的文本用来存我们的佛祖字符画，并将buddha模块里写死的字符画改为读这个文件。
• 增加一个buddha.bat脚本，这个脚本里面就一行python -m buddha，调用buddha模块打印字符画，让buddha包支持命令行直接调用，就省去输入python -m的麻烦。
• 增加一个字符画txt文本，里面就是佛祖字符画，这个文本就当做是个文档，我们会放到PYTHON_HOME的Doc文件夹里。
• 增加一个single_module，试一下单文件模块怎么打包到包里。

接着修改setup.py:

setup(
    # 包信息
    ...

    # 包搜集
    package_dir={"":"src"},
    packages=find_packages("src"),
    package_data={"buddha":["*.txt"]}, 
    py_modules=["single_module"],
    package_data={"buddha":["*.txt"]}
    data_files=[("Doc",["src/buddha_doc.txt"])],
    scripts=["src/buddha.bat"],
)

• find_packages需要指定从遍历哪个文件夹下的包。你可能会有疑问，为什么设置了package_dir还需要指明，不是会默认从src目录下找吗？其实是这样的，find_package这个函数只是返回一个字符串数组，在我们的项目里返回的就是["buddha"]。如果你不用find_package那么就是手写["buddha"]，find_package只是个工具函数，省去你手写的麻烦，但是并不是setuptools内部的机制，find_package不认package_dir。setuptools最终会用packages的字符串数组到package_dir去找包，然后copy到build文件夹，最终一起打到dist目录下生成二进制whl文件。
• packages默认只搜集py文件，buddha.txt不会被打到包里，因此需要在package_data里指明。
• 我们的single_module是一个文件模块，packages只处理文件夹模块。因此要用py_modules参数来添加。
• 我们有个buddha_doc.txt字符画文本，我们把它当做文档，希望包安装的时候能够被放到PYTHON_HOME目录下的Doc文件夹里。
  image.png
  
  (这本身没什么意义，只是演示怎么将自己的文件安装到自己希望的位置，如果你了解pth文件你就知道将文件安装到自己想要的位置有什么意义。)
• 我们有个buddha.bat脚本，希望其能够被安装到PYTHON_HOME/Scripts目录下，这样命令行就能直接调用。

注意：data_files、scripts这两个参数不享受package_dir的效果，必须指定根目录下相对路径。

打包看看：

python setup.py sdist bdist_wheel

image.png

试一下安装：

pip isntall dist\buddha-0.1.0-py3-none-any.whl

Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Processing c:\users\administrator\desktop\pylab\dist\buddha-0.1.0-py3-none-any.whl
Installing collected packages: buddha
Successfully installed buddha-0.1.0

我们去PYTHON_HOME看看我们的包被安装到哪里。

image.png

image.png

image.png

image.png

我们的包各种文件都被安装到了我们想要的位置。

试一下命令行调用buddha.bat:

image.png

python里导入buddha模块：

image.png

python里导入single_module模块：

image.png

依赖

命令行

• cmdclass 比较少用到。我们知道setup.py有build install两个子命令，sdist和bdist_wheel也是其子命令。cmdclass可以让我们自己自定义setup.py的子命令。推荐文章《How To Add Custom Build Steps and Commands To setup.py》
• entry_points，某种意义上讲，跟前面的scripts参数很像，其作用就是为了公开一个命令给控制台。

例子：

    entry_points={
        "console_scripts": [
            "print_buddha = buddha:print_buddha",
        ],
        "gui_scripts": [
            "single_module = sindle_module:a_module",
        ]
    }

• print_buddha是要生成的命令名，调用pring_buddha会去执行buddha模块里的print_buddha函数。
• entry_point 格式是 命令名=模块路径（与import路径一致）：函数名。
• 包安装后会在Scripts目录下生成一个print_buddha.exe，这也是为什么我们可以直接在控制台调用print_buddha的原因。
• console_scripts和gui_scripts的区别在于console_scripts下生成的exe调用的时候会用标准输入输出重定向到控制台，用起来就跟用命令一样；而gui_scripts生成的exe则不会重定向到控制台，控制台上调用了什么都不会打印，因此主要用来启动一个gui程序，例如用tkinter写的界面。
• entry_points的作用有两个，当我们的入口函数不是模块的main.py而是某个py文件里的函数的时候，entry_points可以那个函数直接暴露到命令行。另一个作用是公开入口点给其他

压缩选项

更加详细的说明可以去参考官方文档《setuptools documeng: Building and Distributing Packages with Setuptools》

上传包到PyPi

注册PyPi账号

到PyPi官网注册一个账号，通过各种验证通。

上传PyPi

python -m twine upload dist/*

将dist下的tar.gz和whl文件上传到PyPi。

会提示输入用户名密码，照着做就行。

上传成功后就会出现在PyPi和你的项目页里。

更新版本

你无法重新上传覆盖版本，所以如果你的包有bug或者有修改，你必须修改setup.py里的version，然后再打一次包上传。