Navigation

Google Wave Robot Python API v2

For more information on developing, read the developer’s guide: http://code.google.com/apis/wave/extensions/robots/python-tutorial.html

The blip Module

class blip.Annotation(name, value, start, end)

Models an annotation on a document.

Annotations are key/value pairs over a range of content. Annotations can be used to store data or to be interpreted by a client when displaying the data.

BACKGROUND_COLOR
Reserved annotation for setting background color of text.
COLOR
Reserved annotation for setting color of text.
FONT_FAMILY
Reserved annotation for setting font family of text.
FONT_SIZE
Reserved annotation for setting font family of text.
FONT_STYLE
Reserved annotation for setting font style of text.
FONT_WEIGHT
Reserved annotation for setting font weight of text.
TEXT_DECORATION
Reserved annotation for setting text decoration.
VERTICAL_ALIGN
Reserved annotation for setting vertical alignment.
end
name
serialize()

Serializes the annotation.

Returns:
A dict containing the name, value, and range values.
start
value
class blip.Annotations(operation_queue, blip)

A dictionary-like object containing the annotations, keyed by name.

names()
Return the names of the annotations in the store.
serialize()
Return a list of the serialized annotations.
class blip.Blip(json, other_blips, operation_queue, thread=None, reply_threads=None)

Models a single blip instance.

Blips are essentially the documents that make up a conversation. Blips can live in a hierarchy of blips. A root blip has no parent blip id, but all blips have the ids of the wave and wavelet that they are associated with.

Blips also contain annotations, content and elements, which are accessed via the Document object.

all(findwhat=None, maxres=-1, **restrictions)
Returns a BlipRefs object representing all results for the search. If searching for an element, the restrictions can be used to specify additional element properties to filter on, like the url of a Gadget.
annotations
The annotations for this document.
append(what, bundled_annotations=None)
Convenience method covering a common pattern.
append_markup(markup)

Interpret the markup text as xhtml and append the result to the doc.

Args:
markup: The markup’ed text to append.
at(index)
Returns a BlipRefs object representing a 1-character range.
blip_id
The id of this blip.
child_blip_ids
The list of the ids of this blip’s children.
child_blips
The list of blips that are children of this blip.
continue_thread()
Create and return a blip in the same thread as this blip.
contributors
The set of participant ids that contributed to this blip.
creator
The id of the participant that created this blip.
elements
Returns a list of elements for this document. The elements of a blip are things like forms elements and gadgets that cannot be expressed as plain text. In the text of the blip, you’ll typically find a space as a place holder for the element. If you want to retrieve the element at a particular index in the blip, use blip[index].value().
find(what, **restrictions)

Iterate to matching bits of contents.

Yield either elements or pieces of text.

first(findwhat=None, **restrictions)
Returns a BlipRefs object representing the first result for the search. If searching for an element, the restrictions can be used to specify additional element properties to filter on, like the url of a Gadget.
inline_blip_offset

The offset in the parent if this blip is inline or -1 if not.

If the parent is not in the context, this function will always return -1 since it can’t determine the inline blip status.

inline_reply_threads
insert_inline_blip(position)

Inserts an inline blip into this blip at a specific position.

Args:
position: Position to insert the blip at. This has to be greater than 0.
Returns:
The JSON data of the blip that was created.
is_root()
Returns whether this is the root blip of a wavelet.
last_modified_time
The time in seconds since epoch when this blip was last modified.
parent_blip
The parent blip or None if it is the root.
parent_blip_id
The parent blip_id or None if this is the root blip.
proxy_for(proxy_for_id)

Return a view on this blip that will proxy for the specified id.

A shallow copy of the current blip is returned with the proxy_for_id set. Any modifications made to this copy will be done using the proxy_for_id, i.e. the robot+<proxy_for_id>@appspot.com address will be used.

range(start, end)
Returns a BlipRefs object representing the range.
reply()
Create and return a reply to this blip.
reply_threads
The list of threads that are replies to this blip.
serialize()
Return a dictionary representation of this blip ready for json.
text
Returns the raw text content of this document.
thread
The thread that this blip belongs to.
version
The version of this blip.
wave_id
The id of the wave that this blip belongs to.
wavelet_id
The id of the wavelet that this blip belongs to.
class blip.BlipRefs(blip, maxres=1)

Represents a set of references to contents in a blip.

