proxywhirl.cache.models

Pydantic models for cache data structures.

Defines data models for cache entries, configurations, and statistics used across the three-tier caching system (L1/L2/L3).

Classes

CacheConfig	Configuration for cache behavior and tier settings.
CacheEntry	Container for a single cached proxy with metadata.
CacheStatistics	Aggregate cache statistics across all tiers.
CacheTierConfig	Configuration for a single cache tier.
CacheTierType	Type of cache tier.
L2BackendType	L2 cache backend type.
TierStatistics	Statistics for a single cache tier.

Module Contents

class proxywhirl.cache.models.CacheConfig(/, **data)

Bases: pydantic.BaseModel

Configuration for cache behavior and tier settings.

Aggregates configuration for all three tiers plus global settings like TTL, cleanup intervals, and storage paths.

Example

>>> config = CacheConfig(
...     default_ttl_seconds=3600,
...     l1_config=CacheTierConfig(max_entries=1000),
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

class Config

Pydantic config.

class proxywhirl.cache.models.CacheEntry(/, **data)

Bases: pydantic.BaseModel

Container for a single cached proxy with metadata.

Stores proxy information with TTL, health status, and access tracking. Credentials are SecretStr in memory, encrypted at rest in L2/L3.

Example

>>> entry = CacheEntry(
...     key="abc123",
...     proxy_url="http://proxy.com:8080",
...     source="fetched",
...     fetch_time=datetime.now(timezone.utc),
...     ttl_seconds=3600,
... )
>>> entry.is_expired
False

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

class Config

Pydantic config.

property is_expired: bool

Check if entry has expired based on TTL.

Return type:

bool

property is_healthy: bool

Check if proxy is healthy enough to use.

Return type:

bool

class proxywhirl.cache.models.CacheStatistics(/, **data)

Bases: pydantic.BaseModel

Aggregate cache statistics across all tiers.

Combines tier-level statistics and tracks cross-tier operations like promotions and demotions.

Example

>>> stats = CacheStatistics()
>>> stats.l1_stats.hits = 100
>>> stats.overall_hit_rate
1.0

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

to_metrics_dict()

Convert to flat metrics dict for monitoring systems.

Return type:

dict[str, float]

property overall_hit_rate: float

Overall hit rate across all tiers.

Return type:

float

property total_size: int

Total cached entries across all tiers.

Return type:

int

class proxywhirl.cache.models.CacheTierConfig(/, **data)

Bases: pydantic.BaseModel

Configuration for a single cache tier.

Defines capacity, eviction policy, and enable/disable state for one tier (L1, L2, or L3).

Example

>>> config = CacheTierConfig(max_entries=1000, eviction_policy="lru")

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

classmethod validate_policy(v)

Validate eviction policy is supported.

Parameters:

v (str)

Return type:

str

class proxywhirl.cache.models.CacheTierType

Bases: str, enum.Enum

Type of cache tier.

Initialize self. See help(type(self)) for accurate signature.

class proxywhirl.cache.models.L2BackendType

Bases: str, enum.Enum

L2 cache backend type.

Determines which storage backend is used for the L2 disk cache tier.

• JSONL: File-based using JSON Lines format. Human-readable, portable, best for <10K entries. Uses sharded files with file locking.

• SQLITE: Database-based using SQLite. Faster for >10K entries with O(log n) indexed lookups. Better concurrency and atomic operations.

Initialize self. See help(type(self)) for accurate signature.

class proxywhirl.cache.models.TierStatistics(/, **data)

Bases: pydantic.BaseModel

Statistics for a single cache tier.

Tracks hits, misses, evictions by reason, and computes hit rate.

Example

>>> stats = TierStatistics(hits=100, misses=20)
>>> stats.hit_rate
0.8333...

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

property hit_rate: float

Cache hit rate (0.0 to 1.0).

Return type:

float

property total_evictions: int

Total evictions across all reasons.

Return type:

int