kennethreitz/dive-into-python3
1
0
Fork 0
mirror of https://github.com/kennethreitz/dive-into-python3.git synced 2026-06-05 23:10:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

work on #trove section

Browse Source
This commit is contained in:
Mark Pilgrim
2009-07-29 14:31:54 -04:00
parent 4bc279f58b
commit a06decc814
1 changed files with 50 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packaging.html
+50 -12
View File
@@ -20,13 +20,13 @@ body{counter-reset:h1 16}
</blockquote>
<p id=toc>&nbsp;
<h2 id=divingin>Diving In</h2>
<p class=f>So you want to release a Python library. Excellent. The world needs more Python libraries.
<p class=f>So you want to release a Python script, library, framework, or application. Excellent. The world needs more Python code.
<p>Python 3 comes with a packaging framework called Distutils. Distutils is many things: a build tool (for you), an installation tool (for your users), a package metadata format (for search engines), and more. It integrates with the <a href=http://pypi.python.org/>Python Package Index</a>, a central repository for open source Python libraries.
<p>Python 3 comes with a packaging framework called Distutils. Distutils is many things: a build tool (for you), an installation tool (for your users), a package metadata format (for search engines), and more. It integrates with the <a href=http://pypi.python.org/>Python Package Index</a> (&#8220;PyPI&#8221;), a central repository for open source Python libraries.
<p>All of these facets of Distutils center around the <i>setup script</i>, traditionally called <code>setup.py</code>. In fact, you&#8217;ve already seen a Distutils setup script: <a href=http-web-services.html#introducing-httplib2>you used one to install <code>httplib2</code></a> in the &#8220;HTTP Web Services&#8221; chapter.
<p>In this chapter, we&#8217;ll see how the setup script for <a href=http://code.google.com/p/httplib2/><code>httplib2</code></a> works and step through the process of releasing your own Python library.
<p>In this chapter, you&#8217;ll learn how the setup script for <a href=http://code.google.com/p/httplib2/><code>httplib2</code></a> works and step through the process of releasing your own Python software.
<pre><code class=pp># httplib2's setup.py
from distutils.core import setup
@@ -98,14 +98,14 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
)</code></pre>
<blockquote class=note>
<p><span class=u>&#x261E;</span><code>httplib2</code> is open source, but there&#8217;s no requirement that you release your own Python libraries under any particular license. The process described in this chapter will work for any Python library, regardless of license.
<p><span class=u>&#x261E;</span><code>httplib2</code> is open source, but there&#8217;s no requirement that you release your own Python libraries under any particular license. The process described in this chapter will work for any Python software, regardless of license.
</blockquote>
<p class=a>&#x2042;
<h2 id=cantdo>Things Distutils Can&#8217;t Do For You</h2>
<p>Releasing your first Python library is a daunting process. (Releasing your second one is easier.) Distutils tries to automate as much of it as possible, but there are some things you simply must do yourself.
<p>Releasing your first Python package is a daunting process. (Releasing your second one is easier.) Distutils tries to automate as much of it as possible, but there are some things you simply must do yourself.
<ul>
<li><b>Choose a license</b>. This is a complicated topic, fraught with politics and peril. If you wish to release your software as open source, I humbly offer five pieces of advice:
@@ -116,13 +116,13 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
<li>It doesn&#8217;t need to be <abbr>GPL</abbr>, but <a href=http://www.dwheeler.com/essays/gpl-compatible.html>it needs to be <abbr>GPL</abbr>-compatible</a>.
<li>Don&#8217;t write your own license.
</ol>
<li><b>Classify your library</b> using the Trove classification system. I&#8217;ll explain what this means later in this chapter.
<li><b>Write a &#8220;read me&#8221; file</b>. Don&#8217;t skimp on this. At a minimum, it should give your users an overview of what your library does and how to install it.
<li><b>Classify your software</b> using the PyPI classification system. I&#8217;ll explain what this means later in this chapter.
<li><b>Write a &#8220;read me&#8221; file</b>. Don&#8217;t skimp on this. At a minimum, it should give your users an overview of what your software does and how to install it.
</ul>
<h2 id=structure>Directory Structure</h2>
<p>To start packaging your Python library, you need to get your files and directories in order. The <code>httplib2</code> directory looks like this:
<p>To start packaging your Python software, you need to get your files and directories in order. The <code>httplib2</code> directory looks like this:
<pre class=screen>
<a>httplib2/ <span class=u>&#x2460;</span></a>
@@ -140,7 +140,7 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
<li>Make a root directory to hold everything. Give it the same name as your Python module.
<li>To accomodate Windows users, your &#8220;read me&#8221; file should include a <code>.txt</code> extension, and it should use Windows-style carriage returns. Just because <em>you</em> use a fancy text editor that runs from the command line and includes its own macro language, that doesn&#8217;t mean you need to make life difficult for your users. (Your users use Notepad. Sad but true.) Even if you&#8217;re on Linux or Mac OS X, your fancy text editor undoubtedly has an option to save files with Windows-style carriage returns.
<li>Your Distutils setup script should be named <code>setup.py</code> unless you have a good reason not to. You do not have a good reason not to.
<li>If your Python library is a single <code>.py</code> file, you should put it in the root directory along with your &#8220;read me&#8221; file and your setup script. If your library is a directory with a main <code>__init__.py</code> script, like <code>httplib2</code>, you should put the entire directory here. Yes, that means you&#8217;ll have an <code>httplib2/</code> directory within an <code>httplib2/</code> directory. Trust me, that&#8217;s not a problem. In fact, any other arrangement would be a problem.
<li>If your Python software is a single <code>.py</code> file, you should put it in the root directory along with your &#8220;read me&#8221; file and your setup script. If it&#8217;s a multi-file module (<i>i.e.</i> a directory with a main <code>__init__.py</code> script), like <code>httplib2</code>, you should put the entire directory here. Yes, that means you&#8217;ll have an <code>httplib2/</code> directory within an <code>httplib2/</code> directory. Trust me, that&#8217;s not a problem. In fact, any other arrangement would be a problem.
</ol>
<p>Depending on the license you chose, you may include the license text within your <code>.py</code> files themselves, or you may have a separate file containing license text, or both. <abbr>GPL</abbr>-licensed programs generally include a file called <code>COPYING</code> that includes the entire text of the <abbr>GPL</abbr>. If you have a separate license file, it should go in the root directory along with your &#8220;read me&#8221; file and your setup script.
@@ -159,6 +159,44 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
<h3 id=trove>Classifying Your Package</h3>
<p>The Python Package Index (&#8220;PyPI&#8221;) contains thousands of Python libraries. Proper classification metadata will allow people to find yours more easily.
<p>The PyPI classification system is based on <a href=http://sourceforge.net/softwaremap/>SourceForce&#8217;s software map</a>. Classifiers are strings, but they are <em>not</em> freeform.
<ul>
<li><b>Development Status</b>. Is your software beta quality? Alpha quality? Pre-alpha? Pick one, and be honest.
<li><b>Environment</b>. FIXME (optional, multiples allowed)
<li><b>Framework</b>. Does your software rely on a larger Python framework like <a href=http://www.djangoproject.com/>Django</a> or <a href=http://www.zope.org/>Zope</a>? If not, you can omit this classifier.
<li><b>Intended Audience</b>. Who would download your software? End users looking for desktop software? System administrators? Scientists? Other Python developers?
<li><b>License</b>. FIXME (strongly recommended, probably just one unless your software is available under multiple licenses)
<li><b>Natural Language</b>. FIXME (optional, multiples allowed)
<li><b>Operating System</b>. FIXME (strongly recommended, multiples allowed)
<li><b>Programming Language</b>. FIXME (strongly recommended, multiples allowed and encouraged)
<li><b>Topic</b>. FIXME (recommended, multiples allowed and encouraged)
</ul>
<blockquote class=note>
<p><span class=u>&#x261E;</span>All of your classifiers should come from <a href='http://pypi.python.org/pypi?:action=list_classifiers'>this master list on PyPI</a>.
</blockquote>
<p>You should <em>always</em> include at least these four classifiers:
<ul>
<li><code>"Programming Language :: Python"</code>
<li><code>"Programming Language :: Python :: 3"</code>. If you do not include this, your package will not show up in <a href='http://pypi.python.org/pypi?:action=browse&c=533&show=all'>this list of Python 3-compatible libraries</a>, which linked from the sidebar of every single page of <code>pypi.python.org</code>.
<li><code>"License :: <i>whatever</i>"</code>. This is <em>the absolute first thing I look for</em> when I&#8217;m evaluating third-party libraries. Don&#8217;t make me hunt for this vital information.
<li><code>"Operating System :: <i>whatever</i>"</code>. If your software only runs on Windows, I want to know sooner rather than later. If it runs everywhere, use the classifier <code>"Operating System :: OS Independent"</code>.
</ul>
<p>I <em>strongly</em> recommend that you also include the following classifications:
<ul>
<li><code>"Development Status :: <i>whatever</i>"</code>. Be honest.
<li><code>"Intended Audience :: <i>whatever</i>"</code>.
</ul>
<p>FIXME - look at several examples, including httplib2
<h3 id=check>Checking Your Setup Script for Errors</h3>
<h2 id=setupcfg>Writing Your Setup Configuration File</h2>
@@ -179,11 +217,11 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
<h3 id=rpm>Building a Linux RPM Package</h3>
<h2 id=pypi>The Python Package Index</h2>
<h2 id=pypi>Adding Your Package to The Python Package Index</h2>
<h3 id=register-user>Registering Yourself</h3>
<h3 id=register-package>Registering Your Python Library</h3>
<h3 id=register-package>Registering Your Package</h3>
<h3 id=upload>Uploading New Versions</h3>
@@ -198,7 +236,7 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
<h2 id=future>The Many Possible Futures of Python Packaging</h2>
<p>Distutils is not the be-all and end-all of Python packaging, but as of this writing (August 2009), it&#8217;s the only one that works in Python 3. There are a number of other frameworks for Python 2; some focus on installation, others on testing and deployment. Some or all of these may end up being ported to Python 3 in the future.
<p>Distutils is not the be-all and end-all of Python packaging, but as of this writing (August 2009), it&#8217;s the only packaging framework that works in Python 3. There are a number of other frameworks for Python 2; some focus on installation, others on testing and deployment. Some or all of these may end up being ported to Python 3 in the future.
<p>These frameworks focus on installation: