vayulib 0.6.1

No project description provided

vayu

Async-first Python utility library for caching, time operations, parallel execution, and more.

Docs: vayu.aloktripathy.com

pip install vayulib             # base: cache, time, retry, aio, log, parallel
pip install 'vayulib[data]'     # adds pandas / numpy / plotly helpers

Core names are importable from the top level: from vayu import mem_cached, retry, TimeWindow, L, Interval, FileCache.

What's inside

Module	Highlights
cache	@cached decorator with TTL, FileCache, MemoryCache, pluggable serializers
aio	grab_all_urls() with rate limiting, sleep_until_signal(), shutdown signal helpers
time_utils	TimeWindow, timeit, to_human_readable_time, timezone-aware datetime helpers
common	@retry with exponential backoff, add_jitter, group, camel_or_space_to_snake
interval	Interval dataclass with union / intersection / containment algebra
parallel	ParallelRunner over thread/process pools with progress tracking, thread-safe collections
pandas_utils (data)	slice_frame, select_frame, split_frame, concat_frame_from_dir
plotly_utils (data)	Plotly chart helpers
statistics (data)	quantile aggregation helper
log	Named logger L ("vayu") with L.i, L.d, L.e, L.w, L.c shorthands; opt-in configure_logging() for stdout with timezone-aware timestamps

Modules marked (data) require the vayulib[data] extra.

Quick examples

from vayu.cache import FileCache, Pickler
from datetime import timedelta

cache = FileCache("/tmp/my_cache", Pickler())

@cache.cached(ttl=timedelta(hours=1))
async def fetch_data(url):
    ...

from vayu.common import retry

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

from vayu import TimeWindow

window = TimeWindow.behind(hours=6)  # last 6 hours
print(window.duration, window.start_ms, window.end_ms)

# Opt-in pandas monkey-patch (requires vayulib[data])
import vayu

vayu.install_pandas_extensions()  # enables df.select(...) and series.select(...)

# Opt-in logging setup (stdout, timezone-aware timestamps).
# Library imports add no handlers to the root logger.
import vayu

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

Command-line tool

Base install ships vayu-dir-to-text for concatenating a directory/Git repo into one text file (handy for pasting into LLMs):

vayu-dir-to-text --dir . --extensions .py .md
vayu-dir-to-text --git_url https://github.com/user/repo.git

Development

uv sync                      # install dependencies
uv run pytest tests/         # run tests
uv run black vayu/ tests/    # format

Release process

1. Bump version in pyproject.toml
2. Merge to main
3. The publish workflow automatically tags and publishes to PyPI if the version is new