Worksheet¶
ValueRange¶
-
class
gspread.worksheet.
ValueRange
¶ The class holds the returned values.
This class inherit the
list
object type. It behaves exactly like a list.The values are stored in a matrix.
The property
gspread.worksheet.ValueRange.major_dimension()
holds the major dimension of the first list level.The inner lists will contain the actual values.
Examples:
>>> worksheet.get("A1:B2") [ [ "A1 value", "B1 values", ], [ "A2 value", "B2 value", ] ] >>> worksheet.get("A1:B2").major_dimension ROW
Note
This class should never be instantiated manually. It will be instantiated using the response from the sheet API.
-
first
(default=None)¶ Returns the value of a first cell in a range.
If the range is empty, return the default value.
-
major_dimension
¶ The major dimension of this range
Can be one of:
ROW
: the first list level holds rows of valuesCOLUMNS
: the first list level holds columns of values
-
range
¶ The range of the values
-
Worksheet¶
-
class
gspread.worksheet.
Worksheet
(spreadsheet, properties)¶ The class that represents a single sheet in a spreadsheet (aka “worksheet”).
-
acell
(label, value_render_option='FORMATTED_VALUE')¶ Returns an instance of a
gspread.cell.Cell
.Parameters: - label (str) – Cell label in A1 notation Letter case is ignored.
- value_render_option (( ValueRenderOption.formatted | ValueRenderOption.unformatted | ValueRenderOption.formula )) – (optional) Determines how values should be rendered in the the output. See ValueRenderOption in the Sheets API.
Example:
>>> worksheet.acell('A1') <Cell R1C1 "I'm cell A1">
-
add_dimension_group_columns
(start, end)¶ Group columns in order to hide them in the UI.
Note
API behavior with nested groups and non matching
[start:end[
range can be found here Add Dimension Group RequestParameters:
-
add_dimension_group_rows
(start, end)¶ Group rows in order to hide them in the UI.
Note
API behavior with nested groups and non matching
[start:end[
range can be found here Add Dimension Group RequestParameters:
-
add_protected_range
(name, editor_users_emails, editor_groups_emails=[], description=None, warning_only=False, requesting_user_can_edit=False)¶ Add protected range to the sheet. Only the editors can edit the protected range.
Google API will automatically add the owner of this SpreadSheet. The list
editor_users_emails
must at least contain the e-mail address used to open that SpreadSheet.editor_users_emails
must only contain e-mail addresses who already have a write access to the spreadsheet.Parameters: name (str) – A string with range value in A1 notation, e.g. ‘A1:A5’. Alternatively, you may specify numeric boundaries. All values index from 1 (one):
Parameters: For both A1 and numeric notation:
Parameters: - editor_users_emails (list) – The email addresses of users with edit access to the protected range. This must include your e-mail address at least.
- editor_groups_emails (list) – (optional) The email addresses of groups with edit access to the protected range.
- description (str) – (optional) Description for the protected ranges.
- warning_only (boolean) – (optional) When true this protected range
will show a warning when editing. Defaults to
False
. - requesting_user_can_edit (boolean) – (optional) True if the user
who requested this protected range can edit the protected cells.
Defaults to
False
.
-
append_row
(values, value_input_option='RAW', insert_data_option=None, table_range=None, include_values_in_response=False)¶ Adds a row to the worksheet and populates it with values.
Widens the worksheet if there are more values than columns.
Parameters: - values (list) – List of values for the new row.
- value_input_option (str) – (optional) Determines how the input data should be interpreted. See ValueInputOption in the Sheets API reference.
- insert_data_option (str) – (optional) Determines how the input data should be inserted. See InsertDataOption in the Sheets API reference.
- table_range (str) – (optional) The A1 notation of a range to search
for a logical table of data. Values are appended after the last row
of the table. Examples:
A1
orB2:D4
- include_values_in_response (bool) – (optional) Determines if the update response should include the values of the cells that were appended. By default, responses do not include the updated values.
-
append_rows
(values, value_input_option='RAW', insert_data_option=None, table_range=None, include_values_in_response=False)¶ Adds multiple rows to the worksheet and populates them with values.
Widens the worksheet if there are more values than columns.
Parameters: - values (list) – List of rows each row is List of values for the new row.
- value_input_option (str) – (optional) Determines how input data
should be interpreted. Possible values are
ValueInputOption.raw
orValueInputOption.user_entered
. See ValueInputOption in the Sheets API. - insert_data_option (str) – (optional) Determines how the input data should be inserted. See InsertDataOption in the Sheets API reference.
- table_range (str) – (optional) The A1 notation of a range to search
for a logical table of data. Values are appended after the last row
of the table. Examples:
A1
orB2:D4
- include_values_in_response (bool) – (optional) Determines if the update response should include the values of the cells that were appended. By default, responses do not include the updated values.
-
batch_clear
(ranges)¶ Clears multiple ranges of cells with 1 API call.
Examples:
worksheet.batch_clear(['A1:B1','my_range']) # Note: named ranges are defined in the scope of # a spreadsheet, so even if `my_range` does not belong to # this sheet it is still updated
New in version 3.8.0.
-
batch_format
(formats)¶ Formats cells in batch.
Parameters: formats (list) – List of ranges to format and they actual format to apply for each range.
The list is composed of dict object with the following keys/values:
- range : A1 range notation
- format : a valid dict object with the format to apply for that range see CellFormat in the Sheets API for available fields.
Examples:
# Format the range ``A1:C1`` with bold text # and format the range ``A2:C2`` a font size of 16 formats = [ { "range": "A1:C1", "format": { "textFormat": { "bold": True, }, }, }, { "range": "A2:C2", "format": { "textFormat": { "fontSize": 16, }, }, }, ] worksheet.batch_update(formats)
New in version 5.4.
-
batch_get
(ranges, **kwargs)¶ Returns one or more ranges of values from the sheet.
Parameters: - ranges (list) – List of cell ranges in the A1 notation or named ranges.
- major_dimension (str) – (optional) The major dimension that results
should use. Either
ROWS
orCOLUMNS
. - value_render_option (str) – (optional) How values should be
represented in the output. The default render option
is
ValueRenderOption.formatted
. - date_time_render_option (str) – (optional) How dates, times, and
durations should be represented in the output. This is ignored if
value_render_option is
ValueRenderOption.formatted
. The default dateTime render option isSERIAL_NUMBER
.
New in version 3.3.
Examples:
# Read values from 'A1:B2' range and 'F12' cell worksheet.batch_get(['A1:B2', 'F12'])
-
batch_update
(data, **kwargs)¶ Sets values in one or more cell ranges of the sheet at once.
Parameters: - data (list) – List of dictionaries in the form of {‘range’: ‘…’, ‘values’: [[.., ..], …]} where range is a target range to update in A1 notation or a named range, and values is a list of lists containing new values.
- value_input_option (str) –
(optional) How the input data should be interpreted. Possible values are:
ValueInputOption.raw
The values the user has entered will not be parsed and will be stored as-is.
ValueInputOption.user_entered
The values will be parsed as if the user typed them into the UI. Numbers will stay as numbers, but strings may be converted to numbers, dates, etc. following the same rules that are applied when entering text into a cell via the Google Sheets UI.
Examples:
worksheet.batch_update([{ 'range': 'A1:B1', 'values': [['42', '43']], }, { 'range': 'my_range', 'values': [['44', '45']], }]) # Note: named ranges are defined in the scope of # a spreadsheet, so even if `my_range` does not belong to # this sheet it is still updated
New in version 3.3.
-
cell
(row, col, value_render_option='FORMATTED_VALUE')¶ Returns an instance of a
gspread.cell.Cell
located at row and col column.Parameters: - row (int) – Row number.
- col (int) – Column number.
- value_render_option (( ValueRenderOption.formatted | ValueRenderOption.unformatted | ValueRenderOption.formula )) – (optional) Determines how values should be rendered in the the output. See ValueRenderOption in the Sheets API.
Example:
>>> worksheet.cell(1, 1) <Cell R1C1 "I'm cell A1">
Return type: gspread.cell.Cell
-
clear
()¶ Clears all cells in the worksheet.
-
clear_basic_filter
()¶ Remove the basic filter from a worksheet.
New in version 3.4.
-
clear_note
(cell)¶ Clear a note. The note is attached to a certain cell.
Parameters: cell (str) – A string with cell coordinates in A1 notation, e.g. ‘D7’. Alternatively, you may specify numeric boundaries. All values index from 1 (one):
Parameters: New in version 3.7.
-
col_count
¶ Number of columns.
Warning
This value is fetched when opening the worksheet. This is not dynamically updated when adding columns, yet.
-
col_values
(col, value_render_option='FORMATTED_VALUE')¶ Returns a list of all values in column col.
Empty cells in this list will be rendered as
None
.Parameters: - col (int) – Column number (one-based).
- value_render_option (str) – (optional) Determines how values should be rendered in the the output. See ValueRenderOption in the Sheets API.
-
columns_auto_resize
(start_column_index, end_column_index)¶ Updates the size of rows or columns in the worksheet.
Index start from 0
Parameters: - start_column_index – The index (inclusive) to begin resizing
- end_column_index – The index (exclusive) to finish resizing
New in version 3.4.
Changed in version 5.3.3.
-
copy_to
(spreadsheet_id)¶ Copies this sheet to another spreadsheet.
Parameters: spreadsheet_id (str) – The ID of the spreadsheet to copy the sheet to. Returns: a dict with the response containing information about the newly created sheet. Return type: dict
-
define_named_range
(name, range_name)¶ Parameters: name (str) – A string with range value in A1 notation, e.g. ‘A1:A5’. Alternatively, you may specify numeric boundaries. All values index from 1 (one):
Parameters: Returns: the response body from the request
Return type:
-
delete_columns
(start_index, end_index=None)¶ Deletes multiple columns from the worksheet at the specified index.
Parameters:
-
delete_dimension
(dimension, start_index, end_index=None)¶ Deletes multi rows from the worksheet at the specified index.
Parameters:
-
delete_dimension_group_columns
(start, end)¶ Delete a grouped columns
Note
API behavior with nested groups and non matching
[start:end[
range can be found here Delete Dimension Group RequestParameters:
-
delete_dimension_group_rows
(start, end)¶ Delete a grouped rows
Note
API behavior with nested groups and non matching
[start:end[
range can be found here Delete Dimension Group RequestParameters:
-
delete_named_range
(named_range_id)¶ Parameters: named_range_id (str) – The ID of the named range to delete. Can be obtained with Spreadsheet.list_named_ranges() Returns: the response body from the request Return type: dict
-
delete_protected_range
(id)¶ Delete protected range identified by the ID
id
.To retrieve the ID of a protected range use the following method to list them all:
list_protected_ranges()
-
delete_row
(index)¶ Deprecated since version 5.0.
Deletes the row from the worksheet at the specified index.
Parameters: index (int) – Index of a row for deletion.
-
delete_rows
(start_index, end_index=None)¶ Deletes multiple rows from the worksheet at the specified index.
Parameters: Example:
# Delete rows 5 to 10 (inclusive) worksheet.delete_rows(5, 10) # Delete only the second row worksheet.delete_rows(2)
-
duplicate
(insert_sheet_index=None, new_sheet_id=None, new_sheet_name=None)¶ Duplicate the sheet.
Parameters: - insert_sheet_index (int) – (optional) The zero-based index where the new sheet should be inserted. The index of all sheets after this are incremented.
- new_sheet_id (int) – (optional) The ID of the new sheet. If not set, an ID is chosen. If set, the ID must not conflict with any existing sheet ID. If set, it must be non-negative.
- new_sheet_name (str) – (optional) The name of the new sheet. If empty, a new name is chosen for you.
Returns: a newly created
gspread.worksheet.Worksheet
.New in version 3.1.
-
export
(format)¶ Deprecated since version 2.0.
This feature is not supported in Sheets API v4.
-
find
(query, in_row=None, in_column=None, case_sensitive=True)¶ Finds the first cell matching the query.
Parameters: - query (str,
re.RegexObject
) – A literal string to match or compiled regular expression. - in_row (int) – (optional) One-based row number to scope the search.
- in_column (int) – (optional) One-based column number to scope the search.
- case_sensitive (bool) – (optional) comparison is case sensitive if set to True, case insensitive otherwise. Default is True. Does not apply to regular expressions.
Returns: the first matching cell or None otherwise
Return type: - query (str,
-
findall
(query, in_row=None, in_column=None, case_sensitive=True)¶ Finds all cells matching the query.
Returns a list of
gspread.cell.Cell
.Parameters: - query (str,
re.RegexObject
) – A literal string to match or compiled regular expression. - in_row (int) – (optional) One-based row number to scope the search.
- in_column (int) – (optional) One-based column number to scope the search.
- case_sensitive (bool) – (optional) comparison is case sensitive if set to True, case insensitive otherwise. Default is True. Does not apply to regular expressions.
Returns: the list of all matching cells or empty list otherwise
Return type: - query (str,
-
format
(ranges, format)¶ Format a list of ranges with the given format.
Parameters: - ranges (str|list) – Target ranges in the A1 notation.
- cell_format (dict) – Dictionary containing the fields to update. See CellFormat in the Sheets API for available fields.
Examples:
# Set 'A4' cell's text format to bold worksheet.format("A4", {"textFormat": {"bold": True}}) # Set 'A1:D4' and 'A10:D10' cells's text format to bold worksheet.format(["A1:D4", "A10:D10"], {"textFormat": {"bold": True}}) # Color the background of 'A2:B2' cell range in black, # change horizontal alignment, text color and font size worksheet.format("A2:B2", { "backgroundColor": { "red": 0.0, "green": 0.0, "blue": 0.0 }, "horizontalAlignment": "CENTER", "textFormat": { "foregroundColor": { "red": 1.0, "green": 1.0, "blue": 1.0 }, "fontSize": 12, "bold": True } })
New in version 3.3.
-
freeze
(rows=None, cols=None)¶ Freeze rows and/or columns on the worksheet.
Parameters: - rows – Number of rows to freeze.
- cols – Number of columns to freeze.
-
frozen_col_count
¶ Number of frozen columns.
-
frozen_row_count
¶ Number of frozen rows.
-
get
(range_name=None, **kwargs)¶ Reads values of a single range or a cell of a sheet.
Parameters: - range_name (str) – (optional) Cell range in the A1 notation or a named range.
- major_dimension (str) – (optional) The major dimension that results
should use. Either
ROWS
orCOLUMNS
. - value_render_option (str) – (optional) How values should be
represented in the output. The default render option is
ValueRenderOption.formatted
. - date_time_render_option (str) – (optional) How dates, times, and
durations should be represented in the output. This is ignored if
value_render_option
isValueRenderOption.formatted
. The defaultdate_time_render_option
isSERIAL_NUMBER
.
Return type: Examples:
# Return all values from the sheet worksheet.get() # Return value of 'A1' cell worksheet.get('A1') # Return values of 'A1:B2' range worksheet.get('A1:B2') # Return values of 'my_range' named range worksheet.get('my_range')
New in version 3.3.
-
get_all_cells
()¶ Returns a list of all Cell of the current sheet.
-
get_all_records
(empty2zero=False, head=1, default_blank='', allow_underscores_in_numeric_literals=False, numericise_ignore=None, value_render_option=None, expected_headers=None)¶ Returns a list of dictionaries, all of them having the contents of the spreadsheet with the head row as keys and each of these dictionaries holding the contents of subsequent rows of cells as values.
Cell values are numericised (strings that can be read as ints or floats are converted), unless specified in numericise_ignore
Parameters: - empty2zero (bool) – (optional) Determines whether empty cells are converted to zeros.
- head (int) – (optional) Determines which row to use as keys, starting from 1 following the numeration of the spreadsheet.
- default_blank (str) – (optional) Determines which value to use for blank cells, defaults to empty string.
- allow_underscores_in_numeric_literals (bool) – (optional) Allow underscores in numeric literals, as introduced in PEP 515
- numericise_ignore (list) – (optional) List of ints of indices of the row (starting at 1) to ignore numericising, special use of [‘all’] to ignore numericising on all columns.
- value_render_option (str) – (optional) Determines how values should be rendered in the the output. See ValueRenderOption in the Sheets API.
- expected_headers (list) –
(optional) List of expected headers, they must be unique.
Note
returned dictionaries will contain all headers even if not included in this list
-
get_all_values
(**kwargs)¶ Returns a list of lists containing all cells’ values as strings.
This is an alias to
get_values()
Note
This is a legacy method. Use
get_values()
instead.Examples:
# Return all values from the sheet worksheet.get_all_values() # Is equivalent to worksheet.get_values()
-
get_note
(cell)¶ Get the content of the note located at cell, or the empty string if the cell does not have a note.
Parameters: cell (str) – A string with cell coordinates in A1 notation, e.g. ‘D7’.
-
get_values
(range_name=None, **kwargs)¶ Returns a list of lists containing all values from specified range.
By default values are returned as strings. See
value_render_option
to change the default format.Parameters: - range_name (str) – (optional) Cell range in the A1 notation or a named range. If not specified the method returns values from all non empty cells.
- major_dimension (str) – (optional) The major dimension of the values. Dimension.rows (“ROWS”) or Dimension.cols (“COLUMNS”). Defaults to Dimension.rows
- value_render_option (str) –
(optional) Determines how values should be rendered in the the output. See ValueRenderOption in the Sheets API.
Possible values are:
ValueRenderOption.formatted
- (default) Values will be calculated and formatted according to the cell’s formatting. Formatting is based on the spreadsheet’s locale, not the requesting user’s locale.
ValueRenderOption.unformatted
- Values will be calculated, but not formatted in the reply. For example, if A1 is 1.23 and A2 is =A1 and formatted as currency, then A2 would return the number 1.23.
ValueRenderOption.formula
- Values will not be calculated. The reply will include the formulas. For example, if A1 is 1.23 and A2 is =A1 and formatted as currency, then A2 would return “=A1”.
Parameters: date_time_render_option (str) – (optional) How dates, times, and durations should be represented in the output. This is ignored if value_render_option
isValueRenderOption.formatted
. The defaultdate_time_render_option
isSERIAL_NUMBER
.Note
Empty trailing rows and columns will not be included.
Examples:
# Return all values from the sheet worksheet.get_values() # Return all values from columns "A" and "B" worksheet.get_values('A:B') # Return values from range "A2:C10" worksheet.get_values('A2:C10') # Return values from named range "my_range" worksheet.get_values('my_range') # Return unformatted values (e.g. numbers as numbers) worksheet.get_values('A2:B4', value_render_option=ValueRenderOption.unformatted) # Return cell values without calculating formulas worksheet.get_values('A2:B4', value_render_option=ValueRenderOption.formula)
-
hide
()¶ Hides the current worksheet from the UI.
-
hide_columns
(start, end)¶ Explicitly hide the given column index range.
Index start from 0.
Parameters:
-
hide_rows
(start, end)¶ Explicitly hide the given row index range.
Index start from 0.
Parameters:
-
id
¶ Worksheet ID.
-
index
¶ Worksheet index.
-
insert_cols
(values, col=1, value_input_option='RAW')¶ Adds multiple new cols to the worksheet at specified index and populates them with values.
Parameters: - values (list) – List of col lists. a list of lists, with the lists each containing one col’s values. Increases the number of rows if there are more values than columns.
- col (int) – Start col to update (one-based). Defaults to 1 (one).
- value_input_option (str) – (optional) Determines how input data
should be interpreted. Possible values are
ValueInputOption.raw
orValueInputOption.user_entered
. See ValueInputOption in the Sheets API.
-
insert_note
(cell, content)¶ Insert a note. The note is attached to a certain cell.
Parameters: Alternatively, you may specify numeric boundaries. All values index from 1 (one):
Parameters: New in version 3.7.
-
insert_row
(values, index=1, value_input_option='RAW')¶ Adds a row to the worksheet at the specified index and populates it with values.
Widens the worksheet if there are more values than columns.
Parameters: - values (list) – List of values for the new row.
- index (int) – (optional) Offset for the newly inserted row.
- value_input_option (str) – (optional) Determines how input data
should be interpreted. Possible values are
ValueInputOption.raw
orValueInputOption.user_entered
. See ValueInputOption in the Sheets API.
-
insert_rows
(values, row=1, value_input_option='RAW')¶ Adds multiple rows to the worksheet at the specified index and populates them with values.
Parameters: - values (list) – List of row lists. a list of lists, with the lists each containing one row’s values. Widens the worksheet if there are more values than columns.
- row (int) – Start row to update (one-based). Defaults to 1 (one).
- value_input_option (str) – (optional) Determines how input data
should be interpreted. Possible values are
ValueInputOption.raw
orValueInputOption.user_entered
. See ValueInputOption in the Sheets API.
-
list_dimension_group_columns
()¶ List all the grouped columns in this worksheet
Returns: list of the groupped columns Return type: list
-
list_dimension_group_rows
()¶ List all the grouped rows in this worksheet
Returns: list of the grouped rows Return type: list
-
merge_cells
(name, merge_type='MERGE_ALL')¶ Merge cells. There are 3 merge types:
MERGE_ALL
,MERGE_COLUMNS
, andMERGE_ROWS
.Parameters: Alternatively, you may specify numeric boundaries. All values index from 1 (one):
Parameters: Returns: the response body from the request
Return type:
-
range
(name='')¶ Returns a list of
gspread.cell.Cell
objects from a specified range.Parameters: name (str) – A string with range value in A1 notation (e.g. ‘A1:A5’) or the named range to fetch. Alternatively, you may specify numeric boundaries. All values index from 1 (one):
Parameters: Return type: Example:
>>> # Using A1 notation >>> worksheet.range('A1:B7') [<Cell R1C1 "42">, ...] >>> # Same with numeric boundaries >>> worksheet.range(1, 1, 7, 2) [<Cell R1C1 "42">, ...] >>> # Named ranges work as well >>> worksheet.range('NamedRange') [<Cell R1C1 "42">, ...] >>> # All values in a single API call >>> worksheet.range() [<Cell R1C1 'Hi mom'>, ...]
-
resize
(rows=None, cols=None)¶ Resizes the worksheet. Specify one of
rows
orcols
.Parameters:
-
row_count
¶ Number of rows.
-
row_values
(row, **kwargs)¶ Returns a list of all values in a row.
Empty cells in this list will be rendered as
None
.Parameters: - row (int) – Row number (one-based).
- value_render_option (str) – (optional) Determines how values should be rendered in the the output. See ValueRenderOption in the Sheets API.
-
rows_auto_resize
(start_row_index, end_row_index)¶ Updates the size of rows or columns in the worksheet.
Index start from 0
Parameters: - start_row_index – The index (inclusive) to begin resizing
- end_row_index – The index (exclusive) to finish resizing
New in version 5.3.3.
-
set_basic_filter
(name=None)¶ Add a basic filter to the worksheet. If a range or bundaries are passed, the filter will be limited to the given range.
Parameters: name (str) – A string with range value in A1 notation, e.g. A1:A5
.Alternatively, you may specify numeric boundaries. All values index from 1 (one):
Parameters: New in version 3.4.
-
show
()¶ Show the current worksheet in the UI.
-
sort
(*specs, **kwargs)¶ Sorts worksheet using given sort orders.
Parameters: Example:
# Sort sheet A -> Z by column 'B' wks.sort((2, 'asc')) # Sort range A2:G8 basing on column 'G' A -> Z # and column 'B' Z -> A wks.sort((7, 'asc'), (2, 'des'), range='A2:G8')
New in version 3.4.
-
title
¶ Worksheet title.
-
unhide_columns
(start, end)¶ Explicitly unhide the given column index range.
Index start from 0.
Parameters:
-
unhide_rows
(start, end)¶ Explicitly unhide the given row index range.
Index start from 0.
Parameters:
-
unmerge_cells
(name)¶ Unmerge cells.
Unmerge previously merged cells.
Parameters: name (str) – Range name in A1 notation, e.g. ‘A1:A5’. Alternatively, you may specify numeric boundaries. All values index from 1 (one):
Parameters: Returns: the response body from the request
Return type:
-
update
(range_name, values=None, **kwargs)¶ Sets values in a cell range of the sheet.
Parameters: - range_name (str) – The A1 notation of the values to update.
- values (list) – The data to be written.
- raw (bool) – The values will not be parsed by Sheets API and will
be stored as-is. For example, formulas will be rendered as plain
strings. Defaults to
True
. This is a shortcut for thevalue_input_option
parameter. - major_dimension (str) – (optional) The major dimension of the
values. Either
ROWS
orCOLUMNS
. - value_input_option (str) –
(optional) How the input data should be interpreted. Possible values are:
ValueInputOption.raw
- The values the user has entered will not be parsed and will be stored as-is.
ValueInputOption.user_entered
- The values will be parsed as if the user typed them into the UI. Numbers will stay as numbers, but strings may be converted to numbers, dates, etc. following the same rules that are applied when entering text into a cell via the Google Sheets UI.
Examples:
# Sets 'Hello world' in 'A2' cell worksheet.update('A2', 'Hello world') # Updates cells A1, B1, C1 with values 42, 43, 44 respectively worksheet.update([42, 43, 44]) # Updates A2 and A3 with values 42 and 43 # Note that update range can be bigger than values array worksheet.update('A2:B4', [[42], [43]]) # Add a formula worksheet.update('A5', '=SUM(A1:A4)', raw=False) # Update 'my_range' named range with values 42 and 43 worksheet.update('my_range', [[42], [43]]) # Note: named ranges are defined in the scope of # a spreadsheet, so even if `my_range` does not belong to # this sheet it is still updated
New in version 3.3.
-
update_acell
(label, value)¶ Updates the value of a cell.
Parameters: - label (str) – Cell label in A1 notation.
- value – New value.
Example:
worksheet.update_acell('A1', '42')
-
update_cell
(row, col, value)¶ Updates the value of a cell.
Parameters: Example:
worksheet.update_cell(1, 1, '42')
-
update_cells
(cell_list, value_input_option='RAW')¶ Updates many cells at once.
Parameters: - cell_list (list) – List of
gspread.cell.Cell
objects to update. - value_input_option (str) –
(optional) How the input data should be interpreted. Possible values are:
ValueInputOption.raw
- The values the user has entered will not be parsed and will be stored as-is.
ValueInputOption.user_entered
- The values will be parsed as if the user typed them into the UI. Numbers will stay as numbers, but strings may be converted to numbers, dates, etc. following the same rules that are applied when entering text into a cell via the Google Sheets UI.
See ValueInputOption in the Sheets API.
Example:
# Select a range cell_list = worksheet.range('A1:C7') for cell in cell_list: cell.value = 'O_o' # Update in batch worksheet.update_cells(cell_list)
- cell_list (list) – List of
-
update_index
(index)¶ Updates the
index
property for the worksheet.See the Sheets API documentation for information on how updating the index property affects the order of worksheets in a spreadsheet.
To reorder all worksheets in a spreadsheet, see Spreadsheet.reorder_worksheets.
New in version 3.4.
-
update_note
(cell, content)¶ Update the content of the note located at cell.
Parameters: New in version 3.7.
-
updated
¶ Deprecated since version 2.0.
This feature is not supported in Sheets API v4.
-
url
¶ Worksheet URL.
-