0
# Spreadsheet Management
1

2
The Spreadsheet class provides methods for managing worksheets, metadata, batch operations, and spreadsheet-level sharing controls.
3

4
## Capabilities
5

6
### Worksheet Management
7

8
Create, access, and manage worksheets within a spreadsheet.
9

10
```python { .api }
11
class Spreadsheet:
12
    def add_worksheet(title: str, rows: int = 100, cols: int = 26, index: int = None) -> Worksheet:
13
        """
14
        Add new worksheet to spreadsheet.
15

16
        Parameters:
17
        - title (str): Title for the new worksheet.
18
        - rows (int): Initial number of rows. Default: 100.
19
        - cols (int): Initial number of columns. Default: 26.
20
        - index (int, optional): Position to insert worksheet. If None, adds at end.
21

22
        Returns:
23
        Worksheet: Newly created worksheet instance.
24
        """
25

26
    def del_worksheet(worksheet: Worksheet) -> None:
27
        """
28
        Delete worksheet from spreadsheet.
29

30
        Parameters:
31
        - worksheet (Worksheet): Worksheet instance to delete.
32

33
        Returns:
34
        None
35
        """
36

37
    def del_worksheet_by_id(worksheet_id: Union[str, int]) -> Any:
38
        """
39
        Delete worksheet by ID.
40

41
        Parameters:
42
        - worksheet_id (Union[str, int]): The ID of the worksheet to delete.
43

44
        Returns:
45
        Any: The deletion response.
46
        """
47

48
    def worksheet(title: str) -> Worksheet:
49
        """
50
        Get worksheet by title.
51

52
        Parameters:
53
        - title (str): Exact worksheet title.
54

55
        Returns:
56
        Worksheet: Worksheet instance.
57

58
        Raises:
59
        WorksheetNotFound: If no worksheet with the given title exists.
60
        """
61

62
    def get_worksheet(index: int) -> Worksheet:
63
        """
64
        Get worksheet by index (0-based).
65

66
        Parameters:
67
        - index (int): Worksheet index.
68

69
        Returns:
70
        Worksheet: Worksheet instance.
71

72
        Raises:
73
        WorksheetNotFound: If index is out of range.
74
        """
75

76
    def get_worksheet_by_id(id: int) -> Worksheet:
77
        """
78
        Get worksheet by ID.
79

80
        Parameters:
81
        - id (int): Worksheet ID.
82

83
        Returns:
84
        Worksheet: Worksheet instance.
85

86
        Raises:
87
        WorksheetNotFound: If no worksheet with the given ID exists.
88
        """
89

90
    def duplicate_sheet(source_sheet_id: int, insert_sheet_index: int = None,
91
                       new_sheet_id: int = None, new_sheet_name: str = None) -> Worksheet:
92
        """
93
        Duplicate existing worksheet.
94

95
        Parameters:
96
        - source_sheet_id (int): ID of worksheet to duplicate.
97
        - insert_sheet_index (int, optional): Position to insert duplicated sheet.
98
        - new_sheet_id (int, optional): ID for new sheet.
99
        - new_sheet_name (str, optional): Name for new sheet. If None, uses "Copy of [original name]".
100

101
        Returns:
102
        Worksheet: Duplicated worksheet instance.
103
        """
104

105
    def reorder_worksheets(worksheets_in_desired_order: List[Worksheet]) -> None:
106
        """
107
        Reorder worksheets.
108

109
        Parameters:
110
        - worksheets_in_desired_order (List[Worksheet]): List of worksheets in desired order.
111

112
        Returns:
113
        None
114
        """
115
```
116

117
### Batch Operations
118

119
Perform bulk operations for improved performance.
120

