前言
平时造好的轮子,最后还是有给大家使用的一天。完整的记录一下,如何把Python模块打包成whl(wheel) 文件或者gz压缩文件。打包时会用到setuptools(60.5.0)工具。
目录
一.什么是setuptools?
setuptoolssetuptools是 Python Enterprise Application Kit(PEAK)的一个副项目,是Python distutils增强版的集合,它可以帮助我们更简单的创建和分发Python包,尤其是拥有依赖关系的。Python还可以帮助我们管理第三方依赖包。
setuptools 库中一些常用函数
setup()
setup()
函数是 setuptools 最重要的函数之一,用于定义和配置一个 Python 包的元数据和依赖关系。它接受一系列参数,例如name
、version
、author
、description
等,用于指定包的基本信息和描述。find_packages()
find_packages()
函数用于自动发现并返回当前目录及其子目录下的所有 Python 包。它检查__init__.py
文件来判断目录是否是一个包,可以在setup()
函数的packages
参数中使用。setup_requires()
setup_requires
参数用于指定构建时需要的其他依赖项。这些依赖项会在执行setup()
函数之前被安装。install_requires()
install_requires
参数用于指定运行时需要的其他依赖项。这些依赖项会在用户安装包时自动安装。entry_points()
entry_points
参数用于定义可执行脚本或命令行工具的入口点。可以通过指定不同的分组来配置不同的入口点,例如console_scripts
、gui_scripts
等。extras_require()
extras_require
参数用于定义额外的可选依赖项。这些依赖项可以在安装时通过指定选项的方式安装,例如pip install package[option]
。setup_tools.setup()
setup()
函数的一个别名,使用该函数可以实现与distutils.core.setup()
函数兼容。
二.编写setup.py文件
1.创建一个setup.py文件.
在项目根目录下,创建一个setup.py文件,方便将需要打包的模块找到.
setup.py文件无论打包还是安装都会用到,在setup.py文件中描述清楚这个模块的信息以及依赖项。
2.调用setuptools的setup 方法,参数如下
- name : 打包起来的包的文件名(必填)
- version : 版本号,添加为打包文件的后缀名(必填)
- author : 作者
- author_email : 作者的邮箱
- py_modules : 打包的.py文件
- packages: 一个列表,指定包的名称(相对于当前目录),可以使用
find_packages()
函数自动查找并包含所有包- include_package_data : 项目里会有一些非py文件,比如html和js等,这时候就要靠include_package_data 和 package_data 来指定了。package_data:一般写成{‘your_package_name’: [“files”]}, include_package_data还没完,还需要修改MANIFEST.in文件.MANIFEST.in文件的语法为: include xxx/xxx/xxx/.ini/(所有以.ini结尾的文件,也可以直接指定文件名)
- license : 支持的开源协议
- description : 对项目简短的一个形容
- long
_
description :包的详细描述,通常使用README.md
文件的内容。- ext_modules : 是一个包含Extension实例的列表,Extension的定义也有一些参数。
- ext_package : 定义extension的相对路径
- requires : 定义依赖哪些模块
- provides : 定义可以为哪些模块提供依赖
- data_files :指定其他的一些文件(如配置文件),规定了哪些文件被安装到哪些目录中。如果目录名是相对路径,则是相对于sys.prefix或sys.exec_prefix的路径。如果没有提供模板,会被添加到MANIFEST文件中。
- url 项目的主页 URL
- python_requires 指定运行该包所需的最低 Python 版本
- keywords 包的关键字列表
- classifiers 一个列表,指定包的所属分类标签,如开发状态、许可证、操作系统等
3.代码示例
from setuptools import setup, find_packages
setup(
name="example", # 包名
version="1.0.0", # 版本号
author="Your Name", # 作者名字
author_email="you@example.com", # 作者邮箱
description="A short description of this project", # 描述
long_description="A longer description of this project", # 详细描述
url="https://github.com/yourusername/example", # 主页 URL
packages=find_packages(), # 包列表
install_requires=["numpy", "scipy"], # 运行时依赖关系
classifiers=[
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.7",
"Programming Language :: Python :: 3.8",
"Topic :: Software Development :: Libraries :: Python Modules",
], # 分类标签
)
三.执行打包
3.1.执行打包语句
在set_up.py 文件夹下打开终端,执行set_up.py.
安装包有两种结果 whl文件或者tar.gz文件,可按照自身需求去选择。
3.1.1 打包成 wheel
python setup.py bdist_wheel
执行成功后, 在项目文件夹下,生成dist文件夹
dist文件夹中的whl文件就是打包好的轮子
3.1.2 打包成 xxx-version.tar.gz
python setup.py sdist
3.2.验证
查看打包的模块 wheel 直接将whl改成zip,可以看到被打包的内容
四.安装
4.1安装whl
pip install XXXXX.whl
4.2 安装gz
解压缩gz文档后,打开文件夹,执行setup.py,模块将会被安装到解释器对应的Lib/site-packages目录下。
python setup.py install
总结
在使用 setuptools
库时,以下是一些需要注意的事项
正确安装 setuptools 在使用
setuptools
之前,确保已正确安装了该库。可以通过运行pip install setuptools
命令来安装setuptools
。导入正确的模块:在您的脚本中,确保正确导入所需的
setuptools
模块。通常使用from setuptools import setup, find_packages
来导入所需的函数和类。使用 setup() 函数:核心操作是使用
setup()
函数来配置和定义包的元数据和依赖关系。确保在脚本中调用此函数,并提供适当的参数来设置项目配置。指定包和模块:通过
packages
参数指定要打包的包名称列表,可以使用find_packages()
函数自动查找并包含所有包。如果只需发布单个模块,可以使用py_modules
参数指定单个模块文件。处理依赖关系:使用
install_requires
参数指定项目的运行时依赖项。可以通过字符串列表或从文件中读取的字符串来指定依赖关系。编写 README 文件:建议编写一个名为
README.md
的文件,其中包含项目的详细描述。将long_description
参数设置为README.md
文件的内容,以便在 PyPI 上显示该描述。添加其他元数据:通过使用参数如
author
、author_email
、url
、license
、classifiers
等来提供包的其他元数据信息。构建和发布包:使用
python setup.py sdist bdist_wheel
命令构建软件包,生成源码分发包和二进制 wheel 包。然后可以使用twine
工具将软件包上传到 PyPI 上。其他功能和选项:
setuptools
还提供了其他功能和选项,如定义插件、代码生成、资源管理等。您可以通过参考官方文档和其他教程来了解更多细节。注意版本兼容性:请注意在开发和测试过程中要确保
setuptools
和其他依赖库的版本兼容性。特别是当您升级或切换到新版本时,请留意可能的功能变化或不兼容性。