364 lines
21 KiB
HTML
364 lines
21 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>1. An Introduction to Distutils — Python 3.7.4 documentation</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/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" 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="Distributing Python Modules (Legacy version)" 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>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="setupscript.html" title="2. Writing the Setup Script"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="index.html" title="Distributing Python Modules (Legacy version)"
|
||
accesskey="P">previous</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">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</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="Permalink to this headline">¶</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">Installing Python Modules (Legacy version)</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="Permalink to this headline">¶</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><p>write a setup script (<code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> by convention)</p></li>
|
||
<li><p>(optional) write a setup configuration file</p></li>
|
||
<li><p>create a source distribution</p></li>
|
||
<li><p>(optional) create one or more built (binary) distributions</p></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="Permalink to this headline">¶</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><p>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</p></li>
|
||
<li><p>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)</p></li>
|
||
<li><p>modules are specified by module name, not filename (the same will hold true
|
||
for packages and extensions)</p></li>
|
||
<li><p>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)</p></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="Permalink to this headline">¶</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="simple">
|
||
<dt>module</dt><dd><p>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.</p>
|
||
</dd>
|
||
<dt>pure Python module</dt><dd><p>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.”</p>
|
||
</dd>
|
||
<dt>extension module</dt><dd><p>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.)</p>
|
||
</dd>
|
||
<dt>package</dt><dd><p>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>.</p>
|
||
</dd>
|
||
<dt>root package</dt><dd><p>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.</p>
|
||
</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="Permalink to this headline">¶</a></h2>
|
||
<p>The following terms apply more specifically to the domain of distributing Python
|
||
modules using the Distutils:</p>
|
||
<dl class="simple">
|
||
<dt>module distribution</dt><dd><p>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.)</p>
|
||
</dd>
|
||
<dt>pure module distribution</dt><dd><p>a module distribution that contains only pure Python modules and packages.
|
||
Sometimes referred to as a “pure distribution.”</p>
|
||
</dd>
|
||
<dt>non-pure module distribution</dt><dd><p>a module distribution that contains at least one extension module. Sometimes
|
||
referred to as a “non-pure distribution.”</p>
|
||
</dd>
|
||
<dt>distribution root</dt><dd><p>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.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</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>Previous topic</h4>
|
||
<p class="topless"><a href="index.html"
|
||
title="previous chapter">Distributing Python Modules (Legacy version)</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="setupscript.html"
|
||
title="next chapter">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>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="setupscript.html" title="2. Writing the Setup Script"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="index.html" title="Distributing Python Modules (Legacy version)"
|
||
>previous</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">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</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-2019, 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 Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |