nautilus_common/python/

cache.rs

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! Python bindings for the [`Cache`] component.

use std::{cell::RefCell, rc::Rc, sync::LazyLock};

use bytes::Bytes;
use nautilus_core::python::to_pyvalue_err;
#[cfg(feature = "defi")]
use nautilus_model::defi::{Pool, PoolProfiler};
use nautilus_model::{
    data::{
        Bar, BarType, FundingRateUpdate, InstrumentClose, InstrumentStatus, QuoteTick, TradeTick,
        YieldCurve,
        prices::{IndexPriceUpdate, MarkPriceUpdate},
    },
    enums::{AggregationSource, OmsType, OrderSide, PositionSide, PriceType},
    identifiers::{
        AccountId, ClientId, ClientOrderId, ExecAlgorithmId, InstrumentId, OrderListId, PositionId,
        StrategyId, Venue, VenueOrderId,
    },
    instruments::SyntheticInstrument,
    orderbook::{OrderBook, own::OwnOrderBook},
    orders::OrderList,
    position::Position,
    python::{
        account::account_any_to_pyobject,
        instruments::{instrument_any_to_pyobject, pyobject_to_instrument_any},
        orders::{order_any_to_pyobject, pyobject_to_order_any},
    },
    types::{Currency, Money, Price, Quantity},
};
use pyo3::prelude::*;
use rust_decimal::prelude::ToPrimitive;

use crate::{
    cache::{Cache, CacheConfig, database::CacheDatabaseFactory},
    enums::SerializationEncoding,
    python::{config_error_to_pyvalue_err, factory::FactoryRegistry},
};

/// Registry for Python cache database factory extractors.
pub type CacheDatabaseFactoryRegistry = FactoryRegistry<dyn CacheDatabaseFactory>;

static GLOBAL_CACHE_DATABASE_FACTORY_REGISTRY: LazyLock<CacheDatabaseFactoryRegistry> =
    LazyLock::new(|| CacheDatabaseFactoryRegistry::new("cache database factory"));

/// Returns the global Python cache database factory registry.
#[must_use]
pub fn get_global_cache_database_factory_registry() -> &'static CacheDatabaseFactoryRegistry {
    &GLOBAL_CACHE_DATABASE_FACTORY_REGISTRY
}

/// Wrapper providing shared access to [`Cache`] from Python.
///
/// This wrapper holds an `Rc<RefCell<Cache>>` allowing actors to share
/// the same cache instance. All methods delegate to the underlying cache.
#[allow(non_camel_case_types)]
#[pyo3::pyclass(
    module = "nautilus_trader.common",
    name = "Cache",
    unsendable,
    from_py_object
)]
#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.common")]
#[derive(Debug, Clone)]
pub struct PyCache(Rc<RefCell<Cache>>);

impl PyCache {
    /// Creates a `PyCache` from an `Rc<RefCell<Cache>>`.
    #[must_use]
    pub fn from_rc(rc: Rc<RefCell<Cache>>) -> Self {
        Self(rc)
    }

    /// Gets the inner `Rc<RefCell<Cache>>` for use in Rust code.
    #[must_use]
    pub fn cache_rc(&self) -> Rc<RefCell<Cache>> {
        self.0.clone()
    }
}

#[pymethods]
#[pyo3_stub_gen::derive::gen_stub_pymethods]
impl PyCache {
    #[new]
    #[pyo3(signature = (config=None))]
    fn py_new(config: Option<CacheConfig>) -> PyResult<Self> {
        let cache = Cache::try_new(config, None).map_err(config_error_to_pyvalue_err)?;
        Ok(Self(Rc::new(RefCell::new(cache))))
    }

    #[pyo3(name = "reset")]
    fn py_reset(&mut self) {
        self.0.borrow_mut().reset();
    }

    #[pyo3(name = "dispose")]
    fn py_dispose(&mut self) {
        self.0.borrow_mut().dispose();
    }

    #[pyo3(name = "purge_closed_orders", signature = (ts_now, buffer_secs=0))]
    fn py_purge_closed_orders(&mut self, ts_now: u64, buffer_secs: u64) {
        self.0
            .borrow_mut()
            .purge_closed_orders(ts_now.into(), buffer_secs);
    }

    #[pyo3(name = "purge_closed_positions", signature = (ts_now, buffer_secs=0))]
    fn py_purge_closed_positions(&mut self, ts_now: u64, buffer_secs: u64) {
        self.0
            .borrow_mut()
            .purge_closed_positions(ts_now.into(), buffer_secs);
    }

    #[pyo3(name = "purge_order")]
    fn py_purge_order(&mut self, client_order_id: ClientOrderId) {
        self.0.borrow_mut().purge_order(client_order_id);
    }

    #[pyo3(name = "purge_position")]
    fn py_purge_position(&mut self, position_id: PositionId) {
        self.0.borrow_mut().purge_position(position_id);
    }

    #[pyo3(name = "purge_instrument")]
    fn py_purge_instrument(&mut self, instrument_id: InstrumentId) {
        self.0.borrow_mut().purge_instrument(instrument_id);
    }

    #[pyo3(name = "purge_account_events", signature = (ts_now, lookback_secs=0))]
    fn py_purge_account_events(&mut self, ts_now: u64, lookback_secs: u64) {
        self.0
            .borrow_mut()
            .purge_account_events(ts_now.into(), lookback_secs);
    }

    #[pyo3(name = "get")]
    fn py_get(&self, key: &str) -> PyResult<Option<Vec<u8>>> {
        match self.0.borrow().get(key).map_err(to_pyvalue_err)? {
            Some(bytes) => Ok(Some(bytes.to_vec())),
            None => Ok(None),
        }
    }

    #[pyo3(name = "add")]
    fn py_add_general(&mut self, key: &str, value: Vec<u8>) -> PyResult<()> {
        self.0
            .borrow_mut()
            .add(key, Bytes::from(value))
            .map_err(to_pyvalue_err)
    }

    /// Adds an instrument close, replacing any close cached for the same instrument.
    #[pyo3(name = "add_instrument_close")]
    fn py_add_instrument_close(&mut self, close: InstrumentClose) -> PyResult<()> {
        self.0
            .borrow_mut()
            .add_instrument_close(close)
            .map_err(to_pyvalue_err)
    }

    #[pyo3(name = "add_yield_curve")]
    fn py_add_yield_curve(&mut self, yield_curve: YieldCurve) -> PyResult<()> {
        self.0
            .borrow_mut()
            .add_yield_curve(yield_curve)
            .map_err(to_pyvalue_err)
    }

    /// Returns the quote at `index` for the `instrument_id`.
    ///
    /// Index 0 is the most recently added quote; index 1 is the previous insertion.
    /// Entries are not sorted by timestamp. Returns `None` when no quote exists at the index.
    #[pyo3(name = "quote", signature = (instrument_id, index=0))]
    fn py_quote(&self, instrument_id: InstrumentId, index: usize) -> Option<QuoteTick> {
        self.0
            .borrow()
            .quote_at_index(&instrument_id, index)
            .copied()
    }

    /// Returns the trade at `index` for the `instrument_id`.
    ///
    /// Index 0 is the most recently added trade; index 1 is the previous insertion.
    /// Entries are not sorted by timestamp. Returns `None` when no trade exists at the index.
    #[pyo3(name = "trade", signature = (instrument_id, index=0))]
    fn py_trade(&self, instrument_id: InstrumentId, index: usize) -> Option<TradeTick> {
        self.0
            .borrow()
            .trade_at_index(&instrument_id, index)
            .copied()
    }

    /// Returns the bar at `index` for the `bar_type`.
    ///
    /// Bars are ordered by `ts_event`, newest first. Index 0 is the most recent bar;
    /// index 1 is the previous bar. Returns `None` when no bar exists at the index.
    #[pyo3(name = "bar", signature = (bar_type, index=0))]
    fn py_bar(&self, bar_type: BarType, index: usize) -> Option<Bar> {
        self.0.borrow().bar_at_index(&bar_type, index).copied()
    }

    /// Returns cached quotes for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added quote. Entries are not sorted by timestamp.
    /// Returns `None` when no quotes are cached for the instrument.
    #[pyo3(name = "quotes")]
    fn py_quotes(&self, instrument_id: InstrumentId) -> Option<Vec<QuoteTick>> {
        self.0.borrow().quotes(&instrument_id)
    }

    /// Returns cached trades for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added trade. Entries are not sorted by timestamp.
    /// Returns `None` when no trades are cached for the instrument.
    #[pyo3(name = "trades")]
    fn py_trades(&self, instrument_id: InstrumentId) -> Option<Vec<TradeTick>> {
        self.0.borrow().trades(&instrument_id)
    }

    /// Returns cached bars for the `bar_type` in reverse chronological order by `ts_event`.
    ///
    /// Index 0 is the most recent bar. Returns `None` when no bars are cached for the bar type.
    #[pyo3(name = "bars")]
    fn py_bars(&self, bar_type: BarType) -> Option<Vec<Bar>> {
        self.0.borrow().bars(&bar_type)
    }

    #[pyo3(name = "bar_types", signature = (aggregation_source, instrument_id=None, price_type=None))]
    fn py_bar_types(
        &self,
        aggregation_source: AggregationSource,
        instrument_id: Option<InstrumentId>,
        price_type: Option<PriceType>,
    ) -> Vec<BarType> {
        self.0
            .borrow()
            .bar_types(
                instrument_id.as_ref(),
                price_type.as_ref(),
                aggregation_source,
            )
            .into_iter()
            .copied()
            .collect()
    }

    /// Returns the most recently added mark price update for the `instrument_id`, or `None` if absent.
    #[pyo3(name = "mark_price")]
    fn py_mark_price(&self, instrument_id: InstrumentId) -> Option<MarkPriceUpdate> {
        self.0.borrow().mark_price(&instrument_id).copied()
    }

    /// Returns cached mark price updates for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
    /// Returns `None` when no mark price updates are cached for the instrument.
    #[pyo3(name = "mark_prices")]
    fn py_mark_prices(&self, instrument_id: InstrumentId) -> Option<Vec<MarkPriceUpdate>> {
        self.0.borrow().mark_prices(&instrument_id)
    }

    /// Returns the most recently added index price update for the `instrument_id`, or `None` if absent.
    #[pyo3(name = "index_price")]
    fn py_index_price(&self, instrument_id: InstrumentId) -> Option<IndexPriceUpdate> {
        self.0.borrow().index_price(&instrument_id).copied()
    }

    /// Returns cached index price updates for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
    /// Returns `None` when no index price updates are cached for the instrument.
    #[pyo3(name = "index_prices")]
    fn py_index_prices(&self, instrument_id: InstrumentId) -> Option<Vec<IndexPriceUpdate>> {
        self.0.borrow().index_prices(&instrument_id)
    }

    /// Returns the most recently added funding rate update for the `instrument_id`, or `None` if absent.
    #[pyo3(name = "funding_rate")]
    fn py_funding_rate(&self, instrument_id: InstrumentId) -> Option<FundingRateUpdate> {
        self.0.borrow().funding_rate(&instrument_id).copied()
    }

    /// Returns cached funding rate updates for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
    /// Returns `None` when no funding rate updates are cached for the instrument.
    #[pyo3(name = "funding_rates")]
    fn py_funding_rates(&self, instrument_id: InstrumentId) -> Option<Vec<FundingRateUpdate>> {
        self.0.borrow().funding_rates(&instrument_id)
    }

