update docs; make release

Author: dakra

CHANGES.txt

@@ -1,5 +1,5 @@
-1.5 (unreleased)
-----------------
+1.5
+---
 
 - :meth:`atomx.Atomx.report` takes ``name`` parameter to name reports
 - remove ``network`` scope in :meth:`atomx.Atomx.report` and add

atomx/__init__.py

@@ -151,8 +151,7 @@ def report(self, scope=None, groups=None, metrics=None, where=None, from_=None,
             An expression list is in the form of ``[column, op, value]``:
 
                 - ``column`` can be any of the ``groups`` or ``metrics`` parameter columns.
-                - ``op`` can be any of ``==``, ``!=``, ``<=``, ``>=``,
-                  ``<``, ``>``, ``in`` or ``not in`` as a string.
+                - ``op`` can be any of ``==``, ``!=``, ``in`` or ``not in`` as a string.
                 - ``value`` is either a number or in case of ``in``
                   and ``not in`` a list of numbers.
 
@@ -201,13 +200,11 @@ def report(self, scope=None, groups=None, metrics=None, where=None, from_=None,
         if where:
             report_json['where'] = where
 
-        if when and interval:
-            is_scheduled_report = True
+        if when and interval:  # scheduled report
             report_json['when'] = when
             report_json['interval'] = interval
-        else:
-            is_scheduled_report = False
 
+        else:  # normal report
             if from_ is None:
                 from_ = datetime.now() - timedelta(days=7)
             if isinstance(from_, datetime):

atomx/exceptions.py

@@ -20,10 +20,6 @@ class ModelNotFoundError(Exception):
     """Raised when trying to (re-)load a model that is not in the api."""
     pass
 
-class ReportNotReadyError(Exception):
-    """Raised when requesting ``report.content`` but the report is not ready yet."""
-    pass
-
 class NoPandasInstalledError(Exception):
     """Raised when trying to access ``report.pandas`` without :mod:`pandas` installed."""
     pass

atomx/models.py

@@ -1,6 +1,5 @@
 # -*- coding: utf-8 -*-
 
-import csv
 import pprint
 from decimal import Decimal
 from datetime import datetime, date
@@ -13,7 +12,6 @@
     NoSessionError,
     ModelNotFoundError,
     APIError,
-    ReportNotReadyError,
     NoPandasInstalledError,
 )
 

atomx/version.py

@@ -1,2 +1,2 @@
-VERSION = '1.5b'
+VERSION = '1.5'
 API_VERSION = 'v3'

docs/usage.rst

@@ -70,6 +70,19 @@ E.g.
     # is equivalent to atomx.get('advertiser/42/profiles')
 
 
+You can also use a class or instance of :mod:`atomx.models` in a get requests.
+E.g. all of those api calls request the same resource:
+
+.. code-block:: python
+
+    from atomx.models import Advertiser
+
+    atomx.get('advertiser/42')  # all in 1 string
+    atomx.get('advertiser', 42)  # model, id split up
+    atomx.get(Advertiser, 42)  # using :class:`atomx.models.Advertiser`
+    atomx.get(Advertiser(42))  # using instance of :class:`atomx.models.Advertiser`
+
+
 Or get all domains where the hostname contains `atom`:
 
 .. code-block:: python
@@ -183,16 +196,22 @@ to create a report.
 
 .. code-block:: python
 
-    # reporting example
+    from datetime import datetime, timedelta
+
+    now = datetime.utcnow()
+    last_week = now - timedelta(days=7)
+
     # get a report for a specific publisher
-    report = atomx.report(scope='publisher', groups=['hour'], metrics=['impressions', 'clicks'], where=[['publisher_id', '==', 42]], from_='2015-02-08 00:00:00', to='2015-02-09 00:00:00', timezone='America/Los_Angeles')
-    # check if report is ready
-    print(report.is_ready)
+    report = atomx.report(scope='publisher', groups=['hour'], metrics=['impressions', 'clicks'], where=[['publisher_id', '==', 42]], from_=last_week, to=now, timezone='America/Los_Angeles')
+
+    report.length  # get the number of rows returned
+    report.totals  # get the total values
+
     # 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  # A datetime index is automatically set when group by a hour/day/month.
     # calculate mean, median, std per hour
-    means = df.resample('H', how=['mean', 'median', 'std'])
+    means = df.resample('H').apply(['mean', 'median', 'std'])
     # and plot impression and clicks per day
     means['impressions'].plot()
     means['clicks'].plot()