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.