打包

一个示例

先直接看个示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# chardet's setup.py
from distutils.core import setup
setup(
    name = "chardet",
    packages = ["chardet"],
    version = "1.0.2",
    description = "Universal encoding detector",
    author = "Mark Pilgrim",
    author_email = "mark@diveintomark.org",
    url = "http://chardet.feedparser.org/",
    download_url = "http://chardet.feedparser.org/download/python3-chardet-1.0.1.tgz",
    keywords = ["encoding", "i18n", "xml"],
    classifiers = [
        "Programming Language :: Python",
        "Programming Language :: Python :: 3",
        "Development Status :: 4 - Beta",
        "Environment :: Other Environment",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)",
        "Operating System :: OS Independent",
        "Topic :: Software Development :: Libraries :: Python Modules",
        "Topic :: Text Processing :: Linguistic",
        ],
    long_description = """\
Universal character encoding detector
-------------------------------------

Detects
 - ASCII, UTF-8, UTF-16 (2 variants), UTF-32 (4 variants)
 - Big5, GB2312, EUC-TW, HZ-GB-2312, ISO-2022-CN (Traditional and Simplified Chinese)
 - EUC-JP, SHIFT_JIS, ISO-2022-JP (Japanese)
 - EUC-KR, ISO-2022-KR (Korean)
 - KOI8-R, MacCyrillic, IBM855, IBM866, ISO-8859-5, windows-1251 (Cyrillic)
 - ISO-8859-2, windows-1250 (Hungarian)
 - ISO-8859-5, windows-1251 (Bulgarian)
 - windows-1252 (English)
 - ISO-8859-7, windows-1253 (Greek)
 - ISO-8859-8, windows-1255 (Visual and Logical Hebrew)
 - TIS-620 (Thai)

This version requires Python 3 or later; a Python 2 version is available separately.
"""
)

目录结构

要开始打包 Python 软件，必须先将文件和目录安排好。例如，chardet 的目录树：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
chardet/
|
+--COPYING.txt
|
+--setup.py
|
+--README.txt
|
+--docs/
|  |
|  +--index.html
|  |
|  +--usage.html
|  |
|  +--images/ ...
|
+--chardet/
   |
   +--__init__.py
   |
   +--big5freq.py
   |
   +--...

说明

  1. 创建根目录来保存所有的目录和文件。将其以 Python 模块的名字命名。
  2. 为了适应 Windows 用户，"自述"文件应包含 .txt 扩展名，而且它应该使用 Windows 风格回车符。不能仅仅因为你使用了一个优秀的文本编辑器，它从命令行运行并包括它自己的宏语言，而需要让你的用户为难。（你的用户使用记事本。虽然可悲，但却是事实。）即使你工作在 Linux 或 Mac OS X 环境下，优秀的文本编辑器毫无疑问地会有一个选项，允许将文件以 Windows 风格回车符来保存。
  3. Distutils 安装脚本应命名为 setup.py。
  4. 如果你的Python软件只包含一个单一的 .py 文件，你应该把它和"自述"文件以及安装脚本放到根目录下。但 chardet 并不是单一的 .py 文件，它是一个多文件模块 。但是没关系！只需在根目录下放置 chardet 目录，这样在 chardet/ 根目录下就会有一个包含 __init__.py 文件的 chardet/ 目录。这并不是一个难题，事实上，它可以简化打包过程。

编写安装脚本

每个 Distutils 安装脚本的第一行总是相同的：

1
from distutils.core import setup

该行导入 setup() 函数，这是 Distutils 的主入口点。大部分 Distutils 安装脚本仅由一个对 setup() 方法的调用组成。

setup() 方法可以有几十个参数 。为了使每个参与者都能清楚，你必须对每个参数使用命名变量 。这不只是一项约定，还是一项硬性要求。如果尝试以非命名变量调用 setup() 方法，安装脚本会崩溃。

