Viewing file:  client.py (21.4 KB) -rw-r--r--
Select action/file-type:
 (+) |  (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
#!/usr/bin/env python
#
# Copyright (C) 2009 Google 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.
"""Contains a client to communicate with the Google Spreadsheets servers.
For documentation on the Spreadsheets API, see:
http://code.google.com/apis/spreadsheets/
"""
__author__ = 'j.s@google.com (Jeff Scudder)'
import gdata.client
import gdata.gauth
import gdata.spreadsheets.data
import atom.data
import atom.http_core
SPREADSHEETS_URL = ('http://spreadsheets.google.com/feeds/spreadsheets'
'/private/full')
WORKSHEETS_URL = ('http://spreadsheets.google.com/feeds/worksheets/'
'%s/private/full')
WORKSHEET_URL = ('http://spreadsheets.google.com/feeds/worksheets/'
'%s/private/full/%s')
TABLES_URL = 'http://spreadsheets.google.com/feeds/%s/tables'
RECORDS_URL = 'http://spreadsheets.google.com/feeds/%s/records/%s'
RECORD_URL = 'http://spreadsheets.google.com/feeds/%s/records/%s/%s'
class SpreadsheetsClient(gdata.client.GDClient):
api_version = '3'
auth_service = 'wise'
auth_scopes = gdata.gauth.AUTH_SCOPES['wise']
def get_spreadsheets(self, auth_token=None,
desired_class=gdata.spreadsheets.data.SpreadsheetsFeed,
**kwargs):
"""Obtains a feed with the spreadsheets belonging to the current user.
Args:
auth_token: An object which sets the Authorization HTTP header in its
modify_request method. Recommended classes include
gdata.gauth.ClientLoginToken and gdata.gauth.AuthSubToken
among others. Represents the current user. Defaults to None
and if None, this method will look for a value in the
auth_token member of SpreadsheetsClient.
desired_class: class descended from atom.core.XmlElement to which a
successful response should be converted. If there is no
converter function specified (converter=None) then the
desired_class will be used in calling the
atom.core.parse function. If neither
the desired_class nor the converter is specified, an
HTTP reponse object will be returned. Defaults to
gdata.spreadsheets.data.SpreadsheetsFeed.
"""
return self.get_feed(SPREADSHEETS_URL, auth_token=auth_token,
desired_class=desired_class, **kwargs)
GetSpreadsheets = get_spreadsheets
def get_worksheets(self, spreadsheet_key, auth_token=None,
desired_class=gdata.spreadsheets.data.WorksheetsFeed,
**kwargs):
"""Finds the worksheets within a given spreadsheet.
Args:
spreadsheet_key: str, The unique ID of this containing spreadsheet. This
can be the ID from the URL or as provided in a
Spreadsheet entry.
auth_token: An object which sets the Authorization HTTP header in its
modify_request method. Recommended classes include
gdata.gauth.ClientLoginToken and gdata.gauth.AuthSubToken
among others. Represents the current user. Defaults to None
and if None, this method will look for a value in the
auth_token member of SpreadsheetsClient.
desired_class: class descended from atom.core.XmlElement to which a
successful response should be converted. If there is no
converter function specified (converter=None) then the
desired_class will be used in calling the
atom.core.parse function. If neither
the desired_class nor the converter is specified, an
HTTP reponse object will be returned. Defaults to
gdata.spreadsheets.data.WorksheetsFeed.
"""
return self.get_feed(WORKSHEETS_URL % spreadsheet_key,
auth_token=auth_token, desired_class=desired_class,
**kwargs)
GetWorksheets = get_worksheets
def add_worksheet(self, spreadsheet_key, title, rows, cols,
auth_token=None, **kwargs):
"""Creates a new worksheet entry in the spreadsheet.
Args:
spreadsheet_key: str, The unique ID of this containing spreadsheet. This
can be the ID from the URL or as provided in a
Spreadsheet entry.
title: str, The title to be used in for the worksheet.
rows: str or int, The number of rows this worksheet should start with.
cols: str or int, The number of columns this worksheet should start with.
auth_token: An object which sets the Authorization HTTP header in its
modify_request method. Recommended classes include
gdata.gauth.ClientLoginToken and gdata.gauth.AuthSubToken
among others. Represents the current user. Defaults to None
and if None, this method will look for a value in the
auth_token member of SpreadsheetsClient.
"""
new_worksheet = gdata.spreadsheets.data.WorksheetEntry(
title=atom.data.Title(text=title),
row_count=gdata.spreadsheets.data.RowCount(text=str(rows)),
col_count=gdata.spreadsheets.data.ColCount(text=str(cols)))
return self.post(new_worksheet, WORKSHEETS_URL % spreadsheet_key,
auth_token=auth_token, **kwargs)
AddWorksheet = add_worksheet
def get_worksheet(self, spreadsheet_key, worksheet_id,
desired_class=gdata.spreadsheets.data.WorksheetEntry,
auth_token=None, **kwargs):
"""Retrieves a single worksheet.
Args:
spreadsheet_key: str, The unique ID of this containing spreadsheet. This
can be the ID from the URL or as provided in a
Spreadsheet entry.
worksheet_id: str, The unique ID for the worksheet withing the desired
spreadsheet.
auth_token: An object which sets the Authorization HTTP header in its
modify_request method. Recommended classes include
gdata.gauth.ClientLoginToken and gdata.gauth.AuthSubToken
among others. Represents the current user. Defaults to None
and if None, this method will look for a value in the
auth_token member of SpreadsheetsClient.
desired_class: class descended from atom.core.XmlElement to which a
successful response should be converted. If there is no
converter function specified (converter=None) then the
desired_class will be used in calling the
atom.core.parse function. If neither
the desired_class nor the converter is specified, an
HTTP reponse object will be returned. Defaults to
gdata.spreadsheets.data.WorksheetEntry.
"""
return self.get_entry(WORKSHEET_URL % (spreadsheet_key, worksheet_id,),
auth_token=auth_token, desired_class=desired_class,
**kwargs)
GetWorksheet = get_worksheet
def add_table(self, spreadsheet_key, title, summary, worksheet_name,
header_row, num_rows, start_row, insertion_mode,
column_headers, auth_token=None, **kwargs):
"""Creates a new table within the worksheet.
Args:
spreadsheet_key: str, The unique ID of this containing spreadsheet. This
can be the ID from the URL or as provided in a
Spreadsheet entry.
title: str, The title for the new table within a worksheet.
summary: str, A description of the table.
worksheet_name: str The name of the worksheet in which this table
should live.
header_row: int or str, The number of the row in the worksheet which
will contain the column names for the data in this table.
num_rows: int or str, The number of adjacent rows in this table.
start_row: int or str, The number of the row at which the data begins.
insertion_mode: str
column_headers: dict of strings, maps the column letters (A, B, C) to
the desired name which will be viewable in the
worksheet.
auth_token: An object which sets the Authorization HTTP header in its
modify_request method. Recommended classes include
gdata.gauth.ClientLoginToken and gdata.gauth.AuthSubToken
among others. Represents the current user. Defaults to None
and if None, this method will look for a value in the
auth_token member of SpreadsheetsClient.
"""
data = gdata.spreadsheets.data.Data(
insertion_mode=insertion_mode, num_rows=str(num_rows),
start_row=str(start_row))
for index, name in column_headers.iteritems():
data.column.append(gdata.spreadsheets.data.Column(
index=index, name=name))
new_table = gdata.spreadsheets.data.Table(
title=atom.data.Title(text=title), summary=atom.data.Summary(summary),
worksheet=gdata.spreadsheets.data.Worksheet(name=worksheet_name),
header=gdata.spreadsheets.data.Header(row=str(header_row)), data=data)
return self.post(new_table, TABLES_URL % spreadsheet_key,
auth_token=auth_token, **kwargs)
AddTable = add_table
def get_tables(self, spreadsheet_key,
desired_class=gdata.spreadsheets.data.TablesFeed,
auth_token=None, **kwargs):
"""Retrieves a feed listing the tables in this spreadsheet.
Args:
spreadsheet_key: str, The unique ID of this containing spreadsheet. This
can be the ID from the URL or as provided in a
Spreadsheet entry.
desired_class: class descended from atom.core.XmlElement to which a
successful response should be converted. If there is no
converter function specified (converter=None) then the
desired_class will be used in calling the
atom.core.parse function. If neither
the desired_class nor the converter is specified, an
HTTP reponse object will be returned. Defaults to
gdata.spreadsheets.data.TablesFeed.
auth_token: An object which sets the Authorization HTTP header in its
modify_request method. Recommended classes include
gdata.gauth.ClientLoginToken and gdata.gauth.AuthSubToken
among others. Represents the current user. Defaults to None
and if None, this method will look for a value in the
auth_token member of SpreadsheetsClient.
"""
return self.get_feed(TABLES_URL % spreadsheet_key,
desired_class=desired_class, auth_token=auth_token,
**kwargs)
GetTables = get_tables
def add_record(self, spreadsheet_key, table_id, fields,
title=None, auth_token=None, **kwargs):
"""Adds a new row to the table.
Args:
spreadsheet_key: str, The unique ID of this containing spreadsheet. This
can be the ID from the URL or as provided in a
Spreadsheet entry.
table_id: str, The ID of the table within the worksheet which should
receive this new record. The table ID can be found using the
get_table_id method of a gdata.spreadsheets.data.Table.
fields: dict of strings mapping column names to values.
title: str, optional The title for this row.
auth_token: An object which sets the Authorization HTTP header in its
modify_request method. Recommended classes include
gdata.gauth.ClientLoginToken and gdata.gauth.AuthSubToken
among others. Represents the current user. Defaults to None
and if None, this method will look for a value in the
auth_token member of SpreadsheetsClient.
"""
new_record = gdata.spreadsheets.data.Record()
if title is not None:
new_record.title = atom.data.Title(text=title)
for name, value in fields.iteritems():
new_record.field.append(gdata.spreadsheets.data.Field(
name=name, text=value))
return self.post(new_record, RECORDS_URL % (spreadsheet_key, table_id),
auth_token=auth_token, **kwargs)
AddRecord = add_record
def get_records(self, spreadsheet_key, table_id,
desired_class=gdata.spreadsheets.data.RecordsFeed,
auth_token=None, **kwargs):
"""Retrieves the records in a table.
Args:
spreadsheet_key: str, The unique ID of this containing spreadsheet. This
can be the ID from the URL or as provided in a
Spreadsheet entry.
table_id: str, The ID of the table within the worksheet whose records
we would like to fetch. The table ID can be found using the
get_table_id method of a gdata.spreadsheets.data.Table.
desired_class: class descended from atom.core.XmlElement to which a
successful response should be converted. If there is no
converter function specified (converter=None) then the
desired_class will be used in calling the
atom.core.parse function. If neither
the desired_class nor the converter is specified, an
HTTP reponse object will be returned. Defaults to
gdata.spreadsheets.data.RecordsFeed.
auth_token: An object which sets the Authorization HTTP header in its
modify_request method. Recommended classes include
gdata.gauth.ClientLoginToken and gdata.gauth.AuthSubToken
among others. Represents the current user. Defaults to None
and if None, this method will look for a value in the
auth_token member of SpreadsheetsClient.
"""
return self.get_feed(RECORDS_URL % (spreadsheet_key, table_id),
desired_class=desired_class, auth_token=auth_token,
**kwargs)
GetRecords = get_records
def get_record(self, spreadsheet_key, table_id, record_id,
desired_class=gdata.spreadsheets.data.Record,
auth_token=None, **kwargs):
"""Retrieves a single record from the table.
Args:
spreadsheet_key: str, The unique ID of this containing spreadsheet. This
can be the ID from the URL or as provided in a
Spreadsheet entry.
table_id: str, The ID of the table within the worksheet whose records
we would like to fetch. The table ID can be found using the
get_table_id method of a gdata.spreadsheets.data.Table.
record_id: str, The ID of the record within this table which we want to
fetch. You can find the record ID using get_record_id() on
an instance of the gdata.spreadsheets.data.Record class.
desired_class: class descended from atom.core.XmlElement to which a
successful response should be converted. If there is no
converter function specified (converter=None) then the
desired_class will be used in calling the
atom.core.parse function. If neither
the desired_class nor the converter is specified, an
HTTP reponse object will be returned. Defaults to
gdata.spreadsheets.data.RecordsFeed.
auth_token: An object which sets the Authorization HTTP header in its
modify_request method. Recommended classes include
gdata.gauth.ClientLoginToken and gdata.gauth.AuthSubToken
among others. Represents the current user. Defaults to None
and if None, this method will look for a value in the
auth_token member of SpreadsheetsClient."""
return self.get_entry(RECORD_URL % (spreadsheet_key, table_id, record_id),
desired_class=desired_class, auth_token=auth_token,
**kwargs)
GetRecord = get_record
class SpreadsheetQuery(gdata.client.Query):
def __init__(self, title=None, title_exact=None, **kwargs):
"""Adds Spreadsheets feed query parameters to a request.
Args:
title: str Specifies the search terms for the title of a document.
This parameter used without title-exact will only submit partial
queries, not exact queries.
title_exact: str Specifies whether the title query should be taken as an
exact string. Meaningless without title. Possible values are
'true' and 'false'.
"""
gdata.client.Query.__init__(self, **kwargs)
self.title = title
self.title_exact = title_exact
def modify_request(self, http_request):
gdata.client._add_query_param('title', self.title, http_request)
gdata.client._add_query_param('title-exact', self.title_exact,
http_request)
gdata.client.Query.modify_request(self, http_request)
ModifyRequest = modify_request
class WorksheetQuery(SpreadsheetQuery):
pass
class ListQuery(gdata.client.Query):
def __init__(self, order_by=None, reverse=None, sq=None, **kwargs):
"""Adds List-feed specific query parameters to a request.
Args:
order_by: str Specifies what column to use in ordering the entries in
the feed. By position (the default): 'position' returns
rows in the order in which they appear in the GUI. Row 1, then
row 2, then row 3, and so on. By column:
'column:columnName' sorts rows in ascending order based on the
values in the column with the given columnName, where
columnName is the value in the header row for that column.
reverse: str Specifies whether to sort in descending or ascending order.
Reverses default sort order: 'true' results in a descending
sort; 'false' (the default) results in an ascending sort.
sq: str Structured query on the full text in the worksheet.
[columnName][binaryOperator][value]
Supported binaryOperators are:
- (), for overriding order of operations
- = or ==, for strict equality
- <> or !=, for strict inequality
- and or &&, for boolean and
- or or ||, for boolean or
"""
gdata.client.Query.__init__(self, **kwargs)
self.order_by = order_by
self.reverse = reverse
self.sq = sq
def modify_request(self, http_request):
gdata.client._add_query_param('orderby', self.order_by, http_request)
gdata.client._add_query_param('reverse', self.reverse, http_request)
gdata.client._add_query_param('sq', self.sq, http_request)
gdata.client.Query.modify_request(self, http_request)
ModifyRequest = modify_request
class TableQuery(ListQuery):
pass
class CellQuery(gdata.client.Query):
def __init__(self, min_row=None, max_row=None, min_col=None, max_col=None,
range=None, return_empty=None, **kwargs):
"""Adds Cells-feed specific query parameters to a request.
Args:
min_row: str or int Positional number of minimum row returned in query.
max_row: str or int Positional number of maximum row returned in query.
min_col: str or int Positional number of minimum column returned in query.
max_col: str or int Positional number of maximum column returned in query.
range: str A single cell or a range of cells. Use standard spreadsheet
cell-range notations, using a colon to separate start and end of
range. Examples:
- 'A1' and 'R1C1' both specify only cell A1.
- 'D1:F3' and 'R1C4:R3C6' both specify the rectangle of cells with
corners at D1 and F3.
return_empty: str If 'true' then empty cells will be returned in the feed.
If omitted, the default is 'false'.
"""
gdata.client.Query.__init__(self, **kwargs)
self.min_row = min_row
self.max_row = max_row
self.min_col = min_col
self.max_col = max_col
self.range = range
self.return_empty = return_empty
def modify_request(self, http_request):
gdata.client._add_query_param('min-row', self.min_row, http_request)
gdata.client._add_query_param('max-row', self.max_row, http_request)
gdata.client._add_query_param('min-col', self.min_col, http_request)
gdata.client._add_query_param('max-col', self.max_col, http_request)
gdata.client._add_query_param('range', self.range, http_request)
gdata.client._add_query_param('return-empty', self.return_empty,
http_request)
gdata.client.Query.modify_request(self, http_request)
ModifyRequest = modify_request
|