- Add :class:atomx.models.ScheduledReport

- :meth:`atomx.Atomx.report` accepts ``when`` and ``interval`` to create a :class:`atomx.models.ScheduledReport`
- Changed wiki links to https
- release 1.4

Author: dakra

CHANGES.txt

@@ -1,9 +1,12 @@
-1.4  (unreleased)
------------------
+1.4
+---
 
 - Change default API version to `v2`
 - If :meth:`atomx.Atomx.post` returns a list, auto-convert list of objects
   to a list of :mod:`atomx.models` models. (Useful for `POST` to the `/domains` endpoint)
+- Add :class:`atomx.models.ScheduledReport`
+- :meth:`atomx.Atomx.report` accepts ``when`` and ``interval`` to create a
+  :class:`atomx.models.ScheduledReport`
 
 
 1.3

README.rst

@@ -6,7 +6,7 @@ Interface for the atomx rest api.
 For more information read the full
 `documentation online <http://atomx-api-python.readthedocs.org/en/latest/index.html>`_,
 report bugs in `github <https://github.com/atomx/atomx-api-python>`_
-or see the `atomx wiki <http://wiki.atomx.com/doku.php?id=api>`_
+or see the `atomx wiki <https://wiki.atomx.com/api>`_
 
 
 Example Usage

atomx/__init__.py

@@ -31,7 +31,7 @@ class Atomx(object):
     """Interface for the api on api.atomx.com.
 
     To learn more about the api visit the
-    `atomx wiki <http://wiki.atomx.com/doku.php?id=api>`_
+    `atomx wiki <https://wiki.atomx.com/api>`_
 
     :param str email: email address of your atomx user
     :param str password:  password of your atomx user
@@ -131,11 +131,11 @@ def search(self, query):
                                     for v in search_result[m]]
         return search_result
 
-    def report(self, scope=None, groups=None, metrics=None, where=None,
-               from_=None, to=None, timezone='UTC', emails=None, fast=True):
+    def report(self, scope=None, groups=None, metrics=None, where=None, from_=None, to=None,
+               timezone='UTC', emails=None, fast=True, when=None, interval=None):
         """Create a report.
 
-        See the `reporting atomx wiki <http://wiki.atomx.com/doku.php?id=reporting>`_
+        See the `reporting atomx wiki <https://wiki.atomx.com/reporting>`_
         for details about parameters and available groups, metrics.
 
         :param str scope: either 'advertiser', 'publisher' or 'network' to select the type
@@ -157,14 +157,16 @@ def report(self, scope=None, groups=None, metrics=None, where=None,
         :param datetime.datetime to: :class:`datetime.datetime` where the report
             should end (exclusive). (defaults to `datetime.now()` if undefined)
         :param str timezone:  Timezone used for all times. (defaults to `UTC`)
-            For a supported list see http://wiki.atomx.com/doku.php?id=timezones
+            For a supported list see https://wiki.atomx.com/timezones
         :param emails: One or multiple email addresses that should get
             notified once the report is finished and ready to download.
         :type emails: str or list
         :param bool fast: if `False` the report will always be run against the low level data.
             This is useful for billing reports for example.
             The default is `True` which means it will always try to use aggregate data
             to speed up the query.
+        :param str when: When should the scheduled report run. (daily, monthly, monday-sunday)
+        :param str interval: Time period included in the scheduled report ('N days' or 'N month')
         :return: A :class:`atomx.models.Report` model
         """
         report_json = {'timezone': timezone, 'fast': fast}
@@ -198,19 +200,26 @@ def report(self, scope=None, groups=None, metrics=None, where=None,
         if where:
             report_json['where'] = where
 
-        if from_ is None:
-            from_ = datetime.now() - timedelta(days=7)
-        if isinstance(from_, datetime):
-            report_json['from'] = from_.strftime("%Y-%m-%d %H:00:00")
+        if when and interval:
+            is_scheduled_report = True
+            report_json['when'] = when
+            report_json['interval'] = interval
         else:
-            report_json['from'] = from_
+            is_scheduled_report = False
 
-        if to is None:
-            to = datetime.now()
-        if isinstance(to, datetime):
-            report_json['to'] = to.strftime("%Y-%m-%d %H:00:00")
-        else:
-            report_json['to'] = to
+            if from_ is None:
+                from_ = datetime.now() - timedelta(days=7)
+            if isinstance(from_, datetime):
+                report_json['from'] = from_.strftime("%Y-%m-%d %H:00:00")
+            else:
+                report_json['from'] = from_
+
+            if to is None:
+                to = datetime.now()
+            if isinstance(to, datetime):
+                report_json['to'] = to.strftime("%Y-%m-%d %H:00:00")
+            else:
+                report_json['to'] = to
 
         if emails:
             if not isinstance(emails, list):
@@ -227,6 +236,9 @@ def report(self, scope=None, groups=None, metrics=None, where=None,
             del r_json['report']
             self.last_response = r_json
 
+        if is_scheduled_report:
+            return models.ScheduledReport(self, query=r.json()['query'], **report)
+
         return models.Report(self, query=r.json()['query'], **report)
 
     def report_status(self, report):
@@ -324,7 +336,7 @@ def get(self, resource, *args, **kwargs):
                 # is equivalent to atomx.get('advertiser/42/profiles')
 
         :param kwargs: Any argument is passed as URL parameter to the respective api endpoint.
-            See `API URL Parameters <http://wiki.atomx.com/doku.php?id=api#url_parameters>`_
+            See `API URL Parameters <https://wiki.atomx.com/api#url_parameters>`_
             in the wiki.
 
             Example:
@@ -354,6 +366,11 @@ def get(self, resource, *args, **kwargs):
             if isinstance(res, list):
                 return [getattr(models, model)(self, **m) for m in res]
             return getattr(models, model)(self, **res)
+        elif model_name == 'reporting':  # special case for `/reports` status
+            return {
+                'reports': [models.Report(self, **m) for m in res['reports']],
+                'scheduled': [models.ScheduledReport(self, **m) for m in res['scheduled']]
+            }
         return res
 
     def post(self, resource, json, **kwargs):

atomx/models.py

@@ -190,6 +190,28 @@ def reload(self, session=None):
                        {'__doc__': ':class:`.AtomxModel` for {}'.format(m)})
 
 
+class ScheduledReport(object):
+    """A report scheduling object that you get back when registering a new scheduled report.
+    See the `scheduling section in the atomx wiki
+    <https://wiki.atomx.com/reporting#scheduling_reports>`_.
+    """
+
+    def __init__(self, session, id, query, **kwargs):
+        self.session = session
+        self.id = id
+        self.query = query
+
+    def __repr__(self):
+        return "ScheduledReport(id='{}', query={})".format(self.id, self.query)
+
+    def __eq__(self, other):
+        return self.id == getattr(other, 'id', 'INVALID')
+
+    def delete(self, session=None):
+        """Delete scheduled report"""
+        return self.session.delete('report', self.id)
+
+
 class Report(object):
     """Represents a `report` you get back from :meth:`atomx.Atomx.report`."""
 

atomx/version.py

@@ -1,2 +1,2 @@
-VERSION = '1.4b'
+VERSION = '1.4'
 API_VERSION = 'v2'

docs/api.rst

@@ -19,6 +19,9 @@ Models
 .. automodule:: atomx.models
     :members:
 
+.. autoclass:: atomx.models.ScheduledReport
+    :members:
+
 .. autoclass:: atomx.models.Report
     :members: