source: main/waeup.sirp/trunk/src/waeup/sirp/image/README.txt @ 6509

waeup.sirp.image -- handling image files
========================================

The image file widget is built on top of the :class:`WAeUPImageFile` object::

  >>> from waeup.sirp.image import WAeUPImageFile
  >>> file = WAeUPImageFile('foo.jpg', 'mydata')
  >>> file.filename
  'foo.jpg'
  >>> file.data
  'mydata'
  >>> file.size
  6
  >>> f = file.file
  >>> f.read()
  'mydata'

We can also create WAeUPImageFile objects from file-like objects::

  >>> from StringIO import StringIO
  >>> from zope import component
  >>> from hurry.file.interfaces import IFileRetrieval
  >>> fileretrieval = component.getUtility(IFileRetrieval)
  >>> file = fileretrieval.createFile('bar.jpg', StringIO('test data'))
  >>> file.filename
  'bar.jpg'
  >>> file.size
  9
  >>> file.data
  'test data'
  >>> f = file.file
  >>> f.read()
  'test data'

The WAeUPImageFile object normally stores the file data using ZODB
persistence. For better efficiency, each file is stored in a Blob.
`ImageFile` field
-----------------

As every other field (most of them are defined in :mod:`zope.schema`)
`ImageFile` can be used in interfaces to tell, that the associated
attribute should be -- an image file.

The `ImageFile` field accepts only certain content types:

  >>> from waeup.sirp.image.schema import ImageFile
  >>> from zope.publisher.browser import TestRequest
  >>> field = ImageFile(__name__='foo', title=u'Foo')
  >>> field.validate('asd')
  Traceback (most recent call last):
  ...
  WrongType: ('asd', <class 'waeup.sirp.image.image.WAeUPImageFile'>, 'foo')

which means: `ImageFile` fields should better contain
:class:`WAeUPImageFile` instances.

We can store normal :class:`WAeUPImageFile` instances:

  >>> field.validate(WAeUPImageFile('bar.jpg', 'data')) is None
  True

The `ImageFile` field supports min and max values:

  >>> field = ImageFile(__name__='foo', title=u'Foo')
  >>> hasattr(field, 'min_size')
  True

  >>> hasattr(field, 'max_size')
  True

By default both attributes are set to ``None``:

  >>> field.min_size is field.max_size is None
  True

But we can set them:

  >>> field = ImageFile(__name__='bar', title=u'Bar',
  ...                   min_size=5, max_size=12)

and while these values are okay then:

  >>> field.validate(
  ...     WAeUPImageFile('bar.jpg', '123456789012')) is None
  True

  >>> field.validate(
  ...     WAeUPImageFile('bar.jpg', '12345')) is None
  True

the following are not:

  >>> field.validate(
  ...     WAeUPImageFile('bar.jpg', '1234567890123'))
  Traceback (most recent call last):
  ...
  TooBig: ('bar.jpg', '13 bytes (max: 12 bytes)')

  >>> field.validate(
  ...     WAeUPImageFile('bar.jpg', '1234'))
  Traceback (most recent call last):
  ...
  TooSmall: ('bar.jpg', '4 bytes (min: 5 bytes)')