For example, a BlipRefs instance can represent the results of a search, an explicitly set range, a regular expression, or refer to the entire blip. BlipRefs are used to express operations on a blip in a consistent way that can easily be transfered to the server.

The typical way of creating a BlipRefs object is to use selector methods on the Blip object. Developers will not usually instantiate a BlipRefs object directly.

classmethod all(blip, findwhat, maxres=-1, **restrictions)
Construct an instance representing the search for text or elements.
annotate(name, value=None)

Annotates the content at the matched positions.

You can either specify both name and value to set the same annotation, or supply as the first parameter something that yields name/value pairs. The name and value should both be strings.

clear_annotation(name)
Clears the annotation at the matched positions.
delete()
Deletes the content at the matched positions.
insert(what, bundled_annotations=None)
Inserts what at the matched positions.
insert_after(what, bundled_annotations=None)
Inserts what just after the matched positions.
classmethod range(blip, begin, end)
Constructs an instance representing an explicitly set range.
replace(what, bundled_annotations=None)
Replaces the matched positions with what.
update_element(new_values)

Update an existing element with a set of new values.

For example, this code would update a button value: button.update_element({‘value’: ‘Yes’}) This code would update the ‘seen’ key in a gadget’s state: gadget.update_element({‘seen’: ‘yes’})

Args:
new_values: A dictionary of property names and values.
value()
Convenience method to convert a BlipRefs to value of its first match.
class blip.Blips(blips)

A dictionary-like object containing the blips, keyed on blip ID.

get(blip_id, default_value=None)

Retrieves a blip.

Returns:
A Blip object. If none found for the ID, it returns None, or if default_value is specified, it returns that.
serialize()

Serializes the blips. Returns:

A dict of serialized blips.
values()
Return the blips themselves.

The wavelet Module

Defines classes that are needed to model a wavelet.

class wavelet.BlipThread(id, location, blip_ids, all_blips, operation_queue)

Models a group of blips in a wave.

blip_ids
Returns the blip IDs in this thread.
blips
Returns the blips in this thread.
id
Returns this thread’s id.
location
Returns this thread’s location.
serialize()
Returns serialized properties.
class wavelet.DataDocs(init_docs, wave_id, wavelet_id, operation_queue)

Class modeling a bunch of data documents in pythonic way.

keys()
serialize()
Returns a dictionary of the data documents.
class wavelet.Participants(participants, roles, wave_id, wavelet_id, operation_queue)

Class modelling a set of participants in pythonic way.

ROLE_FULL
Designates full access (read/write) role.
ROLE_READ_ONLY
Designates read-only role.
add(participant_id)
Adds a participant by their ID (address).
get_role(participant_id)
Return the role for the given participant_id.
serialize()
Returns a list of the participants.
set_role(participant_id, role)
Sets the role for the given participant_id.
class wavelet.Tags(tags, wave_id, wavelet_id, operation_queue)

Class modelling a list of tags.

append(tag)
Appends a tag if it doesn’t already exist.
remove(tag)
Removes a tag if it exists.
serialize()
Returns a list of tags.
class wavelet.Wavelet(json, blips, root_thread, operation_queue)

Models a single wavelet.

A single wavelet is composed of metadata, participants, and its blips. To guarantee that all blips are available, specify Context.ALL for events.

add_proxying_participant(id)

Ads a proxying participant to the wave.

Proxying participants are of the form robot+proxy@domain.com. This convenience method constructs this id and then calls participants.add.

blips
Returns the blips for this wavelet.
creation_time
Returns the time that this wavelet was first created in milliseconds.
creator
Returns the participant id of the creator of this wavelet.
data_documents
Returns the data documents for this wavelet based on key name.
delete(todelete)

Remove a blip from this wavelet.

Args:
todelete: either a blip or a blip id to be removed.
domain
Return the domain that wavelet belongs to.
get_operation_queue()
Returns the OperationQueue for this wavelet.
last_modified_time
Returns the time that this wavelet was last modified in ms.
participants
Returns a set of participants on this wavelet.
proxy_for(proxy_for_id)

Return a view on this wavelet that will proxy for the specified id.

A shallow copy of the current wavelet is returned with the proxy_for_id set. Any modifications made to this copy will be done using the proxy_for_id, i.e. the robot+<proxy_for_id>@appspot.com address will be used.

If the wavelet was retrieved using the Active Robot API, that is by fetch_wavelet, then the address of the robot must be added to the wavelet by setting wavelet.robot_address before calling proxy_for().

