#!/usr/bin/python
#
# Copyright (C) 2006 Google Inc.
# Refactored in 2009 to work for Google Analytics by Sal Uryasev at Juice Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""
  AccountsService extends the GDataService to streamline Google Analytics
            account information operations.

  AnalyticsDataService: Provides methods to query google analytics data feeds.
                    Extends GDataService.

  DataQuery: Queries a Google Analytics Data list feed.
  
  AccountQuery: Queries a Google Analytics Account list feed.
"""


__author__ = 'api.suryasev (Sal Uryasev)'


import urllib
import atom
import gdata.service
import gdata.analytics


class AccountsService(gdata.service.GDataService):

  """Client extension for the Google Analytics Account List feed."""

  def __init__(self, email="", password=None, source=None,
               server='www.google.com/analytics', additional_headers=None, 
               **kwargs):
    """Creates a client for the Google Analytics service.

    Args:
      email: string (optional) The user's email address, used for
          authentication.
      password: string (optional) The user's password.
      source: string (optional) The name of the user's application.
      server: string (optional) The name of the server to which a connection
          will be opened.
      **kwargs: The other parameters to pass to gdata.service.GDataService
          constructor.
    """
    
    gdata.service.GDataService.__init__(
        self, email=email, password=password, service='analytics', 
        source=source, server=server, additional_headers=additional_headers,
        **kwargs)

  def QueryAccountListFeed(self, uri):
    """Retrieves an AccountListFeed by retrieving a URI based off the Document
       List feed, including any query parameters. An AccountListFeed object 
       can be used to construct these parameters.

    Args:
      uri: string The URI of the feed being retrieved possibly with query
           parameters.

    Returns:
      An AccountListFeed object representing the feed returned by the server.
    """
    return self.Get(uri, converter=gdata.analytics.AccountListFeedFromString)

  def GetAccountListEntry(self, uri):
    """Retrieves a particular AccountListEntry by its unique URI.

    Args:
      uri: string The unique URI of an entry in an Account List feed.

    Returns:
      An AccountLisFeed object representing the retrieved entry.
      """
    return self.Get(uri, converter=gdata.analytics.AccountListEntryFromString)

  def GetAccountList(self, max_results=1000, text_query=None,
                     params=None, categories=None):
    """Retrieves a feed containing all of a user's accounts and profiles."""
    q = gdata.analytics.service.AccountQuery(max_results=max_results,
                                             text_query=text_query, 
                                             params=params,
                                             categories=categories);
    return self.QueryAccountListFeed(q.ToUri())




class AnalyticsDataService(gdata.service.GDataService):

  """Client extension for the Google Analytics service Data List feed."""

  def __init__(self, email=None, password=None, source=None,
               server='www.google.com/analytics', additional_headers=None, 
               **kwargs):
    """Creates a client for the Google Analytics service.

    Args:
      email: string (optional) The user's email address, used for
          authentication.
      password: string (optional) The user's password.
      source: string (optional) The name of the user's application.
      server: string (optional) The name of the server to which a connection
          will be opened. Default value: 'docs.google.com'.
      **kwargs: The other parameters to pass to gdata.service.GDataService
          constructor.
    """
    
    gdata.service.GDataService.__init__(self, 
        email=email, password=password, service='analytics', source=source,
        server=server, additional_headers=additional_headers, **kwargs)
    
  def GetData(self, ids='', dimensions='', metrics='',
              sort='', filters='', start_date='',
              end_date='', start_index='',
              max_results=''):
    """Retrieves a feed containing a user's data
    
      ids: comma-separated string of analytics accounts.
      dimensions: comma-separated string of dimensions.
      metrics: comma-separated string of metrics.
      sort: comma-separated string of dimensions and metrics for sorting.
            This may be previxed with a minus to sort in reverse order. 
                (e.g. '-ga:keyword')
            If ommited, the first dimension passed in will be used.
      filters: comma-separated string of filter parameters.
            (e.g. 'ga:keyword==google')
      start_date: start date for data pull.
      end_date: end date for data pull.
      start_index: used in combination with max_results to pull more than 1000 
            entries. This defaults to 1.
      max_results: maximum results that the pull will return.  This defaults
            to, and maxes out at 1000.
    """
    q = gdata.analytics.service.DataQuery(ids=ids, 
                                          dimensions=dimensions,
                                          metrics=metrics,
                                          filters=filters,
                                          sort=sort,
                                          start_date=start_date,
                                          end_date=end_date,
                                          start_index=start_index,
                                          max_results=max_results);
    return self.AnalyticsDataFeed(q.ToUri())
    
  def AnalyticsDataFeed(self, uri):
    """Retrieves an AnalyticsListFeed by retrieving a URI based off the 
       Document List feed, including any query parameters. An 
       AnalyticsListFeed object can be used to construct these parameters.

    Args:
      uri: string The URI of the feed being retrieved possibly with query
           parameters.

    Returns:
      An AnalyticsListFeed object representing the feed returned by the 
      server.
    """
    return self.Get(uri,
                    converter=gdata.analytics.AnalyticsDataFeedFromString)
    
  """
  Account Fetching
  """    
    
  def QueryAccountListFeed(self, uri):
    """Retrieves an Account ListFeed by retrieving a URI based off the Account
       List feed, including any query parameters. A AccountQuery object can
       be used to construct these parameters.

    Args:
      uri: string The URI of the feed being retrieved possibly with query
           parameters.

    Returns:
      An AccountListFeed object representing the feed returned by the server.
    """
    return self.Get(uri, converter=gdata.analytics.AccountListFeedFromString)

  def GetAccountListEntry(self, uri):
    """Retrieves a particular AccountListEntry by its unique URI.

    Args:
      uri: string The unique URI of an entry in an Account List feed.

    Returns:
      An AccountListEntry object representing the retrieved entry.
      """
    return self.Get(uri, converter=gdata.analytics.AccountListEntryFromString)

  def GetAccountList(self, username="default", max_results=1000, 
                     start_index=1):
    """Retrieves a feed containing all of a user's accounts and profiles.
       The username parameter is soon to be deprecated, with 'default' 
       becoming the only allowed parameter.
    """
    if not username:
      raise Exception("username is a required parameter")
    q = gdata.analytics.service.AccountQuery(username=username, 
                                             max_results=max_results,
                                             start_index=start_index);
    return self.QueryAccountListFeed(q.ToUri())

