/gdata/analytics/data.py

  1#!/usr/bin/python
  2#
  3# Copyright 2009 Google Inc. All Rights Reserved.
  4#
  5# Licensed under the Apache License, Version 2.0 (the "License");
  6# you may not use this file except in compliance with the License.
  7# You may obtain a copy of the License at
  8#
  9#      http://www.apache.org/licenses/LICENSE-2.0
 10#
 11# Unless required by applicable law or agreed to in writing, software
 12# distributed under the License is distributed on an "AS IS" BASIS,
 13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14# See the License for the specific language governing permissions and
 15# limitations under the License.
 16
 17"""Data model classes for parsing and generating XML for the
 18Google Analytics Data Export API."""
 19
 20__author__ = 'api.nickm@google.com (Nick Mihailovski)'
 21
 22
 23import gdata.data
 24import atom.core
 25
 26
 27# XML Namespace used in Google Analytics API entities.
 28DXP_NS = '{http://schemas.google.com/analytics/2009}%s'
 29GA_NS = '{http://schemas.google.com/ga/2009}%s'
 30
 31
 32class GetProperty(object):
 33  """Utility class to simplify retrieving Property objects."""
 34
 35  def get_property(self, name):
 36    """Helper method to return a propery object by its name attribute.
 37
 38    Args:
 39      name: string The name of the <dxp:property> element to retrieve.
 40
 41    Returns:
 42      A property object corresponding to the matching <dxp:property> element.
 43          if no property is found, None is returned.
 44    """
 45
 46    for prop in self.property:
 47      if prop.name == name:
 48        return prop
 49
 50    return None
 51
 52  GetProperty = get_property
 53
 54
 55class GetMetric(object):
 56  """Utility class to simplify retrieving Metric objects."""
 57
 58  def get_metric(self, name):
 59    """Helper method to return a propery value by its name attribute
 60
 61    Args:
 62      name: string The name of the <dxp:metric> element to retrieve.
 63
 64    Returns:
 65      A property object corresponding to the matching <dxp:metric> element.
 66          if no property is found, None is returned.
 67    """
 68
 69    for met in self.metric:
 70      if met.name == name:
 71        return met
 72
 73    return None
 74
 75  GetMetric = get_metric
 76
 77
 78class GetDimension(object):
 79  """Utility class to simplify retrieving Dimension objects."""
 80
 81  def get_dimension(self, name):
 82    """Helper method to return a dimention object by its name attribute
 83
 84    Args:
 85      name: string The name of the <dxp:dimension> element to retrieve.
 86
 87    Returns:
 88      A dimension object corresponding to the matching <dxp:dimension> element.
 89          if no dimension is found, None is returned.
 90    """
 91
 92    for dim in self.dimension:
 93      if dim.name == name:
 94        return dim
 95
 96    return None
 97
 98  GetDimension = get_dimension
 99
