Merge pull request #9 from dyninc/reports

Adding unified module for TM report calls.

Tagging as 1.0.2

HISTORY.rst

@@ -1,5 +1,11 @@
 Release History
 ---------------
+1.0.2 (2014-08-26)
+++++++++++++++++++
+
+* Added reports module
+* Updated installation documentation.
+
 1.0.1 (2014-08-06)
 ++++++++++++++++++
 

docs/install.rst

@@ -10,9 +10,7 @@ The first step to using any software package is getting it properly installed.
 Distribute & Pip
 ----------------
 
-Installing dyn is simple via `pip <http://www.pip-installer.org/>`_. Currently
-the dyn module is only available internally within Dyn, because of this it can
-only be downloaded while on Dyn's internal VPN::
+Installing dyn is simple via `pip <http://www.pip-installer.org/>`_.
 
     $ pip install dyn
 

docs/tm.rst

@@ -25,5 +25,6 @@ this part of the documentation is for you.
    tm/accounts
    tm/records
    tm/services
+   tm/reports
    tm/errors
 

docs/tm/reports.rst

@@ -0,0 +1,17 @@
+.. _tm-reports:
+
+TM Reports
+==========
+The :mod:`~dyn.tm.reports` module contains interfaces for all of the various Report
+collection calls offered by the dyn.tm REST API
+
+List Functions
+--------------
+
+.. autofunction:: dyn.tm.reports.get_check_permission
+.. autofunction:: dyn.tm.reports.get_dnssec_timeline
+.. autofunction:: dyn.tm.reports.get_rttm_log
+.. autofunction:: dyn.tm.reports.get_rttm_rrset
+.. autofunction:: dyn.tm.reports.get_qps
+.. autofunction:: dyn.tm.reports.get_zone_notes
+

dyn/__init__.py

@@ -5,7 +5,7 @@
 
 Requires Python 2.6 or higher, or the "simplejson" package.
 """
-version_info = (1, 0, 1)
+version_info = (1, 0, 2)
 __name__       = 'dyn'
 __doc__        = 'A python wrapper for the DynDNS and DynEmail APIs'
 __author__     = 'Jonathan Nappi, Cole Tuininga'

dyn/tm/reports.py

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+"""This module contains interfaces for all Report generation features of the
+REST API
+"""
+from .session import DynectSession
+
+__author__ = 'elarochelle'
+__all__ = ['get_check_permission', 'get_dnssec_timeline', 'get_qps',
+           'get_rttm_log', 'get_rttm_rrset', 'get_zone_notes']
+
+
+def get_check_permission(permission, zone_name=None):
+    """Returns a list of allowed and forbidden permissions for the currently
+    logged in user based on the provided permissions array.
+
+    :param permission: A list of permissions to check for the current user.
+    :param zone_name: The zone to check for specific permissions.
+    :return: A :class:`dict` containing permission information.
+    """
+    api_args = {'permission': permission}
+    if zone_name is not None:
+        api_args['zone_name'] = zone_name
+    response = DynectSession.get_session().execute('/CheckPermissionReport/',
+                                                   'POST', api_args)
+    return response['data']
+
+
+def get_dnssec_timeline(zone_name, start_ts=None, end_ts=None):
+    """Generates a report of events for the :class:`DNSSEC` service
+    attached to the specified zone has performed and has scheduled
+    to perform.
+
+    :param zone_name: The name of the zone with DNSSEC service
+    :param start_ts: UNIX timestamp identifying point in time for the
+        report
+    :param end_ts: UNIX timestamp indicating the end of the data range for
+        the report
+    :return: A :class:`dict` containing log report data
+    """
+    api_args = {'zone': zone_name}
+    if start_ts is not None:
+        api_args['start_ts'] = start_ts
+    if end_ts is not None:
+        api_args['end_ts'] = end_ts
+    response = DynectSession.get_session().execute('/DNSSECTimelineReport/',
+                                                   'POST', api_args)
+    return response['data']
+
+
+def get_rttm_log(zone_name, fqdn, start_ts, end_ts):
+    """Generates a report with information about changes to an existing
+    RTTM service.
+
+    :param zone_name: The name of the zone
+    :param fqdn: The FQDN where RTTM is attached
+    :param start_ts: UNIX timestamp identifying point in time for the log
+        report
+    :param end_ts: UNIX timestamp indicating the end of the data range for
+        the report
+    :return: A :class:`dict` containing log report data
+    """
+    api_args = {'zone': zone_name,
+                'fqdn': fqdn,
+                'start_ts': start_ts,
+                'end_ts': end_ts}
+    response = DynectSession.get_session().execute('/RTTMLogReport/',
+                                                   'POST', api_args)
+    return response['data']
+
+
+def get_rttm_rrset(zone_name, fqdn, ts):
+    """Generates a report of regional response sets for this RTTM service
+    at a given point in time.
+
+    :param zone_name: The name of the zone
+    :param fqdn: The FQDN where RTTM is attached
+    :param ts: UNIX timestamp identifying point in time for the report
+    :return: A :class:`dict` containing rrset report data
+    """
+    api_args = {'zone': zone_name,
+                'fqdn': fqdn,
+                'ts': ts}
+    response = DynectSession.get_session().execute('/RTTMRRSetReport/',
+                                                   'POST', api_args)
+    return response['data']
+
+
+def get_qps(start_ts, end_ts, breakdown=None, hosts=None, rrecs=None,
+            zones = None):
+    """Generates a report with information about Queries Per Second (QPS).
+
+    :param start_ts: UNIX timestamp identifying point in time for the QPS
+        report
+    :param end_ts: UNIX timestamp indicating the end of the data range for
+        the report
+    :param breakdown: By default, most data is aggregated together.
+        Valid values ('hosts', 'rrecs', 'zones').
+    :param hosts: List of hosts to include in the report.
+    :param rrecs: List of record types to include in report.
+    :param zones: List of zones to include in report.
+    :return: A :class:`str` with CSV data
+    """
+    api_args = {'start_ts': start_ts,
+                'end_ts': end_ts}
+    if breakdown is not None:
+        api_args['breakdown'] = breakdown
+    if hosts is not None:
+        api_args['hosts'] = hosts
+    if rrecs is not None:
+        api_args['rrecs'] = rrecs
+    if zones is not None:
+        api_args['zones'] = zones
+    response = DynectSession.get_session().execute('/QPSReport/',
+                                                   'POST', api_args)
+    return response['data']
+
+
+def get_zone_notes(zone_name, offset=None, limit=None):
+    """Generates a report containing the Zone Notes for given zone.
+
+    :param zone_name: The name of the zone
+    :param offset: UNIX timestamp of the starting point at which to
+        retrieve the notes
+    :param limit: The maximum number of notes to be retrieved
+    :return: A :class:`list` of :class:`dict` containing Zone Notes
+    """
+    api_args = {'zone': zone_name}
+    if offset:
+        api_args['offset'] = offset
+    if limit:
+        api_args['limit'] = limit
+    response = DynectSession.get_session().execute('/ZoneNoteReport/',
+                                                   'POST', api_args)
+    return response['data']