Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Dolmen thumbnailing library

Project Description

dolmen.thumbnailer is package specialized in Thumbnail generation. Using the mechanisms, it allows a pluggable and flexible thumbnail storage.


The thumbnailer is the component in charge of effectively scaling down the image. This component is defined by the IThumbnailer interface:

>>> from dolmen.thumbnailer import IThumbnailer
>>> print IThumbnailer['scale'].__doc__
Returns a StringIO that is a data representation of an image,
scaled down to the given size.

Out-of-the-box, an IThumbnailer implementation is proposed, as an adapter. In order to test it, we need both a model and an image. The model will serve as a base for the adaptation:

>>> fd = open(IMAGE_PATH, 'r')
>>> data =
>>> fd.close()

>>> class BasicContent(object):
...   pass
>>> mycontext = BasicContent()

>>> thumbnailer = IThumbnailer(mycontext)
>>> thumbnailer
<dolmen.thumbnailer.components.ScaleThumbnailer object at ...>

We can now test the scaling method. This method, as specified in the IThumbnailer interface, requires the data, given as a PIL Image, and a scale (a tuple of width and height):

>>> from PIL import Image
>>> from cStringIO import StringIO

>>> image =
>>> scale = thumbnailer.scale(image, (100, 100))
>>> scale
<cStringIO.StringO object at ...>

(100, 100)

The scale method returns a cStringIO.StringIO that can be used to recreate a PIL.Image or to save in an object, as a binary string.

This implementation of IThumbnailer is not modifying the original image:

>>> image.size
(280, 280)

The thumbnailer handles some basic errors for you:

>>> thumbnailer.scale(None, (100, 100))
Traceback (most recent call last):
TypeError: Scaling can only occur using a PIL Image

>>> thumbnailer.scale(image, None)
Traceback (most recent call last):
ValueError: Size must be a (width, height) tuple


The next component, the Miniaturizer, will query a named IThumbnailer for each thumbnail scale, using the scale name. If no named IThumbnailer is found, it fallbacks to the base one.


The Miniaturizer is the component in charge of the thumbnailing policy. It handles the name and size, the storage class used as the file-wrapper and provides a collection of methods to manage the generation, retrieval and deletion of the thumbnails.

Default policy

The default policy is defined in the interface IImageMiniaturizer, implemented by the Miniaturizer component. Let’s have a quick overview:

>>> from dolmen.thumbnailer import IImageMiniaturizer

>>> print IImageMiniaturizer['scales'].default
{'large': (700, 700), 'mini': (250, 250), 'small': (128, 128), 'preview': (400, 400), 'thumb': (150, 150)}

>>> print IImageMiniaturizer['factory'].default
<class 'dolmen.file.file.NamedFile'>

Storage and adapter

Out-of-the-box, dolmen.thumbnailer provides a IImageMiniaturizer implementation as an adapter. While it uses the default scales and factory, it queries a component for the storage. This storage is a named ‘thumbnail’, in order to write the store the thumbnails in the object annotations.

This means, we need a IAttributeAnnotatable object:

>>> miniaturizer = IImageMiniaturizer(mycontext)
Traceback (most recent call last):
TypeError: ('Could not adapt', <BasicContent object at ...>, <InterfaceClass dolmen.thumbnailer.interfaces.IImageMiniaturizer>)

>>> from zope.annotation import IAttributeAnnotatable
>>> from zope.interface import alsoProvides

>>> alsoProvides(mycontext, IAttributeAnnotatable)
>>> miniaturizer = IImageMiniaturizer(mycontext)
>>> miniaturizer
<dolmen.thumbnailer.components.Miniaturizer object at ...>

Now we obtain a Miniaturizer object. We can verify its conformity with the interface that describes it:

>>> from zope.interface import verify
>>> verify.verifyObject(IImageMiniaturizer, miniaturizer)

<dolmen.thumbnailer.components.ThumbnailStorage object at ...>

