nautilus_model/python/
mod.rs1#![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#[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#[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#[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#[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 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 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 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::ExerciseStyle>()?;
208 m.add_class::<crate::enums::GreeksConvention>()?;
209 m.add_class::<crate::enums::InstrumentClass>()?;
210 m.add_class::<crate::enums::InstrumentCloseType>()?;
211 m.add_class::<crate::enums::LiquiditySide>()?;
212 m.add_class::<crate::enums::MarketStatus>()?;
213 m.add_class::<crate::enums::MarketStatusAction>()?;
214 m.add_class::<crate::enums::OmsType>()?;
215 m.add_class::<crate::enums::OptionKind>()?;
216 m.add_class::<crate::enums::OptionSideFilter>()?;
217 m.add_class::<crate::enums::OtoTriggerMode>()?;
218 m.add_class::<crate::enums::OrderSide>()?;
219 m.add_class::<crate::enums::OrderStatus>()?;
220 m.add_class::<crate::enums::OrderType>()?;
221 m.add_class::<crate::enums::PositionAdjustmentType>()?;
222 m.add_class::<crate::enums::PositionSide>()?;
223 m.add_class::<crate::enums::PriceType>()?;
224 m.add_class::<crate::enums::RecordFlag>()?;
225 m.add_class::<crate::enums::SettlementType>()?;
226 m.add_class::<crate::enums::TimeInForce>()?;
227 m.add_class::<crate::enums::TradingState>()?;
228 m.add_class::<crate::enums::TrailingOffsetType>()?;
229 m.add_class::<crate::enums::TriggerType>()?;
230 m.add_class::<crate::identifiers::AccountId>()?;
232 m.add_class::<crate::identifiers::ActorId>()?;
233 m.add_class::<crate::identifiers::ClientId>()?;
234 m.add_class::<crate::identifiers::ClientOrderId>()?;
235 m.add_class::<crate::identifiers::ComponentId>()?;
236 m.add_class::<crate::identifiers::ExecAlgorithmId>()?;
237 m.add_class::<crate::identifiers::InstrumentId>()?;
238 m.add_class::<crate::identifiers::OrderListId>()?;
239 m.add_class::<crate::identifiers::PositionId>()?;
240 m.add_class::<crate::identifiers::StrategyId>()?;
241 m.add_class::<crate::identifiers::Symbol>()?;
242 m.add_class::<crate::identifiers::TradeId>()?;
243 m.add_class::<crate::identifiers::TraderId>()?;
244 m.add_class::<crate::identifiers::Venue>()?;
245 m.add_class::<crate::identifiers::VenueOrderId>()?;
246 m.add_class::<crate::identifiers::OptionSeriesId>()?;
247 m.add_function(wrap_pyfunction!(
248 crate::python::identifiers::py_new_generic_spread_id,
249 m
250 )?)?;
251 m.add_function(wrap_pyfunction!(
252 crate::python::identifiers::py_generic_spread_id_to_list,
253 m
254 )?)?;
255 m.add_class::<crate::orders::LimitOrder>()?;
257 m.add_class::<crate::orders::LimitIfTouchedOrder>()?;
258 m.add_class::<crate::orders::MarketIfTouchedOrder>()?;
259 m.add_class::<crate::orders::MarketOrder>()?;
260 m.add_class::<crate::orders::MarketToLimitOrder>()?;
261 m.add_class::<crate::orders::OrderList>()?;
262 m.add_class::<crate::orders::StopLimitOrder>()?;
263 m.add_class::<crate::orders::StopMarketOrder>()?;
264 m.add_class::<crate::orders::TrailingStopLimitOrder>()?;
265 m.add_class::<crate::orders::TrailingStopMarketOrder>()?;
266 m.add_class::<crate::reports::fill::FillReport>()?;
268 m.add_class::<crate::reports::order::OrderStatusReport>()?;
269 m.add_class::<crate::reports::position::PositionStatusReport>()?;
270 m.add_class::<crate::reports::mass_status::ExecutionMassStatus>()?;
271 m.add_class::<crate::position::Position>()?;
273 m.add_function(wrap_pyfunction!(
274 crate::python::position::py_fold_net_position,
275 m
276 )?)?;
277 m.add_class::<instruments::tick_scheme::PyFixedTickScheme>()?;
279 m.add_class::<instruments::tick_scheme::PyTieredTickScheme>()?;
280 m.add_function(wrap_pyfunction!(
281 instruments::tick_scheme::py_register_tick_scheme,
282 m
283 )?)?;
284 m.add_function(wrap_pyfunction!(
285 instruments::tick_scheme::py_get_tick_scheme,
286 m
287 )?)?;
288 m.add_function(wrap_pyfunction!(
289 instruments::tick_scheme::py_list_tick_schemes,
290 m
291 )?)?;
292 m.add_class::<crate::instruments::BettingInstrument>()?;
293 m.add_class::<crate::instruments::BinaryOption>()?;
294 m.add_class::<crate::instruments::Cfd>()?;
295 m.add_class::<crate::instruments::Commodity>()?;
296 m.add_class::<crate::instruments::CryptoFuture>()?;
297 m.add_class::<crate::instruments::CryptoFuturesSpread>()?;
298 m.add_class::<crate::instruments::CryptoOption>()?;
299 m.add_class::<crate::instruments::CryptoOptionSpread>()?;
300 m.add_class::<crate::instruments::CryptoPerpetual>()?;
301 m.add_class::<crate::instruments::CurrencyPair>()?;
302 m.add_class::<crate::instruments::Equity>()?;
303 m.add_class::<crate::instruments::FuturesContract>()?;
304 m.add_class::<crate::instruments::FuturesSpread>()?;
305 m.add_class::<crate::instruments::IndexInstrument>()?;
306 m.add_class::<crate::instruments::OptionContract>()?;
307 m.add_class::<crate::instruments::OptionSpread>()?;
308 m.add_class::<crate::instruments::PerpetualContract>()?;
309 m.add_class::<crate::instruments::SyntheticInstrument>()?;
310 m.add_class::<crate::instruments::TokenizedAsset>()?;
311 m.add_class::<crate::orderbook::book::OrderBook>()?;
313 m.add_class::<crate::orderbook::level::BookLevel>()?;
314 m.add_function(wrap_pyfunction!(
315 crate::python::orderbook::book::py_update_book_with_quote_tick,
316 m
317 )?)?;
318 m.add_function(wrap_pyfunction!(
319 crate::python::orderbook::book::py_update_book_with_trade_tick,
320 m
321 )?)?;
322 m.add_class::<crate::orderbook::own::OwnOrderBook>()?;
323 m.add_class::<crate::orderbook::own::OwnBookOrder>()?;
324 m.add_class::<crate::events::AccountState>()?;
326 m.add_class::<crate::events::OrderDenied>()?;
327 m.add_class::<crate::events::OrderFilled>()?;
328 m.add_class::<crate::events::OrderFillVoided>()?;
329 m.add_class::<crate::events::OrderInitialized>()?;
330 m.add_class::<crate::events::OrderRejected>()?;
331 m.add_class::<crate::events::OrderTriggered>()?;
332 m.add_class::<crate::events::OrderSubmitted>()?;
333 m.add_class::<crate::events::OrderEmulated>()?;
334 m.add_class::<crate::events::OrderReleased>()?;
335 m.add_class::<crate::events::OrderUpdated>()?;
336 m.add_class::<crate::events::OrderPendingUpdate>()?;
337 m.add_class::<crate::events::OrderPendingCancel>()?;
338 m.add_class::<crate::events::OrderModifyDenied>()?;
339 m.add_class::<crate::events::OrderModifyRejected>()?;
340 m.add_class::<crate::events::OrderAccepted>()?;
341 m.add_class::<crate::events::OrderCancelDenied>()?;
342 m.add_class::<crate::events::OrderCancelRejected>()?;
343 m.add_class::<crate::events::OrderCanceled>()?;
344 m.add_class::<crate::events::OrderExpired>()?;
345 m.add_class::<crate::events::OrderSnapshot>()?;
346 m.add_class::<crate::events::PositionOpened>()?;
347 m.add_class::<crate::events::PositionChanged>()?;
348 m.add_class::<crate::events::PositionClosed>()?;
349 m.add_class::<crate::events::PositionAdjusted>()?;
350 m.add_class::<crate::events::PositionSnapshot>()?;
351 m.add_class::<crate::events::PortfolioSnapshot>()?;
352 m.add_class::<crate::accounts::BettingAccount>()?;
354 m.add_class::<crate::accounts::CashAccount>()?;
355 m.add_class::<crate::accounts::MarginAccount>()?;
356 m.add_class::<crate::accounts::WalletAccount>()?;
357 m.add_class::<account::margin_model::PyMarginModel>()?;
358 m.add_class::<crate::accounts::margin_model::StandardMarginModel>()?;
359 m.add_class::<crate::accounts::margin_model::LeveragedMarginModel>()?;
360 m.add_function(wrap_pyfunction!(
361 crate::python::account::transformer::betting_account_from_account_events,
362 m
363 )?)?;
364 m.add_function(wrap_pyfunction!(
365 crate::python::account::transformer::cash_account_from_account_events,
366 m
367 )?)?;
368 m.add_function(wrap_pyfunction!(
369 crate::python::account::transformer::margin_account_from_account_events,
370 m
371 )?)?;
372 m.add_function(wrap_pyfunction!(
373 crate::python::account::transformer::wallet_account_from_account_events,
374 m
375 )?)?;
376 m.add_function(wrap_pyfunction!(
377 crate::python::data::bet::py_calc_bets_pnl,
378 m
379 )?)?;
380 m.add_function(wrap_pyfunction!(
381 crate::python::data::bet::py_probability_to_bet,
382 m
383 )?)?;
384 m.add_function(wrap_pyfunction!(
385 crate::python::data::bet::py_inverse_probability_to_bet,
386 m
387 )?)?;
388 #[cfg(feature = "defi")]
390 {
391 m.add_class::<crate::defi::chain::Blockchain>()?;
392 m.add_class::<crate::defi::chain::Chain>()?;
393 m.add_class::<crate::defi::token::Token>()?;
394 m.add_class::<crate::defi::dex::AmmType>()?;
395 m.add_class::<crate::defi::dex::Dex>()?;
396 m.add_class::<crate::defi::amm::Pool>()?;
397 m.add_class::<crate::defi::data::PoolSwap>()?;
398 m.add_class::<crate::defi::data::PoolLiquidityUpdateType>()?;
399 m.add_class::<crate::defi::data::PoolLiquidityUpdate>()?;
400 m.add_class::<crate::defi::data::PoolFeeCollect>()?;
401 m.add_class::<crate::defi::data::PoolFeeProtocolUpdate>()?;
402 m.add_class::<crate::defi::data::PoolFeeProtocolCollect>()?;
403 m.add_class::<crate::defi::data::PoolFlash>()?;
404 m.add_class::<crate::defi::data::Transaction>()?;
405 m.add_class::<crate::defi::data::Block>()?;
406 m.add_class::<crate::defi::data::DefiData>()?;
407 m.add_class::<crate::defi::dex::DexType>()?;
408 m.add_class::<crate::defi::pool_analysis::PoolSnapshot>()?;
409 m.add_class::<crate::defi::pool_analysis::PoolProfiler>()?;
410 m.add_class::<crate::defi::pool_analysis::position::PoolPosition>()?;
411 m.add_class::<crate::defi::pool_analysis::quote::SwapQuote>()?;
412 m.add_class::<crate::defi::pool_analysis::size_estimator::SizeForImpactResult>()?;
413 m.add_class::<crate::defi::pool_analysis::snapshot::PoolAnalytics>()?;
414 m.add_class::<crate::defi::pool_analysis::snapshot::PoolState>()?;
415 m.add_class::<crate::defi::tick_map::tick::PoolTick>()?;
416 }
417 Ok(())
418}
419
420#[cfg(test)]
421mod tests {
422 use std::sync::Once;
423
424 use pyo3::{Python, exceptions::PyValueError};
425 use rstest::rstest;
426
427 use super::*;
428
429 fn ensure_python_initialized() {
430 static INIT: Once = Once::new();
431 INIT.call_once(|| {
432 Python::initialize();
433 });
434 }
435
436 #[rstest]
437 fn test_instrument_id_error_to_pyvalue_err_preserves_display_text() {
438 ensure_python_initialized();
439
440 let error = "BTCUSDT"
441 .parse::<crate::identifiers::InstrumentId>()
442 .unwrap_err();
443
444 Python::attach(|py| {
445 let py_err = instrument_id_error_to_pyvalue_err(error);
446
447 assert!(py_err.is_instance_of::<PyValueError>(py));
448 assert_eq!(
449 py_err.value(py).to_string(),
450 "invalid `InstrumentId` value 'BTCUSDT': missing '.' separator between symbol and venue components"
451 );
452 });
453 }
454
455 #[rstest]
456 fn test_option_series_id_error_to_pyvalue_err_preserves_display_text() {
457 ensure_python_initialized();
458
459 let error = "DERIBIT:BTC:USD"
460 .parse::<crate::identifiers::OptionSeriesId>()
461 .unwrap_err();
462
463 Python::attach(|py| {
464 let py_err = option_series_id_error_to_pyvalue_err(error);
465
466 assert!(py_err.is_instance_of::<PyValueError>(py));
467 assert_eq!(
468 py_err.value(py).to_string(),
469 "invalid `OptionSeriesId` value 'DERIBIT:BTC:USD': expected format 'VENUE:UNDERLYING:[REFERENCE:]SETTLEMENT:EXPIRY'"
470 );
471 });
472 }
473
474 #[rstest]
475 fn test_currency_lookup_error_to_pyvalue_err_preserves_display_text() {
476 ensure_python_initialized();
477
478 let error = "UNKNOWN_CURRENCY"
479 .parse::<crate::types::Currency>()
480 .unwrap_err();
481
482 Python::attach(|py| {
483 let py_err = currency_lookup_error_to_pyvalue_err(error);
484
485 assert!(py_err.is_instance_of::<PyValueError>(py));
486 assert_eq!(
487 py_err.value(py).to_string(),
488 "Unknown currency: UNKNOWN_CURRENCY"
489 );
490 });
491 }
492}