### Install Cachebox

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/README.md

Install the Cachebox library using pip. Ensure you have Python 3.10+.

```bash
pip install -U cachebox
```

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

### Install cachebox using pip

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/installation.md

Use this command to install or upgrade cachebox with pip.

```console
$ pip install -U cachebox
```

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

### Install cachebox using uv

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/installation.md

Use this command to add cachebox to your project with uv.

```console
$ uv add cachebox
```

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

### Install cachebox with pip

Source: https://github.com/awolverp/cachebox/blob/main/README.md

Install the cachebox library using pip. Ensure you are using pip3 for Python 3.

```bash
pip3 install -U cachebox
```

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

### Verify cachebox installation

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/installation.md

This Python snippet imports the cachebox library and prints its version to confirm successful installation.

```python
import cachebox
print(cachebox.__version__)
```

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

### Configuration

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/INDEX.txt

Details all available constructor and decorator parameters, thread safety options, feature flags, and provides configuration examples.

```APIDOC
## Configuration

This document details CacheBox configuration options:

*   All constructor parameters for caches.
*   Decorator parameters with their default values.
*   Thread safety configuration settings.
*   Feature flags.
*   Illustrative configuration examples.
*   Memory management options.
```

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

### Example Usage of _PostProcess

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/types.md

Demonstrates using a custom transformation function with the `cached()` decorator via the `postprocess` parameter.

```python
from cachebox import cached, LRUCache

def custom_transform(value):
    if isinstance(value, dict):
        return {k: v * 2 for k, v in value.items()}
    return value

@cached(LRUCache(100), postprocess=custom_transform)
def get_data():
    return {'a': 1, 'b': 2}
```

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

### Initialize LRUCache and Get Current Size

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-basecache.md

Demonstrates initializing an LRUCache and retrieving its current size. By default, each entry contributes a size of 1.

```python
from cachebox import LRUCache

cache = LRUCache(maxsize=100)
cache['a'] = 10
cache['b'] = 20
print(cache.current_size())  # 2 (each entry has size 1 by default)
```

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

### Example Usage of _Callback

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/types.md

Demonstrates using a callback function to track cache events (hit/miss) with the `cached()` decorator.

```python
from cachebox import cached, LRUCache, EVENT_HIT, EVENT_MISS

def track_events(event, key, value):
    if event == EVENT_HIT:
        print(f"Cache hit for {key}")
    else:
        print(f"Cache miss for {key}, computed {value}")

@cached(LRUCache(100), callback=track_events)
def expensive(x):
    return x ** 2
```

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

### Example Usage of CacheInfo

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/types.md

Demonstrates how to use the @cached decorator and retrieve cache statistics using get_cached_cache_info. Shows how to interpret hits, misses, and memory usage.

```python
from cachebox import cached, LRUCache, get_cached_cache_info

@cached(LRUCache(maxsize=100))
def compute(x):
    return x * 2

compute(5)
compute(5)
compute(10)

info = get_cached_cache_info(compute)
print(f"Hits: {info.hits}")  # 1
print(f"Misses: {info.misses}")  # 2
print(f"Memory: {info.memory} bytes")
```

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

### Transform Results with Postprocessor Function

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/getting-started.md

Apply a postprocessor function to transform results before they are returned. This example logs the result before returning it.

```python
import cachebox

def postprocess(result):
    print(f"RESULT: {result}")
    return result

@cachebox.cached(
    cachebox.LRUCache(0),
    postprocess=postprocess,
)
def add(a, b):
    return a + b

add(1, 2)   # RESULT: 3
```

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

### Get Cachebox Version Information

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Displays the current version of the Cachebox library and the status of a compile-time feature.

```python
import cachebox
print(cachebox.__version__)  # Current version

from cachebox._core import _use_small_offset_feature
print(_use_small_offset_feature)  # Compile-time feature
```

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

### Custom Cache Sizing Functions

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Provides examples of defining custom sizing functions for caches, allowing them to be based on memory footprint, string length, or a combination of factors, rather than just the entry count.

```python
import sys

# Size by memory footprint
cache = LRUCache(
    maxsize=1_000_000,  # 1MB
    getsizeof=lambda k, v: sys.getsizeof(v)
)

# Size by string length
cache = LRUCache(
    maxsize=10000,  # 10k chars total
    getsizeof=lambda k, v: len(str(v))
)

# Mixed
def size_fn(key, value):
    if isinstance(value, str):
        return len(value)
    elif isinstance(value, list):
        return len(value)
    else:
        return 1

cache = LRUCache(maxsize=1000, getsizeof=size_fn)
```

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

### get(key, default=None)

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-basecache.md

Retrieves the value associated with a key. If the key is not found, it returns a specified default value (which is `None` by default).

```APIDOC
## get(key, default=None)

### Description
Retrieves the value for a given key, returning a default if the key is not found.

### Method
`get`

### Parameters
#### Path Parameters
- **key** (Any) - Required - The key to look up.
- **default** (Any) - Optional - Default `None` - Value to return if key is not found.

### Returns
- **Any** - The value associated with the key, or `default` if not found.

### Example
```python
cache = LRUCache(maxsize=100)
cache['exists'] = 'found'
print(cache.get('exists'))          # 'found'
print(cache.get('missing'))         # None
print(cache.get('missing', 'fallback'))  # 'fallback'
```
```

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

