### Install toolcache using pip

Source: https://context7.com/sslivkoff/toolcache/llms.txt

This command installs the toolcache library using pip, the Python package installer. Ensure you have pip installed and accessible in your environment.

```bash
pip install toolcache
```

--------------------------------

### Process-Safe Caching with Toolcache

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Demonstrates how to use the @toolcache.cache decorator for process-safe caching. It shows examples for both process-safe and non-thread-safe operations, along with a thread-safe usage example involving multiple threads accessing a cached function.

```python
import toolcache
import threading

# Assume expensive_computation and fast_computation are defined elsewhere
def expensive_computation(key):
    # Simulate an expensive computation
    return f"Computed expensive for {key}"

def fast_computation(key):
    # Simulate a fast computation
    return f"Computed fast for {key}"

@toolcache.cache('disk', safety='process', cache_dir='/tmp/shared_cache')
def process_safe_operation(key):
    """Safe for concurrent access from multiple processes"""
    return expensive_computation(key)

# No safety for maximum performance (single-threaded only)
@toolcache.cache('memory', safety=None)
def fast_single_thread_operation(key):
    """Maximum performance, but not thread-safe"""
    return fast_computation(key)

# Example: Thread-safe usage
def worker(func, values):
    for v in values:
        func(v)

# Assuming thread_safe_operation is a cached function that is thread-safe
# For demonstration, let's use process_safe_operation as an example of a cached function
# In a real scenario, you might have a function specifically designed for thread safety
cache_func = process_safe_operation
threads = [
    threading.Thread(target=worker, args=(cache_func, range(100))),
    threading.Thread(target=worker, args=(cache_func, range(50, 150))),
]
for t in threads:
    t.start()
for t in threads:
    t.join()

print(f"Cache size after concurrent access: {cache_func.cache.get_cache_size()}")
```

--------------------------------

### Configure cache eviction policies with TTL, LRU, FIFO, LFU

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Shows how to manage cache size and entry lifetime using TTL (time-to-live) and various max size eviction policies. Examples include setting expiration times in different formats and implementing LRU, FIFO, and LFU strategies to control which entries are removed when the cache is full.

```python
import toolcache
import time

# Entries expire after specified time-to-live
@toolcache.cache('memory', ttl='24 hours')
def fetch_api_data(endpoint):
    """Cached data expires after 24 hours"""
    return requests.get(endpoint).json()

# Alternative TTL formats
@toolcache.cache('memory', ttl='30m')      # 30 minutes
@toolcache.cache('memory', ttl='1000s')    # 1000 seconds
@toolcache.cache('memory', ttl=3600)       # 3600 seconds (numeric)

# LRU (Least Recently Used) - evicts least recently accessed entries
@toolcache.cache('memory', max_size=100, max_size_policy='lru')
def get_user_profile(user_id):
    """Keep max 100 entries, evict least recently used"""
    return database.fetch_user(user_id)

# FIFO (First In First Out) - evicts oldest entries first
@toolcache.cache('memory', max_size=50, max_size_policy='fifo')
def process_request(request_id):
    """Keep max 50 entries, evict oldest first"""
    return process(request_id)

# LFU (Least Frequently Used) - evicts least accessed entries
@toolcache.cache('memory', max_size=200, max_size_policy='lfu')
def get_product_details(product_id):
    """Keep max 200 entries, evict least frequently accessed"""
    return catalog.get_product(product_id)

# Check which entries remain in cache
@toolcache.cache('memory', max_size=3, max_size_policy='fifo')
def square(x):
    return x ** 2

square(1)
square(2)
square(3)
square(4)  # This evicts square(1) from cache

print(square.cache.get_cache_size())  # Output: 3
print(square.cache.exists_in_cache(args=[1]))  # Output: False
print(square.cache.exists_in_cache(args=[4]))  # Output: True
```

--------------------------------

### Toolcache Cache Methods Reference

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Provides a reference for the methods available on a toolcache cache instance, including computing entry hashes, saving and loading entries, checking existence, getting cache size, retrieving all entry hashes, deleting specific entries, clearing the cache, and accessing the original unwrapped function.

