-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathintroduction.html
More file actions
354 lines (333 loc) · 21.1 KB
/
introduction.html
File metadata and controls
354 lines (333 loc) · 21.1 KB
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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_TW">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>1. An Introduction to Distutils — Python 3.7.0 說明文件</title>
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/translations.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="在 Python 3.7.0 說明文件 中搜尋"
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="Copyright" href="../copyright.html" />
<link rel="next" title="2. Writing the Setup Script" href="setupscript.html" />
<link rel="prev" title="發布 Python 模組（舊版）" href="index.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/3/distutils/introduction.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/switchers.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>瀏覽</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
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. Writing the Setup Script"
accesskey="N">下一頁</a> |</li>
<li class="right" >
<a href="index.html" title="發布 Python 模組（舊版）"
accesskey="P">上一頁</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<span class="language_switcher_placeholder">zh_TW</span>
<span class="version_switcher_placeholder">3.7.0</span>
<a href="../index.html">Documentation </a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">發布 Python 模組（舊版）</a> »</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="an-introduction-to-distutils">
<span id="distutils-intro"></span><h1>1. An Introduction to Distutils<a class="headerlink" href="#an-introduction-to-distutils" title="本標題的永久連結">¶</a></h1>
<p>This document covers using the Distutils to distribute your Python modules,
concentrating on the role of developer/distributor: if you’re looking for
information on installing Python modules, you should refer to the
<a class="reference internal" href="../install/index.html#install-index"><span class="std std-ref">安裝 Python 模組（舊版）</span></a> chapter.</p>
<div class="section" id="concepts-terminology">
<span id="distutils-concepts"></span><h2>1.1. Concepts & Terminology<a class="headerlink" href="#concepts-terminology" title="本標題的永久連結">¶</a></h2>
<p>Using the Distutils is quite simple, both for module developers and for
users/administrators installing third-party modules. As a developer, your
responsibilities (apart from writing solid, well-documented and well-tested
code, of course!) are:</p>
<ul class="simple">
<li>write a setup script (<code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> by convention)</li>
<li>(optional) write a setup configuration file</li>
<li>create a source distribution</li>
<li>(optional) create one or more built (binary) distributions</li>
</ul>
<p>Each of these tasks is covered in this document.</p>
<p>Not all module developers have access to a multitude of platforms, so it’s not
always feasible to expect them to create a multitude of built distributions. It
is hoped that a class of intermediaries, called <em>packagers</em>, will arise to
address this need. Packagers will take source distributions released by module
developers, build them on one or more platforms, and release the resulting built
distributions. Thus, users on the most popular platforms will be able to
install most popular Python module distributions in the most natural way for
their platform, without having to run a single setup script or compile a line of
code.</p>
</div>
<div class="section" id="a-simple-example">
<span id="distutils-simple-example"></span><h2>1.2. A Simple Example<a class="headerlink" href="#a-simple-example" title="本標題的永久連結">¶</a></h2>
<p>The setup script is usually quite simple, although since it’s written in Python,
there are no arbitrary limits to what you can do with it, though you should be
careful about putting arbitrarily expensive operations in your setup script.
Unlike, say, Autoconf-style configure scripts, the setup script may be run
multiple times in the course of building and installing your module
distribution.</p>
<p>If all you want to do is distribute a module called <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code>, contained in a
file <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code>, then your setup script can be as simple as this:</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="k">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">'foo'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Some observations:</p>
<ul class="simple">
<li>most information that you supply to the Distutils is supplied as keyword
arguments to the <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code> function</li>
<li>those keyword arguments fall into two categories: package metadata (name,
version number) and information about what’s in the package (a list of pure
Python modules, in this case)</li>
<li>modules are specified by module name, not filename (the same will hold true
for packages and extensions)</li>
<li>it’s recommended that you supply a little more metadata, in particular your
name, email address and a URL for the project (see section <a class="reference internal" href="setupscript.html#setup-script"><span class="std std-ref">Writing the Setup Script</span></a>
for an example)</li>
</ul>
<p>To create a source distribution for this module, you would create a setup
script, <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>, containing the above code, and run this command from a
terminal:</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>For Windows, open a command prompt window (<span class="menuselection">Start ‣
Accessories</span>) and change the command to:</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> will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
containing your setup script <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>, and your module <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code>.
The archive file will be named <code class="file docutils literal notranslate"><span class="pre">foo-1.0.tar.gz</span></code> (or <code class="file docutils literal notranslate"><span class="pre">.zip</span></code>), and
will unpack into a directory <code class="file docutils literal notranslate"><span class="pre">foo-1.0</span></code>.</p>
<p>If an end-user wishes to install your <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> module, all they have to do is
download <code class="file docutils literal notranslate"><span class="pre">foo-1.0.tar.gz</span></code> (or <code class="file docutils literal notranslate"><span class="pre">.zip</span></code>), unpack it, and—from the
<code class="file docutils literal notranslate"><span class="pre">foo-1.0</span></code> directory—run</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>which will ultimately copy <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code> to the appropriate directory for
third-party modules in their Python installation.</p>
<p>This simple example demonstrates some fundamental concepts of the Distutils.
First, both developers and installers have the same basic user interface, i.e.
the setup script. The difference is which Distutils <em>commands</em> they use: the
<strong class="command">sdist</strong> command is almost exclusively for module developers, while
<strong class="command">install</strong> is more often for installers (although most developers will
want to install their own code occasionally).</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>Other useful built distribution formats are RPM, implemented by the
<strong class="command">bdist_rpm</strong> command, Solaris <strong class="program">pkgtool</strong>
(<strong class="command">bdist_pkgtool</strong>), and HP-UX <strong class="program">swinstall</strong>
(<strong class="command">bdist_sdux</strong>). For example, the following command will create an RPM
file called <code class="file docutils literal notranslate"><span class="pre">foo-1.0.noarch.rpm</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">bdist_rpm</span>
</pre></div>
</div>
<p>(The <strong class="command">bdist_rpm</strong> command uses the <strong class="command">rpm</strong> executable, therefore
this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
Mandrake Linux.)</p>
<p>You can find out what distribution formats are available at any time by running</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>
</div>
<div class="section" id="general-python-terminology">
<span id="python-terms"></span><h2>1.3. General Python terminology<a class="headerlink" href="#general-python-terminology" title="本標題的永久連結">¶</a></h2>
<p>If you’re reading this document, you probably have a good idea of what modules,
extensions, and so forth are. Nevertheless, just to be sure that everyone is
operating from a common starting point, we offer the following glossary of
common Python terms:</p>
<dl class="docutils">
<dt>module</dt>
<dd>the basic unit of code reusability in Python: a block of code imported by some
other code. Three types of modules concern us here: pure Python modules,
extension modules, and packages.</dd>
<dt>pure Python module</dt>
<dd>a module written in Python and contained in a single <code class="file docutils literal notranslate"><span class="pre">.py</span></code> file (and
possibly associated <code class="file docutils literal notranslate"><span class="pre">.pyc</span></code> files). Sometimes referred to as a
「pure module.」</dd>
<dt>extension module</dt>
<dd>a module written in the low-level language of the Python implementation: C/C++
for Python, Java for Jython. Typically contained in a single dynamically
loadable pre-compiled file, e.g. a shared object (<code class="file docutils literal notranslate"><span class="pre">.so</span></code>) file for Python
extensions on Unix, a DLL (given the <code class="file docutils literal notranslate"><span class="pre">.pyd</span></code> extension) for Python
extensions on Windows, or a Java class file for Jython extensions. (Note that
currently, the Distutils only handles C/C++ extensions for Python.)</dd>
<dt>package</dt>
<dd>a module that contains other modules; typically contained in a directory in the
filesystem and distinguished from other directories by the presence of a file
<code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code>.</dd>
<dt>root package</dt>
<dd>the root of the hierarchy of packages. (This isn’t really a package, since it
doesn’t have an <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> file. But we have to call it something.)
The vast majority of the standard library is in the root package, as are many
small, standalone third-party modules that don’t belong to a larger module
collection. Unlike regular packages, modules in the root package can be found in
many directories: in fact, every directory listed in <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> contributes
modules to the root package.</dd>
</dl>
</div>
<div class="section" id="distutils-specific-terminology">
<span id="distutils-term"></span><h2>1.4. Distutils-specific terminology<a class="headerlink" href="#distutils-specific-terminology" title="本標題的永久連結">¶</a></h2>
<p>The following terms apply more specifically to the domain of distributing Python
modules using the Distutils:</p>
<dl class="docutils">
<dt>module distribution</dt>
<dd>a collection of Python modules distributed together as a single downloadable
resource and meant to be installed <em>en masse</em>. Examples of some well-known
module distributions are NumPy, SciPy, Pillow,
or mxBase. (This would be called a <em>package</em>, except that term is
already taken in the Python context: a single module distribution may contain
zero, one, or many Python packages.)</dd>
<dt>pure module distribution</dt>
<dd>a module distribution that contains only pure Python modules and packages.
Sometimes referred to as a 「pure distribution.」</dd>
<dt>non-pure module distribution</dt>
<dd>a module distribution that contains at least one extension module. Sometimes
referred to as a 「non-pure distribution.」</dd>
<dt>distribution root</dt>
<dd>the top-level directory of your source tree (or source distribution); the
directory where <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> exists. Generally <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> will be
run from this directory.</dd>
</dl>
</div>
</div>
</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. An Introduction to Distutils</a><ul>
<li><a class="reference internal" href="#concepts-terminology">1.1. Concepts & Terminology</a></li>
<li><a class="reference internal" href="#a-simple-example">1.2. A Simple Example</a></li>
<li><a class="reference internal" href="#general-python-terminology">1.3. General Python terminology</a></li>
<li><a class="reference internal" href="#distutils-specific-terminology">1.4. Distutils-specific terminology</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="下一章">2. Writing the Setup Script</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/introduction.rst"
rel="nofollow">Show Source
</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="General Index"
>索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模組索引"
>模組</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. Writing the Setup Script"
>下一頁</a> |</li>
<li class="right" >
<a href="index.html" title="發布 Python 模組（舊版）"
>上一頁</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<span class="language_switcher_placeholder">zh_TW</span>
<span class="version_switcher_placeholder">3.7.0</span>
<a href="../index.html">Documentation </a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >發布 Python 模組（舊版）</a> »</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001-2018, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on 8月 22, 2018.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.7.
</div>
</body>
</html>