Python SDK

Installation 

pip install tollmeshcache
pip install tollmeshcache[async]  # For async support

Quick Start 

from tollmeshcache import Client, AsyncClient, ClientConfig
from datetime import timedelta

# Sync client
config = ClientConfig(host='localhost', port=8080)
client = Client(config)

result = client.consume('user-123', 100, timedelta(minutes=1))
if result['ok']:
    print('Request allowed')

client.close()

# Async client
async with AsyncClient(config) as client:
    result = await client.consume('user-123', 100, timedelta(minutes=1))

Features

  • ✅ Sync & async clients
  • ✅ Type hints
  • ✅ Retry logic with exponential backoff
  • ✅ Connection pooling
  • ✅ Comprehensive error handling

API Reference

This section covers rate limiting, replay protection, and caching. This SDK also has full, identical-API support for Job Queues, Sorted Sets, Streams, Pub/Sub, Transactions, Persistence, Pipelines, WASM Scripting, Search, Ranking, and Metrics — see the full API Reference for all of them, with live-verified examples.

Rate Limiting 

result = client.consume(key, limit, window)
# Returns: {'ok': bool, 'remaining': int, 'reset_at': int}

Replay Protection 

result = client.seen(key, ttl)
# Returns: {'seen': bool}

Caching 

client.cache_set(namespace, key, value, ttl)
value, exists = client.cache_get(namespace, key)

Health 

health = client.health()
peers = client.get_peers()

Examples

See examples/ for:

  • rate_limiting.py - Rate limiting scenarios
  • caching.py - Cache-aside patterns
  • replay_protection.py - Replay detection
  • async_example.py - Async operations

Error Handling 

from tollmeshcache import TollMeshError, RateLimitError, ReplayError

try:
    result = client.consume('key', 100, timedelta(minutes=1))
except RateLimitError as e:
    print(f"Rate limited: {e.message}")
except TollMeshError as e:
    print(f"Error {e.code}: {e.message}")

Configuration 

config = ClientConfig(
    host='localhost',
    port=8080,
    timeout=5.0,
    verify_ssl=True,
    api_key='optional-key',
    http_scheme='http',
    max_retries=3,
    retry_backoff=1.0,
    connection_pool_size=10,
)

Testing 

pip install -e ".[dev]"
pytest -v --cov=tollmeshcache