### Custom Key Maker Function

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/configuration.md

Provides an example of a custom key maker function that uses only the first positional argument as the cache key.

```python
from cachebox import cached, LRUCache

def custom_key_maker(*args, **kwargs):
    # Only use first positional arg as key
    return args[0] if args else None

@cached(LRUCache(100), key_maker=custom_key_maker)
def func(important, *ignored):
    return important * 2
```

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

### Cache Events with Callback Function

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/getting-started.md

Implement callbacks for cache events (hit/miss) using the `callback` parameter. This example logs cache misses and hits.

```python
import cachebox

def on_cache_event(event: int, key, value):
    if event == cachebox.EVENT_MISS:
        print(f"MISS  key={key}")
    elif event == cachebox.EVENT_HIT:
        print(f"HIT   key={key}")

@cachebox.cached(
    cachebox.LRUCache(0),
    callback=on_cache_event,
)
def add(a, b):
    return a + b

add(1, 2)   # MISS  key=(1, 2)
add(1, 2)   # HIT   key=(1, 2)
```

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

### Catching KeyError in Cachebox

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/errors.md

Demonstrates how to catch a KeyError when accessing a non-existent key in a cache. This is useful when you need to handle missing keys gracefully, for example, by providing a default value.

```python
from cachebox import LRUCache

cache = LRUCache(maxsize=100)

try:
    value = cache['nonexistent']
except KeyError:
    print("Key not found in cache")

# With default
value = cache.pop('nonexistent', 'default_value')
print(value)  # 'default_value'
```

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

### Get Cache Info using Utility Function

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/tips.md

Shows how to use `cachebox.get_cached_cache_info` to retrieve cache statistics for a decorated function, offering a way to bypass potential linting issues.

```python
import cachebox

@cachebox.cached(
    cachebox.LFUCache(maxsize=20),
)
def add(a: int, b: int) -> int:
    return a + b

cache_info = cachebox.get_cached_cache_info(add) # CacheInfo(hits=0, misses=0, maxsize=20, size=0)
```

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

### Initialize Cache with Different Options

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Demonstrates initializing the Cache with varying configurations, including simple capacity, initial data, and a custom size function.

```python
from cachebox import Cache

# Simple cache with fixed capacity
cache = Cache(maxsize=100)
cache['key'] = 'value'

# With initial data
cache = Cache(maxsize=100, iterable={'a': 1, 'b': 2})

# With custom size function (by byte length)
cache = Cache(
    maxsize=1000,
    getsizeof=lambda k, v: len(str(k)) + len(str(v))
)
```

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

### `get(key, default=None)`

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Safely retrieves a value using a key, returning a specified default value if the key is not found or has expired. This method has the same side effects on cache policies as `__getitem__`.

```APIDOC
## `get(key, default=None)`

### Description
Safe retrieval with a fallback default value. This method has the same side effects on cache policies as `__getitem__` but returns the specified default value instead of raising a `KeyError`.

### Method
`get(key, default=None)`

### Parameters
#### Path Parameters
- **key** (Any) - Required - The key to retrieve.
- **default** (Any) - Optional - The value to return if the key is not found or has expired. Defaults to `None`.

### Returns
- **value** (Any) - The cached value if the key is found, otherwise the `default` value.

### Example
```python
from cachebox import LRUCache

cache = LRUCache(maxsize=100)
cache['count'] = 42

# Safe retrieval
count = cache.get('count')  # 42
missing = cache.get('missing')  # None
fallback = cache.get('missing', 0)  # 0
```
```

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

### Get Number of Entries in Cache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-basecache.md

Demonstrates how to get the count of key-value pairs currently stored in the cache using the len() function.

```python
cache = LRUCache(maxsize=100)
cache['key1'] = 'value1'
cache['key2'] = 'value2'
print(len(cache))  # 2
```

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

### Initialize VTTLCache and Insert Entries

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Create a VTTLCache instance and insert items with explicit TTLs in seconds.

```python
from cachebox import VTTLCache

cache = VTTLCache(maxsize=100)

# Insert with explicit TTL (5 seconds)
cache.insert('short_lived', 'value', 5.0)

# Insert with longer TTL (60 seconds)
cache.insert('longer_lived', 'value', 60.0)
```

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

### Python LRUCache Safe Get with Default Value

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Illustrates using the `get` method for safe retrieval from an LRUCache. It returns a default value instead of raising a KeyError if the key is not found or expired. This method also has the same side effects on cache order as direct access.

```python
from cachebox import LRUCache

cache = LRUCache(maxsize=100)
cache['count'] = 42

# Safe retrieval
count = cache.get('count')  # 42
missing = cache.get('missing')  # None
fallback = cache.get('missing', 0)  # 0
```

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