    /// Returns the most recently added instrument status for the `instrument_id`, or `None` if absent.
    #[pyo3(name = "instrument_status")]
    fn py_instrument_status(&self, instrument_id: InstrumentId) -> Option<InstrumentStatus> {
        self.0.borrow().instrument_status(&instrument_id).copied()
    }

    /// Returns cached instrument status updates for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
    /// Returns `None` when no instrument status updates are cached for the instrument.
    #[pyo3(name = "instrument_statuses")]
    fn py_instrument_statuses(&self, instrument_id: InstrumentId) -> Option<Vec<InstrumentStatus>> {
        self.0.borrow().instrument_statuses(&instrument_id)
    }

    /// Returns the close cached for `instrument_id`, if present.
    ///
    /// A later insertion replaces the cached close for the instrument; no history is kept.
    #[pyo3(name = "instrument_close")]
    fn py_instrument_close(&self, instrument_id: InstrumentId) -> Option<InstrumentClose> {
        self.0.borrow().instrument_close(&instrument_id).copied()
    }

    #[pyo3(name = "price")]
    fn py_price(&self, instrument_id: InstrumentId, price_type: PriceType) -> Option<Price> {
        self.0.borrow().price(&instrument_id, price_type)
    }

    /// Returns the current order book for the `instrument_id`, or `None` if absent.
    ///
    /// The cache holds the current book state, not a history of book updates.
    #[pyo3(name = "order_book")]
    fn py_order_book(&self, instrument_id: InstrumentId) -> Option<OrderBook> {
        self.0.borrow().order_book(&instrument_id).cloned()
    }

    /// Returns the best bid/ask price and size for the `instrument_id`, without cloning the
    /// resident order book.
    ///
    /// Returns `(bid_price, bid_size, ask_price, ask_size)`, or `None` if the book is
    /// missing, empty, or one-sided.
    ///
    /// For L3 books, each size is the first order's size at the best level, not the
    /// aggregate level size, consistent with the order book's best-size getters.
    ///
    /// Prefer this over `order_book()` in hot paths that only need top-of-book values, since
    /// `order_book()` clones the full book and its cost scales with depth.
    #[pyo3(name = "top_of_book")]
    fn py_top_of_book(
        &self,
        instrument_id: InstrumentId,
    ) -> Option<(Price, Quantity, Price, Quantity)> {
        let cache = self.0.borrow();
        let book = cache.order_book(&instrument_id)?;
        Some((
            book.best_bid_price()?,
            book.best_bid_size()?,
            book.best_ask_price()?,
            book.best_ask_size()?,
        ))
    }

    #[pyo3(name = "has_order_book")]
    fn py_has_order_book(&self, instrument_id: InstrumentId) -> bool {
        self.0.borrow().has_order_book(&instrument_id)
    }

    #[pyo3(name = "book_update_count")]
    fn py_book_update_count(&self, instrument_id: InstrumentId) -> usize {
        self.0.borrow().book_update_count(&instrument_id)
    }

    #[pyo3(name = "has_quote_ticks")]
    fn py_has_quote_ticks(&self, instrument_id: InstrumentId) -> bool {
        self.0.borrow().has_quote_ticks(&instrument_id)
    }

    #[pyo3(name = "has_trade_ticks")]
    fn py_has_trade_ticks(&self, instrument_id: InstrumentId) -> bool {
        self.0.borrow().has_trade_ticks(&instrument_id)
    }

    #[pyo3(name = "has_mark_prices")]
    fn py_has_mark_prices(&self, instrument_id: InstrumentId) -> bool {
        self.0.borrow().has_mark_prices(&instrument_id)
    }

    #[pyo3(name = "has_index_prices")]
    fn py_has_index_prices(&self, instrument_id: InstrumentId) -> bool {
        self.0.borrow().has_index_prices(&instrument_id)
    }

    #[pyo3(name = "has_funding_rates")]
    fn py_has_funding_rates(&self, instrument_id: InstrumentId) -> bool {
        self.0.borrow().has_funding_rates(&instrument_id)
    }

    #[pyo3(name = "has_instrument_statuses")]
    fn py_has_instrument_statuses(&self, instrument_id: InstrumentId) -> bool {
        self.0.borrow().has_instrument_statuses(&instrument_id)
    }

    #[pyo3(name = "has_instrument_close")]
    fn py_has_instrument_close(&self, instrument_id: InstrumentId) -> bool {
        self.0.borrow().has_instrument_close(&instrument_id)
    }

    #[pyo3(name = "has_bars")]
    fn py_has_bars(&self, bar_type: BarType) -> bool {
        self.0.borrow().has_bars(&bar_type)
    }

    #[pyo3(name = "quote_count")]
    fn py_quote_count(&self, instrument_id: InstrumentId) -> usize {
        self.0.borrow().quote_count(&instrument_id)
    }

    #[pyo3(name = "trade_count")]
    fn py_trade_count(&self, instrument_id: InstrumentId) -> usize {
        self.0.borrow().trade_count(&instrument_id)
    }

    #[pyo3(name = "mark_price_count")]
    fn py_mark_price_count(&self, instrument_id: InstrumentId) -> usize {
        self.0.borrow().mark_price_count(&instrument_id)
    }

    #[pyo3(name = "index_price_count")]
    fn py_index_price_count(&self, instrument_id: InstrumentId) -> usize {
        self.0.borrow().index_price_count(&instrument_id)
    }

    #[pyo3(name = "funding_rate_count")]
    fn py_funding_rate_count(&self, instrument_id: InstrumentId) -> usize {
        self.0.borrow().funding_rate_count(&instrument_id)
    }

    #[pyo3(name = "instrument_status_count")]
    fn py_instrument_status_count(&self, instrument_id: InstrumentId) -> usize {
        self.0.borrow().instrument_status_count(&instrument_id)
    }

    #[pyo3(name = "bar_count")]
    fn py_bar_count(&self, bar_type: BarType) -> usize {
        self.0.borrow().bar_count(&bar_type)
    }

    #[pyo3(name = "get_xrate")]
    fn py_get_xrate(
        &self,
        venue: Venue,
        from_currency: Currency,
        to_currency: Currency,
        price_type: PriceType,
    ) -> Option<f64> {
        self.0
            .borrow()
            .get_xrate(venue, from_currency, to_currency, price_type)
            .and_then(|rate| rate.to_f64())
    }

    #[pyo3(name = "get_mark_xrate")]
    fn py_get_mark_xrate(&self, from_currency: Currency, to_currency: Currency) -> Option<f64> {
        self.0.borrow().get_mark_xrate(from_currency, to_currency)
    }

    #[pyo3(name = "own_order_book")]
    fn py_own_order_book(&self, instrument_id: InstrumentId) -> Option<OwnOrderBook> {
        self.0.borrow().own_order_book(&instrument_id).cloned()
    }

    #[pyo3(name = "instrument")]
    fn py_instrument(
        &self,
        py: Python,
        instrument_id: InstrumentId,
    ) -> PyResult<Option<Py<PyAny>>> {
        let cache = self.0.borrow();
        match cache.instrument(&instrument_id) {
            Some(instrument) => Ok(Some(instrument_any_to_pyobject(py, instrument.clone())?)),
            None => Ok(None),
        }
    }

    #[pyo3(name = "instrument_ids", signature = (venue=None))]
    fn py_instrument_ids(&self, venue: Option<Venue>) -> Vec<InstrumentId> {
        self.0
            .borrow()
            .instrument_ids(venue.as_ref())
            .into_iter()
            .copied()
            .collect()
    }

    #[pyo3(name = "instruments", signature = (venue=None))]
    fn py_instruments(&self, py: Python, venue: Option<Venue>) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        let mut py_instruments = Vec::new();

