tipfy.ext.db¶

This module provides several utilities to work with google.appengine.ext.db, including serialization functions, decorators and useful extra db.Property classes.

See the extension wiki page.

`db.Model` utilities¶

tipfy.ext.db.get_protobuf_from_entity(entities)¶

Converts one or more db.Model instances to encoded Protocol Buffers.

This is useful to store entities in memcache, and preferable than storing the entities directly as it has slightly better performance and avoids crashes when unpickling (when, for example, the entity class is moved to a different module).

Cached protobufs can be de-serialized using get_entity_from_protobuf().

Example usage:

from google.appengine.api import memcache
from tipfy.ext.db import get_protobuf_from_entity

# Inside a handler, given that a MyModel model is defined.
entity = MyModel(key_name='foo')
entity.put()

# Cache the protobuf.
memcache.set('my-cache-key', get_protobuf_from_entity(entity))

This function derives from Nick’s Blog.

Parameters:	entities – A single or a list of `db.Model` instances to be serialized.
Returns:	One or more entities serialized to Protocol Buffer (a string or a list).

tipfy.ext.db.get_entity_from_protobuf(data)¶

Converts one or more encoded Protocol Buffers to db.Model instances.

This is used to de-serialize entities previously serialized using get_protobuf_from_entity(). After retrieving an entity protobuf from memcache, this converts it back to a db.Model instance.

Example usage:

from google.appengine.api import memcache
from tipfy.ext.db import get_entity_from_protobuf

# Get the protobuf from cache and de-serialize it.
protobuf = memcache.get('my-cache-key')
if protobuf:
    entity = get_entity_from_protobuf(protobuf)

This function derives from Nick’s Blog.

Parameters:	data – One or more entities serialized to Protocol Buffer (a string or a list).
Returns:	One or more entities de-serialized from Protocol Buffers (a `db.Model` inatance or a list of `db.Model` instances).

tipfy.ext.db.get_reference_key(entity, prop_name)¶

Returns a encoded key from a db.ReferenceProperty without fetching the referenced entity.

Example usage:

from google.appengine.ext import db
from tipfy.ext.db import get_reference_key

# Set a book entity with an author reference.
class Author(db.Model):
    name = db.StringProperty()

class Book(db.Model):
    title = db.StringProperty()
    author = db.ReferenceProperty(Author)

author = Author(name='Stephen King')
author.put()

book = Book(key_name='the-shining', title='The Shining', author=author)
book.put()

# Now let's fetch the book and get the author key without fetching it.
fetched_book = Book.get_by_key_name('the-shining')
assert str(author.key()) == str(get_reference_key(fetched_book,
    'author'))

Parameters:	entity – A `db.Model` instance. prop_name – The name of the `db.ReferenceProperty` property.
Returns:	An entity Key, as a string.

tipfy.ext.db.populate_entity(entity, **kwargs)¶

Sets a batch of property values in an entity. This is useful to set multiple properties coming from a form or set in a dictionary.

Example usage:

from google.appengine.ext import db
from tipfy.ext.db import populate_entity

class Author(db.Model):
    name = db.StringProperty(required=True)
    city = db.StringProperty()
    state = db.StringProperty()
    country = db.StringProperty()

# Save an author entity.
author = Author(key_name='stephen-king', name='Stephen King')
author.put()

# Now let's update the record.
author = Author.get_by_key_name('stephen-king')
populate_entity(author, city='Lovell', state='Maine', country='USA')
author.put()

Parameters:	entity – A `db.Model` instance. kwargs – Keyword arguments for each entity property value.
Returns:	None.

tipfy.ext.db.get_property_dict(entities)¶

Returns a dictionary with all the properties and values in an entity.

Parameters:	entities – One or more `db.Model` instances.
Returns:	A dictionary or a list of dictionaries mapping property names to values.

tipfy.ext.db.get_or_insert_with_flag(model, key_name, **kwargs)¶

Transactionally retrieve or create an instance of db.Model class.

