Package: tgext.datahelpers
About Data Helperstgext.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 modelStore image and thumbnails by just declaring a Column in your modelInstallingtgext.datahelpers can be installed both from pypi or from bitbucket:easy_install tgext.datahelpersshould just work for most of the usersValidatorstgext.datahelpers.validatorsprovides theSQLAEntityConverterandMingEntityConverterthat 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)Validators module provides also thevalidated_handlerutility which
makes possible to apply validation also to error_handlers.
Normally TurboGears would execute @validate based validation only when
the controller method is called through a request, when you use a controller
method as the error_handler of another method the error_handler @validate
gets skipped and arguments are passed as they are.Usingvalidated_handlerit is possible to change this behavior and
apply validation even to error_handlers:from tgext.datahelpers.validators import SQLAEntityConverter, validated_handler

@expose()
@validate({'doc':validators.Int(not_empty=True)},
          error_handler=index)
def next(self, doc):
    return dict(doc=doc+1)

@expose()
@validate({'doc':SQLAEntityConverter(Document)},
          error_handler=validated_handler(next))
def photo(self, doc):
    return redirect(doc.photo.url)In the previous example when calling /photo/3 if document 3 is not available
it would be retrieved the successive document by calling next. If validated_handler
gets removed from photo @validate you would get an error as doc wouldn’t be an integer.Utilitiestgext.datahelpers.utilsprovides theslugifyfunction 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. Addslugified=Trueoption to the entity converted to load
back an entity by its 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 afail_withobject 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, slugified=True)},
          error_handler=fail_with(404))
def photo(self, doc):
    return redirect(doc.photo.url)Entities Based Cachingtgext.datahelpers.cachingprovides the@entitycacheddecorator
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 thecache_keyproperty of the entity, if not available a cache key
will be automatically generated using the primary key andupdated_atproperty 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))@entitycacheddecorator can also be used to cache any function by using
thetgext.datahelpers.caching.CacheKeyobject as a function argument instead
of a Ming/SQLAlchemy entity.If you want to cache an SQLAlchemy query give a look at thesqla_mergeoption.@entitycacheddecorator supports also various options:expire- How long the cached value will be kept around, by default 3 dayscache_type- Which type of cache to use, by default memory will be usednamespace- The cache namespace, by default this is autogenerated by the cached class and method namessqla_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 avoidDetachedInstanceErrorexceptions.Attachmentstgext.datahelpers.fieldsprovides theAttachmentfield for SQLAlchemy
to provide an easy and convenient way to store attachments.TheAttachmentfield will permit to assign files to the attribute
declared withAttachmenttype 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 filefilename- The name of the saved fileurl- Url from which the file is fetchablelocal_path- Local path of the file on diskFiles will be saved intg.config['attachments_path']and url will be
generated usingtg.config['attachments_url']. By default those are set
at/public/attachmentsand/attachments.TheAttachmentfield accepts aattachment_typeparameter which specifies
the kind of attachment that it is going to be saved. The default istgext.datahelpers.fields.AttachedFilewhich 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 ofcgi.FieldStoragecan be assigned
to permit to quickly store uploaded files.Image Attachments with ThumbnailUsing thetgext.datahelpers.fields.AttachedImageas the argument of theAttachmentfield 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 thumbnailthumb_url- The url of the thumbnailStoring 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 OptionsBy default thumbnails will be generated with size 128, 128 and in PNG format.
This can be changed by sublcassing theAttachedImageclass and specifying
thethumbnail_sizeandthumbnail_formatattributes: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))