google.appengine.api.prospective_search.prospective_search module

Summary

ProspectiveSearch API.

A service that enables AppEngine apps to match queries to documents.

Functions defined in this module:

subscribe: Add a query to set of matching queries. unsubscribe: Remove query from set of matching queries. get_subscription: Retrieves subscription with particular id. list_subscriptions: Lists subscriptions on a particular topic. list_topics: Lists topics that have subscriptions. match: Match all subscribed queries to document.

Contents

google.appengine.api.prospective_search.prospective_search.get_document(request)source

Decodes document from prospective_search result POST request.

Args:

request: received POST request

Returns:

document: original datastore.Entity or db.Model document from match call.

Raises:

DocumentTypeError:

google.appengine.api.prospective_search.prospective_search.get_subscription(document_class, sub_id, topic=None)source

Get subscription information.

Args:

document_class: datastore.Entity or db.Model class. sub_id: subscription id to lookup. topic: required for datastore.Entity document_class, optional for db.Model.

Returns:
Tuple containing:

subscription id query expiration time (secs after the Unix epoch when subscription expires) state (SubscriptionState = OK/PENDING/ERROR) error_message (if state is ERROR)

Raises:

DocumentTypeError: document type is unsupported. SubscriptionDoesNotExist: if subscription of specified id does not exist. TopicNotSpecified: raised for datastore.Entity if topic is not specified. apiproxy_errors.Error: call failed.

google.appengine.api.prospective_search.prospective_search.list_subscriptions(document_class, sub_id_start='', topic=None, max_results=1000, expires_before=None)source

List subscriptions on a topic.

Args:

document_class: datastore.Entity or db.Model class. sub_id_start: return only subscriptions that are lexicographically equal or

greater than the specified value.

topic: required for datastore.Entity document_class, optional for db.Model. max_results: maximum number of subscriptions to return. expires_before: when set, limits list to subscriptions which will

expire no later than expires_before (epoch time).

Returns:
List of subscription tuples. The subscription tuple contains:

subscription id query expiration time (secs after the Unix epoch when subscription expires) state (SubscriptionState = OK/PENDING/ERROR) error_message (if state is ERROR)

Raises:

DocumentTypeError: document type is unsupported. TopicNotSpecified: raised for datastore.Entity if topic is not specified. apiproxy_errors.Error: list call failed.

google.appengine.api.prospective_search.prospective_search.list_topics(max_results=1000, topic_start=None)source

List topics.

Args:

max_results: maximum number of topics to return. topic_start: if not None, start listing topics from this one.

Returns:

List of topics (strings)

google.appengine.api.prospective_search.prospective_search.match(document, topic=None, result_key=None, result_relative_url='/_ah/prospective_search', result_task_queue='default', result_batch_size=100, result_return_document=True)source

Match document with all subscribed queries on specified topic.

Args:

document: instance of datastore.Entity or db.Model document. topic: required for datastore.Entity, optional for db.Model.

Only subscriptions of this topic will be matched against this document.

result_key: key to return in result, potentially to identify document. result_relative_url: url of taskqueue event handler for results. result_task_queue: name of taskqueue queue to put batched results on. result_batch_size: number of subscription ids per taskqueue task batch. result_return_document: returns document with match results if true.

Raises:

DocumentTypeError: document type is unsupported. TopicNotSpecified: raised for datastore.Entity if topic is not specified. apiproxy_errors.Error: match call failed.

google.appengine.api.prospective_search.prospective_search.unsubscribe(document_class, sub_id, topic=None)source

Unsubscribe a query.

Args:

document_class: datastore.Entity or db.Model class. sub_id: subscription id to remove. topic: required for datastore.Entity document_class, optional for db.Model.

Topic must be same as used in the subscribe call for this subscription.

Raises:

DocumentTypeError: document type is unsupported. TopicNotSpecified: raised for datastore.Entity if topic is not specified. apiproxy_errors.Error: unsubscribe call failed.

google.appengine.api.prospective_search.prospective_search.subscribe(document_class, query, sub_id, schema=None, topic=None, lease_duration_sec=0)source

Subscribe a query.

If the document_class is a datastore.Entity, a schema must be specified to map document_class member names to the prospective_search supported types. For example, the datastore.Entity 'person' has the following schema:

person = datastore.Entity('person') person['first_name'] = 'Andrew' person['surname'] = 'Smith' person['height'] = 150

person_schema = {

str : ['first_name', 'surname'], int : ['height'],

}

Args:

document_class: datastore.Entity or db.Model class. query: str or unicode query for documents of type document_class. sub_id: subscription id returned when this subscription is matched. schema: required for datastore.Entity document_class. topic: required for datastore.Entity document_class, optional for db.Model.

If not specified for db.Model, topic is assumed to be the class name. Only documents of same topic will be matched against this subscription.

lease_duration_sec: minimum number of seconds subscription should exist.

0 indicates subscription never expires (default).

Raises:

DocumentTypeError: document type is unsupported. TopicNotSpecified: raised for datastore.Entity if topic is not specified. QuerySyntaxError: raised when query is invalid or does not match schema. SchemaError: schema is invalid. apiproxy_errors.Error: subscribe call failed.

google.appengine.api.prospective_search.prospective_search.subscription_state_name(x)source
exception google.appengine.api.prospective_search.prospective_search.DocumentTypeErrorsource

Bases: google.appengine.api.prospective_search.prospective_search.Error

Document type is not supported.

exception google.appengine.api.prospective_search.prospective_search.Errorsource

Bases: exceptions.Exception

Base error class for this module.

exception google.appengine.api.prospective_search.prospective_search.QuerySyntaxError(topic, sub_id, query, detail)source

Bases: google.appengine.api.prospective_search.prospective_search.Error

Query syntax not valid error.

exception google.appengine.api.prospective_search.prospective_search.SchemaError(detail)source

Bases: google.appengine.api.prospective_search.prospective_search.Error

Schema error.

exception google.appengine.api.prospective_search.prospective_search.SubscriptionDoesNotExist(topic, sub_id)source

Bases: google.appengine.api.prospective_search.prospective_search.Error

Subscription does not exist.

class google.appengine.api.prospective_search.prospective_search.SubscriptionStatesource
ERROR = 2
OK = 0
PENDING = 1
exception google.appengine.api.prospective_search.prospective_search.TopicNotSpecifiedsource

Bases: google.appengine.api.prospective_search.prospective_search.Error

Send feedback about...