        match venue {
            Some(venue) => {
                for instrument in cache.instruments(&venue, None) {
                    py_instruments.push(instrument_any_to_pyobject(py, (*instrument).clone())?);
                }
            }
            None => {
                for instrument_id in cache.instrument_ids(None) {
                    if let Some(instrument) = cache.instrument(instrument_id) {
                        py_instruments.push(instrument_any_to_pyobject(py, instrument.clone())?);
                    }
                }
            }
        }
        Ok(py_instruments)
    }

    #[pyo3(name = "synthetic")]
    fn py_synthetic(&self, instrument_id: InstrumentId) -> Option<SyntheticInstrument> {
        self.0.borrow().synthetic(&instrument_id).cloned()
    }

    #[pyo3(name = "synthetic_ids")]
    fn py_synthetic_ids(&self) -> Vec<InstrumentId> {
        self.0
            .borrow()
            .synthetic_ids()
            .into_iter()
            .copied()
            .collect()
    }

    #[pyo3(name = "account")]
    fn py_account(&self, py: Python, account_id: AccountId) -> PyResult<Option<Py<PyAny>>> {
        let cache = self.0.borrow();
        match cache.account(&account_id) {
            Some(account) => Ok(Some(account_any_to_pyobject(py, account.clone())?)),
            None => Ok(None),
        }
    }

    #[pyo3(name = "account_for_venue")]
    fn py_account_for_venue(&self, py: Python, venue: Venue) -> PyResult<Option<Py<PyAny>>> {
        let cache = self.0.borrow();
        match cache.account_for_venue(&venue) {
            Some(account) => Ok(Some(account_any_to_pyobject(py, account.clone())?)),
            None => Ok(None),
        }
    }

    #[pyo3(name = "account_id")]
    fn py_account_id(&self, venue: Venue) -> Option<AccountId> {
        self.0.borrow().account_id(&venue).copied()
    }

    #[pyo3(name = "client_order_ids", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None))]
    fn py_client_order_ids(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<ClientOrderId> {
        self.0
            .borrow()
            .client_order_ids(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
            )
            .into_iter()
            .collect()
    }

    #[pyo3(name = "client_order_ids_open", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None))]
    fn py_client_order_ids_open(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<ClientOrderId> {
        self.0
            .borrow()
            .client_order_ids_open(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
            )
            .into_iter()
            .collect()
    }

    #[pyo3(name = "client_order_ids_closed", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None))]
    fn py_client_order_ids_closed(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<ClientOrderId> {
        self.0
            .borrow()
            .client_order_ids_closed(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
            )
            .into_iter()
            .collect()
    }

    #[pyo3(name = "client_order_ids_emulated", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None))]
    fn py_client_order_ids_emulated(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<ClientOrderId> {
        self.0
            .borrow()
            .client_order_ids_emulated(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
            )
            .into_iter()
            .collect()
    }

    #[pyo3(name = "client_order_ids_inflight", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None))]
    fn py_client_order_ids_inflight(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<ClientOrderId> {
        self.0
            .borrow()
            .client_order_ids_inflight(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
            )
            .into_iter()
            .collect()
    }

    #[pyo3(name = "position_ids", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None))]
    fn py_position_ids(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<PositionId> {
        self.0
            .borrow()
            .position_ids(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
            )
            .into_iter()
            .collect()
    }

    #[pyo3(name = "position_open_ids", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None))]
    fn py_position_open_ids(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<PositionId> {
        self.0
            .borrow()
            .position_open_ids(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
            )
            .into_iter()
            .collect()
    }

    #[pyo3(name = "position_closed_ids", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None))]
    fn py_position_closed_ids(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<PositionId> {
        self.0
            .borrow()
            .position_closed_ids(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
            )
            .into_iter()
            .collect()
    }

    #[pyo3(name = "strategy_ids")]
    fn py_strategy_ids(&self) -> Vec<StrategyId> {
        self.0.borrow().strategy_ids().into_iter().collect()
    }

    #[pyo3(name = "exec_algorithm_ids")]
    fn py_exec_algorithm_ids(&self) -> Vec<ExecAlgorithmId> {
        self.0.borrow().exec_algorithm_ids().into_iter().collect()
    }

    #[pyo3(name = "order")]
    fn py_order(&self, py: Python, client_order_id: ClientOrderId) -> PyResult<Option<Py<PyAny>>> {
        let cache = self.0.borrow();
        match cache.order(&client_order_id) {
            Some(order) => Ok(Some(order_any_to_pyobject(py, order.clone())?)),
            None => Ok(None),
        }
    }

    #[pyo3(name = "client_order_id")]
    fn py_client_order_id(&self, venue_order_id: VenueOrderId) -> Option<ClientOrderId> {
        self.0.borrow().client_order_id(&venue_order_id).copied()
    }

    #[pyo3(name = "venue_order_id")]
    fn py_venue_order_id(&self, client_order_id: ClientOrderId) -> Option<VenueOrderId> {
        self.0.borrow().venue_order_id(&client_order_id).copied()
    }

    #[pyo3(name = "client_id")]
    fn py_client_id(&self, client_order_id: ClientOrderId) -> Option<ClientId> {
        self.0.borrow().client_id(&client_order_id).copied()
    }

    #[pyo3(name = "orders", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_orders(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .orders(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
                side,
            )
            .into_iter()
            .map(|o| order_any_to_pyobject(py, o.clone()))
            .collect()
    }

    #[pyo3(name = "orders_open", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_orders_open(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .orders_open(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
                side,
            )
            .into_iter()
            .map(|o| order_any_to_pyobject(py, o.clone()))
            .collect()
    }

    #[pyo3(name = "orders_closed", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_orders_closed(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .orders_closed(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
                side,
            )
            .into_iter()
            .map(|o| order_any_to_pyobject(py, o.clone()))
            .collect()
    }

    #[pyo3(name = "orders_emulated", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_orders_emulated(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .orders_emulated(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
                side,
            )
            .into_iter()
            .map(|o| order_any_to_pyobject(py, o.clone()))
            .collect()
    }

    #[pyo3(name = "orders_inflight", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_orders_inflight(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .orders_inflight(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
                side,
            )
            .into_iter()
            .map(|o| order_any_to_pyobject(py, o.clone()))
            .collect()
    }

    #[pyo3(name = "orders_for_position")]
    fn py_orders_for_position(
        &self,
        py: Python,
        position_id: PositionId,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .orders_for_position(&position_id)
            .into_iter()
            .map(|o| order_any_to_pyobject(py, o.clone()))
            .collect()
    }

    #[pyo3(name = "order_exists")]
    fn py_order_exists(&self, client_order_id: ClientOrderId) -> bool {
        self.0.borrow().order_exists(&client_order_id)
    }

    #[pyo3(name = "is_order_open")]
    fn py_is_order_open(&self, client_order_id: ClientOrderId) -> bool {
        self.0.borrow().is_order_open(&client_order_id)
    }

    #[pyo3(name = "is_order_closed")]
    fn py_is_order_closed(&self, client_order_id: ClientOrderId) -> bool {
        self.0.borrow().is_order_closed(&client_order_id)
    }

    #[pyo3(name = "is_order_emulated")]
    fn py_is_order_emulated(&self, client_order_id: ClientOrderId) -> bool {
        self.0.borrow().is_order_emulated(&client_order_id)
    }

    #[pyo3(name = "is_order_inflight")]
    fn py_is_order_inflight(&self, client_order_id: ClientOrderId) -> bool {
        self.0.borrow().is_order_inflight(&client_order_id)
    }

    #[pyo3(name = "is_order_pending_cancel_local")]
    fn py_is_order_pending_cancel_local(&self, client_order_id: ClientOrderId) -> bool {
        self.0
            .borrow()
            .is_order_pending_cancel_local(&client_order_id)
    }

    #[pyo3(name = "orders_open_count", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_orders_open_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.0.borrow().orders_open_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    #[pyo3(name = "orders_closed_count", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_orders_closed_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.0.borrow().orders_closed_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    #[pyo3(name = "orders_emulated_count", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_orders_emulated_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.0.borrow().orders_emulated_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    #[pyo3(name = "orders_inflight_count", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_orders_inflight_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.0.borrow().orders_inflight_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    #[pyo3(name = "orders_total_count", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_orders_total_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.0.borrow().orders_total_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    #[pyo3(name = "order_list")]
    fn py_order_list(&self, order_list_id: OrderListId) -> Option<OrderList> {
        self.0.borrow().order_list(&order_list_id).cloned()
    }

    #[pyo3(name = "order_lists", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None))]
    fn py_order_lists(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<OrderList> {
        let cache = self.0.borrow();
        cache
            .order_lists(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
            )
            .into_iter()
            .cloned()
            .collect()
    }

    #[pyo3(name = "order_list_exists")]
    fn py_order_list_exists(&self, order_list_id: OrderListId) -> bool {
        self.0.borrow().order_list_exists(&order_list_id)
    }

    #[pyo3(name = "orders_for_exec_algorithm", signature = (exec_algorithm_id, venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    #[expect(clippy::too_many_arguments)]
    fn py_orders_for_exec_algorithm(
        &self,
        py: Python,
        exec_algorithm_id: ExecAlgorithmId,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .orders_for_exec_algorithm(
                &exec_algorithm_id,
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
                side,
            )
            .into_iter()
            .map(|o| order_any_to_pyobject(py, o.clone()))
            .collect()
    }

    #[pyo3(name = "orders_for_exec_spawn")]
    fn py_orders_for_exec_spawn(
        &self,
        py: Python,
        exec_spawn_id: ClientOrderId,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .orders_for_exec_spawn(&exec_spawn_id)
            .into_iter()
            .map(|o| order_any_to_pyobject(py, o.clone()))
            .collect()
    }

    #[pyo3(name = "exec_spawn_total_quantity")]
    fn py_exec_spawn_total_quantity(
        &self,
        exec_spawn_id: ClientOrderId,
        active_only: bool,
    ) -> Option<Quantity> {
        self.0
            .borrow()
            .exec_spawn_total_quantity(&exec_spawn_id, active_only)
    }

    #[pyo3(name = "exec_spawn_total_filled_qty")]
    fn py_exec_spawn_total_filled_qty(
        &self,
        exec_spawn_id: ClientOrderId,
        active_only: bool,
    ) -> Option<Quantity> {
        self.0
            .borrow()
            .exec_spawn_total_filled_qty(&exec_spawn_id, active_only)
    }

    #[pyo3(name = "exec_spawn_total_leaves_qty")]
    fn py_exec_spawn_total_leaves_qty(
        &self,
        exec_spawn_id: ClientOrderId,
        active_only: bool,
    ) -> Option<Quantity> {
        self.0
            .borrow()
            .exec_spawn_total_leaves_qty(&exec_spawn_id, active_only)
    }

    #[pyo3(name = "position")]
    fn py_position(&self, py: Python, position_id: PositionId) -> PyResult<Option<Py<PyAny>>> {
        let cache = self.0.borrow();
        match cache.position(&position_id) {
            Some(position) => Ok(Some(position.clone().into_pyobject(py)?.into())),
            None => Ok(None),
        }
    }

    #[pyo3(name = "position_for_order")]
    fn py_position_for_order(
        &self,
        py: Python,
        client_order_id: ClientOrderId,
    ) -> PyResult<Option<Py<PyAny>>> {
        let cache = self.0.borrow();
        match cache.position_for_order(&client_order_id) {
            Some(position) => Ok(Some(position.clone().into_pyobject(py)?.into())),
            None => Ok(None),
        }
    }

    #[pyo3(name = "position_id")]
    fn py_position_id(&self, client_order_id: ClientOrderId) -> Option<PositionId> {
        self.0.borrow().position_id(&client_order_id).copied()
    }

    #[pyo3(name = "positions", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_positions(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .positions(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
                side,
            )
            .into_iter()
            .map(|p| Ok(p.clone().into_pyobject(py)?.into()))
            .collect()
    }

    #[pyo3(name = "positions_open", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_positions_open(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .positions_open(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
                side,
            )
            .into_iter()
            .map(|p| Ok(p.clone().into_pyobject(py)?.into()))
            .collect()
    }

    #[pyo3(name = "positions_closed", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_positions_closed(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .positions_closed(
                venue.as_ref(),
                instrument_id.as_ref(),
                strategy_id.as_ref(),
                account_id.as_ref(),
                side,
            )
            .into_iter()
            .map(|p| Ok(p.clone().into_pyobject(py)?.into()))
            .collect()
    }

    #[pyo3(name = "position_exists")]
    fn py_position_exists(&self, position_id: PositionId) -> bool {
        self.0.borrow().position_exists(&position_id)
    }

    #[pyo3(name = "is_position_open")]
    fn py_is_position_open(&self, position_id: PositionId) -> bool {
        self.0.borrow().is_position_open(&position_id)
    }

    #[pyo3(name = "is_position_closed")]
    fn py_is_position_closed(&self, position_id: PositionId) -> bool {
        self.0.borrow().is_position_closed(&position_id)
    }

    #[pyo3(name = "positions_open_count", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_positions_open_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> usize {
        self.0.borrow().positions_open_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    #[pyo3(name = "positions_closed_count", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_positions_closed_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> usize {
        self.0.borrow().positions_closed_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    #[pyo3(name = "positions_total_count", signature = (venue=None, instrument_id=None, strategy_id=None, account_id=None, side=None))]
    fn py_positions_total_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> usize {
        self.0.borrow().positions_total_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    #[pyo3(name = "strategy_id_for_order")]
    fn py_strategy_id_for_order(&self, client_order_id: ClientOrderId) -> Option<StrategyId> {
        self.0
            .borrow()
            .strategy_id_for_order(&client_order_id)
            .copied()
    }

    #[pyo3(name = "strategy_id_for_position")]
    fn py_strategy_id_for_position(&self, position_id: PositionId) -> Option<StrategyId> {
        self.0
            .borrow()
            .strategy_id_for_position(&position_id)
            .copied()
    }

    #[pyo3(name = "position_snapshot_bytes")]
    fn py_position_snapshot_bytes(&self, position_id: PositionId) -> Option<Vec<Vec<u8>>> {
        self.0.borrow().position_snapshot_bytes(&position_id)
    }

    #[pyo3(name = "snapshot_position")]
    #[expect(clippy::needless_pass_by_value)]
    fn py_snapshot_position(&self, py: Python, position: Py<PyAny>) -> PyResult<()> {
        let position_obj = position.extract::<Position>(py)?;
        self.0
            .borrow_mut()
            .snapshot_position(&position_obj)
            .map_err(to_pyvalue_err)
    }

    #[pyo3(name = "position_snapshots", signature = (position_id=None, account_id=None))]
    fn py_position_snapshots(
        &self,
        py: Python,
        position_id: Option<PositionId>,
        account_id: Option<AccountId>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        let cache = self.0.borrow();
        cache
            .position_snapshots(position_id.as_ref(), account_id.as_ref())
            .into_iter()
            .map(|p| Ok(p.into_pyobject(py)?.into()))
            .collect()
    }
}

#[cfg(test)]
mod tests {
    use nautilus_core::UnixNanos;
    use nautilus_model::{
        data::{BookOrder, stubs::stub_instrument_close},
        enums::{BookType, InstrumentCloseType},
    };
    use pyo3::exceptions::PyValueError;
    use rstest::rstest;

    use super::*;