reply(initial_content=None)

Replies to the conversation in this wavelet.

Args:
initial_content: If set, start with this (string) content.
Returns:
A transient version of the blip that contains the reply.
robot_address
Get or set the address of the current robot.
root_blip
Returns this wavelet’s root blip.
root_thread
Returns the root thread of this wavelet.
serialize()
Return a dict of the wavelet properties.
submit_with(other_wavelet)

Submit this wavelet when the passed other wavelet is submited.

wavelets constructed outside of the event callback need to be either explicitly submited using robot.submit(wavelet) or be associated with a different wavelet that will be submited or is part of the event callback.

tags
Returns a list of tags for this wavelet.
title
Returns or sets the wavelet’s title.
wave_id
Returns this wavelet’s parent wave id.
wavelet_id
Returns this wavelet’s id.

The robot Module

Defines the generic robot classes.

This module provides the Robot class and RobotListener interface, as well as some helper functions for web requests and responses.

class robot.Robot(name, image_url='', profile_url='http://code.google.com/apis/wave/extensions/robots/python-tutorial.html')

Robot metadata class.

This class holds on to basic robot information like the name and profile. It also maintains the list of event handlers and cron jobs and dispatches events to the appropriate handlers.

blind_wavelet(json, proxy_for_id=None)

Construct a blind wave from a json string.

Call this method if you have a snapshot of a wave that you want to operate on outside of an event. Since the wave might have changed since you last saw it, you should take care to submit operations that are as safe as possible.

Args:
json: a json object or string containing at least a key
wavelet defining the wavelet and a key blips defining the blips in the view.
proxy_for_id: the proxying information that will be set on the wavelet’s
operation queue.
Returns:
A new wavelet with its own operation queue. It the responsibility of the caller to make sure this wavelet gets submited to the server, either by calling robot.submit() or by calling .submit_with() on the returned wavelet.
capabilities_hash()
Return the capabilities hash as a hex string.
capabilities_xml()
Return this robot’s capabilities as an XML string.
fetch_wavelet(wave_id, wavelet_id=None, proxy_for_id=None)

Use the REST interface to fetch a wave and return it.

The returned wavelet contains a snapshot of the state of the wavelet at that point. It can be used to modify the wavelet, but the wavelet might change in between, so treat carefully.

Also note that the wavelet returned has its own operation queue. It the responsibility of the caller to make sure this wavelet gets submited to the server, either by calling robot.submit() or by calling .submit_with() on the returned wavelet.

get_verification_token_info()
Returns the verification token and ST parameter.
get_waveservice()

Return the currently installed waveservice if available.

Throws an exception if no service is installed.

image_url
Returns the URL of the avatar image.
name
Returns the name of the robot.
new_wave(domain, participants=None, message='', proxy_for_id=None, submit=False)

Create a new wave with the initial participants on it.

A new wave is returned with its own operation queue. It the responsibility of the caller to make sure this wave gets submitted to the server, either by calling robot.submit() or by calling .submit_with() on the returned wave.

Args:
domain: the domain to create the wavelet on. This should
in general correspond to the domain of the incoming wavelet. (wavelet.domain). Exceptions are situations where the robot is calling new_wave outside of an event or when the server is handling multiple domains.
participants: initial participants on the wave. The robot
as the creator of the wave is always added.
message: a string that will be passed back to the robot
when the WAVELET_CREATOR event is fired. This is a lightweight way to pass around state.
submit: if true, use the active gateway to make a round
trip to the server. This will return immediately an actual waveid/waveletid and blipId for the root blip.
process_events(json)
Process an incoming set of events encoded as json.
profile_json(name=None)

Returns a JSON representation of the profile.

This method is called both for the basic profile of the robot and to get a proxying for profile, in which case name is set. By default the information supplied at registration is returned.

Use register_profile_handler to override this default behavior.

profile_url
Returns the URL of an info page for the robot.
register_handler(event_class, handler, context=None, filter=None)

Registers a handler on a specific event type.

Multiple handlers may be registered on a single event type and are guaranteed to be called in order of registration.

The handler takes two arguments, the event object and the corresponding wavelet.

Args:
event_class: An event to listen for from the classes defined in the
events module.
handler: A function handler which takes two arguments, the wavelet for
the event and the event object.

context: The context to provide for this handler.

