1: 简介
每个软件包都需要一个描述软件包的 setup.py 文件。
下面是一个简单软件包的目录结构:
+-- package_name
| |
| +-- __init__.py
|
+-- setup.py
__init__.py 只包含一行 def foo(): return 100。
下面的 setup.py 将定义软件包:
from setuptools import setup
setup(
name='package_name', # package name
version='0.1', # version
description='Package Description', # short description
url='http://example.com', # package URL
install_requires=[], # list of packages this package depends on.
packages=['package_name'], # List of module names that installing this package will provide.
)
virtualenv 是测试软件包安装的好帮手,无需修改其他 Python 环境:
$ virtualenv .virtualenv
...
$ source .virtualenv/bin/activate
$ python setup.py install
running install
...
Installed .../package_name-0.1-....egg
...
$ python
>>> import package_name
>>> package_name.foo()
100
2: 上传到 PyPI
一旦您的 setup.py 功能完善(见上一节),就可以非常容易地将软件包上传到 PyPI。(本节和下节内容暂不演示)
设置 .pypirc 文件
该文件存储用于验证账户的登录名和密码。它通常保存在你的主目录中。
# .pypirc file
[distutils]
index-servers =
pypi
pypitest
[pypi]
repository=https://pypi.python.org/pypi
username=your_username
password=your_password
[pypitest]
repository=https://testpypi.python.org/pypi
username=your_username
password=your_password
使用 twine 上传软件包更安全,因此请确保安装了 twine。
$ pip install twine
注册并上传到 testpypi(可选)
注意:PyPI 不允许覆盖已上传的软件包,因此最好先在专用测试服务器(如 testpypi)上测试你的部署。我们将讨论这一选项。在上传之前,考虑对软件包进行版本控制,例如日历版本控制或语义版本控制。
登录或在 testpypi 创建一个新账户。只有第一次注册时才需要,但多次注册也无妨。
$ python setup.py register -r pypitest
而在软件包的根目录下:
$ twine upload dist/* -r pypitest
现在应该可以通过您的账户访问您的软件包了。
测试
创建一个测试虚拟环境。尝试从 testpypi 或 PyPI 安装你的软件包。
# Using virtualenv
$ mkdir testenv
$ cd testenv
$ virtualenv .virtualenv
...
$ source .virtualenv/bin/activate
\# Test from testpypi
(.virtualenv) pip install --verbose --extra-index-url https://testpypi.python.org/pypi package_name
...
# Or test from PyPI
(.virtualenv) $ pip install package_name
...
(.virtualenv) $ python
Python 3.5.1 (default, Jan 27 2016, 19:16:39)
[GCC 4.2.1 Compatible Apple LLVM 7.0.2 (clang-700.1.81)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import package_name
>>> package_name.foo()
100
如果成功,您的软件包至少是可导入的。在最终上传到 PyPI 之前,您也可以考虑测试一下您的 API。如果你的软件包在测试过程中失败了,不要担心。您仍然可以修复它,重新上传到 testpypi 并再次测试。
注册并上传到 PyPI
确保安装了 twine:
$ pip install twine
Either log in, or create a new account at PyPI.
$ python setup.py register -r pypi
$ twine upload dist/*
就是这样!你的软件包已经上线。
如果发现错误,只需上传新版本的软件包即可。
文档
别忘了至少为你的软件包提供一些文档。PyPi 默认使用 reStructuredText 作为格式化语言。
自述文件
如果您的软件包没有大量的文档,请在 README.rst 文件中加入对其他用户有帮助的内容。文件准备好后,还需要另一个文件来告诉 PyPi 显示它。
创建 setup.cfg 文件,并在其中加入这两行:
[metadata]
description-file = README.rst
请注意,如果您尝试将 Markdown 文件放入您的软件包,PyPi 将把它作为一个纯文本文件来读取,不带任何
格式化。
许可
通常情况下,我们非常欢迎在您的软件包中放入一个 LICENSE.txt 文件,其中包含一个开源许可证,以告诉用户他们是否可以在商业项目中使用您的软件包,或者您的代码是否可以使用他们的许可证。
一些许可证的可读性说明见 TL;DR。
3: 使软件包可执行
如果你的软件包不仅是一个库,而且还有一段代码,在安装软件包后可以作为展示程序或独立应用程序使用,请将这段代码放到 __main__.py 文件中。
把 __main__.py 文件放到 package_name 文件夹中。这样,你就可以直接从控制台运行它了:
python -m package_name
如果没有可用的 __main__.py 文件,软件包将无法使用此命令运行,并将打印此错误信息:
python: 没有名为 package_name.__main__ 的模块;'package_name' 是一个包,不能直接执行。