0
# Account Management
1

2
Administrative functions for managing Archive.org user accounts. This module provides the Account class for account lookup, locking, and unlocking operations.
3

4
**Note:** Account management functionality requires administrative privileges on Archive.org.
5

6
## Capabilities
7

8
### Account Lookup
9

10
Retrieve account information using various identifier types.
11

12
```python { .api }
13
class Account:
14
    """
15
    Administrative interface for managing Archive.org user accounts.
16
    
17
    Attributes:
18
        locked (bool): Whether the account is locked
19
        verified (bool): Whether the account is verified
20
        email (str): Account email address
21
        canonical_email (str): Canonical email address
22
        itemname (str): Account item name
23
        screenname (str): Account screen name
24
        notifications (list): List of notification settings
25
        has_disability_access (bool): Whether account has disability access
26
        lastlogin (str): Last login timestamp
27
        createdate (str): Account creation date
28
        session (ArchiveSession): Session object for API calls
29
    """
30
    
31
    @classmethod
32
    def from_account_lookup(cls, identifier_type: str, identifier: str, session=None):
33
        """
34
        Factory method to create Account object by looking up user information.
35
        
36
        Args:
37
            identifier_type (str): Type of identifier to search by:
38
                - 'email': Search by email address
39
                - 'screenname': Search by screen name
40
                - 'itemname': Search by item name
41
            identifier (str): The identifier value (e.g., 'user@example.com')
42
            session (ArchiveSession, optional): Session object to use for the request
43
            
44
        Returns:
45
            Account: Account object with populated user information
46
            
47
        Raises:
48
            AccountAPIError: If account lookup fails, access is denied, or account not found
49
            requests.exceptions.RequestException: If the API request fails
50
            
51
        Example:
52
            >>> from internetarchive.account import Account
53
            >>> account = Account.from_account_lookup('email', 'user@example.com')
54
            >>> print(f"Account created: {account.createdate}")
55
        """
56

57
    @classmethod  
58
    def from_json(cls, json_data: dict, session=None):
59
        """
60
        Create Account object from JSON data.
61
        
62
        Args:
63
            json_data (dict): Account data from API response
64
            session (ArchiveSession, optional): Session object to use
65
            
66
        Returns:
67
            Account: Account object created from JSON data
68
        """
69
```
70

71
### Account Management Operations
72

73
Lock and unlock user accounts with administrative comments.
74

75
```python { .api }
76
def lock(self, comment: str):
77
    """
78
    Lock the user account.
79
    
80
    Args:
81
        comment (str): Administrative comment explaining the reason for locking
82
        
83
    Raises:
84
        AccountAPIError: If locking fails or insufficient privileges
85
        requests.exceptions.RequestException: If the API request fails
86
        
87
    Example:
88
        >>> account = Account.from_account_lookup('email', 'spam@example.com')
89
        >>> account.lock("Account locked due to spam activity")
90
    """
91

92
def unlock(self, comment: str):
93
    """
94
    Unlock the user account.
95
    
96
    Args:
97
        comment (str): Administrative comment explaining the reason for unlocking
98
        
99
    Raises:
100
        AccountAPIError: If unlocking fails or insufficient privileges
101
        requests.exceptions.RequestException: If the API request fails
102
        
103
    Example:
104
        >>> account = Account.from_account_lookup('email', 'user@example.com')
105
        >>> account.unlock("Issue resolved, account reinstated")
106
    """
107

108
def to_dict(self):
109
    """
110
    Convert account data to dictionary format.
111
    
112
    Returns:
113
        dict: Account information as dictionary with all account attributes
114
        
115
    Example:
116
        >>> account = Account.from_account_lookup('email', 'user@example.com')
117
        >>> account_data = account.to_dict()
118
        >>> print(account_data['screenname'])
119
    """
120
```
121

122
## Usage Examples
123

124
### Basic Account Lookup
125

126
```python
127
from internetarchive.account import Account
128

129
# Look up account by email
130
account = Account.from_account_lookup('email', 'user@example.com')
131

132
# Check account status
133
print(f"Account locked: {account.locked}")
134
print(f"Account verified: {account.verified}")
135
print(f"Screen name: {account.screenname}")
136
print(f"Last login: {account.lastlogin}")
137

138
# Get full account data
139
account_dict = account.to_dict()
140
print(account_dict)
141
```
142

