Files
hustoj/web/python-docs/distutils/introduction.html
2025-03-09 17:10:56 +08:00

374 lines
24 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>1. Distutils 模块介绍 &#8212; Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script src="../_static/translations.js"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="在 Python 3.8.20 文档 中搜索"
href="../_static/opensearch.xml"/>
<link rel="author" title="关于这些文档" href="../about.html" />
<link rel="index" title="索引" href="../genindex.html" />
<link rel="search" title="搜索" href="../search.html" />
<link rel="copyright" title="版权所有" href="../copyright.html" />
<link rel="next" title="2. 编写安装脚本" href="setupscript.html" />
<link rel="prev" title="分发 Python 模块(遗留版本)" href="index.html" />
<link rel="canonical" href="https://docs.python.org/3/distutils/introduction.html" />
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<nav class="nav-content" role="navigation">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Logo"/>
</a>
<div class="version_switcher_placeholder"></div>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero"
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
</svg>
<input type="text" name="q" aria-label="快速搜索"/>
<input type="submit" value="转向"/>
</form>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<h3><a href="../contents.html">目录</a></h3>
<ul>
<li><a class="reference internal" href="#">1. Distutils 模块介绍</a><ul>
<li><a class="reference internal" href="#concepts-terminology">1.1. 概念和术语</a></li>
<li><a class="reference internal" href="#a-simple-example">1.2. 一个简单的例子</a></li>
<li><a class="reference internal" href="#general-python-terminology">1.3. 通用的 Python 术语</a></li>
<li><a class="reference internal" href="#distutils-specific-terminology">1.4. Distutils 特定的术语</a></li>
</ul>
</li>
</ul>
<h4>上一个主题</h4>
<p class="topless"><a href="index.html"
title="上一章">分发 Python 模块(遗留版本)</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="setupscript.html"
title="下一章"><span class="section-number">2. </span>编写安装脚本</a></p>
<div role="note" aria-label="source link">
<h3>本页</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">报告 Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.8/Doc/distutils/introduction.rst"
rel="nofollow">显示源代码
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
这个文档所针对的是一个已不再受支持的 Python 旧版本。
你应当升级版本,并阅读
<a href="/3/distutils/introduction.html"> Python 当前稳定版本的文档</a>.
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>导航</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="总目录"
accesskey="I">索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模块索引"
>模块</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. 编写安装脚本"
accesskey="N">下一页</a> |</li>
<li class="right" >
<a href="index.html" title="分发 Python 模块(遗留版本)"
accesskey="P">上一页</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.8.20 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">分发 Python 模块(遗留版本)</a> &#187;</li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
<input type="submit" value="转向" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="an-introduction-to-distutils">
<span id="distutils-intro"></span><h1><span class="section-number">1. </span>Distutils 模块介绍<a class="headerlink" href="#an-introduction-to-distutils" title="永久链接至标题"></a></h1>
<div class="admonition note">
<p class="admonition-title">注解</p>
<p>这篇文档是历史遗留文档,在 <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html">https://setuptools.readthedocs.io/en/latest/setuptools.html</a> 上的 <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> 文档独立涵盖此处包含的所有相关信息之后,将不再单独作为正式文档保留。</p>
</div>
<p>本文档介绍了使用 Distutils 模块分发你的 Python 模块,主要是针对开发者/分发者的使用的——如果你想了解如何安装 Python 模块,你应该参考这个章节: <a class="reference internal" href="../install/index.html#install-index"><span class="std std-ref">安装Python模块旧版</span></a></p>
<section id="concepts-terminology">
<span id="distutils-concepts"></span><h2><span class="section-number">1.1. </span>概念和术语<a class="headerlink" href="#concepts-terminology" title="永久链接至标题"></a></h2>
<p>Distutils 用起来非常简单,对于模块开发者或安装第三方模块的用户/管理员均是如此。开发者的责任(当然还有编写可靠、良好文档和经过良好测试的代码!)就是:</p>
<ul class="simple">
<li><p>编写一个设置脚本 (<code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> by convention)</p></li>
<li><p>(可选)编写设置脚本的配置文件</p></li>
<li><p>创建源码的发行版</p></li>
<li><p>(可选)创建一个或多个编译好(二进制)的发行版</p></li>
</ul>
<p>这些操作在此文档均有讲解。</p>
<p>并非所有的模块开发者都能接触到众多的平台,所以期望他们创造众多的内置发行版不是总是可行的。最好是有一类名为 <em>打包者</em> 的中介,以满足这一需求。打包者将读取模块开发者发布的源代码,在一个或多个平台上进行编译,并发布构建出来的发行版。这样,最流行平台的用户就能以最自然的方式安装最流行的 Python 模块发行版,不必运行一段 setup 脚本或编译代码了。</p>
</section>
<section id="a-simple-example">
<span id="distutils-simple-example"></span><h2><span class="section-number">1.2. </span>一个简单的例子<a class="headerlink" href="#a-simple-example" title="永久链接至标题"></a></h2>
<p>setup 脚本通常很简单,尽管是用 Python 编写的,它能干的事情没有限制,当然应小心别在 setup 脚本中加入什么运行缓慢的操作。与 Autoconf 风格的 configure 脚本不同,在构建和安装模块的过程中 setup 脚本可能会运行多次。</p>
<p>如果只想发布一个名为 <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> 的模块,位于 <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code> 文件中,那么 setup 脚本可以如此简单:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">&#39;1.0&#39;</span><span class="p">,</span>
<span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>注意要点:</p>
<ul class="simple">
<li><p>提供给 Distutils 的大部分信息将作为关键字参数发给 <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code> 函数。</p></li>
<li><p>这些关键字参数分为两类:包的元数据(名称、版本号)和包中内容的描述信息(本例中是纯 Python 模块的列表)。</p></li>
<li><p>模块由模块名指定,而不是文件名(包和扩展也是如此)。</p></li>
<li><p>建议多提供一些元数据特别是开发者姓名、电子邮件地址和项目的URL参见 <a class="reference internal" href="setupscript.html#setup-script"><span class="std std-ref">编写安装脚本</span></a> 中的例子)。</p></li>
</ul>
<p>要为该模块创建一个源码发布版本,需要创建一段 setup 脚本 <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>,包含上述代码,然后从终端运行以下命令:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span>
</pre></div>
</div>
<p>对于 Windows 用户来说,打开命令行窗口(<span class="menuselection">Start ‣ Accessories</span>)并且写上如下命令:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span>
</pre></div>
</div>
<p><strong class="command">sdist</strong> 将创建一个归档文件(例如在 Unix 中为 tarball在 Windows 中为 ZIP 文件),其中包含你的配置脚本 <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> 以及你的模块 <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code>。 此归档文件将被命名为 <code class="file docutils literal notranslate"><span class="pre">foo-1.0.tar.gz</span></code> (或 <code class="file docutils literal notranslate"><span class="pre">.zip</span></code>),并将解包到目录 <code class="file docutils literal notranslate"><span class="pre">foo-1.0</span></code> 当中。</p>
<p>如果最终用户希望安装 <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> 模块,只需下载 <code class="file docutils literal notranslate"><span class="pre">foo-1.0.tar.gz</span></code> (或 <code class="file docutils literal notranslate"><span class="pre">.zip</span></code> )并解压,进入 <code class="file docutils literal notranslate"><span class="pre">foo-1.0</span></code> 目录运行:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">install</span>
</pre></div>
</div>
<p>这会把 <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code> 复制到 Python 安装环境的第三方模块目录中。</p>
<p>上述简单例子展示了 Distutils 的一些基本概念。首先,开发者和安装者拥有相同的基本用户界面,即 setup 脚本。区别在于使用哪种 Distutils <em>命令</em> <strong class="command">sdist</strong> 命令几乎只适用于模块开发者,而 <strong class="command">install</strong> 则更适用于安装者(当然大多数开发者偶尔也想要安装自己的代码)。</p>
<p>If you want to make things really easy for your users, you can create one or
more built distributions for them. For instance, if you are running on a
Windows machine, and want to make things easy for other Windows users, you can
create an executable installer (the most appropriate type of built distribution
for this platform) with the <strong class="command">bdist_wininst</strong> command. For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist_wininst</span>
</pre></div>
</div>
<p>will create an executable installer, <code class="file docutils literal notranslate"><span class="pre">foo-1.0.win32.exe</span></code>, in the current
directory.</p>
<p>其他有用的内置分发格式是 RPM可由 <strong class="command">bdist_rpm</strong> 、Solaris <strong class="program">pkgtool`:command:`bdist_pkgtool</strong>)和 HP-UX <strong class="program">swinstall`:command:`bdist_sdux</strong>)实现。比如,以下命令将创建一个名为 <code class="file docutils literal notranslate"><span class="pre">foo-1.0.noarch.rpm</span></code> 的RPM文件</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist_rpm</span>
</pre></div>
</div>
<p><strong class="command">bdist_rpm</strong> 命令用到了 <strong class="command">rpm</strong> 可执行文件,因此必须运行在基于 RPM 的系统中,如 Red Hat Linux 、 SuSE Linux 或 Mandrake Linux</p>
<p>可以随时运行以下命令,以便了解当前可用的分发格式:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist</span> <span class="o">--</span><span class="n">help</span><span class="o">-</span><span class="n">formats</span>
</pre></div>
</div>
</section>
<section id="general-python-terminology">
<span id="python-terms"></span><h2><span class="section-number">1.3. </span>通用的 Python 术语<a class="headerlink" href="#general-python-terminology" title="永久链接至标题"></a></h2>
<p>本文读者可能对模块、扩展等已有了很好的理解。但为确保所有人都站在同一起点上,下面提供了 Python 常用术语表:</p>
<dl class="simple">
<dt>module</dt><dd><p>实现 Python 代码重用的基本单位:可被其他代码导入的一段代码。有三种类型的模块与本文有关:纯 Python 模块、扩展模块和包。</p>
</dd>
<dt>纯 Python 模块</dt><dd><p>用 Python 编写的模块,包含在某 <code class="file docutils literal notranslate"><span class="pre">.py</span></code> 文件中(可能还会有相关的 <code class="file docutils literal notranslate"><span class="pre">.pyc</span></code> 文件)。有时被称为 &quot;纯模块&quot;</p>
</dd>
<dt>extension module -- 扩展模块</dt><dd><p>用低级语言编写的 Python 模块。Python 用 C/C++ ,而 Jython 则用Java。通常包含在一个可动态加载的预编译文件中比如 Unix 中的 Python 扩展是一个共享对象(<code class="file docutils literal notranslate"><span class="pre">.so</span></code>文件Windows 中的 Python 扩展则是一个 DLL (扩展名为 <code class="file docutils literal notranslate"><span class="pre">.pyd</span></code> ),而 Jython 的扩展是个 Java class 文件。注意目前Distutils 只处理 Python 的 C/C++ 扩展。)</p>
</dd>
<dt></dt><dd><p>包含其他模块的模块;通常位于文件系统的某个目录中,区别于其他目录的标记就是存在一个 <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> 文件。</p>
</dd>
<dt>根包</dt><dd><p>包的层次结构的根。(其并非一个真正的包,因为没有 <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> 文件。但总得给它起个名字)。 绝大多数标准库都在根包中,还有许多不属于任何大型模块的小型、独立的第三方模块。与普通的包不同,根包中的模块可能会在很多目录中出现:事实上,<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> 列出的每个目录都会为根包提供模块。</p>
</dd>
</dl>
</section>
<section id="distutils-specific-terminology">
<span id="distutils-term"></span><h2><span class="section-number">1.4. </span>Distutils 特定的术语<a class="headerlink" href="#distutils-specific-terminology" title="永久链接至标题"></a></h2>
<p>以下属于更加特别地用于 Distutils 发布 Python 模块。</p>
<dl class="simple">
<dt>模块发行版</dt><dd><p>一组 Python 模块,作为可下载的资源组团发布,以便 <em>大规模</em> 安装。模块发布版的著名例子是 NumPy 、 SciPy 、 Pillow 或 mxBase。这些会被称为 <em>package</em>,这个词在 Python 的语境中也使用过:一个模块发行版可能包含零个、一个或多个 Python 包。)</p>
</dd>
<dt>纯模块发行版</dt><dd><p>只包含纯 Python 模块和软件包的模块发布版。有时被称为“纯发行版”。</p>
</dd>
<dt>非纯模块发行版</dt><dd><p>至少包含一个扩展模块的模块发行版。 有时被称为“非纯发行版”。</p>
</dd>
<dt>根发行版</dt><dd><p>源代码树(或源代码发行版)的顶级目录;即 <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> 所在的目录。 一般来说,<code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> 会在该目录下运行。</p>
</dd>
</dl>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">目录</a></h3>
<ul>
<li><a class="reference internal" href="#">1. Distutils 模块介绍</a><ul>
<li><a class="reference internal" href="#concepts-terminology">1.1. 概念和术语</a></li>
<li><a class="reference internal" href="#a-simple-example">1.2. 一个简单的例子</a></li>
<li><a class="reference internal" href="#general-python-terminology">1.3. 通用的 Python 术语</a></li>
<li><a class="reference internal" href="#distutils-specific-terminology">1.4. Distutils 特定的术语</a></li>
</ul>
</li>
</ul>
<h4>上一个主题</h4>
<p class="topless"><a href="index.html"
title="上一章">分发 Python 模块(遗留版本)</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="setupscript.html"
title="下一章"><span class="section-number">2. </span>编写安装脚本</a></p>
<div role="note" aria-label="source link">
<h3>本页</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">报告 Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.8/Doc/distutils/introduction.rst"
rel="nofollow">显示源代码
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>导航</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="总目录"
>索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模块索引"
>模块</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. 编写安装脚本"
>下一页</a> |</li>
<li class="right" >
<a href="index.html" title="分发 Python 模块(遗留版本)"
>上一页</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.8.20 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >分发 Python 模块(遗留版本)</a> &#187;</li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
<input type="submit" value="转向" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
<br />
This page is licensed under the Python Software Foundation License Version 2.
<br />
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br />
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
最后更新于 12月 09, 2024.
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
</div>
</body>
</html>