0
# Storage Client
1

2
The Storage class is the main entry point for interacting with Google Cloud Storage. It handles authentication, session management, and provides direct access to all storage operations including bucket management, object manipulation, and metadata operations.
3

4
## Capabilities
5

6
### Client Initialization
7

8
Create a Storage client with optional authentication and configuration parameters.
9

10
```python { .api }
11
def __init__(self, *, service_file=None, token=None, session=None, api_root=None):
12
    """
13
    Initialize Storage client.
14
    
15
    Parameters:
16
    - service_file (str, optional): Path to service account JSON file
17
    - token (Token, optional): Pre-configured authentication token
18
    - session (aiohttp.ClientSession, optional): Custom HTTP session
19
    - api_root (str, optional): Custom API root URL for testing/emulators
20
    """
21
```
22

23
**Usage Example:**
24
```python
25
# Default initialization (uses Application Default Credentials)
26
storage = Storage()
27

28
# With service account file
29
storage = Storage(service_file='/path/to/service-account.json')
30

31
# For testing with emulator
32
storage = Storage(api_root='http://localhost:8080')
33
```
34

35
### Context Manager Support
36

37
The Storage client supports async context manager protocol for automatic session cleanup.
38

39
```python { .api }
40
async def __aenter__(self):
41
    """Enter async context manager, returns self."""
42

43
async def __aexit__(self, *args):
44
    """Exit async context manager, closes session."""
45
    
46
async def close(self):
47
    """Manually close the session."""
48
```
49

50
**Usage Example:**
51
```python
52
# Recommended: automatic cleanup
53
async with Storage() as storage:
54
    # Use storage client
55
    pass
56

57
# Manual cleanup when needed
58
storage = Storage()
59
try:
60
    # Use storage client
61
    pass
62
finally:
63
    await storage.close()
64
```
65

66
### Bucket Management
67

68
Operations for listing and managing buckets at the project level.
69

70
```python { .api }
71
async def list_buckets(self, project, *, params=None, headers=None, session=None, timeout=10):
72
    """
73
    List all buckets in a project.
74
    
75
    Parameters:
76
    - project (str): Google Cloud project ID
77
    - params (dict, optional): Additional query parameters
78
    - headers (dict, optional): Custom HTTP headers
79
    - session (aiohttp.ClientSession, optional): Custom session
80
    - timeout (int): Request timeout in seconds
81
    
82
    Returns:
83
    List[Bucket]: List of bucket instances
84
    """
85

86
def get_bucket(self, bucket_name):
87
    """
88
    Get a bucket instance for operations.
89
    
90
    Parameters:
91
    - bucket_name (str): Name of the bucket
92
    
93
    Returns:
94
    Bucket: Bucket instance for further operations
95
    """
96

97
async def get_bucket_metadata(self, bucket, *, params=None, headers=None, session=None, timeout=10):
98
    """
99
    Get metadata for a specific bucket.
100
    
101
    Parameters:
102
    - bucket (str): Bucket name
103
    - params (dict, optional): Additional query parameters
104
    - headers (dict, optional): Custom HTTP headers  
105
    - session (aiohttp.ClientSession, optional): Custom session
106
    - timeout (int): Request timeout in seconds
107
    
108
    Returns:
109
    Dict[str, Any]: Bucket metadata
110
    """
111
```
112

113
**Usage Example:**
114
```python
115
async with Storage() as storage:
116
    # List all buckets in project
117
    buckets = await storage.list_buckets('my-project-id')
118
    
119
    # Get bucket instance
120
    bucket = storage.get_bucket('my-bucket')
121
    
122
    # Get bucket metadata
123
    metadata = await storage.get_bucket_metadata('my-bucket')
124
```
125

126
### Object Download Operations
127

128
Download objects from Cloud Storage with various options for streaming, metadata-only retrieval, and file output.
129

