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.

To install the StreamServer API:

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

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")
...

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.

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

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