0
# Cachier
1
2
Cachier provides persistent, stale-free memoization decorators for Python functions, enabling comprehensive caching with multiple storage backends including memory, filesystem (pickle), MongoDB, Redis, and SQL databases. It offers configurable cache expiration through stale_after parameters, automatic cache invalidation, cross-machine caching capabilities for distributed computing environments, and supports both synchronous and asynchronous function caching.
3
4
## Package Information
5
6
- **Package Name**: cachier
7
- **Language**: Python
8
- **Installation**: `pip install cachier`
9
10
## Core Imports
11
12
```python
13
import cachier
14
```
15
16
Common usage pattern:
17
18
```python
19
from cachier import cachier, set_global_params, enable_caching, disable_caching
20
```
21
22
All public APIs are available from the main module:
23
24
```python
25
from cachier import (
26
cachier, # Main decorator
27
set_global_params, # Global configuration
28
get_global_params, # Get global config
29
enable_caching, # Enable caching globally
30
disable_caching, # Disable caching globally
31
__version__ # Version string
32
)
33
```
34
35
## Basic Usage
36
37
```python
38
from cachier import cachier
39
from datetime import timedelta
40
41
# Simple persistent caching with default pickle backend
42
@cachier()
43
def expensive_computation(n):
44
# Simulate expensive computation
45
result = sum(i**2 for i in range(n))
46
return result
47
48
# Use the cached function
49
result1 = expensive_computation(1000) # Computed and cached
50
result2 = expensive_computation(1000) # Retrieved from cache
51
52
# Caching with expiration after 1 hour
53
@cachier(stale_after=timedelta(hours=1))
54
def fetch_data(url):
55
# Fetch data from API
56
import requests
57
return requests.get(url).json()
58
59
# Multi-backend example with MongoDB
60
@cachier(backend='mongo', mongetter=lambda: my_mongo_collection)
61
def cached_analysis(data_id):
62
# Perform analysis on data
63
return analyze_data(data_id)
64
65
# Clear cache when needed
66
expensive_computation.clear_cache()
67
```
68
69
## Capabilities
70
71
### Core Caching Decorator
72
73
The main `cachier` decorator that provides persistent, stale-free memoization with multiple backend support and extensive configuration options.
74
75
```python { .api }
76
def cachier(
77
hash_func: Optional[HashFunc] = None,
78
hash_params: Optional[HashFunc] = None, # Deprecated
79
backend: Optional[Backend] = None,
80
mongetter: Optional[Mongetter] = None,
81
sql_engine: Optional[Union[str, Any, Callable[[], Any]]] = None,
82
redis_client: Optional[RedisClient] = None,
83
stale_after: Optional[timedelta] = None,
84
next_time: Optional[bool] = None,
85
cache_dir: Optional[Union[str, os.PathLike]] = None,
86
pickle_reload: Optional[bool] = None,
87
separate_files: Optional[bool] = None,
88
wait_for_calc_timeout: Optional[int] = None,
89
allow_none: Optional[bool] = None,
90
cleanup_stale: Optional[bool] = None,
91
cleanup_interval: Optional[timedelta] = None,
92
):
93
"""
94
Wrap as a persistent, stale-free memoization decorator.
95
96
Parameters:
97
- hash_func: Custom hash function for arguments
98
- backend: Backend type ('pickle', 'mongo', 'memory', 'redis', 'sql')
99
- mongetter: MongoDB collection getter function
100
- sql_engine: SQLAlchemy engine
101
- redis_client: Redis client instance or callable
102
- stale_after: Time after which cache becomes stale
103
- next_time: Return stale result while recalculating in background
104
- cache_dir: Cache directory path
105
- pickle_reload: Reload in-memory cache on each read
106
- separate_files: Split cache into separate files per argument set
107
- wait_for_calc_timeout: Max wait time for ongoing calculations
108
- allow_none: Allow caching None values
109
- cleanup_stale: Automatically delete stale entries
110
- cleanup_interval: Minimum time between cleanup runs
111
112
Returns:
113
Decorated function with attached cache management methods
114
"""
115
```
116
117
[Core Decorator](./core-decorator.md)
118
119
### Global Configuration
120
121
Functions for managing global caching parameters that apply to all memoized functions unless overridden by individual decorators.
122
123
```python { .api }
124
def set_global_params(**params: Any) -> None:
125
"""
126
Configure global parameters applicable to all memoized functions.
127
128
Parameters:
129
- **params: Keyword parameters matching decorator parameters
130
"""
131
132
def get_global_params() -> Params:
133
"""
134
Get current set of global parameters.
135
136
Returns:
137
Params dataclass instance with current global settings
138
"""
139
140
def enable_caching() -> None:
141
"""Enable caching globally."""
142
143
def disable_caching() -> None:
144
"""Disable caching globally."""
145
```
146
147
[Global Configuration](./global-configuration.md)
148
149
### Cache Management
150
151
Built-in methods attached to decorated functions for managing cached data and controlling cache behavior.
152
153
```python { .api }
154
# Methods attached to decorated functions
155
def clear_cache() -> None:
156
"""Clear all cached entries for this function."""
157
158
def clear_being_calculated() -> None:
159
"""Mark all entries as not being calculated."""
160
161
def cache_dpath() -> Optional[str]:
162
"""Return cache directory path if exists, None otherwise."""
163
164
def precache_value(*args, value_to_cache, **kwargs):
165
"""
166
Add an initial value to the cache.
167
168
Parameters:
169
- *args, **kwargs: Function arguments to cache value for
170
- value_to_cache: Entry to be written into the cache
171
"""
172
```
173
174
[Cache Management](./cache-management.md)
175
176
### Backend Cores
177
178
Multiple storage backends for different caching requirements, from in-memory to distributed caching solutions.
179
180
```python { .api }
181
# Available backend types
182
Backend = Literal["pickle", "mongo", "memory", "redis", "sql"]
183
```
184
185
[Backend Cores](./backend-cores.md)
186
187
## Types
188
189
Core type definitions used throughout the cachier API:
190
191
```python { .api }
192
from typing import Callable, Literal, Union, Optional
193
from datetime import timedelta
194
import os
195
196
HashFunc = Callable[..., str]
197
Mongetter = Callable[[], "pymongo.collection.Collection"]
198
RedisClient = Union["redis.Redis", Callable[[], "redis.Redis"]]
199
Backend = Literal["pickle", "mongo", "memory", "redis", "sql"]
200
201
class Params:
202
"""Global configuration parameters dataclass."""
203
caching_enabled: bool = True
204
hash_func: HashFunc = _default_hash_func
205
backend: Backend = "pickle"
206
mongetter: Optional[Mongetter] = None
207
stale_after: timedelta = timedelta.max
208
next_time: bool = False
209
cache_dir: Union[str, os.PathLike] = LazyCacheDir() # XDG-compliant cache directory or ~/.cachier/
210
pickle_reload: bool = True
211
separate_files: bool = False
212
wait_for_calc_timeout: int = 0
213
allow_none: bool = False
214
cleanup_stale: bool = False
215
cleanup_interval: timedelta = timedelta(days=1)
216
```
217
218
## Deprecated Functions
219
220
Legacy functions maintained for backwards compatibility:
221
222
```python { .api }
223
def set_default_params(**params: Any) -> None:
224
"""
225
Deprecated: Use set_global_params instead.
226
Configure default parameters applicable to all memoized functions.
227
"""
228
229
def get_default_params() -> Params:
230
"""
231
Deprecated: Use get_global_params instead.
232
Get current set of default parameters.
233
"""
234
```
235
236
## Command Line Interface
237
238
Cachier provides a command-line interface for managing cache behavior:
239
240
```bash
241
# Set maximum number of worker threads
242
python -m cachier set_max_workers 16
243
```
244
245
### CLI Commands
246
247
```bash { .api }
248
cachier --help # Show help information
249
cachier set_max_workers <number> # Set maximum worker threads for background operations
250
```
251
252
The CLI allows configuration of cachier's thread pool used for background cache operations like cleanup and refresh tasks.