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))]
70    fn py_new(
71        key: String,
72        publishers_filepath: PathBuf,
73        use_exchange_as_venue: bool,
74        futures_year_digits: Option<u8>,
75    ) -> PyResult<Self> {
76        let futures_year_digits = futures_year_digits
77            .map(FuturesYearDigits::try_from)
78            .transpose()
79            .map_err(to_pyvalue_err)?
80            .unwrap_or_default();
81
82        let clock = get_atomic_clock_realtime();
83
84        let inner = CoreDatabentoHistoricalClient::new(
85            Credential::new(key),
86            publishers_filepath,
87            clock,
88            use_exchange_as_venue,
89        )
90        .map(|client| client.with_futures_year_digits(futures_year_digits))
91        .map_err(to_pyvalue_err)?;
92
93        Ok(Self { inner })
94    }
95
96    /// Returns the API key from the stored credential.
97    #[getter]
98    #[pyo3(name = "api_key")]
99    fn py_api_key(&self) -> &str {
100        self.inner.api_key()
101    }
102
103    /// Caches a `price_precision` for the given `symbol`.
104    ///
105    /// When market data is fetched without an explicit `price_precision`, the
106    /// client resolves precision per record from this cache. Instruments
107    /// returned by `Self.get_range_instruments` are inserted automatically.
108    #[pyo3(name = "set_price_precision")]
109    fn py_set_price_precision(&self, symbol: &str, price_precision: u8) {
110        self.inner
111            .set_price_precision(Symbol::from(symbol), price_precision);
112    }
113
114    /// Gets the date range for a specific dataset.
115    ///
116    /// # Errors
117    ///
118    /// Returns an error if the API request fails.
119    #[pyo3(name = "get_dataset_range")]
120    fn py_get_dataset_range<'py>(
121        &self,
122        py: Python<'py>,
123        dataset: String,
124    ) -> PyResult<Bound<'py, PyAny>> {
125        let inner = self.inner.clone();
126
127        pyo3_async_runtimes::tokio::future_into_py(py, async move {
128            let response = inner.get_dataset_range(&dataset).await;
129            match response {
130                Ok(res) => Python::attach(|py| {
131                    let dict = PyDict::new(py);
132                    dict.set_item("start", res.start)?;
133                    dict.set_item("end", res.end)?;
134                    dict.into_py_any(py)
135                }),
136                Err(e) => Err(to_pyexception(format!("Error handling response: {e}"))),
137            }
138        })
139    }
140
141    /// Fetches instrument definitions for the given parameters.
142    ///
143    /// # Errors
144    ///
145    /// Returns an error if the API request or data processing fails.
146    #[pyo3(name = "get_range_instruments")]
147    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None))]
148    #[expect(clippy::needless_pass_by_value)]
149    fn py_get_range_instruments<'py>(
150        &self,
151        py: Python<'py>,
152        dataset: String,
153        instrument_ids: Vec<InstrumentId>,
154        start: u64,
155        end: Option<u64>,
156        limit: Option<u64>,
157    ) -> PyResult<Bound<'py, PyAny>> {
158        let inner = self.inner.clone();
159        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
160
161        let params = RangeQueryParams {
162            dataset,
163            symbols,
164            start: start.into(),
165            end: end.map(Into::into),
166            limit,
167            price_precision: None,
168        };
169
170        pyo3_async_runtimes::tokio::future_into_py(py, async move {
171            let instruments = inner
172                .get_range_instruments(params)
173                .await
174                .map_err(to_pyvalue_err)?;
175
176            Python::attach(|py| -> PyResult<Py<PyAny>> {
177                let objs: Vec<Py<PyAny>> = instruments
178                    .into_iter()
179                    .map(|inst| instrument_any_to_pyobject(py, inst))
180                    .collect::<PyResult<Vec<Py<PyAny>>>>()?;
181
182                let list = PyList::new(py, &objs)?;
183                Ok(list.into_py_any_unwrap(py))
184            })
185        })
186    }
187
188    /// Fetches quote ticks for the given parameters.
189    ///
190    /// # Errors
191    ///
192    /// Returns an error if the API request or data processing fails.
193    #[pyo3(name = "get_range_quotes")]
194    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None, price_precision=None, schema=None))]
195    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
196    fn py_get_range_quotes<'py>(
197        &self,
198        py: Python<'py>,
199        dataset: String,
200        instrument_ids: Vec<InstrumentId>,
201        start: u64,
202        end: Option<u64>,
203        limit: Option<u64>,
204        price_precision: Option<u8>,
205        schema: Option<String>,
206    ) -> PyResult<Bound<'py, PyAny>> {
207        let inner = self.inner.clone();
208        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
209
210        let params = RangeQueryParams {
211            dataset,
212            symbols,
213            start: start.into(),
214            end: end.map(Into::into),
215            limit,
216            price_precision,
217        };
218
219        pyo3_async_runtimes::tokio::future_into_py(py, async move {
220            let quotes = inner
221                .get_range_quotes(params, schema)
222                .await
223                .map_err(to_pyvalue_err)?;
224            Python::attach(|py| quotes.into_py_any(py))
225        })
226    }
227
228    /// Fetches trade ticks for the given parameters.
229    ///
230    /// # Errors
231    ///
232    /// Returns an error if the API request or data processing fails.
233    #[pyo3(name = "get_range_trades")]
234    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None, price_precision=None, schema=None))]
235    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
236    fn py_get_range_trades<'py>(
237        &self,
238        py: Python<'py>,
239        dataset: String,
240        instrument_ids: Vec<InstrumentId>,
241        start: u64,
242        end: Option<u64>,
243        limit: Option<u64>,
244        price_precision: Option<u8>,
245        schema: Option<String>,
246    ) -> PyResult<Bound<'py, PyAny>> {
247        let inner = self.inner.clone();
248        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
249
250        let params = RangeQueryParams {
251            dataset,
252            symbols,
253            start: start.into(),
254            end: end.map(Into::into),
255            limit,
256            price_precision,
257        };
258
259        pyo3_async_runtimes::tokio::future_into_py(py, async move {
260            let trades = inner
261                .get_range_trades(params, schema)
262                .await
263                .map_err(to_pyvalue_err)?;
264            Python::attach(|py| trades.into_py_any(py))
265        })
266    }
267
268    /// Fetches bars for the given parameters.
269    ///
270    /// # Errors
271    ///
272    /// Returns an error if the API request or data processing fails.
273    #[pyo3(name = "get_range_bars")]
274    #[pyo3(signature = (dataset, instrument_ids, aggregation, start, end=None, limit=None, price_precision=None, timestamp_on_close=true))]
275    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
276    fn py_get_range_bars<'py>(
277        &self,
278        py: Python<'py>,
279        dataset: String,
280        instrument_ids: Vec<InstrumentId>,
281        aggregation: BarAggregation,
282        start: u64,
283        end: Option<u64>,
284        limit: Option<u64>,
285        price_precision: Option<u8>,
286        timestamp_on_close: bool,
287    ) -> PyResult<Bound<'py, PyAny>> {
288        let inner = self.inner.clone();
289        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
290
291        let params = RangeQueryParams {
292            dataset,
293            symbols,
294            start: start.into(),
295            end: end.map(Into::into),
296            limit,
297            price_precision,
298        };
299
300        pyo3_async_runtimes::tokio::future_into_py(py, async move {
301            let bars = inner
302                .get_range_bars(params, aggregation, timestamp_on_close)
303                .await
304                .map_err(to_pyvalue_err)?;
305            Python::attach(|py| bars.into_py_any(py))
306        })
307    }
308
309    #[pyo3(name = "get_order_book_depth")]
310    #[pyo3(signature = (dataset, instrument_ids, start, end=None, depth=None))]
311    #[expect(clippy::needless_pass_by_value)]
312    fn py_get_order_book_depth<'py>(
313        &self,
314        py: Python<'py>,
315        dataset: String,
316        instrument_ids: Vec<InstrumentId>,
317        start: u64,
318        end: Option<u64>,
319        depth: Option<usize>,
320    ) -> PyResult<Bound<'py, PyAny>> {
321        let inner = self.inner.clone();
322        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
323
324        let params = RangeQueryParams {
325            dataset,
326            symbols,
327            start: start.into(),
328            end: end.map(Into::into),
329            limit: None,
330            price_precision: None,
331        };
332
333        pyo3_async_runtimes::tokio::future_into_py(py, async move {
334            let depths = inner
335                .get_range_order_book_depth(params, depth)
336                .await
337                .map_err(to_pyvalue_err)?;
338            Python::attach(|py| depths.into_py_any(py))
339        })
340    }
341
342    /// Fetches order book deltas for the given parameters.
343    ///
344    /// # Errors
345    ///
346    /// Returns an error if the API request or data processing fails.
347    #[pyo3(name = "get_range_order_book_deltas")]
348    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None, price_precision=None))]
349    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
350    fn py_get_range_order_book_deltas<'py>(
351        &self,
352        py: Python<'py>,
353        dataset: String,
354        instrument_ids: Vec<InstrumentId>,
355        start: u64,
356        end: Option<u64>,
357        limit: Option<u64>,
358        price_precision: Option<u8>,
359    ) -> PyResult<Bound<'py, PyAny>> {
360        let inner = self.inner.clone();
361        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
362
363        let params = RangeQueryParams {
364            dataset,
365            symbols,
366            start: start.into(),
367            end: end.map(Into::into),
368            limit,
369            price_precision,
370        };
371
372        pyo3_async_runtimes::tokio::future_into_py(py, async move {
373            let deltas = inner
374                .get_range_order_book_deltas(params)
375                .await
376                .map_err(to_pyvalue_err)?;
377            Python::attach(|py| deltas.into_py_any(py))
378        })
379    }
380
381    /// Fetches imbalance data for the given parameters.
382    ///
383    /// # Errors
384    ///
385    /// Returns an error if the API request or data processing fails.
386    #[pyo3(name = "get_range_imbalance")]
387    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None, price_precision=None))]
388    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
389    fn py_get_range_imbalance<'py>(
390        &self,
391        py: Python<'py>,
392        dataset: String,
393        instrument_ids: Vec<InstrumentId>,
394        start: u64,
395        end: Option<u64>,
396        limit: Option<u64>,
397        price_precision: Option<u8>,
398    ) -> PyResult<Bound<'py, PyAny>> {
399        let inner = self.inner.clone();
400        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
401
402        let params = RangeQueryParams {
403            dataset,
404            symbols,
405            start: start.into(),
406            end: end.map(Into::into),
407            limit,
408            price_precision,
409        };
410
411        pyo3_async_runtimes::tokio::future_into_py(py, async move {
412            let imbalances = inner
413                .get_range_imbalance(params)
414                .await
415                .map_err(to_pyvalue_err)?;
416            Python::attach(|py| imbalances.into_py_any(py))
417        })
418    }
419
420    /// Fetches statistics data for the given parameters.
421    ///
422    /// # Errors
423    ///
424    /// Returns an error if the API request or data processing fails.
425    #[pyo3(name = "get_range_statistics")]
426    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None, price_precision=None))]
427    #[expect(clippy::too_many_arguments, clippy::needless_pass_by_value)]
428    fn py_get_range_statistics<'py>(
429        &self,
430        py: Python<'py>,
431        dataset: String,
432        instrument_ids: Vec<InstrumentId>,
433        start: u64,
434        end: Option<u64>,
435        limit: Option<u64>,
436        price_precision: Option<u8>,
437    ) -> PyResult<Bound<'py, PyAny>> {
438        let inner = self.inner.clone();
439        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
440
441        let params = RangeQueryParams {
442            dataset,
443            symbols,
444            start: start.into(),
445            end: end.map(Into::into),
446            limit,
447            price_precision,
448        };
449
450        pyo3_async_runtimes::tokio::future_into_py(py, async move {
451            let statistics = inner
452                .get_range_statistics(params)
453                .await
454                .map_err(to_pyvalue_err)?;
455            Python::attach(|py| statistics.into_py_any(py))
456        })
457    }
458
459    /// Fetches status data for the given parameters.
460    ///
461    /// # Errors
462    ///
463    /// Returns an error if the API request or data processing fails.
464    #[pyo3(name = "get_range_status")]
465    #[pyo3(signature = (dataset, instrument_ids, start, end=None, limit=None))]
466    #[expect(clippy::needless_pass_by_value)]
467    fn py_get_range_status<'py>(
468        &self,
469        py: Python<'py>,
470        dataset: String,
471        instrument_ids: Vec<InstrumentId>,
472        start: u64,
473        end: Option<u64>,
474        limit: Option<u64>,
475    ) -> PyResult<Bound<'py, PyAny>> {
476        let inner = self.inner.clone();
477        let symbols = inner.prepare_symbols_from_instrument_ids(&instrument_ids);
478
479        let params = RangeQueryParams {
480            dataset,
481            symbols,
482            start: start.into(),
483            end: end.map(Into::into),
484            limit,
485            price_precision: None,
486        };
487
488        pyo3_async_runtimes::tokio::future_into_py(py, async move {
489            let statuses = inner
490                .get_range_status(params)
491                .await
492                .map_err(to_pyvalue_err)?;
493            Python::attach(|py| statuses.into_py_any(py))
494        })
495    }
496}