Hvild¶

Hvild is a collection of generic or “cookie-cutter” methods that help you implement CRUD functionality for your services quickly.

The basic concept is that instead of repeating this everywhere you need to implement insert functionality:

@ferris3.auto_method(returns=PostMessage)
def insert(cls, request=(PostMessage,)):
    entity = ferris3.messages.deserialize(Post, request)
    entity.put()
    msg = ferris3.messages.serialize(PostMessage, entity)
    return msg

You would just re-use the generic version:

insert = ferris3.hvild.insert(Post)

You can implement a complete CRUD API in just a few lines:

@ferris3.auto_service
class PostsService(ferris3.Service):
    list = ferris3.hvild.paginated_list(Post, name="list")
    get = ferris3.hvild.get(Post)
    insert = ferris3.hvild.insert(Post)
    update = ferris3.hvild.update(Post)
    delete = ferris3.hvild.delete(Post)

Generic method arguments¶

All of the generic methods require at least the Model parameter. The methods will then use model_message() and list_message() where needed to fill in the gaps.

You can of course provide your own messages if desired. For example, if we wanted to create a list of posts that only contained the title:

PostTitleOnlyMessage = ferris3.model_message(Post, only=('title',))

...

title_only_list = ferris3.hvild.list(Post, Message=PostTitleOnlyMessage, name="title_only_list")

Additionally, all of the methods accept the name parameter to allow you to control what the API method name is when exposed to Google Cloud Endpoints. This is very important in the case of multiple uses of the generic method, for example:

full_list = ferris3.hvild.list(Post, Message=PostTitleOnlyMessage, name="full_list")
title_only_list = ferris3.hvild.list(Post, Message=PostTitleOnlyMessage, name="title_only_list")

Without specifying name, these two functions would have the name API method name and would cause an error.

Generic methods¶

ferris3.hvild.list(Model, Message=None, ListMessage=None, query=None, name='list')[source]¶: Implements a very simple list method for the given model.

Warning

No limiting logic is applied to the query so this will attempt to get all results. It is almost always preferable to use paginated_list().

ferris3.hvild.paginated_list(Model, Message=None, ListMessage=None, query=None, limit=50, name='paginated_list')[source]¶: Similar to list() but returns results in pages of limit size.

ferris3.hvild.searchable_list(Model=None, Message=None, ListMessage=None, limit=50, index=None, name='search')[source]¶: Implements a search method by using the search module. This method assumes you are using the common use case of indexing datastore entities and does not work for generic searches.

ferris3.hvild.get(Model, Message=None, name='get')[source]¶: Implements a straightfoward get method by using the urlsafe version of the entity’s key.

ferris3.hvild.insert(Model, Message=None, name='insert')[source]¶: Implements the insert method. The request fields are determined by the Message parameter.

ferris3.hvild.update(Model, Message=None, name='update')[source]¶: Implements the update method. The item updated is determined by the urlsafe key of that item. The request fields are determined by the Message parameter.

ferris3.hvild.delete(Model, name='delete')[source]¶: Implements a straightfoward delete method by using the urlsafe version of the entity’s key.

Under the hood¶

These generic methods are intended to reduce redundancy and code reptition and not to serve all use cases. None of these methods are intended to be difficult to understand or re-implement. We encourage you to read the source code and create your own versions of the generic methods to suit your application’s need.