最小的结构¶

让我们来看一小段代码:

def joke():
    return (u'How do you tell HTML from HTML5?'
            u'Try it out in Internet Explorer.'
            u'Does it work?'
            u'No?'
            u'It\'s HTML5.')

这小段代码仅仅是为了展示如何打包和分发Python代码, 没有实际的用途。

选择一个包名¶

Python 模块或者包名应该遵守以下的规则:

全小写
不要和pypi上已有的包名重复，即使你不想公开发布你的包，因为你的包可能作为其他包的依赖包
使用下划线分隔单词或者什么都不用(不要使用连字符)

现在把我们的函数变成一个Python module funniest

开始工作¶

目录结构 funniest 如下:

funniest/
    funniest/
        __init__.py
    setup.py

最外层的目录是我们版本管理工具的根目录, 例如 funniest.git . 子目录也叫 funniest , 代表Python module.

为了更好理解, 我们把函数 joke() 放到 __init__.py 中:

def joke():
    return (u'How do you tell HTML from HTML5?'
            u'Try it out in Internet Explorer.'
            u'Does it work?'
            u'No?'
            u'It\'s HTML5.')

最主要的setup配置文件是 setup.py , 应该包含一行代码调用 setuptools.setup() ,就像下面这样:

from setuptools import setup

setup(name='funniest',
      version='0.1',
      description='The funniest joke in the world',
      url='http://github.com/storborg/funniest',
      author='Flying Circus',
      author_email='flyingcircus@example.com',
      license='MIT',
      packages=['funniest'],
      zip_safe=False)

现在我们可以在本地安装这个python包:

$ python setup.py install

我们也可以使用开发模式安装这个包, 每次修改代码之后不用重新安装, 立即可用最新的代码.:

$ python setup.py develop

不管用哪种方式，安装之后就可以在python中使用这个包:

>>> import funniest
>>> print funniest.joke()

在PyPI上发布¶

脚本 setup.py 也是在PyPI注册和上传源码包的入口.

第一步注册这个包(包括注册包名,上传元数据,创建pypi.python.org的页面):

$ python setup.py register

如果从未在PyPI上发布过东西, 你需要创建一个账号, 命令行向导会一步一步告诉你怎么做.

注册之后你可以在PyPI看到这个包的页面 funniest :

http://pypi.python.org/pypi/funniest/0.1

尽管用户可以根据URL链接找到你的git仓库, 但是为了使用方便我们需要上传一个源码包. 用户不需要clone你的git仓库，而且可以使用安装工具自动化安装和搜索依赖关系.

第二步创建一个源码包:

$ python setup.py sdist

这一步会在你的顶层目录下创建 dist/funniest-0.1.tar.gz . 如果你有时间, 可以把这个文件拷贝到另一台主机上, 解压然后安装, 测试一下安装包.

第三步上传到PyPI:

$ python setup.py sdist upload

你可以把这几步结合起来, 更新元数据, 发布新版本, 一步就完成:

$ python setup.py register sdist upload

想要查看setup.py更多的功能可以看看帮助:

$ python setup.py --help-commands

安装这个包¶

上面的步骤完成之后, 其他用户可以直接用 easy_install 安装:

easy_install funniest

或者使用 pip

$ pip install funniest

如果这包作为其他包的依赖包, 它将被自动安装(我们在后面会提到如何配置)

添加其他文件¶

大部分时间我们的代码分散在多个文件当中,

举个例子, 我们把函数移动到一个新的文件中 text , 现在我们的目录结构是这样子的:

funniest/
    funniest/
        __init__.py
        text.py
    setup.py

__init__.py

from .text import joke

text.py

def joke():
    return (u'How do you tell HTML from HTML5?'
            u'Try it out in Internet Explorer.'
            u'Does it work?'
            u'No?'
            u'It\'s HTML5.')

所有的代码应该都在 funniest/funniest/ 目录下.

忽略的文件 (.gitignore, etc)¶

我们可能需要一个 .gitignore 或者是其他代码管理工具类似的文件, 因为创建包的过程中会产生一下中间文件, 我们并不想提交到代码仓库当中.

下面是一个 .gitignore 的例子:

# Compiled python modules.
*.pyc

# Setuptools distribution folder.
/dist/

# Python egg metadata, regenerated from source files by setuptools.
/*.egg-info

大功告成¶

上面讲的结构已经包含了创建一个包的所有步骤. 如果所有的Python工具和库都遵循同样的规则来打包, 世界会更加美好.

客官别急 下面还有更多内容, 因为大部分的包还需要命令行脚本, 文档, 测试，分析工具等等, 请看下一篇.