# vayu

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

```bash
pip install vayulib
```

## 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` | `TimeWindow`, `timeit`, `to_human_readable_time`, timezone-aware datetime helpers |
| `common` | `Interval` with set operations, `@retry` with exponential backoff, `add_jitter`, `group` |
| `parallel` | `ParallelRunner` over thread/process pools with progress tracking, thread-safe collections |
| `lock` | Redis-based `LongLivedLock` (auto-renewing), `RedisSemaphore` |
| `pandas_utils` | `slice_frame`, `select_frame`, `split_frame`, `concat_frame_from_dir` |
| `log` | Global logger `L` with `L.i`, `L.d`, `L.e`, `L.w`, `L.c` shorthands |

## Quick examples

```python
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):
    ...
```

```python
from vayu.common import retry

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

```python
from vayu.time import TimeWindow

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

## Development

```bash
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
