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.