Sheet API

class pygsheets.sheet.SheetAPIWrapper(http, data_path, seconds_per_quota=100, retries=1, logger=<Logger pygsheets.sheet (WARNING)>)[source]
batch_update(spreadsheet_id, requests, **kwargs)[source]

Applies one or more updates to the spreadsheet.

Each request is validated before being applied. If any request is not valid then the entire request will fail and nothing will be applied.

Some requests have replies to give you some information about how they are applied. The replies will mirror the requests. For example, if you applied 4 updates and the 3rd one had a reply, then the response will have 2 empty replies, the actual reply, and another empty reply, in that order.

Due to the collaborative nature of spreadsheets, it is not guaranteed that the spreadsheet will reflect exactly your changes after this completes, however it is guaranteed that the updates in the request will be applied together atomically. Your changes may be altered with respect to collaborator changes. If there are no collaborators, the spreadsheet should reflect your changes.

Request body params Description
includeSpreadsheetInResponse
Determines if the update response should include
the spreadsheet resource. (default: False)
responseRanges[]
Limits the ranges included in the response
spreadsheet. Only applied if the first param is
True.
responseIncludeGridData
True if grid data should be returned. Meaningful
only if if includeSpreadsheetInResponse is ‘true’.
This parameter is ignored if a field mask was set
in the request.
Parameters:
  • spreadsheet_id – The spreadsheet to apply the updates to.
  • requests – A list of updates to apply to the spreadsheet. Requests will be applied in the order they are specified. If any request is not valid, no requests will be applied.
  • kwargs – Request body params & standard parameters (see reference for details).
Returns:

create(title, template=None, **kwargs)[source]

Create a spreadsheet.

Can be created with just a title. All other values will be set to default.

A template can be either a JSON representation of a Spreadsheet Resource as defined by the Google Sheets API or an instance of the Spreadsheet class. Missing fields will be set to default.

Parameters:
  • title – Title of the new spreadsheet.
  • template – Template used to create the new spreadsheet.
  • kwargs – Standard parameters (see reference for details).
Returns:

A Spreadsheet Resource.

get(spreadsheet_id, **kwargs)[source]

Returns a full spreadsheet with the entire data.

The data returned can be limited with parameters. See reference for details .

Parameters:
  • spreadsheet_id – The Id of the spreadsheet to return.
  • kwargs – Standard parameters (see reference for details).
Returns:

Return a SheetResource.

update_sheet_properties_request(spreadsheet_id, properties, fields)[source]

Updates the properties of the specified sheet.

Properties must be an instance of SheetProperties.

Parameters:
  • spreadsheet_id – The id of the spreadsheet to be updated.
  • properties – The properties to be updated.
  • fields – Specifies the fields which should be updated.
Returns:

SheetProperties

sheets_copy_to(source_spreadsheet_id, worksheet_id, destination_spreadsheet_id, **kwargs)[source]

Copies a worksheet from one spreadsheet to another.

Reference: request

Parameters:
  • source_spreadsheet_id – The ID of the spreadsheet containing the sheet to copy.
  • worksheet_id – The ID of the sheet to copy.
  • destination_spreadsheet_id – The ID of the spreadsheet to copy the sheet to.
  • kwargs – Standard parameters (see reference for details).
Returns:

SheetProperties

values_append(spreadsheet_id, values, major_dimension, range, **kwargs)[source]

Appends values to a spreadsheet.

The input range is used to search for existing data and find a “table” within that range. Values will be appended to the next row of the table, starting with the first column of the table. See the guide and sample code for specific details of how tables are detected and data is appended.

The caller must specify the spreadsheet ID, range, and a valueInputOption. The valueInputOption only controls how the input data will be added to the sheet (column-wise or row-wise), it does not influence what cell the data starts being written to.

Reference: request

Parameters:
  • spreadsheet_id – The ID of the spreadsheet to update.
  • values – The values to be appended in the body.
  • major_dimension – The major dimension of the values provided (e.g. row or column first?)
  • range – The A1 notation of a range to search for a logical table of data. Values will be appended after the last row of the table.
  • kwargs – Query & standard parameters (see reference for details).
values_batch_clear(spreadsheet_id, ranges)[source]

Clear values from sheet.

Clears one or more ranges of values from a spreadsheet. The caller must specify the spreadsheet ID and one or more ranges. Only values are cleared – all other properties of the cell (such as formatting, data validation, etc..) are kept.

Reference: request

Parameters:
  • spreadsheet_id – The ID of the spreadsheet to update.
  • ranges – A list of ranges to clear in A1 notation.
values_batch_update(spreadsheet_id, body, parse=True)[source]

Impliments batch update

Parameters:
  • spreadsheet_id – id of spreadsheet
  • body – body of request
  • parse
values_get(spreadsheet_id, value_range, major_dimension='ROWS', value_render_option=<ValueRenderOption.FORMATTED_VALUE: 'FORMATTED_VALUE'>, date_time_render_option=<DateTimeRenderOption.SERIAL_NUMBER: 'SERIAL_NUMBER'>)[source]

Returns a range of values from a spreadsheet. The caller must specify the spreadsheet ID and a range.

Reference: request

Parameters:
  • spreadsheet_id – The ID of the spreadsheet to retrieve data from.
  • value_range – The A1 notation of the values to retrieve.
  • major_dimension – The major dimension that results should use. For example, if the spreadsheet data is: A1=1,B1=2,A2=3,B2=4, then requesting range=A1:B2,majorDimension=ROWS will return [[1,2],[3,4]], whereas requesting range=A1:B2,majorDimension=COLUMNS will return [[1,3],[2,4]].
  • value_render_option – How values should be represented in the output. The default render option is ValueRenderOption.FORMATTED_VALUE.
  • date_time_render_option – How dates, times, and durations should be represented in the output. This is ignored if valueRenderOption is FORMATTED_VALUE. The default dateTime render option is [DateTimeRenderOption.SERIAL_NUMBER].
Returns:

ValueRange