Native Caching

Deliver static-site performance with dynamic capabilities. Caspian includes a file-system based caching engine that bypasses the rendering logic for high-traffic routes.

Global Strategy

Control the baseline behavior of your entire application via environment variables. Perfect for switching between development and production modes.

  • Environment-based toggles
  • Default TTL (Time-to-Live)

Page-Level Overrides

Define specific caching rules per route in your index.py. Cache your landing page for hours, but keep your dashboard real-time.

  • Declarative Configuration
  • Single Source of Truth

1. Global Configuration

.env

In your project root, configure the default behavior. When enabled, Caspian creates a caches/ directory to store rendered HTML. 

# Enable caching application-wide (default: false)
CACHE_ENABLED="true"

# Global Time-To-Live in seconds (default: 600s / 10 mins)
CACHE_TTL="3600"
Overrides

2. Granular Control

src/app/**/index.py

Use the declarative Cache class to override global settings. This provides a single, type-safe source of truth for your route's behavior.

src/app/blog/index.py 
from casp.layout import render_page
from casp.cache_handler import Cache

# OPTION A: Declarative Configuration
# Cache this page for 2 hours (7200s), enabling it explicitly
Cache(ttl=7200, enabled=True)

# OPTION B: Force Disable (e.g. for user dashboard)
# Cache(enabled=False)

def page():
    return render_page(__file__)
Request Lifecycle
1
Incoming Request User requests /blog
Check caches/manifest.json
Cache Hit

Valid file exists. Serve HTML directly.
Time: ~2ms

Cache Miss / Expired

Execute index.py logic -> Render -> Save to Disk -> Serve.

Caching Logic Matrix

Caspian determines whether to cache a request based on the interaction between your .env global settings and route-specific overrides.

Global (CACHE_ENABLED) Route (Cache Class) Result
"false" None (default) No Cache
"false" enabled=True Force Cache
"false" enabled=False No Cache
"true" None (default) Cache All
"true" enabled=False Skip Route