About Data Helpers
-------------------------

tgext.datahelpers is a collection of utilities to help manage stored data
in common web applications.

tgext.datahelpers contains:

- Validators to fetch objects from database by Id (both SQLA and Ming)
- Store Attachments by just declaring a Column in your model
- Store image and thumbnails by just declaring a Column in your model

Installing
-------------------------------

tgext.datahelpers can be installed both from pypi or from bitbucket::

    easy_install tgext.datahelpers

should just work for most of the users

Validators
--------------------------------

``tgext.datahelpers.validators`` provides the ``SQLAEntityConverter`` and
``MingEntityConverter`` that convert the given
parameter (which is expected to be the primary key of an object) to
the actually object itself::

    from tgext.datahelpers.validators import SQLAEntityConverter

    @expose()
    @validate({'doc':SQLAEntityConverter(Document)}, error_handler=index)
    def photo(self, doc):
        return redirect(doc.photo.url)

Utilities
-----------------------------------

``tgext.datahelpers.utils`` provides the ``slugify`` function to
generate slug urls for entities which are meaningful for users.

The generated slugs includes the entity id so that it can identify
unique elements making possible for EntityConverter validators
to support retrieving objects from the generated slug.

Sample usage::

    >>> from tgext.datahelpers.utils import slugify

    >>> entity = DBSession.query(Entity).get(5)
    >>> url = slugify(entity, entity.name)
    >>> print url
    'this-is-a-very-long-phrase-5'

Utility functions also provide a ``fail_with`` object which
can be used with turbogears @validate error_handler to report
a missing element or forbidden access::

    from tgext.datahelpers.validators import SQLAEntityConverter
    from tgext.datahelpers.utils import fail_with

    @expose()
    @validate({'doc':SQLAEntityConverter(Document)},
              error_handler=fail_with(404))
    def photo(self, doc):
        return redirect(doc.photo.url)

Entities Based Caching
-----------------------------------

``tgext.datahelpers.caching`` provides the ``@entitycached`` decorator
which can be used to cache methods (and helpers) based on a parameter
which is a Ming or SQLAlchemy entity.

Whenever the entity gets updated the cache is invalidated and the method
called again, otherwise calling the method will return the value from the cache.

To determine if the entity has changed it will try to retrieve the
``cache_key`` property of the entity, if not available a cache key
will be automatically generated using the primary key and ``updated_at``
property of the entity.

Sample usage::

    from tgext.datahelpers.caching import entitycached

    @entitycached('post')
    def render_post(post):
        return '<div>%s</div>' % post.html

    blog = ''.join(map(render_post, blog_posts))

``@entitycached`` decorator can also be used to cache any function by using
the ``tgext.datahelpers.caching.CacheKey`` object as a function argument instead
of a Ming/SQLAlchemy entity.

If you want to cache an SQLAlchemy query give a look at the ``sqla_merge`` option.

``@entitycached`` decorator supports also various options:

- ``expire`` - How long the cached value will be kept around, by default 3 days
- ``cache_type`` - Which type of cache to use, by default memory will be used
- ``namespace`` - The cache namespace, by default this is autogenerated by the cached class and method names
- ``sqla_merge`` - Whenever the cached function return value is a SQLAlchemy query.
    When this option is True you will always get the results instead of the query itself and the resulting
    objects will be merged back in to the currently existing TurboGears DBSession to avoid
    ``DetachedInstanceError`` exceptions.

Attachments
-----------------------------------

``tgext.datahelpers.fields`` provides the ``Attachment`` field for SQLAlchemy
to provide an easy and convenient way to store attachments.

The ``Attachment`` field will permit to assign files to the attribute
declared with ``Attachment`` type and will store a copy of the file on disk
as soon as the object is committed to the database.

The document field will provide a bunch of attributes you can use to
access the file:

- ``file`` - A file object pointing to the saved file
- ``filename`` - The name of the saved file
- ``url`` - Url from which the file is fetchable
- ``local_path`` - Local path of the file on disk

Files will be saved in ``tg.config['attachments_path']`` and url will be
generated using ``tg.config['attachments_url']``. By default those are set
at */public/attachments* and */attachments*.

The ``Attachment`` field accepts a *attachment_type* parameter which specifies
the kind of attachment that it is going to be saved. The default is
``tgext.datahelpers.fields.AttachedFile`` which just stores the file itself::

    from tgext.datahelpers.fields import Attachment
    class Document(DeclarativeBase):
        __tablename__ = 'document'

        uid = Column(Integer, autoincrement=True, primary_key=True)
        file = Column(Attachment)

    d = Document(file=open('/myfile.txt'))
    DBSession.add(d)
    DBSession.flush()
    DBSession.commit()

    d = DBSession.query(Document).first()
    print d.file.url

    '/attachments/747722ca-1a07-11e1-83fc-001ff3d72e6b/myfile.txt'

Apart from file objects also instances of ``cgi.FieldStorage`` can be assigned
to permit to quickly store uploaded files.

Image Attachments with Thumbnail
--------------------------------------

Using the ``tgext.datahelpers.fields.AttachedImage`` as the argument of the
``Attachment`` field it is possible to quickly store images with their thumbnail.

The resulting object will provide the same attributes as the generic Attachment one
adding two more thumbnail related properties:

- ``thumb_local_path`` - The local path of the image thumbnail
- ``thumb_url`` - The url of the thumbnail

Storing image with thumbnails is as easy as storing the file itself::

    from tgext.datahelpers.fields import Attachment, AttachedImage
    class Document(DeclarativeBase):
        __tablename__ = 'document'

        uid = Column(Integer, autoincrement=True, primary_key=True)
        image = Column(Attachment(AttachedImage))

    d = Document(image=open('/photo.jpg'))
    DBSession.add(d)
    DBSession.flush()
    DBSession.commit()

    d = DBSession.query(Document).first()
    print d.image.url
    '/attachments/d977144a-1a08-11e1-8131-001ff3d72e6b/aperto.tiff'
    print d.image.thumb_url
    'attachments/d977144a-1a08-11e1-8131-001ff3d72e6b/thumb.png'


Thumbnail Options
=======================================

By default thumbnails will be generated with size 128, 128 and in PNG format.
This can be changed by sublcassing the ``AttachedImage`` class and specifying
the ``thumbnail_size`` and ``thumbnail_format`` attributes::

    class BigThumbnailAttachedImage(AttachedImage):
        thumbnail_size = (320, 320)
        thumbnail_format = 'jpg'

    class Document(DeclarativeBase):
        __tablename__ = 'document'

        uid = Column(Integer, autoincrement=True, primary_key=True)
        image = Column(Attachment(BigThumbnailAttachedImage))