0
# Utility Functions
1

2
Random data generation and library information utilities provided by UnQLite for testing, development, and system information access.
3

4
## Capabilities
5

6
### Random Data Generation
7

8
Generate random strings and integers for testing, unique identifiers, and sample data creation.
9

10
```python { .api }
11
def random_string(self, int nbytes):
12
    """Generate a random string of given length.
13
    
14
    Args:
15
        nbytes: Number of bytes for the random string
16
        
17
    Returns:
18
        bytes: Random byte string of specified length
19
    """
20
    ...
21

22
def random_int(self):
23
    """Generate a random integer.
24
    
25
    Returns:
26
        int: Random integer value
27
    """
28
    ...
29
```
30

31
**Usage Example:**
32

33
```python
34
db = unqlite.UnQLite(':mem:')
35

36
# Generate random strings of different lengths
37
short_random = db.random_string(8)
38
print(f"Short random (8 bytes): {short_random}")
39

40
medium_random = db.random_string(32)
41
print(f"Medium random (32 bytes): {medium_random}")
42

43
long_random = db.random_string(128)
44
print(f"Long random (128 bytes): {len(long_random)} bytes")
45

46
# Generate random integers
47
for i in range(5):
48
    rand_int = db.random_int()
49
    print(f"Random integer {i+1}: {rand_int}")
50
```
51

52
### Unique Identifier Generation
53

54
Use random functions to create unique identifiers for records:
55

56
```python
57
import hashlib
58
import time
59

60
db = unqlite.UnQLite(':mem:')
61

62
def generate_unique_id():
63
    """Generate unique identifier using random data and timestamp."""
64
    random_bytes = db.random_string(16)
65
    timestamp = str(time.time()).encode()
66
    
67
    # Create hash from random data and timestamp
68
    hash_input = random_bytes + timestamp
69
    unique_id = hashlib.sha256(hash_input).hexdigest()[:16]
70
    
71
    return unique_id
72

73
# Generate unique IDs for records
74
for i in range(5):
75
    record_id = generate_unique_id()
76
    db[f"record_{record_id}"] = f"Data for record {i+1}"
77
    print(f"Generated ID: {record_id}")
78

79
# Verify records were stored
80
print(f"Total records: {len(db)}")
81
```
82

83
### Session Keys and Tokens
84

85
Generate random data for security applications:
86

87
```python
88
import base64
89

90
db = unqlite.UnQLite(':mem:')
91

92
def generate_session_token():
93
    """Generate secure session token."""
94
    random_bytes = db.random_string(32)  # 256 bits of randomness
95
    token = base64.urlsafe_b64encode(random_bytes).decode().rstrip('=')
96
    return token
97

98
def generate_api_key():
99
    """Generate API key with prefix."""
100
    random_bytes = db.random_string(24)  # 192 bits
101
    key_data = base64.urlsafe_b64encode(random_bytes).decode().rstrip('=')
102
    return f"ak_{key_data}"
103

104
# Generate tokens
105
session_token = generate_session_token()
106
api_key = generate_api_key()
107

108
print(f"Session token: {session_token}")
109
print(f"API key: {api_key}")
110

111
# Store tokens with expiration info
112
import time
113
current_time = int(time.time())
114

115
db['sessions'] = f'{{"token": "{session_token}", "created": {current_time}, "expires": {current_time + 3600}}}'
116
db['api_keys'] = f'{{"key": "{api_key}", "created": {current_time}, "active": true}}'
117
```
118

119
### Test Data Generation
120

121
Create realistic test data using random utilities:
122

