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, kalshi_metadata_url=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        kalshi_metadata_url: Option<String>,
73    ) -> Self {
74        let config = http_config(
75            base_url,
76            proxy_url,
77            timeout_secs,
78            max_concurrent_requests,
79            attempt_budget,
80            min_request_interval_ms,
81            max_retries,
82            retry_delay_initial_ms,
83            retry_delay_max_ms,
84            retry_backoff_factor,
85            retry_jitter_ms,
86            retry_operation_timeout_ms,
87            retry_immediate_first,
88            retry_max_elapsed_ms,
89            kalshi_metadata_url,
90        );
91        let loader = FinFeedDataLoader::with_http_config(api_key.map(SecretString::from), config);
92
93        Self {
94            inner: Arc::new(loader),
95        }
96    }
97
98    /// Registers a provider-owned outcome definition.
99    fn add_instrument(&self, instrument: BinaryOption) -> PyResult<()> {
100        self.inner
101            .add_instrument(instrument)
102            .map_err(to_pyvalue_err)
103    }
104
105    /// Returns a registered instrument definition.
106    fn instrument(&self, instrument_id: InstrumentId) -> PyResult<BinaryOption> {
107        self.inner.instrument(instrument_id).map_err(to_pyvalue_err)
108    }
109
110    /// Retrieves and retains a fresh definition for one outcome.
111    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[nautilus_trader.model.BinaryOption]", imports = ("typing", "nautilus_trader.model")))]
112    fn request_instrument<'py>(
113        &self,
114        py: Python<'py>,
115        instrument_id: InstrumentId,
116    ) -> PyResult<Bound<'py, PyAny>> {
117        let loader = Arc::clone(&self.inner);
118        pyo3_async_runtimes::tokio::future_into_py(py, async move {
119            loader
120                .request_instrument(instrument_id)
121                .await
122                .map_err(to_pyruntime_err)
123        })
124    }
125
126    /// Retrieves and retains the supplied outcome selections.
127    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[list[nautilus_trader.model.BinaryOption]]", imports = ("typing", "nautilus_trader.model")))]
128    fn request_instruments<'py>(
129        &self,
130        py: Python<'py>,
131        instruments: Vec<FinFeedInstrumentSelection>,
132    ) -> PyResult<Bound<'py, PyAny>> {
133        let loader = Arc::clone(&self.inner);
134        pyo3_async_runtimes::tokio::future_into_py(py, async move {
135            loader
136                .request_instruments(&instruments)
137                .await
138                .map_err(to_pyruntime_err)
139        })
140    }
141
142    /// Retrieves historical book deltas using retained metadata.
143    ///
144    /// Bounds are UNIX nanoseconds, inclusive on the adapter's ordering clock.
145    /// Conversion or retrieval failures raise without partial results.
146    #[pyo3(signature = (instrument_id, start, end, limit=None))]
147    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[list[nautilus_trader.model.OrderBookDelta]]", imports = ("typing", "nautilus_trader.model")))]
148    fn request_book_deltas<'py>(
149        &self,
150        py: Python<'py>,
151        instrument_id: InstrumentId,
152        start: u64,
153        end: u64,
154        limit: Option<usize>,
155    ) -> PyResult<Bound<'py, PyAny>> {
156        let limit = limit
157            .map(NonZeroUsize::try_from)
158            .transpose()
159            .map_err(to_pyvalue_err)?;
160        let loader = Arc::clone(&self.inner);
161        pyo3_async_runtimes::tokio::future_into_py(py, async move {
162            let records = loader
163                .request_book_deltas(
164                    instrument_id,
165                    UnixNanos::from(start),
166                    UnixNanos::from(end),
167                    limit,
168                )
169                .await
170                .map_err(to_pyruntime_err)?;
171            Python::attach(|py| records.into_py_any(py))
172        })
173    }
174
175    /// Retrieves historical quotes using retained metadata.
176    ///
177    /// Bounds are UNIX nanoseconds, inclusive on the adapter's ordering clock.
178    /// Conversion or retrieval failures raise without partial results.
179    #[pyo3(signature = (instrument_id, start, end, limit=None))]
180    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[list[nautilus_trader.model.QuoteTick]]", imports = ("typing", "nautilus_trader.model")))]
181    fn request_quotes<'py>(
182        &self,
183        py: Python<'py>,
184        instrument_id: InstrumentId,
185        start: u64,
186        end: u64,
187        limit: Option<usize>,
188    ) -> PyResult<Bound<'py, PyAny>> {
189        let limit = limit
190            .map(NonZeroUsize::try_from)
191            .transpose()
192            .map_err(to_pyvalue_err)?;
193        let loader = Arc::clone(&self.inner);
194        pyo3_async_runtimes::tokio::future_into_py(py, async move {
195            let records = loader
196                .request_quotes(
197                    instrument_id,
198                    UnixNanos::from(start),
199                    UnixNanos::from(end),
200                    limit,
201                )
202                .await
203                .map_err(to_pyruntime_err)?;
204            Python::attach(|py| records.into_py_any(py))
205        })
206    }
207
208    /// Retrieves historical trades using retained metadata.
209    ///
210    /// Bounds are UNIX nanoseconds, inclusive on the adapter's ordering clock.
211    /// Conversion or retrieval failures raise without partial results.
212    #[pyo3(signature = (instrument_id, start, end, limit=None))]
213    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[list[nautilus_trader.model.TradeTick]]", imports = ("typing", "nautilus_trader.model")))]
214    fn request_trades<'py>(
215        &self,
216        py: Python<'py>,
217        instrument_id: InstrumentId,
218        start: u64,
219        end: u64,
220        limit: Option<usize>,
221    ) -> PyResult<Bound<'py, PyAny>> {
222        let limit = limit
223            .map(NonZeroUsize::try_from)
224            .transpose()
225            .map_err(to_pyvalue_err)?;
226        let loader = Arc::clone(&self.inner);
227        pyo3_async_runtimes::tokio::future_into_py(py, async move {
228            let records = loader
229                .request_trades(
230                    instrument_id,
231                    UnixNanos::from(start),
232                    UnixNanos::from(end),
233                    limit,
234                )
235                .await
236                .map_err(to_pyruntime_err)?;
237            Python::attach(|py| records.into_py_any(py))
238        })
239    }
240
241    /// Retrieves historical bars using retained metadata.
242    ///
243    /// Bounds are UNIX nanoseconds, inclusive on the adapter's ordering clock.
244    /// Conversion or retrieval failures raise without partial results.
245    #[pyo3(signature = (bar_type, start, end, limit=None))]
246    #[gen_stub(override_return_type(type_repr = "typing.Awaitable[list[nautilus_trader.model.Bar]]", imports = ("typing", "nautilus_trader.model")))]
247    fn request_bars<'py>(
248        &self,
249        py: Python<'py>,
250        bar_type: BarType,
251        start: u64,
252        end: u64,
253        limit: Option<usize>,
254    ) -> PyResult<Bound<'py, PyAny>> {
255        let limit = limit
256            .map(NonZeroUsize::try_from)
257            .transpose()
258            .map_err(to_pyvalue_err)?;
259        let loader = Arc::clone(&self.inner);
260        pyo3_async_runtimes::tokio::future_into_py(py, async move {
261            let records = loader
262                .request_bars(
263                    bar_type,
264                    UnixNanos::from(start),
265                    UnixNanos::from(end),
266                    limit,
267                )
268                .await
269                .map_err(to_pyruntime_err)?;
270            Python::attach(|py| records.into_py_any(py))
271        })
272    }
273}