class DataQuery(gdata.service.Query):
  """Object used to construct a URI to a data feed"""
  def __init__(self, feed='/feeds/data', text_query=None, 
               params=None, categories=None, ids="",
               dimensions="", metrics="", sort="", filters="",
               start_date="", end_date="", start_index="",
               max_results=""):
    """Constructor for Analytics List Query

    Args:
      feed: string (optional) The path for the feed. (e.g. '/feeds/data')

      text_query: string (optional) The contents of the q query parameter. 
            This string is URL escaped upon conversion to a URI.
      params: dict (optional) Parameter value string pairs which become URL
            params when translated to a URI. These parameters are added to
              the query's items.
      categories: list (optional) List of category strings which should be
            included as query categories. See gdata.service.Query for
            additional documentation.
      ids: comma-separated string of analytics accounts.
      dimensions: comma-separated string of dimensions.
      metrics: comma-separated string of metrics.
      sort: comma-separated string of dimensions and metrics.
            This may be previxed with a minus to sort in reverse order 
            (e.g. '-ga:keyword').
            If ommited, the first dimension passed in will be used.
      filters: comma-separated string of filter parameters 
            (e.g. 'ga:keyword==google').
      start_date: start date for data pull.
      end_date: end date for data pull.
      start_index: used in combination with max_results to pull more than 1000 
            entries. This defaults to 1.
      max_results: maximum results that the pull will return.  This defaults 
            to, and maxes out at 1000.

    Yields:
      A DocumentQuery object used to construct a URI based on the Document
      List feed.
    """
    self.elements = {'ids': ids,
                     'dimensions': dimensions,
                     'metrics': metrics,
                     'sort': sort,
                     'filters': filters,
                     'start-date': start_date,
                     'end-date': end_date,
                     'start-index': start_index,
                     'max-results': max_results}
    
    gdata.service.Query.__init__(self, feed, text_query, params, categories)
  
  def ToUri(self):
    """Generates a URI from the query parameters set in the object.

    Returns:
      A string containing the URI used to retrieve entries from the Analytics
      List feed.
    """
    old_feed = self.feed
    self.feed = '/'.join([old_feed]) + '?' + \
                urllib.urlencode(dict([(key, value) for key, value in \
                self.elements.iteritems() if value]))
    new_feed = gdata.service.Query.ToUri(self)
    self.feed = old_feed
    return new_feed


class AccountQuery(gdata.service.Query):
  """Object used to construct a URI to query the Google Account List feed"""
  def __init__(self, feed='/feeds/accounts', start_index=1,
               max_results=1000, username='default', text_query=None,
               params=None, categories=None):
    """Constructor for Account List Query

    Args:
      feed: string (optional) The path for the feed. (e.g. '/feeds/documents')
      visibility: string (optional) The visibility chosen for the current 
            feed.
      projection: string (optional) The projection chosen for the current 
            feed.
      text_query: string (optional) The contents of the q query parameter. 
            This string is URL escaped upon conversion to a URI.
      params: dict (optional) Parameter value string pairs which become URL
              params when translated to a URI. These parameters are added to
              the query's items.
      categories: list (optional) List of category strings which should be
              included as query categories. See gdata.service.Query for
              additional documentation.
      username: string (deprecated) This value should now always be passed as 
              'default'.

    Yields:
      A DocumentQuery object used to construct a URI based on the Document
      List feed.
    """
    self.max_results = max_results
    self.start_index = start_index
    self.username = username
    gdata.service.Query.__init__(self, feed, text_query, params, categories)
  
  def ToUri(self):
    """Generates a URI from the query parameters set in the object.

    Returns:
      A string containing the URI used to retrieve entries from the Account
      List feed.
    """
    old_feed = self.feed
    self.feed = '/'.join([old_feed, self.username]) + '?' + \
                '&'.join(['max-results=' + str(self.max_results), 
                          'start-index=' + str(self.start_index)])
    new_feed = self.feed
    self.feed = old_feed
    return new_feed