nautilus_model/python/data/
mod.rs

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

nautilus_model/python/data/
mod.rs
