Skip to main content

nautilus_finfeed/python/
loaders.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 access to standalone FinFeed ingestion.
17
18use std::{num::NonZeroUsize, sync::Arc};
19
20use nautilus_core::{
21    UnixNanos,
22    python::{to_pyruntime_err, to_pyvalue_err},
23    string::secret::SecretString,
24};
25use nautilus_model::{data::BarType, identifiers::InstrumentId, instruments::BinaryOption};
26use pyo3::{IntoPyObjectExt, prelude::*};
27
28use super::config::http_config;
29use crate::{instruments::FinFeedInstrumentSelection, loaders::FinFeedDataLoader};
30
31/// Standalone ingestion with reusable instrument definitions and lazy credentials.
32///
33/// Register or request definitions before requesting market data. Construction sends no requests.
34/// History bounds are integer UNIX nanoseconds; limits must be positive.
35#[derive(Debug)]
36#[pyclass(
37    name = "FinFeedDataLoader",
38    module = "nautilus_trader.adapters.finfeed",
39    frozen
40)]
41#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.adapters.finfeed")]
42pub struct PyFinFeedDataLoader {
43    inner: Arc<FinFeedDataLoader>,
44}
45
46#[pymethods]
47#[pyo3_stub_gen::derive::gen_stub_pymethods]
48impl PyFinFeedDataLoader {
49    /// Creates a loader with optional credentials and HTTP controls.
50    ///
51    /// Missing credentials fall back to `FINFEED_API_KEY` on the first network request.
52    /// Construction sends no requests.
53    #[new]
54    #[pyo3(signature = (api_key=None, base_url=None, proxy_url=None, timeout_secs=None, max_concurrent_requests=None, attempt_budget=None, min_request_interval_ms=None, max_retries=None, retry_delay_initial_ms=None, retry_delay_max_ms=None, retry_backoff_factor=None, retry_jitter_ms=None, retry_operation_timeout_ms=None, retry_immediate_first=None, retry_max_elapsed_ms=None))]
55    #[expect(clippy::too_many_arguments)]
56    fn py_new(
57        api_key: Option<String>,
58        base_url: Option<String>,
59        proxy_url: Option<String>,
60        timeout_secs: Option<u64>,
61        max_concurrent_requests: Option<usize>,
62        attempt_budget: Option<u64>,
63        min_request_interval_ms: Option<u64>,
64        max_retries: Option<u32>,
65        retry_delay_initial_ms: Option<u64>,
66        retry_delay_max_ms: Option<u64>,
67        retry_backoff_factor: Option<f64>,
68        retry_jitter_ms: Option<u64>,
69        retry_operation_timeout_ms: Option<u64>,
70        retry_immediate_first: Option<bool>,
71        retry_max_elapsed_ms: Option<u64>,
72    ) -> Self {
73        let config = http_config(
74            base_url,
75            proxy_url,
76            timeout_secs,
77            max_concurrent_requests,
78            attempt_budget,
79            min_request_interval_ms,
80            max_retries,
81            retry_delay_initial_ms,
82            retry_delay_max_ms,
83            retry_backoff_factor,
84            retry_jitter_ms,
85            retry_operation_timeout_ms,
86            retry_immediate_first,
87            retry_max_elapsed_ms,
88        );
89        let loader = FinFeedDataLoader::with_http_config(api_key.map(SecretString::from), config);
90
91        Self {
92            inner: Arc::new(loader),
93        }
94    }
95
96    /// Registers a provider-owned outcome definition.
97    fn add_instrument(&self, instrument: BinaryOption) -> PyResult<()> {
98        self.inner
99            .add_instrument(instrument)
100            .map_err(to_pyvalue_err)
101    }
102
103    /// Returns a registered instrument definition.
104    fn instrument(&self, instrument_id: InstrumentId) -> PyResult<BinaryOption> {
105        self.inner.instrument(instrument_id).map_err(to_pyvalue_err)
106    }
107
108    /// Retrieves and retains a fresh definition for one outcome.
109    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[nautilus_trader.model.BinaryOption]", imports = ("typing", "nautilus_trader.model")))]
110    fn request_instrument<'py>(
111        &self,
112        py: Python<'py>,
113        instrument_id: InstrumentId,
114    ) -> PyResult<Bound<'py, PyAny>> {
115        let loader = Arc::clone(&self.inner);
116        pyo3_async_runtimes::tokio::future_into_py(py, async move {
117            loader
118                .request_instrument(instrument_id)
119                .await
120                .map_err(to_pyruntime_err)
121        })
122    }
123
124    /// Retrieves and retains the supplied outcome selections.
125    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[list[nautilus_trader.model.BinaryOption]]", imports = ("typing", "nautilus_trader.model")))]
126    fn request_instruments<'py>(
127        &self,
128        py: Python<'py>,
129        instruments: Vec<FinFeedInstrumentSelection>,
130    ) -> PyResult<Bound<'py, PyAny>> {
131        let loader = Arc::clone(&self.inner);
132        pyo3_async_runtimes::tokio::future_into_py(py, async move {
133            loader
134                .request_instruments(&instruments)
135                .await
136                .map_err(to_pyruntime_err)
137        })
138    }
139
140    /// Retrieves historical book deltas using retained metadata.
141    ///
142    /// Bounds are UNIX nanoseconds, inclusive on the adapter's ordering clock.
143    /// Conversion or retrieval failures raise without partial results.
144    #[pyo3(signature = (instrument_id, start, end, limit=None))]
145    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[list[nautilus_trader.model.OrderBookDelta]]", imports = ("typing", "nautilus_trader.model")))]
146    fn request_book_deltas<'py>(
147        &self,
148        py: Python<'py>,
149        instrument_id: InstrumentId,
150        start: u64,
151        end: u64,
152        limit: Option<usize>,
153    ) -> PyResult<Bound<'py, PyAny>> {
154        let limit = limit
155            .map(NonZeroUsize::try_from)
156            .transpose()
157            .map_err(to_pyvalue_err)?;
158        let loader = Arc::clone(&self.inner);
159        pyo3_async_runtimes::tokio::future_into_py(py, async move {
160            let records = loader
161                .request_book_deltas(
162                    instrument_id,
163                    UnixNanos::from(start),
164                    UnixNanos::from(end),
165                    limit,
166                )
167                .await
168                .map_err(to_pyruntime_err)?;
169            Python::attach(|py| records.into_py_any(py))
170        })
171    }
172
173    /// Retrieves historical quotes using retained metadata.
174    ///
175    /// Bounds are UNIX nanoseconds, inclusive on the adapter's ordering clock.
176    /// Conversion or retrieval failures raise without partial results.
177    #[pyo3(signature = (instrument_id, start, end, limit=None))]
178    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[list[nautilus_trader.model.QuoteTick]]", imports = ("typing", "nautilus_trader.model")))]
179    fn request_quotes<'py>(
180        &self,
181        py: Python<'py>,
182        instrument_id: InstrumentId,
183        start: u64,
184        end: u64,
185        limit: Option<usize>,
186    ) -> PyResult<Bound<'py, PyAny>> {
187        let limit = limit
188            .map(NonZeroUsize::try_from)
189            .transpose()
190            .map_err(to_pyvalue_err)?;
191        let loader = Arc::clone(&self.inner);
192        pyo3_async_runtimes::tokio::future_into_py(py, async move {
193            let records = loader
194                .request_quotes(
195                    instrument_id,
196                    UnixNanos::from(start),
197                    UnixNanos::from(end),
198                    limit,
199                )
200                .await
201                .map_err(to_pyruntime_err)?;
202            Python::attach(|py| records.into_py_any(py))
203        })
204    }
205
206    /// Retrieves historical trades using retained metadata.
207    ///
208    /// Bounds are UNIX nanoseconds, inclusive on the adapter's ordering clock.
209    /// Conversion or retrieval failures raise without partial results.
210    #[pyo3(signature = (instrument_id, start, end, limit=None))]
211    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[list[nautilus_trader.model.TradeTick]]", imports = ("typing", "nautilus_trader.model")))]
212    fn request_trades<'py>(
213        &self,
214        py: Python<'py>,
215        instrument_id: InstrumentId,
216        start: u64,
217        end: u64,
218        limit: Option<usize>,
219    ) -> PyResult<Bound<'py, PyAny>> {
220        let limit = limit
221            .map(NonZeroUsize::try_from)
222            .transpose()
223            .map_err(to_pyvalue_err)?;
224        let loader = Arc::clone(&self.inner);
225        pyo3_async_runtimes::tokio::future_into_py(py, async move {
226            let records = loader
227                .request_trades(
228                    instrument_id,
229                    UnixNanos::from(start),
230                    UnixNanos::from(end),
231                    limit,
232                )
233                .await
234                .map_err(to_pyruntime_err)?;
235            Python::attach(|py| records.into_py_any(py))
236        })
237    }
238
239    /// Retrieves historical bars using retained metadata.
240    ///
241    /// Bounds are UNIX nanoseconds, inclusive on the adapter's ordering clock.
242    /// Conversion or retrieval failures raise without partial results.
243    #[pyo3(signature = (bar_type, start, end, limit=None))]
244    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[list[nautilus_trader.model.Bar]]", imports = ("typing", "nautilus_trader.model")))]
245    fn request_bars<'py>(
246        &self,
247        py: Python<'py>,
248        bar_type: BarType,
249        start: u64,
250        end: u64,
251        limit: Option<usize>,
252    ) -> PyResult<Bound<'py, PyAny>> {
253        let limit = limit
254            .map(NonZeroUsize::try_from)
255            .transpose()
256            .map_err(to_pyvalue_err)?;
257        let loader = Arc::clone(&self.inner);
258        pyo3_async_runtimes::tokio::future_into_py(py, async move {
259            let records = loader
260                .request_bars(
261                    bar_type,
262                    UnixNanos::from(start),
263                    UnixNanos::from(end),
264                    limit,
265                )
266                .await
267                .map_err(to_pyruntime_err)?;
268            Python::attach(|py| records.into_py_any(py))
269        })
270    }
271}