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::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 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 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 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 m.add_class::<crate::position::Position>()?;
271 m.add_function(wrap_pyfunction!(
272 crate::python::position::py_fold_net_position,
273 m
274 )?)?;
275 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 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 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 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 #[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}