下面的命名变量是必需的：

  • name，安装包的名称。
  • version，安装包的版本。
  • author，您的全名。
  • author_email，您的邮件地址。
  • url，项目主页。如果没有一个单独的项目网站，这里可以是安装包的 PyPI 的页面地址。

虽然以下内容不是必须的，但我也建议你把他们包括在你的安装脚本里：

  • description，在线的项目摘要。
  • long_description，以 reStructuredText format 格式编写的多行字符串。PyPI 将其转换为 html 并在安装包中显示它。
  • classifiers，下一节中将讲述的特别格式化字符串。
安装脚本中用到的元数据具体定义在PEP 34中。

现在让我们看看 chardet 的安装脚本。它包含所有这些要求的和建议的参数，还有一个我没有提到： packages 。

1
2
3
4
5
6
7
8
9
from distutils.core import setup
setup(
    name = 'chardet',
    packages = ['chardet'],
    version = '1.0.2',
    description = 'Universal encoding detector',
    author='Mark Pilgrim',
    ...
)

在分发过程中，这个 packages 参数凸显出一个不幸的词汇表重叠。我们一直在谈论正在构建的“安装包”（并将潜在地出现在Python包索引中）。但是，这并不是 packages 参数所指代的。它指代的是 chardet 模块是一个多文件模块这一事实 ，有时也被称为“包”。packages 参数告诉 Distutils 去包含 chardet/ 目录，它的 __init__.py 文件，以及所有其他构成 chardet 模块的 .py 文件。

将包分类

Python 包索引（“PyPI”）包含成千上万的 Python 库。正确的分类数据将让人们更容易找到你的包。PyPI 让你以类别的形式浏览包 。你甚至可以选择多个类别来缩小搜索范围。分类不是你可以忽略的不可见的元数据！

你可以通过传递 classifiers 参数给 Distutils 的 setup() 方法来给你的软件分类。classifers 参数是一个字符串列表。这些字符串不是任意形式的。所有的分类字符串应该来自 PyPI 上的列表 。

你应该总是至少包括以下分类：

  • 编程语言。特别的，你应该包括"Programming Language :: Python"和"Programming Language :: Python :: 3"。如果你不包括这些，你的包将不会出现在兼容Python 3的库列表中，它链接自每个pypi.python.org单页的侧边拦。
  • 许可证. 当我评价一个第三方库的时候，这绝对是我寻找的第一个东西。不要让我（花太多时间）寻找这个重要的信息。不要包含一个以上的许可证分类，除非你的软件明确地在多许可证下分发。（不要在多许可证下发布你的软件，除非你不得不这样做。不要强迫别人这样做。许可证已经足够让人头痛了，不要使情况变得更糟。）
  • 操作系统. 如果你的软件只能运行于Windows（或Mac OS X或Linux），我想要尽早知道。如果你的软件不包含任何特定平台的代码并可以在任何平台运行，请使用分类 “Operating System :: OS Independent”。多操作系统 分类仅在你的软件在不同平台需要特别支持时使用。（这并不常见。）

还建议你包括以下分类：

  • 开发状态. 你的软件品质适合beta发布么？适合Alpha发布么？还是Pre-alpha？在这里面选择一个吧。要诚实点。
  • 目标用户. 谁会下载你的软件？最常见的选项包括： Developers、 End Users/Desktop、 Science/Research 和 System Administrators。
  • 框架. 如果你的软件是像 Django 或 Zope 这样较大的框架的插件，请包含适当的 Framework 分类。如果不是，请忽略它。
  • 主题. 有 大量的主题 可供选择 ，选择所有的适用项。

示例

Django 的分类：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Categories
    Development Status :: 5 - Production/Stable
    Environment :: Web Environment
    Framework :: Django
    Intended Audience :: Developers
    License :: OSI Approved :: BSD License
    Operating System :: OS Independent
    Programming Language :: Python
    Programming Language :: Python :: 2.6
    Programming Language :: Python :: 2.7
    Programming Language :: Python :: 3.2
    Programming Language :: Python :: 3.3
    Topic :: Internet :: WWW/HTTP
    Topic :: Internet :: WWW/HTTP :: Dynamic Content
    Topic :: Internet :: WWW/HTTP :: WSGI
    Topic :: Software Development :: Libraries :: Application Frameworks
    Topic :: Software Development :: Libraries :: Python Modules

