CacheLib

CacheLib provides a unified API interface for various caching backends. Depending on your infrastructure needs, you can use one of the following supported backends:

• DynamoDbCache: For AWS DynamoDB
• FileSystemCache: File-based caching
• MemcachedCache: For Memcached
• MongoDbCache: For MongoDB
• RedisCache: For Redis
• SimpleCache: In-memory, single-process caching
• UWSGICache: For uWSGI
• ValkeyCache: For Valkey

CacheLib is designed with multiple backends that follow a consistent API. While SimpleCache is used for minimal examples, you can swap it for more robust distributed backends by instantiating their respective classes. Common backends include:

• RedisCache
• MemcachedCache

All backends are used in the same way: by creating an instance of the specific cache class and calling its methods.

The SimpleCache class provides a straightforward way to perform basic caching operations like setting, getting, and deleting values. It is a minimal backend implementation suitable for simple use cases.

To use it:

1. Import SimpleCache from cachelib.
2. Instantiate the cache with SimpleCache().
3. Use .set(key, value) to store data.
4. Use .get(key) to retrieve data (returns None if the key does not exist).
5. Use .delete(key) to remove an entry.

from cachelib import SimpleCache

# Create a cache instance
cache = SimpleCache()

# Set a value in the cache
cache.set('my_key', 'my_value')

# Retrieve the value from the cache
value = cache.get('my_key')
print(value)  # Output: my_value

# Delete the value from the cache
cache.delete('my_key')

# Try to retrieve the deleted value
value = cache.get('my_key')
print(value)  # Output: None

To install the core CacheLib library, ensure you are working within a Python virtual environment and run the standard pip install command. CacheLib is a standalone library with no required dependencies for its basic functionality (like SimpleCache or FileSystemCache).

Requirements:

• Python 3.11 or newer.

$ pip install cachelib

Install the cachelib package from PyPI using pip.

pip install cachelib

While the core library has no required dependencies, specific cache backends require additional packages. You can install these using pip extras to ensure the necessary drivers are present for the backend you intend to use.

# For RedisCache
$ pip install cachelib[redis]

# For MemcachedCache
$ pip install cachelib[memcached]

# For DynamoDbCache
$ pip install cachelib[dynamodb]

# For MongoDbCache
$ pip install cachelib[mongodb]

# For ValkeyCache
$ pip install cachelib[valkey]

# For UWSGICache
$ pip install cachelib[uwsgi]

It is recommended to use a virtual environment to manage dependencies and avoid conflicts between projects. You can use the built-in venv module to create and activate an environment.

1. Create the environment

macOS/Linux:

$ mkdir myproject
$ cd myproject
$ python3 -m venv .venv

Windows:

C:\> mkdir myproject
C:\> cd myproject
C:\> py -3 -m venv .venv

2. Activate the environment

macOS/Linux:

$ . .venv/bin/activate

Windows:

C:\> .venv\Scripts\activate

The BaseRedisSerializer is designed for Redis-compatible backends. It uses a specific strategy to ensure compatibility with native Redis operations like INCRBY and DECRBY:

1. Integers: Stored as plain ASCII strings. This allows Redis to perform atomic increments/decrements on the cached value.
2. Other Types: Pickled and prefixed with a ! byte (e.g., b'!...') to distinguish them from plain strings/integers.

This serializer is the base for RedisSerializer, ValkeySerializer, and DynamoDbSerializer.

# Internal behavior example:
# Integer: 123 -> b'123'
# Object: {'a': 1} -> b'!<pickle_data>'

When calling set, add, or set_many, you can specify a timeout.

• Integer/Float: Represents the number of seconds.
  • Note: As of version 0.17.0, float timeouts are deprecated and will be rounded up to the nearest whole second. In future releases, they will raise a TypeError.
• datetime.timedelta: Represents the duration. Subseconds are rounded up to the nearest whole second.
• 0: A timeout of 0 indicates that the cache entry never expires.
• None: Uses the default_timeout configured when the cache instance was initialized.

import datetime as dt

# Using timedelta (Recommended)
cache.set("key", "value", timeout=dt.timedelta(minutes=5))

# Using integer seconds
cache.set("key", "value", timeout=300)

# Never expiring
cache.set("key", "value", timeout=0)

DynamoDbCache is an implementation of BaseCache that uses an AWS DynamoDB table as the storage backend.

Permissions Required

Your server process requires the following IAM permissions on the cache table:

• dynamodb:GetItem
• dynamodb:PutItem

Limitations

• Item Size: DynamoDB items are limited to 400 KB. Because the cache key and expiration time are stored within the item, the maximum size of a cached value will be slightly less than 400 KB.
• TTL: It is recommended to configure the expiration_time_field as the TTL field in DynamoDB so that AWS automatically deletes expired entries.

from cachelib.cache import DynamoDbCache
import datetime

cache = DynamoDbCache(
    table_name='my-cache-table',
    default_timeout=datetime.timedelta(minutes=10),
    key_prefix='app_v1_'
)

cache.set('user_123', {'name': 'Alice'})
value = cache.get('user_123')

The following example demonstrates how to use SimpleCache to perform basic cache operations: creating an instance, setting a value, retrieving a value, and deleting a value.

from cachelib import SimpleCache

# Create a cache instance
cache = SimpleCache()

# Set a value in the cache
cache.set("my_key", "my_value")

# Retrieve the value from the cache
value = cache.get("my_key")
print(value)  # Output: my_value

# Delete the value from the cache
cache.delete("my_key")

# Try to retrieve the deleted value
value = cache.get("my_key")
print(value)  # Output: None