143
### Administrative Operations
144

145
```python
146
from internetarchive.account import Account
147
from internetarchive.exceptions import AccountAPIError
148

149
try:
150
    # Look up problematic account
151
    account = Account.from_account_lookup('screenname', 'spammer123')
152
    
153
    if not account.locked:
154
        # Lock the account with explanation
155
        account.lock("Account locked due to repeated policy violations")
156
        print(f"Account {account.screenname} has been locked")
157
    else:
158
        print(f"Account {account.screenname} is already locked")
159
        
160
except AccountAPIError as e:
161
    print(f"Account operation failed: {e}")
162
    if hasattr(e, 'error_data') and e.error_data:
163
        print(f"Error details: {e.error_data}")
164
```
165

166
### Batch Account Management
167

168
```python
169
from internetarchive.account import Account
170
from internetarchive.exceptions import AccountAPIError
171

172
# List of accounts to review
173
suspicious_emails = [
174
    'user1@suspicious.com',
175
    'user2@suspicious.com', 
176
    'user3@suspicious.com'
177
]
178

179
for email in suspicious_emails:
180
    try:
181
        account = Account.from_account_lookup('email', email)
182
        
183
        print(f"\\nAccount: {account.screenname} ({email})")
184
        print(f"Created: {account.createdate}")
185
        print(f"Last login: {account.lastlogin}")
186
        print(f"Verified: {account.verified}")
187
        print(f"Locked: {account.locked}")
188
        
189
        # Check if action needed based on account status
190
        if not account.verified and account.lastlogin == 'never':
191
            print("-> Potential unused account")
192
            
193
    except AccountAPIError as e:
194
        print(f"Could not lookup {email}: {e}")
195
```
196

197
### Account Unlocking Workflow
198

199
```python
200
from internetarchive.account import Account
201

202
# Process account unlock request
203
def process_unlock_request(email, justification):
204
    try:
205
        account = Account.from_account_lookup('email', email)
206
        
207
        if account.locked:
208
            # Review account status
209
            print(f"Account {account.screenname} currently locked")
210
            print(f"Created: {account.createdate}")
211
            print(f"Last login: {account.lastlogin}")
212
            
213
            # Unlock with justification
214
            unlock_comment = f"Account unlocked: {justification}"
215
            account.unlock(unlock_comment)
216
            
217
            print(f"Account {account.screenname} has been unlocked")
218
            return True
219
        else:
220
            print(f"Account {account.screenname} is not locked")
221
            return False
222
            
223
    except AccountAPIError as e:
224
        print(f"Failed to process unlock request: {e}")
225
        return False
226

227
# Example usage
228
result = process_unlock_request(
229
    'user@example.com', 
230
    'False positive spam detection, legitimate user verified'
231
)
232
```
233

234
## Error Handling
235

236
The Account class can raise several types of exceptions:
237

238
### AccountAPIError
239

240
```python { .api }
241
class AccountAPIError(Exception):
242
    """
243
    Account API-related errors.
244
    
245
    Attributes:
246
        error_data (dict, optional): Additional error information from API response
247
    """
248
```
249

250
Common scenarios that raise `AccountAPIError`:
251
- Account not found for the given identifier
252
- Insufficient administrative privileges
253
- Invalid identifier type or format
254
- API service unavailable
255

256
### Request Exceptions
257

258
Network and HTTP-related errors are propagated as `requests.exceptions.RequestException` or its subclasses.
259

260
## Prerequisites
261

262
To use the Account management functionality:
263

264
1. **Administrative Privileges**: Your Archive.org account must have administrative privileges
265
2. **Authentication**: Proper IA-S3 credentials must be configured
266
3. **Network Access**: Access to Archive.org API endpoints
267

268
## Security Considerations
269

270
- Account management operations are logged by Archive.org
271
- All lock/unlock operations require administrative comments for audit trail
272
- API access is rate-limited and monitored
273
- Misuse of administrative privileges may result in account suspension