0
# gspread
1

2
Google Spreadsheets Python API - A comprehensive library providing programmatic access to Google Sheets through a clean, intuitive interface. Supports authentication via service accounts, OAuth2, and API keys, enabling robust integration with Google's spreadsheet platform for data manipulation, formatting, batch operations, and access control.
3

4
## Package Information
5

6
- **Package Name**: gspread
7
- **Language**: Python
8
- **Installation**: `pip install gspread`
9
- **Dependencies**: `google-auth>=1.12.0`, `google-auth-oauthlib>=0.4.1`
10

11
## Core Imports
12

13
```python
14
import gspread
15
```
16

17
For authentication functions:
18

19
```python
20
from gspread import service_account, oauth, authorize, api_key
21
```
22

23
For core classes:
24

25
```python
26
from gspread import Client, Spreadsheet, Worksheet, Cell
27
```
28

29
## Basic Usage
30

31
```python
32
import gspread
33

34
# Service account authentication
35
gc = gspread.service_account()
36

37
# Open spreadsheet by title
38
sheet = gc.open("My Spreadsheet").sheet1
39

40
# Read all values
41
values = sheet.get_all_values()
42
print(values)
43

44
# Update a single cell
45
sheet.update('B1', 'Hello World!')
46

47
# Update multiple cells
48
sheet.update([
49
    ['Name', 'Age', 'City'],
50
    ['Alice', 25, 'New York'],
51
    ['Bob', 30, 'San Francisco']
52
], 'A1')
53

54
# Get cell value
55
cell_value = sheet.cell(1, 1).value
56
print(cell_value)
57

58
# Find cells
59
cell = sheet.find("Alice")
60
print(f"Found at row {cell.row}, col {cell.col}")
61

62
# Batch operations for performance
63
sheet.batch_update([
64
    {'range': 'A1:C1', 'values': [['Name', 'Age', 'City']]},
65
    {'range': 'A2:C3', 'values': [['Alice', 25, 'NY'], ['Bob', 30, 'SF']]}
66
])
67
```
68

69
## Architecture
70

71
gspread follows a hierarchical object model:
72

73
- **Client**: Main entry point for authentication and spreadsheet management
74
- **Spreadsheet**: Container for worksheets with metadata and sharing capabilities
75
- **Worksheet**: Individual sheet with data manipulation and formatting methods
76
- **Cell**: Single cell representation with coordinate and value information
77

78
The library supports multiple authentication methods and provides both high-level convenience methods and low-level API access for advanced use cases.
79

80
## Capabilities
81

82
### Authentication
83

84
Multiple authentication methods including service accounts, OAuth2 flows, and API keys with support for both credential files and dictionary-based configuration.
85

86
```python { .api }
87
def service_account(filename: str = None, scopes: List[str] = None, http_client: HTTPClient = None) -> Client: ...
88
def oauth(scopes: List[str] = None, flow: InstalledAppFlow = None, filename: str = "credentials.json", port: int = 0, host: str = "localhost") -> Client: ...
89
def authorize(credentials, http_client: HTTPClient = None) -> Client: ...
90
def api_key(api_key: str) -> Client: ...
91
```
92

93
[Authentication](./authentication.md)
94

95
### Client Operations
96

97
Main client functionality for spreadsheet management, file operations, permissions, and sharing.
98

99
```python { .api }
100
class Client:
101
    def open(title: str) -> Spreadsheet: ...
102
    def open_by_key(key: str) -> Spreadsheet: ...
103
    def open_by_url(url: str) -> Spreadsheet: ...
104
    def create(title: str, folder_id: str = None) -> Spreadsheet: ...
105
    def copy(file_id: str, title: str = None, copy_permissions: bool = False) -> Spreadsheet: ...
106
```
107

108
[Client Operations](./client-operations.md)
109

110
### Spreadsheet Management
111

112
Spreadsheet-level operations including worksheet management, metadata access, batch operations, and sharing controls.
113

