Skip to main content

安装Python模块(旧版)

Author:

格雷格·沃德

参见

安装Python模块

最新的模块安装文档

本文档从最终用户的角度描述了Python分布实用程序(“Distutils”),描述了如何通过构建和安装第三方Python模块和扩展来扩展标准Python安装的功能。

注解

本指南仅介绍构建和分发作为此版本Python提供的扩展的基本工具。第三方工具提供更易于使用和更安全的替代方案。有关详细信息,请参阅Python包装用户指南中的 快速建议部分

介绍

虽然Python的广泛的标准库涵盖了许多编程需求,但是通常需要一段时间,当你需要以第三方模块的形式为你的Python安装添加一些新的功能。这可能是必要的,以支持您自己的编程,或支持您想要使用的应用程序,并且恰好用Python编写。

在过去,几乎不支持在现有的Python安装中添加第三方模块。随着Python 2.0中的Python Distribution Utilities(简称Distutils)的引入,这个改变了。

本文档主要针对需要安装第三方Python模块的人员:最终用户和系统管理员,只需要运行一些Python应用程序,现有的Python程序员想要在工具箱中添加一些新的好东西。你不需要知道Python来阅读这个文档;将会有一些简单的使用Python的交互模式来探索你的安装,但就是这样。如果您正在寻找有关如何分发您自己的Python模块的信息,以便其他人可以使用它们,请参阅 分发Python模块(旧版) 手册。 调试安装脚本 也可能是感兴趣的。

最佳案例:小型安装

在最好的情况下,有人将准备一个特殊版本的模块分发,你想要安装,专门针对您的平台,并像您的平台上的任何其他软件一样安装。例如,模块开发人员可能为Windows用户提供可执行安装程序,为基于RPM的Linux系统(Red Hat,SuSE,Mandrake和许多其他用户)的用户提供RPM软件包,Debian软件包为基于Debian的Linux系统等。

在这种情况下,您将下载适合您的平台的安装程序,并做明显的事情:运行它,如果它是可执行安装程序,rpm --install 它,如果它是一个RPM等。你不需要运行Python或安装脚本,你不需要编译任何东西—你可能甚至不需要阅读任何指令(虽然它总是一个好主意,这样做反正)。

当然,事情并不总是那么容易。您可能对模块分发感兴趣,但没有为您的平台提供易于使用的安装程序。在这种情况下,您必须从模块的作者/维护者发布的源代码发布开始。从源分发安装不是太难,只要模块以标准方式打包即可。本文档的主要内容是关于从标准源代码发行版构建和安装模块。

新标准:Distutils

如果你下载一个模块源代码发布,你可以很快地告诉它是否以标准方式打包和发布,即使用Distutils。首先,发布商的名称和版本号将显示在已下载的存档名称中,例如 foo-1.0.tar.gzwidget-0.9.7.zip。接下来,归档文件将解压到类似命名的目录中:foo-1.0widget-0.9.7。此外,分发将包含一个设置脚本 setup.py 和一个名为 README.txt 或可能只是 README 的文件,这应该解释,构建和安装模块分发是一个简单的事情,从终端运行一个命令:

python setup.py install

对于Windows,此命令应从命令提示符窗口(Start ‣ Accessories)运行,:

setup.py install

如果所有这些事情都是真的,那么你已经知道如何构建和安装刚刚下载的模块:运行上面的命令。除非你需要以非标准方式安装东西或自定义构建过程,否则你不需要这本手册。或者,上述命令是您需要脱离本手册的一切。

标准构建和安装

新标准:Distutils 部分所述,使用Distutils构建和安装模块分发通常是从终端运行的一个简单命令:

python setup.py install

平台变体

您应该始终从分发根目录(即模块源分发解包到的顶级子目录)运行setup命令。例如,如果你刚刚将模块源代码分发 foo-1.0.tar.gz 下载到Unix系统上,那么正常的做法是:

gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install

在Windows上,您可能会下载 foo-1.0.zip。如果您将归档文件下载到 C:\Temp,则会将其解包到 C:\Temp\foo-1.0 中;您可以使用具有图形用户界面(例如WinZip)的归档操纵器或命令行工具(例如 unzippkunzip)来解压缩归档。然后,打开命令提示符窗口并运行:

