本篇介绍个人或企业在 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
下面例子是如何使用 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/
官方有详细的示例和文档 https://packaging.python.org/tutorials/packaging-projects/
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 文档。
这些本地的 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 官方的版本标识和依赖规范文档
企业级的项目 License 一般由公司的法律团队来提供,发布者只需拿到 License 文件做一些格式化工作(比如将 license.txt 文件格式化为每行 70~80 个字符)。
如果是个人项目或是想了解开源许可相关的介绍,常见的软件开源许可证(以下许可证是按条件数量排序的)
这里有一篇关于《Github 仓库如何选择开源许可证》文章供参考。