filter: Depending on the event, a filter can be specified that restricts
for which values the event handler will be called from the server. Valuable to restrict the amount of traffic send to the robot.
register_profile_handler(handler)

Sets the profile handler for this robot.

The profile handler will be called when a profile is needed. The handler gets passed the name for which a profile is needed or None for the robot itself. A dictionary with keys for name, imageUrl and profileUrl should be returned.

set_http_post(http_post)
Set the http_post handler to use when posting.
set_verification_token_info(token, st=None)

Set the verification token used in the ownership verification.

/wave/robot/register starts this process up and will produce this token.

Args:

token: the token provided by /wave/robot/register.

st: optional parameter to verify the request for the token came from
the wave server.
setup_oauth(consumer_key, consumer_secret, server_rpc_base='https://www-opensocial.googleusercontent.com/api/rpc')

Configure this robot to use the oauth’d json rpc.

Args:

consumer_key: consumer key received from the verification process.

consumer_secret: secret received from the verification process.

server_rpc_base: url of the rpc gateway to use. Specify None for default.
For wave preview, http://gmodules.com/api/rpc should be used. For wave sandbox, http://sandbox.gmodules.com/api/rpc should be used.
submit(wavelet_to_submit)

Submit the pending operations associated with wavelet_to_submit.

Typically the wavelet will be the result of fetch_wavelet, blind_wavelet or new_wave.

The element Module

Elements are non-text bits living in blips like images, gadgets etc.

This module defines the Element class and the derived classes.

class element.Attachment(caption=None, data=None, mimeType=None, attachmentId=None, attachmentUrl=None)

An attachment element.

To create a new attachment, caption and data are needed. mimeType, attachmentId and attachmentUrl are sent via events.

classmethod from_props(props)
serialize()

Serializes the attachment object into JSON.

The attachment data is base64 encoded.

class element.Button(name, value)

A button element.

classmethod from_props(props)
class element.Check(name, value='')

A checkbox element.

classmethod from_props(props)
class element.Element(element_type, **properties)

Elements are non-text content within a document.

These are generally abstracted from the Robot. Although a Robot can query the properties of an element it can only interact with the specific types that the element represents.

Properties of elements are both accessible directly (image.url) and through the get method (image.get(‘url’)). In general, Element should not be instantiated by robots, but rather rely on the derived classes.

classmethod from_json(json)
Class method to instantiate an Element based on a json string.
get(key, default=None)
Standard get interface.
serialize()
Custom serializer for Elements.
type
The type of this element.
class element.Gadget(url, props=None)

A gadget element.

classmethod from_props(props)
keys()
Get the valid keys for this gadget.
serialize()
Gadgets allow for None values.
class element.Image(url='', width=None, height=None, attachmentId=None, caption=None)

An image element.

classmethod from_props(props)
class element.Input(name, value='')

A single-line input element.

classmethod from_props(props)
class element.Installer(manifest)

An installer element.

classmethod from_props(props)
class element.Label(label_for, caption)

A label element.

classmethod from_props(props)
class element.Line(line_type=None, indent=None, alignment=None, direction=None)

A line element.

Note that Lines are represented in the text as newlines.

ALIGN_CENTER
Sets line alignment to centered.
ALIGN_JUSTIFIED
Sets line alignment to justified.
ALIGN_LEFT
Sets line alignment to left.
ALIGN_RIGHT
Sets line alignment to right.
TYPE_H1
Designates line as H1, largest heading.
TYPE_H2
Designates line as H2 heading.
TYPE_H3
Designates line as H3 heading.
TYPE_H4
Designates line as H4 heading.
TYPE_H5
Designates line as H5, smallest heading.
TYPE_LI
Designates line as a bulleted list item.
classmethod from_props(props)
class element.Password(name, value)

A password element.

classmethod from_props(props)
class element.RadioButton(name, group)

A radio button element.

classmethod from_props(props)
class element.RadioButtonGroup(name, value)

A group of radio buttons.

classmethod from_props(props)
class element.TextArea(name, value)

A text area element.

classmethod from_props(props)
element.is_element(cls)
Returns whether the passed class is an element.

The events Module

Defines event types that are sent from the wave server.

This module defines all of the event types currently supported by the wave server. Each event type is sub classed from Event and has its own properties depending on the type.

class events.AnnotatedTextChanged(json, wavelet)

Event triggered when text with an annotation has changed.

This is mainly useful in combination with a filter on the name of the annotation.

