# Migration Notice

Python client v3 unifies historical replay, CSV dataset downloads and exchange metadata into one package: `tardis-dev`.

{% hint style="warning" %}
This is a hard break. There is no compatibility layer for `tardis-client`, `TardisClient`, `tardis_dev.datasets`, reconstructors or any temporary shim.
{% endhint %}

## Install the new package

```bash
pip uninstall tardis-client
pip install tardis-dev
```

If you were already using the dataset-download package, upgrade it in place:

```bash
pip install --upgrade tardis-dev
```

## API mapping

| Before                                            | After                                                                |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| `from tardis_client import TardisClient, Channel` | `from tardis_dev import replay, Channel`                             |
| `tardis_client = TardisClient(api_key="...")`     | pass `api_key="..."` directly to `replay()` or `download_datasets()` |
| `tardis_client.replay(...)`                       | `replay(...)`                                                        |
| `from tardis_dev import datasets`                 | `from tardis_dev import download_datasets`                           |
| `datasets.download(...)`                          | `download_datasets(...)`                                             |
| `tardis_client.clear_cache()`                     | `clear_cache()`                                                      |
| `get_exchange_details(exchange)`                  | `get_exchange_details(exchange)`                                     |

## Replay migration

### Before

```python
import asyncio
from tardis_client import TardisClient, Channel


async def main():
    tardis_client = TardisClient(api_key="YOUR_API_KEY")

    async for local_timestamp, message in tardis_client.replay(
        exchange="bitmex",
        from_date="2019-06-01",
        to_date="2019-06-02",
        filters=[Channel("trade", ["XBTUSD"])],
    ):
        print(local_timestamp, message)


asyncio.run(main())
```

### After

```python
import asyncio
from tardis_dev import Channel, replay


async def main():
    async for local_timestamp, message in replay(
        exchange="bitmex",
        from_date="2019-06-01",
        to_date="2019-06-02",
        filters=[Channel("trade", ["XBTUSD"])],
        api_key="YOUR_API_KEY",
    ):
        print(local_timestamp, message)


asyncio.run(main())
```

What changed:

* `TardisClient` is gone; `replay()` is now a top-level async generator
* configuration stays explicit at the call site via keyword arguments
* `Channel.symbols=None` or omitting `symbols` means all symbols for that channel

## Dataset download migration

### Before

```python
from tardis_dev import datasets

datasets.download(
    exchange="deribit",
    data_types=["trades", "incremental_book_L2"],
    symbols=["BTC-PERPETUAL"],
    from_date="2019-11-01",
    to_date="2019-11-02",
    api_key="YOUR_API_KEY",
)
```

### After

```python
from tardis_dev import download_datasets

download_datasets(
    exchange="deribit",
    data_types=["trades", "incremental_book_L2"],
    symbols=["BTC-PERPETUAL"],
    from_date="2019-11-01",
    to_date="2019-11-02",
    api_key="YOUR_API_KEY",
)
```

What changed:

* `datasets` subpackage was removed
* `download()` was renamed to `download_datasets()`
* `download_datasets()` is the synchronous wrapper; use `download_datasets_async()` inside an existing event loop

## Cache cleanup migration

### Before

```python
from tardis_client import TardisClient

tardis_client = TardisClient()
tardis_client.clear_cache()
```

### After

```python
from tardis_dev import clear_cache

clear_cache()
clear_cache(cache_dir="./cache")
```

## Removed APIs

The following public APIs are intentionally removed in v3:

* `TardisClient`
* `reconstruct_market()`
* `tardis_client.reconstructors`
* `tardis_dev.datasets`

## Related docs

* [Quickstart](https://docs.tardis.dev/python-client/quickstart)
* [Replaying Historical Data](https://docs.tardis.dev/python-client/replaying-historical-data)
* [Downloadable CSV Files Quickstart](https://docs.tardis.dev/downloadable-csv-files/overview)
* [Downloadable CSV Files API Reference](https://docs.tardis.dev/downloadable-csv-files/api)