Metadata-Version: 2.4
Name: vayulib
Version: 0.6.1
Author-email: Alok Tripathy <developer@alok.one>
License-Expression: MIT
Requires-Python: <3.14,>=3.13
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: aiohttp<4,>=3.13.2
Requires-Dist: orjson>=3.11.7
Provides-Extra: data
Requires-Dist: numpy<3,>=2.3.0; extra == 'data'
Requires-Dist: pandas-stubs==2.3.2.250926; extra == 'data'
Requires-Dist: pandas<3,>=2.3.3; extra == 'data'
Requires-Dist: plotly<7,>=6.3.1; extra == 'data'
Description-Content-Type: text/markdown

# vayu

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

**Docs:** [vayu.aloktripathy.com](https://vayu.aloktripathy.com)

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

```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 import TimeWindow

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

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

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

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

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

## 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
