Datastore

Ferris provides several supplemental utilities on top of the NDB Datastore API. These utilities are intended to complement the items in the google.appengine.ext.ndb package. Items that share the same name are intended to be drop-in replacements.

The Model Class

Ferris includes a model class that inherits from ndb.Model and adds some additional functionality. Use of the Ferris model is completely optional and most Ferris functionality works with standard ndb.Model objects.

class ferris3.ndb.Model(*args, **kwds)[source]

ndb.Model subclass that supports easier callbacks and behaviors.

You define these models in the exact same way as you do with ndb:

import ferris3
from google.appengine.ext import ndb

class Post(ferris3.ndb.Model):
    title = ndb.StringProperty()
    author = ndb.StringProperty()

Callbacks

The Model class also provides aliases for the callback methods. You can override these methods in your Model and they will automatically be called after their respective action.

Model.before_put(self)[source]

Called before an item is saved.

Parameters:self – refers to the item that is about to be saved
Note:self.key is invalid if the current item has never been saved
Model.after_put(self, key)[source]

Called after an item has been saved.

Parameters:
  • self – refers to the item that has been saved
  • key – refers to the key that the item was saved as
classmethod Model.before_get(cls, key)[source]

Called before an item is retrieved. Note that this does not occur for queries.

Parameters:key – Is the key of the item that is to be retrieved.
classmethod Model.after_get(cls, key, item)[source]

Called after an item has been retrieved. Note that this does not occur for queries.

Parameters:
  • key – Is the key of the item that was retrieved.
  • item – Is the item itself.
classmethod Model.before_delete(cls, key)[source]

Called before an item is deleted.

Parameters:key – is the key of the item that is about to be deleted. It is okay to get() this key to interogate the properties of the item.
classmethod Model.after_delete(cls, key)[source]

Called after an item is deleted.

Parameters:key – is the key of the item that was deleted. It is not possible to call get() on this key.

These methods are useful for replicating database triggers, enforcing application logic, validation, search indexing, and more.

Behaviors

Behaviors are ways of packaging up related callbacks into reusable components. For example, you may write a behavior that notifies the creator of an item when their item is deleted. You may attach this behavior to multiple models. For example, a behavior might look like this:

class NotifyOnDelete(ferris3.ndb.Behavior):
    def before_delete(self, key):
        item = key.get()
        send_delete_notification(item.author, item.title)

This behavior can be attached to any model that has an author and title field:

class Post(ferris3.ndb.Model):
    class Meta:
        behaviors = (NotifyOnDelete,)

    title = ndb.StringProperty()
    author = ndb.StringProperty()

Behaviors can be combined and each behavior’s callbacks are triggered along with the model’s. For example if you wanted to use NotifyOnDelete as well as a new behavior like FixTitle:

class Post(ferris3.ndb.Model):
    class Meta:
        behaviors = (NotifyOnDelete, FixTitle)

By combining behaviors you can create models with deep logic out of small, discrete building blocks.

class ferris3.ndb.Behavior(Model)[source]

Behaviors allow you to encapsulate callbacks into discrete units that can be combined together.

Behavior.before_put(instance)[source]
Behavior.after_put(instance)[source]
Behavior.before_get(key)[source]
Behavior.after_get(item)[source]
Behavior.before_delete(key)[source]
Behavior.after_delete(key)[source]