0
# Core Caching
1

2
The Cache class provides the primary caching functionality in DiskCache, offering thread-safe and process-safe disk-based storage with SQLite as the backend. It supports all standard cache operations, atomic transactions, queue operations, and comprehensive cache management with statistics and eviction policies.
3

4
## Capabilities
5

6
### Cache Initialization
7

8
Create a Cache instance with optional directory path, timeout settings, and custom serialization.
9

10
```python { .api }
11
class Cache:
12
    def __init__(self, directory=None, timeout=60, disk=Disk, **settings):
13
        """
14
        Initialize cache instance.
15
        
16
        Args:
17
            directory (str, optional): Cache directory path. If None, creates temp directory.
18
            timeout (float): SQLite connection timeout in seconds. Default 60.
19
            disk (Disk): Disk instance for serialization. Default Disk.
20
            **settings: Cache configuration options from DEFAULT_SETTINGS.
21
        """
22

23
    @property
24
    def directory(self):
25
        """Cache directory path."""
26
        
27
    @property
28
    def timeout(self):
29
        """SQLite connection timeout."""
30
        
31
    @property
32
    def disk(self):
33
        """Disk instance used for serialization."""
34
```
35

36
### Basic Cache Operations
37

38
Store, retrieve, and delete key-value pairs with optional expiration, read mode, and tagging.
39

40
```python { .api }
41
def set(self, key, value, expire=None, read=False, tag=None, retry=False):
42
    """
43
    Store key-value pair in cache.
44
    
45
    Args:
46
        key: Cache key (must be hashable)
47
        value: Value to store
48
        expire (float, optional): Expiration time in seconds from now
49
        read (bool): Store value as file for reading. Default False.
50
        tag (str, optional): Tag for grouping related items
51
        retry (bool): Retry operation on timeout. Default False.
52
        
53
    Returns:
54
        bool: True if set succeeded
55
    """
56

57
def get(self, key, default=None, read=False, expire_time=False, tag=False, retry=False):
58
    """
59
    Retrieve value by key.
60
    
61
    Args:
62
        key: Cache key
63
        default: Default value if key not found
64
        read (bool): Return file handle instead of value. Default False.
65
        expire_time (bool): Include expiration time in result. Default False.
66
        tag (bool): Include tag in result. Default False.
67
        retry (bool): Retry operation on timeout. Default False.
68
        
69
    Returns:
70
        Value, or tuple with additional info if expire_time/tag requested
71
    """
72

73
def delete(self, key, retry=False):
74
    """
75
    Delete key from cache.
76
    
77
    Args:
78
        key: Cache key to delete
79
        retry (bool): Retry operation on timeout. Default False.
80
        
81
    Returns:
82
        bool: True if key existed and was deleted
83
    """
84

85
def add(self, key, value, expire=None, read=False, tag=None, retry=False):
86
    """
87
    Add key-value pair only if key doesn't exist.
88
    
89
    Args:
90
        key: Cache key
91
        value: Value to store
92
        expire (float, optional): Expiration time in seconds from now
93
        read (bool): Store value as file for reading. Default False.
94
        tag (str, optional): Tag for grouping related items
95
        retry (bool): Retry operation on timeout. Default False.
96
        
97
    Returns:
98
        bool: True if key was added (didn't exist)
99
    """
100

101
def touch(self, key, expire=None, retry=False):
102
    """
103
    Update expiration time for existing key.
104
    
105
    Args:
106
        key: Cache key
107
        expire (float, optional): New expiration time in seconds from now
108
        retry (bool): Retry operation on timeout. Default False.
109
        
110
    Returns:
111
        bool: True if key existed and was touched
112
    """
113

114
def pop(self, key, default=None, expire_time=False, tag=False, retry=False):
115
    """
116
    Remove and return value for key.
117
    
118
    Args:
119
        key: Cache key
120
        default: Default value if key not found
121
        expire_time (bool): Include expiration time in result. Default False.
122
        tag (bool): Include tag in result. Default False.
123
        retry (bool): Retry operation on timeout. Default False.
124
        
125
    Returns:
126
        Value, or tuple with additional info if expire_time/tag requested
127
    """
128

129
def read(self, key, retry=False):
130
    """
131
    Get file handle for key stored in read mode.
132
    
133
    Args:
134
        key: Cache key
135
        retry (bool): Retry operation on timeout. Default False.
136
        
137
    Returns:
138
        File handle or None if key not found
139
    """
140
```
141

142
### Dict-like Interface
143

144
Use familiar dictionary syntax for cache operations.
145

146
```python { .api }
147
def __setitem__(self, key, value):
148
    """Store key-value pair using cache[key] = value syntax."""
149

150
def __getitem__(self, key):
151
    """Retrieve value using cache[key] syntax. Raises KeyError if not found."""
152

153
def __delitem__(self, key, retry=True):
154
    """Delete key using del cache[key] syntax. Raises KeyError if not found."""
155

156
def __contains__(self, key):
157
    """Check if key exists using 'key in cache' syntax."""
158

159
def __len__(self):
160
    """Get count of items in cache."""
161

162
def __iter__(self):
163
    """Iterate over cache keys."""
164

165
def __reversed__(self):
166
    """Reverse iterate over cache keys."""
167
```
168

