1use std::collections::HashMap;
19
20#[cfg(feature = "examples")]
21use nautilus_common::python::config_error_to_pyvalue_err;
22use nautilus_common::{actor::data_actor::ImportableActorConfig, python::cache::PyCache};
23#[cfg(feature = "examples")]
24use nautilus_core::python::to_pytype_err;
25use nautilus_core::python::{to_pyruntime_err, to_pyvalue_err};
26use nautilus_model::identifiers::{AccountId, ActorId, StrategyId, Venue};
27use nautilus_portfolio::python::PyPortfolio;
28#[cfg(feature = "examples")]
29use nautilus_trading::examples::strategies::{
30 CompositeMarketMaker, CompositeMarketMakerConfig, DeltaNeutralVol, DeltaNeutralVolConfig,
31 EmaCross, EmaCrossConfig, GridMarketMaker, GridMarketMakerConfig, HurstVpinDirectional,
32 HurstVpinDirectionalConfig,
33};
34use nautilus_trading::{ImportableExecutionAlgorithmConfig, ImportableStrategyConfig};
35use pyo3::{prelude::*, types::PyDict};
36
37use super::engine::{
38 PyBacktestEngine, engine_cache, engine_portfolio, generate_account_report,
39 generate_fills_report, generate_order_fills_report, generate_orders_report,
40 generate_positions_report,
41};
42use crate::{
43 config::BacktestRunConfig, engine::BacktestEngine, node::BacktestNode, result::BacktestResult,
44};
45
46#[pyo3_stub_gen::derive::gen_stub_pymethods]
47#[pymethods]
48impl BacktestNode {
49 #[new]
54 fn py_new(configs: Vec<BacktestRunConfig>) -> PyResult<Self> {
55 Self::new(configs).map_err(to_pyruntime_err)
56 }
57
58 #[getter]
60 #[pyo3(name = "configs")]
61 fn py_configs(&self) -> Vec<BacktestRunConfig> {
62 self.configs().to_vec()
63 }
64
65 #[pyo3(name = "build")]
80 fn py_build(&mut self) -> PyResult<()> {
81 self.build().map_err(to_pyruntime_err)
82 }
83
84 #[pyo3(name = "run")]
103 fn py_run(&mut self) -> PyResult<Vec<BacktestResult>> {
104 self.run().map_err(to_pyruntime_err)
105 }
106
107 #[pyo3(name = "dispose")]
111 fn py_dispose(&mut self) {
112 self.dispose();
113 }
114
115 #[pyo3(name = "get_engine_cache")]
121 fn py_get_engine_cache(&self, run_config_id: &str) -> PyResult<PyCache> {
122 Ok(engine_cache(self.require_engine(run_config_id)?))
123 }
124
125 #[pyo3(name = "get_engine_portfolio")]
131 fn py_get_engine_portfolio(&self, run_config_id: &str) -> PyResult<PyPortfolio> {
132 Ok(engine_portfolio(self.require_engine(run_config_id)?))
133 }
134
135 #[pyo3(name = "generate_orders_report")]
141 fn py_generate_orders_report<'py>(
142 &self,
143 py: Python<'py>,
144 run_config_id: &str,
145 ) -> PyResult<Bound<'py, PyAny>> {
146 generate_orders_report(self.require_engine(run_config_id)?, py)
147 }
148
149 #[pyo3(name = "generate_order_fills_report")]
155 fn py_generate_order_fills_report<'py>(
156 &self,
157 py: Python<'py>,
158 run_config_id: &str,
159 ) -> PyResult<Bound<'py, PyAny>> {
160 generate_order_fills_report(self.require_engine(run_config_id)?, py)
161 }
162
163 #[pyo3(name = "generate_fills_report")]
169 fn py_generate_fills_report<'py>(
170 &self,
171 py: Python<'py>,
172 run_config_id: &str,
173 ) -> PyResult<Bound<'py, PyAny>> {
174 generate_fills_report(self.require_engine(run_config_id)?, py)
175 }
176
177 #[pyo3(name = "generate_positions_report")]
183 fn py_generate_positions_report<'py>(
184 &self,
185 py: Python<'py>,
186 run_config_id: &str,
187 ) -> PyResult<Bound<'py, PyAny>> {
188 generate_positions_report(self.require_engine(run_config_id)?, py)
189 }
190
191 #[pyo3(
200 name = "generate_account_report",
201 signature = (run_config_id, venue=None, account_id=None)
202 )]
203 fn py_generate_account_report<'py>(
204 &self,
205 py: Python<'py>,
206 run_config_id: &str,
207 venue: Option<Venue>,
208 account_id: Option<AccountId>,
209 ) -> PyResult<Bound<'py, PyAny>> {
210 generate_account_report(self.require_engine(run_config_id)?, py, venue, account_id)
211 }
212
213 #[pyo3(name = "add_actor")]
215 fn py_add_actor(&mut self, run_config_id: &str, actor: &Bound<'_, PyAny>) -> PyResult<()> {
216 let engine = self.require_engine_mut(run_config_id)?;
217 PyBacktestEngine::add_python_actor(engine, &actor.clone().unbind())
218 }
219
220 #[pyo3(name = "add_actor_from_config")]
222 #[expect(clippy::needless_pass_by_value)]
223 fn py_add_actor_from_config(
224 &mut self,
225 _py: Python,
226 run_config_id: &str,
227 config: ImportableActorConfig,
228 ) -> PyResult<()> {
229 log::debug!("`add_actor_from_config` with: {config:?}");
230 let engine = self.require_engine_mut(run_config_id)?;
231 let actor = create_importable_component(
232 &config.actor_path,
233 "actor_path",
234 &config.config_path,
235 &config.config,
236 "actor",
237 )?;
238 PyBacktestEngine::add_python_actor(engine, &actor)
239 }
240
241 #[pyo3(name = "add_strategy")]
243 fn py_add_strategy(
244 &mut self,
245 run_config_id: &str,
246 strategy: &Bound<'_, PyAny>,
247 ) -> PyResult<()> {
248 let engine = self.require_engine_mut(run_config_id)?;
249 PyBacktestEngine::add_python_strategy(engine, &strategy.clone().unbind())
250 }
251
252 #[pyo3(name = "add_strategy_from_config")]
254 #[expect(clippy::needless_pass_by_value)]
255 fn py_add_strategy_from_config(
256 &mut self,
257 _py: Python,
258 run_config_id: &str,
259 config: ImportableStrategyConfig,
260 ) -> PyResult<()> {
261 log::debug!("`add_strategy_from_config` with: {config:?}");
262 let engine = self.require_engine_mut(run_config_id)?;
263 let strategy = create_importable_component(
264 &config.strategy_path,
265 "strategy_path",
266 &config.config_path,
267 &config.config,
268 "strategy",
269 )?;
270 PyBacktestEngine::add_python_strategy(engine, &strategy)
271 }
272
273 #[pyo3(name = "add_exec_algorithm")]
275 fn py_add_exec_algorithm(
276 &mut self,
277 run_config_id: &str,
278 exec_algorithm: &Bound<'_, PyAny>,
279 ) -> PyResult<()> {
280 let engine = self.require_engine_mut(run_config_id)?;
281 PyBacktestEngine::add_python_exec_algorithm(engine, &exec_algorithm.clone().unbind())
282 }
283
284 #[pyo3(name = "add_exec_algorithm_from_config")]
286 #[expect(clippy::needless_pass_by_value)]
287 fn py_add_exec_algorithm_from_config(
288 &mut self,
289 _py: Python,
290 run_config_id: &str,
291 config: ImportableExecutionAlgorithmConfig,
292 ) -> PyResult<()> {
293 log::debug!("`add_exec_algorithm_from_config` with: {config:?}");
294 let engine = self.require_engine_mut(run_config_id)?;
295 PyBacktestEngine::ensure_can_add_exec_algorithm(engine)?;
296 let exec_algorithm = create_importable_component(
297 &config.exec_algorithm_path,
298 "exec_algorithm_path",
299 &config.config_path,
300 &config.config,
301 "exec algorithm",
302 )?;
303 PyBacktestEngine::add_python_exec_algorithm(engine, &exec_algorithm)
304 }
305
306 #[pyo3(name = "add_builtin_strategy")]
312 #[cfg_attr(
313 not(feature = "examples"),
314 expect(
315 clippy::unused_self,
316 reason = "PyO3 method keeps the instance API when examples are disabled"
317 )
318 )]
319 fn py_add_builtin_strategy(
320 &mut self,
321 run_config_id: &str,
322 type_name: &str,
323 config: &Bound<'_, PyAny>,
324 ) -> PyResult<()> {
325 #[cfg(feature = "examples")]
326 {
327 let engine = self.require_engine_mut(run_config_id)?;
328
329 let register = builtin_strategy_register(type_name).ok_or_else(|| {
330 to_pytype_err(format!("Unsupported built-in strategy type: {type_name}"))
331 })?;
332 register(engine, config)
333 }
334
335 #[cfg(not(feature = "examples"))]
336 {
337 let _ = (run_config_id, type_name, config);
338 Err(to_pyruntime_err(
339 "add_builtin_strategy requires the `examples` feature",
340 ))
341 }
342 }
343
344 fn __repr__(&self) -> String {
345 format!("{self:?}")
346 }
347}
348
349impl BacktestNode {
350 fn require_engine(&self, run_config_id: &str) -> PyResult<&BacktestEngine> {
351 self.get_engine(run_config_id)
352 .ok_or_else(|| self.missing_engine_err(run_config_id))
353 }
354
355 fn require_engine_mut(&mut self, run_config_id: &str) -> PyResult<&mut BacktestEngine> {
356 if self.get_engine(run_config_id).is_none() {
357 return Err(self.missing_engine_err(run_config_id));
358 }
359
360 Ok(self.get_engine_mut(run_config_id).expect("checked above"))
361 }
362
363 fn missing_engine_err(&self, run_config_id: &str) -> PyErr {
364 let known = self
365 .configs()
366 .iter()
367 .any(|config| config.id() == run_config_id);
368 let reason = if known {
369 "call build() before accessing the engine; if build() already ran, \
370 it may have failed (check the log) or the engine was disposed"
371 .to_string()
372 } else {
373 let ids: Vec<&str> = self.configs().iter().map(BacktestRunConfig::id).collect();
374 format!("unknown run config ID (known IDs: {ids:?})")
375 };
376 to_pyruntime_err(format!(
377 "No engine for run config '{run_config_id}': {reason}"
378 ))
379 }
380}
381
382#[cfg(feature = "examples")]
383type BuiltinStrategyRegister = for<'py> fn(&mut BacktestEngine, &Bound<'py, PyAny>) -> PyResult<()>;
384
385#[cfg(feature = "examples")]
386fn builtin_strategy_register(type_name: &str) -> Option<BuiltinStrategyRegister> {
387 match type_name {
388 "CompositeMarketMaker" => Some(register_composite_market_maker),
389 "DeltaNeutralVol" => Some(register_delta_neutral_vol),
390 "EmaCross" => Some(register_ema_cross),
391 "GridMarketMaker" => Some(register_grid_market_maker),
392 "HurstVpinDirectional" => Some(register_hurst_vpin_directional),
393 "OrderBookImbalance" => Some(super::engine::register_orderbook_imbalance),
394 _ => None,
395 }
396}
397
398#[cfg(feature = "examples")]
399fn register_composite_market_maker(
400 engine: &mut BacktestEngine,
401 config: &Bound<'_, PyAny>,
402) -> PyResult<()> {
403 let config = config.extract::<CompositeMarketMakerConfig>()?;
404 engine
405 .add_strategy(CompositeMarketMaker::new(config))
406 .map_err(to_pyruntime_err)
407}
408
409#[cfg(feature = "examples")]
410fn register_delta_neutral_vol(
411 engine: &mut BacktestEngine,
412 config: &Bound<'_, PyAny>,
413) -> PyResult<()> {
414 let config = config.extract::<DeltaNeutralVolConfig>()?;
415 engine
416 .add_strategy(DeltaNeutralVol::new(config))
417 .map_err(to_pyruntime_err)
418}
419
420#[cfg(feature = "examples")]
421fn register_ema_cross(engine: &mut BacktestEngine, config: &Bound<'_, PyAny>) -> PyResult<()> {
422 let config = config.extract::<EmaCrossConfig>()?;
423 engine
424 .add_strategy(EmaCross::from_config(config))
425 .map_err(to_pyruntime_err)
426}
427
428#[cfg(feature = "examples")]
429fn register_grid_market_maker(
430 engine: &mut BacktestEngine,
431 config: &Bound<'_, PyAny>,
432) -> PyResult<()> {
433 let config = config.extract::<GridMarketMakerConfig>()?;
434 engine
435 .add_strategy(GridMarketMaker::new(config))
436 .map_err(to_pyruntime_err)
437}
438
439#[cfg(feature = "examples")]
440fn register_hurst_vpin_directional(
441 engine: &mut BacktestEngine,
442 config: &Bound<'_, PyAny>,
443) -> PyResult<()> {
444 let config = config.extract::<HurstVpinDirectionalConfig>()?;
445 let strategy =
446 HurstVpinDirectional::new_checked(config).map_err(config_error_to_pyvalue_err)?;
447 engine.add_strategy(strategy).map_err(to_pyruntime_err)
448}
449
450#[cfg(all(test, feature = "examples"))]
451mod tests {
452 use pyo3::{Python, types::PyDict};
453 use rstest::rstest;
454
455 use crate::{config::BacktestEngineConfig, engine::BacktestEngine};
456
457 #[rstest]
458 #[case("CompositeMarketMaker")]
459 #[case("DeltaNeutralVol")]
460 #[case("EmaCross")]
461 #[case("GridMarketMaker")]
462 #[case("HurstVpinDirectional")]
463 #[case("OrderBookImbalance")]
464 fn test_builtin_strategy_register_accepts_supported_names(#[case] type_name: &str) {
465 assert!(super::builtin_strategy_register(type_name).is_some());
466 }
467
468 #[rstest]
469 fn test_builtin_strategy_register_rejects_unknown_name() {
470 assert!(super::builtin_strategy_register("UnknownStrategy").is_none());
471 }
472
473 #[rstest]
474 fn test_builtin_strategy_register_rejects_mismatched_config() {
475 Python::initialize();
476
477 let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
478 Python::attach(|py| {
479 let register = super::builtin_strategy_register("EmaCross").unwrap();
480 let config = PyDict::new(py);
481 let error = register(&mut engine, config.as_any()).unwrap_err();
482
483 assert!(error.is_instance_of::<pyo3::exceptions::PyTypeError>(py));
484 });
485 }
486}
487
488pub(crate) fn create_importable_component(
489 component_path: &str,
490 path_field: &str,
491 config_path: &str,
492 config: &HashMap<String, serde_json::Value>,
493 component_name: &str,
494) -> PyResult<Py<PyAny>> {
495 let Some((module_name, class_name)) = component_path.split_once(':') else {
496 return Err(to_pyvalue_err(format!(
497 "{path_field} must be in format 'module.path:ClassName'",
498 )));
499 };
500
501 if module_name.is_empty() || class_name.is_empty() || class_name.contains(':') {
502 return Err(to_pyvalue_err(format!(
503 "{path_field} must be in format 'module.path:ClassName'",
504 )));
505 }
506
507 log::info!("Importing {component_name} from module: {module_name} class: {class_name}");
508
509 Python::attach(|py| -> anyhow::Result<Py<PyAny>> {
510 let module = py
511 .import(module_name)
512 .map_err(|e| anyhow::anyhow!("Failed to import module {module_name}: {e}"))?;
513 let class = module
514 .getattr(class_name)
515 .map_err(|e| anyhow::anyhow!("Failed to get class {class_name}: {e}"))?;
516 let config_instance = create_config_instance(py, config_path, config)?;
517 let component = if let Some(config_obj) = config_instance {
518 class.call1((config_obj,))?
519 } else {
520 class.call0()?
521 };
522 Ok(component.unbind())
523 })
524 .map_err(to_pyruntime_err)
525}
526
527pub(crate) fn create_config_instance<'py>(
528 py: Python<'py>,
529 config_path: &str,
530 config: &HashMap<String, serde_json::Value>,
531) -> anyhow::Result<Option<Bound<'py, PyAny>>> {
532 if config_path.is_empty() && config.is_empty() {
533 log::debug!("No config_path or empty config, using None");
534 return Ok(None);
535 }
536
537 let config_parts: Vec<&str> = config_path.split(':').collect();
538 if config_parts.len() != 2 {
539 anyhow::bail!("config_path must be in format 'module.path:ClassName', was {config_path}");
540 }
541 let (config_module_name, config_class_name) = (config_parts[0], config_parts[1]);
542
543 log::debug!(
544 "Importing config class from module: {config_module_name} class: {config_class_name}"
545 );
546
547 let config_module = py
548 .import(config_module_name)
549 .map_err(|e| anyhow::anyhow!("Failed to import config module {config_module_name}: {e}"))?;
550 let config_class = config_module
551 .getattr(config_class_name)
552 .map_err(|e| anyhow::anyhow!("Failed to get config class {config_class_name}: {e}"))?;
553
554 let py_dict = PyDict::new(py);
556
557 for (key, value) in config {
558 let py_value = config_value_to_py(py, key, value)?;
559 py_dict.set_item(key, py_value)?;
560 }
561
562 log::debug!("Created config dict: {py_dict:?}");
563
564 let config_instance = match config_class.call((), Some(&py_dict)) {
566 Ok(instance) => {
567 log::debug!("Created config instance with kwargs");
568 instance
569 }
570 Err(kwargs_err) => {
571 log::debug!("Failed to create config with kwargs: {kwargs_err}");
572
573 match config_class.call0() {
574 Ok(instance) => {
575 log::debug!("Created default config instance, setting attributes");
576 for (key, value) in config {
577 let py_value = config_value_to_py(py, key, value)?;
578
579 if let Err(setattr_err) = instance.setattr(key, py_value) {
580 anyhow::bail!("Failed to set attribute {key}: {setattr_err}");
581 }
582 }
583
584 if instance.hasattr("__post_init__")? {
587 instance.call_method0("__post_init__")?;
588 }
589
590 instance
591 }
592 Err(default_err) => {
593 anyhow::bail!(
594 "Failed to create config instance. \
595 Tried kwargs: {kwargs_err}, default: {default_err}"
596 );
597 }
598 }
599 }
600 };
601
602 log::debug!("Created config instance: {config_instance:?}");
603
604 Ok(Some(config_instance))
605}
606
607fn config_value_to_py<'py>(
608 py: Python<'py>,
609 key: &str,
610 value: &serde_json::Value,
611) -> anyhow::Result<Bound<'py, PyAny>> {
612 if key == "actor_id"
613 && let Some(actor_id) = value.as_str()
614 {
615 return Ok(ActorId::new_checked(actor_id)?
616 .into_pyobject(py)?
617 .into_any());
618 }
619
620 if key == "strategy_id"
621 && let Some(strategy_id) = value.as_str()
622 {
623 return Ok(StrategyId::new_checked(strategy_id)?
624 .into_pyobject(py)?
625 .into_any());
626 }
627
628 let json_str = serde_json::to_string(value)
629 .map_err(|e| anyhow::anyhow!("Failed to serialize config value: {e}"))?;
630 Ok(PyModule::import(py, "json")?
631 .call_method("loads", (json_str,), None)?
632 .into_any())
633}