    fn book_order(side: OrderSide, price: &str, size: &str, id: u64) -> BookOrder {
        BookOrder::new(side, Price::from(price), Quantity::from(size), id)
    }

    #[rstest]
    fn test_top_of_book_missing() {
        let cache = PyCache::from_rc(Rc::new(RefCell::new(Cache::default())));

        assert_eq!(
            cache.py_top_of_book(InstrumentId::from("AUD/USD.SIM")),
            None
        );
    }

    #[rstest]
    #[case::empty(None)]
    #[case::bid_only(Some(OrderSide::Buy))]
    #[case::ask_only(Some(OrderSide::Sell))]
    fn test_top_of_book_incomplete(#[case] side: Option<OrderSide>) {
        let instrument_id = InstrumentId::from("AUD/USD.SIM");
        let mut book = OrderBook::new(instrument_id, BookType::L2_MBP);
        if let Some(side) = side {
            book.add(book_order(side, "0.70000", "10", 1), 0, 1, 1.into());
        }
        let mut cache = Cache::default();
        cache.add_order_book(book).unwrap();
        let cache = PyCache::from_rc(Rc::new(RefCell::new(cache)));

        assert_eq!(cache.py_top_of_book(instrument_id), None);
    }

    #[rstest]
    fn test_top_of_book_python_values_and_resident_updates() {
        let instrument_id = InstrumentId::from("AUD/USD.SIM");
        let mut book = OrderBook::new(instrument_id, BookType::L2_MBP);
        book.add(
            book_order(OrderSide::Buy, "0.70000", "10", 1),
            0,
            1,
            1.into(),
        );
        book.add(
            book_order(OrderSide::Sell, "0.70010", "20", 2),
            0,
            2,
            2.into(),
        );
        let mut cache = Cache::default();
        cache.add_order_book(book).unwrap();
        let cache = Rc::new(RefCell::new(cache));

        Python::initialize();
        Python::attach(|py| {
            let py_cache = Py::new(py, PyCache::from_rc(cache.clone())).unwrap();
            let original = py_cache
                .call_method1(py, "top_of_book", (instrument_id,))
                .unwrap();
            let expected = (
                Price::from("0.70000"),
                Quantity::from("10"),
                Price::from("0.70010"),
                Quantity::from("20"),
            );
            assert_eq!(
                original
                    .extract::<(Price, Quantity, Price, Quantity)>(py)
                    .unwrap(),
                expected
            );

            {
                let mut cache = cache.borrow_mut();
                let book = cache.order_book_mut(&instrument_id).unwrap();
                book.update(
                    book_order(OrderSide::Buy, "0.70000", "15", 1),
                    0,
                    3,
                    3.into(),
                );
                book.add(
                    book_order(OrderSide::Sell, "0.70005", "25", 3),
                    0,
                    4,
                    4.into(),
                );
            }
            let updated = py_cache
                .call_method1(py, "top_of_book", (instrument_id,))
                .unwrap()
                .extract::<(Price, Quantity, Price, Quantity)>(py)
                .unwrap();
            assert_eq!(
                updated,
                (
                    Price::from("0.70000"),
                    Quantity::from("15"),
                    Price::from("0.70005"),
                    Quantity::from("25"),
                )
            );
            assert_eq!(
                original
                    .extract::<(Price, Quantity, Price, Quantity)>(py)
                    .unwrap(),
                expected
            );

            cache
                .borrow_mut()
                .order_book_mut(&instrument_id)
                .unwrap()
                .clear_asks(5, 5.into());
            assert!(
                py_cache
                    .call_method1(py, "top_of_book", (instrument_id,))
                    .unwrap()
                    .is_none(py)
            );
        });
    }

    #[rstest]
    fn test_top_of_book_l3_returns_first_order_sizes() {
        let instrument_id = InstrumentId::from("AUD/USD.SIM");
        let mut book = OrderBook::new(instrument_id, BookType::L3_MBO);
        let first_bid = book_order(OrderSide::Buy, "0.70000", "10", 1);
        let first_ask = book_order(OrderSide::Sell, "0.70010", "20", 3);
        book.add(first_bid, 0, 1, 1.into());
        book.add(
            book_order(OrderSide::Buy, "0.70000", "30", 2),
            0,
            2,
            2.into(),
        );
        book.add(first_ask, 0, 3, 3.into());
        book.add(
            book_order(OrderSide::Sell, "0.70010", "40", 4),
            0,
            4,
            4.into(),
        );
        let mut cache = Cache::default();
        cache.add_order_book(book).unwrap();
        let cache = PyCache::from_rc(Rc::new(RefCell::new(cache)));

        assert_eq!(
            cache.py_top_of_book(instrument_id),
            Some((
                Price::from("0.70000"),
                Quantity::from("10"),
                Price::from("0.70010"),
                Quantity::from("20"),
            ))
        );

        {
            let mut inner = cache.0.borrow_mut();
            let book = inner.order_book_mut(&instrument_id).unwrap();
            book.delete(first_bid, 0, 5, 5.into());
            book.delete(first_ask, 0, 6, 6.into());
        }
        assert_eq!(
            cache.py_top_of_book(instrument_id),
            Some((
                Price::from("0.70000"),
                Quantity::from("30"),
                Price::from("0.70010"),
                Quantity::from("40"),
            ))
        );
    }

    fn create_order_list() -> OrderList {
        OrderList::new(
            OrderListId::from("OL-001"),
            InstrumentId::from("AUD/USD.SIM"),
            StrategyId::from("S-001"),
            vec![ClientOrderId::from("O-001")],
            UnixNanos::from(42_u64),
        )
    }

    #[rstest]
    fn test_order_list_queries_preserve_concrete_type() {
        let order_list = create_order_list();
        let order_list_id = order_list.id;
        let cache = Rc::new(RefCell::new(Cache::default()));
        cache
            .borrow_mut()
            .add_order_list(order_list.clone())
            .unwrap();
        let py_cache = PyCache::from_rc(cache);

        assert_eq!(
            py_cache.py_order_list(order_list_id),
            Some(order_list.clone()),
        );
        assert_eq!(
            py_cache.py_order_lists(None, None, None, None),
            vec![order_list],
        );
    }

    #[rstest]
    fn test_add_instrument_close_replaces_existing() {
        let first = stub_instrument_close();
        let replacement = InstrumentClose::new(
            first.instrument_id,
            Price::from("0.00000"),
            InstrumentCloseType::EndOfSession,
            UnixNanos::from(3_u64),
            UnixNanos::from(4_u64),
        );
        let mut py_cache = PyCache::from_rc(Rc::new(RefCell::new(Cache::default())));

        py_cache.py_add_instrument_close(first).unwrap();
        py_cache.py_add_instrument_close(replacement).unwrap();

        assert_eq!(
            py_cache.py_instrument_close(first.instrument_id),
            Some(replacement)
        );
    }

    #[rstest]
    fn test_py_cache_constructor_returns_value_error_for_invalid_config() {
        Python::initialize();
        let config = CacheConfig {
            tick_capacity: 0,
            ..Default::default()
        };

        let err = PyCache::py_new(Some(config)).expect_err("invalid capacity must be rejected");

        Python::attach(|py| assert!(err.is_instance_of::<PyValueError>(py)));
    }

    #[rstest]
    fn test_native_cache_binding_returns_value_error_for_invalid_config() {
        Python::initialize();
        let config = CacheConfig {
            bar_capacity: 0,
            ..Default::default()
        };

        let err = Cache::py_new(Some(config)).expect_err("invalid capacity must be rejected");

        Python::attach(|py| assert!(err.is_instance_of::<PyValueError>(py)));
    }
}

#[cfg(feature = "defi")]
#[pymethods]
#[pyo3_stub_gen::derive::gen_stub_pymethods]
impl PyCache {
    #[pyo3(name = "pool")]
    fn py_pool(&self, instrument_id: InstrumentId) -> Option<Pool> {
        self.0
            .try_borrow()
            .ok()
            .and_then(|cache| cache.pool(&instrument_id).cloned())
    }

    #[pyo3(name = "pool_profiler")]
    fn py_pool_profiler(&self, instrument_id: InstrumentId) -> Option<PoolProfiler> {
        self.0
            .try_borrow()
            .ok()
            .and_then(|cache| cache.pool_profiler(&instrument_id).cloned())
    }
}

#[pymethods]
#[pyo3_stub_gen::derive::gen_stub_pymethods]
impl CacheConfig {
    /// Configuration for `Cache` instances.
    #[new]
    #[expect(clippy::too_many_arguments)]
    #[pyo3(signature = (
        encoding=None,
        timestamps_as_iso8601=None,
        buffer_interval_ms=None,
        bulk_read_batch_size=None,
        use_trader_prefix=None,
        use_instance_id=None,
        flush_on_start=None,
        drop_instruments_on_reset=None,
        tick_capacity=None,
        bar_capacity=None,
        save_market_data=None,
        persist_account_events=None,
    ))]
    fn py_new(
        encoding: Option<SerializationEncoding>,
        timestamps_as_iso8601: Option<bool>,
        buffer_interval_ms: Option<usize>,
        bulk_read_batch_size: Option<usize>,
        use_trader_prefix: Option<bool>,
        use_instance_id: Option<bool>,
        flush_on_start: Option<bool>,
        drop_instruments_on_reset: Option<bool>,
        tick_capacity: Option<usize>,
        bar_capacity: Option<usize>,
        save_market_data: Option<bool>,
        persist_account_events: Option<bool>,
    ) -> PyResult<Self> {
        let config = Self {
            encoding: encoding.unwrap_or_default(),
            timestamps_as_iso8601: timestamps_as_iso8601.unwrap_or(false),
            buffer_interval_ms,
            bulk_read_batch_size,
            use_trader_prefix: use_trader_prefix.unwrap_or(true),
            use_instance_id: use_instance_id.unwrap_or(false),
            flush_on_start: flush_on_start.unwrap_or(false),
            drop_instruments_on_reset: drop_instruments_on_reset.unwrap_or(true),
            tick_capacity: tick_capacity.unwrap_or(10_000),
            bar_capacity: bar_capacity.unwrap_or(10_000),
            persist_account_events: persist_account_events.unwrap_or(true),
            save_market_data: save_market_data.unwrap_or(false),
        };
        config.validate().map_err(config_error_to_pyvalue_err)?;
        Ok(config)
    }

    fn __str__(&self) -> String {
        format!("{self:?}")
    }

    fn __repr__(&self) -> String {
        format!("{self:?}")
    }

    #[getter]
    fn encoding(&self) -> SerializationEncoding {
        self.encoding
    }

    #[getter]
    fn timestamps_as_iso8601(&self) -> bool {
        self.timestamps_as_iso8601
    }

    #[getter]
    fn buffer_interval_ms(&self) -> Option<usize> {
        self.buffer_interval_ms
    }

    #[getter]
    fn bulk_read_batch_size(&self) -> Option<usize> {
        self.bulk_read_batch_size
    }

    #[getter]
    fn use_trader_prefix(&self) -> bool {
        self.use_trader_prefix
    }

    #[getter]
    fn use_instance_id(&self) -> bool {
        self.use_instance_id
    }

    #[getter]
    fn flush_on_start(&self) -> bool {
        self.flush_on_start
    }

    #[getter]
    fn drop_instruments_on_reset(&self) -> bool {
        self.drop_instruments_on_reset
    }

    #[getter]
    fn tick_capacity(&self) -> usize {
        self.tick_capacity
    }

    #[getter]
    fn bar_capacity(&self) -> usize {
        self.bar_capacity
    }

    #[getter]
    fn persist_account_events(&self) -> bool {
        self.persist_account_events
    }

    #[getter]
    fn save_market_data(&self) -> bool {
        self.save_market_data
    }
}

