nautilus_model/python/data/
mod.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//! Data types for the trading domain model.
17
18pub mod bar;
19pub mod bet;
20pub mod close;
21pub mod delta;
22pub mod deltas;
23pub mod depth;
24pub mod funding;
25pub mod greeks;
26pub mod order;
27pub mod prices;
28pub mod quote;
29pub mod status;
30pub mod trade;
31
32use indexmap::IndexMap;
33#[cfg(feature = "ffi")]
34use nautilus_core::ffi::cvec::CVec;
35use nautilus_core::python::to_pyvalue_err;
36use pyo3::{prelude::*, types::PyCapsule};
37
38use crate::data::{
39    Bar, Data, DataType, FundingRateUpdate, IndexPriceUpdate, MarkPriceUpdate, OrderBookDelta,
40    QuoteTick, TradeTick, close::InstrumentClose, is_monotonically_increasing_by_init,
41};
42
43const ERROR_MONOTONICITY: &str = "`data` was not monotonically increasing by the `ts_init` field";
44
45#[pymethods]
46#[cfg_attr(feature = "python", pyo3_stub_gen::derive::gen_stub_pymethods)]
47impl DataType {
48    #[new]
49    #[pyo3(signature = (type_name, metadata=None))]
50    fn py_new(type_name: &str, metadata: Option<IndexMap<String, String>>) -> Self {
51        Self::new(type_name, metadata)
52    }
53
54    #[getter]
55    #[pyo3(name = "type_name")]
56    fn py_type_name(&self) -> &str {
57        self.type_name()
58    }
59
60    #[getter]
61    #[pyo3(name = "metadata")]
62    fn py_metadata(&self) -> Option<IndexMap<String, String>> {
63        self.metadata().cloned()
64    }
65
66    #[getter]
67    #[pyo3(name = "topic")]
68    fn py_topic(&self) -> &str {
69        self.topic()
70    }
71}
72
73/// Creates a Python `PyCapsule` object containing a Rust `Data` instance.
74///
75/// This function takes ownership of the `Data` instance and encapsulates it within
76/// a `PyCapsule` object, allowing the Rust data to be passed into the Python runtime.
77///
78/// # Panics
79///
80/// This function panics if the `PyCapsule` creation fails, which may occur if
81/// there are issues with memory allocation or if the `Data` instance cannot be
82/// properly encapsulated.
83///
84/// # Safety
85///
86/// This function is safe as long as the `Data` instance does not violate Rust's
87/// safety guarantees (e.g., no invalid memory access). Users of the
88/// `PyCapsule` in Python must ensure they understand how to extract and use the
89/// encapsulated `Data` safely, especially when converting the capsule back to a
90/// Rust data structure.
91#[must_use]
92pub fn data_to_pycapsule(py: Python, data: Data) -> Py<PyAny> {
93    // Register a destructor which simply drops the `Data` value once the
94    // capsule is released by Python.
95    let capsule = PyCapsule::new_with_destructor(py, data, None, |_, _| {})
96        .expect("Error creating `PyCapsule`");
97    capsule.into_any().unbind()
98}
99
100/// Drops a `PyCapsule` containing a `CVec` structure.
101///
102/// This function safely extracts and drops the `CVec` instance encapsulated within
103/// a `PyCapsule` object. It is intended for cleaning up after the `Data` instances
104/// have been transferred into Python and are no longer needed.
105///
106/// # Panics
107///
108/// Panics if the capsule cannot be downcast to a `PyCapsule`, indicating a type
109/// mismatch or improper capsule handling.
110///
111/// # Safety
112///
113/// This function is unsafe as it involves raw pointer dereferencing and manual memory
114/// management. The caller must ensure the `PyCapsule` contains a valid `CVec` pointer.
115/// Incorrect usage can lead to memory corruption or undefined behavior.
116#[cfg(feature = "ffi")]
117#[pyfunction]
118#[allow(unsafe_code)]
119pub fn drop_cvec_pycapsule(capsule: &Bound<'_, PyAny>) {
120    let capsule: &Bound<'_, PyCapsule> = capsule
121        .cast::<PyCapsule>()
122        .expect("Error on downcast to `&PyCapsule`");
123    let cvec: &CVec = unsafe { &*(capsule.pointer_checked(None).unwrap().as_ptr() as *const CVec) };
124    let data: Vec<Data> =
125        unsafe { Vec::from_raw_parts(cvec.ptr.cast::<Data>(), cvec.len, cvec.cap) };
126    drop(data);
127}
128
129#[cfg(not(feature = "ffi"))]
130#[pyfunction]
131/// Drops a Python `PyCapsule` containing a `CVec` when the `ffi` feature is not enabled.
132///
133/// # Panics
134///
135/// Always panics with the message "`ffi` feature is not enabled" to indicate that
136/// FFI functionality is unavailable.
137pub fn drop_cvec_pycapsule(_capsule: &Bound<'_, PyAny>) {
138    panic!("`ffi` feature is not enabled");
139}
140
141/// Transforms the given Python objects into a vector of [`OrderBookDelta`] objects.
142///
143/// # Errors
144///
145/// Returns a `PyErr` if element conversion fails or the data is not monotonically increasing.
146pub fn pyobjects_to_book_deltas(data: Vec<Bound<'_, PyAny>>) -> PyResult<Vec<OrderBookDelta>> {
147    let deltas: Vec<OrderBookDelta> = data
148        .into_iter()
149        .map(|obj| OrderBookDelta::from_pyobject(&obj))
150        .collect::<PyResult<Vec<OrderBookDelta>>>()?;
151
152    // Validate monotonically increasing
153    if !is_monotonically_increasing_by_init(&deltas) {
154        return Err(to_pyvalue_err(ERROR_MONOTONICITY));
155    }
156
157    Ok(deltas)
158}
159
160/// Transforms the given Python objects into a vector of [`QuoteTick`] objects.
161///
162/// # Errors
163///
164/// Returns a `PyErr` if element conversion fails or the data is not monotonically increasing.
165pub fn pyobjects_to_quotes(data: Vec<Bound<'_, PyAny>>) -> PyResult<Vec<QuoteTick>> {
166    let quotes: Vec<QuoteTick> = data
167        .into_iter()
168        .map(|obj| QuoteTick::from_pyobject(&obj))
169        .collect::<PyResult<Vec<QuoteTick>>>()?;
170
171    // Validate monotonically increasing
172    if !is_monotonically_increasing_by_init(&quotes) {
173        return Err(to_pyvalue_err(ERROR_MONOTONICITY));
174    }
175
176    Ok(quotes)
177}
178
179/// Transforms the given Python objects into a vector of [`TradeTick`] objects.
180///
181/// # Errors
182///
183/// Returns a `PyErr` if element conversion fails or the data is not monotonically increasing.
184pub fn pyobjects_to_trades(data: Vec<Bound<'_, PyAny>>) -> PyResult<Vec<TradeTick>> {
185    let trades: Vec<TradeTick> = data
186        .into_iter()
187        .map(|obj| TradeTick::from_pyobject(&obj))
188        .collect::<PyResult<Vec<TradeTick>>>()?;
189
190    // Validate monotonically increasing
191    if !is_monotonically_increasing_by_init(&trades) {
192        return Err(to_pyvalue_err(ERROR_MONOTONICITY));
193    }
194
195    Ok(trades)
196}
197
198/// Transforms the given Python objects into a vector of [`Bar`] objects.
199///
200/// # Errors
201///
202/// Returns a `PyErr` if element conversion fails or the data is not monotonically increasing.
203pub fn pyobjects_to_bars(data: Vec<Bound<'_, PyAny>>) -> PyResult<Vec<Bar>> {
204    let bars: Vec<Bar> = data
205        .into_iter()
206        .map(|obj| Bar::from_pyobject(&obj))
207        .collect::<PyResult<Vec<Bar>>>()?;
208
209    // Validate monotonically increasing
210    if !is_monotonically_increasing_by_init(&bars) {
211        return Err(to_pyvalue_err(ERROR_MONOTONICITY));
212    }
213
214    Ok(bars)
215}
216
217/// Transforms the given Python objects into a vector of [`MarkPriceUpdate`] objects.
218///
219/// # Errors
220///
221/// Returns a `PyErr` if element conversion fails or the data is not monotonically increasing.
222pub fn pyobjects_to_mark_prices(data: Vec<Bound<'_, PyAny>>) -> PyResult<Vec<MarkPriceUpdate>> {
223    let mark_prices: Vec<MarkPriceUpdate> = data
224        .into_iter()
225        .map(|obj| MarkPriceUpdate::from_pyobject(&obj))
226        .collect::<PyResult<Vec<MarkPriceUpdate>>>()?;
227
228    // Validate monotonically increasing
229    if !is_monotonically_increasing_by_init(&mark_prices) {
230        return Err(to_pyvalue_err(ERROR_MONOTONICITY));
231    }
232
233    Ok(mark_prices)
234}
235
236/// Transforms the given Python objects into a vector of [`IndexPriceUpdate`] objects.
237///
238/// # Errors
239///
240/// Returns a `PyErr` if element conversion fails or the data is not monotonically increasing.
241pub fn pyobjects_to_index_prices(data: Vec<Bound<'_, PyAny>>) -> PyResult<Vec<IndexPriceUpdate>> {
242    let index_prices: Vec<IndexPriceUpdate> = data
243        .into_iter()
244        .map(|obj| IndexPriceUpdate::from_pyobject(&obj))
245        .collect::<PyResult<Vec<IndexPriceUpdate>>>()?;
246
247    // Validate monotonically increasing
248    if !is_monotonically_increasing_by_init(&index_prices) {
249        return Err(to_pyvalue_err(ERROR_MONOTONICITY));
250    }
251
252    Ok(index_prices)
253}
254
255/// Transforms the given Python objects into a vector of [`InstrumentClose`] objects.
256///
257/// # Errors
258///
259/// Returns a `PyErr` if element conversion fails or the data is not monotonically increasing.
260pub fn pyobjects_to_instrument_closes(
261    data: Vec<Bound<'_, PyAny>>,
262) -> PyResult<Vec<InstrumentClose>> {
263    let closes: Vec<InstrumentClose> = data
264        .into_iter()
265        .map(|obj| InstrumentClose::from_pyobject(&obj))
266        .collect::<PyResult<Vec<InstrumentClose>>>()?;
267
268    // Validate monotonically increasing
269    if !is_monotonically_increasing_by_init(&closes) {
270        return Err(to_pyvalue_err(ERROR_MONOTONICITY));
271    }
272
273    Ok(closes)
274}
275
276/// Transforms the given Python objects into a vector of [`FundingRateUpdate`] objects.
277///
278/// # Errors
279///
280/// Returns a `PyErr` if element conversion fails or the data is not monotonically increasing.
281pub fn pyobjects_to_funding_rates(data: Vec<Bound<'_, PyAny>>) -> PyResult<Vec<FundingRateUpdate>> {
282    let funding_rates: Vec<FundingRateUpdate> = data
283        .into_iter()
284        .map(|obj| FundingRateUpdate::from_pyobject(&obj))
285        .collect::<PyResult<Vec<FundingRateUpdate>>>()?;
286
287    // Validate monotonically increasing
288    if !is_monotonically_increasing_by_init(&funding_rates) {
289        return Err(to_pyvalue_err(ERROR_MONOTONICITY));
290    }
291
292    Ok(funding_rates)
293}
nautilus_model/python/data/mod.rs

nautilus_model/python/data/
mod.rs
