0
# Bucket Operations
1

2
The Bucket class provides a container abstraction for Google Cloud Storage buckets, simplifying operations on groups of related objects. Bucket instances are created through the Storage client and maintain a reference to the parent storage client for authentication and session management.
3

4
## Capabilities
5

6
### Bucket Initialization
7

8
Bucket instances are typically created through the Storage client's `get_bucket()` method rather than directly instantiated.
9

10
```python { .api }
11
def __init__(self, storage, name):
12
    """
13
    Initialize a Bucket instance.
14
    
15
    Parameters:
16
    - storage (Storage): Parent storage client instance
17
    - name (str): Bucket name
18
    
19
    Attributes:
20
    - storage (Storage): Reference to parent storage client
21
    - name (str): Bucket name
22
    """
23
```
24

25
**Usage Example:**
26
```python
27
async with Storage() as storage:
28
    # Get bucket instance
29
    bucket = storage.get_bucket('my-bucket')
30
    
31
    # Bucket properties
32
    print(f"Bucket name: {bucket.name}")
33
    print(f"Storage client: {bucket.storage}")
34
```
35

36
### Blob Discovery and Management
37

38
Operations for finding, checking existence of, and creating blob instances within the bucket.
39

40
```python { .api }
41
async def get_blob(self, blob_name, timeout=10, session=None):
42
    """
43
    Get a blob instance with metadata loaded.
44
    
45
    Parameters:
46
    - blob_name (str): Name/path of the blob
47
    - timeout (int): Request timeout in seconds
48
    - session (aiohttp.ClientSession, optional): Custom session
49
    
50
    Returns:
51
    Blob: Blob instance with loaded metadata
52
    """
53

54
async def blob_exists(self, blob_name, session=None):
55
    """
56
    Check if a blob exists in the bucket.
57
    
58
    Parameters:
59
    - blob_name (str): Name/path of the blob to check
60
    - session (aiohttp.ClientSession, optional): Custom session
61
    
62
    Returns:
63
    bool: True if blob exists, False otherwise
64
    """
65

66
def new_blob(self, blob_name):
67
    """
68
    Create a new blob instance without metadata.
69
    
70
    Parameters:
71
    - blob_name (str): Name/path for the new blob
72
    
73
    Returns:
74
    Blob: New blob instance (not yet uploaded)
75
    """
76
```
77

78
**Usage Example:**
79
```python
80
async with Storage() as storage:
81
    bucket = storage.get_bucket('my-bucket')
82
    
83
    # Check if blob exists
84
    if await bucket.blob_exists('data.json'):
85
        # Get existing blob with metadata
86
        blob = await bucket.get_blob('data.json')
87
        print(f"Blob size: {blob.size} bytes")
88
    else:
89
        # Create new blob instance
90
        blob = bucket.new_blob('data.json')
91
        # Upload data to the new blob
92
        await blob.upload(json_data, content_type='application/json')
93
```
94

95
### Blob Listing
96

97
List blobs within the bucket with filtering options using prefixes, glob patterns, and delimiters.
98

99
```python { .api }
100
async def list_blobs(self, prefix='', match_glob='', delimiter='', session=None):
101
    """
102
    List blob names in the bucket.
103
    
104
    Parameters:
105
    - prefix (str): Only return blobs whose names begin with this prefix
106
    - match_glob (str): Glob pattern to match blob names against
107
    - delimiter (str): Used to simulate a folder structure (e.g., '/')
108
    - session (aiohttp.ClientSession, optional): Custom session
109
    
110
    Returns:
111
    List[str]: List of blob names matching the criteria
112
    """
113
```
114

115
**Usage Example:**
116
```python
117
async with Storage() as storage:
118
    bucket = storage.get_bucket('my-bucket')
119
    
120
    # List all blobs
121
    all_blobs = await bucket.list_blobs()
122
    
123
    # List blobs with prefix (folder-like structure)
124
    log_files = await bucket.list_blobs(prefix='logs/')
125
    
126
    # List blobs matching glob pattern
127
    json_files = await bucket.list_blobs(match_glob='*.json')
128
    
129
    # List with delimiter for folder simulation
130
    top_level = await bucket.list_blobs(delimiter='/')
131
    
132
    # Combine filters
133
    recent_logs = await bucket.list_blobs(prefix='logs/2023/', match_glob='*.log')
134
```
135

136
### Bucket Metadata Operations
137

138
Retrieve metadata and configuration information for the bucket.
139

140
```python { .api }
141
async def get_metadata(self, params=None, session=None):
142
    """
143
    Get bucket metadata and configuration.
144
    
145
    Parameters:
146
    - params (dict, optional): Additional query parameters
147
    - session (aiohttp.ClientSession, optional): Custom session
148
    
149
    Returns:
150
    Dict[str, Any]: Bucket metadata including creation time, location, storage class, etc.
151
    """
152
```
153

154
**Usage Example:**
155
```python
156
async with Storage() as storage:
157
    bucket = storage.get_bucket('my-bucket')
158
    
159
    # Get bucket metadata
160
    metadata = await bucket.get_metadata()
161
    
162
    print(f"Bucket location: {metadata.get('location')}")
163
    print(f"Storage class: {metadata.get('storageClass')}")
164
    print(f"Created: {metadata.get('timeCreated')}")
165
    print(f"Versioning enabled: {metadata.get('versioning', {}).get('enabled', False)}")
166
```
167

168
## Common Usage Patterns
169

170
### Batch Operations on Multiple Blobs
171

172
```python
173
async with Storage() as storage:
174
    bucket = storage.get_bucket('my-bucket')
175
    
176
    # Get all JSON files and process them
177
    json_files = await bucket.list_blobs(match_glob='*.json')
178
    
179
    # Process each file
180
    for blob_name in json_files:
181
        blob = await bucket.get_blob(blob_name)
182
        content = await blob.download()
183
        # Process content
184
        
185
        # Update metadata after processing
186
        metadata = {'processed': 'true', 'processed_at': datetime.now().isoformat()}
187
        await storage.patch_metadata(bucket.name, blob_name, metadata)
188
```
189

190
### Folder-like Organization
191

192
```python
193
async with Storage() as storage:
194
    bucket = storage.get_bucket('my-data-bucket')
195
    
196
    # List top-level "folders"
197
    folders = await bucket.list_blobs(delimiter='/')
198
    
199
    # List files in a specific "folder"
200
    files_in_folder = await bucket.list_blobs(prefix='images/')
201
    
202
    # Create folder-like structure when uploading
203
    for i, image_data in enumerate(image_files):
204
        blob = bucket.new_blob(f'images/batch-{batch_id}/image-{i}.jpg')
205
        await blob.upload(image_data, content_type='image/jpeg')
206
```
207

208
### Existence Checking and Conditional Operations
209

210
```python
211
async with Storage() as storage:
212
    bucket = storage.get_bucket('my-bucket')
213
    
214
    # Check before creating to avoid overwriting
215
    blob_name = 'important-data.json'
216
    if not await bucket.blob_exists(blob_name):
217
        blob = bucket.new_blob(blob_name)
218
        await blob.upload(data, content_type='application/json')
219
        print("Data uploaded successfully")
220
    else:
221
        print("File already exists, skipping upload")
222
        
223
    # Or get existing and update
224
    if await bucket.blob_exists(blob_name):
225
        blob = await bucket.get_blob(blob_name)
226
        # Update existing blob
227
        await blob.upload(updated_data, content_type='application/json')
228
```