169
### Atomic Operations
170

171
Perform atomic increment and decrement operations.
172

173
```python { .api }
174
def incr(self, key, delta=1, default=0, retry=False):
175
    """
176
    Atomically increment numeric value.
177
    
178
    Args:
179
        key: Cache key
180
        delta (int): Amount to increment. Default 1.
181
        default (int): Default value if key doesn't exist. Default 0.
182
        retry (bool): Retry operation on timeout. Default False.
183
        
184
    Returns:
185
        New value after increment
186
    """
187

188
def decr(self, key, delta=1, default=0, retry=False):
189
    """
190
    Atomically decrement numeric value.
191
    
192
    Args:
193
        key: Cache key  
194
        delta (int): Amount to decrement. Default 1.
195
        default (int): Default value if key doesn't exist. Default 0.
196
        retry (bool): Retry operation on timeout. Default False.
197
        
198
    Returns:
199
        New value after decrement
200
    """
201
```
202

203
### Queue Operations
204

205
Use the cache as a queue with push/pull operations supporting prefixes and different sides.
206

207
```python { .api }
208
def push(self, value, prefix=None, side='back', expire=None, read=False, tag=None, retry=False):
209
    """
210
    Push value to queue.
211
    
212
    Args:
213
        value: Value to push
214
        prefix (str, optional): Key prefix for queue namespace
215
        side (str): Which side to push to ('back' or 'front'). Default 'back'.
216
        expire (float, optional): Expiration time in seconds from now
217
        read (bool): Store value as file for reading. Default False.
218
        tag (str, optional): Tag for grouping related items
219
        retry (bool): Retry operation on timeout. Default False.
220
        
221
    Returns:
222
        Generated key for the pushed value
223
    """
224

225
def pull(self, prefix=None, default=(None, None), side='front', expire_time=False, tag=False, retry=False):
226
    """
227
    Pull value from queue.
228
    
229
    Args:
230
        prefix (str, optional): Key prefix for queue namespace
231
        default: Default value if queue is empty. Default (None, None).
232
        side (str): Which side to pull from ('front' or 'back'). Default 'front'.
233
        expire_time (bool): Include expiration time in result. Default False.
234
        tag (bool): Include tag in result. Default False.
235
        retry (bool): Retry operation on timeout. Default False.
236
        
237
    Returns:
238
        Tuple of (key, value) or default if queue empty
239
    """
240

241
def peek(self, prefix=None, default=(None, None), side='front', expire_time=False, tag=False, retry=False):
242
    """
243
    Peek at queue value without removing it.
244
    
245
    Args:
246
        prefix (str, optional): Key prefix for queue namespace
247
        default: Default value if queue is empty. Default (None, None).
248
        side (str): Which side to peek at ('front' or 'back'). Default 'front'.
249
        expire_time (bool): Include expiration time in result. Default False.
250
        tag (bool): Include tag in result. Default False.
251
        retry (bool): Retry operation on timeout. Default False.
252
        
253
    Returns:
254
        Tuple of (key, value) or default if queue empty
255
    """
256

257
def peekitem(self, last=True, expire_time=False, tag=False, retry=False):
258
    """
259
    Peek at any item in cache without removing it.
260
    
261
    Args:
262
        last (bool): Peek at last item if True, first if False. Default True.
263
        expire_time (bool): Include expiration time in result. Default False.
264
        tag (bool): Include tag in result. Default False.
265
        retry (bool): Retry operation on timeout. Default False.
266
        
267
    Returns:
268
        Tuple of (key, value) or (None, None) if cache empty
269
    """
270
```
271

272
### Cache Management
273

274
Manage cache contents with clearing, culling, expiration, and eviction operations.
275

276
```python { .api }
277
def clear(self, retry=False):
278
    """
279
    Remove all items from cache.
280
    
281
    Args:
282
        retry (bool): Retry operation on timeout. Default False.
283
        
284
    Returns:
285
        int: Number of items removed
286
    """
287

288
def cull(self, retry=False):
289
    """
290
    Remove items according to eviction policy.
291
    
292
    Args:
293
        retry (bool): Retry operation on timeout. Default False.
294
        
295
    Returns:
296
        int: Number of items removed
297
    """
298

299
def expire(self, now=None, retry=False):
300
    """
301
    Remove expired items from cache.
302
    
303
    Args:
304
        now (float, optional): Current time. Default time.time().
305
        retry (bool): Retry operation on timeout. Default False.
306
        
307
    Returns:
308
        int: Number of expired items removed
309
    """
310

311
def evict(self, tag, retry=False):
312
    """
313
    Remove all items with specified tag.
314
    
315
    Args:
316
        tag (str): Tag to evict
317
        retry (bool): Retry operation on timeout. Default False.
318
        
319
    Returns:
320
        int: Number of items evicted
321
    """
322

323
def check(self, fix=False, retry=False):
324
    """
325
    Check cache database consistency.
326
    
327
    Args:
328
        fix (bool): Attempt to fix issues if found. Default False.
329
        retry (bool): Retry operation on timeout. Default False.
330
        
331
    Returns:
332
        List of issues found (empty if no issues)
333
    """
334
```
335