121
```python { .api }
122
class Spreadsheet:
123
    def batch_update(body: Dict) -> Dict:
124
        """
125
        Execute batch update request.
126

127
        Parameters:
128
        - body (Dict): Batch update request body following Google Sheets API format.
129

130
        Returns:
131
        Dict: Response from batch update operation.
132
        """
133

134
    def values_batch_get(ranges: List[str], major_dimension: str = "ROWS",
135
                        value_render_option: str = "FORMATTED_VALUE",
136
                        date_time_render_option: str = "SERIAL_NUMBER") -> Dict:
137
        """
138
        Get multiple ranges in single request.
139

140
        Parameters:
141
        - ranges (List[str]): List of A1 notation ranges.
142
        - major_dimension (str): "ROWS" or "COLUMNS". Default: "ROWS".
143
        - value_render_option (str): How values should be represented. Default: "FORMATTED_VALUE".
144
        - date_time_render_option (str): How dates/times should be represented. Default: "SERIAL_NUMBER".
145

146
        Returns:
147
        Dict: Response containing values for all requested ranges.
148
        """
149

150
    def values_batch_update(body: Dict) -> Dict:
151
        """
152
        Update multiple ranges in single request.
153

154
        Parameters:
155
        - body (Dict): Batch update values request body.
156

157
        Returns:
158
        Dict: Response from batch update operation.
159
        """
160

161
    def batch_clear(ranges: List[str]) -> Dict:
162
        """
163
        Clear multiple ranges in single request.
164

165
        Parameters:
166
        - ranges (List[str]): List of A1 notation ranges to clear.
167

168
        Returns:
169
        Dict: Response from clear operation.
170
        """
171
```
172

173
### Sharing and Permissions
174

175
Manage spreadsheet sharing and access permissions.
176

177
```python { .api }
178
class Spreadsheet:
179
    def share(value: str, perm_type: str = "user", role: str = "reader",
180
              notify: bool = True, email_message: str = None, with_link: bool = False) -> Dict:
181
        """
182
        Share spreadsheet with user, group, or make public.
183

184
        Parameters:
185
        - value (str): Email address, domain, or "anyone".
186
        - perm_type (str): "user", "group", "domain", or "anyone". Default: "user".
187
        - role (str): "owner", "writer", or "reader". Default: "reader".
188
        - notify (bool): Send notification email. Default: True.
189
        - email_message (str, optional): Custom notification message.
190
        - with_link (bool): Grant access via link sharing. Default: False.
191

192
        Returns:
193
        Dict: Permission details.
194
        """
195

196
    def list_permissions() -> List[Dict]:
197
        """
198
        List all permissions for this spreadsheet.
199

200
        Returns:
201
        List[Dict]: List of permission details.
202
        """
203

204
    def remove_permissions(permission_id: str) -> None:
205
        """
206
        Remove permission by ID.
207

208
        Parameters:
209
        - permission_id (str): Permission ID to remove.
210

211
        Returns:
212
        None
213
        """
214

215
    def transfer_ownership(permission_id: str) -> Dict:
216
        """
217
        Transfer ownership to another user.
218

219
        Parameters:
220
        - permission_id (str): Permission ID of the new owner.
221

222
        Returns:
223
        Dict: Updated permission details.
224
        """
225
```
226

227
### Values Operations
228

229
Direct spreadsheet-level value operations that work across ranges.
230

