python-echo-streamserver 0.84

Function Interface

The function interface provides each API as a simple module or package. The API uses the Default Account to contact Echo. For example, the Items API is echo.items and has the REST API methods.

>>> # Items API: Count EQL Query
>>> from echo import items, StreamServerError
>>> try:
>>>     n = items.count("scope:http//example.com/\*")
>>>     print "EQL Count: %d" % n
>>> except StreamServerError, e:
>>>     print "Error: %s" % str(e)

Client Interface

The Client interface provides each API as a class instance. The Client uses an Account object to contact Echo, or the default. For example, the Key-Value Store API is echo.kvs.Client and has the KVS API methods.

>>> # KVS Client API: Get a value for the key 'sample'.
>>> from echo import kvs, StreamServerError
>>> # Create a KVS client using the default account.
>>> client = kvs.Client()
>>> try:
>>>     v = client.get('sample')
>>>     print "KVS: %r" % v
>>> except StreamServerError, e:
>>>     print "Error: %s" % str(e)

Account Objects

Each Client instance can use an Account object to contact Echo. This is required to support multiple Echo accounts.

>>> from echo import feeds, Account
>>> # Non-default account: Login Account.BasicAuth with no secret
>>> other_account = Account('test.echoenabled.com', '', Account.BasicAuth)
>>> client = feeds.Client(account=other_account)

MUX Requests

The Items API supports MUX, or multiplexed requests. Several count and search requests can be combined into one REST call. The items.mux method sends a list of MuxRequest objects to Echo. See the Echo mux method documentation for the output format.

>>> from echo import items
>>> from echo.items.mux_api import MuxRequest
>>> # EQL Query String
>>> query_eql = "scope:http://www.example.com/\*"
>>> # Search Query (default)
>>> search = MuxRequest(query_eql)
>>> # Count Query
>>> count = MuxRequest(query_eql, api_method='count')
>>> # Form list of them for Mux API.
>>> requests = [ search, count ]
>>> # Send Mux API requests.
>>> r = items.mux(requests)

Echo Query Language Builder

There is an object-oriented Echo Query Language API to build query strings. An echo.eql.Query object may be passed to the Items API methods eql.items.count and eql.items.search rather than query text. Add echo.eql.filters to build on the query terms and produce a complete EQL query string.

>>> from echo import eql
>>> q = eql.Query("http://site.example.com/index.html", uri_filter='url')
>>> q.add_filter(eql.filters.ChildrenDepth(3))
>>> q.add_filter(eql.filters.TypeFilter('article'), negate=True)
>>> print "EQL> ", q
EQL> "url:"http://site.example.com/index.html" children:3 -type:article"

>>> from echo import eql
>>> q = eql.Query("http://www.example.com/movies//")
>>> # Exclude articles and notes with (-).
>>> q = q - eql.filters.TypeFilter(['article', 'note'])
>>> # Allow children up to depth 2.
>>> q + (eql.filters.ChildrenDepth(2))