gspread_helpers.range_name.range_name#

Helper method for dynamically creating range names, i.e. ‘A2:BR34’.

Classes

RangeName

Generates a range name for updating a worksheet in Google Sheets or Excel, e.g. 'A1:B5'.

class gspread_helpers.range_name.range_name.RangeName[source]#

Generates a range name for updating a worksheet in Google Sheets or Excel, e.g. ‘A1:B5’.

Parameters:

rowsint: The number of total rows that should be updated in the worksheet. Value must be greater than zero. Value must also not exceed the predtermined limits set by the GOOGLE_SHEETS_ROW_LIMIT and-or EXCEL_ROW_LIMIT constants. Modulate the override_row_limit argument to supersede those limits. You may also modify the just-mentioned constants.
colsint: The number of total columns that should be updated in the worksheet. Value must be greater than zero. Value must also not exceed the predtermined limits set by the GOOGLE_SHEETS_COL_LIMIT and-or EXCEL_COL_LIMIT constants. Modulate the override_col_limit argument to supersede those limits. You may also modify the just-mentioned constants.
header_rows_sizeint, optional: If the rows and cols arguments do not account for a pre-existing header in the worksheet then use this parameter to indicate how large the header is, in terms of number of rows. Value must be equal to or greater than zero. Default is 0.
bufferint | str, optional: If you do not want to construct the range name beginning from the letter ‘A’ then provide an integer or alphabetical letter that corresponds to the position with which you intend to begin constructing the range name. When providing an integer, think of that value as meaning how many shifts to the right you want. For instance, if you intend to begin constructing the range name from ‘B’ then provide ‘1’ as an argument, i.e. one shift rightward. It may be more intuitive, therefore, to provide alphabetical letters as arguments instead of integers!
source(‘google_sheets’, ‘excel’), optional: Default is ‘google_sheets’.
override_row_limitbool, optional: Set to True if you would like to override the predetermined row limit. Default is False.
override_col_limitbool, optional: Set to True if you would like to override the predetermined column limit. Default is False.

Attributes

range_name:

Only accessible after the RangeName object is initialized. Generates the range name, e.g. ‘A2:EE1000’ per the provided arguments.

Raises:

RowLimitExceededException: Raised if the rows argument exceeds the predetermined limit set by the GOOGLE_SHEETS_ROW_LIMIT and EXCEL_ROW_LIMIT constants.
ColumnLimitExceededException: Raised if the cols argument exceeds the predetermined limit set by the GOOGLE_SHEETS_COL_LIMIT and EXCEL_COL_LIMIT constants.

See also

gspread_helpers.range_name.validations.GOOGLE_SHEETS_ROW_LIMIT
gspread_helpers.range_name.validations.EXCEL_ROW_LIMIT
gspread_helpers.range_name.validations.GOOGLE_SHEETS_COL_LIMIT
gspread_helpers.range_name.validations.EXCEL_COL_LIMIT
gspread_helpers.range_name.exceptions.RowLimitExceeded
gspread_helpers.range_name.exceptions.ColumnLimitExceeded

Examples

The row limit for range names in Microsoft Excel is, by default, 1,048,576. Below, we override that limitation using the override_col_limit argument set to True and by setting source equal to ‘excel’.

>>> rn = RangeName(
>>>     rows=2, cols=1_048_580, override_col_limit=True, source="excel"
>>> )
>>> print(rn.range_name)
'A1:BGQCZ2'

However, we could have also updated the EXCEL_ROW_LIMIT constant instead.

>>> from gspread_helpers import EXCEL_ROW_LIMIT
>>> EXCEL_ROW_LIMIT = 1_048_580
>>> rn = RangeName(rows=2, cols=1_048_580, source="excel")
>>> print(rn.range_name)
'A1:BGQCZ2'

Modulating the header_rows_size argument looks like this.

>>> rn = RangeName(rows=2, cols=2, header_rows_size=2)
'A3:B4'

Finally, if we want to buffer the range name beginning from ‘B’, we may do this.

>>> rn = RangeName(rows=2, cols=2, buffer=1)
'B1:C2'

Passing ‘B’ to buffer is equivalent to passing 1.

>>> rn = RangeName(rows=2, cols=2, buffer="B")
'B1:C2'

gspread_helpers.range_name.range_name#

This Page