0
# Configuration and Session Management
1
2
Authentication, configuration, and session management for Quilt catalogs and AWS services. Handles login/logout, credentials, and configuration settings.
3
4
## Capabilities
5
6
### Configuration Management
7
8
Configure Quilt3 to work with catalogs and set configuration options.
9
10
```python { .api }
11
def config(*catalog_url, **config_values):
12
"""
13
Set or read the QUILT configuration.
14
15
Parameters:
16
- catalog_url: A single URL indicating a location to configure from
17
- **config_values: Key=value pairs to set in the config
18
19
Returns:
20
QuiltConfig: An ordered mapping of configuration values
21
22
Usage:
23
- config() - retrieve current config
24
- config('https://your-catalog-url.com') - autoconfigure from URL
25
- config(navigator_url='http://example.com') - set specific values
26
27
Raises:
28
QuiltException: If both catalog_url and config_values are provided
29
"""
30
```
31
32
### Authentication
33
34
Authenticate with Quilt catalogs and manage login state.
35
36
```python { .api }
37
def login():
38
"""
39
Authenticate to your Quilt stack and assume the role assigned to you by
40
your stack administrator. Not required if you have existing AWS credentials.
41
42
Launches a web browser and asks the user for a token.
43
44
Raises:
45
QuiltException: If no registry URL is configured
46
"""
47
48
def logout():
49
"""
50
Do not use Quilt credentials. Useful if you have existing AWS credentials.
51
52
Clears saved authentication tokens and resets session.
53
"""
54
55
def logged_in() -> str:
56
"""
57
Return catalog URL if Quilt client is authenticated. Otherwise return None.
58
59
Returns:
60
String: Navigator URL if authenticated, None otherwise
61
"""
62
```
63
64
### Session and Credentials Management
65
66
Manage boto3 sessions and AWS credentials integration.
67
68
```python { .api }
69
def get_boto3_session(*, fallback: bool = True):
70
"""
71
Return a Boto3 session with Quilt stack credentials and AWS region.
72
73
Parameters:
74
- fallback: Return normal Boto3 session if no Quilt credentials found
75
76
Returns:
77
boto3.Session: Session with Quilt credentials and region configuration
78
79
Raises:
80
QuiltException: If no Quilt credentials found and fallback=False
81
82
Note:
83
You need to call quilt3.config("https://your-catalog-homepage/") to have
84
region set on the session, if you previously called it in quilt3 < 6.1.0.
85
"""
86
```
87
88
### Telemetry Control
89
90
Control anonymous usage metrics collection.
91
92
```python { .api }
93
def disable_telemetry():
94
"""
95
Permanently disable sending of anonymous usage metrics.
96
97
This setting persists across sessions and package reinstalls.
98
"""
99
```
100
101
## Configuration Types
102
103
### QuiltConfig
104
105
```python { .api }
106
class QuiltConfig:
107
"""
108
Configuration object providing access to Quilt settings.
109
110
Behaves like an ordered dictionary with configuration keys and values.
111
Common configuration keys include:
112
- navigator_url: URL of the Quilt catalog interface
113
- registryUrl: URL of the Quilt registry backend
114
- region: AWS region for S3 operations
115
- telemetry_disabled: Whether telemetry is disabled
116
"""
117
```
118
119
## Usage Examples
120
121
### Basic Configuration
122
123
```python
124
import quilt3
125
126
# View current configuration
127
current_config = quilt3.config()
128
print("Current configuration:")
129
for key, value in current_config.items():
130
print(f" {key}: {value}")
131
132
# Configure from catalog URL (autoconfiguration)
133
quilt3.config('https://your-catalog.quiltdata.com')
134
135
# Set specific configuration values
136
quilt3.config(
137
navigator_url='https://your-catalog.quiltdata.com',
138
region='us-east-1'
139
)
140
141
# Mixed configuration example
142
quilt3.config(
143
navigator_url='https://catalog.company.com',
144
telemetry_disabled=True
145
)
146
```
147
148
### Authentication Workflow
149
150
```python
151
import quilt3
152
153
# Check if already logged in
154
if quilt3.logged_in():
155
print(f"Already logged in to: {quilt3.logged_in()}")
156
else:
157
print("Not currently logged in")
158
159
# Login to Quilt catalog
160
quilt3.login() # Opens browser for authentication
161
162
# Verify login successful
163
if quilt3.logged_in():
164
print(f"Successfully logged in to: {quilt3.logged_in()}")
165
166
# Logout when done
167
quilt3.logout()
168
print("Logged out successfully")
169
```
170
171
### Session Management
172
173
```python
174
import quilt3
175
176
# Get Boto3 session with Quilt credentials
177
session = quilt3.get_boto3_session()
178
179
# Use session for AWS operations
180
s3_client = session.client('s3')
181
response = s3_client.list_buckets()
182
print(f"Found {len(response['Buckets'])} buckets")
183
184
# Get session with fallback disabled
185
try:
186
session = quilt3.get_boto3_session(fallback=False)
187
print("Using Quilt credentials")
188
except quilt3.QuiltException:
189
print("No Quilt credentials available")
190
191
# Use session for other AWS services
192
ec2_client = session.client('ec2')
193
instances = ec2_client.describe_instances()
194
```
195
196
### Advanced Configuration
197
198
```python
199
import quilt3
200
201
# Configure for multiple environments
202
def configure_for_environment(env):
203
if env == 'development':
204
quilt3.config(
205
navigator_url='https://dev-catalog.company.com',
206
registryUrl='https://dev-registry.company.com',
207
region='us-west-2'
208
)
209
elif env == 'production':
210
quilt3.config(
211
navigator_url='https://catalog.company.com',
212
registryUrl='https://registry.company.com',
213
region='us-east-1'
214
)
215
216
# Use environment-specific configuration
217
configure_for_environment('production')
218
219
# Verify configuration
220
config = quilt3.config()
221
print(f"Environment: {config.get('navigator_url')}")
222
print(f"Region: {config.get('region')}")
223
```
224
225
### Telemetry Management
226
227
```python
228
import quilt3
229
230
# Check current telemetry status
231
config = quilt3.config()
232
if config.get('telemetry_disabled'):
233
print("Telemetry is disabled")
234
else:
235
print("Telemetry is enabled")
236
237
# Disable telemetry
238
quilt3.disable_telemetry()
239
print("Telemetry disabled")
240
241
# Verify telemetry is disabled
242
config = quilt3.config()
243
assert config.get('telemetry_disabled') == True
244
```
245
246
### Configuration Validation
247
248
```python
249
import quilt3
250
251
def validate_configuration():
252
"""Validate that Quilt is properly configured"""
253
config = quilt3.config()
254
255
required_keys = ['navigator_url', 'registryUrl']
256
missing_keys = [key for key in required_keys if not config.get(key)]
257
258
if missing_keys:
259
print(f"Missing configuration: {missing_keys}")
260
return False
261
262
# Test authentication
263
if not quilt3.logged_in():
264
print("Warning: Not authenticated")
265
return False
266
267
# Test session
268
try:
269
session = quilt3.get_boto3_session(fallback=False)
270
print("Configuration valid - Quilt credentials available")
271
return True
272
except quilt3.QuiltException:
273
print("Warning: No Quilt credentials available")
274
return False
275
276
# Run validation
277
if validate_configuration():
278
print("Ready to use Quilt3")
279
else:
280
print("Configuration needs attention")
281
```
282
283
### Error Handling
284
285
```python
286
import quilt3
287
288
try:
289
# Attempt to configure with invalid URL
290
quilt3.config('not-a-valid-url')
291
except quilt3.QuiltException as e:
292
print(f"Configuration error: {e}")
293
294
try:
295
# Attempt to get session without fallback
296
session = quilt3.get_boto3_session(fallback=False)
297
except quilt3.QuiltException as e:
298
print(f"No Quilt credentials: {e}")
299
# Fall back to default AWS credentials
300
import boto3
301
session = boto3.Session()
302
303
try:
304
# Attempt login when not configured
305
quilt3.logout() # Clear any existing config
306
quilt3.login()
307
except quilt3.QuiltException as e:
308
print(f"Login failed: {e}")
309
print("Please configure catalog URL first with quilt3.config('https://your-catalog.com')")
310
```