### Get Most Recently Used Entry (LRU)

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Returns the most recently accessed entry in the cache. This method is specific to LRUCache.

```APIDOC
## `most_recently_used()` (LRUCache)

### Description
Returns the most recently accessed entry.

### Method
`most_recently_used(self) -> tuple[Any, Any]`

### Parameters
None

### Returns
(key, value) tuple.
```

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

### Initialize FIFOCache and Add Elements

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Initialize a FIFOCache with a maximum size and add elements. Demonstrates eviction of the oldest element when the cache is full.

```python
from cachebox import FIFOCache

cache = FIFOCache(maxsize=3)
cache['a'] = 1
cache['b'] = 2
cache['c'] = 3
# Cache is full

cache['d'] = 4  # Evicts 'a' (oldest insertion)
print('a' in cache)  # False
```

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

### Retrieve Value with Default Fallback

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-basecache.md

The `get` method retrieves a value by key. If the key is not found, it returns a specified default value instead of raising an error. This is useful for safely accessing potentially missing cache entries.

```python
cache = LRUCache(maxsize=100)
cache['exists'] = 'found'
print(cache.get('exists'))          # 'found'
print(cache.get('missing'))         # None
print(cache.get('missing', 'fallback'))  # 'fallback'
```

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

### LFUCache Constructor and Basic Usage

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Initializes an LFUCache with a maximum size and demonstrates adding items and accessing them to influence eviction based on frequency.

```python
from cachebox import LFUCache

cache = LFUCache(maxsize=3)
cache['a'] = 1
cache['b'] = 2
cache['c'] = 3

# Access 'a' 3 times, 'b' 2 times, 'c' 0 times
for _ in range(3):
    cache['a']
for _ in range(2):
    cache['b']

cache['d'] = 4  # Evicts 'c' (frequency 0)
```

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

### Basic Cache Operations: Insert, Retrieve, Check

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Demonstrates fundamental cache operations including inserting/updating key-value pairs, retrieving values safely or with defaults, and checking for key existence.

```python
cache = LRUCache(maxsize=100)

# Insert/Update
cache['key'] = 'value'
old_value = cache.insert('key', 'value')  # Returns old value or None

# Retrieve
value = cache['key']  # Raises KeyError
value = cache.get('key')  # Returns None if not found
value = cache.get('key', 'default')  # Returns default
```

```python
# Check/Remove
'key' in cache  # True if exists
cache.contains('key')  # Same as above
```

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

### Checking Cache Size Metrics

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Demonstrates how to retrieve various size-related metrics for a cache, including the current number of entries, remaining capacity, total allocated capacity, and the approximate memory usage in bytes.

```python
print(f"{cache.current_size()}/{cache.maxsize}")
print(f"Remaining: {cache.remaining_size()}")
print(f"Allocated: {cache.capacity()}")
print(f"Memory: {cache.__sizeof__()} bytes")
```

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

### Access TTLCache sweep_interval property

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Get the interval in seconds at which the background sweeper thread removes expired entries from the TTLCache.

```python
cache = TTLCache(maxsize=100, global_ttl=30.0)
print(f"Sweeping every {cache.sweep_interval} seconds")
```

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

### Get Items with Expiration Info (TTL/VTTL)

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Returns an iterable of (key, value, ttl_remaining) for all non-expired entries in TTLCache or VTTLCache.

```APIDOC
## `items_with_expire()` (TTLCache, VTTLCache)

### Description
Returns (key, value, ttl_remaining) for all non-expired entries.

### Method
`items_with_expire(self) -> Iterable[tuple[Any, Any, float]]`

### Parameters
None

### Returns
Iterator over (key, value, seconds_remaining) tuples.
```

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

### Saving and Loading Cache to Disk

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/getting-started.md

Illustrates how to save a Cachebox cache to disk using Python's pickle module and then load it back. Ensure the cache object is compatible with pickle.

```python
import cachebox, pickle

cache = cachebox.LRUCache(100, {i: i for i in range(50)})

with open("cache.pkl", "wb") as f:
    pickle.dump(cache, f)

with open("cache.pkl", "rb") as f:
    loaded = pickle.load(f)

assert cache == loaded
```

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

### Import FIFOCache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Import the FIFOCache class from the cachebox library.

```python
from cachebox import FIFOCache
```

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

### Get String Representation of Cache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-basecache.md

Returns a string representation of the cache, including its type and contents. Useful for debugging and inspection.

```python
def __repr__(self) -> str
```

```python
cache = LRUCache(maxsize=100)
cache['a'] = 1
print(repr(cache))  # LRUCache({'a': 1}, maxsize=100, ...)
```

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

### Import TTLCache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Import the TTLCache class from the cachebox library.

```python
from cachebox import TTLCache
```

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

### Iterate Over Items with Remaining TTL

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Use `items_with_expire()` to get an iterable of (key, value, ttl_remaining) tuples for all non-expired entries in the cache.

```python
cache = TTLCache(maxsize=100, global_ttl=60.0)
cache.update({'a': 1, 'b': 2, 'c': 3})

for key, value, ttl in cache.items_with_expire():
    print(f"{key}: {value} (expires in {ttl:.1f}s)")
```

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