130
```python { .api }
131
async def download(self, bucket, object_name, *, headers=None, timeout=10, session=None):
132
    """
133
    Download object content as bytes.
134
    
135
    Parameters:
136
    - bucket (str): Bucket name
137
    - object_name (str): Object name/path
138
    - headers (dict, optional): Custom HTTP headers for range requests, etc.
139
    - timeout (int): Request timeout in seconds
140
    - session (aiohttp.ClientSession, optional): Custom session
141
    
142
    Returns:
143
    bytes: Object content
144
    """
145

146
async def download_to_filename(self, bucket, object_name, filename, **kwargs):
147
    """
148
    Download object directly to a local file.
149
    
150
    Parameters:
151
    - bucket (str): Bucket name
152
    - object_name (str): Object name/path
153
    - filename (str): Local file path to write to
154
    - **kwargs: Additional arguments passed to download()
155
    
156
    Returns:
157
    None
158
    """
159

160
async def download_metadata(self, bucket, object_name, *, headers=None, session=None, timeout=10):
161
    """
162
    Get object metadata without downloading content.
163
    
164
    Parameters:
165
    - bucket (str): Bucket name
166
    - object_name (str): Object name/path
167
    - headers (dict, optional): Custom HTTP headers
168
    - session (aiohttp.ClientSession, optional): Custom session
169
    - timeout (int): Request timeout in seconds
170
    
171
    Returns:
172
    Dict[str, Any]: Object metadata
173
    """
174

175
async def download_stream(self, bucket, object_name, *, headers=None, timeout=10, session=None):
176
    """
177
    Download object as a stream for large files.
178
    
179
    Parameters:
180
    - bucket (str): Bucket name
181
    - object_name (str): Object name/path
182
    - headers (dict, optional): Custom HTTP headers for range requests
183
    - timeout (int): Request timeout in seconds
184
    - session (aiohttp.ClientSession, optional): Custom session
185
    
186
    Returns:
187
    StreamResponse: Async stream for reading content
188
    """
189
```
190

191
**Usage Example:**
192
```python
193
async with Storage() as storage:
194
    # Download entire file
195
    content = await storage.download('my-bucket', 'file.txt')
196
    
197
    # Download to local file
198
    await storage.download_to_filename('my-bucket', 'large-file.zip', '/tmp/download.zip')
199
    
200
    # Get metadata only
201
    metadata = await storage.download_metadata('my-bucket', 'file.txt')
202
    print(f"File size: {metadata['size']} bytes")
203
    
204
    # Stream large file
205
    async with storage.download_stream('my-bucket', 'huge-file.dat') as stream:
206
        while True:
207
            chunk = await stream.read(8192)
208
            if not chunk:
209
                break
210
            # Process chunk
211
```
212

213
### Object Upload Operations
214

215
Upload objects to Cloud Storage with support for different upload methods, compression, and metadata.
216

217
```python { .api }
218
async def upload(self, bucket, object_name, file_data, *, content_type=None, parameters=None, headers=None, metadata=None, session=None, force_resumable_upload=None, zipped=False, timeout=30):
219
    """
220
    Upload data to an object.
221
    
222
    Parameters:
223
    - bucket (str): Bucket name
224
    - object_name (str): Object name/path
225
    - file_data (bytes or file-like): Data to upload
226
    - content_type (str, optional): MIME type of the content
227
    - parameters (dict, optional): Additional upload parameters
228
    - headers (dict, optional): Custom HTTP headers
229
    - metadata (dict, optional): Object metadata key-value pairs
230
    - session (aiohttp.ClientSession, optional): Custom session
231
    - force_resumable_upload (bool, optional): Force resumable upload method
232
    - zipped (bool): Whether to gzip compress the data
233
    - timeout (int): Request timeout in seconds
234
    
235
    Returns:
236
    Dict[str, Any]: Upload response metadata
237
    """
238

239
async def upload_from_filename(self, bucket, object_name, filename, **kwargs):
240
    """
241
    Upload a local file to an object.
242
    
243
    Parameters:
244
    - bucket (str): Bucket name
245
    - object_name (str): Object name/path
246
    - filename (str): Local file path to upload
247
    - **kwargs: Additional arguments passed to upload()
248
    
249
    Returns:
250
    Dict[str, Any]: Upload response metadata
251
    """
252
```
253

254
**Usage Example:**
255
```python
256
async with Storage() as storage:
257
    # Upload bytes data
258
    data = b"Hello, Cloud Storage!"
259
    result = await storage.upload('my-bucket', 'greeting.txt', data, 
260
                                  content_type='text/plain')
261
    
262
    # Upload with metadata
263
    metadata = {'author': 'user', 'version': '1.0'}
264
    result = await storage.upload('my-bucket', 'data.json', json_data,
265
                                  content_type='application/json',
266
                                  metadata=metadata)
267
    
268
    # Upload from local file
269
    result = await storage.upload_from_filename('my-bucket', 'backup.zip', 
270
                                                '/path/to/backup.zip')
271
    
272
    # Upload with compression
273
    result = await storage.upload('my-bucket', 'large-text.txt', text_data,
274
                                  zipped=True, content_type='text/plain')
275
```
276

