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 delta;
21pub mod deltas;
22pub mod depth;
23pub mod greeks;
24pub mod order;
25pub mod quote;
26pub mod status;
27pub mod trade;
28
29use indexmap::IndexMap;
30#[cfg(feature = "ffi")]
31use nautilus_core::ffi::cvec::CVec;
32use pyo3::{exceptions::PyValueError, prelude::*, types::PyCapsule};
33
34use crate::data::{
35    is_monotonically_increasing_by_init, Bar, Data, DataType, OrderBookDelta, QuoteTick, TradeTick,
36};
37
38const ERROR_MONOTONICITY: &str = "`data` was not monotonically increasing by the `ts_init` field";
39
40#[pymethods]
41impl DataType {
42    #[new]
43    #[pyo3(signature = (type_name, metadata=None))]
44    fn py_new(type_name: &str, metadata: Option<IndexMap<String, String>>) -> Self {
45        Self::new(type_name, metadata)
46    }
47
48    #[getter]
49    #[pyo3(name = "type_name")]
50    fn py_type_name(&self) -> &str {
51        self.type_name()
52    }
53
54    #[getter]
55    #[pyo3(name = "metadata")]
56    fn py_metadata(&self) -> Option<IndexMap<String, String>> {
57        self.metadata().cloned()
58    }
59
60    #[getter]
61    #[pyo3(name = "topic")]
62    fn py_topic(&self) -> &str {
63        self.topic()
64    }
65}
66
67/// Creates a Python `PyCapsule` object containing a Rust `Data` instance.
68///
69/// This function takes ownership of the `Data` instance and encapsulates it within
70/// a `PyCapsule` object, allowing the Rust data to be passed into the Python runtime.
71///
72/// # Panics
73///
74/// This function will panic if the `PyCapsule` creation fails, which may occur if
75/// there are issues with memory allocation or if the `Data` instance cannot be
76/// properly encapsulated.
77///
78/// # Safety
79///
80/// This function is safe as long as the `Data` instance does not violate Rust's
81/// safety guarantees (e.g., no invalid memory access). Users of the
82/// `PyCapsule` in Python must ensure they understand how to extract and use the
83/// encapsulated `Data` safely, especially when converting the capsule back to a
84/// Rust data structure.
85#[must_use]
86pub fn data_to_pycapsule(py: Python, data: Data) -> PyObject {
87    let capsule = PyCapsule::new(py, data, None).expect("Error creating `PyCapsule`");
88    capsule.into_any().unbind()
89}
90
91/// Drops a `PyCapsule` containing a `CVec` structure.
92///
93/// This function safely extracts and drops the `CVec` instance encapsulated within
94/// a `PyCapsule` object. It is intended for cleaning up after the `Data` instances
95/// have been transferred into Python and are no longer needed.
96///
97/// # Panics
98///
99/// This function panics:
100/// - If the capsule cannot be downcast to a `PyCapsule`, indicating a type mismatch
101/// or improper capsule handling.
102///
103/// # Safety
104///
105/// This function is unsafe as it involves raw pointer dereferencing and manual memory
106/// management. The caller must ensure the `PyCapsule` contains a valid `CVec` pointer.
107/// Incorrect usage can lead to memory corruption or undefined behavior.
108#[pyfunction]
109#[cfg(feature = "ffi")]
110pub fn drop_cvec_pycapsule(capsule: &Bound<'_, PyAny>) {
111    let capsule: &Bound<'_, PyCapsule> = capsule
112        .downcast::<PyCapsule>()
113        .expect("Error on downcast to `&PyCapsule`");
114    let cvec: &CVec = unsafe { &*(capsule.pointer() as *const CVec) };
115    let data: Vec<Data> =
116        unsafe { Vec::from_raw_parts(cvec.ptr.cast::<Data>(), cvec.len, cvec.cap) };
117    drop(data);
118}
119
120#[pyfunction]
121#[cfg(not(feature = "ffi"))]
122pub fn drop_cvec_pycapsule(_capsule: &Bound<'_, PyAny>) {
123    panic!("`ffi` feature is not enabled");
124}
125
126/// Transforms the given `data` Python objects into a vector of [`OrderBookDelta`] objects.
127pub fn pyobjects_to_order_book_deltas(
128    data: Vec<Bound<'_, PyAny>>,
129) -> PyResult<Vec<OrderBookDelta>> {
130    let deltas: Vec<OrderBookDelta> = data
131        .into_iter()
132        .map(|obj| OrderBookDelta::from_pyobject(&obj))
133        .collect::<PyResult<Vec<OrderBookDelta>>>()?;
134
135    // Validate monotonically increasing
136    if !is_monotonically_increasing_by_init(&deltas) {
137        return Err(PyValueError::new_err(ERROR_MONOTONICITY));
138    }
139
140    Ok(deltas)
141}
142
143/// Transforms the given `data` Python objects into a vector of [`QuoteTick`] objects.
144pub fn pyobjects_to_quote_ticks(data: Vec<Bound<'_, PyAny>>) -> PyResult<Vec<QuoteTick>> {
145    let ticks: Vec<QuoteTick> = data
146        .into_iter()
147        .map(|obj| QuoteTick::from_pyobject(&obj))
148        .collect::<PyResult<Vec<QuoteTick>>>()?;
149
150    // Validate monotonically increasing
151    if !is_monotonically_increasing_by_init(&ticks) {
152        return Err(PyValueError::new_err(ERROR_MONOTONICITY));
153    }
154
155    Ok(ticks)
156}
157
158/// Transforms the given `data` Python objects into a vector of [`TradeTick`] objects.
159pub fn pyobjects_to_trade_ticks(data: Vec<Bound<'_, PyAny>>) -> PyResult<Vec<TradeTick>> {
160    let ticks: Vec<TradeTick> = data
161        .into_iter()
162        .map(|obj| TradeTick::from_pyobject(&obj))
163        .collect::<PyResult<Vec<TradeTick>>>()?;
164
165    // Validate monotonically increasing
166    if !is_monotonically_increasing_by_init(&ticks) {
167        return Err(PyValueError::new_err(ERROR_MONOTONICITY));
168    }
169
170    Ok(ticks)
171}
172
173/// Transforms the given `data` Python objects into a vector of [`Bar`] objects.
174pub fn pyobjects_to_bars(data: Vec<Bound<'_, PyAny>>) -> PyResult<Vec<Bar>> {
175    let bars: Vec<Bar> = data
176        .into_iter()
177        .map(|obj| Bar::from_pyobject(&obj))
178        .collect::<PyResult<Vec<Bar>>>()?;
179
180    // Validate monotonically increasing
181    if !is_monotonically_increasing_by_init(&bars) {
182        return Err(PyValueError::new_err(ERROR_MONOTONICITY));
183    }
184
185    Ok(bars)
186}
nautilus_model/python/data/mod.rs

nautilus_model/python/data/
mod.rs
