Skip to main content

nautilus_databento/python/
historical.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Python bindings for the Databento historical client.
17
18use std::{fmt::Debug, path::PathBuf};
19
20use nautilus_core::{
21    python::{IntoPyObjectNautilusExt, to_pyexception, to_pyvalue_err},
22    time::get_atomic_clock_realtime,
23};
24use nautilus_model::{
25    enums::BarAggregation,
26    identifiers::{InstrumentId, Symbol, futures::FuturesYearDigits},
27    python::instruments::instrument_any_to_pyobject,
28};
29use pyo3::{
30    IntoPyObjectExt,
31    prelude::*,
32    types::{PyDict, PyList},
33};
34
35use crate::{
36    common::Credential,
37    historical::{DatabentoHistoricalClient as CoreDatabentoHistoricalClient, RangeQueryParams},
38};
39
40/// Python wrapper for the core Databento historical client.
41#[cfg_attr(
42    feature = "python",
43    pyo3::pyclass(module = "nautilus_trader.adapters.databento")
44)]
45#[cfg_attr(
46    feature = "python",
47    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.adapters.databento")
48)]
49pub struct DatabentoHistoricalClient {
50    inner: CoreDatabentoHistoricalClient,
51}
52
53impl Debug for DatabentoHistoricalClient {
54    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
55        f.debug_struct(stringify!(DatabentoHistoricalClient))
56            .field("inner", &self.inner)
57            .finish()
58    }
59}
60
61#[pymethods]
62#[pyo3_stub_gen::derive::gen_stub_pymethods]
63impl DatabentoHistoricalClient {
64    /// Core Databento historical client for fetching historical market data.
65    ///
66    /// This client provides both synchronous and asynchronous interfaces for fetching
67    /// various types of historical market data from Databento.
68    #[new]
69    #[pyo3(signature = (key, publishers_filepath, use_exchange_as_venue, futures_year_digits=None, share_class_space=true))]
70    fn py_new(
71        key: String,
72        publishers_filepath: PathBuf,
73        use_exchange_as_venue: bool,
74        futures_year_digits: Option<u8>,
75        share_class_space: bool,
76    ) -> PyResult<Self> {
77        let futures_year_digits = futures_year_digits
78            .map(FuturesYearDigits::try_from)
79            .transpose()
80            .map_err(to_pyvalue_err)?
81            .unwrap_or_default();
82
83        let clock = get_atomic_clock_realtime();
84
85        let inner = CoreDatabentoHistoricalClient::new(
86            Credential::new(key),
87            publishers_filepath,
88            clock,
89            use_exchange_as_venue,
90        )
91        .map(|client| {
92            client
93                .with_futures_year_digits(futures_year_digits)
94                .with_share_class_space(share_class_space)
95        })
96        .map_err(to_pyvalue_err)?;
97
98        Ok(Self { inner })
99    }
100
101    /// Returns the API key from the stored credential.
102    #[getter]
103    #[pyo3(name = "api_key")]
104    fn py_api_key(&self) -> &str {
105        self.inner.api_key()
106    }
107
108    /// Caches a `price_precision` for the given `symbol`.
109    ///
110    /// When market data is fetched without an explicit `price_precision`, the
111    /// client resolves precision per record from this cache. Instruments
112    /// returned by `Self.get_range_instruments` are inserted automatically.
113    #[pyo3(name = "set_price_precision")]
114    fn py_set_price_precision(&self, symbol: &str, price_precision: u8) {
115        self.inner
116            .set_price_precision(Symbol::from(symbol), price_precision);
117    }
118
119    /// Gets the date range for a specific dataset.
120    ///
121    /// # Errors
122    ///
123    /// Returns an error if the API request fails.
124    #[pyo3(name = "get_dataset_range")]
125    fn py_get_dataset_range<'py>(
126        &self,
127        py: Python<'py>,
128        dataset: String,
129    ) -> PyResult<Bound<'py, PyAny>> {
130        let inner = self.inner.clone();
131
132        pyo3_async_runtimes::tokio::future_into_py(py, async move {
133            let response = inner.get_dataset_range(&dataset).await;
134            match response {
135                Ok(res) => Python::attach(|py| {
136                    let dict = PyDict::new(py);
137                    dict.set_item("start", res.start)?;
138                    dict.set_item("end", res.end)?;
139                    dict.into_py_any(py)
140                }),
141                Err(e) => Err(to_pyexception(format!("Error handling response: {e}"))),
142            }
143        })
144    }
145
146    /// Fetches instrument definitions for the given parameters.
147    ///
148    /// # Errors
149    ///
150    /// Returns an error if the API request or data processing fails.
151    #[pyo3(name = "get_range_instruments")]
152    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None))]
153    #[expect(clippy::needless_pass_by_value)]
154    fn py_get_range_instruments<'py>(
155        &self,
156        py: Python<'py>,
157        dataset: String,
158        instrument_ids: Vec<InstrumentId>,
159        start: u64,
160        end: Option<u64>,
161        limit: Option<u64>,
162    ) -> PyResult<Bound<'py, PyAny>> {
163        let inner = self.inner.clone();
164        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
165
166        let params = RangeQueryParams {
167            dataset,
168            symbols,
169            start: start.into(),
170            end: end.map(Into::into),
171            limit,
172            price_precision: None,
173        };
174
175        pyo3_async_runtimes::tokio::future_into_py(py, async move {
176            let instruments = inner
177                .get_range_instruments(params)
178                .await
179                .map_err(to_pyvalue_err)?;
180
181            Python::attach(|py| -> PyResult<Py<PyAny>> {
182                let objs: Vec<Py<PyAny>> = instruments
183                    .into_iter()
184                    .map(|inst| instrument_any_to_pyobject(py, inst))
185                    .collect::<PyResult<Vec<Py<PyAny>>>>()?;
186
187                let list = PyList::new(py, &objs)?;
188                Ok(list.into_py_any_unwrap(py))
189            })
190        })
191    }
192
193    /// Fetches quote ticks for the given parameters.
194    ///
195    /// # Errors
196    ///
197    /// Returns an error if the API request or data processing fails.
198    #[pyo3(name = "get_range_quotes")]
199    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None, price_precision=None, schema=None))]
200    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
201    fn py_get_range_quotes<'py>(
202        &self,
203        py: Python<'py>,
204        dataset: String,
205        instrument_ids: Vec<InstrumentId>,
206        start: u64,
207        end: Option<u64>,
208        limit: Option<u64>,
209        price_precision: Option<u8>,
210        schema: Option<String>,
211    ) -> PyResult<Bound<'py, PyAny>> {
212        let inner = self.inner.clone();
213        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
214
215        let params = RangeQueryParams {
216            dataset,
217            symbols,
218            start: start.into(),
219            end: end.map(Into::into),
220            limit,
221            price_precision,
222        };
223
224        pyo3_async_runtimes::tokio::future_into_py(py, async move {
225            let quotes = inner
226                .get_range_quotes(params, schema)
227                .await
228                .map_err(to_pyvalue_err)?;
229            Python::attach(|py| quotes.into_py_any(py))
230        })
231    }
232
233    /// Fetches trade ticks for the given parameters.
234    ///
235    /// # Errors
236    ///
237    /// Returns an error if the API request or data processing fails.
238    #[pyo3(name = "get_range_trades")]
239    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None, price_precision=None, schema=None))]
240    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
241    fn py_get_range_trades<'py>(
242        &self,
243        py: Python<'py>,
244        dataset: String,
245        instrument_ids: Vec<InstrumentId>,
246        start: u64,
247        end: Option<u64>,
248        limit: Option<u64>,
249        price_precision: Option<u8>,
250        schema: Option<String>,
251    ) -> PyResult<Bound<'py, PyAny>> {
252        let inner = self.inner.clone();
253        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
254
255        let params = RangeQueryParams {
256            dataset,
257            symbols,
258            start: start.into(),
259            end: end.map(Into::into),
260            limit,
261            price_precision,
262        };
263
264        pyo3_async_runtimes::tokio::future_into_py(py, async move {
265            let trades = inner
266                .get_range_trades(params, schema)
267                .await
268                .map_err(to_pyvalue_err)?;
269            Python::attach(|py| trades.into_py_any(py))
270        })
271    }
272
273    /// Fetches bars for the given parameters.
274    ///
275    /// # Errors
276    ///
277    /// Returns an error if the API request or data processing fails.
278    #[pyo3(name = "get_range_bars")]
279    #[pyo3(signature = (dataset, instrument_ids, aggregation, start, end=None, limit=None, price_precision=None, timestamp_on_close=true))]
280    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
281    fn py_get_range_bars<'py>(
282        &self,
283        py: Python<'py>,
284        dataset: String,
285        instrument_ids: Vec<InstrumentId>,
286        aggregation: BarAggregation,
287        start: u64,
288        end: Option<u64>,
289        limit: Option<u64>,
290        price_precision: Option<u8>,
291        timestamp_on_close: bool,
292    ) -> PyResult<Bound<'py, PyAny>> {
293        let inner = self.inner.clone();
294        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
295
296        let params = RangeQueryParams {
297            dataset,
298            symbols,
299            start: start.into(),
300            end: end.map(Into::into),
301            limit,
302            price_precision,
303        };
304
305        pyo3_async_runtimes::tokio::future_into_py(py, async move {
306            let bars = inner
307                .get_range_bars(params, aggregation, timestamp_on_close)
308                .await
309                .map_err(to_pyvalue_err)?;
310            Python::attach(|py| bars.into_py_any(py))
311        })
312    }
313
314    #[pyo3(name = "get_order_book_depth")]
315    #[pyo3(signature = (dataset, instrument_ids, start, end=None, depth=None))]
316    #[expect(clippy::needless_pass_by_value)]
317    fn py_get_order_book_depth<'py>(
318        &self,
319        py: Python<'py>,
320        dataset: String,
321        instrument_ids: Vec<InstrumentId>,
322        start: u64,
323        end: Option<u64>,
324        depth: Option<usize>,
325    ) -> PyResult<Bound<'py, PyAny>> {
326        let inner = self.inner.clone();
327        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
328
329        let params = RangeQueryParams {
330            dataset,
331            symbols,
332            start: start.into(),
333            end: end.map(Into::into),
334            limit: None,
335            price_precision: None,
336        };
337
338        pyo3_async_runtimes::tokio::future_into_py(py, async move {
339            let depths = inner
340                .get_range_order_book_depth(params, depth)
341                .await
342                .map_err(to_pyvalue_err)?;
343            Python::attach(|py| depths.into_py_any(py))
344        })
345    }
346
347    /// Fetches order book deltas for the given parameters.
348    ///
349    /// # Errors
350    ///
351    /// Returns an error if the API request or data processing fails.
352    #[pyo3(name = "get_range_order_book_deltas")]
353    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None, price_precision=None))]
354    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
355    fn py_get_range_order_book_deltas<'py>(
356        &self,
357        py: Python<'py>,
358        dataset: String,
359        instrument_ids: Vec<InstrumentId>,
360        start: u64,
361        end: Option<u64>,
362        limit: Option<u64>,
363        price_precision: Option<u8>,
364    ) -> PyResult<Bound<'py, PyAny>> {
365        let inner = self.inner.clone();
366        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
367
368        let params = RangeQueryParams {
369            dataset,
370            symbols,
371            start: start.into(),
372            end: end.map(Into::into),
373            limit,
374            price_precision,
375        };
376
377        pyo3_async_runtimes::tokio::future_into_py(py, async move {
378            let deltas = inner
379                .get_range_order_book_deltas(params)
380                .await
381                .map_err(to_pyvalue_err)?;
382            Python::attach(|py| deltas.into_py_any(py))
383        })
384    }
385
386    /// Fetches imbalance data for the given parameters.
387    ///
388    /// # Errors
389    ///
390    /// Returns an error if the API request or data processing fails.
391    #[pyo3(name = "get_range_imbalance")]
392    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None, price_precision=None))]
393    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
394    fn py_get_range_imbalance<'py>(
395        &self,
396        py: Python<'py>,
397        dataset: String,
398        instrument_ids: Vec<InstrumentId>,
399        start: u64,
400        end: Option<u64>,
401        limit: Option<u64>,
402        price_precision: Option<u8>,
403    ) -> PyResult<Bound<'py, PyAny>> {
404        let inner = self.inner.clone();
405        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
406
407        let params = RangeQueryParams {
408            dataset,
409            symbols,
410            start: start.into(),
411            end: end.map(Into::into),
412            limit,
413            price_precision,
414        };
415
416        pyo3_async_runtimes::tokio::future_into_py(py, async move {
417            let imbalances = inner
418                .get_range_imbalance(params)
419                .await
420                .map_err(to_pyvalue_err)?;
421            Python::attach(|py| imbalances.into_py_any(py))
422        })
423    }
424
425    /// Fetches statistics data for the given parameters.
426    ///
427    /// # Errors
428    ///
429    /// Returns an error if the API request or data processing fails.
430    #[pyo3(name = "get_range_statistics")]
431    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None, price_precision=None))]
432    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
433    fn py_get_range_statistics<'py>(
434        &self,
435        py: Python<'py>,
436        dataset: String,
437        instrument_ids: Vec<InstrumentId>,
438        start: u64,
439        end: Option<u64>,
440        limit: Option<u64>,
441        price_precision: Option<u8>,
442    ) -> PyResult<Bound<'py, PyAny>> {
443        let inner = self.inner.clone();
444        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
445
446        let params = RangeQueryParams {
447            dataset,
448            symbols,
449            start: start.into(),
450            end: end.map(Into::into),
451            limit,
452            price_precision,
453        };
454
455        pyo3_async_runtimes::tokio::future_into_py(py, async move {
456            let statistics = inner
457                .get_range_statistics(params)
458                .await
459                .map_err(to_pyvalue_err)?;
460            Python::attach(|py| statistics.into_py_any(py))
461        })
462    }
463
464    /// Fetches status data for the given parameters.
465    ///
466    /// # Errors
467    ///
468    /// Returns an error if the API request or data processing fails.
469    #[pyo3(name = "get_range_status")]
470    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None))]
471    #[expect(clippy::needless_pass_by_value)]
472    fn py_get_range_status<'py>(
473        &self,
474        py: Python<'py>,
475        dataset: String,
476        instrument_ids: Vec<InstrumentId>,
477        start: u64,
478        end: Option<u64>,
479        limit: Option<u64>,
480    ) -> PyResult<Bound<'py, PyAny>> {
481        let inner = self.inner.clone();
482        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
483
484        let params = RangeQueryParams {
485            dataset,
486            symbols,
487            start: start.into(),
488            end: end.map(Into::into),
489            limit,
490            price_precision: None,
491        };
492
493        pyo3_async_runtimes::tokio::future_into_py(py, async move {
494            let statuses = inner
495                .get_range_status(params)
496                .await
497                .map_err(to_pyvalue_err)?;
498            Python::attach(|py| statuses.into_py_any(py))
499        })
500    }
501}