Attributes:

name: The name of the annotation.

value: The value of the annotation that changed.

class events.BlipContributorsChanged(json, wavelet)

Event triggered when the contributors to this blip change.

Attributes:

contributors_added: List of contributors that were added.

contributors_removed: List of contributors that were removed.

class events.BlipSubmitted(json, wavelet)
Event triggered when a blip is submitted.
class events.Context

Specifies constants representing different context requests.

ALL
Requests all of the blips of the event wavelet.
CHILDREN
Requests the child blips of the event blip.
PARENT
Requests the parent blip of the event blip.
ROOT
Requests the root blip.
SELF
Requests the event blip itself.
SIBLINGS
Requests the siblings blip of the event blip.
class events.DocumentChanged(json, wavelet)

Event triggered when a document is changed.

This event is fired after any changes in the document and should be used carefully to keep the amount of traffic to the robot reasonable. Use filters where appropriate.

class events.Event(json, wavelet)

Object describing a single event.

Attributes:

modified_by: Participant id that caused this event.

timestamp: Timestamp that this event occurred on the server.

type: Type string of this event.

properties: Dictionary of all extra properties. Typically the derrived
event type should have these explicitly set as attributes, but experimental features might appear in properties before that.
blip_id: The blip_id of the blip for blip related events or the root
blip for wavelet related events.

blip: If available, the blip with id equal to the events blip_id.

proxying_for: If available, the proxyingFor id of the robot that caused the event.

class events.FormButtonClicked(json, wavelet)

Event triggered when a form button is clicked.

Attributes:
button_name: The name of the button that was clicked.
class events.GadgetStateChanged(json, wavelet)

Event triggered when the state of a gadget changes.

Attributes:

index: The index of the gadget that changed in the document.

old_state: The old state of the gadget.

class events.OperationError(json, wavelet)

Triggered when an event on the server occurred.

Attributes:

operation_id: The operation id of the failing operation.

error_message: More information as to what went wrong.

class events.WaveletBlipCreated(json, wavelet)

Event triggered when a new blip is created.

Attributes:

new_blip_id: The id of the newly created blip.

new_blip: If in context, the actual new blip.

class events.WaveletBlipRemoved(json, wavelet)

Event triggered when a new blip is removed.

Attributes:

removed_blip_id: the id of the removed blip

removed_blip: if in context, the removed blip

class events.WaveletCreated(json, wavelet)

Triggered when a new wavelet is created.

This event is only triggered if the robot creates a new wavelet and can be used to initialize the newly created wave. wavelets created by other participants remain invisible to the robot until the robot is added to the wave in which case WaveletSelfAdded is triggered.

Attributes:
message: Whatever string was passed into the new_wave
call as message (if any).
class events.WaveletFetched(json, wavelet)

Triggered when a new wavelet is fetched.

This event is triggered after a robot requests to see another wavelet. The robot has to be on the other wavelet already.

Attributes:
message: Whatever string was passed into the new_wave
call as message (if any).
class events.WaveletParticipantsChanged(json, wavelet)

Event triggered when the participants on a wave change.

Attributes:

participants_added: List of participants added.

participants_removed: List of participants removed.

class events.WaveletSelfAdded(json, wavelet)
Event triggered when the robot is added to the wavelet.
class events.WaveletSelfRemoved(json, wavelet)
Event triggered when the robot is removed from the wavelet.
class events.WaveletTagsChanged(json, wavelet)
Event triggered when the tags on a wavelet change.
class events.WaveletTitleChanged(json, wavelet)

Event triggered when the title of the wavelet has changed.

Attributes:
title: The new title.
events.is_event(cls)
Returns whether the passed class is an event.

The errors Module

Contains various API-specific exception classes.

This module contains various specific exception classes that are raised by the library back to the client.

exception errors.Error
Base library error type.
exception errors.RpcError
Wave rpc error.

The ops Module

Support for operations that can be applied to the server.

Contains classes and utilities for creating operations that are to be applied on the server.

class ops.Operation(method, opid, params)

Represents a generic operation applied on the server.

This operation class contains data that is filled in depending on the operation type.

It can be used directly, but doing so will not result in local, transient reflection of state on the blips. In other words, creating a ‘delete blip’ operation will not remove the blip from the local context for the duration of this session. It is better to use the OpBased model classes directly instead.

serialize(method_prefix='')

Serialize the operation.