231
```python { .api }
232
class Spreadsheet:
233
    def values_get(range_name: str, major_dimension: str = "ROWS",
234
                   value_render_option: str = "FORMATTED_VALUE",
235
                   date_time_render_option: str = "SERIAL_NUMBER") -> Dict:
236
        """
237
        Get values from specified range.
238

239
        Parameters:
240
        - range_name (str): A1 notation range.
241
        - major_dimension (str): "ROWS" or "COLUMNS". Default: "ROWS".
242
        - value_render_option (str): Value rendering option. Default: "FORMATTED_VALUE".
243
        - date_time_render_option (str): Date/time rendering option. Default: "SERIAL_NUMBER".
244

245
        Returns:
246
        Dict: Response containing range values.
247
        """
248

249
    def values_update(range_name: str, values: List[List], value_input_option: str = "RAW") -> Dict:
250
        """
251
        Update values in specified range.
252

253
        Parameters:
254
        - range_name (str): A1 notation range.
255
        - values (List[List]): 2D array of values to update.
256
        - value_input_option (str): "RAW" or "USER_ENTERED". Default: "RAW".
257

258
        Returns:
259
        Dict: Response from update operation.
260
        """
261

262
    def values_append(range_name: str, values: List[List], value_input_option: str = "RAW",
263
                     insert_data_option: str = "OVERWRITE", include_values_in_response: bool = False) -> Dict:
264
        """
265
        Append values to range.
266

267
        Parameters:
268
        - range_name (str): A1 notation range.
269
        - values (List[List]): 2D array of values to append.
270
        - value_input_option (str): "RAW" or "USER_ENTERED". Default: "RAW".
271
        - insert_data_option (str): "OVERWRITE" or "INSERT_ROWS". Default: "OVERWRITE".
272
        - include_values_in_response (bool): Include updated values in response. Default: False.
273

274
        Returns:
275
        Dict: Response from append operation.
276
        """
277

278
    def values_clear(range_name: str) -> Dict:
279
        """
280
        Clear values in specified range.
281

282
        Parameters:
283
        - range_name (str): A1 notation range to clear.
284

285
        Returns:
286
        Dict: Response from clear operation.
287
        """
288
```
289

290
### Export Operations
291

292
Export spreadsheet content in various formats.
293

294
```python { .api }
295
class Spreadsheet:
296
    def export(format: str = "pdf") -> bytes:
297
        """
298
        Export entire spreadsheet.
299

300
        Parameters:
301
        - format (str): Export format ("pdf", "xlsx", "ods", "csv", "tsv", "zip"). Default: "pdf".
302

303
        Returns:
304
        bytes: Exported file content.
305
        """
306
```
307

308
### Spreadsheet Properties
309

310
```python { .api }
311
class Spreadsheet:
312
    @property
313
    def id -> str:
314
        """Spreadsheet ID."""
315

316
    @property
317
    def title -> str:
318
        """Spreadsheet title."""
319

320
    @property
321
    def url -> str:
322
        """Spreadsheet URL."""
323

324
    @property
325
    def creationTime -> str:
326
        """Creation timestamp."""
327

328
    @property
329
    def lastUpdateTime -> str:
330
        """Last update timestamp."""
331

332
    @property
333
    def locale -> str:
334
        """Spreadsheet locale setting."""
335

336
    @property
337
    def timezone -> str:
338
        """Spreadsheet timezone setting."""
339

340
    @property
341
    def sheet1 -> Worksheet:
342
        """First worksheet (convenience property)."""
343

344
    @property
345
    def worksheets_property -> List[Dict]:
346
        """List of worksheet metadata dictionaries."""
347
```
348

349
### Named Range Management
350

351
Create and manage named ranges within the spreadsheet.
352

353
```python { .api }
354
class Spreadsheet:
355
    def define_named_range(name: str, range_name: str) -> Dict:
356
        """
357
        Define a named range in the spreadsheet.
358

359
        Parameters:
360
        - name (str): A string with range value in A1 notation, e.g. 'A1:A5'.
361
        - range_name (str): The name to assign to the range of cells.
362

363
        Returns:
364
        Dict: The response body from the request.
365
        """
366

367
    def delete_named_range(named_range_id: str) -> Dict:
368
        """
369
        Delete a named range by its ID.
370

371
        Parameters:
372
        - named_range_id (str): The ID of the named range to delete. Can be obtained with list_named_ranges().
373

374
        Returns:
375
        Dict: The response body from the request.
376
        """
377
```
378

379
Usage examples:
380

381
```python
382
# Access spreadsheet
383
sheet = gc.open("My Spreadsheet")
384

385
# Create new worksheet
386
worksheet = sheet.add_worksheet("New Sheet", rows=50, cols=10)
387

388
# Get worksheet by name
389
ws = sheet.worksheet("Sheet1")
390

391
# Batch operations
392
batch_result = sheet.values_batch_get(['A1:B10', 'D1:F5'])
393

394
# Share spreadsheet
395
sheet.share('user@example.com', role='writer')
396

397
# Export as Excel
398
xlsx_data = sheet.export('xlsx')
399
```