#!/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