### Using FIFOCache Directly

Source: https://github.com/awolverp/cachebox/blob/main/README.md

Demonstrates using a cache algorithm like FIFOCache directly as a dictionary, without the @cachebox.cached decorator. This allows manual control over caching.

```python
from cachebox import FIFOCache

cache = FIFOCache(maxsize=128)
cache["key"] = "value"
assert cache["key"] == "value"

# You can also use `cache.get(key, default)`
assert cache.get("key") == "value"
```

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

### Import VTTLCache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Import the VTTLCache class from the cachebox library.

```python
from cachebox import VTTLCache
```

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

### Get Items with Frequency (LFU)

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Returns an iterable of tuples, where each tuple contains the key, value, and access frequency for each item in the LFUCache.

```APIDOC
## `items_with_frequency()` (LFUCache)

### Description
Returns an iterable of (key, value, frequency) tuples.

### Method
`items_with_frequency(self) -> Iterable[tuple[Any, Any, int]]`

### Parameters
None

### Returns
Iterator over (key, value, access_count) tuples.
```

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

### TTLCache Advanced Operations

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Details on getting items with their remaining TTL, iterating through items with TTL info, and manual expiration control.

```APIDOC
## TTLCache Advanced Operations

### Description
This section focuses on the advanced features of `TTLCache`, including retrieving items along with their remaining Time To Live (TTL), iterating over items that include their TTL information, and managing cache expiration manually. It also covers stopping the background sweeper thread.

### Methods
- `get_with_expire(key)`: Retrieves the value for a given key and its remaining TTL. Returns `None` if the key is not found or has expired.
- `items_with_expire()`: An iterator yielding tuples of (key, value, ttl_remaining) for all items in the cache.
- `expire()`: Manually triggers the expiration of any expired items in the cache.
- `stop_sweeper()`: Disables the background thread that periodically cleans up expired items.

### Example Usage
```python
from cachebox import TTLCache
import time

# Initialize TTLCache with a global TTL of 5 seconds
cache = TTLCache(maxsize=100, global_ttl=5.0)

cache['persistent_key'] = 'persistent_value'
cache.insert('expiring_key', 'expiring_value', ttl=2.0) # Specific TTL of 2 seconds

time.sleep(1) # Wait for 1 second

# Get with TTL info
result = cache.get_with_expire('expiring_key')
if result:
    value, ttl_remaining = result
    print(f"Expiring key: {value}, Expires in {ttl_remaining:.1f}s")
else:
    print("Expiring key not found or expired.")

time.sleep(2) # Wait for 2 more seconds (total 3 seconds elapsed)

# Iterate with TTL info
print("Items with TTL info:")
for key, value, ttl in cache.items_with_expire():
    print(f"{key}: {value}, {ttl:.1f}s remaining")

# Manually expire items (though they would expire naturally soon)
cache.expire()

# Stop the background sweeper if no longer needed
# cache.stop_sweeper()
```
```

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

### Importing Cachebox Types

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/types.md

Demonstrates importing various types and constants from different modules within the cachebox library.

```python
from cachebox import (
    CacheInfo,
    EVENT_HIT,
    EVENT_MISS,
    Frozen,
    BaseCacheImpl,
    Cache,
    FIFOCache,
    RRCache,
    LRUCache,
    LFUCache,
    TTLCache,
    VTTLCache,
)
```

```python
from cachebox._core import (
    BaseCacheImpl,
    Cache,
    FIFOCache,
    RRCache,
    LRUCache,
    LFUCache,
)
```

```python
from cachebox._cachebox import (
    TTLCache,
    VTTLCache,
)
```

```python
from cachebox._wrappers import (
    CacheInfo,
    EVENT_HIT,
    EVENT_MISS,
)
```

```python
from cachebox import (
    cached,
    is_cached,
    get_cached_cache,
    get_cached_cache_info,
    get_cached_callback,
    clear_cached_cache,
)
```

```python
from cachebox import (
    postprocess_copy,
    postprocess_copy_mutables,
    postprocess_deepcopy,
    postprocess_deepcopy_mutables,
)
```

```python
from cachebox import (
    make_key,
    make_hash_key,
    make_typed_key,
)
```

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

### Per-Instance Caching with Callable

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/configuration.md

Illustrates how to use a lambda function to provide a per-instance cache for a method within a class.

```python
# Per-instance cache
class MyClass:
    def __init__(self):
        self._cache = LRUCache(100)
    
    @cached(lambda self: self._cache)
    def compute(self, x):
        return x * 2
```

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

### Get Most Recently Used Entry in LRUCache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Use `most_recently_used()` to retrieve the entry that was accessed most recently in an `LRUCache`. This method does not remove the entry.

```python
cache = LRUCache(maxsize=3)
cache['a'] = 1
cache['b'] = 2
cache['c'] = 3

# Access 'b'
val = cache['b']

key, value = cache.most_recently_used()
print(f"Most recent: {key}={value}")  # b=2
```

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

