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

nautilus_model/python/
mod.rs
