/gdata/spreadsheets/data.py

http://radioappz.googlecode.com/ · Python · 317 lines · 190 code · 49 blank · 78 comment · 10 complexity · a5aa5c40b800bfa223b3587e6261fc35 MD5 · raw file

  1. #!/usr/bin/env python
  2. #
  3. # Copyright (C) 2009 Google Inc.
  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. # This module is used for version 2 of the Google Data APIs.
  17. """Provides classes and constants for the XML in the Google Spreadsheets API.
  18. Documentation for the raw XML which these classes represent can be found here:
  19. http://code.google.com/apis/spreadsheets/docs/3.0/reference.html#Elements
  20. """
  21. __author__ = 'j.s@google.com (Jeff Scudder)'
  22. import atom.core
  23. import gdata.data
  24. GS_TEMPLATE = '{http://schemas.google.com/spreadsheets/2006}%s'
  25. GSX_NAMESPACE = 'http://schemas.google.com/spreadsheets/2006/extended'
  26. INSERT_MODE = 'insert'
  27. OVERWRITE_MODE = 'overwrite'
  28. WORKSHEETS_REL = 'http://schemas.google.com/spreadsheets/2006#worksheetsfeed'
  29. class Error(Exception):
  30. pass
  31. class FieldMissing(Exception):
  32. pass
  33. class HeaderNotSet(Error):
  34. """The desired column header had no value for the row in the list feed."""
  35. class Cell(atom.core.XmlElement):
  36. """The gs:cell element.
  37. A cell in the worksheet. The <gs:cell> element can appear only as a child
  38. of <atom:entry>.
  39. """
  40. _qname = GS_TEMPLATE % 'cell'
  41. col = 'col'
  42. input_value = 'inputValue'
  43. numeric_value = 'numericValue'
  44. row = 'row'
  45. class ColCount(atom.core.XmlElement):
  46. """The gs:colCount element.
  47. Indicates the number of columns in the worksheet, including columns that
  48. contain only empty cells. The <gs:colCount> element can appear as a child
  49. of <atom:entry> or <atom:feed>
  50. """
  51. _qname = GS_TEMPLATE % 'colCount'
  52. class Field(atom.core.XmlElement):
  53. """The gs:field element.
  54. A field single cell within a record. Contained in an <atom:entry>.
  55. """
  56. _qname = GS_TEMPLATE % 'field'
  57. index = 'index'
  58. name = 'name'
  59. class Column(Field):
  60. """The gs:column element."""
  61. _qname = GS_TEMPLATE % 'column'
  62. class Data(atom.core.XmlElement):
  63. """The gs:data element.
  64. A data region of a table. Contained in an <atom:entry> element.
  65. """
  66. _qname = GS_TEMPLATE % 'data'
  67. column = [Column]
  68. insertion_mode = 'insertionMode'
  69. num_rows = 'numRows'
  70. start_row = 'startRow'
  71. class Header(atom.core.XmlElement):
  72. """The gs:header element.
  73. Indicates which row is the header row. Contained in an <atom:entry>.
  74. """
  75. _qname = GS_TEMPLATE % 'header'
  76. row = 'row'
  77. class RowCount(atom.core.XmlElement):
  78. """The gs:rowCount element.
  79. Indicates the number of total rows in the worksheet, including rows that
  80. contain only empty cells. The <gs:rowCount> element can appear as a
  81. child of <atom:entry> or <atom:feed>.
  82. """
  83. _qname = GS_TEMPLATE % 'rowCount'
  84. class Worksheet(atom.core.XmlElement):
  85. """The gs:worksheet element.
  86. The worksheet where the table lives.Contained in an <atom:entry>.
  87. """
  88. _qname = GS_TEMPLATE % 'worksheet'
  89. name = 'name'
  90. class Spreadsheet(gdata.data.GDEntry):
  91. """An Atom entry which represents a Google Spreadsheet."""
  92. def find_worksheets_feed(self):
  93. return self.find_url(WORKSHEETS_REL)
  94. FindWorksheetsFeed = find_worksheets_feed
  95. class SpreadsheetsFeed(gdata.data.GDFeed):
  96. """An Atom feed listing a user's Google Spreadsheets."""
  97. entry = [Spreadsheet]
  98. class WorksheetEntry(gdata.data.GDEntry):
  99. """An Atom entry representing a single worksheet in a spreadsheet."""
  100. row_count = RowCount
  101. col_count = ColCount
  102. class WorksheetsFeed(gdata.data.GDFeed):
  103. """A feed containing the worksheets in a single spreadsheet."""
  104. entry = [WorksheetEntry]
  105. class Table(gdata.data.GDEntry):
  106. """An Atom entry that represents a subsection of a worksheet.
  107. A table allows you to treat part or all of a worksheet somewhat like a
  108. table in a database that is, as a set of structured data items. Tables
  109. don't exist until you explicitly create them before you can use a table
  110. feed, you have to explicitly define where the table data comes from.
  111. """
  112. data = Data
  113. header = Header
  114. worksheet = Worksheet
  115. def get_table_id(self):
  116. if self.id.text:
  117. return self.id.text.split('/')[-1]
  118. return None
  119. GetTableId = get_table_id
  120. class TablesFeed(gdata.data.GDFeed):
  121. """An Atom feed containing the tables defined within a worksheet."""
  122. entry = [Table]
  123. class Record(gdata.data.GDEntry):
  124. """An Atom entry representing a single record in a table.
  125. Note that the order of items in each record is the same as the order of
  126. columns in the table definition, which may not match the order of
  127. columns in the GUI.
  128. """
  129. field = [Field]
  130. def value_for_index(self, column_index):
  131. for field in self.field:
  132. if field.index == column_index:
  133. return field.text
  134. raise FieldMissing('There is no field for %s' % column_index)
  135. ValueForIndex = value_for_index
  136. def value_for_name(self, name):
  137. for field in self.field:
  138. if field.name == name:
  139. return field.text
  140. raise FieldMissing('There is no field for %s' % name)
  141. ValueForName = value_for_name
  142. def get_record_id(self):
  143. if self.id.text:
  144. return self.id.text.split('/')[-1]
  145. return None
  146. class RecordsFeed(gdata.data.GDFeed):
  147. """An Atom feed containing the individuals records in a table."""
  148. entry = [Record]
  149. class ListRow(atom.core.XmlElement):
  150. """A gsx column value within a row.
  151. The local tag in the _qname is blank and must be set to the column
  152. name. For example, when adding to a ListEntry, do:
  153. col_value = ListRow(text='something')
  154. col_value._qname = col_value._qname % 'mycolumnname'
  155. """
  156. _qname = '{http://schemas.google.com/spreadsheets/2006/extended}%s'
  157. class ListEntry(gdata.data.GDEntry):
  158. """An Atom entry representing a worksheet row in the list feed.
  159. The values for a particular column can be get and set using
  160. x.get_value('columnheader') and x.set_value('columnheader', 'value').
  161. See also the explanation of column names in the ListFeed class.
  162. """
  163. def get_value(self, column_name):
  164. """Returns the displayed text for the desired column in this row.
  165. The formula or input which generated the displayed value is not accessible
  166. through the list feed, to see the user's input, use the cells feed.
  167. If a column is not present in this spreadsheet, or there is no value
  168. for a column in this row, this method will return None.
  169. """
  170. values = self.get_elements(column_name, GSX_NAMESPACE)
  171. if len(values) == 0:
  172. return None
  173. return values[0].text
  174. def set_value(self, column_name, value):
  175. """Changes the value of cell in this row under the desired column name.
  176. Warning: if the cell contained a formula, it will be wiped out by setting
  177. the value using the list feed since the list feed only works with
  178. displayed values.
  179. No client side checking is performed on the column_name, you need to
  180. ensure that the column_name is the local tag name in the gsx tag for the
  181. column. For example, the column_name will not contain special characters,
  182. spaces, uppercase letters, etc.
  183. """
  184. # Try to find the column in this row to change an existing value.
  185. values = self.get_elements(column_name, GSX_NAMESPACE)
  186. if len(values) > 0:
  187. values[0].text = value
  188. else:
  189. # There is no value in this row for the desired column, so add a new
  190. # gsx:column_name element.
  191. new_value = ListRow(text=value)
  192. new_value._qname = new_value._qname % (column_name,)
  193. self._other_elements.append(new_value)
  194. class ListsFeed(gdata.data.GDFeed):
  195. """An Atom feed in which each entry represents a row in a worksheet.
  196. The first row in the worksheet is used as the column names for the values
  197. in each row. If a header cell is empty, then a unique column ID is used
  198. for the gsx element name.
  199. Spaces in a column name are removed from the name of the corresponding
  200. gsx element.
  201. Caution: The columnNames are case-insensitive. For example, if you see
  202. a <gsx:e-mail> element in a feed, you can't know whether the column
  203. heading in the original worksheet was "e-mail" or "E-Mail".
  204. Note: If two or more columns have the same name, then subsequent columns
  205. of the same name have _n appended to the columnName. For example, if the
  206. first column name is "e-mail", followed by columns named "E-Mail" and
  207. "E-mail", then the columnNames will be gsx:e-mail, gsx:e-mail_2, and
  208. gsx:e-mail_3 respectively.
  209. """
  210. entry = [ListEntry]
  211. class CellEntry(gdata.data.BatchEntry):
  212. """An Atom entry representing a single cell in a worksheet."""
  213. cell = Cell
  214. class CellsFeed(gdata.data.BatchFeed):
  215. """An Atom feed contains one entry per cell in a worksheet.
  216. The cell feed supports batch operations, you can send multiple cell
  217. operations in one HTTP request.
  218. """
  219. entry = [CellEntry]
  220. def batch_set_cell(row, col, input):
  221. pass