#[pymethods]
impl Cache {
    /// A common in-memory `Cache` for market and execution related data.
    #[new]
    fn py_new(config: Option<CacheConfig>) -> PyResult<Self> {
        Self::try_new(config, None).map_err(config_error_to_pyvalue_err)
    }

    fn __repr__(&self) -> String {
        format!("{self:?}")
    }

    /// Resets the cache.
    ///
    /// All stateful fields are reset to their initial value. Instruments,
    /// currencies, and synthetics are retained when `drop_instruments_on_reset`
    /// is `false` so that repeated backtest runs can reuse the same dataset. External order claims
    /// and execution client account, route, and external client registrations are retained so
    /// registered strategy and client routing remain configured across resets.
    #[pyo3(name = "reset")]
    fn py_reset(&mut self) {
        self.reset();
    }

    /// Dispose of the cache which will close any underlying database adapter.
    ///
    /// If closing the database connection fails, an error is logged.
    #[pyo3(name = "dispose")]
    fn py_dispose(&mut self) {
        self.dispose();
    }

    /// Purges all closed orders from the cache that are older than `buffer_secs`.
    ///
    ///
    /// Only orders that have been closed for at least this amount of time will be purged.
    /// A value of 0 means purge all closed orders regardless of when they were closed.
    #[pyo3(name = "purge_closed_orders", signature = (ts_now, buffer_secs=0))]
    fn py_purge_closed_orders(&mut self, ts_now: u64, buffer_secs: u64) {
        self.purge_closed_orders(ts_now.into(), buffer_secs);
    }

    /// Purges all closed positions from the cache that are older than `buffer_secs`.
    #[pyo3(name = "purge_closed_positions", signature = (ts_now, buffer_secs=0))]
    fn py_purge_closed_positions(&mut self, ts_now: u64, buffer_secs: u64) {
        self.purge_closed_positions(ts_now.into(), buffer_secs);
    }

    /// Purges the order with the `client_order_id` from the cache (if found).
    ///
    /// For safety, an order is prevented from being purged if it's open.
    #[pyo3(name = "purge_order")]
    fn py_purge_order(&mut self, client_order_id: ClientOrderId) {
        self.purge_order(client_order_id);
    }

    /// Purges the position with the `position_id` from the cache (if found).
    ///
    /// For safety, a position is prevented from being purged if it's open.
    #[pyo3(name = "purge_position")]
    fn py_purge_position(&mut self, position_id: PositionId) {
        self.purge_position(position_id);
    }

    /// Purges the instrument with the `instrument_id` from the cache.
    ///
    /// This refuses to purge when associated orders or positions remain in
    /// non-terminal state.
    #[pyo3(name = "purge_instrument")]
    fn py_purge_instrument(&mut self, instrument_id: InstrumentId) {
        self.purge_instrument(instrument_id);
    }

    /// Purges all account state events which are outside the lookback window.
    ///
    /// Only events which are outside the lookback window will be purged.
    /// A value of 0 means purge all account state events.
    #[pyo3(name = "purge_account_events", signature = (ts_now, lookback_secs=0))]
    fn py_purge_account_events(&mut self, ts_now: u64, lookback_secs: u64) {
        self.purge_account_events(ts_now.into(), lookback_secs);
    }

    /// Adds the `currency` to the cache.
    ///
    /// # Errors
    ///
    /// Returns an error if persisting the currency to the backing database fails.
    #[pyo3(name = "add_currency")]
    fn py_add_currency(&mut self, currency: Currency) -> PyResult<()> {
        self.add_currency(currency).map_err(to_pyvalue_err)
    }

    /// Adds the `instrument` to the cache.
    ///
    /// # Errors
    ///
    /// Returns an error if persisting the instrument to the backing database fails.
    #[pyo3(name = "add_instrument")]
    fn py_add_instrument(&mut self, py: Python, instrument: Py<PyAny>) -> PyResult<()> {
        let instrument_any = pyobject_to_instrument_any(py, instrument)?;
        self.add_instrument(instrument_any).map_err(to_pyvalue_err)
    }

    /// Returns a reference to the instrument for the `instrument_id` (if found).
    #[pyo3(name = "instrument")]
    fn py_instrument(
        &self,
        py: Python,
        instrument_id: InstrumentId,
    ) -> PyResult<Option<Py<PyAny>>> {
        match self.instrument(&instrument_id) {
            Some(instrument) => Ok(Some(instrument_any_to_pyobject(py, instrument.clone())?)),
            None => Ok(None),
        }
    }

    /// Returns references to all instrument IDs for the `venue`.
    #[pyo3(name = "instrument_ids")]
    fn py_instrument_ids(&self, venue: Option<Venue>) -> Vec<InstrumentId> {
        self.instrument_ids(venue.as_ref())
            .into_iter()
            .copied()
            .collect()
    }

    /// Returns references to all instruments for the `venue`.
    #[pyo3(name = "instruments")]
    fn py_instruments(&self, py: Python, venue: Option<Venue>) -> PyResult<Vec<Py<PyAny>>> {
        let mut py_instruments = Vec::new();

        if let Some(venue) = venue {
            let instruments = self.instruments(&venue, None);
            for instrument in instruments {
                py_instruments.push(instrument_any_to_pyobject(py, (*instrument).clone())?);
            }
        } else {
            let instrument_ids = self.instrument_ids(None);
            for instrument_id in instrument_ids {
                if let Some(instrument) = self.instrument(instrument_id) {
                    py_instruments.push(instrument_any_to_pyobject(py, instrument.clone())?);
                }
            }
        }

        Ok(py_instruments)
    }

    /// Adds the `order` to the cache indexed with any given identifiers.
    ///
    /// # Parameters
    ///
    /// `override_existing`: If the added order should 'override' any existing order and replace
    /// it in the cache. This is currently used for emulated orders which are
    /// being released and transformed into another type.
    ///
    /// # Errors
    ///
    /// Returns an error if not `replace_existing` and the `order.client_order_id` is already contained in the cache,
    /// or if persisting the order to the backing database fails. The order and every index are
    /// committed to memory before persistence is attempted, so a persistence error leaves the
    /// cache internally consistent.
    #[pyo3(name = "add_order")]
    fn py_add_order(
        &mut self,
        py: Python,
        order: Py<PyAny>,
        position_id: Option<PositionId>,
        client_id: Option<ClientId>,
        replace_existing: Option<bool>,
    ) -> PyResult<()> {
        let order_any = pyobject_to_order_any(py, order)?;
        self.add_order(
            order_any,
            position_id,
            client_id,
            replace_existing.unwrap_or(false),
        )
        .map_err(to_pyvalue_err)
    }

    /// Gets a borrow of the order with the `client_order_id` (if found).
    ///
    /// Prefer `Self.order_ref` in new native code.
    #[pyo3(name = "order")]
    fn py_order(&self, py: Python, client_order_id: ClientOrderId) -> PyResult<Option<Py<PyAny>>> {
        match self.order(&client_order_id) {
            Some(order) => Ok(Some(order_any_to_pyobject(py, order.clone())?)),
            None => Ok(None),
        }
    }

    /// Returns whether an order with the `client_order_id` exists.
    #[pyo3(name = "order_exists")]
    fn py_order_exists(&self, client_order_id: ClientOrderId) -> bool {
        self.order_exists(&client_order_id)
    }

    /// Returns whether an order with the `client_order_id` is open.
    #[pyo3(name = "is_order_open")]
    fn py_is_order_open(&self, client_order_id: ClientOrderId) -> bool {
        self.is_order_open(&client_order_id)
    }

    /// Returns whether an order with the `client_order_id` is closed.
    #[pyo3(name = "is_order_closed")]
    fn py_is_order_closed(&self, client_order_id: ClientOrderId) -> bool {
        self.is_order_closed(&client_order_id)
    }

    /// Returns whether an order with the `client_order_id` is locally active.
    ///
    /// Locally active orders are in the `INITIALIZED`, `EMULATED`, or `RELEASED` state
    /// (a superset of emulated orders).
    #[pyo3(name = "is_order_active_local")]
    fn py_is_order_active_local(&self, client_order_id: ClientOrderId) -> bool {
        self.is_order_active_local(&client_order_id)
    }

