0
# Administrative Functions
1

2
Administrative capabilities for managing users, roles, SSO configuration, and other Quilt stack administrative tasks.
3

4
## Package Overview
5

6
The `quilt3.admin` module provides administrative functions for Quilt stack backend services, including identity management, user administration, and system configuration.
7

8
```python
9
import quilt3.admin
10
```
11

12
## Type Imports
13

14
```python { .api }
15
from typing import Optional, List, Literal
16
from datetime import datetime
17
from dataclasses import dataclass
18
```
19

20
## Capabilities
21

22
### User Management
23

24
Administrative functions for managing users in the Quilt stack.
25

26
```python { .api }
27
import quilt3.admin.users
28

29
def get(name: str) -> Optional[User]:
30
    """
31
    Get a specific user from the registry.
32

33
    Parameters:
34
    - name: Username to retrieve
35

36
    Returns:
37
    User object if found, None otherwise
38
    """
39

40
def list() -> List[User]:
41
    """
42
    Get a list of all users in the registry.
43

44
    Returns:
45
    List of User objects
46
    """
47

48
def create(name: str, email: str, role: str, extra_roles: Optional[List[str]] = None) -> User:
49
    """
50
    Create a new user in the registry.
51

52
    Parameters:
53
    - name: Username for the new user
54
    - email: Email address for the user
55
    - role: Primary role for the user
56
    - extra_roles: Additional roles to assign
57

58
    Returns:
59
    Created User object
60
    """
61

62
def delete(name: str) -> None:
63
    """
64
    Delete user from the registry.
65

66
    Parameters:
67
    - name: Username to delete
68
    """
69

70
def set_email(name: str, email: str) -> User:
71
    """
72
    Set the email for a user.
73

74
    Parameters:
75
    - name: Username to update
76
    - email: New email address
77

78
    Returns:
79
    Updated User object
80
    """
81

82
def set_admin(name: str, admin: bool) -> User:
83
    """
84
    Set the admin status for a user.
85

86
    Parameters:
87
    - name: Username to update
88
    - admin: Whether user should have admin privileges
89

90
    Returns:
91
    Updated User object
92
    """
93

94
def set_active(name: str, active: bool) -> User:
95
    """
96
    Set the active status for a user.
97

98
    Parameters:
99
    - name: Username to update
100
    - active: Whether user account should be active
101

102
    Returns:
103
    Updated User object
104
    """
105

106
def reset_password(name: str) -> None:
107
    """
108
    Reset password for a user.
109

110
    Parameters:
111
    - name: Username to reset password for
112
    """
113
```
114

115
### Role Management
116

117
Administrative functions for managing roles and permissions.
118

119
```python { .api }
120
import quilt3.admin.roles
121

122
def list() -> List[Role]:
123
    """
124
    Get a list of all roles in the registry.
125

126
    Returns:
127
    List of Role objects (ManagedRole and UnmanagedRole)
128
    """
129
```
130

131
### SSO Configuration
132

133
Administrative functions for configuring Single Sign-On settings.
134

135
```python { .api }
136
import quilt3.admin.sso_config
137

138
# SSO configuration functions for managing Single Sign-On settings
139
# Specific implementation depends on deployment configuration
140
```
141

142
### Data Tabulation
143

144
Administrative functions for data tabulation and analysis.
145

146
```python { .api }
147
import quilt3.admin.tabulator
148

149
# Tabulator functions for data processing and table management
150
# Specific implementation depends on deployment configuration
151
```
152

153
## Admin Data Types
154

155
### User Type
156