```python
import toolcache

# Assume a simple function for demonstration
def example(x):
    return x * 2

# Apply the cache decorator
cached_example = toolcache.cache('memory')(example)

# Access cache instance
cache = cached_example.cache

# Compute hash for given arguments
entry_hash = cache.compute_entry_hash(args=[5], kwargs={})

# Save entry directly
cache.save_entry(entry_hash='custom_key', entry_data={'result': 100})

# Check if entry exists
exists = cache.exists_in_cache(entry_hash='custom_key')
exists = cache.exists_in_cache(args=[5])  # Using function args

# Load entry from cache
data = cache.load_entry(entry_hash='custom_key')
data = cache.load_entry(args=[5], must_exist=True)  # Raises if not found

# Get current cache size
size = cache.get_cache_size()

# Get all entry hashes
all_hashes = cache.get_all_entry_hashes()

# Delete specific entry
cache.delete_entry(entry_hash='custom_key')
cache.delete_entry(args=[5])

# Clear entire cache
cache.delete_all_entries()

# Access original unwrapped function
original_func = cached_example.__wrapped__

```

--------------------------------

### Standalone Cache Usage with Toolcache

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Demonstrates how to create and manage cache instances directly, without using decorators. Supports memory and disk caches with features like custom keys, entry management, and eviction policies.

```python
import toolcache

# Create standalone memory cache
cache = toolcache.MemoryCache()

# Save entry with custom hash key
entry_hash = 'user_123_profile'
entry_data = {'name': 'John', 'email': 'john@example.com'}
cache.save_entry(entry_hash, entry_data)

# Check if entry exists
exists = cache.exists_in_cache(entry_hash=entry_hash)
print(f"Entry exists: {exists}")  # Output: Entry exists: True

# Load entry from cache
loaded_data = cache.load_entry(entry_hash=entry_hash)
print(loaded_data)  # Output: {'name': 'John', 'email': 'john@example.com'}

# Get cache size
print(f"Cache size: {cache.get_cache_size()}")  # Output: Cache size: 1

# Delete specific entry
cache.delete_entry(entry_hash=entry_hash)

# Create standalone disk cache with eviction
persistent_cache = toolcache.DiskCache(
    cache_dir='/tmp/my_cache',
    max_size=1000,
    max_size_policy='lru',
    ttl='1 hour'
)

# Bulk operations
for i in range(10):
    persistent_cache.save_entry(f'item_{i}', {'value': i * 100})

print(f"All entries: {persistent_cache.get_all_entry_hashes()}")

# Clear all entries
persistent_cache.delete_all_entries()
```

--------------------------------

### Cache Statistics and Monitoring in Toolcache

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Explains how to track cache performance using built-in statistics. Covers basic hit/miss counts and detailed per-entry access patterns, including creation times and access counts.

```python
import toolcache
import pprint

# Basic stats tracking (enabled by default)
@toolcache.cache('memory', track_basic_stats=True)
def multiply(a, b):
    return a * b

multiply(2, 3)  # Miss, computes and saves
multiply(2, 3)  # Hit, loads from cache
multiply(4, 5)  # Miss, computes and saves
multiply(2, 3)  # Hit, loads from cache

pprint.pprint(multiply.cache.stats)
# Output:
# {'n_checks': 4,
#  'n_deletes': 0,
#  'n_hashes': 4,
#  'n_hits': 2,
#  'n_loads': 2,
#  'n_misses': 2,
#  'n_saves': 2,
#  'n_size_evictions': 0,
#  'n_ttl_evictions': 0}

# Detailed stats with per-entry tracking
@toolcache.cache('memory', track_detailed_stats=True)
def fetch_record(record_id):
    return {'id': record_id, 'data': 'sample'}

fetch_record(1)
fetch_record(1)
fetch_record(1)

# Get entry-level statistics
entry_hash = fetch_record.cache.compute_entry_hash(args=[1])
creation_time = fetch_record.cache.get_entry_creation_time(entry_hash)
access_time = fetch_record.cache.get_entry_access_time(entry_hash)
access_count = fetch_record.cache.get_entry_access_count(entry_hash)

print(f"Entry created at: {creation_time}")
print(f"Last accessed at: {access_time}")
print(f"Total accesses: {access_count}")  # Output: Total accesses: 2

# Print comprehensive stats summary
fetch_record.cache.print_cache_stats()
# Output:
# stats for cache fetch_record
# current state:
#     - n_entries: 1
#     - ttl: None
#     - max_size: None
# usage:
#     - n_hits: 2
#     - n_misses: 1
#     - n_saves: 1
# detailed usage:
#     - tracking creation times: True
#     - tracking access times: True
#     - tracking access counts: True
```

