diff --git a/packaging.html b/packaging.html index 5903c2c..de9618a 100644 --- a/packaging.html +++ b/packaging.html @@ -20,13 +20,13 @@ body{counter-reset:h1 16}

 

Diving In

-

So you want to release a Python library. Excellent. The world needs more Python libraries. +

So you want to release a Python script, library, framework, or application. Excellent. The world needs more Python code. -

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 Python Package Index, a central repository for open source Python libraries. +

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 Python Package Index (“PyPI”), a central repository for open source Python libraries.

All of these facets of Distutils center around the setup script, traditionally called setup.py. In fact, you’ve already seen a Distutils setup script: you used one to install httplib2 in the “HTTP Web Services” chapter. -

In this chapter, we’ll see how the setup script for httplib2 works and step through the process of releasing your own Python library. +

In this chapter, you’ll learn how the setup script for httplib2 works and step through the process of releasing your own Python software. 

# httplib2's setup.py
 from distutils.core import setup
@@ -98,14 +98,14 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
 )
-

☞httplib2 is open source, but there’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. +

☞httplib2 is open source, but there’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.

⁂

Things Distutils Can’t Do For You

-

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. +

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.

Directory Structure

-

To start packaging your Python library, you need to get your files and directories in order. The httplib2 directory looks like this: +

To start packaging your Python software, you need to get your files and directories in order. The httplib2 directory looks like this: 

 httplib2/                 ①
@@ -140,7 +140,7 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
 
  • Make a root directory to hold everything. Give it the same name as your Python module.
 
  • To accomodate Windows users, your “read me” file should include a .txt extension, and it should use Windows-style carriage returns. Just because you use a fancy text editor that runs from the command line and includes its own macro language, that doesn’t mean you need to make life difficult for your users. (Your users use Notepad. Sad but true.) Even if you’re on Linux or Mac OS X, your fancy text editor undoubtedly has an option to save files with Windows-style carriage returns.
 
  • Your Distutils setup script should be named setup.py unless you have a good reason not to. You do not have a good reason not to.
-
  • If your Python library is a single .py file, you should put it in the root directory along with your “read me” file and your setup script. If your library is a directory with a main __init__.py script, like httplib2, you should put the entire directory here. Yes, that means you’ll have an httplib2/ directory within an httplib2/ directory. Trust me, that’s not a problem. In fact, any other arrangement would be a problem.
+
  • If your Python software is a single .py file, you should put it in the root directory along with your “read me” file and your setup script. If it’s a multi-file module (i.e. a directory with a main __init__.py script), like httplib2, you should put the entire directory here. Yes, that means you’ll have an httplib2/ directory within an httplib2/ directory. Trust me, that’s not a problem. In fact, any other arrangement would be a problem.
 
 
 
    Depending on the license you chose, you may include the license text within your .py files themselves, or you may have a separate file containing license text, or both. GPL-licensed programs generally include a file called COPYING that includes the entire text of the GPL. If you have a separate license file, it should go in the root directory along with your “read me” file and your setup script.
@@ -159,6 +159,44 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
 
 
    Classifying Your Package
    
 
+
    The Python Package Index (“PyPI”) contains thousands of Python libraries. Proper classification metadata will allow people to find yours more easily.
+
+
    The PyPI classification system is based on SourceForce’s software map. Classifiers are strings, but they are not freeform.
+
+
    
+
+
    
+
    ☞All of your classifiers should come from this master list on PyPI.
+
    
+
+
    You should always include at least these four classifiers:
+
+
    
+
+
    I strongly recommend that you also include the following classifications:
+
+
    
+
+
    FIXME - look at several examples, including httplib2
+
 
    Checking Your Setup Script for Errors
    
 
 
    Writing Your Setup Configuration File
    
@@ -179,11 +217,11 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
 
 
    Building a Linux RPM Package
    
 
-
    The Python Package Index
    
+
    Adding Your Package to The Python Package Index
    
 
 
    Registering Yourself
    
 
-
    Registering Your Python Library
    
+
    Registering Your Package
    
 
 
    Uploading New Versions
    
 
@@ -198,7 +236,7 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
 
 
    The Many Possible Futures of Python Packaging
    
 
-
    Distutils is not the be-all and end-all of Python packaging, but as of this writing (August 2009), it’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.
+
    Distutils is not the be-all and end-all of Python packaging, but as of this writing (August 2009), it’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.
 
 
    These frameworks focus on installation: