gspread

https://docs.gspread.org/en/v6.2.1/
Admin
gspread is a Python API for Google Sheets, enabling users to open, read, write, format, and share...
Tokens:94,993
Snippets:782
Trust Score:7.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### get() examples

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Shows various ways to call worksheet.get() to retrieve values from a sheet, including specific cells, ranges, columns, named ranges, and with value_render_option.

```python
# 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 all values from columns "A" and "B"
worksheet.get('A:B')

# Return values of 'my_range' named range
worksheet.get('my_range')

# Return unformatted values (e.g. numbers as numbers)
worksheet.get('A2:B4', value_render_option=ValueRenderOption.unformatted)

# Return cell values without calculating formulas
worksheet.get('A2:B4', value_render_option=ValueRenderOption.formula)
```

--------------------------------

### Insert Permission Examples

Source: https://docs.gspread.org/en/v6.2.1/api/http_client.html

Examples showing how to grant write access to a specific user and how to make a spreadsheet publicly readable.

```python
# Give write permissions to otto@example.com

gc.insert_permission(
    '0BmgG6nO_6dprnRRUWl1UFE',
    'otto@example.org',
    perm_type='user',
    role='writer'
)

# Make the spreadsheet publicly readable

gc.insert_permission(
    '0BmgG6nO_6dprnRRUWl1UFE',
    None,
    perm_type='anyone',
    role='reader'
)
```

--------------------------------

### Install gspread with pip

Source: https://docs.gspread.org/en/v6.2.1/_sources/index.rst.txt

Install gspread using pip. Requires Python 3+.

```sh
pip install gspread
```

--------------------------------

### to_records example

Source: https://docs.gspread.org/en/v6.2.1/api/utils.html

Builds a list of dictionaries from headers and values. The example shows the output for headers ['name', 'City'] and values [['Spiderman', 'NY'], ['Batman', 'Gotham']].

```python
>>> to_records(["name", "City"], [["Spiderman", "NY"], ["Batman", "Gotham"]])
[
    {
        "Name": "Spiderman",
        "City": "NY",
    },
    {
        "Name": "Batman",
        "City": "Gotham",
    },
]
```

--------------------------------

### get_notes() examples

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Reads notes from the sheet or a specific range. The example shows the output for a sheet with notes in A1 and B2, and how to fill gaps to make the matrix square.

```python
# Note data:
#      A      B
# 1    A1     -
# 2    -      B2

# Read all notes from the sheet
>>> worksheet.get_notes()
[
    ["A1"],
    ["", "B2"]
]
>>> arr = worksheet.get_notes()
>>> gspread.utils.fill_gaps(arr, len(arr), max(len(a) for a in arr), None)
[
    ["A1", ""],
    ["", "B2"]
]
# Read notes from a specific range
>>> worksheet.get_notes(grid_range="A2:B2")
[
    ["", "B2"]
]
```

--------------------------------

### Service account JSON credentials file example

Source: https://docs.gspread.org/en/v6.2.1/_sources/oauth2.rst.txt

Example of the JSON credentials file downloaded when creating a service account key. Contains the service account's private key, client email, and other fields. The client_email is needed to share the spreadsheet with the service account.

```json
{
    "type": "service_account",
    "project_id": "api-project-XXX",
    "private_key_id": "2cd … ba4",
    "private_key": "-----BEGIN PRIVATE KEY-----\nNrDyLw … jINQh/9\n-----END PRIVATE KEY-----\n",
    "client_email": "473000000000-yoursisdifferent@developer.gserviceaccount.com",
    "client_id": "473 … hd.apps.googleusercontent.com",
    ...
}
```

--------------------------------

### find_table example

Source: https://docs.gspread.org/en/v6.2.1/api/utils.html

Expands a list of values based on non-null adjacent cells. The example uses TableDirection.table starting at 'B2' to find a table. Raises InvalidInputValue if start_range is outside the matrix. Values must be padded with empty strings.

```python
values = [
    ['', '',   '',   '', ''  ],
    ['', 'B2', 'C2', '', 'E2'],
    ['', 'B3', 'C3', '', 'E3'],
    ['', ''  , ''  , '', 'E4'],
]
>>> utils.find_table(TableDirection.table, 'B2')
[
    ['B2', 'C2'],
    ['B3', 'C3'],
]
```

--------------------------------

### insert_notes example: dict of notes

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Example of the dict format for the insert_notes method, mapping cell coordinates to note content.

```python
{
    "D7": "Please read my notes",
    "GH42": "this one is too far",
}
```

--------------------------------

### get_all_records() example

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Reads all rows from the sheet and returns a list of dictionaries with the first row as keys. The example shows the output for a sheet with data in columns A, B, C.

```python
# Sheet data:
#      A    B    C
#
# 1    A1   B2   C3
# 2    A6   B7   C8
# 3    A11  B12  C13

# Read all rows from the sheet
>>> worksheet.get_all_records()
[
    {"A1": "A6", "B2": "B7", "C3": "C8"},
    {"A1": "A11", "B2": "B12", "C3": "C13"}
]
```

--------------------------------

### absolute_range_name examples

Source: https://docs.gspread.org/en/v6.2.1/api/utils.html

Returns an absolutized path of a range, quoting sheet names as needed. Examples show various inputs and outputs.

```python
>>> absolute_range_name("Sheet1", "A1:B1")
"'Sheet1'!A1:B1"
```

```python
>>> absolute_range_name("Sheet1", "A1")
"'Sheet1'!A1"
```

```python
>>> absolute_range_name("Sheet1")
"'Sheet1'"
```

```python
>>> absolute_range_name("Sheet'1")
"'Sheet''1'"
```

```python
>>> absolute_range_name("Sheet''1")
"'Sheet''''1'"
```

```python
>>> absolute_range_name("''sheet12''", "A1:B2")
"'''''sheet12'''''!A1:B2"
```

--------------------------------

### a1_range_to_grid_range examples

Source: https://docs.gspread.org/en/v6.2.1/api/utils.html

Converts A1 notation to a GridRange dict. Indexes are zero-based and half-open. Missing indexes indicate unbounded range. Examples show various inputs and outputs.

```python
>>> a1_range_to_grid_range('A1:A1')
{'startRowIndex': 0, 'endRowIndex': 1, 'startColumnIndex': 0, 'endColumnIndex': 1}
```

```python
>>> a1_range_to_grid_range('A3:B4')
{'startRowIndex': 2, 'endRowIndex': 4, 'startColumnIndex': 0, 'endColumnIndex': 2}
```

```python
>>> a1_range_to_grid_range('A:B')
{'startColumnIndex': 0, 'endColumnIndex': 2}
```

```python
>>> a1_range_to_grid_range('A5:B')
{'startRowIndex': 4, 'startColumnIndex': 0, 'endColumnIndex': 2}
```

```python
>>> a1_range_to_grid_range('A1')
{'startRowIndex': 0, 'endRowIndex': 1, 'startColumnIndex': 0, 'endColumnIndex': 1}
```

```python
>>> a1_range_to_grid_range('A')
{'startColumnIndex': 0, 'endColumnIndex': 1}
```

```python
>>> a1_range_to_grid_range('1')
{'startRowIndex': 0, 'endRowIndex': 1}
```

```python
>>> a1_range_to_grid_range('A1', sheet_id=0)
{'sheetId': 0, 'startRowIndex': 0, 'endRowIndex': 1, 'startColumnIndex': 0, 'endColumnIndex': 1}
```

--------------------------------

### open_by_key: Open spreadsheet by key

Source: https://docs.gspread.org/en/v6.2.1/api/client.html

Example of using gc.open_by_key to open a spreadsheet by its key (Spreadsheet ID). Returns a Spreadsheet instance.

```python
>>> gc.open_by_key('0BmgG6nO_6dprdS1MN3d3MkdPa142WFRrdnRRUWl1UFE')

```

--------------------------------

### Authenticate with OAuth credentials as a Python dict

Source: https://docs.gspread.org/en/v6.2.1/_sources/oauth2.rst.txt

Shows how to pass OAuth credentials directly as a Python dict to `gspread.oauth_from_dict`. This avoids storing credentials as files. The example includes a placeholder `...` for additional fields.

```python
import gspread

credentials = {
    "installed": {
        "client_id": "12345678901234567890abcdefghijklmn.apps.googleusercontent.com",
        "project_id": "my-project1234",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        ...
    }
}
gc, authorized_user = gspread.oauth_from_dict(credentials)

sh = gc.open("Example spreadsheet")

print(sh.sheet1.get('A1'))
```

--------------------------------

### fill_gaps example

Source: https://docs.gspread.org/en/v6.2.1/api/utils.html

Fills gaps in a list of lists to a specified number of rows and columns, using a padding value (default ''). The example shows filling a 1-row list to 2 rows and 4 columns.

```python
>>> L = [
... [1, 2, 3],
... ]
>>> fill_gaps(L, 2, 4)
[
    [1, 2, 3, ""],
    ["", "", "", ""]
]
```

--------------------------------

### open_by_url: Open spreadsheet by URL

Source: https://docs.gspread.org/en/v6.2.1/api/client.html

Example of using gc.open_by_url to open a spreadsheet by its URL. Returns a Spreadsheet instance. Raises gspread.SpreadsheetNotFound if no spreadsheet with the specified URL is found.

```python
>>> gc.open_by_url('https://docs.google.com/spreadsheet/ccc?key=0Bm...FE&hl')

```

--------------------------------

### open: Open spreadsheet by title

Source: https://docs.gspread.org/en/v6.2.1/api/client.html

Example of using gc.open to open a spreadsheet by its title. Returns a Spreadsheet instance. Raises gspread.SpreadsheetNotFound if no spreadsheet with the specified title is found.

```python
>>> gc.open('My fancy spreadsheet')

```

--------------------------------

### Get formatted cell value

Source: https://docs.gspread.org/en/v6.2.1/user-guide.html

Gets the value as displayed, including formatting such as currency symbols. Example output: [['$12.00']].

```python
worksheet.get("A1:B2")
```

--------------------------------

### values_update example

Source: https://docs.gspread.org/en/v6.2.1/api/http_client.html

Directly calls the PUT spreadsheets/<ID>/values/<range> endpoint. The range is given in A1 notation, and the body must contain the values to update. The valueInputOption parameter is set to 'USER_ENTERED'.

```python
sh.values_update(
    'Sheet1!A2',
    params={
        'valueInputOption': 'USER_ENTERED'
    },
    body={
        'values': [[1, 2, 3]]
    }
)

```

--------------------------------

### Get cell value with cell coordinates

Source: https://docs.gspread.org/en/v6.2.1/_sources/user-guide.rst.txt

Gets a cell value using row and column coordinates. Row and column numbers start at 1.

```python
   val = worksheet.cell(1, 2).value
```

--------------------------------

### Get unformatted cell value

Source: https://docs.gspread.org/en/v6.2.1/user-guide.html

Gets the underlying numeric value without formatting. Requires importing ValueRenderOption from gspread.utils. Example output: [[12]].

```python
from gspread.utils import ValueRenderOption
worksheet.get("A1:B2", value_render_option=ValueRenderOption.unformatted)
```

--------------------------------

### Quick example: open, update, and format a Google Sheet

Source: https://docs.gspread.org/en/v6.2.1/_sources/index.rst.txt

Shows how to authenticate with a service account, open a spreadsheet by title, update a range and a single cell, and format a header. Requires OAuth2 credentials.

```python
import gspread

gc = gspread.service_account()

# Open a sheet from a spreadsheet in one go
wks = gc.open("Where is the money Lebowski?").sheet1

# Update a range of cells using the top left corner address
wks.update([[1, 2], [3, 4]], 'A1')

# Or update a single cell
wks.update_acell('B42', "it's down there somewhere, let me take another look.")

# Format the header
wks.format('A1:B1', {'textFormat': {'bold': True}})
```

--------------------------------

### Get formula with worksheet.get and ValueRenderOption.formula

Source: https://docs.gspread.org/en/v6.2.1/_sources/user-guide.rst.txt

Gets a cell's formula instead of the resulting value using ValueRenderOption.formula. The example returns [['=1/1024']] for cell G6.

```python
   from gspread.utils import ValueRenderOption
   worksheet.get("G6", value_render_option=ValueRenderOption.formula)
```

```text
   Resulsts in: [['=1/1024']]
```

--------------------------------

### Get cell value

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Returns a Cell object for the given row and column. The example shows accessing cell A1.

```python
>>> worksheet.cell(1, 1)
<Cell R1C1 "I'm cell A1">
```

--------------------------------

### Get a cell with worksheet.acell()

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Returns a Cell instance for the given A1 label. The example shows the repr of the returned Cell.

```python
>>> worksheet.acell('A1')
<Cell R1C1 "I'm cell A1">
```

--------------------------------

### Get cell formula using ValueRenderOption.formula

Source: https://docs.gspread.org/en/v6.2.1/user-guide.html

Retrieves the formula from a cell instead of its value. Requires importing ValueRenderOption from gspread.utils. Example output: [['=1/1024']].

```python
from gspread.utils import ValueRenderOption
worksheet.get("G6", value_render_option=ValueRenderOption.formula)
```

--------------------------------

### service_account

Source: https://docs.gspread.org/en/v6.2.1/_sources/api/top-level.rst.txt

Creates a service account client from a service account key file and authorizes it with gspread.

```APIDOC
## service_account

### Description
Creates a service account client from a service account key file and authorizes it with gspread.

### Method
Function

### Signature
`service_account(filename)`

### Parameters
- **filename** (str) - Required - Path to the service account key file.

### Returns
- Authorized client object.

```

--------------------------------

### gspread.auth.get_config_dir(config_dir_name='gspread', os_is_windows=False)

Source: https://docs.gspread.org/en/v6.2.1/api/auth.html

Construct a config dir path. By default: %APPDATA%gspread on Windows, ~/.config/gspread everywhere else.

```APIDOC
## gspread.auth.get_config_dir

### Description
Construct a config dir path. By default: %APPDATA%gspread on Windows, ~/.config/gspread everywhere else.

### Method
Function call

### Signature
`gspread.auth.get_config_dir(config_dir_name: str = 'gspread', os_is_windows: bool = False) -> Path`

### Parameters
- **config_dir_name** (str) - Optional - The name of the config directory. Defaults to 'gspread'.
- **os_is_windows** (bool) - Optional - Whether the operating system is Windows. Defaults to False.

### Return Type
`pathlib.Path`

### Example
```python
import gspread

config_dir = gspread.auth.get_config_dir()
print(config_dir)  # ~/.config/gspread on Linux/macOS
```
```

--------------------------------

### Expand a table with worksheet.expand

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Expands a cell range based on non-null adjacent cells. The example shows a matrix and the result of utils.find_table(TableDirection.table, 'B2') which returns the table starting at B2. Note that TableDirection.table looks right then down from the starting cell and does not check cells inside the table.

```python
values = [
    ['', '',   '',   '', ''  ],
    ['', 'B2', 'C2', '', 'E2'],
    ['', 'B3', 'C3', '', 'E3'],
    ['', ''  , ''  , '', 'E4'],
]
>>> utils.find_table(TableDirection.table, 'B2')
[
    ['B2', 'C2'],
    ['B3', 'C3'],
]

```

--------------------------------

### gspread.auth.local_server_flow(client_config, scopes, port=0)

Source: https://docs.gspread.org/en/v6.2.1/api/auth.html

Run an OAuth flow using a local server strategy. Creates an OAuth flow and runs google_auth_oauthlib.flow.InstalledAppFlow.run_local_server. This will start a local web server and open the authorization URL in the user's browser. Pass this function to `flow` parameter of `oauth()` to run a local server flow.

```APIDOC
## gspread.auth.local_server_flow

### Description
Run an OAuth flow using a local server strategy. Creates an OAuth flow and runs google_auth_oauthlib.flow.InstalledAppFlow.run_local_server. This will start a local web server and open the authorization URL in the user's browser. Pass this function to `flow` parameter of `oauth()` to run a local server flow.

### Method
Function call

### Signature
`gspread.auth.local_server_flow(client_config: Mapping[str, Any], scopes: Iterable[str], port: int = 0) -> Credentials`

### Parameters
- **client_config** (Mapping[str, Any]) - Required - The client configuration dictionary.
- **scopes** (Iterable[str]) - Required - The OAuth scopes to request.
- **port** (int) - Optional - The port for the local server. Defaults to 0 (random).

### Return Type
`google.auth.credentials.Credentials`

### Example
```python
import gspread

client_config = {
    'installed': {
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET',
        'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
        'token_uri': 'https://oauth2.googleapis.com/token',
    }
}
scopes = ['https://www.googleapis.com/auth/spreadsheets']
creds = gspread.auth.local_server_flow(client_config, scopes)
```
```

--------------------------------

### rightpad()

Source: https://docs.gspread.org/en/v6.2.1/api/utils.html

Right pads a string.

```APIDOC
## rightpad()

### Description
Right pads a string.

```

--------------------------------

### Authenticate in Google Colaboratory with gspread

Source: https://docs.gspread.org/en/v6.2.1/_sources/advanced.rst.txt

Authenticate in a Google Colaboratory notebook using the built-in auth module and default credentials. This is the easiest way to get started with gspread in Colab.

```python
from google.colab import auth
auth.authenticate_user()

import gspread
from google.auth import default
creds, _ = default()

gc = gspread.authorize(creds)
```

--------------------------------

### gspread.Client.create()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Method to create a new spreadsheet.

```APIDOC
## create()

### Description
Method to create a new spreadsheet.

### Method
Function

### Location
`gspread.Client`

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Extract table with worksheet.expand("A2")

Source: https://docs.gspread.org/en/v6.2.1/user-guide.html

Extracts a rectangular table starting from cell A2, searching right and down until empty cells are found. The example output shows rows 2 to 4 from the sample sheet.

```python
worksheet.expand("A2")

[
   ["Batman", "DC", "Very rich"],
   ["DeadPool", "Marvel", "self healing"],
   ["Superman", "DC", "super human"],
]

```

--------------------------------

### Open public spreadsheet with API key

Source: https://docs.gspread.org/en/v6.2.1/_sources/oauth2.rst.txt

Creates a gspread client using an API key and opens a public spreadsheet by its key, then prints cell A1. Only works with public spreadsheets; gc.open() will not work because it searches private files.

```python
import gspread

gc = gspread.api_key("<your newly create key>")

sh = gc.open_by_key("1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms")

print(sh.sheet1.get('A1'))
```

--------------------------------

### Get all values from a column with col_values

Source: https://docs.gspread.org/en/v6.2.1/_sources/user-guide.rst.txt

Gets all values from the first column of the worksheet.

```python
   values_list = worksheet.col_values(1)
```

--------------------------------

### oauth

Source: https://docs.gspread.org/en/v6.2.1/_sources/api/top-level.rst.txt

Creates an OAuth2 client using the provided credentials and authorizes it with gspread.

```APIDOC
## oauth

### Description
Creates an OAuth2 client using the provided credentials and authorizes it with gspread.

### Method
Function

### Signature
`oauth(credentials)`

### Parameters
- **credentials** (OAuth2Credentials) - Required - The OAuth2 credentials object.

### Returns
- Authorized client object.

```

--------------------------------

### Get all values from a row with row_values

Source: https://docs.gspread.org/en/v6.2.1/_sources/user-guide.rst.txt

Gets all values from the first row of the worksheet.

```python
   values_list = worksheet.row_values(1)
```

--------------------------------

### Client.create(title, folder_id=None)

Source: https://docs.gspread.org/en/v6.2.1/api/client.html

Creates a new spreadsheet with the specified title and optional folder placement.

```APIDOC
## `Client.create(title, folder_id=None)`

### Description
Creates a new spreadsheet with the given title.

### Parameters
- **title** (str) - Required - A title of a new spreadsheet.
- **folder_id** (str) - Optional - Id of the folder where we want to save the spreadsheet.

### Returns
- A `Spreadsheet` instance.
```

--------------------------------

### Get cell value with acell A1 notation

Source: https://docs.gspread.org/en/v6.2.1/_sources/user-guide.rst.txt

Gets a cell value using A1 notation.

```python
   val = worksheet.acell('B1').value
```

--------------------------------

### Pass service account credentials as a dictionary

Source: https://docs.gspread.org/en/v6.2.1/_sources/oauth2.rst.txt

Alternative to loading from a file: pass a dictionary containing the service account credentials directly to gspread.service_account(). The dictionary must contain the same fields as the JSON file.

```python
import gspread

credentials = {
    "type": "service_account",
    "project_id": "api-project-XXX",
    "private_key_id": "2cd … ba4",
    "private_key": "-----BEGIN PRIVATE KEY-----\nNrDyLw … jINQh/9\n-----END PRIVATE KEY-----\n",
    "client_email": "473000000000-yoursisdifferent@developer.gserviceaccount.com",
    "client_id": "473 … hd.apps.googleusercontent.com",
    ...
}
```

--------------------------------

### hide_rows(start, end)

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Explicitly hides the given row index range. Index starts from 0.

```APIDOC
## hide_rows(start, end)

### Description
Explicitly hides the given row index range. Index starts from 0.

### Method
POST

### Endpoint
Worksheet.hide_rows()

### Parameters
#### Path Parameters
- **start** (int) - Required - The (inclusive) starting row to hide.
- **end** (int) - Required - The (exclusive) end row to hide.

### Response
#### Success Response
- **MutableMapping[str, Any]** - The response from the Sheets API.

#### Response Example
```
{}
```
```

--------------------------------

### hide_columns(start, end)

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Explicitly hides the given column index range. Index starts from 0.

```APIDOC
## hide_columns(start, end)

### Description
Explicitly hides the given column index range. Index starts from 0.

### Method
POST

### Endpoint
Worksheet.hide_columns()

### Parameters
#### Path Parameters
- **start** (int) - Required - The (inclusive) starting column to hide.
- **end** (int) - Required - The (exclusive) end column to hide.

### Response
#### Success Response
- **MutableMapping[str, Any]** - The response from the Sheets API.

#### Response Example
```
{}
```
```

--------------------------------

### Pass credentials as a dictionary

Source: https://docs.gspread.org/en/v6.2.1/oauth2.html

Authenticates using a dictionary of service account credentials instead of a file.

```python
import gspread

credentials = {
    "type": "service_account",
    "project_id": "api-project-XXX",
    "private_key_id": "2cd … ba4",
    "private_key": "-----BEGIN PRIVATE KEY-----\nNrDyLw … jINQh/9\n-----END PRIVATE KEY-----\n",
    "client_email": "473000000000-yoursisdifferent@developer.gserviceaccount.com",
    "client_id": "473 … hd.apps.googleusercontent.com",
    ...
}

gc = gspread.service_account_from_dict(credentials)

sh = gc.open("Example spreadsheet")

print(sh.sheet1.get('A1'))
```

--------------------------------

### range() examples with A1 notation, numeric boundaries, named ranges, and all values

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Shows how to use worksheet.range() with A1 notation, numeric boundaries, named ranges, and no arguments to fetch all values in a single API call.

```python
>>> # 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'>, ...]
```

--------------------------------

### Authenticate with google-auth Credentials and gspread.authorize

Source: https://docs.gspread.org/en/v6.2.1/_sources/oauth2.rst.txt

Under-the-hood equivalent of gspread.service_account() using the google.oauth2.service_account.Credentials class. Loads credentials from a service account file with the required scopes and authorizes gspread.

```python
from google.oauth2.service_account import Credentials

scopes = [
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/drive'
]

credentials = Credentials.from_service_account_file(
    'path/to/the/downloaded/file.json',
    scopes=scopes
)

gc = gspread.authorize(credentials)
```

--------------------------------

### Get cell formula with acell/cell value_render_option

Source: https://docs.gspread.org/en/v6.2.1/_sources/user-guide.rst.txt

Gets a cell's formula instead of the resulting value by passing value_render_option='FORMULA' to acell or cell.

```python
   cell = worksheet.acell('B1', value_render_option='FORMULA').value

   # or

   cell = worksheet.cell(1, 2, value_render_option='FORMULA').value
```

--------------------------------

### Authenticate with OAuth credentials and authorized user dict

Source: https://docs.gspread.org/en/v6.2.1/_sources/oauth2.rst.txt

Shows how to pass both credentials and an authorized user dict to `gspread.oauth_from_dict`. This allows skipping the browser flow if the authorized user has not expired. The example includes placeholder values for the authorized user.

```python
import gspread

credentials = {
    "installed": {
        "client_id": "12345678901234567890abcdefghijklmn.apps.googleusercontent.com",
        "project_id": "my-project1234",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        ...
    }
}
authorized_user = {
    "refresh_token": "8//ThisALONGTOkEn....",
    "token_uri": "https://oauth2.googleapis.com/token",
    "client_id": "12345678901234567890abcdefghijklmn.apps.googleusercontent.com",
    "client_secret": "MySecRet....",
    "scopes": [
        "https://www.googleapis.com/auth/spreadsheets",
        "https://www.googleapis.com/auth/drive"
    ],
    "expiry": "1070-01-01T00:00:00.000001Z"
}
gc, authorized_user = gspread.oauth_from_dict(credentials, authorized_user)
```

--------------------------------

### is_scalar examples

Source: https://docs.gspread.org/en/v6.2.1/api/utils.html

Returns True if the value is scalar (not a sequence, but can be a string). Examples show that lists are not scalar, while numbers, strings, dicts, and sets are.

```python
>>> is_scalar([])
False
```

```python
>>> is_scalar([1, 2])
False
```

```python
>>> is_scalar(42)
True
```

```python
>>> is_scalar('nice string')
True
```

```python
>>> is_scalar({})
True
```

```python
>>> is_scalar(set())
True
```

--------------------------------

### get()

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

The get() method retrieves values from a worksheet. It can return all values, a specific cell, a range, a column range, or a named range. It supports value rendering options.

```APIDOC
## get()

### Description
Returns values from the worksheet. Can return all values, a specific cell, a range, a column range, or a named range. Supports value rendering options.

### Method
GET

### Endpoint
worksheet.get()

### Parameters
#### Query Parameters
- **range_name** (str) - Optional - A1 notation or named range. If omitted, returns all values.
- **value_render_option** (ValueRenderOption) - Optional - Determines how values are rendered (e.g., unformatted, formula).

### Request Example
```python
worksheet.get('A1:B2', value_render_option=ValueRenderOption.unformatted)
```

### Response
#### Success Response (200)
- **ValueRange** - The values in the specified range.

#### Response Example
```python
ValueRange object
```
```

--------------------------------

### gspread.oauth() with console flow

Source: https://docs.gspread.org/en/v6.2.1/api/auth.html

Runs a console strategy where the user is instructed to open the authorization URL in their browser and then copy & paste the authorization code into the application. Pass the console_flow function to the flow parameter.

```python
gc = gspread.oauth(flow=gspread.auth.console_flow)
```

--------------------------------

### Provide custom credentials file paths

Source: https://docs.gspread.org/en/v6.2.1/api/top-level.html

Specifies alternative paths for the credentials and authorized user JSON files.

```python
gc = gspread.oauth(
    credentials_filename='/alternative/path/credentials.json',
    authorized_user_filename='/alternative/path/authorized_user.json',
)
```

--------------------------------

### gspread.auth.authorize(credentials, http_client=HTTPClient, session=None)

Source: https://docs.gspread.org/en/v6.2.1/api/auth.html

Login to Google API using OAuth2 credentials. This is a shortcut/helper function which instantiates a client using http_client. By default `gspread.HTTPClient` is used (but could also use `gspread.BackOffHTTPClient` to avoid rate limiting). It can take an additional requests.Session object in order to provide your own session object.

```APIDOC
## gspread.auth.authorize

### Description
Login to Google API using OAuth2 credentials. This is a shortcut/helper function which instantiates a client using http_client. By default `gspread.HTTPClient` is used (but could also use `gspread.BackOffHTTPClient` to avoid rate limiting). It can take an additional requests.Session object in order to provide your own session object.

### Method
Function call

### Signature
`gspread.auth.authorize(credentials: google.auth.credentials.Credentials, http_client: Type[gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>, session: requests.Session | None = None) -> Client`

### Parameters
- **credentials** (google.auth.credentials.Credentials) - Required - OAuth2 credentials
- **http_client** (Type[gspread.http_client.HTTPClient]) - Optional - A factory function that returns a client class. Defaults to `gspread.http_client.HTTPClient` (but could also use `gspread.http_client.BackOffHTTPClient` to avoid rate limiting)
- **session** (requests.Session | None) - Optional - An additional requests.Session object to provide your own session object. When providing your own session, use the value None as credentials.

### Return Type
`gspread.client.Client`

### Example
```python
import gspread

# Using default HTTPClient
gc = gspread.auth.authorize(credentials)

# Using BackOffHTTPClient and custom session
import requests
session = requests.Session()
gc = gspread.auth.authorize(None, http_client=gspread.BackOffHTTPClient, session=session)
```
```

--------------------------------

### gspread.worksheet.Worksheet.get_note()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Gets the note of a cell.

```APIDOC
## get_note()

### Description
Gets the note of a cell.

### Method
- get_note()

### Parameters
None

### Returns
None
```

--------------------------------

### Create a new spreadsheet with gc.create

Source: https://docs.gspread.org/en/v6.2.1/_sources/user-guide.rst.txt

Creates a new blank spreadsheet. If using a service account, the new spreadsheet is only visible to that account; you must share it with your own email to access it from Google Sheets, see the sharing example below.

```python
   sh = gc.create('A new spreadsheet')
```

--------------------------------

### gspread.worksheet.Worksheet.get_tab_color()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Gets the tab color of the worksheet.

```APIDOC
## get_tab_color()

### Description
Gets the tab color of the worksheet.

### Method
- get_tab_color()

### Parameters
None

### Returns
None
```

--------------------------------

### gspread.worksheet.Worksheet.get_notes()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Gets notes of multiple cells.

```APIDOC
## get_notes()

### Description
Gets notes of multiple cells.

### Method
- get_notes()

### Parameters
None

### Returns
None
```

--------------------------------

### Open spreadsheet by URL with gc.open_by_url

Source: https://docs.gspread.org/en/v6.2.1/_sources/user-guide.rst.txt

Opens a spreadsheet by pasting the entire spreadsheet URL. This is a convenience alternative to open_by_key when you do not want to extract the key manually.

```python
   sht2 = gc.open_by_url('https://docs.google.com/spreadsheet/ccc?key=0Bm...FE&hl')
```

--------------------------------

### gspread.worksheet.Worksheet.col_values()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Method to get all values in a column.

```APIDOC
## col_values()

### Description
Method to get all values in a column.

### Method
Function

### Location
`gspread.worksheet.Worksheet`

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### gspread.Client.openall()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Opens all spreadsheets accessible to the client. This method is part of the gspread Client class.

```APIDOC
## openall()

### Description
Opens all spreadsheets accessible to the client.

### Method
openall()

### Returns
- **list** - A list of Spreadsheet objects.
```

