Python · TardisDevParser op GitHub

Wat het doet

Tardis.dev verkoopt historische marktdata voor crypto exchanges: trades, orderbook snapshots, en meer. Deze tool downloadt die data en slaat hem op schijf op. Verder niets. Hij parseert de data niet, maakt ze niet schoon, en zet ze niet in een database. Het is de eerste stap in een grotere pipeline, en hij doet ook alleen die eerste stap.

De tool heeft twee commando's. tardis-fetch downloadt data. tardis-inspect checkt je API key en laat zien welke data beschikbaar is, zonder iets te downloaden.

Installatie

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Je hebt een Tardis.dev API key nodig. Zet die eenmalig als environment variable.

cp .env.example .env   # edit .env with your real key
export TARDIS_API_KEY=your-tardis-dev-api-key-here

Key checken en data verkennen

Gebruik tardis-inspect voordat je iets downloadt, om te bevestigen dat je key werkt en om te zien wat er beschikbaar is. Het stuurt kleine, read-only requests, dus er wordt niets gedownload.

# Confirm the API key works
tardis-inspect check-key

# List every exchange Tardis.dev has data for
tardis-inspect exchanges

# See data types, symbols, and date ranges for one exchange
tardis-inspect describe binance

Data ophalen

Een fetch-job heeft vijf dingen nodig: een exchange, één of meer data types, één of meer symbols, een startdatum en een einddatum. Je kunt die zetten met command-line flags, of in een YAML-configbestand.

tardis-fetch \
  --exchange binance \
  --data-types trades,book_snapshot_25 \
  --symbols BTCUSDT,ETHUSDT \
  --from-date 2024-01-01 \
  --to-date 2024-01-07 \
  --output-dir ./data

Of met een configbestand, wat makkelijker is om tussen runs te hergebruiken:

exchange: binance
data_types:
  - trades
  - book_snapshot_25
symbols:
  - BTCUSDT
  - ETHUSDT
from_date: "2024-01-01"
to_date: "2024-01-07"
output_dir: ./data
format: csv
overwrite: false
tardis-fetch --config config/example.yaml

Gebruik je beide, dan wint de command-line flag. Een flag overschrijft het configbestand, en het configbestand overschrijft de TARDIS_API_KEY environment variable. Zo kun je één herbruikbaar configbestand bijhouden en per run maar één of twee waardes aanpassen.

Gedownloade bestanden komen terecht op <output_dir>/<exchange>/<data_type>/<symbol>/<date>.csv.gz. Bestaat een bestand al, dan slaat de fetch het over. Geef --overwrite mee om het toch opnieuw te downloaden.

Hoe het werkt

FetchOptions, in config.py, bevat de instellingen voor één fetch-job. Het valideert ze: er moet een exchange gezet zijn, minstens één data type en één symbol moeten gegeven zijn, de startdatum mag niet na de einddatum liggen, en er moet een API key zijn uit één van de drie bronnen. Klopt dat niet, dan gooit het TardisConfigError met een boodschap over wat ontbreekt.

@dataclass
class FetchOptions:
    exchange: str
    data_types: list[str]
    symbols: list[str]
    from_date: date
    to_date: date
    output_dir: Path = Path("./data")
    api_key: str = ""
    format: str = "csv"
    overwrite: bool = False

    def __post_init__(self) -> None:
        if not self.exchange:
            raise TardisConfigError("exchange is required")
        if not self.data_types:
            raise TardisConfigError("at least one data_type is required")
        # ... symbols, dates, and api_key are checked the same way

TardisClient, in client.py, doet het eigenlijke downloaden. Voor elke combinatie van data type, symbol en dag in de datumrange bouwt het een URL, stuurt een GET-request met de API key als bearer token, en streamt de response naar een tijdelijk bestand. Zodra de download klaar is, hernoemt het het tijdelijke bestand naar zijn definitieve naam. Zo laat een mislukte of onderbroken download nooit een half bestand achter op het pad dat een latere run als "al gedownload" zou beschouwen.

def fetch_one(self, data_type: str, symbol: str, day: date) -> Path:
    dest = self.local_path(data_type, symbol, day)
    if dest.exists() and not self.options.overwrite:
        return dest

    url = self.build_url(data_type, symbol, day)
    response = self.session.get(url, stream=True, timeout=60)
    self._raise_for_status(response, url)

    dest.parent.mkdir(parents=True, exist_ok=True)
    tmp_path = dest.with_suffix(dest.suffix + ".part")
    with open(tmp_path, "wb") as f:
        for chunk in response.iter_content(chunk_size=1024 * 256):
            if chunk:
                f.write(chunk)
    tmp_path.replace(dest)
    return dest

De client probeert mislukte requests ook opnieuw. Antwoordt Tardis.dev met een 429 (rate limit) of een 5xx (server error), dan wacht hij even en probeert het opnieuw, tot vijf keer, met een groeiende wachttijd tussen de pogingen. Een 401 of 403 betekent dat de API key is afgewezen, en gooit meteen TardisAuthError in plaats van opnieuw te proberen, want een foute key gaat bij een retry ook niet werken.

TardisInspector, in inspector.py, is de read-only begeleider die tardis-inspect gebruikt. check_credentials() bevestigt dat een API key werkt door een HEAD-request te sturen voor een symbol en datum die gegarandeerd beschikbaar zijn, zodat de key gecheckt kan worden zonder echte data te downloaden. list_exchanges() en describe_exchange() roepen de publieke metadata-API van Tardis.dev aan om exchanges te tonen en te laten zien welke data types, symbols en datumranges elke exchange heeft.

Errors

Drie exception types vangen de manieren waarop een fetch kan mislukken, zodat een caller ze uit elkaar kan houden.

  • TardisConfigError — de fetch options zijn ongeldig, bijvoorbeeld een ontbrekende API key of een einddatum voor de startdatum.
  • TardisAuthError — de API key is afgewezen door Tardis.dev.
  • TardisAPIError — een andere request mislukte, bijvoorbeeld geen data op de opgevraagde URL, of een onverwachte serverrespons.

tardis-fetch vangt alle drie op het hoogste niveau op en sluit af met een andere statuscode per type, zodat het foutype ook in de shell zichtbaar is, naast de boodschap zelf.

Projectstructuur

src/tardis_reader/
    config.py          # FetchOptions: loads, merges, and validates fetch settings
    client.py          # TardisClient: downloads data from the Datasets API
    inspector.py        # TardisInspector: checks the API key, lists available data
    exceptions.py        # TardisConfigError / TardisAuthError / TardisAPIError
    cli.py              # tardis-fetch entrypoint
    inspect_cli.py       # tardis-inspect entrypoint

config/
    example.yaml        # Sample fetch config

tests/
    test_config.py
    test_client.py
    test_inspector.py

De tests dekken het parsen en valideren van options, de download/skip/retry/error-paden in de client, en de credential check en metadata lookups in de inspector. Draai ze met pytest.