>>> from import IDelegatedStorage
>>> IDelegatedStorage.providedBy(


The Miniaturizer assumes that your data is stored on a field of the object. The methods provided by the component will use the fieldname to trigger their action.

Let’s add an image attribute to our content object:

>>> from dolmen.file import file
>>> mycontext.image = file.NamedFile(data=data)
>>> mycontext.image
<dolmen.file.file.NamedFile object at ...>

Our image is persisted on our object, in an attribute called ‘image’. Let’s trigger the thumbnails generation:

>>> miniaturizer.generate(fieldname="image")

The return value is a boolean representing the success of the generation. Let’s have a look at our storage, after the generation:

>>> list(
['image.large', '', 'image.preview', 'image.small', 'image.thumb']

Some errors are handled for you:

>>> miniaturizer.generate(fieldname="nonexisting")

>>> miniaturizer.generate(fieldname="__class__")
Traceback (most recent call last):
IOError: cannot identify image file


The thumbnails can be retrieved easily, using the scale name and the field name:

>>> scale = miniaturizer.retrieve('mini', fieldname="image")
>>> scale
<dolmen.file.file.NamedFile object at ...>

As we can see, the thumbnails data is wrapped in a dolmen.file.file.NamedFile object, which is the factory defined in your default policy:

>>> isinstance(scale, IImageMiniaturizer['factory'].default)

The Miniaturizer can fetch a thumbnail using a “fieldname.scalename” key:

>>> print miniaturizer['']
<dolmen.file.file.NamedFile object at ...>

>>> print miniaturizer.get('image.small')
<dolmen.file.file.NamedFile object at ...>

>>> print miniaturizer.get('image.nonexistance')
>>> print miniaturizer.get('image.nonexistance', 'nothing !')
nothing !

As usual, some error situations are handled for you:

>>> print miniaturizer.retrieve('manfred', fieldname="image")
>>> print miniaturizer.retrieve('manfred', fieldname="not there")


The deletion action will use the fieldname to delete all the thumbnails generated for the given field:

>>> miniaturizer.delete(fieldname="image")
>>> list(

Access and security

The thumbnails are generated and stored. Logically, we now want to publish the thumbnails in order to make them accessible through a URL. The dolmen.thumbnailer provides a traverser based on dolmen.file.access.FilePublisher:

>>> from zope.component import getMultiAdapter
>>> from zope.publisher.browser import TestRequest
>>> from zope.traversing.interfaces import ITraversable

>>> miniaturizer.generate(fieldname="image")

>>> request = TestRequest()
>>> traverser = getMultiAdapter((mycontext, request),
...                             ITraversable, name='thumbnail')

The basic permission used to check the availability of the data is zope.View. We set up two principals to test this. ‘jason’ is a logged in member with no rights, while ‘judith’ has the zope.View permission granted:

>>> import as security
>>> from import Principal, Participation

>>> judith = Principal('zope.judith', 'Judith')
>>> jason = Principal('zope.jason', 'Jason')

We create the interaction and try to traverse to our thumbnail:

>>> security.newInteraction(Participation(jason))
>>> traverser.traverse('image.small')
Traceback (most recent call last):
Unauthorized: image.small
>>> security.endInteraction()

It fails. An Unauthorized Error is raised. We now try with Judith:

>>> security.newInteraction(Participation(judith))
>>> traverser.traverse('image.small')
<dolmen.file.access.FilePublisher object at ...>
>>> security.endInteraction()

Our thumbnail is returned, wrapped in a FilePublisher view, which is ready to be rendered (see dolmen.file access documentation for more information).


0.3 (2010-02-27)

  • Cleaned dependencies. We no longer have dependencies.
  • We now use dolmen.file.file.File as base files for the thumbnails.

0.2.3 (2010-02-19)

  • Corrected the PIL version to 1.1.7

0.2.2 (2010-02-19)

  • Updated dependency : PILwoTK to PIL.

0.2.1 (2009-10-25)

  • Updated to the latest version of dolmen.field.

0.2 (2009-10-23)

  • Now thumbnails can be named, if the factory implements dolmen.file.INamedFile.
  • Corrected a bug where the specified mimeType was not a valid one.

0.1 (2009-10-21)

  • Initial release
Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
dolmen.thumbnailer-0.3.tar.gz (17.5 kB) Copy SHA256 Checksum SHA256 Source Feb 27, 2010

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting