How to create, upload and install a package for PyPI?

Question

I wrote a little module and I would like to know what are the basic steps to package it in order to upload it to PyPI:

• What is the file hierarchy?
• How should I name files?
• Should I use distutils to create PKG-INFO?
• Where should I include my documentation (made with sphinx)?

Answer 1

I recommend reading The Hitchhiker's Guide to Packaging. Specifically, you should look at the Quick Start section, which describes how to:

1. Lay out your project
2. Describe your project
3. Create your first release
4. Register your package with the Python Package Index (PyPI)
5. Upload your release, then grab your towel and save the Universe!

You should also look at the Current State of Packaging in the Introduction to Packaging section, as this helps untangle some of the confusion surrounding setuptools, distutils, distutils2, and distribute.

Update Re: How to Name Files

The excerpt below is from PEP8, which answers your question about how to name files:

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

Since module names are mapped to file names, and some file systems are case insensitive and truncate long names, it is important that module names be chosen to be fairly short -- this won't be a problem on Unix, but it may be a problem when the code is transported to older Mac or Windows versions, or DOS.