korsygfhrtzangaiide
Elepffwdsff
/
usr
/
share
/
doc
/
python-docs-2.7.5
/
html
/
distutils
/
Upload FileeE
HOME
<!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"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>1. An Introduction to Distutils — Python 2.7.5 documentation</title> <link rel="stylesheet" href="../_static/default.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '2.7.5', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </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/sidebar.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python 2.7.5 documentation" href="../_static/opensearch.xml"/> <link rel="author" title="About these documents" href="../about.html" /> <link rel="copyright" title="Copyright" href="../copyright.html" /> <link rel="top" title="Python 2.7.5 documentation" href="../index.html" /> <link rel="up" title="Distributing Python Modules" href="index.html" /> <link rel="next" title="2. Writing the Setup Script" href="setupscript.html" /> <link rel="prev" title="Distributing Python Modules" href="index.html" /> <link rel="shortcut icon" type="image/png" href="../_static/py.png" /> <script type="text/javascript" src="../_static/copybutton.js"></script> </head> <body> <div class="related"> <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" accesskey="P">previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="http://www.python.org/">Python</a> »</li> <li> <a href="../index.html">Python 2.7.5 documentation</a> » </li> <li><a href="index.html" accesskey="U">Distributing Python Modules</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <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"><em>Installing Python Modules</em></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>write a setup script (<tt class="file docutils literal"><span class="pre">setup.py</span></tt> 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="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 <tt class="xref py py-mod docutils literal"><span class="pre">foo</span></tt>, contained in a file <tt class="file docutils literal"><span class="pre">foo.py</span></tt>, then your setup script can be as simple as this:</p> <div class="highlight-python"><div class="highlight"><pre><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="s">'foo'</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s">'1.0'</span><span class="p">,</span> <span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s">'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 <tt class="xref py py-func docutils literal"><span class="pre">setup()</span></tt> 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"><em>Writing the Setup Script</em></a> for an example)</li> </ul> <p>To create a source distribution for this module, you would create a setup script, <tt class="file docutils literal"><span class="pre">setup.py</span></tt>, containing the above code, and run this command from a terminal:</p> <div class="highlight-python"><pre>python setup.py sdist</pre> </div> <p>For Windows, open a command prompt windows (<em class="menuselection">Start ‣ Accessories</em>) and change the command to:</p> <div class="highlight-python"><pre>setup.py sdist</pre> </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 <tt class="file docutils literal"><span class="pre">setup.py</span></tt>, and your module <tt class="file docutils literal"><span class="pre">foo.py</span></tt>. The archive file will be named <tt class="file docutils literal"><span class="pre">foo-1.0.tar.gz</span></tt> (or <tt class="file docutils literal"><span class="pre">.zip</span></tt>), and will unpack into a directory <tt class="file docutils literal"><span class="pre">foo-1.0</span></tt>.</p> <p>If an end-user wishes to install your <tt class="xref py py-mod docutils literal"><span class="pre">foo</span></tt> module, all she has to do is download <tt class="file docutils literal"><span class="pre">foo-1.0.tar.gz</span></tt> (or <tt class="file docutils literal"><span class="pre">.zip</span></tt>), unpack it, and—from the <tt class="file docutils literal"><span class="pre">foo-1.0</span></tt> directory—run</p> <div class="highlight-python"><pre>python setup.py install</pre> </div> <p>which will ultimately copy <tt class="file docutils literal"><span class="pre">foo.py</span></tt> 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-python"><pre>python setup.py bdist_wininst</pre> </div> <p>will create an executable installer, <tt class="file docutils literal"><span class="pre">foo-1.0.win32.exe</span></tt>, 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 <tt class="file docutils literal"><span class="pre">foo-1.0.noarch.rpm</span></tt>:</p> <div class="highlight-python"><pre>python setup.py bdist_rpm</pre> </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-python"><pre>python setup.py bdist --help-formats</pre> </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="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 <tt class="file docutils literal"><span class="pre">.py</span></tt> file (and possibly associated <tt class="file docutils literal"><span class="pre">.pyc</span></tt> and/or <tt class="file docutils literal"><span class="pre">.pyo</span></tt> 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 (<tt class="file docutils literal"><span class="pre">.so</span></tt>) file for Python extensions on Unix, a DLL (given the <tt class="file docutils literal"><span class="pre">.pyd</span></tt> 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 <tt class="file docutils literal"><span class="pre">__init__.py</span></tt>.</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 <tt class="file docutils literal"><span class="pre">__init__.py</span></tt> 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 <tt class="docutils literal"><span class="pre">sys.path</span></tt> 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="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="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 Numeric Python, PyXML, PIL (the Python Imaging Library), 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 <tt class="file docutils literal"><span class="pre">setup.py</span></tt> exists. Generally <tt class="file docutils literal"><span class="pre">setup.py</span></tt> will be run from this directory.</dd> </dl> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <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</a></p> <h4>Next topic</h4> <p class="topless"><a href="setupscript.html" title="next chapter">2. Writing the Setup Script</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../bugs.html">Report a Bug</a></li> <li><a href="../_sources/distutils/introduction.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="../search.html" method="get"> <input 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> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <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" >previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="http://www.python.org/">Python</a> »</li> <li> <a href="../index.html">Python 2.7.5 documentation</a> » </li> <li><a href="index.html" >Distributing Python Modules</a> »</li> </ul> </div> <div class="footer"> © <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation. <br /> The Python Software Foundation is a non-profit corporation. <a href="http://www.python.org/psf/donations/">Please donate.</a> <br /> Last updated on Jul 03, 2019. <a href="../bugs.html">Found a bug</a>? <br /> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3. </div> </body> </html>