Python Timetric client
======================

A client for Timetric (http://timetric.com).

Requirements (easy-installable, listed as prereqs in setup.py):

    * httplib2
    * python-dateutil
    * simplejson

Optionally, if you want to use OAuth authentication:

    * oauth

This is *not* listed as a prereq, so it won't be installed by default.

Authentication setup
--------------------

You'll provide authentication information to the ``TimetricClient`` in a config
dict. Timetric supports two types of authentication: OAuth and API tokens. You
can choose a method using the ``'authtype'`` key to the config dict. The value
of this key can be ``'oauth'`` or ``'apitoken'``; if not given it defaults to
``'oauth'``.

If an API token is being used, there must be keys for:

    * 'apitoken_key'
    * 'apitoken_secret'

If OAuth is being used, there must also be keys for:

    * 'consumer_key'
    * 'consumer_secret'

and if you have already done the necessary key exchange, then this can also
contain:

    * 'access_key'
    * 'access_token'

OAuth setup
-----------

The first time you use the OAuth protocol, you'll need to do some key exchange
with Timetric to set up your tokens.

    >>> import timetric

    # You need a config dict with at minimum your secret and key from Timetric
    # (see the "Applications" pane of the settings page). In a real app you'll
    # want to make this config persistant (the shelve module is a lightweight
    # place to start) because the library will store OAuth authentication
    # information back to this config.
    >>> conf = {'authtype':'oauth', 
    ...         'consumer_key: 'XXX',
    ...         'consumer_secret': 'XXX'}
    >>> client = timetric.TimetricClient(conf)

    # The first time through you'll need to authorize your key with Timetric
    # by sending the user to an authorization request page.
    >> token = client.get_request_token()
    >>> import webbrowser
    >>> webbrowser.open(client.get_authorize_url(token))

    # Once the user has authorized at that page, you can continue.
    >>> access_token = client.get_access_token(token)

    # You can now re-authorize to use this token:
    >>> conf.update({'oauth_key':access_token.key,
    ...              'oauth_secret':access_token.secret})
    >>> client = timetric.TimetricClient(conf)

API token setup
---------------

    >>> import timetric

    # Having got your config dict from somewhere:
    >>> conf = {'authtype':'apitoken', 
    ...         'apitoken_key': 'XXX', 
    ..          'apitoken-secret': 'XXX'}

    # you initialize the timetric client:
    >>> client = timetric.TimetricClient(conf)


Usage
-----

::
    
    # There's no API method to get a list of a particular
    # user's series, so you need to somehow "know" the series ID.
    >>> series = client.series('p-DpewL0TO-iBE4nMBCTsQ')
    
    # Get the latest value
    >>> series.latest()
    (1236707269.0, 2.0)
    
    # Iterate over the whole dataset
    >>> for (timestamp, value) in series:
    ...     print timestamp, value
    1236463646.39 3.0 
    1236486562.94 5.0 
    1236493503.37 6.0
    
    # Update given a single value
    >>> series.update(14)
    
    # Update given an iterable of (time, value) pairs
    >>> import time
    >>> data = [(time.time() - 100, 11), (time.time() + 100, 15)]
    >>> series.update(data)
    
    # Update given a file of CSV data
    >>> series.update(open('/tmp/data.csv'))
    
    # Clear all the data out of the series
    >>> series.delete()