### Instance-Specific Caching in Methods

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Demonstrates the correct way to implement per-instance caching for methods using Cachebox decorators.

```python
# ❌ Wrong: Every instance shares cache
@cached(LRUCache(100))
def method(self, x):
    return x * 2

# ✅ Right: Per-instance cache
@cached(lambda self: self._cache)
def method(self, x):
    return x * 2
```

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

### Iterate Over Cache Keys

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Use the `keys()` method to get an iterable of all keys in the cache. This is useful for processing all keys or collecting them into a list.

```python
from cachebox import LRUCache

cache = LRUCache(maxsize=100)
cache.update({'a': 1, 'b': 2, 'c': 3})

for key in cache.keys():
    print(f"Key: {key}")

# Collect keys into list
all_keys = list(cache.keys())
print(all_keys)  # ['a', 'b', 'c'] or in different order
```

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

### Configure Production API Cache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/configuration.md

Sets up a TTLCache for API responses with a maximum size of 10MB and a global time-to-live of 5 minutes. Includes a rough size estimation function.

```python
from cachebox import TTLCache
from datetime import timedelta

# API responses cached for 5 minutes, max 10MB
api_cache = TTLCache(
    maxsize=10_000_000,  # 10MB limit
    global_ttl=timedelta(minutes=5),
    capacity=1000,
    getsizeof=lambda k, v: len(str(v))  # Rough size estimate
)
```

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

### Get Least Frequently Used Entry (LFU)

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Returns the entry with the lowest access frequency, which is the candidate for eviction. This method is specific to LFUCache.

```APIDOC
## `least_frequently_used()` (LFUCache)

### Description
Returns the entry with lowest access frequency (will be evicted first).

### Method
`least_frequently_used(self) -> tuple[Any, Any]`

### Parameters
None

### Returns
(key, value) tuple.
```

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

### Safe Iteration with Snapshot

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/advanced-features.md

Demonstrates how to safely iterate over a cache while modifying it by taking a snapshot of keys first. This prevents issues that can arise from modifying a collection during iteration.

```python
cache = LRUCache(100)
cache.update({'a': 1, 'b': 2, 'c': 3})

# Snapshot to avoid issues during modification
keys_snapshot = list(cache.keys())

for key in keys_snapshot:
    if key in cache:  # Key might have been deleted
        value = cache.get(key)
        # Safe to modify cache here
        cache.pop(key)
```

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

### Get Oldest Entry (FIFO/TTL)

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Returns the oldest entry in the cache (which will be evicted first) without removing it. Raises KeyError if the cache is empty.

```APIDOC
## `first()` (FIFOCache, TTLCache)

### Description
Returns the oldest entry (will be evicted first) without removing it.

### Method
`first(self) -> tuple[Any, Any]`

### Parameters
None

### Returns
(key, value) tuple.

### Raises
`KeyError` if cache is empty.
```

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

### Iterating Over Cache Keys

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Highlights the importance of documenting or snapshotting cache keys if order is a concern, as iteration order is undefined.

```python
# ❌ Wrong: Expecting order
for key in cache.keys():  # Order undefined
    print(key)

# ✅ Right: If order matters, document assumption
# or use list(cache.keys()) snapshot
```

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

### Get Newest Entry with last()

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Retrieve the newest entry (the most recently inserted) from the FIFOCache without removing it. Raises KeyError if the cache is empty.

```python
cache = FIFOCache(maxsize=3)
cache['a'] = 1
cache['b'] = 2
cache['c'] = 3
key, value = cache.last()
print(f"Last (newest): {key}={value}")  # c=3
```

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

### Initialize Cache with Data

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-decorators.md

Pre-populate a cache with initial data when creating the cache instance. This allows cached values to be available immediately without needing to call the decorated function first.

```python
from cachebox import cached, LRUCache

cache = LRUCache(maxsize=100, iterable={'x': 10, 'y': 20})

@cached(cache)
def compute(key):
    return key * 2

print(compute('x'))  # Returns 10 from cache
print(compute('z'))  # Computes 2*'z', then caches
```

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

### Import Main Cache Classes

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Import the primary cache classes and their specialized variants like FIFO, RR, LRU, LFU, TTL, and VTTL caches.

```python
# Main cache classes
from cachebox import Cache, FIFOCache, RRCache, LRUCache, LFUCache
from cachebox import TTLCache, VTTLCache
```

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

### Get Most Recently Used Entry in LRUCache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Returns the key-value pair that was most recently accessed in the LRUCache, without removing it. Raises KeyError if the cache is empty.

```python
cache = LRUCache(maxsize=3)
cache['a'] = 1
cache['b'] = 2
cache['c'] = 3
cache['b']  # Most recent access
key, value = cache.most_recently_used()
print(f"Most recent: {key}={value}")  # b=2
```

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

### Get Least Recently Used Entry (LRU)

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Returns the entry that will be evicted next based on least recent access. This method is specific to LRUCache.

```APIDOC
## `least_recently_used()` (LRUCache)

### Description
Returns the entry that will be evicted next (least recently accessed).

### Method
`least_recently_used(self) -> tuple[Any, Any]`

### Parameters
None

### Returns
(key, value) tuple.
```

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

