本篇介绍个人或企业在 GitHub 上发布一个 Python 项目需要了解和注意哪些内容
打包和发布一项都是通过准备一个 setup.py
文件来完成的。假设你的项目目录结构如下:
demo
├── LICENSE
├── README.md
├── MANIFEST.in # 打包时,用来定制化生成 `dist/*.tar.gz` 里的内容
├── demo
│ └── __init__.py
├── setup.py
├── tests
│ └── __init__.py
│ └── __pycache__/
└── docs
使用打包命令 python setup.py sdist bdist_wheel
将会生成在 dist 目录下生成两个文件 demo-1.0.0-py3-none-any.whl
和 demo-1.0.0.tar.gz
.whl
文件是用于执行 pip install dist/demo-1.0.0-py3-none-any.whl
将其安装到 ...\Python38\Lib\site-packages\demo
目录时使用的文件。.tar.gz
是打包后的源代码的存档文件。而 MANIFEST.in
则是用来控制这个文件里到底要有哪些内容。下面例子是如何使用 MANIFEST.in
来定制化生成 dist/*.tar.gz
里的内容。MANIFEST.in
文件内容如下:
include LICENSE
include README.md
include MANIFEST.in
graft demo
graft tests
graft docs
global-exclude __pycache__
global-exclude *.log
global-exclude *.pyc
根据以上文件内容,在使用命令 python setup.py sdist bdist_wheel
生成 demo-1.0.0.tar.gz
文件时会包含 LICENSE
, README.md
, MANIFEST.in
这三个文件,并且还会包含 demo
, tests
, docs
三个目录下的所有文件,最后排除掉所有的 __pycache__
, *.log
, *.pyc
文件。
更多关于 MANIFEST.in
文件的语法请参看 https://packaging.python.org/guides/using-manifest-in/
1. 官方有详细的示例和文档 https://packaging.python.org/tutorials/packaging-projects/ 2. Python sample 项目供你参考 https://github.com/pypa/sampleproject
攒点耐心将上面的链接看完,就完全满足一般项目的发布要求了。
使用 Python 大家都知道可以通过以下命令来下载你要是使用的外部库,Python 有着大量的第三方库,将开源项目发布到 PyPI 上方便用户使用。
pip install xxxx
PyPI 是 The Python Package Index 的缩写,意思是 Python 包索引仓库,用来查找、安装和发布 Python 包。
PyPI 有两个环境
假设你的项目已经完成了,准备要发布到 PyPI 了,执行下面的命令,就可以将项目发布到 PyPI 上了。
rm dist/*
# 生成代码存档 .tar.gz 文件和构建文件 .whl 文件
python setup.py sdist bdist_wheel
# 如果发布到TestPyPI使用以下命令
twine upload --repository testpypi dist/*
# 如果发布到PyPI使用以下命令
twine upload dist/*
Python 内置了 doc 的功能,叫 pydoc
。执行 python -m pydoc
可以看到它有哪些选项和功能。
cd docs
python -m pydoc -w ..\ # 生成全部文档
执行 python -m pydoc -b
可以在本地立即启动一个 web 页面来访问你 ...\Python38\Lib\site-packages\
目录下所有 Libraries 文档。
以 elasticsearch 文档为例
这些本地的 web 文档如何在外网进行访问呢?可以通过 GitHub 有内置的 GitHub Pages 功能,很容易提供一个在线网址。
打开你的 GitHub python 项目设置选项 -> 找到 GitHub Pages -> Source 选择你的分支和路径,保存后就立刻拥有了一个网址。例如:
另外如果是正式版本,在发布还需要注意版本号的选择。
比如一个项目从准备发布到正式发布有四个阶段:Alpha, Beta, 候选发布以及正式发布。假如正式发布的版本号是 1.1.0 版本,根据以下的版本标识的规范:
X.YaN # Alpha release
X.YbN # Beta release
X.YrcN # Release Candidate
X.Y # Final release
得到 Alpha, Beta, 候选发布及正式发布版本分别如下:
Alpha release 版本号是 1.1.0a1, 1.1.0a1, 1.1.0aN...
Beta release 版本号是 1.1.0b1, 1.1.0b1, 1.1.0bN...
Release Candidate 版本号是 1.1.0rc1, 1.1.0rc2, 1.1.0rcN...
Final release 版本号 1.1.0, 1.1.1, 1.1.N...
Python 官方的版本标识和依赖规范文档 https://www.python.org/dev/peps/pep-0440
企业级的项目 License 一般由公司的法律团队来提供,发布者只需拿到 License 文件做一些格式化工作(比如将 license.txt 文件格式化为每行 70~80 个字符)。
如果是个人项目或是想了解开源许可相关的介绍,常见的软件开源许可证(以下许可证是按条件数量排序的)
这里有一篇关于《Github仓库如何选择开源许可证》文章供参考。
1. 如何选项 License https://choosealicense.com/licenses 2. 如何选项 License GitHub 仓库 https://github.com/github/choosealicense.com 3. 如何选项 License 附录 https://choosealicense.com/appendix