通过清单指定附加文件

默认情况下，Distutils 将把下列文件包含在你的发布包中：

  • README.txt
  • setup.py
  • 由列在 packages 参数中的多模块文件所需的 .py 文件
  • 在 py_modules 参数中列出的单独 .py 文件

但对于 chardet 项目，我们还希望包含 COPYING.txt 许可文件和含有图像与 html 文件的整个 docs/ 目录。要让 Distutils 在构建 chardet 发布包时包含这些额外的文件和目录，你需要创建一个 manifest file 。

清单文件是一个名为 MANIFEST.in 的文本文件。将它放置在项目的根目录下，同 README.txt 和 setup.py 一起。清单文件并不是 Python 脚本，它是文本文件，其中包含一系列 Distutils 定义格式的命令。清单命令允许你包含或排除特定的文件和目录。

以下是 chardet 项目的全部清单文件：

1
2
include COPYING.txt                            
recursive-include docs *.html *.css *.png *.gif
  • 第一行是不言自明的：包含项目根目录的 COPYING.txt 文件。
  • 第二行有些复杂。recursive-include 命令需要一个目录名和至少一个文件名。文件名并不限于特定的文件，可以包含通配符。这行的意思是“看到在项目根目录下的 docs/ 目录了吗？在该目录下（递归地）查找 .html、 .css、 .png 和 .gif 文件。我希望将他们都包含在我的发布包中。”
清单文件有自己独特的格式。详见 分发指定文件 和 清单文件命令 。

检查安装脚本的错误

有许多事情需要留意。Distutils带有一个内置的验证命令，它检查是否所有必须的元数据都体现在你的安装脚本中。例如，如果你忘记包含 version 参数，Distutils 会提醒你。

1
2
3
c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py check
running check
warning: check: missing required meta-data: version

当你包含了 version 参数（和所有其他所需的元数据）时， check 命令将如下所示：

1
2
c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py check
running check

创建发布源

Distutils 支持构建多种类型的发布包。至少，你应该建立一个“源代码分发”，其中包含源代码，你的Distutils 安装脚本，“Readme”文件和你想要包含其他文件 。为了建立一个源代码分发，传递 sdist 命令给你的 Distutils 安装脚本。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py sdist
running sdist
running check
reading manifest template 'MANIFEST.in'
writing manifest file 'MANIFEST'
creating chardet-1.0.2
creating chardet-1.0.2\chardet
creating chardet-1.0.2\docs
creating chardet-1.0.2\docs\images
copying files to chardet-1.0.2...
copying COPYING -> chardet-1.0.2
copying README.txt -> chardet-1.0.2
copying setup.py -> chardet-1.0.2
copying chardet\__init__.py -> chardet-1.0.2\chardet
copying chardet\big5freq.py -> chardet-1.0.2\chardet
...
copying chardet\universaldetector.py -> chardet-1.0.2\chardet
copying chardet\utf8prober.py -> chardet-1.0.2\chardet
copying docs\faq.html -> chardet-1.0.2\docs
copying docs\history.html -> chardet-1.0.2\docs
copying docs\how-it-works.html -> chardet-1.0.2\docs
copying docs\index.html -> chardet-1.0.2\docs
copying docs\license.html -> chardet-1.0.2\docs
copying docs\supported-encodings.html -> chardet-1.0.2\docs
copying docs\usage.html -> chardet-1.0.2\docs
copying docs\images\caution.png -> chardet-1.0.2\docs\images
copying docs\images\important.png -> chardet-1.0.2\docs\images
copying docs\images\note.png -> chardet-1.0.2\docs\images
copying docs\images\permalink.gif -> chardet-1.0.2\docs\images
copying docs\images\tip.png -> chardet-1.0.2\docs\images
copying docs\images\warning.png -> chardet-1.0.2\docs\images
creating dist
creating 'dist\chardet-1.0.2.zip' and adding 'chardet-1.0.2' to it
adding 'chardet-1.0.2\COPYING'
adding 'chardet-1.0.2\PKG-INFO'
adding 'chardet-1.0.2\README.txt'
adding 'chardet-1.0.2\setup.py'
adding 'chardet-1.0.2\chardet\big5freq.py'
adding 'chardet-1.0.2\chardet\big5prober.py'
...
adding 'chardet-1.0.2\chardet\universaldetector.py'
adding 'chardet-1.0.2\chardet\utf8prober.py'
adding 'chardet-1.0.2\chardet\__init__.py'
adding 'chardet-1.0.2\docs\faq.html'
adding 'chardet-1.0.2\docs\history.html'
adding 'chardet-1.0.2\docs\how-it-works.html'
adding 'chardet-1.0.2\docs\index.html'
adding 'chardet-1.0.2\docs\license.html'
adding 'chardet-1.0.2\docs\supported-encodings.html'
adding 'chardet-1.0.2\docs\usage.html'
adding 'chardet-1.0.2\docs\images\caution.png'
adding 'chardet-1.0.2\docs\images\important.png'
adding 'chardet-1.0.2\docs\images\note.png'
adding 'chardet-1.0.2\docs\images\permalink.gif'
adding 'chardet-1.0.2\docs\images\tip.png'
adding 'chardet-1.0.2\docs\images\warning.png'
removing 'chardet-1.0.2' (and everything under it)