Args:
method_prefix: prefixed for each method name to allow for specifying a namespace.
Returns:
a dict representation of the operation.
set_optional(param, value)

Sets an optional parameter.

If value is None or “”, this is a no op. Otherwise it calls set_param.

set_param(param, value)
class ops.OperationQueue(proxy_for_id=None)

Wraps the queuing of operations using easily callable functions.

The operation queue wraps single operations as functions and queues the resulting operations in-order. Typically there shouldn’t be a need to call this directly unless operations are needed on entities outside of the scope of the robot. For example, to modify a blip that does not exist in the current context, you might specify the wave, wavelet and blip id to generate an operation.

Any calls to this will not be reflected in the robot in any way. For example, calling wavelet_append_blip will not result in a new blip being added to the robot, only an operation to be applied on the server.

blip_continue_thread(wave_id, wavelet_id, blip_id)

Creates a blip in same thread as specified blip.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. blip_id: The blip id that this operation is applied to.
Returns:
JSON of blip for which further operations can be applied.
blip_create_child(wave_id, wavelet_id, blip_id)

Creates a child blip of another blip.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. blip_id: The blip id that this operation is applied to.
Returns:
JSON of blip for which further operations can be applied.
blip_delete(wave_id, wavelet_id, blip_id)

Deletes the specified blip.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. blip_id: The blip id that this operation is applied to.
Returns:
The operation created.
clear()
copy_operations(other_queue)
Copy the pending operations from other_queue into this one.
document_append_markup(wave_id, wavelet_id, blip_id, content)

Appends content with markup to a document.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. blip_id: The blip id that this operation is applied to. content: The markup content to append.
Returns:
The operation created.
document_inline_blip_insert(wave_id, wavelet_id, blip_id, position)

Inserts an inline blip at a specific location.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. blip_id: The blip id that this operation is applied to. position: The position in the document to insert the blip.
Returns:
JSON data for the blip that was created for further operations.
document_modify(wave_id, wavelet_id, blip_id)

Creates and queues a document modify operation

The returned operation still needs to be filled with details before it makes sense.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. blip_id: The blip id that this operation is applied to.
Returns:
The operation created.
new_operation(method, wave_id, wavelet_id, props=None, **kwprops)
Creates and adds a new operation to the operation list.
proxy_for(proxy)

Return a view of this operation queue with the proxying for set to proxy.

This method returns a new instance of an operation queue that shares the operation list, but has a different proxying_for_id set so the robot using this new queue will send out operations with the proxying_for field set.

robot_create_wavelet(domain, participants=None, message='')

Creates a new wavelet.

Args:

domain: the domain to create the wave in participants: initial participants on this wavelet or None if none message: an optional payload that is returned with the corresponding

event.
Returns:
data for the root_blip, wavelet
robot_fetch_wave(wave_id, wavelet_id)

Requests a snapshot of the specified wave.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to.
Returns:
The operation created.

Execute a search request.

For now this only makes sense in the data API. Wave does not maintain an index for robots so no results will be returned in that scenario.

Args:
query: what to search for index: what index to search from num_results: how many results to return
Returns:
The operation created.
serialize(method_prefix='')
set_capability_hash(capability_hash)
wavelet_add_participant(wave_id, wavelet_id, participant_id)

Adds a participant to a wavelet.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. participant_id: Id of the participant to add.
Returns:
data for the root_blip, wavelet
wavelet_append_blip(wave_id, wavelet_id, initial_content='')

Appends a blip to a wavelet.

Args:
wave_id: The wave id owning the containing wavelet. wavelet_id: The wavelet id that this blip should be appended to. initial_content: optionally the content to start with
Returns:
JSON representing the information of the new blip.
wavelet_datadoc_set(wave_id, wavelet_id, name, data)

Sets a key/value pair on the data document of a wavelet.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. name: The key name for this data. data: The value of the data to set.
Returns:
The operation created.
wavelet_modify_participant_role(wave_id, wavelet_id, participant_id, role)

Modify the role of a participant on a wavelet.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. participant_id: Id of the participant to add. role: the new roles
Returns:
data for the root_blip, wavelet
wavelet_modify_tag(wave_id, wavelet_id, tag, modify_how=None)

Modifies a tag in a wavelet.

Args:

wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. tag: The tag (a string). modify_how: (optional) how to apply the tag. The default is to add