### Configure Computation Cache with Monitoring

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/configuration.md

Sets up an LRUCache for an expensive computation with a callback to track cache hits and misses. Results are not copied after processing.

```python
from cachebox import cached, LRUCache, EVENT_HIT, EVENT_MISS

stats = {'hits': 0, 'misses': 0}

def track_stats(event, key, value):
    if event == EVENT_HIT:
        stats['hits'] += 1
    else:
        stats['misses'] += 1

@cached(
    LRUCache(maxsize=1000),
    callback=track_stats,
    postprocess=None  # No copying for immutable results
)
def expensive_computation(x):
    return x ** 2
```

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

### Basic Cachebox Usage with LRUCache

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/index.md

Demonstrates how to use Cachebox with an LRUCache decorator to cache the results of a function. The first call to `get_user` will execute the database query, while subsequent calls with the same `user_id` will retrieve the result from the cache.

```python
import cachebox

@cachebox.cached(cachebox.LRUCache(maxsize=128))
def get_user(user_id: int) -> dict:
    # Expensive DB call - cached after first call
    return db.query("SELECT * FROM users WHERE id = ?", user_id)

# First call hits the database
user = get_user(42)

# Subsequent calls are served from cache instantly
user = get_user(42)
```

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

### Get Newest Entry (FIFO/TTL)

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Returns the newest entry in the cache (inserted or updated most recently) without removing it. Raises KeyError if the cache is empty.

```APIDOC
## `last()` (FIFOCache, TTLCache)

### Description
Returns the newest entry (inserted/updated most recently) without removing it.

### Method
`last(self) -> tuple[Any, Any]`

### Parameters
None

### Returns
(key, value) tuple.

### Raises
`KeyError` if cache is empty.
```

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

### Get Oldest Entry with first()

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Retrieve the oldest entry (the one that will be evicted next) from the FIFOCache without removing it. Raises KeyError if the cache is empty.

```python
cache = FIFOCache(maxsize=3)
cache['a'] = 1
cache['b'] = 2
key, value = cache.first()
print(f"First (oldest): {key}={value}")  # a=1
```

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

### Instantiate TTLCache with seconds

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Create a TTLCache instance with a maximum size and a global TTL specified in seconds. Entries will expire after this duration.

```python
from cachebox import TTLCache
from datetime import timedelta

# TTL of 60 seconds
cache = TTLCache(maxsize=100, global_ttl=60.0)
```

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

### Import Frozen Wrapper

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Import the Frozen wrapper for creating immutable cache entries.

```python
# Frozen wrapper
from cachebox import Frozen
```

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

### Get Remaining Cache Size

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-basecache.md

Calculates and prints the remaining available space in the cache. This is determined by subtracting the current size from the maximum allowed size.

```python
cache = LRUCache(maxsize=10)
cache['a'] = 'x'
print(cache.remaining_size())  # 9
```

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

### Iterate Over Items with Frequency in LFUCache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

Use `items_with_frequency()` to get an iterable of (key, value, frequency) tuples for all entries in an `LFUCache`. This is useful for inspecting access counts.

```python
cache = LFUCache(maxsize=100)
cache['a'] = 1
cache['b'] = 2

for _ in range(5):
    cache['a']

for key, value, freq in cache.items_with_frequency():
    print(f"{key}: {value} (accessed {freq} times)")
```

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

### Implement Session Cache with LRUCache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/configuration.md

Creates a session manager using LRUCache with weak references for per-user session data. The `get_profile` method is cached.

```python
from cachebox import cached, LRUCache

# Per-user session cache with weak references
class SessionManager:
    def __init__(self, user_id):
        self.user_id = user_id
        self._cache = LRUCache(maxsize=100)
    
    @cached(lambda self: self._cache)
    def get_profile(self, field):
        return fetch_user_field(self.user_id, field)
```

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

### Get Cache Statistics from Cached Function

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/tips.md

Shows how to retrieve cache statistics (hits, misses, size) from a function decorated with `@cachebox.cached` by calling its `cache_info` attribute.

```python
import cachebox

@cachebox.cached(
    cachebox.LFUCache(maxsize=20),
)
def add(a: int, b: int) -> int:
    return a + b

cache_info = add.cache_info() # CacheInfo(hits=0, misses=0, maxsize=20, size=0)
```

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

### Cachebox: Postprocessing (None)

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Use `postprocess=None` to return cached objects as-is, offering the fastest retrieval but no protection against mutations.

```python
from cachebox import cached, LRUCache

# Return cached object as-is (fastest)
@cached(LRUCache(100), postprocess=None)
def make_tuple():
    return (1, 2, 3)
```

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

### Deadlocking Recursive Function with Default Lock

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/tips.md

This example shows a recursive function that will deadlock when using the default non-reentrant lock. Disable the lock for recursive functions.

```python
# ❌ Deadlocks on any recursive call
@cachebox.cached(cachebox.LRUCache(maxsize=256))
def factorial(n: int) -> int:
    return 1 if n <= 1 else n * factorial(n - 1)
```

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