有几件事情需要注意：

  • Distutils发现了清单文件( MANIFEST.in )
  • Distutils 成功地解析了清单文件，并添加了我们所需要的文件—— COPYING.txt 和在 docs/ 目录下的 html 与图像文件。
  • 如果你进入你的项目目录，你会看到 Distutils 创建了一个 dist/ 目录。你可以分发在 dist/ 目录中的 .zip 文件。
1
2
3
4
5
6
7
8
9
10
11
c:\Users\pilgrim\chardet> dir dist
 Volume in drive C has no label.
 Volume Serial Number is DED5-B4F8

 Directory of c:\Users\pilgrim\chardet\dist

07/30/2009  06:29 PM    <DIR>          .
07/30/2009  06:29 PM    <DIR>          ..
07/30/2009  06:29 PM           206,440 chardet-1.0.2.zip
               1 File(s)        206,440 bytes
               2 Dir(s)  61,424,635,904 bytes free

创建图形化安装程序

在我看来，每一个 Python 库都应该为 Windows 用户提供图形安装程序。这很容易做（即使你并没有运行 Windows ），而且 Windows 用户会对此表示感激。

通过传递 bdist_wininst 命令到你的 Distutils 安装脚本，它可以为你创建一个图形化的 Windows 安装程序 。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py bdist_wininst
running bdist_wininst
running build
running build_py
creating build
creating build\lib
creating build\lib\chardet
copying chardet\big5freq.py -> build\lib\chardet
copying chardet\big5prober.py -> build\lib\chardet
...
copying chardet\universaldetector.py -> build\lib\chardet
copying chardet\utf8prober.py -> build\lib\chardet
copying chardet\__init__.py -> build\lib\chardet
installing to build\bdist.win32\wininst
running install_lib
creating build\bdist.win32
creating build\bdist.win32\wininst
creating build\bdist.win32\wininst\PURELIB
creating build\bdist.win32\wininst\PURELIB\chardet
copying build\lib\chardet\big5freq.py -> build\bdist.win32\wininst\PURELIB\chardet
copying build\lib\chardet\big5prober.py -> build\bdist.win32\wininst\PURELIB\chardet
...
copying build\lib\chardet\universaldetector.py -> build\bdist.win32\wininst\PURELIB\chardet
copying build\lib\chardet\utf8prober.py -> build\bdist.win32\wininst\PURELIB\chardet
copying build\lib\chardet\__init__.py -> build\bdist.win32\wininst\PURELIB\chardet
running install_egg_info
Writing build\bdist.win32\wininst\PURELIB\chardet-1.0.2-py3.1.egg-info
creating 'c:\users\pilgrim\appdata\local\temp\tmp2f4h7e.zip' and adding '.' to it
adding 'PURELIB\chardet-1.0.2-py3.1.egg-info'
adding 'PURELIB\chardet\big5freq.py'
adding 'PURELIB\chardet\big5prober.py'
...
adding 'PURELIB\chardet\universaldetector.py'
adding 'PURELIB\chardet\utf8prober.py'
adding 'PURELIB\chardet\__init__.py'
removing 'build\bdist.win32\wininst' (and everything under it)
c:\Users\pilgrim\chardet> dir dist
c:\Users\pilgrim\chardet>dir dist
 Volume in drive C has no label.
 Volume Serial Number is AADE-E29F

 Directory of c:\Users\pilgrim\chardet\dist

