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, share_class_space=true))]
116    #[expect(
117        clippy::too_many_arguments,
118        reason = "the Python constructor preserves existing positional parameters"
119    )]
120    pub fn py_new(
121        key: String,
122        dataset: String,
123        publishers_filepath: PathBuf,
124        use_exchange_as_venue: bool,
125        bars_timestamp_on_close: Option<bool>,
126        reconnect_timeout_mins: Option<i64>,
127        futures_year_digits: Option<u8>,
128        share_class_space: bool,
129    ) -> PyResult<Self> {
130        let futures_year_digits = futures_year_digits
131            .map(FuturesYearDigits::try_from)
132            .transpose()
133            .map_err(to_pyvalue_err)?
134            .unwrap_or_default();
135
136        Self::new(
137            key,
138            dataset,
139            publishers_filepath,
140            use_exchange_as_venue,
141            bars_timestamp_on_close,
142            reconnect_timeout_mins,
143        )
144        .map(|client| {
145            client
146                .with_futures_year_digits(futures_year_digits)
147                .with_share_class_space(share_class_space)
148        })
149        .map_err(to_pyvalue_err)
150    }
151
152    #[getter]
153    fn dataset(&self) -> &str {
154        self.dataset.as_str()
155    }
156
157    #[pyo3(name = "is_running")]
158    const fn py_is_running(&self) -> bool {
159        self.is_running()
160    }
161
162    #[pyo3(name = "is_closed")]
163    const fn py_is_closed(&self) -> bool {
164        self.is_closed()
165    }
166
167    /// Subscribes to Databento live data for the requested instruments.
168    ///
169    /// # Errors
170    ///
171    /// Returns an error if symbology, schema, timestamp, or precision inputs are invalid,
172    /// or if the command cannot be sent to the feed handler.
173    #[pyo3(name = "subscribe")]
174    #[pyo3(signature = (schema, instrument_ids, start=None, snapshot=None, price_precisions=None, stype_in=None))]
175    fn py_subscribe(
176        &mut self,
177        schema: String,
178        instrument_ids: Vec<InstrumentId>,
179        start: Option<u64>,
180        snapshot: Option<bool>,
181        price_precisions: Option<Vec<Option<u8>>>,
182        stype_in: Option<String>,
183    ) -> PyResult<()> {
184        if let Err(e) = self.subscribe(
185            schema,
186            instrument_ids,
187            start,
188            snapshot,
189            price_precisions,
190            stype_in,
191        ) {
192            return if is_command_send_error(&e) {
193                Err(to_pyruntime_err(e))
194            } else {
195                Err(to_pyvalue_err(e))
196            };
197        }
198
199        Ok(())
200    }
201
202    /// Starts the live feed handler and returns its message receiver.
203    ///
204    /// # Errors
205    ///
206    /// Returns an error if the client is already closed, already running, or cannot start.
207    #[pyo3(name = "start")]
208    fn py_start<'py>(
209        &mut self,
210        py: Python<'py>,
211        callback: Py<PyAny>,
212        callback_pyo3: Py<PyAny>,
213    ) -> PyResult<Bound<'py, PyAny>> {
214        let (mut feed_handler, msg_rx) = self.start().map_err(to_pyruntime_err)?;
215
216        pyo3_async_runtimes::tokio::future_into_py(py, async move {
217            let (proc_handle, feed_handle) = tokio::join!(
218                Self::process_messages(msg_rx, callback, callback_pyo3),
219                feed_handler.run(),
220            );
221
222            proc_handle?;
223            feed_handle.map_err(to_pyruntime_err)?;
224
225            log::debug!("Live client completed");
226            Ok(())
227        })
228    }
229
230    /// Closes the live client.
231    ///
232    /// # Errors
233    ///
234    /// Returns an error if the client was never started, is already closed, or cannot send
235    /// the close command to the feed handler.
236    #[pyo3(name = "close")]
237    fn py_close(&mut self) -> PyResult<()> {
238        self.close().map_err(to_pyruntime_err)
239    }
240}
241
242#[cfg(test)]
243mod tests {
244    use std::path::PathBuf;
245
246    use pyo3::exceptions::{PyRuntimeError, PyValueError};
247    use rstest::rstest;
248
249    use super::*;
250
251    fn create_test_client() -> DatabentoLiveClient {
252        DatabentoLiveClient::new(
253            "test-api-key".to_string(),
254            "GLBX.MDP3".to_string(),
255            PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("publishers.json"),
256            true,
257            None,
258            None,
259        )
260        .unwrap()
261    }
262
263    #[rstest]
264    fn test_py_subscribe_maps_invalid_input_to_value_error() {
265        Python::initialize();
266        let mut client = create_test_client();
267
268        let err = client
269            .py_subscribe(
270                "definition".to_string(),
271                vec![InstrumentId::from("ES.FUT.GLBX")],
272                None,
273                None,
274                None,
275                Some("not-a-stype".to_string()),
276            )
277            .unwrap_err();
278
279        Python::attach(|py| {
280            assert!(err.is_instance_of::<PyValueError>(py));
281        });
282    }
283
284    #[rstest]
285    fn test_py_subscribe_maps_command_send_error_to_runtime_error() {
286        Python::initialize();
287        let mut client = create_test_client();
288        let (feed_handler, msg_rx) = client.start().unwrap();
289        drop(feed_handler);
290        drop(msg_rx);
291
292        let err = client
293            .py_subscribe(
294                "definition".to_string(),
295                vec![InstrumentId::from("ES.FUT.GLBX")],
296                None,
297                None,
298                None,
299                Some("parent".to_string()),
300            )
301            .unwrap_err();
302
303        Python::attach(|py| {
304            assert!(err.is_instance_of::<PyRuntimeError>(py));
305        });
306    }
307}