### LFUCache Operations

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Illustrates how to use LFUCache, focusing on viewing item frequencies and iterating through items along with their counts.

```APIDOC
## LFUCache Operations

### Description
This section details the operations for the Least Frequently Used (LFU) cache. It covers how to identify the item with the lowest access frequency and how to iterate through all items in the cache, displaying each item's key, value, and its corresponding frequency count.

### Methods
- `least_frequently_used()`: Returns the key-value pair with the lowest access frequency.
- `items_with_frequency()`: An iterator that yields tuples of (key, value, frequency) for all items in the cache.

### Example Usage
```python
from cachebox import LFUCache

cache = LFUCache(maxsize=100)

# Add items and access them to affect frequency
cache['a'] = 1
cache['b'] = 2
cache['a'] = 11 # Access 'a' again
cache['c'] = 3
cache['a'] = 111 # Access 'a' again

# View frequency information
least_freq_key, least_freq_value = cache.least_frequently_used()
print(f"Least frequently used: {least_freq_key}={least_freq_value}")

print("Items with frequency:")
for key, value, freq in cache.items_with_frequency():
    print(f"{key}: count={freq}")
```
```

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

### Import BaseCacheImpl

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-basecache.md

Import the BaseCacheImpl class from the cachebox library. This is the base class for all cache implementations.

```python
from cachebox import BaseCacheImpl
```

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

### Import Cache Class

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Import the Cache class from the cachebox library.

```python
from cachebox import Cache
```

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

### Cache Async Function Return Value

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/getting-started.md

The @cached decorator seamlessly supports asynchronous functions (coroutines). This example caches the result of an asynchronous network request.

```python
import cachebox

@cachebox.cached(cachebox.LRUCache(maxsize=128))
async def make_request(method: str, url: str) -> dict:
    response = await client.request(method, url)
    return response.json()
```

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

### Get Least Frequently Used Entry in LFUCache

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/iteration-and-access.md

The `least_frequently_used()` method returns the entry with the lowest access frequency from an `LFUCache`, which is the candidate for eviction. This method does not remove the entry.

```python
cache = LFUCache(maxsize=3)
cache['a'] = 1
cache['b'] = 2
cache['c'] = 3

# Access 'a' and 'b' multiple times
for _ in range(5):
    cache['a']
for _ in range(3):
    cache['b']

# 'c' has frequency 0
key, value = cache.least_frequently_used()
print(f"Will evict: {key}={value}")  # c=2
```

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

### BaseCacheImpl Methods

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/api/impls.md

Core methods available across all cache implementations, including initialization, size management, and basic cache operations.

```APIDOC
## BaseCacheImpl Methods

### Description
Provides fundamental cache operations and management functionalities.

### Methods
- `__init__`: Initializes the cache.
- `maxsize`: Gets or sets the maximum size of the cache.
- `getsizeof`: Returns the size of a given key-value pair.
- `current_size`: Returns the current size of the cache.
- `remaining_size`: Returns the remaining capacity of the cache.
- `capacity`: Returns the total capacity of the cache.
- `__len__`: Returns the number of items in the cache.
- `__contains__`: Checks if a key exists in the cache.
- `contains`: Alias for `__contains__`.
- `is_empty`: Checks if the cache is empty.
- `is_full`: Checks if the cache is full.
- `insert`: Inserts a key-value pair into the cache.
- `__setitem__`: Sets an item in the cache using dictionary-like syntax.
- `update`: Updates an existing key-value pair or inserts a new one.
- `get`: Retrieves the value associated with a key.
- `__getitem__`: Gets an item from the cache using dictionary-like syntax.
- `setdefault`: Inserts a key-value pair if the key does not exist.
- `pop`: Removes and returns the value associated with a key.
- `__delitem__`: Deletes an item from the cache using dictionary-like syntax.
- `popitem`: Removes and returns an arbitrary key-value pair.
- `drain`: Removes items until a certain size is reached.
- `shrink_to_fit`: Reduces the cache size to fit its current contents.
- `clear`: Removes all items from the cache.
- `__eq__`: Compares two cache instances for equality.
- `__ne__`: Compares two cache instances for inequality.
- `items`: Returns a view of the cache's items (key-value pairs).
- `values`: Returns a view of the cache's values.
- `keys`: Returns a view of the cache's keys.
- `__iter__`: Returns an iterator over the cache's keys.
- `copy`: Creates a shallow copy of the cache.
- `__repr__`: Returns a string representation of the cache.
```

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

### Get Cached Callback using Utility Function

Source: https://github.com/awolverp/cachebox/blob/main/docs/docs/tips.md

Illustrates using `cachebox.get_cached_callback` to retrieve the callback function associated with a decorated function, useful for linting and IDE compatibility.

```python
import cachebox

def callback(event, key, value): ...

@cachebox.cached(
    cachebox.LFUCache(maxsize=20),
    callback=callback,
)
def add(a: int, b: int) -> int:
    return a + b

assert cachebox.get_cached_callback(add) is callback
```

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

