nautilus_model/python/data/
mod.rs

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

nautilus_model/python/data/
mod.rs
