add documentation

Author: dakra

CHANGES.txt

@@ -1,4 +1,4 @@
-0.1.0
------
+0.1
+---
 
--  Initial version
+- First release

README.rst

@@ -1,10 +1,12 @@
-atomx api README
+Python Atomx Api
 ================
 
-Simple interface for the atomx rest api.
+Interface for the atomx rest api.
+`atomx wiki <http://wiki.atomx.com/doku.php?id=api>`_
 
-Example Usage:
---------------
+
+Example Usage
+-------------
 
 .. code-block:: python
 
@@ -60,7 +62,7 @@ Example Usage:
 
     # 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')
+    report = atomx.report(type='publisher', sums=['impressions', 'clicks'], groups=['hour'], 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)
     # if pandas is installed you can get the pandas dataframe with `report.pandas`

atomx/__init__.py

@@ -2,10 +2,10 @@
 
 from datetime import datetime
 import requests
-from .version import API_VERSION, VERSION
-from . import models
-from .utils import get_model_name
-from .exceptions import (
+from atomx.version import API_VERSION, VERSION
+from atomx import models
+from atomx.utils import get_model_name
+from atomx.exceptions import (
     APIError,
     ModelNotFoundError,
     InvalidCredentials,
@@ -21,6 +21,17 @@
 
 
 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>`_
+
+    :param str email: email address of your atomx user
+    :param str password:  password of your atomx user
+    :param str api_endpoint: url for connections to the api
+        (defaults to `https://api.atomx.com/{API_VERSION}`)
+    :return: :class:`.Atomx` session to interact with the api
+    """
     def __init__(self, email, password, api_endpoint=API_ENDPOINT):
         self.email = email
         self.password = password
@@ -29,6 +40,18 @@ def __init__(self, email, password, api_endpoint=API_ENDPOINT):
         self.login()
 
     def login(self, email=None, password=None):
+        """Gets new authentication token for user ``email``.
+
+        This method is automatically called in :meth:`__init__` so
+        you rarely have to call this method directly.
+
+        :param str email: Use this email instead of the one provided at
+            construction time. (optional)
+        :param str password: Use this password instead of the one provided at
+            construction time. (optional)
+        :return: None
+        :raises: :class:`.exceptions.InvalidCredentials` if ``email``/``password`` is wrong
+        """
         if email:
             self.email = email
         if password:
@@ -43,9 +66,37 @@ def login(self, email=None, password=None):
         self.auth_tk = r.json()['auth_tkt']
 
     def logout(self):
+        """Removes authentication token from session."""
+        self.auth_tk = None
         self.session.get(self.api_endpoint + 'logout')
 
     def search(self, query):
+        """Search for ``query``.
+
+        Returns a `dict` with all found results for:
+        'Advertisers', 'Campaigns', 'Creatives', 'Placements', 'Publishers', 'Sites'.
+
+        The resulting :mod:`.models` have only `id` and `name` loaded since that's
+        what's returned from the api `/search` call, but attributes will be lazy loaded
+        once you try to accessed them.
+        Or you can just fetch everything with one api call with :meth:`.AtomxModel.reload`.
+
+        Example::
+
+            >>> atomx = Atomx('apiuser@example.com', 'password')
+            >>> search_result = atomx.search('atomx')
+            >>> assert 'campaigns' in search_result
+            >>> campaign = search_result['campaigns'][0]
+            >>> assert isinstance(campaign, models.Campaign)
+            >>> # campaign has only `id` and `name` loaded but you
+            >>> # can still access (lazy load) all attributes
+            >>> assert isinstance(campaign.budget, float)
+            >>> # or reload all attributes with one api call
+            >>> campaign.reload()
+
+        :param str query: keyword to search for.
+        :return: dict with list of :mod:`.models` as values
+        """
         r = self.session.get(self.api_endpoint + 'search', params={'q': query})
         if not r.ok:
             raise APIError(r.json()['error'])
@@ -61,17 +112,25 @@ def search(self, query):
     def report(self, scope, groups, sums, where, from_, to=None, timezone='UTC', fast=True):
         """Create a report.
 
+        See the `reporting atomx wiki <http://wiki.atomx.com/doku.php?id=reporting>`_
+        for details about parameters and available groups, sums.
+
         :param str scope: either 'advertiser' or 'publisher' to select the type of report.
-        :param list groups: columns to group by (see http://wiki.atomx.com/doku.php?id=reporting#groups)
-        :param list sums: columns to sum on (see http://wiki.atomx.com/doku.php?id=reporting#sums)
+        :param list groups: columns to group by.
+        :param list sums: columns to sum on.
         :param list where: is a list of expression lists.
-            An expression list is in the form of `[column, op, value]`.
-            `column` can be any of the :param:`groups` or :param:`sums` columns.
-            `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.
-        :param datetime from_: `datetime` where the report should start (inclusive)
-        :param datetime to: `datetime` where the report should end (exclusive).
-            (defaults to `datetime.now()` if undefined)
+            An expression list is in the form of ``[column, op, value]``:
+
+                - ``column`` can be any of the ``groups`` or ``sums`` parameter columns.
+                - ``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.
+
+        :param datetime.datetime from_: :class:`datetime.datetime` where the report
+            should start (inclusive)
+        :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
         :param bool fast: if `False` the report will always be run against the low level data.
@@ -98,6 +157,15 @@ def report(self, scope, groups, sums, where, from_, to=None, timezone='UTC', fas
         return models.Report(self, query=r.json()['query'], **r.json()['report'])
 
     def report_status(self, report):
+        """Get the status for a `report`.
+
+        This is typically used by calling :meth:`.models.Report.status`.
+
+        :param report: Either a :class:`str` that contains the ``id`` of
+            of the report or an :class:`.models.Report` instance.
+        :type report: :class:`.models.Report` or :class:`list`
+        :return: :class:`dict` containing the report status.
+        """
         if isinstance(report, models.Report):
             report_id = report.id
         else:
@@ -109,6 +177,16 @@ def report_status(self, report):
         return r.json()['report']
 
     def report_get(self, report):
+        """Get the content (csv) of a :class:`.models.Report`
+
+        Typically used by calling :meth:`.models.Report.content` or
+        :meth:`.models.Report.pandas`.
+
+        :param report: Either a :class:`str` that contains the ``id`` of
+            of the report or an :class:`.models.Report` instance.
+        :type report: :class:`.models.Report` or :class:`list`
+        :return: :class:`str` with the report content.
+        """
         if isinstance(report, models.Report):
             report_id = report.id
         else:
@@ -120,6 +198,47 @@ def report_get(self, report):
         return r.content.decode()
 
     def get(self, resource, **kwargs):
+        """Returns a list of models from :mod:`.models` if you query for
+        multiple models or a single instance of a model from :mod:`.models`
+        if you query for a specific `id`
+
+        :param str resource: Specify the resource to get from the atomx api.
+
+            Examples:
+
+            Query all advertisers::
+
+                >>> atomx = Atomx('apiuser@example.com', 'password')
+                >>> advertisers = atomx.get('advertisers')
+                >>> assert isinstance(advertisers, list)
+                >>> assert isinstance(advertisers[0], atomx.models.Advertiser)
+
+            Get publisher with id 23::
+
+                >>> publisher = atomx.get('publisher/23')
+                >>> assert publisher.id == 23
+                >>> assert isinstance(publisher, atomx.models.Publisher)
+
+            Get all profiles for advertiser 42::
+
+                >>> profiles = atomx.get('advertiser/42/profiles')
+                >>> assert isinstance(profiles, list)
+                >>> assert isinstance(profiles[0], atomx.models.Profile)
+                >>> assert profiles[0].advertiser.id == 42
+
+        :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>`_
+            in the wiki.
+
+            Example:
+            Get the first 20 domains that contain ``atom``::
+
+                >>> atom_domains = atomx.get('domains', hostname='*atom*', limit=20)
+                >>> assert len(atom_domains) == 20
+                >>> assert 'atom' in atom_domains[1].hostname
+
+        :return: a class from :mod:`.models` or a list of models depending on param `resource`
+        """
         r = self.session.get(self.api_endpoint + resource.strip('/'), params=kwargs)
         if not r.ok:
             raise APIError(r.json()['error'])
@@ -134,28 +253,51 @@ def get(self, resource, **kwargs):
             return getattr(models, model)(self, **res)
         return res
 
-    def post(self, model, json, **kwargs):
-        r = self.session.post(self.api_endpoint + model.strip('/'),
+    def post(self, resource, json, **kwargs):
+        """Send HTTP POST to ``resource`` with ``json`` content.
+
+        Used by :meth:`.models.AtomxModel.create`.
+
+        :param resource: Name of the resource to `POST` to.
+        :param json: Content of the `POST` request.
+        :param kwargs: URL Parameters of the request.
+        :return: :class:`dict` with the newly created resource.
+        """
+        r = self.session.post(self.api_endpoint + resource.strip('/'),
                               json=json, params=kwargs)
         r_json = r.json()
         if not r.ok:
             raise APIError(r_json['error'])
         return r_json[r_json['resource']]
 
-    def put(self, model, id, json, **kwargs):
-        r = self.session.put(self.api_endpoint + model.strip('/') + '/' + str(id),
+    def put(self, resource, id, json, **kwargs):
+        """Send HTTP PUT to ``resource``/``id`` with ``json`` content.
+
+        Used by :meth:`.models.AtomxModel.save`.
+
+        :param resource: Name of the resource to `PUT` to.
+        :param id: Id of the resource you want to modify
+        :param json: Content of the `PUT` request.
+        :param kwargs: URL Parameters of the request.
+        :return: :class:`dict` with the modified resource.
+        """
+        r = self.session.put(self.api_endpoint + resource.strip('/') + '/' + str(id),
                              json=json, params=kwargs)
         r_json = r.json()
         if not r.ok:
             raise APIError(r_json['error'])
         return r_json[r_json['resource']]
 
-    def delete(self, model, id, json, **kwargs):
-        return self.session.put(self.api_endpoint + model.strip('/') + '/' + str(id),
-                                json=json, params=kwargs)
+    def delete(self, resource, id, json, **kwargs):
+        """Delete is currently not supported by the api.
+        Set the resources `state` to `INACTIVE` to deactivate it.
+        """
+        pass
 
     def save(self, model):
+        """Alias for :meth:`.models.AtomxModel.save` with `session` argument."""
         return model.save(self)
 
-    def update(self, model):
-        return model.update(self)
+    def create(self, model):
+        """Alias for :meth:`.models.AtomxModel.create` with `session` argument."""
+        return model.create(self)

atomx/exceptions.py

@@ -1,17 +1,25 @@
 class NoSessionError(Exception):
+    """Raised when a model from :mod:`.models` wants to ``create``/``update``
+    but it doesn't have an :class:`atomx.Atomx` session yet.
+    """
     pass
 
 class InvalidCredentials(Exception):
+    """Raised when trying to login with the wrong e-mail or password."""
     pass
 
 class APIError(Exception):
+    """Raised when the atomx api returns an error that is not caught otherwise."""
     pass
 
 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