nautilus_model/python/data/
quote.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
16use std::{
17    collections::{hash_map::DefaultHasher, HashMap},
18    hash::{Hash, Hasher},
19    str::FromStr,
20};
21
22use nautilus_core::{
23    python::{
24        serialization::{from_dict_pyo3, to_dict_pyo3},
25        to_pyvalue_err,
26    },
27    serialization::Serializable,
28    UnixNanos,
29};
30use pyo3::{
31    prelude::*,
32    pyclass::CompareOp,
33    types::{PyDict, PyLong, PyString, PyTuple},
34};
35
36use super::data_to_pycapsule;
37use crate::{
38    data::{Data, QuoteTick},
39    enums::PriceType,
40    identifiers::InstrumentId,
41    python::common::PY_MODULE_MODEL,
42    types::{
43        price::{Price, PriceRaw},
44        quantity::{Quantity, QuantityRaw},
45    },
46};
47
48impl QuoteTick {
49    /// Create a new [`QuoteTick`] extracted from the given [`PyAny`].
50    pub fn from_pyobject(obj: &Bound<'_, PyAny>) -> PyResult<Self> {
51        let instrument_id_obj: Bound<'_, PyAny> = obj.getattr("instrument_id")?.extract()?;
52        let instrument_id_str: String = instrument_id_obj.getattr("value")?.extract()?;
53        let instrument_id =
54            InstrumentId::from_str(instrument_id_str.as_str()).map_err(to_pyvalue_err)?;
55
56        let bid_price_py: Bound<'_, PyAny> = obj.getattr("bid_price")?.extract()?;
57        let bid_price_raw: PriceRaw = bid_price_py.getattr("raw")?.extract()?;
58        let bid_price_prec: u8 = bid_price_py.getattr("precision")?.extract()?;
59        let bid_price = Price::from_raw(bid_price_raw, bid_price_prec);
60
61        let ask_price_py: Bound<'_, PyAny> = obj.getattr("ask_price")?.extract()?;
62        let ask_price_raw: PriceRaw = ask_price_py.getattr("raw")?.extract()?;
63        let ask_price_prec: u8 = ask_price_py.getattr("precision")?.extract()?;
64        let ask_price = Price::from_raw(ask_price_raw, ask_price_prec);
65
66        let bid_size_py: Bound<'_, PyAny> = obj.getattr("bid_size")?.extract()?;
67        let bid_size_raw: QuantityRaw = bid_size_py.getattr("raw")?.extract()?;
68        let bid_size_prec: u8 = bid_size_py.getattr("precision")?.extract()?;
69        let bid_size = Quantity::from_raw(bid_size_raw, bid_size_prec);
70
71        let ask_size_py: Bound<'_, PyAny> = obj.getattr("ask_size")?.extract()?;
72        let ask_size_raw: QuantityRaw = ask_size_py.getattr("raw")?.extract()?;
73        let ask_size_prec: u8 = ask_size_py.getattr("precision")?.extract()?;
74        let ask_size = Quantity::from_raw(ask_size_raw, ask_size_prec);
75
76        let ts_event: u64 = obj.getattr("ts_event")?.extract()?;
77        let ts_init: u64 = obj.getattr("ts_init")?.extract()?;
78
79        Self::new_checked(
80            instrument_id,
81            bid_price,
82            ask_price,
83            bid_size,
84            ask_size,
85            ts_event.into(),
86            ts_init.into(),
87        )
88        .map_err(to_pyvalue_err)
89    }
90}
91
92#[pymethods]
93impl QuoteTick {
94    #[new]
95    fn py_new(
96        instrument_id: InstrumentId,
97        bid_price: Price,
98        ask_price: Price,
99        bid_size: Quantity,
100        ask_size: Quantity,
101        ts_event: u64,
102        ts_init: u64,
103    ) -> PyResult<Self> {
104        Self::new_checked(
105            instrument_id,
106            bid_price,
107            ask_price,
108            bid_size,
109            ask_size,
110            ts_event.into(),
111            ts_init.into(),
112        )
113        .map_err(to_pyvalue_err)
114    }
115
116    fn __setstate__(&mut self, state: &Bound<'_, PyAny>) -> PyResult<()> {
117        let py_tuple: &Bound<'_, PyTuple> = state.downcast::<PyTuple>()?;
118        let binding = py_tuple.get_item(0)?;
119        let instrument_id_str: &str = binding.downcast::<PyString>()?.extract()?;
120        let bid_price_raw: PriceRaw = py_tuple.get_item(1)?.downcast::<PyLong>()?.extract()?;
121        let ask_price_raw: PriceRaw = py_tuple.get_item(2)?.downcast::<PyLong>()?.extract()?;
122        let bid_price_prec: u8 = py_tuple.get_item(3)?.downcast::<PyLong>()?.extract()?;
123        let ask_price_prec: u8 = py_tuple.get_item(4)?.downcast::<PyLong>()?.extract()?;
124
125        let bid_size_raw: QuantityRaw = py_tuple.get_item(5)?.downcast::<PyLong>()?.extract()?;
126        let ask_size_raw: QuantityRaw = py_tuple.get_item(6)?.downcast::<PyLong>()?.extract()?;
127        let bid_size_prec: u8 = py_tuple.get_item(7)?.downcast::<PyLong>()?.extract()?;
128        let ask_size_prec: u8 = py_tuple.get_item(8)?.downcast::<PyLong>()?.extract()?;
129        let ts_event: u64 = py_tuple.get_item(9)?.downcast::<PyLong>()?.extract()?;
130        let ts_init: u64 = py_tuple.get_item(10)?.downcast::<PyLong>()?.extract()?;
131
132        self.instrument_id = InstrumentId::from_str(instrument_id_str).map_err(to_pyvalue_err)?;
133        self.bid_price = Price::from_raw(bid_price_raw, bid_price_prec);
134        self.ask_price = Price::from_raw(ask_price_raw, ask_price_prec);
135        self.bid_size = Quantity::from_raw(bid_size_raw, bid_size_prec);
136        self.ask_size = Quantity::from_raw(ask_size_raw, ask_size_prec);
137        self.ts_event = ts_event.into();
138        self.ts_init = ts_init.into();
139
140        Ok(())
141    }
142
143    fn __getstate__(&self, py: Python) -> PyResult<PyObject> {
144        Ok((
145            self.instrument_id.to_string(),
146            self.bid_price.raw,
147            self.ask_price.raw,
148            self.bid_price.precision,
149            self.ask_price.precision,
150            self.bid_size.raw,
151            self.ask_size.raw,
152            self.bid_size.precision,
153            self.ask_size.precision,
154            self.ts_event.as_u64(),
155            self.ts_init.as_u64(),
156        )
157            .to_object(py))
158    }
159
160    fn __reduce__(&self, py: Python) -> PyResult<PyObject> {
161        let safe_constructor = py.get_type::<Self>().getattr("_safe_constructor")?;
162        let state = self.__getstate__(py)?;
163        Ok((safe_constructor, PyTuple::empty(py), state).to_object(py))
164    }
165
166    #[staticmethod]
167    fn _safe_constructor() -> PyResult<Self> {
168        Self::new_checked(
169            InstrumentId::from("NULL.NULL"),
170            Price::zero(0),
171            Price::zero(0),
172            Quantity::zero(0),
173            Quantity::zero(0),
174            UnixNanos::default(),
175            UnixNanos::default(),
176        )
177        .map_err(to_pyvalue_err)
178    }
179
180    fn __richcmp__(&self, other: &Self, op: CompareOp, py: Python<'_>) -> Py<PyAny> {
181        match op {
182            CompareOp::Eq => self.eq(other).into_py(py),
183            CompareOp::Ne => self.ne(other).into_py(py),
184            _ => py.NotImplemented(),
185        }
186    }
187
188    fn __hash__(&self) -> isize {
189        let mut h = DefaultHasher::new();
190        self.hash(&mut h);
191        h.finish() as isize
192    }
193
194    fn __repr__(&self) -> String {
195        format!("{}({})", stringify!(QuoteTick), self)
196    }
197
198    fn __str__(&self) -> String {
199        self.to_string()
200    }
201
202    #[getter]
203    #[pyo3(name = "instrument_id")]
204    fn py_instrument_id(&self) -> InstrumentId {
205        self.instrument_id
206    }
207
208    #[getter]
209    #[pyo3(name = "bid_price")]
210    fn py_bid_price(&self) -> Price {
211        self.bid_price
212    }
213
214    #[getter]
215    #[pyo3(name = "ask_price")]
216    fn py_ask_price(&self) -> Price {
217        self.ask_price
218    }
219
220    #[getter]
221    #[pyo3(name = "bid_size")]
222    fn py_bid_size(&self) -> Quantity {
223        self.bid_size
224    }
225
226    #[getter]
227    #[pyo3(name = "ask_size")]
228    fn py_ask_size(&self) -> Quantity {
229        self.ask_size
230    }
231
232    #[getter]
233    #[pyo3(name = "ts_event")]
234    fn py_ts_event(&self) -> u64 {
235        self.ts_event.as_u64()
236    }
237
238    #[getter]
239    #[pyo3(name = "ts_init")]
240    fn py_ts_init(&self) -> u64 {
241        self.ts_init.as_u64()
242    }
243
244    #[staticmethod]
245    #[pyo3(name = "fully_qualified_name")]
246    fn py_fully_qualified_name() -> String {
247        format!("{}:{}", PY_MODULE_MODEL, stringify!(QuoteTick))
248    }
249
250    #[staticmethod]
251    #[pyo3(name = "get_metadata")]
252    fn py_get_metadata(
253        instrument_id: &InstrumentId,
254        price_precision: u8,
255        size_precision: u8,
256    ) -> PyResult<HashMap<String, String>> {
257        Ok(Self::get_metadata(
258            instrument_id,
259            price_precision,
260            size_precision,
261        ))
262    }
263
264    #[staticmethod]
265    #[pyo3(name = "get_fields")]
266    fn py_get_fields(py: Python<'_>) -> PyResult<Bound<'_, PyDict>> {
267        let py_dict = PyDict::new(py);
268        for (k, v) in Self::get_fields() {
269            py_dict.set_item(k, v)?;
270        }
271
272        Ok(py_dict)
273    }
274
275    #[staticmethod]
276    #[pyo3(name = "from_raw")]
277    #[allow(clippy::too_many_arguments)]
278    fn py_from_raw(
279        instrument_id: InstrumentId,
280        bid_price_raw: PriceRaw,
281        ask_price_raw: PriceRaw,
282        bid_price_prec: u8,
283        ask_price_prec: u8,
284        bid_size_raw: QuantityRaw,
285        ask_size_raw: QuantityRaw,
286        bid_size_prec: u8,
287        ask_size_prec: u8,
288        ts_event: u64,
289        ts_init: u64,
290    ) -> PyResult<Self> {
291        Self::new_checked(
292            instrument_id,
293            Price::from_raw(bid_price_raw, bid_price_prec),
294            Price::from_raw(ask_price_raw, ask_price_prec),
295            Quantity::from_raw(bid_size_raw, bid_size_prec),
296            Quantity::from_raw(ask_size_raw, ask_size_prec),
297            ts_event.into(),
298            ts_init.into(),
299        )
300        .map_err(to_pyvalue_err)
301    }
302
303    /// Returns a new object from the given dictionary representation.
304    #[staticmethod]
305    #[pyo3(name = "from_dict")]
306    fn py_from_dict(py: Python<'_>, values: Py<PyDict>) -> PyResult<Self> {
307        from_dict_pyo3(py, values)
308    }
309
310    #[staticmethod]
311    #[pyo3(name = "from_json")]
312    fn py_from_json(data: Vec<u8>) -> PyResult<Self> {
313        Self::from_json_bytes(&data).map_err(to_pyvalue_err)
314    }
315
316    #[staticmethod]
317    #[pyo3(name = "from_msgpack")]
318    fn py_from_msgpack(data: Vec<u8>) -> PyResult<Self> {
319        Self::from_msgpack_bytes(&data).map_err(to_pyvalue_err)
320    }
321
322    #[pyo3(name = "extract_price")]
323    fn py_extract_price(&self, price_type: PriceType) -> PyResult<Price> {
324        Ok(self.extract_price(price_type))
325    }
326
327    #[pyo3(name = "extract_size")]
328    fn py_extract_size(&self, price_type: PriceType) -> PyResult<Quantity> {
329        Ok(self.extract_size(price_type))
330    }
331
332    /// Creates a `PyCapsule` containing a raw pointer to a `Data::Quote` object.
333    ///
334    /// This function takes the current object (assumed to be of a type that can be represented as
335    /// `Data::Quote`), and encapsulates a raw pointer to it within a `PyCapsule`.
336    ///
337    /// # Safety
338    ///
339    /// This function is safe as long as the following conditions are met:
340    /// - The `Data::Quote` object pointed to by the capsule must remain valid for the lifetime of the capsule.
341    /// - The consumer of the capsule must ensure proper handling to avoid dereferencing a dangling pointer.
342    ///
343    /// # Panics
344    ///
345    /// The function will panic if the `PyCapsule` creation fails, which can occur if the
346    /// `Data::Quote` object cannot be converted into a raw pointer.
347    #[pyo3(name = "as_pycapsule")]
348    fn py_as_pycapsule(&self, py: Python<'_>) -> PyObject {
349        data_to_pycapsule(py, Data::Quote(*self))
350    }
351
352    /// Return a dictionary representation of the object.
353    #[pyo3(name = "as_dict")]
354    fn py_as_dict(&self, py: Python<'_>) -> PyResult<Py<PyDict>> {
355        to_dict_pyo3(py, self)
356    }
357
358    /// Return JSON encoded bytes representation of the object.
359    #[pyo3(name = "as_json")]
360    fn py_as_json(&self, py: Python<'_>) -> Py<PyAny> {
361        // Unwrapping is safe when serializing a valid object
362        self.as_json_bytes().unwrap().into_py(py)
363    }
364
365    /// Return MsgPack encoded bytes representation of the object.
366    #[pyo3(name = "as_msgpack")]
367    fn py_as_msgpack(&self, py: Python<'_>) -> Py<PyAny> {
368        // Unwrapping is safe when serializing a valid object
369        self.as_msgpack_bytes().unwrap().into_py(py)
370    }
371}
372
373////////////////////////////////////////////////////////////////////////////////
374// Tests
375////////////////////////////////////////////////////////////////////////////////
376#[cfg(test)]
377mod tests {
378    use pyo3::{IntoPy, Python};
379    use rstest::rstest;
380
381    use crate::{
382        data::{stubs::quote_ethusdt_binance, QuoteTick},
383        identifiers::InstrumentId,
384        types::{Price, Quantity},
385    };
386
387    #[rstest]
388    #[case(
389    Price::from_raw(10_000_000, 6),
390    Price::from_raw(10_001_000, 7), // Mismatched precision
391    Quantity::from_raw(1_000_000, 6),
392    Quantity::from_raw(1_000_000, 6),
393)]
394    #[case(
395    Price::from_raw(10_000_000, 6),
396    Price::from_raw(10_001_000, 6),
397    Quantity::from_raw(1_000_000, 6),
398    Quantity::from_raw(1_000_000, 7), // Mismatched precision
399)]
400    fn test_quote_tick_py_new_invalid_precisions(
401        #[case] bid_price: Price,
402        #[case] ask_price: Price,
403        #[case] bid_size: Quantity,
404        #[case] ask_size: Quantity,
405    ) {
406        pyo3::prepare_freethreaded_python();
407
408        let instrument_id = InstrumentId::from("ETH-USDT-SWAP.OKX");
409        let ts_event = 0;
410        let ts_init = 1;
411
412        let result = QuoteTick::py_new(
413            instrument_id,
414            bid_price,
415            ask_price,
416            bid_size,
417            ask_size,
418            ts_event,
419            ts_init,
420        );
421
422        assert!(result.is_err());
423    }
424
425    #[rstest]
426    fn test_as_dict(quote_ethusdt_binance: QuoteTick) {
427        pyo3::prepare_freethreaded_python();
428        let quote = quote_ethusdt_binance;
429
430        Python::with_gil(|py| {
431            let dict_string = quote.py_as_dict(py).unwrap().to_string();
432            let expected_string = r"{'type': 'QuoteTick', 'instrument_id': 'ETHUSDT-PERP.BINANCE', 'bid_price': '10000.0000', 'ask_price': '10001.0000', 'bid_size': '1.00000000', 'ask_size': '1.00000000', 'ts_event': 0, 'ts_init': 1}";
433            assert_eq!(dict_string, expected_string);
434        });
435    }
436
437    #[rstest]
438    fn test_from_dict(quote_ethusdt_binance: QuoteTick) {
439        pyo3::prepare_freethreaded_python();
440        let quote = quote_ethusdt_binance;
441
442        Python::with_gil(|py| {
443            let dict = quote.py_as_dict(py).unwrap();
444            let parsed = QuoteTick::py_from_dict(py, dict).unwrap();
445            assert_eq!(parsed, quote);
446        });
447    }
448
449    #[rstest]
450    fn test_from_pyobject(quote_ethusdt_binance: QuoteTick) {
451        pyo3::prepare_freethreaded_python();
452        let quote = quote_ethusdt_binance;
453
454        Python::with_gil(|py| {
455            let tick_pyobject = quote.into_py(py);
456            let parsed_tick = QuoteTick::from_pyobject(tick_pyobject.bind(py)).unwrap();
457            assert_eq!(parsed_tick, quote);
458        });
459    }
460}
nautilus_model/python/data/quote.rs

nautilus_model/python/data/
quote.rs