123
```python
124
import json
125
import random
126

127
db = unqlite.UnQLite('testdata.db')
128

129
# Sample data templates
130
FIRST_NAMES = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Henry']
131
LAST_NAMES = ['Smith', 'Johnson', 'Williams', 'Brown', 'Jones', 'Garcia', 'Miller', 'Davis']
132
DEPARTMENTS = ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance', 'Operations']
133

134
def generate_test_user():
135
    """Generate test user with random data."""
136
    # Use database random functions
137
    user_id = db.random_int() % 10000 + 1000  # ID between 1000-10999
138
    
139
    # Random selections from predefined lists
140
    first_name = random.choice(FIRST_NAMES)
141
    last_name = random.choice(LAST_NAMES)
142
    department = random.choice(DEPARTMENTS)
143
    
144
    # Random salary in realistic range
145
    salary = (db.random_int() % 80000) + 40000  # $40k-$120k
146
    
147
    # Random binary data for profile picture placeholder
148
    avatar_data = db.random_string(64)  # Simulate image hash
149
    
150
    user = {
151
        'id': user_id,
152
        'name': f"{first_name} {last_name}",
153
        'email': f"{first_name.lower()}.{last_name.lower()}@example.com",
154
        'department': department,
155
        'salary': salary,
156
        'active': db.random_int() % 10 > 1,  # 90% active
157
        'avatar_hash': avatar_data.hex()
158
    }
159
    
160
    return user
161

162
# Generate test dataset
163
print("Generating test users...")
164
for i in range(50):
165
    user = generate_test_user()
166
    db[f"user:{user['id']}"] = json.dumps(user)
167

168
print(f"Generated {len(db)} test records")
169

170
# Verify some records
171
with db.cursor() as cursor:
172
    cursor.first()
173
    for _ in range(3):  # Show first 3 records
174
        if cursor.is_valid():
175
            key = cursor.key()
176
            value = json.loads(cursor.value())
177
            print(f"{key}: {value['name']} - {value['department']}")
178
            try:
179
                cursor.next_entry()
180
            except StopIteration:
181
                break
182
```
183

184
### Library Information
185

186
Access UnQLite library version and configuration information.
187

188
```python { .api }
189
def lib_version(self):
190
    """Get UnQLite library version.
191
    
192
    Returns:
193
        str: Version string of the UnQLite C library
194
    """
195
    ...
196
```
197

198
**Usage Example:**
199

200
```python
201
db = unqlite.UnQLite(':mem:')
202

203
# Get library version
204
version = db.lib_version()
205
print(f"UnQLite library version: {version}")
206

207
# Display system information
208
print(f"Database type: {'In-memory' if db.is_memory else 'File-based'}")
209
print(f"Database open: {db.is_open}")
210
print(f"Database file: {db.filename}")
211

212
# Create system info record
213
import sys
214
import platform
215

216
system_info = {
217
    'unqlite_version': version,
218
    'python_version': sys.version,
219
    'platform': platform.platform(),
220
    'database_type': 'memory' if db.is_memory else 'file'
221
}
222

223
db['system_info'] = json.dumps(system_info, indent=2)
224
print("System information stored")
225
```
226

227
### Benchmarking and Performance Testing
228

229
Use random data for performance testing:
230