This is the same as db.Model.get_or_insert(), but it returns a tuple (entity, flag) to indicate if the entity was inserted. If the entity is inserted, the flag is True, otherwise it is False.

Example usage:

from google.appengine.ext import db
from tipfy.ext.db import get_or_insert_with_flag

class Author(db.Model):
    name = db.StringProperty()

author, is_new = get_or_insert_with_flag(Author, 'stephen-king',
    name='Stephen King')

Parameters:	model – A `db.Model` class to fetch or create an entity. key_name – The entity’s key name. kwargs – Keyword argumens to create an entity, if it doesn’t exist yet.
Returns:	A tuple `(entity, flag)`, where entity is the fetched or inserted entity and flag is a boolean True if the entity was inserted or False if it existed already.

tipfy.ext.db.get_or_404(key)¶

Returns a model instance fetched by key or raises a 404 Not Found error.

Example usage:

from tipfy import RequestHandler
from tipfy.ext.db import get_or_404
from mymodels import Contact

class EditContactHandler(RequestHandler):
    def get(self, **kwargs):
        contact = get_or_404(Contact, kwargs['contact_key'])

        # ... continue processing contact ...

This function derives from Kay.

Parameters:	key – An encoded `db.Key` (a string).
Returns:	A `db.Model` instance.

tipfy.ext.db.get_by_id_or_404(model, id, parent=None)¶

Returns a model instance fetched by id or raises a 404 Not Found error.

Example usage:

from tipfy import RequestHandler
from tipfy.ext.db import get_by_id_or_404
from mymodels import Contact

class EditContactHandler(RequestHandler):
    def get(self, **kwargs):
        contact = get_by_id_or_404(Contact, kwargs['contact_id'])

        # ... continue processing contact ...

This function derives from Kay.

Parameters:	model – A `db.Model` class to load an entity. id – An id from a `db.Key` (an integer). parent – The parent entity for the requested entities, as a Model instance or Key instance, or None (the default) if the requested entities do not have a parent.
Returns:	A `db.Model` instance.

tipfy.ext.db.get_by_key_name_or_404(model, key_name, parent=None)¶

Returns a model instance fetched by key name or raises a 404 Not Found error.

Example usage:

from tipfy import RequestHandler
from tipfy.ext.db import get_by_key_name_or_404
from mymodels import Contact

class EditContactHandler(RequestHandler):
    def get(self, **kwargs):
        contact = get_by_key_name_or_404(Contact,
            kwargs['contact_key_name'])

        # ... continue processing contact ...

This function derives from Kay.

Parameters:	model – A `db.Model` class to load an entity. key_name – A key name from a `db.Key` (a string). parent – The parent entity for the requested entities, as a Model instance or Key instance, or None (the default) if the requested entities do not have a parent.
Returns:	A `db.Model` instance.

Decorators¶

tipfy.ext.db.retry_on_timeout(retries=3, interval=1.0, exponent=2.0)¶

A decorator to retry a function that performs db operations in case a db.Timeout exception is raised.

Example usage:

from tipfy import RequestHandler
from tipfy.ext.db import retry_on_timeout
from mymodels import Contact

class EditContactHandler(RequestHandler):
    def get(self, **kwargs):
        # ... do the get stuff ...
        # ...
        pass

    @retry_on_timeout()
    def post(self, **kwargs):
        # ... load entity and process form data ...
        # ...

        # Save the entity. This will be retried in case of timeouts.
        entity.put()

This function derives from Kay.

Parameters:	retries – An integer value for the number of retries in case `db.Timeout` is raised. interval – A float value for the number of seconds between each interval. exponent – A float exponent to be applied to each retry interval. For example, if `interval` is set to 0.2 and exponent is 2.0, retries intervals will be in seconds: 0.2, 0.4, 0.8, etc.
Returns:	A decorator wrapping the target function.

tipfy.ext.db.load_entity(model, kwarg_old, kwarg_new=None, fetch_mode=None)¶