157
```python { .api }
158
@dataclass
159
class User:
160
    """
161
    Represents a user in the Quilt system.
162
    
163
    Attributes:
164
    - name: Username
165
    - email: User email address
166
    - date_joined: When user account was created
167
    - last_login: Last login timestamp
168
    - is_active: Whether account is active
169
    - is_admin: Whether user has admin privileges
170
    - is_sso_only: Whether user can only login via SSO
171
    - is_service: Whether this is a service account
172
    - role: Primary role assigned to user
173
    - extra_roles: Additional roles assigned to user
174
    """
175
    name: str
176
    email: str
177
    date_joined: datetime
178
    last_login: datetime
179
    is_active: bool
180
    is_admin: bool
181
    is_sso_only: bool
182
    is_service: bool
183
    role: Optional[Role]
184
    extra_roles: List[Role]
185
```
186

187
### Role Types
188

189
```python { .api }
190
@dataclass
191
class ManagedRole:
192
    """
193
    Represents a managed role in the Quilt system.
194
    
195
    Managed roles are controlled by the Quilt stack administrators
196
    and have predefined permissions and policies.
197
    """
198
    id: str
199
    name: str
200
    arn: str
201
    typename__: Literal["ManagedRole"]
202

203
@dataclass
204
class UnmanagedRole:
205
    """
206
    Represents an unmanaged role in the Quilt system.
207
    
208
    Unmanaged roles are custom roles that can be configured
209
    with specific permissions as needed.
210
    """
211
    id: str
212
    name: str
213
    arn: str
214
    typename__: Literal["UnmanagedRole"]
215
```
216

217
### Configuration Types
218

219
```python { .api }
220
@dataclass
221
class SSOConfig:
222
    """
223
    Represents Single Sign-On configuration settings.
224
    
225
    Contains SSO provider settings, authentication parameters,
226
    and integration configuration.
227
    """
228
    text: str
229
    timestamp: datetime
230
    uploader: User
231

232
@dataclass
233
class TabulatorTable:
234
    """
235
    Represents a tabulator table configuration.
236
    
237
    Contains table definition, schema, and processing settings
238
    for data tabulation operations.
239
    """
240
    name: str
241
    config: str
242
```
243

244
## Admin Exception Types
245

246
```python { .api }
247
class Quilt3AdminError(Exception):
248
    """
249
    General administrative operation error.
250
    
251
    Raised when admin operations fail due to permissions,
252
    configuration issues, or system errors.
253
    """
254
    pass
255

256
class UserNotFoundError(Quilt3AdminError):
257
    """
258
    User not found error.
259
    
260
    Raised when attempting to perform operations on
261
    a user that doesn't exist in the system.
262
    """
263
    pass
264

265
class BucketNotFoundError(Quilt3AdminError):
266
    """
267
    Bucket not found error.
268
    
269
    Raised when attempting to perform operations on
270
    a bucket that doesn't exist or isn't accessible.
271
    """
272
    pass
273
```
274

275
## Usage Examples
276

277
### Basic Admin Operations
278

279
```python
280
import quilt3.admin
281

282
# Import specific admin modules
283
from quilt3.admin import users, roles, sso_config
284

285
# Admin operations require appropriate permissions
286
# and authentication to the Quilt stack
287
```
288

289
### User Administration
290

291
```python
292
import quilt3.admin.users
293
from quilt3.admin import User, UserNotFoundError
294

295
try:
296
    # User management operations
297
    # (Specific APIs depend on admin implementation)
298
    
299
    # Example operations might include:
300
    # - List users
301
    # - Create users  
302
    # - Update user permissions
303
    # - Delete users
304
    
305
    pass  # Placeholder for actual admin operations
306
    
307
except UserNotFoundError as e:
308
    print(f"User not found: {e}")
309
except Exception as e:
310
    print(f"Admin operation failed: {e}")
311
```
312

313
### Role Management
314

315
```python
316
import quilt3.admin.roles
317
from quilt3.admin import ManagedRole, UnmanagedRole
318

319
# Role management operations
320
# (Specific APIs depend on admin implementation)
321

322
# Example operations might include:
323
# - List available roles
324
# - Create custom roles
325
# - Assign roles to users
326
# - Update role permissions
327
# - Delete roles
328

329
# Work with managed roles (predefined by system)
330
managed_roles = []  # Get managed roles from system
331

332
# Work with unmanaged roles (custom roles)
333
custom_roles = []  # Get custom roles from system
334
```
335

