Category Archives: Python

Taking your PIL with py2exe

Leave a reply

Letting PIL and py2exe be friends

Escape from “cannot identify image file” hell

Summary

The Python Imaging Library (PIL) provides great image manipulation help for your python programs. Py2exe provides a smart way of turning a python script into a windows executable. There are times however when the resulting .exe will break if you don’t do the right thing.

My Problem

I’d written a Python script, openpilwithdiag.py, which read TIFF files and worked just fine when run through the Python interpreter.

from PIL import Image
im = Image.open("test.TIFF")
print im.getcolors()

I then used py2exe to convert the script to a .exe.  Aargh – when I went to run it I got an error :

IOError: cannot identify image file

It took a little digging around but it seems that when PIL constructs one of its PIL Image objects it searches a set of ‘image plugin’ files within the PIL installation. This is all good except that by the time py2exe has done it’s thing PIL (now nicely wrapped up inside the .exe) will be looking in the wrong place.

The Solution

Pleasantly simple – given all the blind alleys I looked down to start with ! I’d previously had nasty problems using TIFF files with PIL and I think I started looking at this expecting the answer to be really nasty !

Whatever file formats you want to use import the corresponding PIL plugin directly into the script so that the instantiation of Image can ‘see’ them. For my example that’s like this :

from PIL import Image
from PIL import TiffImagePlugin
im = Image.open("test.TIFF")
print im.getcolors()

Tried py2exe again and what do we get ?

C:\>openpilwithdiag.exe
[(37306, (76, 25, 12, 51)), (42810, (0, 0, 0, 255)), (1489484, (0, 0, 0, 0))]

Much better !

Plugin Details

The set of possible plugins may be found by looking for files named xImagePlugin.py (where x is the name of the supported format) within the sub-directory of your Python installation at :

<your python directory>\Lib\site-packages\PIL

A list of file formats PIL supports is seen in the appendix of the PIL Handbook

Postscript

It occurs to me that for anyone who’s never touched py2exe it might be worth posting the setup.py I was using to drive the py2exe process – so here it is :

from distutils.core import setup
import glob
import py2exe

setup(console=['openpilwithdiag.py'],
            data_files=[]
)

Sphinx Documentation Generator – Tutorial 2

Leave a reply

Sphinx – first project output

A series of tutorials on using the Sphinx Documentation system aimed at absolute beginners.

Summary

In this second part of my Sphinx Tutorial we use the ‘quickstart’ script provided with Sphinx to quickly produce a basic set of documentation source files.

Our First Sphinx Project

Sphinx has a great way to get you started and that’s the ‘quickstart’ script (you’ll find sphinx-quickstart-script.py in the Scripts directory of your Python installation). Quickstart walks you through a series of questions to produce a basic set of the files you’ll need to produce your documentation.

Quickstart is pretty easy to use and even more so when your aim is to produce something very basic (which is the aim of this tutorial).

We’ll just step through the more important bits here :

Specify where you want the Documentation to be created

Sphinx is going to create some files and a few directories so choose where you want those to be created :
Enter the root path for documentation.
> Root path for the documentation [.]: C:\data\src\Sphinx\Test1

Specify a name for the Documentation:

What ever name you choose will appear in various places in the documentation so choose something you’re happy with

The project name will occur in several places in the built documentation.
> Project name: Sphinx Tutorial
> Author name(s): Richard Shea

Specify a version for the Documentation:

Similarly you’ll get the version number appearing in various parts of the output documenation

> Project version: 1.0.0

Specify if you want any clever stuff:

Sphinx is able to do all sorts of clever stuff apart from interpreting your RST files into beautiful output. We don’t want any of that for the first part of the tutorial so say ‘no’ to all of this.

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]:
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:

Make it easy on yourself (at least to start with)

It’s perfectly reasonable to use build the Sphinx output by providing your own command line options but to get started with it’s helpful to allow Sphinx to help a little so say ‘yes’ to a .BAT or a makefile (depending on what’s your choice of poison).

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]:

The results of quickstart

So after all that what have we got ? Well we specified C:\data\src\Sphinx\Test1 as the output path and if we look in there we find we’ve got a build and a source directory (as well as the Makefile and make.bat we asked for). What we’re interested in to start with is source\index.rst.

Open it up in a text editor and you’ll see it looks like this :
.. Sphinx Tutorial documentation master file, created by
sphinx-quickstart on Sun Nov 1 18:08:19 2009.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to Sphinx Tutorial's documentation!
===========================================

Contents:

.. toctree::
:maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Next Steps

In the next part of this series, Sphinx – Absolute Beginners – Part 3, we’ll see how to make this file into either HTML or PDF output. In later parts of the series we’ll see how to use your existing Python code comments to produce automated documentation of your Python code.

Sphinx Documentation Generator – Tutorial 1

Leave a reply

Sphinx – Absolute Beginners – Part 1

A series of tutorials on using the Sphinx Documentation system aimed at absolute beginners

Summary

Sphinx is a great tool that makes it easy to create good looking documentation in a range of output formats. If you’re a Python programmer it also makes it easy to use your existing docstring comments to form the basis of your documentation.

I’ve found using Sphinx for the first time a little difficult as much of the documentation seems to assume you know certain things. This series of posts provides a tutorial for the absolute beginner.

Ground Rules (for impatient programmers)

Now at this stage there’s a couple of things that are well worth knowing !

  • Sphinx is good at auto-documenting Python code but that’s not its primary role. If you’re a Python programmer looking to auto-document your code it takes a while to understand that a lot of the facilities in Sphinx are nothing to do with what you’re after and that can be confusing.
  • In Sphinx-land ‘the source files’ refer to the documentation configuration files. This confused me for a while whenever the term ‘source files’ was used I thought it meant my python source files.

Getting Spinx Installed

The prerequisites part of the Sphinx doco does a good job here but in summary:

  • You want to have installed Python 2.4 or better
  • Grab the source from the Sphinx Python Project Page or …
  • … just use easy_install -U Sphinx

Next Steps

Sphinx has a great way to get you started and that’s the ‘quickstart’ script. In the next part of this tutorial series we’ll cover how to quickly and easily produce your first Sphinx project.