Skip to main content

nautilus_databento/python/
factories.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 data client factory.
17
18use std::path::PathBuf;
19
20use indexmap::IndexMap;
21use nautilus_core::{
22    python::{to_pyruntime_err, to_pyvalue_err},
23    time::get_atomic_clock_realtime,
24};
25use nautilus_model::identifiers::{ClientId, futures::FuturesYearDigits};
26use pyo3::prelude::*;
27
28use crate::{
29    data::{DatabentoDataClient, DatabentoDataClientConfig},
30    factories::DatabentoDataClientFactory,
31};
32
33#[pymethods]
34#[pyo3_stub_gen::derive::gen_stub_pymethods]
35impl DatabentoDataClientConfig {
36    /// Configuration for the Databento data client.
37    #[new]
38    #[pyo3(signature = (api_key, publishers_filepath, use_exchange_as_venue=false, bars_timestamp_on_close=true, venue_dataset_map=None, historical_base_url=None, live_gateway_addr=None, futures_year_digits=None))]
39    #[expect(
40        clippy::too_many_arguments,
41        reason = "the Python constructor preserves existing positional parameters"
42    )]
43    fn py_new(
44        api_key: String,
45        publishers_filepath: PathBuf,
46        use_exchange_as_venue: bool,
47        bars_timestamp_on_close: bool,
48        venue_dataset_map: Option<IndexMap<String, String>>,
49        historical_base_url: Option<String>,
50        live_gateway_addr: Option<String>,
51        futures_year_digits: Option<u8>,
52    ) -> PyResult<Self> {
53        let futures_year_digits = futures_year_digits
54            .map(FuturesYearDigits::try_from)
55            .transpose()
56            .map_err(to_pyvalue_err)?
57            .unwrap_or_default();
58
59        let mut config = Self::new(
60            api_key,
61            publishers_filepath,
62            use_exchange_as_venue,
63            bars_timestamp_on_close,
64        );
65
66        if let Some(venue_dataset_map) = venue_dataset_map {
67            config.venue_dataset_map = venue_dataset_map;
68        }
69
70        config.historical_base_url = historical_base_url;
71        config.live_gateway_addr = live_gateway_addr;
72        config.futures_year_digits = futures_year_digits;
73
74        Ok(config)
75    }
76
77    #[getter]
78    fn futures_year_digits(&self) -> u8 {
79        self.futures_year_digits.into()
80    }
81
82    fn __repr__(&self) -> String {
83        format!("{self:?}")
84    }
85}
86
87#[pymethods]
88#[pyo3_stub_gen::derive::gen_stub_pymethods]
89impl DatabentoDataClientFactory {
90    /// Factory for creating Databento data clients.
91    #[new]
92    fn py_new() -> Self {
93        Self
94    }
95
96    #[pyo3(name = "name")]
97    fn py_name(&self) -> &'static str {
98        "DATABENTO"
99    }
100
101    /// Creates a new `DatabentoDataClient` instance.
102    ///
103    /// # Errors
104    ///
105    /// Returns an error if the client cannot be created or publisher configuration cannot be loaded.
106    #[staticmethod]
107    #[pyo3(name = "create_live_data_client")]
108    #[pyo3(signature = (client_id, api_key, publishers_filepath, use_exchange_as_venue = true, bars_timestamp_on_close = true))]
109    pub fn py_create_live_data_client(
110        client_id: ClientId,
111        api_key: String,
112        publishers_filepath: PathBuf,
113        use_exchange_as_venue: bool,
114        bars_timestamp_on_close: bool,
115    ) -> PyResult<DatabentoDataClient> {
116        Self::create_live_data_client(
117            client_id,
118            api_key,
119            publishers_filepath,
120            use_exchange_as_venue,
121            bars_timestamp_on_close,
122            get_atomic_clock_realtime(),
123        )
124        .map_err(to_pyruntime_err)
125    }
126}
127
128#[cfg(test)]
129mod tests {
130    use pyo3::{prelude::*, types::PyDict};
131    use rstest::rstest;
132
133    use super::DatabentoDataClientConfig;
134
135    #[rstest]
136    #[case(None, 2)]
137    #[case(Some(1), 1)]
138    #[case(Some(2), 2)]
139    fn test_python_futures_year_digits(#[case] configured: Option<u8>, #[case] expected: u8) {
140        Python::initialize();
141        Python::attach(|py| {
142            let kwargs = PyDict::new(py);
143            if let Some(digits) = configured {
144                kwargs.set_item("futures_year_digits", digits).unwrap();
145            }
146
147            let config = py
148                .get_type::<DatabentoDataClientConfig>()
149                .call(("test-key", "publishers.json"), Some(&kwargs))
150                .unwrap();
151            assert_eq!(
152                config
153                    .getattr("futures_year_digits")
154                    .unwrap()
155                    .extract::<u8>()
156                    .unwrap(),
157                expected
158            );
159        });
160    }
161
162    #[rstest]
163    #[case(0)]
164    #[case(3)]
165    #[case(4)]
166    #[case(u8::MAX)]
167    fn test_python_rejects_invalid_futures_year_digits(#[case] digits: u8) {
168        Python::initialize();
169        Python::attach(|py| {
170            let kwargs = PyDict::new(py);
171            kwargs.set_item("futures_year_digits", digits).unwrap();
172            let error = py
173                .get_type::<DatabentoDataClientConfig>()
174                .call(("test-key", "publishers.json"), Some(&kwargs))
175                .unwrap_err();
176            assert!(error.is_instance_of::<pyo3::exceptions::PyValueError>(py));
177            assert_eq!(
178                error.value(py).to_string(),
179                "`futures_year_digits` must be either 1 or 2"
180            );
181        });
182    }
183}