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