114
```python { .api }
115
class Spreadsheet:
116
    def add_worksheet(title: str, rows: int = 100, cols: int = 26, index: int = None) -> Worksheet: ...
117
    def batch_update(body: Dict) -> Dict: ...
118
    def share(value: str, perm_type: str = "user", role: str = "reader", notify: bool = True) -> Dict: ...
119
    def values_batch_get(ranges: List[str], major_dimension: str = "ROWS") -> Dict: ...
120
```
121

122
[Spreadsheet Management](./spreadsheet-management.md)
123

124
### Data Access & Manipulation
125

126
Comprehensive worksheet data operations including reading, writing, updating, and batch processing of cell values and ranges.
127

128
```python { .api }
129
class Worksheet:
130
    def get_all_values(value_render_option: str = "FORMATTED_VALUE") -> List[List]: ...
131
    def update(range_name: str = None, values: List[List] = None, value_input_option: str = "RAW") -> Dict: ...
132
    def batch_get(ranges: List[str], value_render_option: str = "FORMATTED_VALUE") -> List[List]: ...
133
    def find(query: str, in_row: int = None, in_column: int = None, case_sensitive: bool = True) -> Cell: ...
134
```
135

136
[Data Access & Manipulation](./data-access.md)
137

138
### Worksheet Structure
139

140
Worksheet structural modifications including adding/deleting rows and columns, resizing, freezing, and dimension grouping.
141

142
```python { .api }
143
class Worksheet:
144
    def add_rows(rows: int) -> None: ...
145
    def add_cols(cols: int) -> None: ...
146
    def delete_rows(start_index: int, end_index: int = None) -> Dict: ...
147
    def resize(rows: int = None, cols: int = None) -> Dict: ...
148
    def freeze(rows: int = None, cols: int = None) -> Dict: ...
149
```
150

151
[Worksheet Structure](./worksheet-structure.md)
152

153
### Formatting & Display
154

155
Cell and range formatting including merge operations, text formatting, colors, number formats, and conditional formatting.
156

157
```python { .api }
158
class Worksheet:
159
    def format(ranges: str, format: Dict) -> Dict: ...
160
    def merge_cells(name: str, merge_type: str = "MERGE_ALL") -> Dict: ...
161
    def update_tab_color(color: Dict) -> Dict: ...
162
    def hide_columns(start_index: int, end_index: int) -> Dict: ...
163
```
164

165
[Formatting & Display](./formatting.md)
166

167
### Utilities & Helpers
168

169
Coordinate conversion, range processing, data type conversion, and various utility functions for working with spreadsheet data.
170

171
```python { .api }
172
def a1_to_rowcol(label: str) -> Tuple[int, int]: ...
173
def rowcol_to_a1(row: int, col: int) -> str: ...
174
def numericise(value: str, default_blank: str = "", ignore: List[str] = None) -> Union[str, int, float]: ...
175
```
176

177
[Utilities & Helpers](./utilities.md)
178

179
## Types
180

181
```python { .api }
182
class Cell:
183
    def __init__(row: int, col: int, value: str = ""): ...
184
    @property
185
    def address -> str: ...
186
    @property
187
    def row -> int: ...
188
    @property
189
    def col -> int: ...
190
    @property
191
    def value -> str: ...
192

193
class ValueRange:
194
    def __init__(worksheet: Worksheet, name: str, values: List[List] = None): ...
195
    @property
196
    def values -> List[List]: ...
197
    def update(values: List[List] = None) -> Dict: ...
198
    def clear() -> Dict: ...
199
```
200

201
## Exceptions
202

203
```python { .api }
204
class GSpreadException(Exception): ...
205
class APIError(GSpreadException): ...
206
class SpreadsheetNotFound(GSpreadException): ...
207
class WorksheetNotFound(GSpreadException): ...
208
class IncorrectCellLabel(GSpreadException): ...
209
class NoValidUrlKeyFound(GSpreadException): ...
210
```