277
### Object Management Operations
278

279
Additional operations for managing objects including copying, deleting, listing, and metadata updates.
280

281
```python { .api }
282
async def copy(self, bucket, object_name, destination_bucket, *, new_name=None, metadata=None, params=None, headers=None, timeout=10, session=None):
283
    """
284
    Copy an object to another location.
285
    
286
    Parameters:
287
    - bucket (str): Source bucket name
288
    - object_name (str): Source object name/path
289
    - destination_bucket (str): Destination bucket name
290
    - new_name (str, optional): New object name, defaults to original name
291
    - metadata (dict, optional): New metadata for copied object
292
    - params (dict, optional): Additional query parameters
293
    - headers (dict, optional): Custom HTTP headers
294
    - timeout (int): Request timeout in seconds
295
    - session (aiohttp.ClientSession, optional): Custom session
296
    
297
    Returns:
298
    Dict[str, Any]: Copy operation response
299
    """
300

301
async def delete(self, bucket, object_name, *, timeout=10, params=None, headers=None, session=None):
302
    """
303
    Delete an object.
304
    
305
    Parameters:
306
    - bucket (str): Bucket name
307
    - object_name (str): Object name/path
308
    - timeout (int): Request timeout in seconds
309
    - params (dict, optional): Additional query parameters
310
    - headers (dict, optional): Custom HTTP headers
311
    - session (aiohttp.ClientSession, optional): Custom session
312
    
313
    Returns:
314
    str: Deletion response
315
    """
316

317
async def list_objects(self, bucket, *, params=None, headers=None, session=None, timeout=10):
318
    """
319
    List objects in a bucket.
320
    
321
    Parameters:
322
    - bucket (str): Bucket name
323
    - params (dict, optional): Query parameters (prefix, delimiter, maxResults, etc.)
324
    - headers (dict, optional): Custom HTTP headers
325
    - session (aiohttp.ClientSession, optional): Custom session
326
    - timeout (int): Request timeout in seconds
327
    
328
    Returns:
329
    Dict[str, Any]: List response with objects and metadata
330
    """
331

332
async def patch_metadata(self, bucket, object_name, metadata, *, params=None, headers=None, session=None, timeout=10):
333
    """
334
    Update object metadata.
335
    
336
    Parameters:
337
    - bucket (str): Bucket name
338
    - object_name (str): Object name/path
339
    - metadata (dict): Metadata key-value pairs to update
340
    - params (dict, optional): Additional query parameters
341
    - headers (dict, optional): Custom HTTP headers
342
    - session (aiohttp.ClientSession, optional): Custom session
343
    - timeout (int): Request timeout in seconds
344
    
345
    Returns:
346
    Dict[str, Any]: Updated object metadata
347
    """
348

349
async def compose(self, bucket, object_name, source_object_names, *, content_type=None, params=None, headers=None, session=None, timeout=10):
350
    """
351
    Compose multiple objects into a single object.
352
    
353
    Parameters:
354
    - bucket (str): Bucket name
355
    - object_name (str): Name for the composed object
356
    - source_object_names (List[str]): List of source object names to compose
357
    - content_type (str, optional): MIME type for composed object
358
    - params (dict, optional): Additional query parameters
359
    - headers (dict, optional): Custom HTTP headers
360
    - session (aiohttp.ClientSession, optional): Custom session
361
    - timeout (int): Request timeout in seconds
362
    
363
    Returns:
364
    Dict[str, Any]: Compose operation response
365
    """
366
```
367

368
**Usage Example:**
369
```python
370
async with Storage() as storage:
371
    # Copy object to another bucket
372
    await storage.copy('source-bucket', 'file.txt', 'dest-bucket', 
373
                       new_name='copied-file.txt')
374
    
375
    # Delete object
376
    await storage.delete('my-bucket', 'old-file.txt')
377
    
378
    # List objects with prefix
379
    params = {'prefix': 'logs/', 'maxResults': 100}
380
    result = await storage.list_objects('my-bucket', params=params)
381
    
382
    # Update metadata
383
    metadata = {'status': 'processed', 'last_modified': '2023-01-01'}
384
    await storage.patch_metadata('my-bucket', 'data.json', metadata)
385
    
386
    # Compose multiple objects
387
    parts = ['part1.txt', 'part2.txt', 'part3.txt']
388
    await storage.compose('my-bucket', 'combined.txt', parts,
389
                          content_type='text/plain')
390
```