--------------------------------

### gspread.worksheet.Worksheet.cell()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Method to get a cell from the worksheet.

```APIDOC
## cell()

### Description
Method to get a cell from the worksheet.

### Method
Function

### Location
`gspread.worksheet.Worksheet`

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Format cells in batch with batch_format

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Shows how to apply formatting to multiple ranges in one call using batch_format. The example formats A1:C1 with bold text and A2:C2 with font size 16.

```python
# 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_format(formats)

```

--------------------------------

### get_a1_from_absolute_range()

Source: https://docs.gspread.org/en/v6.2.1/api/utils.html

Gets A1 notation from absolute range.

```APIDOC
## get_a1_from_absolute_range()

### Description
Gets A1 notation from absolute range.

```

--------------------------------

### gspread.spreadsheet.Spreadsheet.get_lastUpdateTime()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Gets the last update time of the spreadsheet.

```APIDOC
## get_lastUpdateTime()

### Description
Gets the last update time of the spreadsheet.

### Method
- get_lastUpdateTime()

### Parameters
None

### Returns
None
```

--------------------------------

### Client.copy(file_id, title=None, copy_permissions=False, folder_id=None, copy_comments=True)

Source: https://docs.gspread.org/en/v6.2.1/api/client.html

Copies a spreadsheet to a new spreadsheet with options to copy permissions and comments.

```APIDOC
## `Client.copy(file_id, title=None, copy_permissions=False, folder_id=None, copy_comments=True)`

### Description
Copies a spreadsheet to a new spreadsheet. Can copy permissions and comments.

### Parameters
- **file_id** (str) - Required - A key of a spreadsheet to copy.
- **title** (str) - Optional - A title for the new spreadsheet.
- **copy_permissions** (bool) - Optional - If True, copy permissions from the original spreadsheet to the new spreadsheet.
- **folder_id** (str) - Optional - Id of the folder where we want to save the spreadsheet.
- **copy_comments** (bool) - Optional - If True, copy the comments from the original spreadsheet to the new spreadsheet.

### Returns
- A `Spreadsheet` instance.

### Notes
Requires Google Drive scope `https://www.googleapis.com/auth/drive` when using custom credentials; otherwise, an `Insufficient Permission` error may occur.
```

--------------------------------

### gspread.Client.get_file_drive_metadata()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Gets file metadata from Google Drive.

```APIDOC
## get_file_drive_metadata()

### Description
Gets file metadata from Google Drive.

### Method
- get_file_drive_metadata()

### Parameters
None

### Returns
None
```

--------------------------------

### gspread.oauth_from_dict with console flow

Source: https://docs.gspread.org/en/v6.2.1/api/auth.html

Use gspread.oauth_from_dict with the console flow, where the user is instructed to open the authorization URL and paste the authorization code into the application.

```python
gc = gspread.oauth_from_dict(flow=gspread.auth.console_flow)

```

--------------------------------

### Spreadsheet.get_lastUpdateTime()

Source: https://docs.gspread.org/en/v6.2.1/api/models/spreadsheet.html

Gets the lastUpdateTime metadata from the Drive API.

```APIDOC
## get_lastUpdateTime()

### Description
Get the lastUpdateTime metadata from the Drive API.

### Method
get_lastUpdateTime

### Parameters
None

### Returns
str - The last update time of the spreadsheet.
```

--------------------------------

### show

Source: https://docs.gspread.org/en/v6.2.1/api/models/worksheet.html

Shows the current worksheet in the UI.

```APIDOC
## show() -> MutableMapping[str, Any]

### Description
Show the current worksheet in the UI.

### Response
Returns a MutableMapping representing the response body from the request.
```

--------------------------------

### gspread.Client.list_permissions()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Lists permissions for a file. This method is available on gspread.Client, gspread.HTTPClient, and gspread.spreadsheet.Spreadsheet.

```APIDOC
## list_permissions()

### Description
Lists permissions for a file.

### Method
Not specified (Python method)

### Parameters
Not specified in source.

### Returns
List of permission objects.

### Example
```python
client.list_permissions(file_id)
```
```

--------------------------------

### gspread.HTTPClient.get_file_drive_metadata()

Source: https://docs.gspread.org/en/v6.2.1/genindex.html

Gets file metadata from Google Drive using HTTP client.

```APIDOC
## get_file_drive_metadata()

### Description
Gets file metadata from Google Drive using HTTP client.

### Method
- get_file_drive_metadata()

### Parameters
None

### Returns
None
```
Tokens:
Raw