add report

Author: dakra

README.rst

@@ -58,6 +58,23 @@ Example Usage:
     print(publisher)  # now all publisher data is there
 
 
+    # reporting example
+    # get a report for a specific publisher
+    report = atomx.report(type='publisher', sums=['impressions', 'clicks'], groups=['hour'], where=[['publisher_id', '==', 42]], from_='2015-02-08 00:00:00Z', to='2015-02-09 00:00:00Z')
+    # check if report is ready
+    print(report.is_ready)
+    # if pandas is installed you can get the pandas dataframe with `report.pandas`
+    # you can also get the report csv in `report.content` without pandas
+    df = report.pandas
+    # set index to datetime
+    import pandas as pd
+    df.index = pd.to_datetime(df.pop('hour'))
+    # resample per day
+    means = df.resample('D', how=['mean', 'median', 'std'])
+    # and plot impression and clicks per day
+    means['impressions'].plot()
+    means['clicks'].plot()
+
 
 Installation
 ------------
@@ -68,3 +85,8 @@ To install the python atomx api, simply:
 
     $ pip install atomx
 
+or if you want to use ipython notebook and reporting functionality:
+
+.. code-block:: bash
+
+    $ pip install atomx[report]

atomx/__init__.py

@@ -57,6 +57,36 @@ def search(self, query):
                                     for v in search_result[m]]
         return search_result
 
+    def report(self, **kwargs):
+        kwargs['from'] = kwargs['from_']
+        del kwargs['from_']
+        r = self.session.post(self.api_endpoint + 'report', json=kwargs)
+        if not r.ok:
+            raise APIError(r.json()['error'])
+        return models.Report(self, query=r.json()['query'], **r.json()['report'])
+
+    def report_status(self, report):
+        if isinstance(report, models.Report):
+            report_id = report.id
+        else:
+            report_id = report
+
+        r = self.session.get(self.api_endpoint + 'report/' + report_id, params={'status': True})
+        if not r.ok:
+            raise APIError(r.json()['error'])
+        return r.json()['report']
+
+    def report_get(self, report):
+        if isinstance(report, models.Report):
+            report_id = report.id
+        else:
+            report_id = report
+
+        r = self.session.get(self.api_endpoint + 'report/' + report_id)
+        if not r.ok:
+            raise APIError(r.json()['error'])
+        return r.content.decode()
+
     def get(self, resource, **kwargs):
         r = self.session.get(self.api_endpoint + resource, params=kwargs)
         if not r.ok:

atomx/exceptions.py

@@ -9,3 +9,9 @@ class APIError(Exception):
 
 class ModelNotFoundError(Exception):
     pass
+
+class ReportNotReadyError(Exception):
+    pass
+
+class NoPandasInstalledError(Exception):
+    pass

atomx/models.py

@@ -1,7 +1,17 @@
 # -*- coding: utf-8 -*-
 
 import pprint
-from .exceptions import NoSessionError, ModelNotFoundError, APIError
+try:  # py3
+    from io import StringIO
+except ImportError:  # py2
+    from StringIO import StringIO
+from .exceptions import (
+    NoSessionError,
+    ModelNotFoundError,
+    APIError,
+    ReportNotReadyError,
+    NoPandasInstalledError,
+)
 
 __all__ = ['Advertiser', 'Bidder', 'Browser', 'Campaign', 'Category', 'ConnectionType',
            'ConversionPixel', 'Country', 'Creative', 'Datacenter', 'DeviceType',
@@ -94,3 +104,45 @@ def reload(self, session=None):
 
 for m in __all__:
     locals()[m] = type(m, (AtomxModel,), {})
+
+
+class Report(object):
+    def __init__(self, session, id, fast, status, lines, query, **kwargs):
+        self.session = session
+        self.id = id
+        self.fast = fast
+        self.status = status
+        self.lines = lines
+        self.query = query
+
+    @property
+    def is_ready(self):
+        if hasattr(self, '_is_ready'):
+            return self._is_ready
+        report_status = self.session.report_status(self)
+        self.status = report_status['status']
+        self.lines = report_status['lines']
+        if self.status == 'SUCCESS':
+            setattr(self, '_is_ready', True)
+            return True
+        elif self.status == 'ERROR':
+            setattr(self, '_is_ready', True)
+        return False
+
+    @property
+    def content(self):
+        if not self.is_ready:
+            raise ReportNotReadyError()
+        return self.session.report_get(self)
+
+    @property
+    def pandas(self):
+        try:
+            import pandas as pd
+        except ImportError:
+            raise NoPandasInstalledError('To get the report as a pandas dataframe you '
+                                         'have to have pandas installed. '
+                                         'Do `pip install pandas` in your command line.')
+
+        return pd.read_csv(StringIO(self.content),
+                           names=self.query.get('groups', []) + self.query.get('sums', []))

setup.py

@@ -15,6 +15,11 @@
 requires = [
     'requests',
 ]
+extra_require={
+    'report': ['ipython[notebook]', 'pandas', 'matplotlib'],
+    'test': ['pytest'],
+    'docs': ['sphinx'],
+}
 
 setup(
     name='atomx',
@@ -42,8 +47,5 @@
     keywords='atomx rest api',
 
     install_requires=requires,
-    extra_require={
-        'test': 'pytest',
-        'docs': 'sphinx',
-    }
+    extra_require=extra_require,
 )

tests.py

@@ -3,7 +3,7 @@
 
 @pytest.fixture(scope="session")
 def atomx():
-    from .atomx import Atomx
+    from atomx import Atomx
     return Atomx('daniel@atomx.com', 'password', 'http://127.0.0.1:6543/v1/')
 
 
@@ -21,7 +21,7 @@ def test_update(atomx):
 
 
 def test_save(atomx):
-    from .atomx.models import Profile
+    from atomx.models import Profile
     profile = Profile(advertiser_id=23, name='test advertiser')
     profile.save()
     profile_new = atomx.get(Profile, id=profile.id)