Echo StreamServer API Library for Python
Python Ruby
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs
simulator
streamserver
tests
.gitignore
LICENSE.txt
Makefile
README.rst
requirements.txt
setup.py

README.rst

Echo StreamServer API Library

The Echo StreamServer API library provides support for working with the Echo StreamServer from Python. All interaction is via the Echo HTTP/REST API, as described on the Echo Wiki.

Installation

To install the StreamServer API:

$ pip install git+https://github.com/paulj/echo-streamserver-python

Getting Started

To use the StreamServer API library, you'll need an active StreamServer account. See http://wiki.aboutecho.com/w/page/35344006/Echo%20overview for details. Some requests will require just your API key, others will require your API secret too.

To make a call when only your key is needed (such as a search query), then you can do the following:

>>> from streamserver import (ItemsClient, EchoAuthConfig)
>>> import streamserver.querybuilder as qb
>>> c = ItemsClient(auth = EchoAuthConfig(appkey = "test.echoenabled.com"))
>>> c.count(qb.query().childrenof("http://echosandbox.com/use-cases/commenting"))
2832
...

For calls that require authentication, you can use either OAuth or Basic authentication. Both are supported transparently by the library, and can be selected when creating the EchoAuthConfig. For example, to use OAuth to add a key to the Echo KVS:

>>> from streamserver import (KVClient, EchoAuthConfig, EchoAuthMethod)
>>> c = KVClient(auth = EchoAuthConfig(appkey = "prod.myapp", secret = "abcd", method = EchoAuthMethod.OAUTH))
>>> c.put("somekey", "someval")
...

Executing Queries

When using either the ItemsClient.count or ItemsClient.search methods, an Echo search query needs to be specified. This can either be a string containing a valid query, or a query builder object. A query builder operates like:

>>> import streamserver.querybuilder as qb
>>> str(qb.query().scope('http://echosandbox.com/*').itemsPerPage(5))
'scope:http://echosandbox.com itemsPerPage:5'
>>> str(qb.query().scope('http://echosandbox.com/*').itemsPerPage(5).children(2).source('Twitter'))
'scope:http://echosandbox.com/* itemsPerPage:5 children:2 source:Twitter'
>>> str(qb.query().or_terms(qb.subquery().scope('http://echosandbox.com/*').source('Twitter'), \
          qb.subquery().scope('http://aboutecho.com/*')).itemsPerPage(5).children(2).source('Twitter'))
'(scope:http://echosandbox.com/* source:Twitter) OR (scope:http://aboutecho.com/*) itemsPerPage:5 children:2 source:Twitter'
...

The builder allows queries to be built in code, and ensures a valid query expression will be generated by preventing operators being used in incorrect contexts.

Developing

To develop on the library, execute the following to configure your local environment:

make init

To execute the unit tests, first start a simulator server. Note that you'll need Ruby 1.9 and Bundler installed.

cd simulator; bundle install; ruby streamserver.rb

Then execute the tests by running:

make test

Generating Documentation

Assuming that you have a functional development environment (see the above section), documentation can be generated by running:

make doc # Docs will be generated in doc/_build/html