0
# Client Operations
1

2
The Client class provides the main interface for managing spreadsheets, handling file operations, permissions, and sharing.
3

4
## Capabilities
5

6
### Opening Spreadsheets
7

8
Access existing spreadsheets by title, key, or URL.
9

10
```python { .api }
11
class Client:
12
    def open(title: str) -> Spreadsheet:
13
        """
14
        Open spreadsheet by title.
15

16
        Parameters:
17
        - title (str): Exact spreadsheet title.
18

19
        Returns:
20
        Spreadsheet: Spreadsheet instance.
21

22
        Raises:
23
        SpreadsheetNotFound: If no spreadsheet with the given title is found.
24
        """
25

26
    def open_by_key(key: str) -> Spreadsheet:
27
        """
28
        Open spreadsheet by key (ID).
29

30
        Parameters:
31
        - key (str): Spreadsheet ID from URL.
32

33
        Returns:
34
        Spreadsheet: Spreadsheet instance.
35

36
        Raises:
37
        SpreadsheetNotFound: If spreadsheet with the given key is not found or not accessible.
38
        """
39

40
    def open_by_url(url: str) -> Spreadsheet:
41
        """
42
        Open spreadsheet by URL.
43

44
        Parameters:
45
        - url (str): Full Google Sheets URL.
46

47
        Returns:
48
        Spreadsheet: Spreadsheet instance.
49

50
        Raises:
51
        NoValidUrlKeyFound: If URL doesn't contain a valid spreadsheet ID.
52
        SpreadsheetNotFound: If spreadsheet is not found or not accessible.
53
        """
54

55
    def openall(title: str = None) -> List[Spreadsheet]:
56
        """
57
        Open all accessible spreadsheets, optionally filtered by title.
58

59
        Parameters:
60
        - title (str, optional): Filter by exact title. If None, returns all accessible spreadsheets.
61

62
        Returns:
63
        List[Spreadsheet]: List of spreadsheet instances.
64
        """
65
```
66

67
Usage examples:
68

69
```python
70
# Open by exact title
71
sheet = gc.open("My Spreadsheet")
72

73
# Open by ID (from URL: https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit)
74
sheet = gc.open_by_key("1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms")
75

76
# Open by full URL
77
sheet = gc.open_by_url("https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit#gid=0")
78

79
# Get all accessible spreadsheets
80
all_sheets = gc.openall()
81

82
# Get all spreadsheets with specific title
83
matching_sheets = gc.openall("My Spreadsheet")
84
```
85

86
### Creating and Managing Spreadsheets
87

88
Create new spreadsheets, copy existing ones, and delete spreadsheets.
89

90
```python { .api }
91
class Client:
92
    def create(title: str, folder_id: str = None) -> Spreadsheet:
93
        """
94
        Create new spreadsheet.
95

96
        Parameters:
97
        - title (str): Title for the new spreadsheet.
98
        - folder_id (str, optional): Google Drive folder ID to create spreadsheet in.
99

100
        Returns:
101
        Spreadsheet: Newly created spreadsheet instance.
102
        """
103

104
    def copy(file_id: str, title: str = None, copy_permissions: bool = False) -> Spreadsheet:
105
        """
106
        Copy existing spreadsheet.
107

108
        Parameters:
109
        - file_id (str): ID of spreadsheet to copy.
110
        - title (str, optional): Title for the copy. If None, uses "Copy of [original title]".
111
        - copy_permissions (bool): Whether to copy sharing permissions. Default: False.
112

113
        Returns:
114
        Spreadsheet: Copied spreadsheet instance.
115
        """
116

117
    def del_spreadsheet(file_id: str) -> None:
118
        """
119
        Delete spreadsheet.
120

121
        Parameters:
122
        - file_id (str): ID of spreadsheet to delete.
123

124
        Returns:
125
        None
126
        """
127
```
128

129
Usage examples:
130

131
```python
132
# Create new spreadsheet
133
new_sheet = gc.create("My New Spreadsheet")
134

135
# Create in specific folder
136
folder_sheet = gc.create("Project Data", folder_id="1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms")
137

138
# Copy spreadsheet
139
copied_sheet = gc.copy("original_spreadsheet_id", title="Copy of Original")
140

141
# Copy with permissions
142
copied_with_perms = gc.copy("original_spreadsheet_id", copy_permissions=True)
143

144
# Delete spreadsheet
145
gc.del_spreadsheet("spreadsheet_id_to_delete")
146
```
147

148
### Permission Management
149

150
Manage spreadsheet access permissions and sharing.
151