231
```python
232
import time
233
import statistics
234

235
db = unqlite.UnQLite(':mem:')
236

237
def benchmark_writes(num_records):
238
    """Benchmark write performance with random data."""
239
    print(f"Benchmarking {num_records} writes with random data...")
240
    
241
    start_time = time.time()
242
    write_times = []
243
    
244
    for i in range(num_records):
245
        record_start = time.time()
246
        
247
        # Generate random key and value
248
        key_data = db.random_string(16)
249
        value_data = db.random_string(64)
250
        
251
        key = f"benchmark_{key_data.hex()[:8]}"
252
        value = value_data.hex()
253
        
254
        db[key] = value
255
        
256
        record_time = time.time() - record_start
257
        write_times.append(record_time)
258
    
259
    total_time = time.time() - start_time
260
    
261
    print(f"Total time: {total_time:.4f} seconds")
262
    print(f"Records per second: {num_records / total_time:.2f}")
263
    print(f"Average write time: {statistics.mean(write_times) * 1000:.4f} ms")
264
    print(f"Min write time: {min(write_times) * 1000:.4f} ms")
265
    print(f"Max write time: {max(write_times) * 1000:.4f} ms")
266

267
def benchmark_reads(num_reads):
268
    """Benchmark read performance."""
269
    print(f"Benchmarking {num_reads} random reads...")
270
    
271
    # Get all keys for random selection
272
    all_keys = list(db.keys())
273
    if len(all_keys) == 0:
274
        print("No data to read")
275
        return
276
    
277
    start_time = time.time()
278
    read_times = []
279
    
280
    for i in range(num_reads):
281
        # Select random key
282
        key = random.choice(all_keys)
283
        
284
        record_start = time.time()
285
        value = db[key]
286
        record_time = time.time() - record_start
287
        
288
        read_times.append(record_time)
289
    
290
    total_time = time.time() - start_time
291
    
292
    print(f"Total time: {total_time:.4f} seconds")
293
    print(f"Reads per second: {num_reads / total_time:.2f}")
294
    print(f"Average read time: {statistics.mean(read_times) * 1000:.4f} ms")
295

296
# Run benchmarks
297
benchmark_writes(1000)
298
benchmark_reads(500)
299

300
print(f"Final database size: {len(db)} records")
301
```
302

303
### Data Validation and Testing
304

305
Generate test data for validation scenarios:
306

307
```python
308
db = unqlite.UnQLite(':mem:')
309

310
def generate_edge_case_data():
311
    """Generate edge cases for testing."""
312
    test_cases = []
313
    
314
    # Empty data
315
    test_cases.append(('empty_string', ''))
316
    test_cases.append(('empty_bytes', b''))
317
    
318
    # Random binary data
319
    binary_data = db.random_string(256)
320
    test_cases.append(('random_binary', binary_data))
321
    
322
    # Large random string
323
    large_string = db.random_string(1024 * 10).hex()  # 10KB as hex
324
    test_cases.append(('large_string', large_string))
325
    
326
    # Random numbers
327
    for i in range(5):
328
        rand_num = db.random_int()
329
        test_cases.append((f'random_int_{i}', str(rand_num)))
330
    
331
    return test_cases
332

333
# Generate and store test cases
334
test_data = generate_edge_case_data()
335

336
print("Storing edge case test data...")
337
for key, value in test_data:
338
    db[f'test_{key}'] = value
339
    print(f"Stored: {key} ({type(value).__name__}, {len(str(value))} chars)")
340

341
# Verify all test data can be retrieved
342
print("\nVerifying test data retrieval...")
343
for key, expected_value in test_data:
344
    stored_key = f'test_{key}'
345
    retrieved_value = db[stored_key]
346
    
347
    # For bytes, compare as bytes
348
    if isinstance(expected_value, bytes):
349
        matches = retrieved_value == expected_value
350
    else:
351
        matches = str(retrieved_value) == str(expected_value)
352
    
353
    status = "✓" if matches else "✗"
354
    print(f"{status} {key}: {matches}")
355
```
356

357
## Best Practices
358

359
1. **Use appropriate randomness**: Generate enough random data for your security requirements
360
2. **Handle binary data**: Random strings return bytes objects, convert as needed
361
3. **Seed considerations**: UnQLite random functions use internal seeding
362
4. **Performance testing**: Use utilities for realistic performance benchmarks
363
5. **Version compatibility**: Check library version for feature compatibility
364

365
```python
366
# Good: Appropriate random data size for use case
367
session_id = db.random_string(32)  # 256 bits for session IDs
368
csrf_token = db.random_string(16)   # 128 bits for CSRF tokens
369

370
# Handle binary data properly
371
random_bytes = db.random_string(20)
372
hex_string = random_bytes.hex()      # Convert to hex string
373
b64_string = base64.b64encode(random_bytes).decode()  # Convert to base64
374

375
# Version-aware code
376
version = db.lib_version()
377
if version >= "1.1.9":
378
    # Use newer features
379
    pass
380
else:
381
    # Fallback for older versions
382
    pass
383
```