cd c:\Temp\foo-1.0
python setup.py install

拆分作业

运行 setup.py install 在一次运行中构建和安装所有模块。如果你喜欢增量工作—特别有用的,如果你想自定义构建过程,或者如果事情出了错误—你可以使用安装脚本一次做一件事。当构建和安装将由不同的用户完成时,这是特别有用的 - 例如,您可能需要构建一个模块分发并交给系统管理员进行安装(或者自己使用超级用户权限)。

例如,您可以在一个步骤中构建一切,然后在第二步中通过调用安装脚本两次安装所有内容:

python setup.py build
python setup.py install

如果这样做,您将注意到,运行 install 命令首先运行 build 命令,在这种情况下—快速地通知它没有任何事情,因为 build 目录中的所有内容都是最新的。

你可能不需要这种能力,如果你所做的是安装从网上下载的模块,经常下来,但它是非常方便的更高级的任务。如果你开始分发你自己的Python模块和扩展,你将自己运行大量的单独的Distutils命令。

建筑如何工作

如上所述,build 命令负责将文件安装到 构建目录 中。默认情况下,这是分布根下的 build;如果你过于关注速度,或者想保持源代码树的原始性,你可以用 --build-base 选项更改构建目录。例如:

python setup.py build --build-base=/path/to/pybuild/foo-1.0

(或者你可以在你的系统或个人Distutils配置文件中永久地使用指令;参见 Distutils配置文件 部分。)通常,这不是必需的。

构建树的默认布局如下:

--- build/ --- lib/
or
--- build/ --- lib.<plat>/
               temp.<plat>/

其中 <plat> 扩展为当前OS/硬件平台和Python版本的简要描述。第一种形式,只有一个 lib 目录,用于“纯模块分发” - 也就是说,模块分发只包括纯Python模块。如果模块分发包含任何扩展(使用C/C++编写的模块),则使用带有两个 <plat> 目录的第二种形式。在这种情况下,temp.plat 目录保存由编译/链接进程生成的,实际上没有安装的临时文件。在任一情况下,lib (或 lib.plat)目录包含将要安装的所有Python模块(纯Python和扩展)。

将来,将添加更多目录来处理Python脚本,文档,二进制可执行文件以及处理安装Python模块和应用程序所需的任何其他操作。

如何安装工作

build 命令运行之后(无论是显式运行还是 install 命令为您运行),install 命令的工作相对简单:它所需要做的就是将 build/lib (或 build/lib.plat)下的所有内容复制到您选择的安装目录。

如果你不选择安装目录—即,如果你只是运行 setup.py install —然后 install 命令安装到第三方Python模块的标准位置。这个位置因平台以及如何构建/安装Python本身而异。在Unix(和Mac OS X,也是基于Unix的)上,它还取决于所安装的模块分发是纯Python还是包含扩展(“非纯”):

平台

标准安装位置

默认值

笔记

Unix(纯)

prefix/lib/pythonX.Y/site-packages

/usr/local/lib/pythonX.Y/site-packages

(1)

Unix(非纯)

exec-prefix/lib/pythonX.Y/site-packages

/usr/local/lib/pythonX.Y/site-packages

(1)

视窗

prefix\Lib\site-packages

C:\PythonXY\Lib\site-packages

(2)

笔记:

  1. 大多数Linux发行版包括Python作为系统的标准部分,因此 prefixexec-prefix 在Linux上通常都是 /usr。如果你在Linux(或任何类Unix系统)上构建Python,默认的 prefixexec-prefix/usr/local

  2. Windows上的默认安装目录是Python 1.6a1,1.5.2和更早版本中的 C:\Program Files\Python

prefixexec-prefix 代表Python安装的目录,它在运行时找到它的库。它们在Windows下总是相同的,在Unix和Mac OS X下通常是相同的。你可以通过在交互模式下运行Python并输入几个简单的命令来了解你的Python安装对 prefixexec-prefix 的使用。在Unix下,只需在shell提示符下键入 python。在Windows下,选择 Start ‣ Programs ‣ Python X.Y ‣ Python (command line)。解释器启动后,您将在提示符下键入Python代码。例如,在我的Linux系统上,我键入以下三个Python语句,并获得如图所示的输出,以找到我的 prefixexec-prefix:

Python 2.4 (#26, Aug  7 2004, 17:19:02)
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.prefix
'/usr'
>>> sys.exec_prefix
'/usr'

本文档中使用了一些其他占位符:X.Y 表示Python的版本,例如 3.2abiflags 将被替换为 sys.abiflags 的值或没有定义ABI标志的平台的空字符串; distname 将替换为正在安装的模块分发的名称。点和大写在路径中很重要;例如,在UNIX上使用 python3.2 的值通常在Windows上使用 Python32

如果您不想将模块安装到标准位置,或者您没有在那里写入的权限,那么您需要阅读 备用安装 部分中关于备用安装的内容。如果要更加自定义安装目录,请参阅自定义安装中的 自定义安装 部分。

备用安装

通常,将模块安装到除了第三方Python模块的标准位置以外的位置是必要的或期望的。例如,在Unix系统上,您可能没有写入标准第三方模块目录的权限。或者,您可能希望尝试一个模块,然后将其作为本地Python安装的标准部分。在升级已经存在的分发包时尤其如此:您希望在实际升级之前确保现有脚本基础仍然与新版本一起使用。

Distutils install 命令旨在简化和无痛地将模块分发安装到备用位置。基本思想是为安装提供基本目录,install 命令在此基本目录下选择一组目录(称为 安装方案)以在其中安装文件。不同平台的详细信息有所不同,因此请阅读以下适用于您的章节。

请注意,各种备用安装方案是相互排斥的:您可以通过 --user--home,或 --prefix--exec-prefix,或 --install-base--install-platbase,但不能从这些组混合。

备用安装:用户方案

此方案旨在为那些没有全局site-packages目录的写入权限或不想安装到其中的用户提供最方便的解决方案。它使用一个简单的选项启用:

python setup.py install --user

文件将安装到 site.USER_BASE 的子目录(以下写为 userbase)中。此方案在同一位置(也称为 site.USER_SITE)安装纯Python模块和扩展模块。以下是UNIX的值,包括Mac OS X:

文件类型

安装目录

模块

userbase/lib/pythonX.Y/site-packages

脚本

userbase/bin

数据

userbase

C标头

userbase/include/pythonX.Yabiflags/distname

下面是在Windows上使用的值:

文件类型

安装目录

模块

userbase\PythonXY\site-packages

脚本

userbase\PythonXY\Scripts

数据

userbase

C标头

userbase\PythonXY\Include\distname

与下面描述的其他方案相比,使用此方案的优点是,用户site-packages目录在 sys.path 中始终包括的正常条件下(更多信息,请参阅 site),这意味着在运行 setup.py 脚本来完成安装。

build_ext 命令还具有一个 --user 选项,用于将 userbase/include 添加到编译器搜索路径中用于头文件,将 userbase/lib 添加到用于库的编译器搜索路径以及用于共享C库(rpath)的运行时搜索路径。

替代安装:home方案

“home方案”背后的理念是,您构建和维护一个个人的Python模块存储。该方案的名称源于Unix上的“home”目录,因为Unix用户使他们的主目录具有类似于 /usr//usr/local/ 的布局是不寻常的。此方案可由任何人使用,无论他们正在安装的操作系统。

安装新的模块分发是很简单的

python setup.py install --home=<dir>

在那里你可以提供任何你喜欢的 --home 选项的目录。在Unix上,延迟打字员只需键入一个波浪号(~); install 命令会将其扩展到您的主目录:

python setup.py install --home=~

要使Python查找使用此方案安装的发行版,您可能需要 修改Python的搜索路径 或编辑 sitecustomize (请参阅 site)调用 site.addsitedir() 或编辑 sys.path

--home 选项定义安装基本目录。文件安装到安装基础下的以下目录中,如下所示:

文件类型

安装目录

模块

home/lib/python

脚本

home/bin

数据

home

C标头

home/include/python/distname

(如果您在Windows上,则用斜杠替换斜杠。)

备用安装:Unix(前缀方案)

当您希望使用一个Python安装来执行构建/安装(即运行安装脚本),而是将模块安装到另一个Python安装的第三方模块目录中时,“前缀方案”非常有用看起来像一个不同的Python安装)。如果这听起来很奇怪,那就是—这就是为什么用户和家庭计划来之前。然而,存在至少两种已知的情况,其中前缀方案将是有用的。