100
101class StartDate(atom.core.XmlElement):
102  """Analytics Feed <dxp:startDate>"""
103  _qname = DXP_NS % 'startDate'
104
105
106class EndDate(atom.core.XmlElement):
107  """Analytics Feed <dxp:endDate>"""
108  _qname = DXP_NS % 'endDate'
109
110
111class Metric(atom.core.XmlElement):
112  """Analytics Feed <dxp:metric>"""
113  _qname = DXP_NS % 'metric'
114  name = 'name'
115  type = 'type'
116  value = 'value'
117  confidence_interval = 'confidenceInterval'
118
119
120class Aggregates(atom.core.XmlElement, GetMetric):
121  """Analytics Data Feed <dxp:aggregates>"""
122  _qname = DXP_NS % 'aggregates'
123  metric = [Metric]
124
125
126class TableId(atom.core.XmlElement):
127  """Analytics Feed <dxp:tableId>"""
128  _qname = DXP_NS % 'tableId'
129
130
131class TableName(atom.core.XmlElement):
132  """Analytics Feed <dxp:tableName>"""
133  _qname = DXP_NS % 'tableName'
134
135
136class Property(atom.core.XmlElement):
137  """Analytics Feed <dxp:property>"""
138  _qname = DXP_NS % 'property'
139  name = 'name'
140  value = 'value'
141
142
143class Definition(atom.core.XmlElement):
144  """Analytics Feed <dxp:definition>"""
145  _qname = DXP_NS % 'definition'
146
147
148class Segment(atom.core.XmlElement):
149  """Analytics Feed <dxp:segment>"""
150  _qname = DXP_NS % 'segment'
151  id = 'id'
152  name = 'name'
153  definition = Definition
154
155
156class Engagement(atom.core.XmlElement):
157  """Analytics Feed <dxp:engagement>"""
158  _qname = GA_NS % 'engagement'
159  type = 'type'
160  comparison = 'comparison'
161  threshold_value = 'thresholdValue'
162
163
164class Step(atom.core.XmlElement):
165  """Analytics Feed <dxp:step>"""
166  _qname = GA_NS % 'step'
167  number = 'number'
168  name = 'name'
169  path = 'path'
170
171
172class Destination(atom.core.XmlElement):
173  """Analytics Feed <dxp:destination>"""
174  _qname = GA_NS % 'destination'
175  step = [Step]
176  expression = 'expression'
177  case_sensitive = 'caseSensitive'
178  match_type = 'matchType'
179  step1_required = 'step1Required'
180
181
182class Goal(atom.core.XmlElement):
183  """Analytics Feed <dxp:goal>"""
184  _qname = GA_NS % 'goal'
185  destination = Destination
186  engagement = Engagement
187  number = 'number'
188  name = 'name'
189  value = 'value'
190  active = 'active'
191
192
193class CustomVariable(atom.core.XmlElement):
194  """Analytics Data Feed <dxp:customVariable>"""
195  _qname = GA_NS % 'customVariable'
196  index = 'index'
197  name = 'name'
198  scope = 'scope'
199
200
201class DataSource(atom.core.XmlElement, GetProperty):
202  """Analytics Data Feed <dxp:dataSource>"""
203  _qname = DXP_NS % 'dataSource'
204  table_id = TableId
205  table_name = TableName
206  property = [Property]
207
208
209class Dimension(atom.core.XmlElement):
210  """Analytics Feed <dxp:dimension>"""
211  _qname = DXP_NS % 'dimension'
212  name = 'name'
213  value = 'value'
214
215
216# Account Feed.
217class AccountEntry(gdata.data.GDEntry, GetProperty):
218  """Analytics Account Feed <entry>"""
219  _qname = atom.data.ATOM_TEMPLATE % 'entry'
220  table_id = TableId
221  property = [Property]
222  goal = [Goal]
223  custom_variable = [CustomVariable]
224
225
226class AccountFeed(gdata.data.GDFeed):
227  """Analytics Account Feed <feed>"""
228  _qname = atom.data.ATOM_TEMPLATE % 'feed'
229  segment = [Segment]
230  entry = [AccountEntry]
231
232
233# Data Feed.
234class DataEntry(gdata.data.GDEntry, GetMetric, GetDimension):
235  """Analytics Data Feed <entry>"""
236  _qname = atom.data.ATOM_TEMPLATE % 'entry'
237  dimension = [Dimension]
238  metric = [Metric]
239
240  def get_object(self, name):
241    """Returns either a Dimension or Metric object with the same name as the
242    name parameter.
243
244    Args:
245      name: string The name of the object to retrieve.
246
247    Returns:
248      Either a Dimension or Object that has the same as the name parameter.
249    """
250
251    output = self.GetDimension(name)
252    if not output:
253      output = self.GetMetric(name)
254
255    return output
256
257  GetObject = get_object
258
259
260class DataFeed(gdata.data.GDFeed):
261  """Analytics Data Feed <feed>. Althrough there is only one datasource, it is
262  stored in an array to replicate the design of the Java client library and
263  ensure backwards compatibility if new data sources are added in the future.
264  """
265
266  _qname = atom.data.ATOM_TEMPLATE % 'feed'
267  start_date = StartDate
268  end_date = EndDate
269  aggregates = Aggregates
270  data_source = [DataSource]
271  entry = [DataEntry]
272  segment = Segment
273