tgext.datahelpers 0.2.1

关于数据辅助工具

tgext.datahelpers 是一组帮助管理常见Web应用程序中存储数据的实用工具。

tgext.datahelpers 包含

• 通过Id从数据库获取对象的有效器（SQLA和Ming）

• 通过在模型中声明一个列即可存储附件

• 通过在模型中声明一个列即可存储图像和缩略图

安装

tgext.datahelpers 可以从pypi或从bitbucket安装

easy_install tgext.datahelpers

对于大多数用户应该可以正常工作

验证器

tgext.datahelpers.validators 提供了 SQLAEntityConverter 和 MingEntityConverter，可以将给定的参数（预期为对象的主键）转换为实际的对象本身

from tgext.datahelpers.validators import SQLAEntityConverter

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

验证器模块还提供了一个 validated_handler 工具，该工具使得在错误处理器上也应用验证成为可能。通常，TurboGears 只会在控制器方法通过请求调用时执行 @validate 基于的验证，当您将控制器方法用作另一个方法的错误处理器时，错误处理器 @validate 被跳过，参数按原样传递。

使用 validated_handler，可以改变这种行为，并将验证应用于错误处理器。

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)

在前一个示例中，当调用 /photo/3 时，如果文档 3 不可用，它会通过调用 next 获取后续文档。如果从 photo @validate 中移除 validated_handler，您将得到一个错误，因为 doc 不会是整数。

实用工具

tgext.datahelpers.utils 提供了 slugify 函数，用于生成对用户有意义的实体的缩略 URL。

生成的缩略 URL 包括实体 ID，这样它可以识别唯一元素，使实体转换器验证器能够支持从生成的缩略 URL 中检索对象。将 slugified=True 选项添加到转换的实体中，可以通过其缩略 URL 加载回实体。

示例用法

>>> 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'

实用工具函数还提供了一个 fail_with 对象，可以与 turbogears @validate 错误处理器一起使用，以报告缺少的元素或禁止访问。

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)

基于实体的缓存

tgext.datahelpers.caching 提供了 @entitycached 装饰器，该装饰器可以用于根据 Ming 或 SQLAlchemy 实体缓存方法（和辅助函数）。

每当实体被更新时，缓存将被无效化，并再次调用该方法，否则调用该方法将返回缓存中的值。

为了确定实体是否已更改，它将尝试检索实体的 cache_key 属性，如果不可用，则将自动使用实体的主键和 updated_at 属性生成一个缓存键。

示例用法

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 装饰器还可以使用 tgext.datahelpers.caching.CacheKey 对象作为函数参数而不是 Ming/SQLAlchemy 实体来缓存任何函数。

如果您想缓存一个 SQLAlchemy 查询，请查看 sqla_merge 选项。

@entitycached 装饰器还支持各种选项

• expire - 缓存值将保持多久，默认为 3 天

• cache_type - 要使用的缓存类型，默认使用内存缓存

• namespace - 缓存命名空间，默认情况下，这由缓存的类和方法名称自动生成

• sqla_merge - 当缓存函数的返回值是 SQLAlchemy 查询时。

  当此选项为 True 时，您将始终获得结果而不是查询本身，并将结果对象合并回当前存在的 TurboGears DBSession，以避免 DetachedInstanceError 异常。

附件

tgext.datahelpers.fields 为 SQLAlchemy 提供了 Attachment 字段，以提供一种简单方便的方式来存储附件。

Attachment 字段允许将文件分配给声明为 Attachment 类型的属性，并在对象提交到数据库后立即在磁盘上存储文件的副本。

文档字段将提供一些属性，您可以使用这些属性来访问文件

• file - 指向已保存文件的文件对象

• filename - 已保存文件的名称

• url - 文件可获取的URL

• local_path - 磁盘上文件的本地路径

文件将保存在tg.config['attachments_path']，并使用tg.config['attachments_url']生成URL。默认情况下，这些设置为/public/attachments和/attachments。

附件字段接受一个attachment_type参数，用于指定将要保存的附件类型。默认是tgext.datahelpers.fields.AttachedFile，它仅存储文件本身。

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'

除了文件对象外，还可以将cgi.FieldStorage实例分配给附件字段，以快速存储上传的文件。

带缩略图的图片附件

使用tgext.datahelpers.fields.AttachedImage作为附件字段的参数，可以快速存储带有缩略图的图片。

生成的对象将提供与通用附件相同的属性，并增加两个与缩略图相关的属性。

• thumb_local_path - 图片缩略图的本地路径

• thumb_url - 缩略图的URL

存储带有缩略图的图片与存储文件本身一样简单

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'

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))