152
```python { .api }
153
class Client:
154
    def insert_permission(file_id: str, value: str, perm_type: str = "user", role: str = "reader",
155
                         notify: bool = True, email_message: str = None, with_link: bool = False) -> Dict:
156
        """
157
        Add permission to spreadsheet.
158

159
        Parameters:
160
        - file_id (str): Spreadsheet ID.
161
        - value (str): Email address, domain, or "anyone".
162
        - perm_type (str): Permission type ("user", "group", "domain", "anyone"). Default: "user".
163
        - role (str): Access role ("owner", "writer", "reader"). Default: "reader".
164
        - notify (bool): Whether to send notification email. Default: True.
165
        - email_message (str, optional): Custom message for notification email.
166
        - with_link (bool): Whether to grant access via link. Default: False.
167

168
        Returns:
169
        Dict: Permission details.
170
        """
171

172
    def list_permissions(file_id: str) -> List[Dict]:
173
        """
174
        List all permissions for spreadsheet.
175

176
        Parameters:
177
        - file_id (str): Spreadsheet ID.
178

179
        Returns:
180
        List[Dict]: List of permission details.
181
        """
182

183
    def remove_permission(file_id: str, permission_id: str) -> None:
184
        """
185
        Remove permission from spreadsheet.
186

187
        Parameters:
188
        - file_id (str): Spreadsheet ID.
189
        - permission_id (str): Permission ID to remove.
190

191
        Returns:
192
        None
193
        """
194
```
195

196
Usage examples:
197

198
```python
199
# Grant read access to user
200
gc.insert_permission("spreadsheet_id", "user@example.com", role="reader")
201

202
# Grant write access without notification
203
gc.insert_permission("spreadsheet_id", "editor@example.com", role="writer", notify=False)
204

205
# Grant access to anyone with link
206
gc.insert_permission("spreadsheet_id", "anyone", perm_type="anyone", role="reader", with_link=True)
207

208
# List all permissions
209
permissions = gc.list_permissions("spreadsheet_id")
210
for perm in permissions:
211
    print(f"Email: {perm.get('emailAddress')}, Role: {perm.get('role')}")
212

213
# Remove permission
214
gc.remove_permission("spreadsheet_id", "permission_id")
215
```
216

217
### Import and Export Operations
218

219
Import CSV data and export spreadsheets in various formats.
220

221
```python { .api }
222
class Client:
223
    def import_csv(file_id: str, data: str) -> None:
224
        """
225
        Import CSV data into spreadsheet.
226

227
        Parameters:
228
        - file_id (str): Spreadsheet ID.
229
        - data (str): CSV data as string.
230

231
        Returns:
232
        None
233
        """
234

235
    def export(file_id: str, format: str = "pdf") -> bytes:
236
        """
237
        Export spreadsheet in specified format.
238

239
        Parameters:
240
        - file_id (str): Spreadsheet ID.
241
        - format (str): Export format ("pdf", "xlsx", "ods", "csv", "tsv", "zip"). Default: "pdf".
242

243
        Returns:
244
        bytes: Exported file content.
245
        """
246
```
247

248
Usage examples:
249

250
```python
251
# Import CSV data
252
csv_data = "Name,Age,City\nAlice,25,New York\nBob,30,San Francisco"
253
gc.import_csv("spreadsheet_id", csv_data)
254

255
# Export as PDF
256
pdf_content = gc.export("spreadsheet_id", format="pdf")
257
with open("spreadsheet.pdf", "wb") as f:
258
    f.write(pdf_content)
259

260
# Export as Excel
261
xlsx_content = gc.export("spreadsheet_id", format="xlsx")
262
with open("spreadsheet.xlsx", "wb") as f:
263
    f.write(xlsx_content)
264
```
265

266
### Timeout Configuration
267

268
Configure HTTP request timeouts for all API calls.
269

270
```python { .api }
271
class Client:
272
    def set_timeout(timeout: Optional[Union[float, Tuple[float, float]]] = None) -> None:
273
        """
274
        Set HTTP request timeout.
275

276
        Parameters:
277
        - timeout (Optional[Union[float, Tuple[float, float]]]): Timeout in seconds as float, or (connect_timeout, read_timeout) tuple. None restores default.
278

279
        Returns:
280
        None
281
        """
282
```
283

284
### Client Properties
285

286
```python { .api }
287
class Client:
288
    @property
289
    def auth:
290
        """Authentication credentials object."""
291

292
    @property
293
    def http_client -> HTTPClient:
294
        """HTTP client instance used for API requests."""
295
```