首先,考虑许多Linux发行版将Python放在 /usr 中,而不是更传统的 /usr/local。这是完全合适的,因为在这些情况下,Python是“系统”的一部分,而不是本地附加组件。但是,如果您从源代码安装Python模块,您可能希望它们使用 /usr/local/lib/python2.X 而不是 /usr/lib/python2.X。这可以用

/usr/bin/python setup.py install --prefix=/usr/local

另一种可能性是网络文件系统,其中用于写入远程目录的名称与用于读取远程目录的名称不同:例如,作为 /usr/local/bin/python 访问的Python解释器可能搜索 /usr/local/lib/python2.X 中的模块,但是这些模块必须安装例如,/mnt/@server/export/lib/python2.X。这可以用

/usr/local/bin/python setup.py install --prefix=/mnt/@server/export

在任一情况下,--prefix 选项定义安装基础,--exec-prefix 选项定义平台特定的安装基础,用于平台特定的文件。 (目前,这只是指非纯模块分发,但可以扩展到C库,二进制可执行文件等)。如果没有提供 --exec-prefix,它默认为 --prefix。文件安装如下:

文件类型

安装目录

Python模块

prefix/lib/pythonX.Y/site-packages

扩展模块

exec-prefix/lib/pythonX.Y/site-packages

脚本

prefix/bin

数据

prefix

C标头

prefix/include/pythonX.Yabiflags/distname

没有要求 --prefix--exec-prefix 实际指向一个替代的Python安装;如果上面列出的目录不存在,则在安装时创建它们。

顺便说一下,前缀方案很重要的真正原因是标准的Unix安装使用前缀方案,但是由AICG和 --exec-prefix 提供的 --prefix--exec-prefix 作为 sys.prefixsys.exec_prefix。因此,你可能认为你永远不会使用前缀方案,但每次运行 python setup.py install 没有任何其他选项,你使用它。

请注意,安装扩展到备用Python安装不会影响这些扩展的构建:特别是,用于运行安装脚本的Python解释器安装的Python头文件(Python.h 和朋友)将用于编译扩展。您有责任确保用于运行以这种方式安装的扩展的解释器与用于构建它们的解释器兼容。执行此操作的最佳方法是确保两个解释器是相同版本的Python(可能是不同的构建,或者可能是相同构建的副本)。 (当然,如果你的 --prefix--exec-prefix 甚至不指向一个替代的Python安装,这是无关紧要的。)

备用安装:Windows(前缀方案)

Windows没有用户主目录的概念,并且由于在Windows下的标准Python安装比在Unix下更简单,因此 --prefix 选项传统上被用于在Windows上的单独位置安装附加软件包。

python setup.py install --prefix="\Temp\Python"

将模块安装到当前驱动器上的 \Temp\Python 目录。

安装基础由 --prefix 选项定义;在Windows下不支持 --exec-prefix 选项,这意味着纯Python模块和扩展模块安装在同一位置。文件安装如下:

文件类型

安装目录

模块

prefix\Lib\site-packages

脚本

prefix\Scripts

数据

prefix

C标头

prefix\Include\distname

自定义安装

有时,备用安装 部分中描述的替代安装方案不能满足您的要求。您可能希望只调整一个或两个目录,同时将所有内容保留在同一基本目录下,或者您可能希望完全重新定义安装方案。无论在哪种情况下,您都在创建 定制安装方案

要创建自定义安装方案,请从其中一个备用方案开始,并使用以下选项覆盖用于各种类型文件的某些安装目录:

文件类型

覆盖选项

Python模块

--install-purelib

扩展模块

--install-platlib

所有模块

--install-lib

脚本

--install-scripts

数据

--install-data

C标头

--install-headers