### Cachebox: Frozen Cache (Ignore Writes)

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Create a read-only cache using `Frozen(cache, ignore=True)`. Writes to this cache are silently ignored, preserving the original cache's state.

```python
from cachebox import Frozen, LRUCache

cache = LRUCache(100)
cache.update({'a': 1, 'b': 2})

# Read-only, ignore writes
frozen = Frozen(cache, ignore=True)
print(frozen['a'])  # 1
frozen['c'] = 3  # Silently ignored
```

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

### TTLCache with Expiration Info

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Demonstrates how to retrieve items from a TTLCache along with their remaining TTL, iterate through items showing their TTL, and manually trigger expiration. Also shows how to stop the background sweeper thread.

```python
from cachebox import TTLCache

cache = TTLCache(maxsize=100, global_ttl=60.0)

# Get with TTL info
result = cache.get_with_expire('key')
if result:
    value, ttl_remaining = result
    print(f"Expires in {ttl_remaining:.1f}s")

# Iterate with TTL
for key, value, ttl in cache.items_with_expire():
    print(f"{key}: {ttl:.1f}s remaining")

# Manual expiration
cache.expire()
cache.stop_sweeper()  # Disable background cleanup
```

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

### Get Cache Capacity

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-basecache.md

Retrieves the current allocated capacity of the cache's internal hash table. This indicates how many elements the cache can hold before needing to reallocate.

```python
cache = LRUCache(maxsize=100, capacity=50)
print(cache.capacity())  # >= 50
```

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

### LRUCache Operations

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Demonstrates how to interact with an LRUCache, including viewing access order and peeking at values without affecting their position.

```APIDOC
## LRUCache Operations

### Description
Provides methods to inspect the Least Recently Used (LRU) order of items in the cache. You can retrieve the least recently used item (next to be evicted) and the most recently used item. The `peek` method allows viewing a value by key without changing its position in the access order.

### Methods
- `least_recently_used()`: Returns the key-value pair that is least recently used.
- `most_recently_used()`: Returns the key-value pair that is most recently used.
- `peek(key)`: Returns the value associated with the given key without updating its usage status.

### Example Usage
```python
from cachebox import LRUCache

cache = LRUCache(maxsize=100)

# Add some items
cache['a'] = 1
cache['b'] = 2
cache['c'] = 3

# View access order
least_recent_key, least_recent_value = cache.least_recently_used()
print(f"Least recently used: {least_recent_key}={least_recent_value}")

most_recent_key, most_recent_value = cache.most_recently_used()
print(f"Most recently used: {most_recent_key}={most_recent_value}")

# Peek at a value
value_b = cache.peek('b')
print(f"Peeked value for 'b': {value_b}")

# Accessing 'b' makes it most recently used
most_recent_key, most_recent_value = cache.most_recently_used()
print(f"Most recently used after peek: {most_recent_key}={most_recent_value}")
```
```

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

### Example Usage of @cached Decorator

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-decorators.md

Demonstrates how to use the @cached decorator with an LRUCache to memoize function results and retrieve cache information. Ensure LRUCache and cached are imported.

```python
from cachebox import cached, LRUCache

@cached(LRUCache(100))
def compute(x):
    return x * 2

compute(5)
compute(5)
compute(10)

info = compute.cache_info()
print(f"Hits: {info.hits}, Misses: {info.misses}")  # Hits: 1, Misses: 2
print(f"Cache memory: {info.memory} bytes")
```

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

### Caching with a Custom Key Function

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/quick-reference.md

Employ a custom key_maker function to control how cache keys are generated. This example uses make_typed_key to differentiate keys based on type.

```python
from cachebox import cached, LRUCache, make_typed_key

@cached(LRUCache(100), key_maker=make_typed_key)
def func(x):
    # f(1) and f(1.0) cached separately
    return x * 2
```

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

### LFUCache Constructor

Source: https://github.com/awolverp/cachebox/blob/main/_autodocs/api-reference-cache-implementations.md

Initializes an LFUCache instance. It evicts entries based on the least frequency of access when the cache reaches its size limit.

```APIDOC
## LFUCache Constructor

### Description
Initializes an LFUCache instance. It evicts entries based on the least frequency of access when the cache reaches its size limit. Tracks how many times each entry has been accessed.

### Parameters
- **maxsize** (int) - Required - The maximum number of items the cache can hold.
- **iterable** (dict | Iterable[tuple] | None) - Optional - An iterable to initialize the cache with.
- **capacity** (int) - Optional - Alias for maxsize.
- **getsizeof** (Callable[[Any, Any], int] | None) - Optional - A function to determine the size of each item.

### Example
```python
from cachebox import LFUCache

cache = LFUCache(maxsize=3)
cache['a'] = 1
cache['b'] = 2
cache['c'] = 3

# Access 'a' 3 times, 'b' 2 times, 'c' 0 times
for _ in range(3):
    cache['a']
for _ in range(2):
    cache['b']

cache['d'] = 4  # Evicts 'c' (frequency 0)
```
```