336
### SSO Configuration
337

338
```python
339
import quilt3.admin.sso_config
340
from quilt3.admin import SSOConfig
341

342
# SSO configuration operations
343
# (Specific APIs depend on admin implementation)
344

345
# Example operations might include:
346
# - Configure SSO providers
347
# - Update authentication settings  
348
# - Test SSO integration
349
# - Manage SSO user mappings
350

351
try:
352
    # Configure SSO settings
353
    sso_settings = SSOConfig()
354
    # Update SSO configuration
355
    
356
except Exception as e:
357
    print(f"SSO configuration failed: {e}")
358
```
359

360
### Data Tabulation
361

362
```python
363
import quilt3.admin.tabulator
364
from quilt3.admin import TabulatorTable
365

366
# Tabulator operations for data analysis
367
# (Specific APIs depend on admin implementation)
368

369
# Example operations might include:
370
# - Define tabulation schemas
371
# - Process data through tabulator
372
# - Generate reports
373
# - Manage tabulation jobs
374

375
try:
376
    # Configure tabulation table
377
    table_config = TabulatorTable()
378
    # Process data through tabulator
379
    
380
except Exception as e:
381
    print(f"Tabulation operation failed: {e}")
382
```
383

384
### Error Handling
385

386
```python
387
import quilt3.admin
388
from quilt3.admin import (
389
    Quilt3AdminError,
390
    UserNotFoundError, 
391
    BucketNotFoundError
392
)
393

394
def safe_admin_operation():
395
    """Example of safe admin operation with error handling"""
396
    try:
397
        # Perform admin operations
398
        # result = admin_operation()
399
        pass
400
        
401
    except UserNotFoundError as e:
402
        print(f"User does not exist: {e}")
403
        return None
404
        
405
    except BucketNotFoundError as e:
406
        print(f"Bucket not accessible: {e}")
407
        return None
408
        
409
    except Quilt3AdminError as e:
410
        print(f"Admin operation failed: {e}")
411
        return None
412
        
413
    except Exception as e:
414
        print(f"Unexpected error: {e}")
415
        return None
416

417
# Use safe operation
418
result = safe_admin_operation()
419
if result:
420
    print("Admin operation successful")
421
else:
422
    print("Admin operation failed - check permissions and configuration")
423
```
424

425
### Prerequisites and Setup
426

427
```python
428
import quilt3
429

430
# Admin operations require:
431
# 1. Proper authentication to Quilt stack
432
# 2. Administrative privileges
433
# 3. Correct configuration
434

435
def check_admin_access():
436
    """Check if current user has admin access"""
437
    
438
    # Verify authentication
439
    if not quilt3.logged_in():
440
        print("Error: Not authenticated. Run quilt3.login() first.")
441
        return False
442
    
443
    # Verify configuration
444
    config = quilt3.config()
445
    if not config.get('registryUrl'):
446
        print("Error: No registry URL configured.")
447
        return False
448
    
449
    # Test basic admin access
450
    try:
451
        import quilt3.admin
452
        print("Admin module imported successfully")
453
        return True
454
    except ImportError as e:
455
        print(f"Error: Admin module not available: {e}")
456
        return False
457
    except Exception as e:
458
        print(f"Error: Admin access check failed: {e}")
459
        return False
460

461
# Check admin prerequisites
462
if check_admin_access():
463
    print("Ready for admin operations")
464
    # Proceed with admin tasks
465
else:
466
    print("Admin operations not available")
467
    # Handle lack of admin access
468
```
469

470
## Notes
471

472
- Admin functions require appropriate permissions on the Quilt stack
473
- All admin operations should be performed with proper authentication
474
- Admin APIs may vary depending on Quilt stack version and configuration
475
- Administrative operations can affect system-wide settings and user access
476
- Always test admin operations in a development environment first
477
- Some admin functions may require elevated privileges or special roles