<commit_before>=============================
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 <http://wiki.aboutecho.com/w/page/35344006/Echo%20overview>`_.

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:
<commit_msg>Fix formatting for simulator setup<commit_after>=============================
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 <http://wiki.aboutecho.com/w/page/35344006/Echo%20overview>`_.

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:

{'fraction_non_alphanumeric': 0.1404552893914596, 'fraction_numerical': 0.010712691563755393, 'mean_word_length': 3.7171929824561403, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 71, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3538601', 'n_tokens_mistral': 1933, 'n_tokens_neox': 1814, 'n_words': 652}