Getting started¶

Install¶

Base install (cache, time, retry, async HTTP, logging, parallel):

pip install vayulib

With the pandas/numpy/plotly stack:

pip install 'vayulib[data]'

Vayu targets Python 3.13+.

Your first cached call¶

A decorator-based disk cache with a TTL:

from datetime import timedelta
from vayu.cache import FileCache

cache = FileCache("/tmp/my_cache")

@cache.cached(ttl=timedelta(hours=1))
async def fetch_user(user_id: int) -> dict:
    ...

The cache key is sha256(args + sorted kwargs) by default, so calls with the same arguments share a cache entry.

For an in-process cache, use the module-level mem_cached:

from datetime import timedelta
from vayu import mem_cached

@mem_cached(ttl=timedelta(minutes=5))
def expensive(x: int) -> int:
    ...

See the Caching guide for custom key functions, eviction, and serializer swap.

Timezone-aware time math¶

from vayu import TimeWindow, time_now

window = TimeWindow.behind(hours=6)
print(window.start, window.end, window.duration)

# Intersect two windows (inherits Interval algebra)
other = TimeWindow.ahead(t=time_now(), hours=2)
if window.intersects(other):
    overlap = window & other

TimeWindow reads the TZ environment variable on import and uses it as the default timezone. See Time & scheduling.

Retry with backoff¶

from vayu import retry

@retry(ConnectionError, tries=5, delay=0.5, backoff=2)
async def call_api():
    ...

Works on both sync and async functions — the decorator detects iscoroutinefunction and wraps appropriately. See Retry & jitter.

Fan-out HTTP¶

import asyncio
from vayu.aio import grab_all_urls

urls = {f"user_{i}": f"https://api.example.com/users/{i}" for i in range(100)}
results = asyncio.run(grab_all_urls(urls, concurrency=20, timeout=10))
# results: {"user_0": (200, b"..."), ...}

See Async HTTP & signals.

Opt-in logging¶

The library attaches a NullHandler to its "vayu" logger and never mutates root logging. If you want the library's classic stdout-with-timezone formatter:

import vayu
vayu.configure_logging(level="INFO", tz="Asia/Kolkata")

Or configure your own handler on the vayu logger. See Logging.

Opt-in pandas `.select()`¶

For df.select(col__gt=10, other__in=["a","b"]) ergonomics:

import vayu
vayu.install_pandas_extensions()  # monkey-patches pd.DataFrame / pd.Series

Requires vayulib[data]. See Pandas helpers.