这些覆盖选项可以是相对的,绝对的,或者根据一个安装基本目录显式定义。 (有两个安装基本目录,它们通常是相同的 - 它们仅在使用Unix“前缀方案”时提供不同,并提供不同的 --prefix--exec-prefix 选项;使用 --install-lib 将覆盖为 --install-purelib--install-platlib 计算或给定的值,并且推荐用于不会在Python和扩展模块之间产生差异的方案。)

例如,假设您在Unix下将模块分发到您的主目录 - 但是您希望脚本进入 ~/scripts 而不是 ~/bin。如您所料,您可以使用 --install-scripts 选项覆盖此目录;在这种情况下,提供相对路径是最有意义的,相对路径将相对于安装基本目录(在这种情况下是您的主目录):

python setup.py install --home=~ --install-scripts=scripts

另一个Unix示例:假设您的Python安装是用 /usr/local/python 的前缀构建和安装的,因此在标准安装下,脚本将在 /usr/local/python/bin 中结束。如果你希望它们在 /usr/local/bin,你将提供这个绝对目录为 --install-scripts 选项:

python setup.py install --install-scripts=/usr/local/bin

(这使用“前缀方案”执行安装,其中前缀是任何您的Python解释器安装与此 /usr/local/python 在这种情况下。)

如果你在Windows上维护Python,你可能希望第三方模块存在于 prefix 的子目录中,而不是在 prefix 本身。这几乎和定制脚本安装目录一样简单 - 你只需要记住有两种类型的模块需要担心,Python和扩展模块,它们可以方便地由一个选项控制:

python setup.py install --install-lib=Site

指定的安装目录是相对于 prefix。当然,你还必须确保这个目录在Python的模块搜索路径中,例如通过将 .pth 文件放在网站目录中(参见 site)。参见第 修改Python的搜索路径 节了解如何修改Python的搜索路径。

如果要定义整个安装方案,则只需提供所有安装目录选项。推荐的方法是提供相对路径;例如,如果要在主目录中的 python 下维护所有与Python模块相关的文件,并且希望为使用主目录的每个平台提供单独的目录,则可以定义以下安装方案:

python setup.py install --home=~ \
                        --install-purelib=python/lib \
                        --install-platlib=python/lib.$PLAT \
                        --install-scripts=python/scripts
                        --install-data=python/data

或者,等同地,

python setup.py install --home=~/python \
                        --install-purelib=lib \
                        --install-platlib='lib.$PLAT' \
                        --install-scripts=scripts
                        --install-data=data

$PLAT 不是(必然)一个环境变量—它将被Distutils扩展,因为它解析您的命令行选项,就像解析配置文件时一样。

显然,每次安装新的模块分发时指定整个安装方案将是非常乏味的。因此,您可以将这些选项放入您的Distutils配置文件(请参阅 Distutils配置文件 部分):