336
### Tag Management
337

338
Create and manage database indexes for tag-based operations.
339

340
```python { .api }
341
def create_tag_index(self):
342
    """Create database index on tag column for faster tag operations."""
343

344
def drop_tag_index(self):
345
    """Drop database index on tag column."""
346
```
347

348
### Statistics and Iteration
349

350
Access cache statistics and iterate through cache contents.
351

352
```python { .api }
353
def stats(self, enable=True, reset=False):
354
    """
355
    Get cache hit/miss statistics.
356
    
357
    Args:
358
        enable (bool): Enable statistics tracking. Default True.
359
        reset (bool): Reset statistics counters. Default False.
360
        
361
    Returns:
362
        Tuple of (hits, misses) counters
363
    """
364

365
def volume(self):
366
    """
367
    Get total cache size on disk.
368
    
369
    Returns:
370
        int: Total size in bytes
371
    """
372

373
def iterkeys(self, reverse=False):
374
    """
375
    Iterate cache keys in sorted order.
376
    
377
    Args:
378
        reverse (bool): Iterate in reverse order. Default False.
379
        
380
    Yields:
381
        Cache keys in sorted order
382
    """
383
```
384

385
### Transaction Management
386

387
Use context managers and transactions for atomic operations.
388

389
```python { .api }
390
def transact(self, retry=False):
391
    """
392
    Context manager for atomic transactions.
393
    
394
    Args:
395
        retry (bool): Retry transaction on timeout. Default False.
396
        
397
    Returns:
398
        Context manager for transaction
399
    """
400

401
def __enter__(self):
402
    """Context manager entry - opens database connection."""
403

404
def __exit__(self, *exception):
405
    """Context manager exit - closes database connection."""
406

407
def close(self):
408
    """Close database connection and cleanup resources."""
409
```
410

411
### Memoization Decorator
412

413
Use the cache as a memoization decorator for functions.
414

415
```python { .api }
416
def memoize(self, name=None, typed=False, expire=None, tag=None, ignore=()):
417
    """
418
    Memoization decorator using this cache.
419
    
420
    Args:
421
        name (str, optional): Name for memoized function. Default function name.
422
        typed (bool): Distinguish arguments by type. Default False.
423
        expire (float, optional): Expiration time in seconds from now
424
        tag (str, optional): Tag for grouping related items
425
        ignore (tuple): Argument positions/names to ignore in caching
426
        
427
    Returns:
428
        Decorator function
429
    """
430
```
431

432
### Advanced Operations
433

434
Advanced cache operations for settings management and serialization support.
435

436
```python { .api }
437
def reset(self, key, value=ENOVAL, update=True):
438
    """
439
    Reset cache setting value.
440
    
441
    Args:
442
        key (str): Setting key from DEFAULT_SETTINGS
443
        value: New value for setting
444
        update (bool): Update existing cache with new setting. Default True.
445
        
446
    Returns:
447
        Previous value of setting
448
    """
449

450
def __getstate__(self):
451
    """Support for pickle serialization - returns cache state."""
452

453
def __setstate__(self, state):
454
    """Support for pickle deserialization - restores cache state."""
455
```
456

457
## Usage Examples
458

459
### Basic Usage
460

461
```python
462
import diskcache
463

464
# Create cache
465
cache = diskcache.Cache('/tmp/mycache')
466

467
# Basic operations
468
cache.set('user:123', {'name': 'Alice', 'age': 30})
469
user = cache.get('user:123')
470

471
# Dict-like interface
472
cache['settings'] = {'theme': 'dark', 'lang': 'en'}
473
if 'settings' in cache:
474
    settings = cache['settings']
475

476
# Expiration
477
cache.set('temp_data', 'expires in 1 hour', expire=3600)
478

479
# Atomic operations
480
cache.set('counter', 0)
481
cache.incr('counter')  # Returns 1
482
cache.decr('counter')  # Returns 0
483
```
484

485
### Transaction Example
486

487
```python
488
# Atomic operations
489
with cache.transact():
490
    cache.set('a', 1)
491
    cache.set('b', 2)
492
    cache.incr('counter')
493
    # All operations committed together
494
```
495

496
### Queue Usage
497

498
```python
499
# Use as a queue
500
task_id = cache.push({'task': 'process_data', 'priority': 1}, prefix='tasks')
501
key, task = cache.pull(prefix='tasks')
502

503
# LIFO queue (stack)
504
cache.push('item1', side='back')
505
cache.push('item2', side='back')
506
key, item = cache.pull(side='back')  # Gets 'item2'
507
```
508

509
### Memoization
510

511
```python
512
@cache.memoize(expire=3600)  # Cache for 1 hour
513
def expensive_computation(n):
514
    # Expensive operation
515
    return sum(i**2 for i in range(n))
516

517
result = expensive_computation(1000)  # Computed and cached
518
result = expensive_computation(1000)  # Retrieved from cache
519
```