the tag. Specify ‘remove’ to remove. Specify None or ‘add’ to add.
Returns:
The operation created.
wavelet_set_title(wave_id, wavelet_id, title)

Sets the title of a wavelet.

Args:
wave_id: The wave id owning that this operation is applied to. wavelet_id: The wavelet id that this operation is applied to. title: The title to set.
Returns:
The operation created.

The util Module

Utility library containing various helpers used by the API.

class util.StringEnum(*values)

Enum like class that is configured with a list of values.

This class effectively implements an enum for Elements, except for that the actual values of the enums will be the string values.

util.check_is_valid_proxy_for_id(s)

Checks if the given string is a valid proxy id.

Please see isValidProxyForId(String) for more details on the assertion. This method raises a ValueError exception if the input string is not a valid proxy id.

Args:
s: the string to be checked.
util.force_unicode(object)
Return the Unicode string version of object, with UTF-8 encoding.
util.is_dict(inst)
Returns whether or not the specified instance is a dict.
util.is_iterable(inst)

Returns whether or not this is a list, tuple, set or dict .

Note that this does not return true for strings.

util.is_user_defined_new_style_class(obj)
Returns whether or not the specified instance is a user-defined type.
util.is_valid_proxy_for_id(s)

Checks if the given string is a valid proxy id.

This method asserts whether the string contains reserved characters or not. This check is to ensure that when we concatenate the robot id and the proxy id, it doesn’t result in an invalid participant id.

The reserved characters are: - whitespaces - non-printing characters: decimal 0 - 31 (hex 00 - 1F), and decimal 127

(hex 7F)
  • @, comma, :, <, and >

If you need to pass in an arbitrary string as the proxy id, please consider encoding the string with a URL encoder (for example, urllib.quote_plus) or base64 encoder (for example, base64.b64encode) first.

Args:
s: the string to be checked.
Returns:
True if the string is a valid proxy for id.
util.lower_camel_case(s)

Converts a string to lower camel case.

Examples:
foo => foo foo_bar => fooBar foo__bar => fooBar foo_bar_baz => fooBarBaz
Args:
s: The string to convert to lower camel case.
Returns:
The lower camel cased string.
util.non_none_dict(d)
return a copy of the dictionary without none values.
util.parse_markup(markup)

Parses a bit of markup into robot compatible text.

For now this is a rough approximation.

util.serialize(obj)

Serializes any instance.

If this is a user-defined instance type, it will first check for a custom Serialize() function and use that if it exists. Otherwise, it will invoke serialize all of its public attributes. Lists and dicts are serialized trivially.

Args:
obj: The instance to serialize.
Returns:
The serialized object.

The waveservice Module

Base class to use OAuth to talk to the wave service.

class waveservice.WaveService(use_sandbox=False, server_rpc_base=None, consumer_key='anonymous', consumer_secret='anonymous', http_post=None)
blind_wavelet(json, proxy_for_id=None)

Construct a blind wave from a json string.

Call this method if you have a snapshot of a wave that you want to operate on outside of an event. Since the wave might have changed since you last saw it, you should take care to submit operations that are as safe as possible.

Args:
json: a json object or string containing at least a key
wavelet defining the wavelet and a key blips defining the blips in the view.
proxy_for_id: the proxying information that will be set on the wavelet’s
operation queue.
Returns:
A new wavelet with its own operation queue. It the responsibility of the caller to make sure this wavelet gets submited to the server, either by calling robot.submit() or by calling .submit_with() on the returned wavelet.
fetch_request_token(callback=None)

Fetches the request token to start the oauth dance.

Args:
callback: the URL to where the service will redirect to after
access is granted.
Returns:
An OAuthToken object
fetch_wavelet(wave_id, wavelet_id=None, proxy_for_id=None)

Use the REST interface to fetch a wave and return it.

The returned wavelet contains a snapshot of the state of the wavelet at that point. It can be used to modify the wavelet, but the wavelet might change in between, so treat carefully.

Also note that the wavelet returned has its own operation queue. It the responsibility of the caller to make sure this wavelet gets submited to the server, either by calling robot.submit() or by calling .submit_with() on the returned wavelet.

generate_authorization_url(request_token=None)

Generates the authorization URL (Step 2).

Args:
request_token: An OAuthToken object
Returns:
An authorization URL
get_token_from_request(oauth_request)

Convenience function to returning the token from a request.

Args:
oauth_request: An OAuthRequest object
Returns:
An OAuthToken object
http_post(url, data, headers)

