Skip to main content

nautilus_databento/python/
live.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 live client.
17
18use std::path::PathBuf;
19
20use nautilus_core::python::{to_pyruntime_err, to_pyvalue_err};
21use nautilus_model::{
22    identifiers::{InstrumentId, futures::FuturesYearDigits},
23    python::{data::data_to_pyobject, instruments::instrument_any_to_pyobject},
24};
25use pyo3::{IntoPyObjectExt, prelude::*};
26
27use super::types::DatabentoSubscriptionAck;
28pub use crate::live::DatabentoLiveClient;
29use crate::live::{DatabentoMessage, is_command_send_error};
30
31impl DatabentoLiveClient {
32    async fn process_messages(
33        mut msg_rx: tokio::sync::mpsc::UnboundedReceiver<DatabentoMessage>,
34        callback: Py<PyAny>,
35        callback_pyo3: Py<PyAny>,
36    ) -> PyResult<()> {
37        log::debug!("Processing messages...");
38        // Continue to process messages until channel is hung up
39        while let Some(msg) = msg_rx.recv().await {
40            log::trace!("Received message: {msg:?}");
41
42            match msg {
43                DatabentoMessage::Data(data) => Python::attach(|py| -> PyResult<()> {
44                    let py_obj = data_to_pyobject(py, data)?;
45                    call_python(py, &callback, py_obj);
46                    Ok(())
47                })?,
48                DatabentoMessage::Instrument(data) => {
49                    Python::attach(|py| match instrument_any_to_pyobject(py, *data) {
50                        Ok(py_obj) => call_python(py, &callback, py_obj),
51                        Err(e) => log::error!("Failed creating instrument: {e}"),
52                    });
53                }
54                DatabentoMessage::Status(data) => {
55                    Python::attach(|py| -> PyResult<()> {
56                        call_python(py, &callback_pyo3, data.into_py_any(py)?);
57                        Ok(())
58                    })?;
59                }
60                DatabentoMessage::Imbalance(data) => {
61                    Python::attach(|py| -> PyResult<()> {
62                        call_python(py, &callback_pyo3, data.into_py_any(py)?);
63                        Ok(())
64                    })?;
65                }
66                DatabentoMessage::Statistics(data) => {
67                    Python::attach(|py| -> PyResult<()> {
68                        call_python(py, &callback_pyo3, data.into_py_any(py)?);
69                        Ok(())
70                    })?;
71                }
72                DatabentoMessage::SubscriptionAck(ack) => {
73                    Python::attach(|py| -> PyResult<()> {
74                        let py_obj = DatabentoSubscriptionAck::from(ack).into_py_any(py)?;
75                        call_python(py, &callback_pyo3, py_obj);
76                        Ok(())
77                    })?;
78                }
79                DatabentoMessage::Close => {
80                    // Graceful close
81                    break;
82                }
83                DatabentoMessage::Error(e) => {
84                    // Return error to Python
85                    return Err(to_pyruntime_err(e));
86                }
87            }
88        }
89
90        msg_rx.close();
91        log::debug!("Closed message receiver");
92
93        Ok(())
94    }
95}
96
97fn call_python(py: Python, callback: &Py<PyAny>, py_obj: Py<PyAny>) {
98    if let Err(e) = callback.call1(py, (py_obj,)) {
99        // TODO: Improve this by checking for the actual exception type
100        if !e.to_string().contains("CancelledError") {
101            log::error!("Error calling Python: {e}");
102        }
103    }
104}
105
106#[pymethods]
107#[pyo3_stub_gen::derive::gen_stub_pymethods]
108impl DatabentoLiveClient {
109    /// Creates a new `DatabentoLiveClient` instance.
110    ///
111    /// # Errors
112    ///
113    /// Returns an error if reading or parsing the publishers file fails.
114    #[new]
115    #[pyo3(signature = (key, dataset, publishers_filepath, use_exchange_as_venue, bars_timestamp_on_close=None, reconnect_timeout_mins=None, futures_year_digits=None))]
116    pub fn py_new(
117        key: String,
118        dataset: String,
119        publishers_filepath: PathBuf,
120        use_exchange_as_venue: bool,
121        bars_timestamp_on_close: Option<bool>,
122        reconnect_timeout_mins: Option<i64>,
123        futures_year_digits: Option<u8>,
124    ) -> PyResult<Self> {
125        let futures_year_digits = futures_year_digits
126            .map(FuturesYearDigits::try_from)
127            .transpose()
128            .map_err(to_pyvalue_err)?
129            .unwrap_or_default();
130
131        Self::new(
132            key,
133            dataset,
134            publishers_filepath,
135            use_exchange_as_venue,
136            bars_timestamp_on_close,
137            reconnect_timeout_mins,
138        )
139        .map(|client| client.with_futures_year_digits(futures_year_digits))
140        .map_err(to_pyvalue_err)
141    }
142
143    #[getter]
144    fn dataset(&self) -> &str {
145        self.dataset.as_str()
146    }
147
148    #[pyo3(name = "is_running")]
149    const fn py_is_running(&self) -> bool {
150        self.is_running()
151    }
152
153    #[pyo3(name = "is_closed")]
154    const fn py_is_closed(&self) -> bool {
155        self.is_closed()
156    }
157
158    /// Subscribes to Databento live data for the requested instruments.
159    ///
160    /// # Errors
161    ///
162    /// Returns an error if symbology, schema, timestamp, or precision inputs are invalid,
163    /// or if the command cannot be sent to the feed handler.
164    #[pyo3(name = "subscribe")]
165    #[pyo3(signature = (schema, instrument_ids, start=None, snapshot=None, price_precisions=None, stype_in=None))]
166    fn py_subscribe(
167        &mut self,
168        schema: String,
169        instrument_ids: Vec<InstrumentId>,
170        start: Option<u64>,
171        snapshot: Option<bool>,
172        price_precisions: Option<Vec<Option<u8>>>,
173        stype_in: Option<String>,
174    ) -> PyResult<()> {
175        if let Err(e) = self.subscribe(
176            schema,
177            instrument_ids,
178            start,
179            snapshot,
180            price_precisions,
181            stype_in,
182        ) {
183            return if is_command_send_error(&e) {
184                Err(to_pyruntime_err(e))
185            } else {
186                Err(to_pyvalue_err(e))
187            };
188        }
189
190        Ok(())
191    }
192
193    /// Starts the live feed handler and returns its message receiver.
194    ///
195    /// # Errors
196    ///
197    /// Returns an error if the client is already closed, already running, or cannot start.
198    #[pyo3(name = "start")]
199    fn py_start<'py>(
200        &mut self,
201        py: Python<'py>,
202        callback: Py<PyAny>,
203        callback_pyo3: Py<PyAny>,
204    ) -> PyResult<Bound<'py, PyAny>> {
205        let (mut feed_handler, msg_rx) = self.start().map_err(to_pyruntime_err)?;
206
207        pyo3_async_runtimes::tokio::future_into_py(py, async move {
208            let (proc_handle, feed_handle) = tokio::join!(
209                Self::process_messages(msg_rx, callback, callback_pyo3),
210                feed_handler.run(),
211            );
212
213            proc_handle?;
214            feed_handle.map_err(to_pyruntime_err)?;
215
216            log::debug!("Live client completed");
217            Ok(())
218        })
219    }
220
221    /// Closes the live client.
222    ///
223    /// # Errors
224    ///
225    /// Returns an error if the client was never started, is already closed, or cannot send
226    /// the close command to the feed handler.
227    #[pyo3(name = "close")]
228    fn py_close(&mut self) -> PyResult<()> {
229        self.close().map_err(to_pyruntime_err)
230    }
231}
232
233#[cfg(test)]
234mod tests {
235    use std::path::PathBuf;
236
237    use pyo3::exceptions::{PyRuntimeError, PyValueError};
238    use rstest::rstest;
239
240    use super::*;
241
242    fn create_test_client() -> DatabentoLiveClient {
243        DatabentoLiveClient::new(
244            "test-api-key".to_string(),
245            "GLBX.MDP3".to_string(),
246            PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("publishers.json"),
247            true,
248            None,
249            None,
250        )
251        .unwrap()
252    }
253
254    #[rstest]
255    fn test_py_subscribe_maps_invalid_input_to_value_error() {
256        Python::initialize();
257        let mut client = create_test_client();
258
259        let err = client
260            .py_subscribe(
261                "definition".to_string(),
262                vec![InstrumentId::from("ES.FUT.GLBX")],
263                None,
264                None,
265                None,
266                Some("not-a-stype".to_string()),
267            )
268            .unwrap_err();
269
270        Python::attach(|py| {
271            assert!(err.is_instance_of::<PyValueError>(py));
272        });
273    }
274
275    #[rstest]
276    fn test_py_subscribe_maps_command_send_error_to_runtime_error() {
277        Python::initialize();
278        let mut client = create_test_client();
279        let (feed_handler, msg_rx) = client.start().unwrap();
280        drop(feed_handler);
281        drop(msg_rx);
282
283        let err = client
284            .py_subscribe(
285                "definition".to_string(),
286                vec![InstrumentId::from("ES.FUT.GLBX")],
287                None,
288                None,
289                None,
290                Some("parent".to_string()),
291            )
292            .unwrap_err();
293
294        Python::attach(|py| {
295            assert!(err.is_instance_of::<PyRuntimeError>(py));
296        });
297    }
298}