[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data

或者,等同地,

[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data

请注意,如果在运行安装脚本时提供不同的安装基本目录,这两个是 not 等效的。例如,

python setup.py install --install-base=/tmp

将在第一种情况下向 /tmp/python/lib 安装纯模块,在第二种情况下向 /tmp/lib 安装纯模块。 (对于第二种情况,您可能想要提供 /tmp/python 的安装基础。)

您可能注意到在示例配置文件输入中使用 $HOME$PLAT。这些是Distutils配置变量,它们与环境变量具有很强的相似性。实际上,您可以在具有这种概念的平台上的配置文件中使用环境变量,但Distutils还定义了一些可能不在您的环境中的额外变量,例如 $PLAT。 (当然,在没有环境变量的系统上,例如Mac OS 9,Distutils提供的配置变量是唯一可以使用的配置变量。)有关详细信息,请参见第 Distutils配置文件 节。

注解

激活 虚拟环境 时,将更改所有distutils配置文件的任何更改安装路径的选项都将被忽略,以防止无意中在虚拟环境之外安装项目。

修改Python的搜索路径

当Python解释器执行 import 语句时,它将沿着搜索路径搜索Python代码和扩展模块。在构建解释器时,将路径的默认值配置为Python二进制文件。您可以通过导入 sys 模块并打印 sys.path 的值来确定路径。

$ python
Python 2.2 (#11, Oct  3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
 '/usr/local/lib/python2.3/site-packages']
>>>

sys.path 中的空字符串表示当前工作目录。

本地安装的包的预期约定是将它们放在 .../site-packages/ 目录中,但您可能想要将Python模块安装到某个任意目录中。例如,您的网站可能会保留所有与Web服务器相关的软件在 /www 下的约定。加载Python模块可能属于 /www/python,为了导入它们,必须将该目录添加到 sys.path。有几种不同的方式添加目录。

最方便的方法是将路径配置文件添加到Python路径上的目录,通常是 .../site-packages/ 目录。路径配置文件的扩展名为 .pth,每行必须包含一个将附加到 sys.path 的路径。 (因为新的路径追加到 sys.path,在添加的目录模块将不会覆盖标准模块。这意味着你不能使用这种机制用于安装的标准模块固定版本)。

路径可以是绝对路径或相对路径,在这种情况下,它们相对于包含 .pth 文件的目录。有关详细信息,请参阅 site 模块的文档。

一个稍微不太方便的方法是在Python的标准库中编辑 site.py 文件,并修改 sys.path。当执行Python解释器时,将自动导入 site.py,除非提供 -S 开关来抑制此行为。所以你可以简单地编辑 site.py 并添加两行:

import sys
sys.path.append('/www/python/')

然而,如果你重新安装相同的主要版本的Python(也许当从2.2升级到2.2.2,例如) site.py 将被股票版本覆盖。你必须记住它在修改和保存副本,然后再进行安装。

有两个环境变量可以修改 sys.pathPYTHONHOME 为Python安装的前缀设置一个备用值。例如,如果 PYTHONHOME 设置为 /www/python,则搜索路径将设置为 ['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...]

PYTHONPATH 变量可以设置为将添加到 sys.path 开头的路径列表。例如,如果 PYTHONPATH 设置为 /www/python:/opt/py,搜索路径将以 ['/www/python', '/opt/py'] 开头。 (请注意,目录必须存在才能添加到 sys.pathsite 模块删除不存在的路径。)

最后,sys.path 只是一个普通的Python列表,所以任何Python应用程序都可以通过添加或删除条目来修改它。

Distutils配置文件

如上所述,您可以使用Distutils配置文件记录任何Distutils选项的个人或站点首选项。也就是说,任何命令的任何选项都可以存储在两个或三个(取决于您的平台)配置文件之一中,在命令行被解析之前将参考它。这意味着配置文件将覆盖默认值,命令行将依次覆盖配置文件。此外,如果应用多个配置文件,“较早”文件的值将被“较晚”文件覆盖。

配置文件的位置和名称

配置文件的名称和位置在各平台之间略有不同。在Unix和Mac OS X上,三个配置文件(按照它们的处理顺序)是:

文件类型

位置和文件名

笔记

系统

prefix/lib/pythonver/distutils/distutils.cfg

(1)

个人

$HOME/.pydistutils.cfg

(2)

本地

setup.cfg

(3)

而在Windows上,配置文件是:

文件类型

位置和文件名

笔记

系统

prefix\Lib\distutils\distutils.cfg

(4)

个人

%HOME%\pydistutils.cfg

(5)

本地

setup.cfg

(3)

在所有平台上,可以通过传递 –no-user-cfg 选项临时禁用“个人”文件。

笔记:

  1. 严格地说,系统范围的配置文件位于安装Distutils的目录中;在Python 1.6和更高版本的Unix上,如下所示。对于Python 1.5.2,Distutils通常会安装到 prefix/lib/python1.5/site-packages/distutils,因此系统配置文件应该放在Python 1.5.2下。

  2. 在Unix上,如果未定义 HOME 环境变量,则将使用来自标准 pwd 模块的 getpwuid() 函数确定用户的主目录。这是由Distutils使用的 os.path.expanduser() 函数完成的。

  3. 即,在当前目录(通常是安装脚本的位置)。

  4. 在Python 1.6和更高版本中,Python的默认“安装前缀”是 C:\Python,因此系统配置文件通常是 C:\Python\Lib\distutils\distutils.cfg。在Python 1.5.2下,默认前缀是 C:\Program Files\Python,Distutils不是标准库的一部分,因此系统配置文件将是在Windows下的标准Python 1.5.2安装中的 C:\Program Files\Python\distutils\distutils.cfg

  5. 在Windows上,如果未定义 HOME 环境变量,则将尝试 USERPROFILE,然后尝试 HOMEDRIVEHOMEPATH。这是由Distutils使用的 os.path.expanduser() 函数完成的。

配置文件的语法

Distutils配置文件都具有相同的语法。配置文件分为几个部分。每个Distutils命令都有一个部分,另外还有一个用于影响每个命令的全局选项的 global 部分。每个部分每行包含一个选项,指定为 option=value

例如,以下是一个完整的配置文件,只是强制所有命令默认运行静默:

[global]
verbose=0

如果这是作为系统配置文件安装,它将影响当前系统上任何用户对任何Python模块分发的所有处理。如果将其作为个人配置文件(在支持它们的系统上)安装,它将仅影响由您处理的模块分发。如果它用作特定模块分布的 setup.cfg,则它仅影响该分布。

您可以覆盖默认的“构建基础”目录,并使 build* 命令始终强制重建所有文件与以下:

[build]
build-base=blib
force=1

它对应于命令行参数

python setup.py build --build-base=blib --force

除了在命令行上包括 build 命令意味着将运行该命令。在配置文件中包含特定的命令没有这样的含义;它只意味着如果命令运行,配置文件中的选项将适用。 (或者如果运行从其派生值的其他命令,它们将使用配置文件中的值。)

您可以使用 --help 选项找到任何命令的完整选项列表,例如:

python setup.py build --help

并且您可以通过使用 --help 而不使用命令找到全局选项的完整列表:

python setup.py --help

另请参见“分发Python模块”手册的“参考”部分。

建筑扩展:提示和技巧

只要有可能,Distutils就会尝试使用用于运行 setup.py 脚本的Python解释器提供的配置信息。例如,用于编译Python的相同编译器和链接器标志也将用于编译扩展。通常这将工作很好,但在复杂的情况下,这可能是不合适的。本节讨论如何覆盖通常的Distutils行为。

调整编译器/链接器标志

编译使用C或C++编写的Python扩展有时需要为编译器和链接器指定自定义标志,以便使用特定库或生成特殊类型的目标代码。如果扩展没有在你的平台上测试,或者如果你试图交叉编译Python,这是特别真实的。

在最一般的情况下,扩展作者可能预见编译扩展将是复杂的,并提供了一个 Setup 文件供您编辑。这可能只有在模块分发包含许多单独的扩展模块时,或者如果它们经常需要精心设置的编译器标志才能工作。

Setup 文件(如果存在)将被解析,以便获取要构建的扩展的列表。 Setup 中的每一行描述单个模块。线具有以下结构:

module ... [sourcefile ...] [cpparg ...] [library ...]

让我们依次检查每个字段。

  • module 是要构建的扩展模块的名称,应该是有效的Python标识符。你不能只是改变它为了重命名一个模块(编辑源代码也将需要),所以这应该被孤立。

  • sourcefile 是任何可能是源代码文件,至少由文件名判断。假设以 .c 结尾的文件名以C结尾,以 .C 结尾的文件名,.cc.c++ 假定为C++,以 .m.mm 结尾的文件名假定为目标C.

  • cpparg 是C预处理器的参数,并且是以 -I-D-U-C 开头的任何参数。

  • library 是以 .a 结尾或以 -l-L 开头的任何结果。

如果特定平台需要您的平台上的特殊库,您可以通过编辑 Setup 文件并运行 python setup.py build 来添加它。例如,如果模块由行定义

foo foomodule.c

必须与您的平台上的数学库 libm.a 相关联,只需将 -lm 添加到该行:

foo foomodule.c -lm

用于编译器或链接器的任意开关可以与 -Xcompiler arg-Xlinker arg 选项一起提供:

foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm

-Xcompiler-Xlinker 之后的下一个选项将附加到正确的命令行,因此在上面的示例中,编译器将传递 -o32 选项,并且链接器将通过 -shared。如果编译器选项需要参数,则必须提供多个 -Xcompiler 选项;例如,为了通过 -x c++Setup 文件将必须包含 -Xcompiler -x -Xcompiler c++

也可以通过设置 CFLAGS 环境变量来提供编译器标志。如果设置,CFLAGS 的内容将被添加到 Setup 文件中指定的编译器标志。

在Windows上使用非Microsoft编译器

Borland/CodeGear C++

本小节描述了在Borland C++编译器版本5.5中使用Distutils的必要步骤。首先你必须知道Borland的目标文件格式(OMF)与Python版本使用的格式不同,可以从Python或ActiveState网站下载。 (Python是用Microsoft Visual C++构建的,它使用COFF作为目标文件格式。)因此,您必须将Python的库 python25.lib 转换为Borland格式。您可以执行以下操作:

coff2omf python25.lib python25_bcpp.lib

coff2omf 程序自带Borland编译器。文件 python25.lib 位于Python安装的 Libs 目录中。如果你的扩展使用其他库(zlib,...),你必须转换它们。

转换的文件必须位于与普通库相同的目录中。

Distutils如何使用这些库改变名称?如果扩展需要一个库(例如 foo),Distutils首先检查它是否找到一个后缀为 _bcpp 的库(例如 foo_bcpp.lib),然后使用这个库。在没有找到这样的特殊库的情况下,它使用默认名称(foo.lib。) [1]

要让Distutils用Borland C++编译你的扩展,你现在必须键入:

python setup.py build --compiler=bcpp

如果要使用Borland C++编译器作为默认值,可以在个人或系统范围的Distutils配置文件中指定(见 Distutils配置文件 章节)。

参见

C++ Builder编译器

有关Borland的免费C++编译器的信息,包括指向下载页面的链接。

使用Borland的免费编译器创建Python扩展

文档描述如何使用Borland的免费命令行C++编译器来构建Python。

GNU C / Cygwin / MinGW

本节介绍在Cygwin和MinGW发行版中使用带有GNU C/C++编译器的Distutils的必要步骤。 [2] 对于使用Cygwin构建的Python解释器,一切都应该工作,没有任何以下这些步骤。

不是所有的扩展都可以用MinGW或Cygwin来构建,但很多都可以。最可能无法工作的扩展是那些使用C++或依赖于Microsoft Visual C扩展。

要让Distutils用Cygwin编译你的扩展,你必须键入:

python setup.py build --compiler=cygwin

和Cygwin在无cygwin模式 [3] 或MinGW类型:

python setup.py build --compiler=mingw32

如果要使用任何这些选项/编译器作为默认值,您应该考虑将它写入您的个人或系统范围的Distutils配置文件(参见 Distutils配置文件 章节)

旧版本的Python和MinGW

以下说明仅适用于使用低于2.4.1的MinGW低于3.0.0(使用binutils-2.13.90-20030111-1)的Python版本。

这些编译器需要一些特殊的库。这个任务比Borland的C++更复杂,因为没有程序来转换库。首先,你必须创建Python DLL导出的符号列表。 (你可以在 https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/ 找到一个很好的这个任务的程序)。

pexports python25.dll >python25.def

已安装的 python25.dll 的位置将取决于安装选项以及Windows的版本和语言。在“只为我”安装,它将显示在安装目录的根目录。在共享安装中,它将位于系统目录中。

然后,您可以从这些信息创建gcc的导入库。

/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a

结果库必须放置在与 python25.lib 相同的目录中。 (应该是你的Python安装目录下的 libs 目录。)

如果你的扩展使用其他库(zlib,...),你可能需要转换它们。转换的文件必须驻留在与普通库相同的目录中。

参见

使用MinGW在MS Windows平台上构建Python模块

有关构建MinGW环境所需的库的信息。

脚注

[1]

这也意味着您可以用相同名称的OMF库替换所有现有的COFF库。

[2]

查看 https://www.sourceware.org/cygwin/http://www.mingw.org/ 了解更多信息

[3]

然后你没有POSIX仿真可用,但你也不需要 cygwin1.dll