Skip to main content

nautilus_model/python/
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//! Python bindings from [PyO3](https://pyo3.rs).
17
18#![expect(
19    clippy::missing_errors_doc,
20    reason = "errors documented on underlying Rust methods"
21)]
22
23use nautilus_core::python::to_pyvalue_err;
24use pyo3::{PyErr, prelude::*};
25
26pub mod account;
27pub mod common;
28pub mod data;
29pub mod enums;
30pub mod events;
31pub mod identifiers;
32pub mod instruments;
33pub mod macros;
34pub mod orderbook;
35pub mod orders;
36pub mod position;
37pub mod reports;
38pub mod types;
39
40#[cfg(feature = "defi")]
41pub mod defi;
42
43use crate::{
44    data::{
45        CustomDataTrait, ensure_py_extractor_registered, ensure_rust_extractor_registered,
46        get_rust_extractor,
47        greeks::{GreeksData, PortfolioGreeks, YieldCurve},
48    },
49    identifiers::{InstrumentIdError, OptionSeriesIdError},
50    types::CurrencyLookupError,
51};
52
53/// Converts an instrument ID validation failure to a Python `ValueError`.
54#[must_use]
55#[allow(
56    clippy::needless_pass_by_value,
57    reason = "Result::map_err passes owned errors to conversion functions"
58)]
59pub fn instrument_id_error_to_pyvalue_err(e: InstrumentIdError) -> PyErr {
60    to_pyvalue_err(e)
61}
62
63/// Converts an option series ID validation failure to a Python `ValueError`.
64#[must_use]
65#[allow(
66    clippy::needless_pass_by_value,
67    reason = "Result::map_err passes owned errors to conversion functions"
68)]
69pub fn option_series_id_error_to_pyvalue_err(e: OptionSeriesIdError) -> PyErr {
70    to_pyvalue_err(e)
71}
72
73/// Converts a currency lookup failure to a Python `ValueError`.
74#[must_use]
75#[allow(
76    clippy::needless_pass_by_value,
77    reason = "Result::map_err passes owned errors to conversion functions"
78)]
79pub fn currency_lookup_error_to_pyvalue_err(e: CurrencyLookupError) -> PyErr {
80    to_pyvalue_err(e)
81}
82
83/// Exposed through `nautilus_trader.model`.
84///
85/// # Errors
86///
87/// Returns an error if registering any module components fails.
88#[pymodule]
89pub fn model(_: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
90    let _result = ensure_rust_extractor_registered::<GreeksData>();
91    let _result = ensure_rust_extractor_registered::<PortfolioGreeks>();
92    let _result = ensure_rust_extractor_registered::<YieldCurve>();
93
94    for type_name in [
95        GreeksData::type_name_static(),
96        PortfolioGreeks::type_name_static(),
97        YieldCurve::type_name_static(),
98    ] {
99        if let Some(extractor) = get_rust_extractor(type_name) {
100            let _result = ensure_py_extractor_registered(type_name, extractor);
101        }
102    }
103
104    // Types
105    m.add("HIGH_PRECISION", crate::types::fixed::HIGH_PRECISION_MODE)?;
106    m.add("FIXED_SCALAR", crate::types::fixed::FIXED_SCALAR)?;
107    m.add("FIXED_PRECISION", crate::types::fixed::FIXED_PRECISION)?;
108    m.add("PRECISION_BYTES", crate::types::fixed::PRECISION_BYTES)?;
109    m.add_class::<crate::types::currency::Currency>()?;
110    m.add_class::<crate::types::money::Money>()?;
111    m.add_class::<crate::types::price::Price>()?;
112    m.add_class::<crate::types::quantity::Quantity>()?;
113    m.add_class::<crate::types::balance::AccountBalance>()?;
114    m.add_class::<crate::types::balance::MarginBalance>()?;
115    m.add_class::<crate::python::common::EnumIterator>()?;
116    // Data
117    m.add_class::<data::PyNautilusDataType>()?;
118    m.add_class::<data::PyNautilusRecordType>()?;
119    m.add_class::<instruments::PyNautilusInstrumentType>()?;
120    for record_type in <crate::data::NautilusRecordType as strum::IntoEnumIterator>::iter() {
121        m.getattr("NautilusRecordType")?.setattr(
122            record_type.to_string(),
123            Py::new(m.py(), data::PyNautilusRecordType::new(record_type))?,
124        )?;
125    }
126
127    for instrument_type in
128        <crate::instruments::NautilusInstrumentType as strum::IntoEnumIterator>::iter()
129    {
130        m.getattr("NautilusInstrumentType")?.setattr(
131            instrument_type.to_string(),
132            Py::new(
133                m.py(),
134                instruments::PyNautilusInstrumentType::new(instrument_type),
135            )?,
136        )?;
137    }
138    m.add_class::<crate::data::DataType>()?;
139    m.add_class::<crate::data::CustomData>()?;
140    m.add_function(pyo3::wrap_pyfunction!(
141        crate::python::data::deserialize_custom_from_json,
142        m
143    )?)?;
144    m.add_function(pyo3::wrap_pyfunction!(
145        crate::python::data::register_custom_data_class,
146        m
147    )?)?;
148    m.add_function(pyo3::wrap_pyfunction!(
149        crate::python::data::custom::custom_data_backend_kind,
150        m
151    )?)?;
152    m.add_class::<crate::data::bar::BarSpecification>()?;
153    m.add_class::<crate::data::bar::BarType>()?;
154    m.add_class::<crate::data::bar::Bar>()?;
155    m.add_class::<crate::data::bet::Bet>()?;
156    m.add_class::<crate::data::bet::BetPosition>()?;
157    m.add_class::<crate::data::order::BookOrder>()?;
158    m.add_class::<crate::data::prices::MarkPriceUpdate>()?;
159    m.add_class::<crate::data::prices::IndexPriceUpdate>()?;
160    m.add_class::<crate::data::delta::OrderBookDelta>()?;
161    m.add_class::<crate::data::deltas::OrderBookDeltas>()?;
162    m.add_class::<crate::data::depth::OrderBookDepth>()?;
163    m.add_class::<crate::data::quote::QuoteTick>()?;
164    m.add_class::<crate::data::status::InstrumentStatus>()?;
165    m.add_class::<crate::data::trade::TradeTick>()?;
166    m.add_class::<crate::data::close::InstrumentClose>()?;
167    m.add_class::<crate::data::funding::FundingRateUpdate>()?;
168    m.add_class::<crate::data::greeks::OptionGreekValues>()?;
169    m.add_class::<crate::data::greeks::BlackScholesGreeksResult>()?;
170    m.add_class::<crate::data::greeks::GreeksData>()?;
171    m.add_class::<crate::data::greeks::PortfolioGreeks>()?;
172    m.add_class::<crate::data::greeks::YieldCurve>()?;
173    m.add_class::<crate::data::option_chain::OptionGreeks>()?;
174    m.add_class::<crate::data::option_chain::OptionChainSlice>()?;
175    m.add_class::<crate::data::option_chain::OptionStrikeData>()?;
176    m.add_class::<crate::python::data::option_chain::PyStrikeRange>()?;
177    m.add_function(wrap_pyfunction!(
178        crate::python::data::greeks::py_black_scholes_greeks,
179        m
180    )?)?;
181    m.add_function(wrap_pyfunction!(
182        crate::python::data::greeks::py_imply_vol,
183        m
184    )?)?;
185    m.add_function(wrap_pyfunction!(
186        crate::python::data::greeks::py_imply_vol_and_greeks,
187        m
188    )?)?;
189    m.add_function(wrap_pyfunction!(
190        crate::python::data::greeks::py_refine_vol_and_greeks,
191        m
192    )?)?;
193    // Enums
194    m.add_class::<crate::enums::AccountType>()?;
195    m.add_class::<crate::enums::AggregationSource>()?;
196    m.add_class::<crate::enums::AggressorSide>()?;
197    m.add_class::<crate::enums::AssetClass>()?;
198    m.add_class::<crate::enums::AvgPxReconciliation>()?;
199    m.add_class::<crate::enums::BarAggregation>()?;
200    m.add_class::<crate::enums::BarIntervalType>()?;
201    m.add_class::<crate::enums::BetSide>()?;
202    m.add_class::<crate::enums::BookAction>()?;
203    m.add_class::<crate::enums::BookType>()?;
204    m.add_class::<crate::enums::ContingencyType>()?;
205    m.add_class::<crate::enums::ContinuousFutureAdjustmentType>()?;
206    m.add_class::<crate::enums::CurrencyType>()?;
207    m.add_class::<crate::enums::GreeksConvention>()?;
208    m.add_class::<crate::enums::InstrumentClass>()?;
209    m.add_class::<crate::enums::InstrumentCloseType>()?;
210    m.add_class::<crate::enums::LiquiditySide>()?;
211    m.add_class::<crate::enums::MarketStatus>()?;
212    m.add_class::<crate::enums::MarketStatusAction>()?;
213    m.add_class::<crate::enums::OmsType>()?;
214    m.add_class::<crate::enums::OptionKind>()?;
215    m.add_class::<crate::enums::OptionSideFilter>()?;
216    m.add_class::<crate::enums::OtoTriggerMode>()?;
217    m.add_class::<crate::enums::OrderSide>()?;
218    m.add_class::<crate::enums::OrderStatus>()?;
219    m.add_class::<crate::enums::OrderType>()?;
220    m.add_class::<crate::enums::PositionAdjustmentType>()?;
221    m.add_class::<crate::enums::PositionSide>()?;
222    m.add_class::<crate::enums::PriceType>()?;
223    m.add_class::<crate::enums::RecordFlag>()?;
224    m.add_class::<crate::enums::TimeInForce>()?;
225    m.add_class::<crate::enums::TradingState>()?;
226    m.add_class::<crate::enums::TrailingOffsetType>()?;
227    m.add_class::<crate::enums::TriggerType>()?;
228    // Identifiers
229    m.add_class::<crate::identifiers::AccountId>()?;
230    m.add_class::<crate::identifiers::ActorId>()?;
231    m.add_class::<crate::identifiers::ClientId>()?;
232    m.add_class::<crate::identifiers::ClientOrderId>()?;
233    m.add_class::<crate::identifiers::ComponentId>()?;
234    m.add_class::<crate::identifiers::ExecAlgorithmId>()?;
235    m.add_class::<crate::identifiers::InstrumentId>()?;
236    m.add_class::<crate::identifiers::OrderListId>()?;
237    m.add_class::<crate::identifiers::PositionId>()?;
238    m.add_class::<crate::identifiers::StrategyId>()?;
239    m.add_class::<crate::identifiers::Symbol>()?;
240    m.add_class::<crate::identifiers::TradeId>()?;
241    m.add_class::<crate::identifiers::TraderId>()?;
242    m.add_class::<crate::identifiers::Venue>()?;
243    m.add_class::<crate::identifiers::VenueOrderId>()?;
244    m.add_class::<crate::identifiers::OptionSeriesId>()?;
245    m.add_function(wrap_pyfunction!(
246        crate::python::identifiers::py_new_generic_spread_id,
247        m
248    )?)?;
249    m.add_function(wrap_pyfunction!(
250        crate::python::identifiers::py_generic_spread_id_to_list,
251        m
252    )?)?;
253    // Orders
254    m.add_class::<crate::orders::LimitOrder>()?;
255    m.add_class::<crate::orders::LimitIfTouchedOrder>()?;
256    m.add_class::<crate::orders::MarketIfTouchedOrder>()?;
257    m.add_class::<crate::orders::MarketOrder>()?;
258    m.add_class::<crate::orders::MarketToLimitOrder>()?;
259    m.add_class::<crate::orders::OrderList>()?;
260    m.add_class::<crate::orders::StopLimitOrder>()?;
261    m.add_class::<crate::orders::StopMarketOrder>()?;
262    m.add_class::<crate::orders::TrailingStopLimitOrder>()?;
263    m.add_class::<crate::orders::TrailingStopMarketOrder>()?;
264    // Reports
265    m.add_class::<crate::reports::fill::FillReport>()?;
266    m.add_class::<crate::reports::order::OrderStatusReport>()?;
267    m.add_class::<crate::reports::position::PositionStatusReport>()?;
268    m.add_class::<crate::reports::mass_status::ExecutionMassStatus>()?;
269    // Position
270    m.add_class::<crate::position::Position>()?;
271    m.add_function(wrap_pyfunction!(
272        crate::python::position::py_fold_net_position,
273        m
274    )?)?;
275    // Instruments
276    m.add_class::<instruments::tick_scheme::PyFixedTickScheme>()?;
277    m.add_class::<instruments::tick_scheme::PyTieredTickScheme>()?;
278    m.add_function(wrap_pyfunction!(
279        instruments::tick_scheme::py_register_tick_scheme,
280        m
281    )?)?;
282    m.add_function(wrap_pyfunction!(
283        instruments::tick_scheme::py_get_tick_scheme,
284        m
285    )?)?;
286    m.add_function(wrap_pyfunction!(
287        instruments::tick_scheme::py_list_tick_schemes,
288        m
289    )?)?;
290    m.add_class::<crate::instruments::BettingInstrument>()?;
291    m.add_class::<crate::instruments::BinaryOption>()?;
292    m.add_class::<crate::instruments::Cfd>()?;
293    m.add_class::<crate::instruments::Commodity>()?;
294    m.add_class::<crate::instruments::CryptoFuture>()?;
295    m.add_class::<crate::instruments::CryptoFuturesSpread>()?;
296    m.add_class::<crate::instruments::CryptoOption>()?;
297    m.add_class::<crate::instruments::CryptoOptionSpread>()?;
298    m.add_class::<crate::instruments::CryptoPerpetual>()?;
299    m.add_class::<crate::instruments::CurrencyPair>()?;
300    m.add_class::<crate::instruments::Equity>()?;
301    m.add_class::<crate::instruments::FuturesContract>()?;
302    m.add_class::<crate::instruments::FuturesSpread>()?;
303    m.add_class::<crate::instruments::IndexInstrument>()?;
304    m.add_class::<crate::instruments::OptionContract>()?;
305    m.add_class::<crate::instruments::OptionSpread>()?;
306    m.add_class::<crate::instruments::PerpetualContract>()?;
307    m.add_class::<crate::instruments::SyntheticInstrument>()?;
308    m.add_class::<crate::instruments::TokenizedAsset>()?;
309    // Order book
310    m.add_class::<crate::orderbook::book::OrderBook>()?;
311    m.add_class::<crate::orderbook::level::BookLevel>()?;
312    m.add_function(wrap_pyfunction!(
313        crate::python::orderbook::book::py_update_book_with_quote_tick,
314        m
315    )?)?;
316    m.add_function(wrap_pyfunction!(
317        crate::python::orderbook::book::py_update_book_with_trade_tick,
318        m
319    )?)?;
320    m.add_class::<crate::orderbook::own::OwnOrderBook>()?;
321    m.add_class::<crate::orderbook::own::OwnBookOrder>()?;
322    // Events
323    m.add_class::<crate::events::AccountState>()?;
324    m.add_class::<crate::events::OrderDenied>()?;
325    m.add_class::<crate::events::OrderFilled>()?;
326    m.add_class::<crate::events::OrderFillVoided>()?;
327    m.add_class::<crate::events::OrderInitialized>()?;
328    m.add_class::<crate::events::OrderRejected>()?;
329    m.add_class::<crate::events::OrderTriggered>()?;
330    m.add_class::<crate::events::OrderSubmitted>()?;
331    m.add_class::<crate::events::OrderEmulated>()?;
332    m.add_class::<crate::events::OrderReleased>()?;
333    m.add_class::<crate::events::OrderUpdated>()?;
334    m.add_class::<crate::events::OrderPendingUpdate>()?;
335    m.add_class::<crate::events::OrderPendingCancel>()?;
336    m.add_class::<crate::events::OrderModifyDenied>()?;
337    m.add_class::<crate::events::OrderModifyRejected>()?;
338    m.add_class::<crate::events::OrderAccepted>()?;
339    m.add_class::<crate::events::OrderCancelDenied>()?;
340    m.add_class::<crate::events::OrderCancelRejected>()?;
341    m.add_class::<crate::events::OrderCanceled>()?;
342    m.add_class::<crate::events::OrderExpired>()?;
343    m.add_class::<crate::events::OrderSnapshot>()?;
344    m.add_class::<crate::events::PositionOpened>()?;
345    m.add_class::<crate::events::PositionChanged>()?;
346    m.add_class::<crate::events::PositionClosed>()?;
347    m.add_class::<crate::events::PositionAdjusted>()?;
348    m.add_class::<crate::events::PositionSnapshot>()?;
349    m.add_class::<crate::events::PortfolioSnapshot>()?;
350    // Accounts
351    m.add_class::<crate::accounts::BettingAccount>()?;
352    m.add_class::<crate::accounts::CashAccount>()?;
353    m.add_class::<crate::accounts::MarginAccount>()?;
354    m.add_class::<crate::accounts::WalletAccount>()?;
355    m.add_class::<account::margin_model::PyMarginModel>()?;
356    m.add_class::<crate::accounts::margin_model::StandardMarginModel>()?;
357    m.add_class::<crate::accounts::margin_model::LeveragedMarginModel>()?;
358    m.add_function(wrap_pyfunction!(
359        crate::python::account::transformer::betting_account_from_account_events,
360        m
361    )?)?;
362    m.add_function(wrap_pyfunction!(
363        crate::python::account::transformer::cash_account_from_account_events,
364        m
365    )?)?;
366    m.add_function(wrap_pyfunction!(
367        crate::python::account::transformer::margin_account_from_account_events,
368        m
369    )?)?;
370    m.add_function(wrap_pyfunction!(
371        crate::python::account::transformer::wallet_account_from_account_events,
372        m
373    )?)?;
374    m.add_function(wrap_pyfunction!(
375        crate::python::data::bet::py_calc_bets_pnl,
376        m
377    )?)?;
378    m.add_function(wrap_pyfunction!(
379        crate::python::data::bet::py_probability_to_bet,
380        m
381    )?)?;
382    m.add_function(wrap_pyfunction!(
383        crate::python::data::bet::py_inverse_probability_to_bet,
384        m
385    )?)?;
386    // DeFi
387    #[cfg(feature = "defi")]
388    {
389        m.add_class::<crate::defi::chain::Blockchain>()?;
390        m.add_class::<crate::defi::chain::Chain>()?;
391        m.add_class::<crate::defi::token::Token>()?;
392        m.add_class::<crate::defi::dex::AmmType>()?;
393        m.add_class::<crate::defi::dex::Dex>()?;
394        m.add_class::<crate::defi::amm::Pool>()?;
395        m.add_class::<crate::defi::data::PoolSwap>()?;
396        m.add_class::<crate::defi::data::PoolLiquidityUpdateType>()?;
397        m.add_class::<crate::defi::data::PoolLiquidityUpdate>()?;
398        m.add_class::<crate::defi::data::PoolFeeCollect>()?;
399        m.add_class::<crate::defi::data::PoolFeeProtocolUpdate>()?;
400        m.add_class::<crate::defi::data::PoolFeeProtocolCollect>()?;
401        m.add_class::<crate::defi::data::PoolFlash>()?;
402        m.add_class::<crate::defi::data::Transaction>()?;
403        m.add_class::<crate::defi::data::Block>()?;
404        m.add_class::<crate::defi::data::DefiData>()?;
405        m.add_class::<crate::defi::dex::DexType>()?;
406        m.add_class::<crate::defi::pool_analysis::PoolSnapshot>()?;
407        m.add_class::<crate::defi::pool_analysis::PoolProfiler>()?;
408        m.add_class::<crate::defi::pool_analysis::position::PoolPosition>()?;
409        m.add_class::<crate::defi::pool_analysis::quote::SwapQuote>()?;
410        m.add_class::<crate::defi::pool_analysis::size_estimator::SizeForImpactResult>()?;
411        m.add_class::<crate::defi::pool_analysis::snapshot::PoolAnalytics>()?;
412        m.add_class::<crate::defi::pool_analysis::snapshot::PoolState>()?;
413        m.add_class::<crate::defi::tick_map::tick::PoolTick>()?;
414    }
415    Ok(())
416}
417
418#[cfg(test)]
419mod tests {
420    use std::sync::Once;
421
422    use pyo3::{Python, exceptions::PyValueError};
423    use rstest::rstest;
424
425    use super::*;
426
427    fn ensure_python_initialized() {
428        static INIT: Once = Once::new();
429        INIT.call_once(|| {
430            Python::initialize();
431        });
432    }
433
434    #[rstest]
435    fn test_instrument_id_error_to_pyvalue_err_preserves_display_text() {
436        ensure_python_initialized();
437
438        let error = "BTCUSDT"
439            .parse::<crate::identifiers::InstrumentId>()
440            .unwrap_err();
441
442        Python::attach(|py| {
443            let py_err = instrument_id_error_to_pyvalue_err(error);
444
445            assert!(py_err.is_instance_of::<PyValueError>(py));
446            assert_eq!(
447                py_err.value(py).to_string(),
448                "invalid `InstrumentId` value 'BTCUSDT': missing '.' separator between symbol and venue components"
449            );
450        });
451    }
452
453    #[rstest]
454    fn test_option_series_id_error_to_pyvalue_err_preserves_display_text() {
455        ensure_python_initialized();
456
457        let error = "DERIBIT:BTC:USD"
458            .parse::<crate::identifiers::OptionSeriesId>()
459            .unwrap_err();
460
461        Python::attach(|py| {
462            let py_err = option_series_id_error_to_pyvalue_err(error);
463
464            assert!(py_err.is_instance_of::<PyValueError>(py));
465            assert_eq!(
466                py_err.value(py).to_string(),
467                "invalid `OptionSeriesId` value 'DERIBIT:BTC:USD': expected format 'VENUE:UNDERLYING:[REFERENCE:]SETTLEMENT:EXPIRY'"
468            );
469        });
470    }
471
472    #[rstest]
473    fn test_currency_lookup_error_to_pyvalue_err_preserves_display_text() {
474        ensure_python_initialized();
475
476        let error = "UNKNOWN_CURRENCY"
477            .parse::<crate::types::Currency>()
478            .unwrap_err();
479
480        Python::attach(|py| {
481            let py_err = currency_lookup_error_to_pyvalue_err(error);
482
483            assert!(py_err.is_instance_of::<PyValueError>(py));
484            assert_eq!(
485                py_err.value(py).to_string(),
486                "Unknown currency: UNKNOWN_CURRENCY"
487            );
488        });
489    }
490}