Execute an http post.

You can provide a different method to use in the constructor. This is mostly useful when running on app engine and you want to set the time out to something different than the default 5 seconds.

Args:
url: to post to body: post body headers: extra headers to pass along
Returns:
response_code, returned_page
make_rpc(operations)
Make an rpc call, submitting the specified operations.
new_wave(domain, participants=None, message='', proxy_for_id=None, submit=False)

Create a new wave with the initial participants on it.

A new wave is returned with its own operation queue. It the responsibility of the caller to make sure this wave gets submitted to the server, either by calling robot.submit() or by calling .submit_with() on the returned wave.

Args:
domain: the domain to create the wavelet on. This should
in general correspond to the domain of the incoming wavelet. (wavelet.domain). Exceptions are situations where the robot is calling new_wave outside of an event or when the server is handling multiple domains.
participants: initial participants on the wave. The robot
as the creator of the wave is always added.
message: a string that will be passed back to the robot
when the WAVELET_CREATOR event is fired. This is a lightweight way to pass around state.
submit: if true, use the active gateway to make a round
trip to the server. This will return immediately an actual waveid/waveletid and blipId for the root blip.
search(query, index=None, num_results=None)

Execute a search request.

Args:
query: what to search for, for example [in:inbox] index: index of the first result to return num_results: how many results to return
set_access_token(access_token)
set_http_post(http_post)
Set the http_post handler to use when posting.
submit(wavelet_to_submit)

Submit the pending operations associated with wavelet_to_submit.

Typically the wavelet will be the result of fetch_wavelet, blind_wavelet or new_wave.

upgrade_to_access_token(request_token, verifier=None)

Upgrades the request_token to an access token (Step 3).

Args:
request_token: An OAuthToken object or string verifier: A verifier string
Returns:
An OAuthToken object

The appengine_robot_runner Module

A module to run wave robots on app engine.

class appengine_robot_runner.CapabilitiesHandler(method, contenttype)

Handler to forward a request ot a handler of a robot.

get()
Handles HTTP GET request.
class appengine_robot_runner.ProfileHandler(method, contenttype)

Handler to forward a request ot a handler of a robot.

get()
Handles HTTP GET request.
class appengine_robot_runner.RobotEventHandler(robot)

Handler for the dispatching of events to various handlers to a robot.

This handler only responds to post events with a JSON post body. Its primary task is to separate out the context data from the events in the post body and dispatch all events in order. Once all events have been dispatched it serializes the context data and its associated operations as a response.

get()

Handles the get event for debugging.

This is useful for debugging but since event bundles tend to be rather big it often won’t fit for more complex requests.

post()
Handles HTTP POST requests.
class appengine_robot_runner.RobotVerifyTokenHandler(robot)

Handler for the token_verify request.

get()
Handles the get event for debugging. Ops usually too long.
appengine_robot_runner.appengine_post(url, data, headers)
appengine_robot_runner.create_robot_webapp(robot, debug=False, extra_handlers=None)
Returns an instance of webapp.WSGIApplication with robot handlers.
appengine_robot_runner.operation_error_handler(event, wavelet)
Default operation error handler, logging what went wrong.
appengine_robot_runner.run(robot, debug=False, log_errors=True, extra_handlers=None)

Sets up the webapp handlers for this robot and starts listening.

A robot is typically setup in the following steps:
  1. Instantiate and define robot.
  2. Register various handlers that it is interested in.
  3. Call Run, which will setup the handlers for the app.
For example:
robot = Robot(‘Terminator’,
image_url=’http://www.sky.net/models/t800.png‘, profile_url=’http://www.sky.net/models/t800.html‘)

robot.register_handler(WAVELET_PARTICIPANTS_CHANGED, KillParticipant) run(robot)

Args:
robot: the robot to run. This robot is modified to use app engines
urlfetch for posting http.
debug: Optional variable that defaults to False and is passed through
to the webapp application to determine if it should show debug info.
log_errors: Optional flag that defaults to True and determines whether
a default handlers to catch errors should be setup that uses the app engine logging to log errors.
extra_handlers: Optional list of tuples that are passed to the webapp
to install more handlers. For example, passing
[(‘/about’, AboutHandler),] would install an extra about handler for the robot.

Table Of Contents

This Page

Navigation

© Copyright 2009, Douwe. Created using Sphinx 0.6.5.