Packaging a Python project

Packaging 的相关内容/用法

https://packaging.python.org/tutorials/packaging-projects/

https://packaging.python.org/guides/distributing-packages-using-setuptools/

https://packaging.python.org/

 

Packaging 的 tutorial

https://python-packaging.readthedocs.io/en/latest/index.html

 https://python-packaging-tutorial.readthedocs.io/en/latest/setup_py.html

https://blog.ionelmc.ro/2014/05/25/python-packaging/    //这篇blog对于Python project 的 structure 有详细说明

 

开始一个Python package

sampleproject是一个比较好的开始一个python project的template，推荐大家使用它： https://github.com/pypa/sampleproject。

 

Package的基本步骤

1. 准备好代码，以及合理的目录结构

2. 编写配置文件，使用setuptools(或者distutils)一般情况下都是使用setup.py(setup.cfg一般配置setup.py的command相关的参数)，其中的配置项和参数具体参考这里。

3. 打包

python setup.py sdist

python setup.py bdist_wheel //打wheel 包

4. 上传pypi或者私有artifactory 比如Jfrog.

 

Future packaging

传统的打包方式是使用setuptools(distutils)，但是PEP517和PEP518一起引入了新的打包方式。PEP518引入了新的配置文件pyproject.toml， PEP517引入了新的配置项，可以在pyproject.toml中配置打包工具相关内容(比如使用其他打包工具flit)。

 

我在打包过程中的pitfalls

 1. __init__.py 

在__init__.py中尽量保持简洁，不推荐把main()放在__init__.py中（https://github.com/pypa/sampleproject就是这么做的），在__init__.py中可以定义__all__，这样在使用

from pkg import *

的时候，就会import所有定义在__all__中的object，一个例子:

__all__ = [
    "__version__",
    "ClassName1",
    "ClassName2",
    ...
]

如果不指定的话，import *一般不会把package里面的所有内容都import 进来。

另外，在__init__.py中可以定义__version__，这样的话安装好Package之后可以使用pkg.__version__来获取这个包的版本号。比如在使用setuptools_scm自动版本管理时，我们可以在__init__.py中定义如下__version__：

from pkg_resources import get_distribution
__version__ = get_distribution(__name__).version

 

2. __main__.py

在package中的__main__.py中一般放置main()函数的调用或者package主要cli的入口，这样可以让package能够使用'python -m pkg'命令，详细这里。

 

3. version的管理推荐使用setuptools_scm

https://pypi.org/project/setuptools-scm/