    /// Returns borrows of all locally active orders matching the optional filter parameters.
    ///
    /// Prefer `Self.orders_active_local_refs` in new native code.
    #[pyo3(name = "orders_active_local")]
    fn py_orders_active_local(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.orders_active_local(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
        .into_iter()
        .map(|order| order_any_to_pyobject(py, order.clone()))
        .collect()
    }

    /// Returns the count of all locally active orders.
    ///
    /// Locally active orders are in the `INITIALIZED`, `EMULATED`, or `RELEASED` state
    /// (a superset of emulated orders).
    #[pyo3(name = "orders_active_local_count")]
    fn py_orders_active_local_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.orders_active_local_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    /// Returns the count of all open orders.
    #[pyo3(name = "orders_open_count")]
    fn py_orders_open_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.orders_open_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    /// Returns the count of all closed orders.
    #[pyo3(name = "orders_closed_count")]
    fn py_orders_closed_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.orders_closed_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    /// Returns the count of all orders.
    #[pyo3(name = "orders_total_count")]
    fn py_orders_total_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.orders_total_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    /// Adds the `position` to the cache.
    ///
    /// For `OmsType.Unspecified`, IDs matching `{instrument_id}-{strategy_id}` resolve to
    /// `OmsType.Netting`. Other IDs retain the supplied OMS type.
    ///
    /// # Errors
    ///
    /// Returns an error if persisting the position to the backing database fails. After
    /// serialization succeeds, the complete operation is committed to memory before persistence
    /// is attempted, so a persistence error leaves the cache internally consistent.
    #[pyo3(name = "add_position")]
    #[expect(clippy::needless_pass_by_value)]
    fn py_add_position(
        &mut self,
        py: Python,
        position: Py<PyAny>,
        oms_type: OmsType,
    ) -> PyResult<()> {
        let position_obj = position.extract::<Position>(py)?;
        self.add_position(&position_obj, oms_type)
            .map_err(to_pyvalue_err)
    }

    /// Creates a snapshot of the `position` by cloning it, assigning a new ID, and storing it
    /// in the position snapshots.
    ///
    /// The copy excludes `replay_events` and `fill_voids`, which no snapshot consumer reads,
    /// so snapshot size stays independent of the fills applied to the position ID. The copy
    /// encodes only when a consumer asks for the bytes, so this call stays off the encode path
    /// unless a backing database has to persist the frame.
    ///
    /// # Errors
    ///
    /// Returns an error if serializing or storing the position snapshot fails.
    #[pyo3(name = "snapshot_position")]
    #[expect(clippy::needless_pass_by_value)]
    fn py_snapshot_position(&mut self, py: Python, position: Py<PyAny>) -> PyResult<()> {
        let position_obj = position.extract::<Position>(py)?;
        self.snapshot_position(&position_obj)
            .map_err(to_pyvalue_err)
    }

    /// Returns a borrow of the position with the `position_id` (if found).
    ///
    /// Prefer `Self.position_ref` in new native code.
    #[pyo3(name = "position")]
    fn py_position(&self, py: Python, position_id: PositionId) -> PyResult<Option<Py<PyAny>>> {
        match self.position(&position_id) {
            Some(position) => Ok(Some(position.clone().into_pyobject(py)?.into())),
            None => Ok(None),
        }
    }

    /// Returns whether a position with the `position_id` exists.
    #[pyo3(name = "position_exists")]
    fn py_position_exists(&self, position_id: PositionId) -> bool {
        self.position_exists(&position_id)
    }

    /// Returns whether a position with the `position_id` is open.
    #[pyo3(name = "is_position_open")]
    fn py_is_position_open(&self, position_id: PositionId) -> bool {
        self.is_position_open(&position_id)
    }

    /// Returns whether a position with the `position_id` is closed.
    #[pyo3(name = "is_position_closed")]
    fn py_is_position_closed(&self, position_id: PositionId) -> bool {
        self.is_position_closed(&position_id)
    }

    /// Returns the count of all open positions.
    #[pyo3(name = "positions_open_count")]
    fn py_positions_open_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> usize {
        self.positions_open_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    /// Returns the count of all closed positions.
    #[pyo3(name = "positions_closed_count")]
    fn py_positions_closed_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> usize {
        self.positions_closed_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    /// Returns the count of all positions.
    #[pyo3(name = "positions_total_count")]
    fn py_positions_total_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> usize {
        self.positions_total_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    /// Adds the `quote` tick to the cache.
    ///
    /// # Errors
    ///
    /// Returns an error if persisting the quote tick to the backing database fails.
    #[pyo3(name = "add_quote")]
    fn py_add_quote(&mut self, quote: QuoteTick) -> PyResult<()> {
        self.add_quote(quote).map_err(to_pyvalue_err)
    }

    /// Adds the `trade` tick to the cache.
    ///
    /// # Errors
    ///
    /// Returns an error if persisting the trade tick to the backing database fails.
    #[pyo3(name = "add_trade")]
    fn py_add_trade(&mut self, trade: TradeTick) -> PyResult<()> {
        self.add_trade(trade).map_err(to_pyvalue_err)
    }

    /// Adds the `bar` to the cache, keeping the per-`bar_type` series newest-first.
    ///
    /// A newer bar is pushed, an older `ts_event` is skipped, and an equal
    /// `ts_event` replaces the front bar for time bars.
    ///
    /// # Errors
    ///
    /// Returns an error if persisting the bar to the backing database fails.
    #[pyo3(name = "add_bar")]
    fn py_add_bar(&mut self, bar: Bar) -> PyResult<()> {
        self.add_bar(bar).map_err(to_pyvalue_err)
    }

    /// Returns the most recently added quote for the `instrument_id`, or `None` if absent.
    #[pyo3(name = "quote")]
    fn py_quote(&self, instrument_id: InstrumentId) -> Option<QuoteTick> {
        self.quote(&instrument_id).copied()
    }

    /// Returns the most recently added trade for the `instrument_id`, or `None` if absent.
    #[pyo3(name = "trade")]
    fn py_trade(&self, instrument_id: InstrumentId) -> Option<TradeTick> {
        self.trade(&instrument_id).copied()
    }

    /// Returns the most recent bar by `ts_event` for the `bar_type`, or `None` if absent.
    #[pyo3(name = "bar")]
    fn py_bar(&self, bar_type: BarType) -> Option<Bar> {
        self.bar(&bar_type).copied()
    }

    /// Returns cached quotes for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added quote. Entries are not sorted by timestamp.
    /// Returns `None` when no quotes are cached for the instrument.
    #[pyo3(name = "quotes")]
    fn py_quotes(&self, instrument_id: InstrumentId) -> Option<Vec<QuoteTick>> {
        self.quotes(&instrument_id)
    }

    /// Returns cached trades for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added trade. Entries are not sorted by timestamp.
    /// Returns `None` when no trades are cached for the instrument.
    #[pyo3(name = "trades")]
    fn py_trades(&self, instrument_id: InstrumentId) -> Option<Vec<TradeTick>> {
        self.trades(&instrument_id)
    }

    /// Returns cached bars for the `bar_type` in reverse chronological order by `ts_event`.
    ///
    /// Index 0 is the most recent bar. Returns `None` when no bars are cached for the bar type.
    #[pyo3(name = "bars")]
    fn py_bars(&self, bar_type: BarType) -> Option<Vec<Bar>> {
        self.bars(&bar_type)
    }

    /// Returns whether the cache contains quotes for the `instrument_id`.
    #[pyo3(name = "has_quote_ticks")]
    fn py_has_quote_ticks(&self, instrument_id: InstrumentId) -> bool {
        self.has_quote_ticks(&instrument_id)
    }

    /// Returns whether the cache contains trades for the `instrument_id`.
    #[pyo3(name = "has_trade_ticks")]
    fn py_has_trade_ticks(&self, instrument_id: InstrumentId) -> bool {
        self.has_trade_ticks(&instrument_id)
    }

    /// Returns whether the cache contains mark price updates for the `instrument_id`.
    #[pyo3(name = "has_mark_prices")]
    fn py_has_mark_prices(&self, instrument_id: InstrumentId) -> bool {
        self.has_mark_prices(&instrument_id)
    }

    /// Returns whether the cache contains index price updates for the `instrument_id`.
    #[pyo3(name = "has_index_prices")]
    fn py_has_index_prices(&self, instrument_id: InstrumentId) -> bool {
        self.has_index_prices(&instrument_id)
    }

    /// Returns whether the cache contains funding rate updates for the `instrument_id`.
    #[pyo3(name = "has_funding_rates")]
    fn py_has_funding_rates(&self, instrument_id: InstrumentId) -> bool {
        self.has_funding_rates(&instrument_id)
    }

    /// Returns whether the cache contains instrument status updates for the `instrument_id`.
    #[pyo3(name = "has_instrument_statuses")]
    fn py_has_instrument_statuses(&self, instrument_id: InstrumentId) -> bool {
        self.has_instrument_statuses(&instrument_id)
    }

    /// Returns whether the cache contains a close for the `instrument_id`.
    #[pyo3(name = "has_instrument_close")]
    fn py_has_instrument_close(&self, instrument_id: InstrumentId) -> bool {
        self.has_instrument_close(&instrument_id)
    }

    /// Returns whether the cache contains bars for the `bar_type`.
    #[pyo3(name = "has_bars")]
    fn py_has_bars(&self, bar_type: BarType) -> bool {
        self.has_bars(&bar_type)
    }

    /// Gets the quote tick count for the `instrument_id`.
    #[pyo3(name = "quote_count")]
    fn py_quote_count(&self, instrument_id: InstrumentId) -> usize {
        self.quote_count(&instrument_id)
    }

    /// Gets the trade tick count for the `instrument_id`.
    #[pyo3(name = "trade_count")]
    fn py_trade_count(&self, instrument_id: InstrumentId) -> usize {
        self.trade_count(&instrument_id)
    }

    /// Gets the mark price update count for the `instrument_id`.
    #[pyo3(name = "mark_price_count")]
    fn py_mark_price_count(&self, instrument_id: InstrumentId) -> usize {
        self.mark_price_count(&instrument_id)
    }

    /// Gets the index price update count for the `instrument_id`.
    #[pyo3(name = "index_price_count")]
    fn py_index_price_count(&self, instrument_id: InstrumentId) -> usize {
        self.index_price_count(&instrument_id)
    }

    /// Gets the funding rate update count for the `instrument_id`.
    #[pyo3(name = "funding_rate_count")]
    fn py_funding_rate_count(&self, instrument_id: InstrumentId) -> usize {
        self.funding_rate_count(&instrument_id)
    }

    /// Gets the instrument status update count for the `instrument_id`.
    #[pyo3(name = "instrument_status_count")]
    fn py_instrument_status_count(&self, instrument_id: InstrumentId) -> usize {
        self.instrument_status_count(&instrument_id)
    }

    /// Gets the bar count for the `instrument_id`.
    #[pyo3(name = "bar_count")]
    fn py_bar_count(&self, bar_type: BarType) -> usize {
        self.bar_count(&bar_type)
    }

    /// Returns the most recently added mark price update for the `instrument_id`, or `None` if absent.
    #[pyo3(name = "mark_price")]
    fn py_mark_price(&self, instrument_id: InstrumentId) -> Option<MarkPriceUpdate> {
        self.mark_price(&instrument_id).copied()
    }

    /// Returns cached mark price updates for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
    /// Returns `None` when no mark price updates are cached for the instrument.
    #[pyo3(name = "mark_prices")]
    fn py_mark_prices(&self, instrument_id: InstrumentId) -> Option<Vec<MarkPriceUpdate>> {
        self.mark_prices(&instrument_id)
    }

    /// Returns the most recently added index price update for the `instrument_id`, or `None` if absent.
    #[pyo3(name = "index_price")]
    fn py_index_price(&self, instrument_id: InstrumentId) -> Option<IndexPriceUpdate> {
        self.index_price(&instrument_id).copied()
    }

    /// Returns cached index price updates for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
    /// Returns `None` when no index price updates are cached for the instrument.
    #[pyo3(name = "index_prices")]
    fn py_index_prices(&self, instrument_id: InstrumentId) -> Option<Vec<IndexPriceUpdate>> {
        self.index_prices(&instrument_id)
    }

    /// Returns the most recently added funding rate update for the `instrument_id`, or `None` if absent.
    #[pyo3(name = "funding_rate")]
    fn py_funding_rate(&self, instrument_id: InstrumentId) -> Option<FundingRateUpdate> {
        self.funding_rate(&instrument_id).copied()
    }

    /// Returns cached funding rate updates for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
    /// Returns `None` when no funding rate updates are cached for the instrument.
    #[pyo3(name = "funding_rates")]
    fn py_funding_rates(&self, instrument_id: InstrumentId) -> Option<Vec<FundingRateUpdate>> {
        self.funding_rates(&instrument_id)
    }

    /// Returns the most recently added instrument status for the `instrument_id`, or `None` if absent.
    #[pyo3(name = "instrument_status")]
    fn py_instrument_status(&self, instrument_id: InstrumentId) -> Option<InstrumentStatus> {
        self.instrument_status(&instrument_id).copied()
    }

    /// Returns cached instrument status updates for the `instrument_id` in reverse insertion order.
    ///
    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
    /// Returns `None` when no instrument status updates are cached for the instrument.
    #[pyo3(name = "instrument_statuses")]
    fn py_instrument_statuses(&self, instrument_id: InstrumentId) -> Option<Vec<InstrumentStatus>> {
        self.instrument_statuses(&instrument_id)
    }

    /// Returns the close cached for `instrument_id`, if present.
    ///
    /// A later insertion replaces the cached close for the instrument; no history is kept.
    #[pyo3(name = "instrument_close")]
    fn py_instrument_close(&self, instrument_id: InstrumentId) -> Option<InstrumentClose> {
        self.instrument_close(&instrument_id).copied()
    }

    /// Returns the current order book for the `instrument_id`, or `None` if absent.
    ///
    /// The cache holds the current book state, not a history of book updates.
    #[pyo3(name = "order_book")]
    fn py_order_book(&self, instrument_id: InstrumentId) -> Option<OrderBook> {
        self.order_book(&instrument_id).cloned()
    }

    /// Returns whether the cache contains an order book for the `instrument_id`.
    #[pyo3(name = "has_order_book")]
    fn py_has_order_book(&self, instrument_id: InstrumentId) -> bool {
        self.has_order_book(&instrument_id)
    }

    /// Gets the order book update count for the `instrument_id`.
    #[pyo3(name = "book_update_count")]
    fn py_book_update_count(&self, instrument_id: InstrumentId) -> usize {
        self.book_update_count(&instrument_id)
    }

    /// Returns a reference to the synthetic instrument for the `instrument_id` (if found).
    #[pyo3(name = "synthetic")]
    fn py_synthetic(&self, instrument_id: InstrumentId) -> Option<SyntheticInstrument> {
        self.synthetic(&instrument_id).cloned()
    }

    /// Returns references to instrument IDs for all synthetic instruments contained in the cache.
    #[pyo3(name = "synthetic_ids")]
    fn py_synthetic_ids(&self) -> Vec<InstrumentId> {
        self.synthetic_ids().into_iter().copied().collect()
    }

    /// Returns the `ClientOrderId`s of all orders.
    #[pyo3(name = "client_order_ids")]
    fn py_client_order_ids(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<ClientOrderId> {
        self.client_order_ids(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
        )
        .into_iter()
        .collect()
    }

    /// Returns the `ClientOrderId`s of all open orders.
    #[pyo3(name = "client_order_ids_open")]
    fn py_client_order_ids_open(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<ClientOrderId> {
        self.client_order_ids_open(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
        )
        .into_iter()
        .collect()
    }

    /// Returns the `ClientOrderId`s of all closed orders.
    #[pyo3(name = "client_order_ids_closed")]
    fn py_client_order_ids_closed(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<ClientOrderId> {
        self.client_order_ids_closed(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
        )
        .into_iter()
        .collect()
    }

    /// Returns the `ClientOrderId`s of all emulated orders.
    #[pyo3(name = "client_order_ids_emulated")]
    fn py_client_order_ids_emulated(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<ClientOrderId> {
        self.client_order_ids_emulated(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
        )
        .into_iter()
        .collect()
    }

    /// Returns the `ClientOrderId`s of all in-flight orders.
    #[pyo3(name = "client_order_ids_inflight")]
    fn py_client_order_ids_inflight(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<ClientOrderId> {
        self.client_order_ids_inflight(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
        )
        .into_iter()
        .collect()
    }

    /// Returns `PositionId`s of all positions.
    #[pyo3(name = "position_ids")]
    fn py_position_ids(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<PositionId> {
        self.position_ids(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
        )
        .into_iter()
        .collect()
    }

    /// Returns the `PositionId`s of all open positions.
    #[pyo3(name = "position_open_ids")]
    fn py_position_open_ids(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<PositionId> {
        self.position_open_ids(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
        )
        .into_iter()
        .collect()
    }

    /// Returns the `PositionId`s of all closed positions.
    #[pyo3(name = "position_closed_ids")]
    fn py_position_closed_ids(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<PositionId> {
        self.position_closed_ids(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
        )
        .into_iter()
        .collect()
    }

    /// Returns the `StrategyId`s of all strategies.
    #[pyo3(name = "strategy_ids")]
    fn py_strategy_ids(&self) -> Vec<StrategyId> {
        self.strategy_ids().into_iter().collect()
    }

    /// Returns the `ExecAlgorithmId`s of all execution algorithms.
    #[pyo3(name = "exec_algorithm_ids")]
    fn py_exec_algorithm_ids(&self) -> Vec<ExecAlgorithmId> {
        self.exec_algorithm_ids().into_iter().collect()
    }

    /// Gets a reference to the client order ID for the `venue_order_id` (if found).
    #[pyo3(name = "client_order_id")]
    fn py_client_order_id(&self, venue_order_id: VenueOrderId) -> Option<ClientOrderId> {
        self.client_order_id(&venue_order_id).copied()
    }

    /// Gets a reference to the venue order ID for the `client_order_id` (if found).
    #[pyo3(name = "venue_order_id")]
    fn py_venue_order_id(&self, client_order_id: ClientOrderId) -> Option<VenueOrderId> {
        self.venue_order_id(&client_order_id).copied()
    }

    /// Gets a reference to the client ID indexed for then `client_order_id` (if found).
    #[pyo3(name = "client_id")]
    fn py_client_id(&self, client_order_id: ClientOrderId) -> Option<ClientId> {
        self.client_id(&client_order_id).copied()
    }

    /// Returns borrows of all orders matching the optional filter parameters.
    ///
    /// Prefer `Self.orders_refs` in new native code.
    #[pyo3(name = "orders")]
    fn py_orders(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.orders(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
        .into_iter()
        .map(|o| order_any_to_pyobject(py, o.clone()))
        .collect()
    }

    /// Returns borrows of all open orders matching the optional filter parameters.
    ///
    /// Prefer `Self.orders_open_refs` in new native code.
    #[pyo3(name = "orders_open")]
    fn py_orders_open(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.orders_open(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
        .into_iter()
        .map(|o| order_any_to_pyobject(py, o.clone()))
        .collect()
    }

    /// Returns borrows of all closed orders matching the optional filter parameters.
    ///
    /// Prefer `Self.orders_closed_refs` in new native code.
    #[pyo3(name = "orders_closed")]
    fn py_orders_closed(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.orders_closed(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
        .into_iter()
        .map(|o| order_any_to_pyobject(py, o.clone()))
        .collect()
    }

    /// Returns borrows of all emulated orders matching the optional filter parameters.
    ///
    /// Prefer `Self.orders_emulated_refs` in new native code.
    #[pyo3(name = "orders_emulated")]
    fn py_orders_emulated(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.orders_emulated(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
        .into_iter()
        .map(|o| order_any_to_pyobject(py, o.clone()))
        .collect()
    }

    /// Returns borrows of all in-flight orders matching the optional filter parameters.
    ///
    /// Prefer `Self.orders_inflight_refs` in new native code.
    #[pyo3(name = "orders_inflight")]
    fn py_orders_inflight(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.orders_inflight(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
        .into_iter()
        .map(|o| order_any_to_pyobject(py, o.clone()))
        .collect()
    }

    /// Returns borrows of all orders for the `position_id`.
    #[pyo3(name = "orders_for_position")]
    fn py_orders_for_position(
        &self,
        py: Python,
        position_id: PositionId,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.orders_for_position(&position_id)
            .into_iter()
            .map(|o| order_any_to_pyobject(py, o.clone()))
            .collect()
    }

    /// Returns whether an order with the `client_order_id` is emulated.
    #[pyo3(name = "is_order_emulated")]
    fn py_is_order_emulated(&self, client_order_id: ClientOrderId) -> bool {
        self.is_order_emulated(&client_order_id)
    }

    /// Returns whether an order with the `client_order_id` is in-flight.
    #[pyo3(name = "is_order_inflight")]
    fn py_is_order_inflight(&self, client_order_id: ClientOrderId) -> bool {
        self.is_order_inflight(&client_order_id)
    }

    /// Returns whether an order with the `client_order_id` is `PENDING_CANCEL` locally.
    #[pyo3(name = "is_order_pending_cancel_local")]
    fn py_is_order_pending_cancel_local(&self, client_order_id: ClientOrderId) -> bool {
        self.is_order_pending_cancel_local(&client_order_id)
    }

    /// Returns the count of all emulated orders.
    #[pyo3(name = "orders_emulated_count")]
    fn py_orders_emulated_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.orders_emulated_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    /// Returns the count of all in-flight orders.
    #[pyo3(name = "orders_inflight_count")]
    fn py_orders_inflight_count(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> usize {
        self.orders_inflight_count(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
    }

    /// Returns the order list for the `order_list_id`.
    #[pyo3(name = "order_list")]
    fn py_order_list(&self, order_list_id: OrderListId) -> Option<OrderList> {
        self.order_list(&order_list_id).cloned()
    }

    /// Returns all order lists matching the optional filter parameters.
    #[pyo3(name = "order_lists")]
    fn py_order_lists(
        &self,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
    ) -> Vec<OrderList> {
        self.order_lists(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
        )
        .into_iter()
        .cloned()
        .collect()
    }

    /// Returns whether an order list with the `order_list_id` exists.
    #[pyo3(name = "order_list_exists")]
    fn py_order_list_exists(&self, order_list_id: OrderListId) -> bool {
        self.order_list_exists(&order_list_id)
    }

    /// Returns references to all orders associated with the `exec_algorithm_id` matching the
    /// optional filter parameters.
    #[pyo3(name = "orders_for_exec_algorithm")]
    #[expect(clippy::too_many_arguments)]
    fn py_orders_for_exec_algorithm(
        &self,
        py: Python,
        exec_algorithm_id: ExecAlgorithmId,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<OrderSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.orders_for_exec_algorithm(
            &exec_algorithm_id,
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
        .into_iter()
        .map(|o| order_any_to_pyobject(py, o.clone()))
        .collect()
    }

    /// Returns references to all orders with the `exec_spawn_id`.
    #[pyo3(name = "orders_for_exec_spawn")]
    fn py_orders_for_exec_spawn(
        &self,
        py: Python,
        exec_spawn_id: ClientOrderId,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.orders_for_exec_spawn(&exec_spawn_id)
            .into_iter()
            .map(|o| order_any_to_pyobject(py, o.clone()))
            .collect()
    }

    /// Returns the total order quantity for the `exec_spawn_id`.
    #[pyo3(name = "exec_spawn_total_quantity")]
    fn py_exec_spawn_total_quantity(
        &self,
        exec_spawn_id: ClientOrderId,
        active_only: bool,
    ) -> Option<Quantity> {
        self.exec_spawn_total_quantity(&exec_spawn_id, active_only)
    }

    /// Returns the total filled quantity for all orders with the `exec_spawn_id`.
    #[pyo3(name = "exec_spawn_total_filled_qty")]
    fn py_exec_spawn_total_filled_qty(
        &self,
        exec_spawn_id: ClientOrderId,
        active_only: bool,
    ) -> Option<Quantity> {
        self.exec_spawn_total_filled_qty(&exec_spawn_id, active_only)
    }

    /// Returns the total leaves quantity for all orders with the `exec_spawn_id`.
    #[pyo3(name = "exec_spawn_total_leaves_qty")]
    fn py_exec_spawn_total_leaves_qty(
        &self,
        exec_spawn_id: ClientOrderId,
        active_only: bool,
    ) -> Option<Quantity> {
        self.exec_spawn_total_leaves_qty(&exec_spawn_id, active_only)
    }

    /// Returns a borrow of the position for the `client_order_id` (if found).
    ///
    /// Prefer `Self.position_for_order_ref` in new native code.
    #[pyo3(name = "position_for_order")]
    fn py_position_for_order(
        &self,
        py: Python,
        client_order_id: ClientOrderId,
    ) -> PyResult<Option<Py<PyAny>>> {
        match self.position_for_order(&client_order_id) {
            Some(position) => Ok(Some(position.clone().into_pyobject(py)?.into())),
            None => Ok(None),
        }
    }

    /// Returns a reference to the position ID for the `client_order_id` (if found).
    #[pyo3(name = "position_id")]
    fn py_position_id(&self, client_order_id: ClientOrderId) -> Option<PositionId> {
        self.position_id(&client_order_id).copied()
    }

    /// Returns borrows of all positions matching the optional filter parameters.
    ///
    /// Prefer `Self.positions_refs` in new native code.
    #[pyo3(name = "positions")]
    fn py_positions(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.positions(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
        .into_iter()
        .map(|p| Ok(p.clone().into_pyobject(py)?.into()))
        .collect()
    }

    /// Returns borrows of all open positions matching the optional filter parameters.
    ///
    /// Prefer `Self.positions_open_refs` in new native code.
    #[pyo3(name = "positions_open")]
    fn py_positions_open(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.positions_open(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
        .into_iter()
        .map(|p| Ok(p.clone().into_pyobject(py)?.into()))
        .collect()
    }

    /// Returns borrows of all closed positions matching the optional filter parameters.
    ///
    /// Prefer `Self.positions_closed_refs` in new native code.
    #[pyo3(name = "positions_closed")]
    fn py_positions_closed(
        &self,
        py: Python,
        venue: Option<Venue>,
        instrument_id: Option<InstrumentId>,
        strategy_id: Option<StrategyId>,
        account_id: Option<AccountId>,
        side: Option<PositionSide>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.positions_closed(
            venue.as_ref(),
            instrument_id.as_ref(),
            strategy_id.as_ref(),
            account_id.as_ref(),
            side,
        )
        .into_iter()
        .map(|p| Ok(p.clone().into_pyobject(py)?.into()))
        .collect()
    }

    /// Gets a reference to the strategy ID for the `client_order_id` (if found).
    #[pyo3(name = "strategy_id_for_order")]
    fn py_strategy_id_for_order(&self, client_order_id: ClientOrderId) -> Option<StrategyId> {
        self.strategy_id_for_order(&client_order_id).copied()
    }

    /// Gets a reference to the strategy ID for the `position_id` (if found).
    #[pyo3(name = "strategy_id_for_position")]
    fn py_strategy_id_for_position(&self, position_id: PositionId) -> Option<StrategyId> {
        self.strategy_id_for_position(&position_id).copied()
    }

    /// Gets the serialized position snapshot frames for the `position_id`.
    ///
    /// Each element in the returned vector is one JSON-encoded `Position` snapshot,
    /// in the order they were taken. Frames that fail to serialize are skipped with a warning.
    #[pyo3(name = "position_snapshot_bytes")]
    fn py_position_snapshot_bytes(&self, position_id: PositionId) -> Option<Vec<Vec<u8>>> {
        self.position_snapshot_bytes(&position_id)
    }

    /// Returns all position snapshots with the given optional filters.
    ///
    /// When `position_id` is `Some`, only snapshots for that position are returned.
    /// When `account_id` is `Some`, snapshots are filtered to that account.
    #[pyo3(name = "position_snapshots", signature = (position_id=None, account_id=None))]
    fn py_position_snapshots(
        &self,
        py: Python,
        position_id: Option<PositionId>,
        account_id: Option<AccountId>,
    ) -> PyResult<Vec<Py<PyAny>>> {
        self.position_snapshots(position_id.as_ref(), account_id.as_ref())
            .into_iter()
            .map(|p| Ok(p.into_pyobject(py)?.into()))
            .collect()
    }

    /// Returns a borrow of the account for the `account_id` (if found).
    ///
    /// Prefer `Self.account_ref` in new native code.
    #[pyo3(name = "account")]
    fn py_account(&self, py: Python, account_id: AccountId) -> PyResult<Option<Py<PyAny>>> {
        match self.account(&account_id) {
            Some(account) => Ok(Some(account_any_to_pyobject(py, account.clone())?)),
            None => Ok(None),
        }
    }

    /// Returns a borrow of the account for the `venue` (if found).
    ///
    /// Returns `None` when more than one account is issued under the `venue`; look those
    /// accounts up by account ID instead.
    #[pyo3(name = "account_for_venue")]
    fn py_account_for_venue(&self, py: Python, venue: Venue) -> PyResult<Option<Py<PyAny>>> {
        match self.account_for_venue(&venue) {
            Some(account) => Ok(Some(account_any_to_pyobject(py, account.clone())?)),
            None => Ok(None),
        }
    }

    /// Returns a reference to the account ID for the `venue` (if found).
    ///
    /// Returns `None` when more than one account is issued under the `venue`.
    #[pyo3(name = "account_id")]
    fn py_account_id(&self, venue: Venue) -> Option<AccountId> {
        self.account_id(&venue).copied()
    }

    /// Gets a reference to the general value for the `key` (if found).
    ///
    /// # Errors
    ///
    /// Returns an error if the `key` is invalid.
    #[pyo3(name = "get")]
    fn py_get(&self, key: &str) -> PyResult<Option<Vec<u8>>> {
        match self.get(key).map_err(to_pyvalue_err)? {
            Some(bytes) => Ok(Some(bytes.to_vec())),
            None => Ok(None),
        }
    }

    /// Adds a general `value` to the cache for the given `key`.
    #[pyo3(name = "add")]
    fn py_add_general(&mut self, key: &str, value: Vec<u8>) -> PyResult<()> {
        self.add(key, Bytes::from(value)).map_err(to_pyvalue_err)
    }

    /// Returns the price for the `instrument_id` and `price_type` (if found).
    ///
    /// For `Mid`, returns `None` if no quote is cached or either price is a sentinel.
    /// For quote precision `p`, the midpoint has precision `p + 1` when exactly representable,
    /// otherwise `p`, rounded half-even if necessary. The fallback applies when the precision
    /// limit or raw range rules out `p + 1`, and when `p` is the maximum float precision (16),
    /// so a midpoint of a float-convertible quote stays float-convertible.
    #[pyo3(name = "price")]
    fn py_price(&self, instrument_id: InstrumentId, price_type: PriceType) -> Option<Price> {
        self.price(&instrument_id, price_type)
    }

    /// Returns the exchange rate for the given parameters.
    #[pyo3(name = "get_xrate")]
    fn py_get_xrate(
        &self,
        venue: Venue,
        from_currency: Currency,
        to_currency: Currency,
        price_type: PriceType,
    ) -> Option<f64> {
        self.get_xrate(venue, from_currency, to_currency, price_type)
            .and_then(|rate| rate.to_f64())
    }

    /// Returns the mark exchange rate for the given currency pair, or `None` if not set.
    #[pyo3(name = "get_mark_xrate")]
    fn py_get_mark_xrate(&self, from_currency: Currency, to_currency: Currency) -> Option<f64> {
        self.get_mark_xrate(from_currency, to_currency)
    }

    /// Sets the mark exchange rate for the given currency pair and automatically sets the inverse rate.
    #[pyo3(name = "set_mark_xrate")]
    fn py_set_mark_xrate(&mut self, from_currency: Currency, to_currency: Currency, xrate: f64) {
        self.set_mark_xrate(from_currency, to_currency, xrate);
    }

    /// Clears the mark exchange rate for the given currency pair direction.
    ///
    /// Removes only the `(from_currency, to_currency)` entry; the inverse rate written
    /// by `Self.set_mark_xrate` is retained until cleared separately or
    /// `Self.clear_mark_xrates` is called.
    #[pyo3(name = "clear_mark_xrate")]
    fn py_clear_mark_xrate(&mut self, from_currency: Currency, to_currency: Currency) {
        self.clear_mark_xrate(from_currency, to_currency);
    }

    /// Clears all mark exchange rates.
    #[pyo3(name = "clear_mark_xrates")]
    fn py_clear_mark_xrates(&mut self) {
        self.clear_mark_xrates();
    }

    /// Calculates the unrealized PnL for the given position.
    #[pyo3(name = "calculate_unrealized_pnl")]
    #[expect(clippy::needless_pass_by_value)]
    fn py_calculate_unrealized_pnl(
        &self,
        py: Python,
        position: Py<PyAny>,
    ) -> PyResult<Option<Money>> {
        let position = position.extract::<Position>(py)?;
        Ok(self.calculate_unrealized_pnl(&position))
    }

    /// Gets a reference to the own order book for the `instrument_id`.
    #[pyo3(name = "own_order_book")]
    fn py_own_order_book(&self, instrument_id: InstrumentId) -> Option<OwnOrderBook> {
        self.own_order_book(&instrument_id).cloned()
    }

    /// Updates the own order book with an order.
    ///
    /// This method adds, updates, or removes an order from the own order book
    /// based on the order's current state.
    ///
    /// Orders without prices (MARKET, etc.) are skipped as they cannot be
    /// represented in own books.
    #[pyo3(name = "update_own_order_book")]
    fn py_update_own_order_book(&mut self, py: Python, order: Py<PyAny>) -> PyResult<()> {
        let order_any = pyobject_to_order_any(py, order)?;
        self.update_own_order_book(&order_any);
        Ok(())
    }

    /// Force removal of an order from own order books and clean up all indexes.
    ///
    /// This method is used when order event application fails and we need to ensure
    /// terminal orders are properly cleaned up from own books and all relevant indexes.
    /// Replicates the index cleanup that `update_order` performs for closed orders.
    #[pyo3(name = "force_remove_from_own_order_book")]
    fn py_force_remove_from_own_order_book(&mut self, client_order_id: ClientOrderId) {
        self.force_remove_from_own_order_book(&client_order_id);
    }

    /// Audit all own order books against active order indexes.
    ///
    /// Ensures orders absent from the open, inflight, and active-local indexes are removed from
    /// own order books.
    #[pyo3(name = "audit_own_order_books")]
    fn py_audit_own_order_books(&mut self) {
        self.audit_own_order_books();
    }
}

#[cfg(feature = "defi")]
#[pymethods]
impl Cache {
    /// Adds a `Pool` to the cache.
    ///
    /// This function does not return errors; the result type matches the other add methods.
    #[pyo3(name = "add_pool")]
    fn py_add_pool(&mut self, pool: Pool) -> PyResult<()> {
        self.add_pool(pool).map_err(to_pyvalue_err)
    }

    /// Gets a reference to the pool for the `instrument_id`.
    #[pyo3(name = "pool")]
    fn py_pool(&self, instrument_id: InstrumentId) -> Option<Pool> {
        self.pool(&instrument_id).cloned()
    }

    /// Returns the instrument IDs of all pools in the cache, optionally filtered by `venue`.
    #[pyo3(name = "pool_ids")]
    fn py_pool_ids(&self, venue: Option<Venue>) -> Vec<InstrumentId> {
        self.pool_ids(venue.as_ref())
    }

    /// Returns references to all pools in the cache, optionally filtered by `venue`.
    #[pyo3(name = "pools")]
    fn py_pools(&self, venue: Option<Venue>) -> Vec<Pool> {
        self.pools(venue.as_ref()).into_iter().cloned().collect()
    }

    /// Adds a `PoolProfiler` to the cache.
    ///
    /// This function does not return errors; the result type matches the other add methods.
    #[pyo3(name = "add_pool_profiler")]
    fn py_add_pool_profiler(&mut self, pool_profiler: PoolProfiler) -> PyResult<()> {
        self.add_pool_profiler(pool_profiler)
            .map_err(to_pyvalue_err)
    }

    /// Gets a reference to the pool profiler for the `instrument_id`.
    #[pyo3(name = "pool_profiler")]
    fn py_pool_profiler(&self, instrument_id: InstrumentId) -> Option<PoolProfiler> {
        self.pool_profiler(&instrument_id).cloned()
    }

    /// Returns the instrument IDs of all pool profilers in the cache, optionally filtered by `venue`.
    #[pyo3(name = "pool_profiler_ids")]
    fn py_pool_profiler_ids(&self, venue: Option<Venue>) -> Vec<InstrumentId> {
        self.pool_profiler_ids(venue.as_ref())
    }

    /// Returns references to all pool profilers in the cache, optionally filtered by `venue`.
    #[pyo3(name = "pool_profilers")]
    fn py_pool_profilers(&self, venue: Option<Venue>) -> Vec<PoolProfiler> {
        self.pool_profilers(venue.as_ref())
            .into_iter()
            .cloned()
            .collect()
    }
}