[Image-SIG] Clarifying Image.info

[Andrew M. Kuchling]

The .info attribute of the Image class is vaguely defined, and only
imperfectly supported.  .info is a dictionary that's sometimes used
for storing image comments and other metadata; on other occasions,
it's used for internal functions by a given en/decoder.

For instance, a while back I posted a patch to the PNG plug-in that
writes out the contents of .info{} as text chunks.  However, the PNG
code sets info['gamma'] to a gamma-correction value, so I have to
exclude it when writing out text chunks.  The GIF module sets
info['version'] to a string like 'GIF87a', and info['background'] to
an integer (presumably the index of the background colour); my patch
will need to be changed to exclude those keys, too.

Using .info for both comments and various bits of private data mixes
two different purposes in the same data structure.  I propose,
therefore, that these two purposes be separated, by creating a new
attribute of Image objects such as .comments or .metadata (I'm vague
on the name).

This new attribute would hold textual comments, and *only* textual
comments; image plug-ins would make an effort to incorporate this data
when saving a new image.  A plug-in might either only handle certain
keys, or might handle everything in the dictionary.  For example, if
an image format has a single field for a comment, the PIL plug-in
might only write out .comments['comment'], ignoring other keys.  On
the other hand, PNG text chunks contain key/value pairs, so the
plug-in could just iterate over them.

I think this is important, because in many applications where Python
scripts will be doing image processing automatically, it's useful to
be able to reliably add metadata; for example, a graph might contain
info about the parameters used to draw it, or, in my microscope
application, an image will hold metadata about the time, microscope
settings, process step with which to associate this image, etc.

I'm not sure how to introduce this change into PIL in a
backwards-compatible way.

Thoughts, anyone?

-- 
A.M. Kuchling			http://starship.python.net/crew/amk/
We were here before any other city that now stands. And we will sing the
funeral songs that are sung for cities for them when they die.
    -- The role of the Necropolis Litharge, in SANDMAN #55: "Cerements"