--------------------------------

### Controlling Cache Behavior with Toolcache Arguments

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Illustrates how to control caching behavior on a per-call basis using special keyword arguments like `cache_load`, `cache_save`, and `cache_verbose`. It also shows how to handle functions that already have parameters conflicting with these cache arguments.

```python
import toolcache

# Assume fetch_from_api and process are defined elsewhere
def fetch_from_api(resource_id):
    # Simulate fetching data
    return f"Data for {resource_id}"

def process(data, cache_load=None):
    # Simulate processing data
    return f"Processed {data} with cache_load={cache_load}"

@toolcache.cache('memory')
def get_data(resource_id):
    return fetch_from_api(resource_id)

# Normal cached call
result = get_data('item_1')

# Force recomputation (skip loading from cache)
fresh_result = get_data('item_1', cache_load=False)

# Compute but don't save to cache
temp_result = get_data('item_2', cache_save=False)

# Enable verbose logging for this call
result = get_data('item_3', cache_verbose=True)
# Output: [cache] get_data saving to cache

# Combine options
result = get_data('item_4', cache_load=False, cache_save=True, cache_verbose=True)

# Disable added cache arguments if they conflict with function signature
@toolcache.cache('memory', add_cache_args=False)
def func_with_own_args(data, cache_load=None):
    """Function already has cache_load parameter"""
    return process(data, cache_load)

```

--------------------------------

### Async Function Caching with Toolcache

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Shows how to cache asynchronous functions using the same @toolcache.cache decorator syntax. It demonstrates fetching data asynchronously and retrieving it from the cache on subsequent calls, along with accessing cache statistics.

```python
import toolcache
import asyncio
import aiohttp

@toolcache.cache('memory')
async def fetch_async_data(url):
    """Async functions are automatically detected and handled"""
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

async def main():
    # First call fetches and caches
    data1 = await fetch_async_data('https://api.example.com/data')

    # Second call returns from cache
    data2 = await fetch_async_data('https://api.example.com/data')

    print(f"Cache hits: {fetch_async_data.cache.stats['n_hits']}")

asyncio.run(main())

```

--------------------------------

### Create Memory and Disk Caches with toolcache

Source: https://github.com/sslivkoff/toolcache/blob/main/README.md

Demonstrates creating memory and disk caches using the @toolcache.cache decorator. Supports specifying cache directory, time-to-live (ttl), maximum size with eviction policies (fifo, lru, lfu), and custom hash arguments.

```python
import toolcache

# memoize function with memory cache
@toolcache.cache('memory')
def f(a, b, c):
    return a * b * c

# memoize function with disk cache, stored in a tempdir
@toolcache.cache('disk')
def f(a, b, c):
    return a * b * c

# memoize function with disk cache, stored in a persistent dir
@toolcache.cache('disk', cache_dir='/path/to/cache/dir')
def f(a, b, c):
    return a * b * c
    
# remove cache entries once they reach a specific age
@toolcache.cache('disk', ttl='24 hours')
def f(a, b, c):
    return a * b * c

# remove cache entries once cache reaches a specific size
@toolcache.cache('disk', max_size=3, max_size_policy='fifo')
def f(a, b, c):
    return a * b * c

# specify which args are used to create unique hash of inputs
@toolcache.cache('disk', hash_args=['a', 'b'])
def f(a, b, c):
    return a * b * c

# create standalone cache
standalone_cache = toolcache.MemoryCache()
```

--------------------------------

### Configure DiskCache Specifics for Toolcache

Source: https://github.com/sslivkoff/toolcache/blob/main/README.md

Set up disk caching with a specified directory, file format (JSON or Pickle), and custom save/load functions. Allows persistence of cache data to the file system.

```python
import toolcache

def custom_save(entry_path, entry_data):
    # Custom save logic
    pass

def custom_load(entry_path):
    # Custom load logic
    pass

# Example using JSON format and custom save/load functions
@toolcache.cache(
    cache_type='disk',
    cache_dir='/path/to/cache_dir',
    file_format='json',
    f_disk_save=custom_save,
    f_disk_load=custom_load
)
def function_with_disk_cache(data):
    pass

# Example using default pickle format
@toolcache.cache(cache_type='disk', cache_dir='/path/to/another_cache')
def another_disk_cached_function(data):
    pass

```

--------------------------------

### Configure Eviction Policy for Toolcache

Source: https://github.com/sslivkoff/toolcache/blob/main/README.md

Set time-to-live (TTL) and maximum cache size with various eviction policies. Supports LRU, FIFO, and LFU strategies to manage cache space effectively.

```python
import toolcache

# Example with TTL and LRU eviction
@toolcache.cache(ttl='1000s', max_size=1000, max_size_policy='lru')
def cached_function_lru(data):
    pass

# Example with FIFO eviction
@toolcache.cache(max_size=500, max_size_policy='fifo')
def cached_function_fifo(data):
    pass

# Example with LFU eviction
@toolcache.cache(max_size=2000, max_size_policy='lfu')
def cached_function_lfu(data):
    pass

```

--------------------------------

### Cache function results to disk using @toolcache.cache

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Illustrates using the 'disk' cache type for persistence. Cache entries are saved to files, allowing data to survive application restarts. It shows caching to a specific directory, using temporary directories, and customizing file formats like JSON.

```python
import toolcache

# Cache to a specific persistent directory
@toolcache.cache('disk', cache_dir='/path/to/cache/dir')
def fetch_large_dataset(dataset_id):
    """Cache persists across application restarts"""
    return download_dataset(dataset_id)

# Cache to temporary directory (default behavior)
@toolcache.cache('disk')
def process_file(filepath):
    """Cache stored in system tmpdir, cleared on reboot"""
    return read_and_process(filepath)

# Use JSON format instead of pickle
@toolcache.cache('disk', file_format='json')
def get_config(config_name):
    """JSON format is human-readable and cross-language compatible"""
    return load_config(config_name)

# Custom disk I/O for specialized data types
import numpy as np

def save_numpy(cache_path, entry_data):
    np.savez_compressed(cache_path, data=entry_data)

def load_numpy(cache_path):
    return np.load(cache_path)['data']

@toolcache.cache('disk', f_disk_save=save_numpy, f_disk_load=load_numpy)
def compute_matrix(size):
    """Efficiently cache numpy arrays to disk"""
    return np.random.rand(size, size)
```

--------------------------------

### Custom Hash Functions for Toolcache

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Defines custom hash functions to control how cache keys are generated based on input arguments. Supports MD5, SHA256, and inclusion/exclusion of specific arguments.

```python
import hashlib
import toolcache

# Custom hash function using MD5
def md5_hash(raw_bytes):
    return hashlib.md5(raw_bytes).hexdigest()

@toolcache.cache('memory', f_hash=md5_hash)
def process_binary_data(raw_bytes):
    """Cache keyed by MD5 hash of binary input"""
    return transform(raw_bytes)

# Custom hash function for multiple arguments
def custom_multi_hash(data, version, config):
    return f"{hashlib.sha256(data).hexdigest()}_{version}"

@toolcache.cache('memory', f_hash=custom_multi_hash)
def process_with_version(data, version, config):
    """Cache key includes data hash and version, ignores config"""
    return process(data, version, config)

# Include only specific arguments in hash
@toolcache.cache('memory', hash_include_args=['user_id', 'query'])
def search_results(user_id, query, page_size=10, debug=False):
    """Only user_id and query affect cache key; page_size and debug are ignored"""
    return database.search(user_id, query, page_size)

# Exclude specific arguments from hash
@toolcache.cache('memory', hash_exclude_args=['timestamp', 'request_id'])
def get_data(resource_id, timestamp, request_id):
    """timestamp and request_id are excluded from cache key"""
    return fetch(resource_id)

# Normalize hash inputs (positional and keyword args treated equivalently)
@toolcache.cache('memory', normalize_hash_inputs=True)
def add(a, b, c):
    return a + b + c

# Example of normalized calls
add(1, 2, 3)
add(1, 2, c=3)
add(a=1, b=2, c=3)
print(add.cache.get_cache_size())  # Output: 1
```

--------------------------------

### Configure Hashing for Toolcache

Source: https://github.com/sslivkoff/toolcache/blob/main/README.md

Customize how function inputs are hashed for caching. Supports custom hash functions, including specific arguments, or excluding arguments. Useful when default hashing fails or for performance optimization.

```python
import toolcache

# Example with custom hash function
@toolcache.cache(f_hash=lambda x: hash(x))
def my_function(arg1, arg2):
    pass

# Example including specific arguments for hashing
@toolcache.cache(hash_include_args=['arg1', 'arg2'])
def another_function(arg1, arg2, arg3):
    pass

# Example excluding specific arguments from hashing
@toolcache.cache(hash_exclude_args=['arg3', 'arg4'])
def yet_another_function(arg1, arg2, arg3, arg4):
    pass

```

--------------------------------

### Interact with toolcache Caches

Source: https://github.com/sslivkoff/toolcache/blob/main/README.md

Shows how to interact with a cached function in toolcache, including retrieving cache size, accessing usage statistics, and clearing all cache entries.

```python
# get cache size
print(f.cache.get_cache_size())
> 4

# track cache usage statistics
print(f.cache.stats)
> {'n_checks': 6,
>  'n_deletes': 2,
>  'n_hashes': 8,
>  'n_hits': 2,
>  'n_loads': 1,
>  'n_misses': 4,
>  'n_saves': 3,
>  'n_size_evictions': 0,
>  'n_ttl_evictions': 0}

# clear cache
f.cache.delete_all_entries()
```

--------------------------------

### Configure Statistic Tracking for Toolcache

Source: https://github.com/sslivkoff/toolcache/blob/main/README.md

Enable or disable various statistics tracking options. Control basic usage stats, detailed creation/access times, and access counts based on cache policies.

```python
import toolcache

# Example tracking basic stats
@toolcache.cache(track_basic_stats=True)
def function_with_basic_stats(x):
    pass

# Example tracking detailed stats including creation and access times
@toolcache.cache(track_detailed_stats=True, track_creation_times=True, track_access_times=True)
def function_with_detailed_stats(x):
    pass

# Example tracking access counts for LFU policy
@toolcache.cache(track_access_counts=True, max_size_policy='lfu')
def function_with_access_counts(x):
    pass

```

--------------------------------

### Cache function results in memory using @toolcache.cache

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Demonstrates basic in-memory caching with the @toolcache.cache decorator. Results are stored in memory and retrieved if the function is called again with the same arguments. It shows how to check cache size and access statistics.

```python
import toolcache

# Basic memory cache
@toolcache.cache('memory')
def expensive_computation(a, b, c):
    """Results are cached in memory based on input arguments"""
    return a * b * c

# First call computes and caches
result1 = expensive_computation(2, 3, 4)  # Computes: 24

# Second call with same args returns cached value
result2 = expensive_computation(2, 3, 4)  # Returns cached: 24

# Check cache size
print(f"Cache size: {expensive_computation.cache.get_cache_size()}")
# Output: Cache size: 1

# Access cache statistics
print(expensive_computation.cache.stats)
# Output: {'n_checks': 2, 'n_hits': 1, 'n_misses': 1, 'n_saves': 1, ...}
```

--------------------------------

### Concurrency Safety Configuration in Toolcache

Source: https://context7.com/sslivkoff/toolcache/llms.txt

Configures cache safety for concurrent access. Supports 'thread' safety for multi-threaded applications and 'process' safety for multi-process environments.

```python
import toolcache
import threading
import multiprocessing

# Thread-safe cache (default)
@toolcache.cache('memory', safety='thread')
def thread_safe_operation(key):
    """Safe for concurrent access from multiple threads"""
    return expensive_computation(key)

# Example for process safety (if needed, though 'thread' is default and often sufficient)
# @toolcache.cache('memory', safety='process')
# def process_safe_operation(key):
#     return another_expensive_computation(key)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.