07/30/2009  10:14 PM    <DIR>          .
07/30/2009  10:14 PM    <DIR>          ..
07/30/2009  10:14 PM           371,236 chardet-1.0.2.win32.exe
07/30/2009  06:29 PM           206,440 chardet-1.0.2.zip
               2 File(s)        577,676 bytes
               2 Dir(s)  61,424,070,656 bytes free

Distutils 也可以帮助你为 Linux 用户构建可安装包 。但这可能不值得你浪费时间。如果你希望在 Linux 中分发你的软件，你最好将时间花在与那些社区成员进行交流上，他们专门为主流 Linux 发行版打包软件。

将软件添加到 Python 安装包列表

上传软件到 Python 包索引需要三个步骤。

  • 注册你自己
  • 注册你的软件
  • 上传你通过 setup.py sdist 和 setup.py bdist_* 创建的包。

要注册自己，访问 PyPI用户注册页面。输入你想要的用户名和密码，提供一个有效的电子邮件地址，然后点击 Register 按钮。（如果你有一个 pgp 或 gpg 密钥，你也可以提供。如果你没有或者不知道这是什么意思，不用担心。）检查你的电子邮件，在几分钟之内，你应该会收到一封来自 PyPI 的包含验证链接的邮件。点击链接以完成注册过程。

现在，你需要在PyPI注册你的软件并上传它。你可以用一步完成。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py register sdist bdist_wininst upload  
running register
We need to know who you are, so please choose either:
 1. use your existing login,
 2. register as a new user,
 3. have the server generate a new password for you (and email it to you), or
 4. quit
Your selection [default 1]:  1                                                                 
Username: MarkPilgrim                                                                          
Password:
Registering chardet to http://pypi.python.org/pypi                                             
Server response (200): OK
running sdist                                                                                  
... output trimmed for brevity ...
running bdist_wininst                                                                          
... output trimmed for brevity ...
running upload                                                                                 
Submitting dist\chardet-1.0.2.zip to http://pypi.python.org/pypi
Server response (200): OK
Submitting dist\chardet-1.0.2.win32.exe to http://pypi.python.org/pypi
Server response (200): OK
I can store your PyPI login so future submissions will be faster.
(the login will be stored in c:\home\.pypirc)
Save your login (y/N)?n

发布新版本

如果你想发布一个新版本，只需以新的版本号更新 setup.py 文件，然后再一次运行相同的上传命令:

1
c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py register sdist bdist_wininst upload

Python 打包工具的一些可能的将来

Python 还存在许多其他的框架，有的重在安装，有的重在测试，还有的重在部署：

以下框架重在安装

Setuptools Pip Distribute

以下框架重在测试和部署

virtualenv zc.buildout Paver Fabric py2exe

深入阅读

通过 Distutils 发布 Python 模块 核心发布功能 列出了 setup() 函数的所有可能参数 Distutils食谱 Python 打包生态系统 关于打包 对 “关于打包” 的几点纠错

Comments

▲