Metadata-Version: 2.4
Name: tt-data-store
Version: 2.0.0
Summary: Local working copy of a remote market-data archive
Author-email: Apurv Salunke <salunke.apurv7@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Tiny-Trader/data-store
Project-URL: Repository, https://github.com/Tiny-Trader/data-store
Project-URL: Issues, https://github.com/Tiny-Trader/data-store/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: pyarrow
Provides-Extra: s3
Requires-Dist: boto3; extra == "s3"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: moto[s3]; extra == "dev"
Requires-Dist: boto3; extra == "dev"
Dynamic: license-file

# tt-data-store

Work with a shared market-data archive as if it were a local folder — backed by S3.

[`tt-data-store` on PyPI](https://pypi.org/project/tt-data-store/) · [GitHub](https://github.com/Tiny-Trader/data-store)

**New here?** Start with the [usage guide](docs/usage.md).

---

## The idea

You have candle data (OHLCV) stored as Parquet files on S3. Multiple people or jobs need to read and write that data without stepping on each other.

`MarketStore` gives you a **local working copy** of the archive:

- Open a folder → catalogue syncs from S3 (instruments + file list)
- Call `read()` → downloads only the Parquet you need
- Call `write()` + `publish()` → share your changes

You never manage S3 keys or checksums by hand.

---

## Install

```bash
pip install "tt-data-store[s3]"
```

Python 3.11+. The `[s3]` extra installs `boto3`.

---

## 30-second example

```python
from tt_data_store import Instrument, MarketStore

store = MarketStore(
    "./data",
    remote="s3://my-bucket/archive",
    region="us-east-1",
)

nifty = Instrument.index("NSE", "NIFTY")

# Read
df = store.read(nifty, start="2026-01-01", end="2026-01-31")

# Write
store.write(nifty, df, source="my-collector", register=True)
store.publish()
```

---

## Documentation

| Guide | What you'll learn |
| ----- | ----------------- |
| [**Usage guide**](docs/usage.md) | Concepts, setup, reading, writing, sync |
| [**API reference**](docs/api.md) | Method signatures and types |

---

## When to use what

| You want to… | Call |
| ------------ | ---- |
| Check if remote moved ahead | `store.drift()` |
| Catch up with remote | `store.sync()` or `store.pull()` |
| Load candles | `store.read(instrument, start=..., end=...)` |
| Save candles locally | `store.write(instrument, candles, source=..., register=True)` |
| Share changes | `store.publish()` |
| See sync state | `store.status()` |

---

## Development

```bash
git clone https://github.com/Tiny-Trader/data-store.git
cd data-store
uv sync --extra dev --extra s3
uv run pytest
```

## License

Apache-2.0 — see [LICENSE](LICENSE).
