Metadata-Version: 2.0
Name: atomx
Version: 1.5
Summary: python interface for the atomx api on https://api.atomx.com
Home-page: https://github.com/atomx/atomx-api-python
Author: Spot Media Solutions Sdn. Bhd.
Author-email: daniel@atomx.com
License: ISC
Keywords: atomx rest api
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: requests
Provides-Extra: docs
Requires-Dist: sphinx; extra == 'docs'
Provides-Extra: report
Requires-Dist: ipython[notebook]; extra == 'report'
Requires-Dist: matplotlib; extra == 'report'
Requires-Dist: pandas; extra == 'report'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'

Python Atomx Api
================

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 <https://wiki.atomx.com/api>`_


Example Usage
-------------

.. code-block:: python

    from atomx import Atomx

    # create atomx session
    atomx = Atomx('user@example.com', 'password')

    # get 10 creatives
    creatives = atomx.get('Creatives', limit=10)
    # the result is a list of `atomx.models.Creative` models
    # that you can easily inspect, manipulate and update
    for creative in creatives:
        print('Creative ID: {c.id}, state: {c.state}, '
              'name: {c.name}, title: {c.title}'.format(c=creative))

    # update title for the first creative in list
    creative = creatives[0]
    creative.title = 'shiny new title'
    # the session is inherited from `atomx` that made the get request
    creative.save()


    # create a new profile
    from atomx.models import Profile
    profile = Profile(advertiser_id=23, name='test profile')
    # Note that you have to pass it a valid `Atomx` session for create
    # or use `atomx.create(profile)`
    profile.create(atomx)

    # now you could alter and update it like the creative above
    profile.name = 'changed name'
    profile.save()


    # you can also get attributes
    profiles = atomx.get('advertiser', 88, 'profiles')
    # equivalent is to pass the complete resource path as string instead of arguments
    profiles = atomx.get('advertiser/88/profiles')  # same as above
    # profiles is now a list of `atomx.models.Profile` that you can
    # read, update, etc again.
    profiles[0].click_frequency_cap_per = 86400
    profiles[0].save()


    # working with search
    s = atomx.search('mini*')
    # s is now a dict with lists of search results for the different models
    # with the model id and name

    publisher = s['publisher'][0]  # get the first publisher..
    publisher.reload()  # .. and load all the data
    print(publisher)  # now all publisher data is there
    publisher.history()  # gets all changes made to this publisher


    # reporting example
    # 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)
    # 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'])
    # and plot impression and clicks per day
    means['impressions'].plot()
    means['clicks'].plot()


Installation
------------

To install the python atomx api, simply:

.. code-block:: bash

    $ pip install atomx

or if you want to use ipython notebook and reporting functionality:

.. code-block:: bash

    $ pip install atomx[report]