A decorator that takes an entity key, key name or id from the request handler keyword arguments, load an entity and add it to the arguments. If not found, a NotFound exception is raised.

Example usage:

from tipfy import RequestHandler
from tipfy.ext.db import load_entity
from mymodels import Contact

class EditContactHandler(RequestHandler):
    @load_entity(Contact, 'contact_id', 'contact', 'id')
    def get(self, **kwargs):
        # kwargs['contact_id'] is used to load a Contact entity using
        # get_by_id(). The entity is then added to kwargs['contact'].
        pass

    @load_entity(Contact, 'contact_id', 'contact', 'id')
    def post(self, **kwargs):
        # kwargs['contact_id'] is used to load a Contact entity using
        # get_by_id(). The entity is then added to kwargs['contact'].
        pass

Parameters:

model – A db.Model class to fetch an entity from.
kwarg_old – The keyword argument, passed by the routing system to the request handler, that contains the key, id or key_name of the entity to be loaded. For example, contact_key, contact_id or contact_key_name.
kwarg_new – The new keyword argument to be passed to the request handler. This keyword is added to the arguments. If not set, uses kwarg_old as base, removing the fetch mode sufix. For example, contact.
fetch_mode – The fetch mode. Can be either key, id or key_name, to fetch using db.Model.get(), db.Model.get_by_id() or db.Model.get_by_key_name(), respectively. If not set, it will check if kwargs_old ends with _key, _id or _key_name to guess the fetch mode.

Returns:

A decorator wrapping the target tipfy.RequestHandler method.

Extra `db.Property` classes¶

class tipfy.ext.db.EtagProperty(prop, *args, **kwargs)¶

Automatically creates an ETag based on the value of another property.

Note: the ETag is only set or updated after the entity is saved.

Example usage:

from google.appengine.ext import db
from tipfy.ext.db import EtagProperty

class StaticContent(db.Model):
    data = db.BlobProperty()
    etag = EtagProperty(data)

This class derives from aetycoon.

class tipfy.ext.db.JsonProperty(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None, indexed=True)¶

Stores a value automatically encoding to JSON on set and decoding on get.

Example usage:

>>> class JsonModel(db.Model):
... data = JsonProperty()
>>> model = PickleModel()
>>> model.data = {"foo": "bar"}
>>> model.data
{'foo': 'bar'}
>>> model.put() 
datastore_types.Key.from_path(u'PickleModel', ...)
>>> model2 = PickleModel.all().get()
>>> model2.data
{'foo': 'bar'}

class tipfy.ext.db.PickleProperty(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None, indexed=True)¶

A property for storing complex objects in the datastore in pickled form.

Example usage:

>>> class PickleModel(db.Model):
... data = PickleProperty()
>>> model = PickleModel()
>>> model.data = {"foo": "bar"}
>>> model.data
{'foo': 'bar'}
>>> model.put() 
datastore_types.Key.from_path(u'PickleModel', ...)
>>> model2 = PickleModel.all().get()
>>> model2.data
{'foo': 'bar'}

This class derives from aetycoon.

class tipfy.ext.db.SlugProperty(prop, max_length=None, *args, **kwargs)¶

Automatically creates a slug (a lowercase string with words separated by dashes) based on the value of another property.

Note: the slug is only set or updated after the entity is saved.

Example usage:

from google.appengine.ext import db
from tipfy.ext.db import SlugProperty

class BlogPost(db.Model):
    title = db.StringProperty()
    slug = SlugProperty(title)

This class derives from aetycoon.

class tipfy.ext.db.TimezoneProperty(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None, indexed=True)¶: Stores a timezone value.

← tipfy.ext.blobstore | tipfy.ext.debugger →

tipfy.ext.db¶

`db.Model` utilities¶

Decorators¶

Extra `db.Property` classes¶

Table Of Contents

All Topics

This Page

tipfy.ext.db¶

db.Model utilities¶

Decorators¶

Extra db.Property classes¶

Table Of Contents

All Topics

This Page

`db.Model` utilities¶

Extra `db.Property` classes¶