Introduction to distutils

I have recently used distutils for the first time and thought I would share what I have learned.

Please note: I am not a pro. All this is based on my own hacking and struggling to get things to work. I am sure there will be alternative ways to do things and that I will make mistakes. Caveat Emptor.

(Based on Gnu/Linux)

The layout of folders

A proper layout of your files and folders can really save you trouble later on. I use this layout:

top
|-- package
|   |-- __init__.py
|   |-- module.py
|   `-- things
|       |-- cross.png
|       |-- fplogo.png
|       `-- tick.png
|-- runner
|-- MANIFEST.in
|-- README
`-- setup.py

• top - The very top of the tree is some arbitrary folder, perhaps in your home directory under pythondev. It doesn't matter.
• package - I call it this to indicate that it's where I am developing my package(s).

  (Packages are simply folders with modules (py files) in them. They also have a special file called __init__.py so that Python will know that this folder is a package.)

• package/things - This is where I will keep all my things. Here I have some image files, but you can put anything your module may need here. Naturally you can use any folder name you like.
• The other files are all in the root and will be described soon.

The files

I assume that there will be a single script file that you will use to start your Python app. I call it 'runner' (without the .py) in this example. It will import the actual package. Here is the code:

runner

##This will work in development on a relative folder basis
##It will then work when installed in site-packages on a target system
##where the runner script is in /usr/bin (or wherever)
##
##So, you don't need anything special - no fancy path tricks.

import package.module

package.module.start ()

Next is the package. In this case there is only one module in the package (import package.module), so here is the module: module.py {{{#!/usr/bin/env python2.4

import os, sys

def determine_path ():

• """Borrowed from wxglade.py""" try:

  • root = file if os.path.islink(root):

    • root = os.path.realpath(root)
    return os.path.dirname(os.path.abspath(root))
  except:
  • print "I'm sorry, but something is wrong."

    print "There is no file variable. Please contact the author." sys.exit ()

def start ():

• print "module is running" print determine_path () print "My various data files and so on are:" files = [f for f in os.listdir(determine_path () + "/things")] print files

if name == "main":

• print "Decide what to do"

}}}

This uses the magic variable __file__ that will return the path and name of the module. Without it you would have to jump through some hoops to locate the module on any given distro or O/S.

• (If you can find this in the Python docs, then your grep-foo is better than mine. I found it by pouring through other Python apps in the site-packages folder of python2.4)

It shows that it can find the data files in the things folder.

The __init__.py file is empty

The README file is named that way because it's one of the ways that distutils automatically looks for it. You should put details about your app into it. It's not a required file.