Enhance instrument handling by adding InstrumentNotFound exception, updating assure_instrument and related methods to improve order book ID validation, and refining argument checking for instrument types.

Cuizi7 · Cuizi7 · commit 30fb5dc93d02 · 2025-12-16T14:13:12.000+08:00
diff --git a/rqalpha/apis/api_base.py b/rqalpha/apis/api_base.py
@@ -28,7 +28,7 @@
 from rqalpha.environment import Environment
 from rqalpha.core.execution_context import ExecutionContext
 from rqalpha.utils import is_valid_price
-from rqalpha.utils.exception import RQInvalidArgument
+from rqalpha.utils.exception import RQInvalidArgument, InstrumentNotFound
 from rqalpha.utils.i18n import gettext as _
 from rqalpha.utils.arg_checker import apply_rules, verify_that
 from rqalpha.api import export_as_api
@@ -60,22 +60,35 @@
 export_as_api(EVENT, name='EVENT')
 
 
-def assure_instrument(id_or_ins) -> Instrument:
+def assure_instrument(id_or_ins, verify_listing: bool) -> Instrument:
+    # verify_listing: 是否验证合约是否上市，注意，港股存在复用代码的情况，因此该参数应尽量设为 True 以避免搜索 instrument 失败
     if isinstance(id_or_ins, Instrument):
         return id_or_ins
     elif isinstance(id_or_ins, six.string_types):
-        ins = Environment.get_instance().data_proxy.instrument(id_or_ins)
-        if not ins:
-            raise RQInvalidArgument(_(
-                "invalid argument, expected order_book_ids or Instrument objects, got {} (type: {})"
-            ).format(id_or_ins, type(id_or_ins)))
+        env = Environment.get_instance()
+        try:
+            ins = env.data_proxy.instrument_not_none(id_or_ins, env.trading_dt if verify_listing else None)
+        except InstrumentNotFound as e:
+            if verify_listing:
+                raise RQInvalidArgument(_(
+                    "instrument {} not found or not listed at {}"
+                ).format(id_or_ins, env.trading_dt.date()))
+            else:
+                raise RQInvalidArgument(_(
+                    "instrument {} not found"
+                ).format(id_or_ins))
         return ins
     else:
         raise RQInvalidArgument(_(u"unsupported order_book_id type"))
 
 
 def assure_order_book_id(id_or_ins):
-    return assure_instrument(id_or_ins).order_book_id
+    if isinstance(id_or_ins, Instrument):
+        return id_or_ins.order_book_id
+    try:
+        return Environment.get_instance().data_proxy.assure_order_book_id(id_or_ins)
+    except InstrumentNotFound as e:
+        raise RQInvalidArgument(_("instrument {} not found").format(id_or_ins))
 
 
 def cal_style(price, style, price_or_style=None):
@@ -134,7 +147,7 @@ def get_open_orders():
 
 @export_as_api
 @apply_rules(
-    verify_that("id_or_ins").is_valid_instrument(),
+    verify_that("id_or_ins").is_valid_order_book_id(),
     verify_that("amount").is_number().is_greater_than(0),
     verify_that("side").is_in([SIDE.BUY, SIDE.SELL]),
 )
@@ -755,7 +768,7 @@ def get_next_trading_date(date, n=1):
     EXECUTION_PHASE.AFTER_TRADING,
     EXECUTION_PHASE.SCHEDULED,
 )
-@apply_rules(verify_that("id_or_symbol").is_valid_instrument())
+@apply_rules(verify_that("id_or_symbol").is_valid_order_book_id())
 def current_snapshot(id_or_symbol):
     # type: (Union[str, Instrument]) -> Optional[TickObject]
     """
diff --git a/rqalpha/apis/api_rqdatac.py b/rqalpha/apis/api_rqdatac.py
@@ -827,7 +827,7 @@ def get_stock_connect(order_book_ids, count=1, fields=None, expect_df=False):
 
 
 @export_as_api
-@apply_rules(verify_that('order_book_id').is_valid_instrument(),
+@apply_rules(verify_that('order_book_id').is_valid_order_book_id(),
              verify_that('quarter').is_valid_quarter(),
              verify_that('fields').are_valid_fields(VALID_CURRENT_PERFORMANCE_FIELDS, ignore_none=True))
 def current_performance(order_book_id, info_date=None, quarter=None, interval='1q', fields=None):
diff --git a/rqalpha/data/base_data_source/data_source.py b/rqalpha/data/base_data_source/data_source.py
@@ -183,8 +183,7 @@ def get_dividend(self, instrument):
     def get_trading_minutes_for(self, instrument, trading_dt):
         raise NotImplementedError
 
-    def get_trading_calendars(self):
-        # type: () -> Dict[TRADING_CALENDAR_TYPE, pd.DatetimeIndex]
+    def get_trading_calendars(self) -> Dict[TRADING_CALENDAR_TYPE, pd.DatetimeIndex]:
         return {t: store.get_trading_calendar() for t, store in self._calendar_stores.items()}
 
     def get_instruments(self, id_or_syms: Optional[Iterable[str]] = None, types: Optional[Iterable[INSTRUMENT_TYPE]] = None) -> Iterable[Instrument]:
diff --git a/rqalpha/data/data_proxy.py b/rqalpha/data/data_proxy.py
@@ -16,25 +16,26 @@
 #         详细的授权流程，请联系 public@ricequant.com 获取。
 
 from datetime import datetime, date
-from typing import Union, List, Sequence, Optional, Tuple, Iterable, Dict
+from typing import Union, List, Sequence, Optional, Tuple, Iterable, Dict, Callable
 
 import numpy as np
 import pandas as pd
 
-from rqalpha.const import INSTRUMENT_TYPE, TRADING_CALENDAR_TYPE, EXECUTION_PHASE, MARKET
+from rqalpha.const import INSTRUMENT_TYPE, EXECUTION_PHASE, MARKET
 from rqalpha.utils import risk_free_helper, TimeRange, merge_trading_period
 from rqalpha.data.trading_dates_mixin import TradingDatesMixin
 from rqalpha.model.bar import BarObject, NANDict, PartialBarObject
 from rqalpha.model.tick import TickObject
 from rqalpha.model.instrument import Instrument
 from rqalpha.model.order import ALGO_ORDER_STYLES
 from rqalpha.utils.functools import lru_cache
-from rqalpha.utils.datetime_func import convert_int_to_datetime, convert_date_to_int
+from rqalpha.utils.datetime_func import convert_int_to_datetime
 from rqalpha.utils.typing import DateLike, StrOrIter
 from rqalpha.utils.i18n import gettext as _
 from rqalpha.interface import AbstractDataSource, AbstractPriceBoard, ExchangeRate
 from rqalpha.core.execution_context import ExecutionContext
 from rqalpha.utils.typing import DateLike
+from rqalpha.utils.exception import InstrumentNotFound
 
 
 class DataProxy(TradingDatesMixin):
@@ -285,8 +286,7 @@ def get_last_price(self, order_book_id):
         # type: (str) -> float
         return float(self._price_board.get_last_price(order_book_id))
 
-    def all_instruments(self, types, dt=None):
-        # type: (List[INSTRUMENT_TYPE], Optional[datetime]) -> List[Instrument]
+    def all_instruments(self, types: List[INSTRUMENT_TYPE], dt: Optional[datetime] = None) -> List[Instrument]:
         li = []
         for i in self._data_source.get_instruments(types=types):
             if dt is None or i.listing_at(dt):
@@ -295,20 +295,42 @@ def all_instruments(self, types, dt=None):
         # return [i for i in self._data_source.get_instruments(types=types) if dt is None or i.listing_at(dt)]
 
     @lru_cache(2048)
-    def instrument(self, sym_or_id):
-        return next(iter(self._data_source.get_instruments(id_or_syms=[sym_or_id])), None)
+    def instrument_not_none(self, id_or_sym: str, dt: Optional[datetime] = None) -> Instrument:
+        """
+        根据合约代码获取唯一的 Instrument 对象
 
-    @lru_cache(2048)
-    def instrument_not_none(self, sym_or_id) -> Instrument:
-        try:
-            return next(iter(self._data_source.get_instruments(id_or_syms=[sym_or_id])))
-        except StopIteration:
-            raise LookupError(_("Instrument not found: {}").format(sym_or_id))
+        :param str id_or_sym: 合约代码或合约简称
+        :param datetime dt: 可选，指定查询的时间点。若提供此参数，则仅返回在该时间点处于上市状态的合约
+            注意，对于港股等可能出现复用代码情况等品种，请一律指定 dt 参数
+        :return: 匹配的 Instrument 对象
+        """
+        candidates = []
+        for instrument in self._data_source.get_instruments(id_or_syms=[id_or_sym]):
+            if dt is None or instrument.listing_at(dt):
+                candidates.append(instrument)
+        if not candidates:
+            raise InstrumentNotFound(_("No instrument found at {dt}: {id_or_sym}").format(dt=dt, id_or_sym=id_or_sym))
+        if len(candidates) > 1:
+            raise InstrumentNotFound(_("Multiple instruments found at {dt}: {id_or_sym}").format(dt=dt, id_or_sym=id_or_sym))
+        return candidates[0]
 
     def multi_instruments(self, order_book_ids: Iterable[str]) -> Dict[str, Instrument]:
         return {i.order_book_id: i for i in self._data_source.get_instruments(id_or_syms=order_book_ids)}
 
+    def assure_order_book_id(self, order_book_id: str, expected_type: Optional[INSTRUMENT_TYPE] = None) -> str:
+        for instrument in self._data_source.get_instruments(id_or_syms=[order_book_id]):
+            if expected_type is not None and instrument.type != expected_type:
+                continue
+            return instrument.order_book_id
+        raise InstrumentNotFound(_("No instrument found: {}").format(order_book_id))
+
+    @lru_cache(2048)
+    def instrument(self, sym_or_id):
+        # deprecated
+        return next(iter(self._data_source.get_instruments(id_or_syms=[sym_or_id])), None)
+
     def instruments(self, sym_or_ids):
+        # deprecated
         # type: (StrOrIter) -> Union[None, Instrument, List[Instrument]]
         if isinstance(sym_or_ids, str):
             return next(iter(self._data_source.get_instruments(id_or_syms=[sym_or_ids])), None)
diff --git a/rqalpha/mod/rqalpha_mod_sys_accounts/api/api_stock.py b/rqalpha/mod/rqalpha_mod_sys_accounts/api/api_stock.py
@@ -268,7 +268,11 @@ def stock_order_to(order_book_id, quantity, price_or_style=None, price=None, sty
     EXECUTION_PHASE.SCHEDULED,
     EXECUTION_PHASE.GLOBAL
 )
-@apply_rules(verify_that('id_or_ins').is_valid_stock(), verify_that('amount').is_number(), *common_rules)
+@apply_rules(
+    verify_that('id_or_ins').is_valid_order_book_id(expected_type=INSTRUMENT_TYPE.CS), 
+    verify_that('amount').is_number(), 
+    *common_rules
+)
 def order_lots(id_or_ins, amount, price_or_style=None, price=None, style=None):
     # type: (Union[str, Instrument], int, PRICE_OR_STYLE_TYPE, Optional[float], Optional[OrderStyle]) -> Optional[Order]
     """
@@ -462,7 +466,7 @@ def order_target_portfolio(
                                 EXECUTION_PHASE.ON_TICK,
                                 EXECUTION_PHASE.AFTER_TRADING,
                                 EXECUTION_PHASE.SCHEDULED)
-@apply_rules(verify_that('order_book_id').is_valid_instrument(),
+@apply_rules(verify_that('order_book_id').is_valid_order_book_id(),
              verify_that('count').is_greater_than(0))
 def is_suspended(order_book_id, count=1):
     # type: (str, Optional[int]) -> Union[bool, pd.DataFrame]
@@ -486,7 +490,7 @@ def is_suspended(order_book_id, count=1):
                                 EXECUTION_PHASE.ON_TICK,
                                 EXECUTION_PHASE.AFTER_TRADING,
                                 EXECUTION_PHASE.SCHEDULED)
-@apply_rules(verify_that('order_book_id').is_valid_instrument())
+@apply_rules(verify_that('order_book_id').is_valid_order_book_id())
 def is_st_stock(order_book_id, count=1):
     # type: (str, Optional[int]) -> Union[bool, pd.DataFrame]
     """
@@ -697,7 +701,7 @@ def init(context):
 
 @export_as_api
 @apply_rules(
-    verify_that("order_book_id").is_valid_instrument(),
+    verify_that("order_book_id").is_valid_order_book_id(),
     verify_that("start_date").is_valid_date(ignore_none=False),
 )
 def get_dividend(order_book_id, start_date):
diff --git a/rqalpha/model/instrument.py b/rqalpha/model/instrument.py
@@ -17,8 +17,7 @@
 
 import re
 import copy
-import datetime
-import inspect
+from datetime import datetime, time, date
 from typing import Dict, Callable, Optional
 from methodtools import lru_cache
 
@@ -34,17 +33,17 @@
 
 # TODO：改为 namedtuple，提升性能
 class Instrument(metaclass=PropertyReprMeta):
-    DEFAULT_DE_LISTED_DATE = datetime.datetime(2999, 12, 31)
+    DEFAULT_DE_LISTED_DATE = datetime(2999, 12, 31)
 
     @staticmethod
-    def _fix_date(ds, dflt=None) -> Optional[datetime.datetime]:
-        if isinstance(ds, datetime.datetime):
+    def _fix_date(ds, dflt=None) -> Optional[datetime]:
+        if isinstance(ds, datetime):
             return ds
         if ds == '0000-00-00' or ds is None:
             return dflt
         try:
             year, month, day = ds.split('-')
-            return datetime.datetime(int(year), int(month), int(day))
+            return datetime(int(year), int(month), int(day))
         except:
             return parse(ds)
 
@@ -92,15 +91,14 @@ def round_lot(self) -> int:
         return int(self._dict["round_lot"])
 
     @cached_property
-    def listed_date(self) -> Optional[datetime.datetime]:
+    def listed_date(self) -> datetime:
         """
         [datetime] 股票：该证券上市日期。期货：期货的上市日期，主力连续合约与指数连续合约都为 datetime(1990, 1, 1)。
         """
         return self._dict["listed_date"]
 
     @cached_property
-    def de_listed_date(self):
-        # type: () -> datetime.datetime
+    def de_listed_date(self) -> datetime:
         """
         [datetime] 股票：退市日期。期货：交割日期。
         """
@@ -262,7 +260,7 @@ def underlying_symbol(self):
 
     @cached_property
     def maturity_date(self):
-        # type: () -> datetime.datetime
+        # type: () -> datetime
         """
         [datetime] 到期日
         """
@@ -316,36 +314,30 @@ def account_type(self):
         else:
             raise NotImplementedError
 
-    def listing_at(self, dt):
+    def listing_at(self, dt: datetime) -> bool:
         """
         该合约在指定日期是否在交易
-        :param dt: datetime.datetime
-        :return: bool
         """
         return self.listed_at(dt) and not self.de_listed_at(dt)
 
-    def listed_at(self, dt):
+    def listed_at(self, dt: datetime) -> bool:
         """
         该合约在指定日期是否已上市
-        :param dt: datetime.datetime
-        :return: bool
         """
-        return self.listed_date and self.listed_date <= dt
+        return self.listed_date <= dt
 
-    def de_listed_at(self, dt):
+    def de_listed_at(self, dt: datetime) -> bool:
         """
         该合约在指定日期是否已退市
-        :param dt: datetime.datetime
-        :return: bool
         """
         if self.type in (INSTRUMENT_TYPE.FUTURE, INSTRUMENT_TYPE.OPTION):
             return dt.date() > self.de_listed_date.date()
         else:
             return dt >= self.de_listed_date
 
     STOCK_TRADING_PERIOD = [
-        TimeRange(start=datetime.time(9, 31), end=datetime.time(11, 30)),
-        TimeRange(start=datetime.time(13, 1), end=datetime.time(15, 0)),
+        TimeRange(start=time(9, 31), end=time(11, 30)),
+        TimeRange(start=time(13, 1), end=time(15, 0)),
     ]
 
     @cached_property
@@ -361,16 +353,16 @@ def trading_hours(self):
         trading_hours = trading_hours.replace("-", ":")
         for time_range_str in trading_hours.split(","):
             start_h, start_m, end_h, end_m = (int(i) for i in time_range_str.split(":"))
-            start, end = datetime.time(start_h, start_m), datetime.time(end_h, end_m)
+            start, end = time(start_h, start_m), time(end_h, end_m)
             if start > end:
-                trading_period.append(TimeRange(start, datetime.time(23, 59)))
-                trading_period.append(TimeRange(datetime.time(0, 0), end))
+                trading_period.append(TimeRange(start, time(23, 59)))
+                trading_period.append(TimeRange(time(0, 0), end))
             else:
                 trading_period.append(TimeRange(start, end))
         return trading_period
 
     def during_continuous_auction(self, time):
-        # type: (datetime.time) -> bool
+        # type: (time) -> bool
         """ 是否处于连续竞价时间段内 """
         for time_range in self.trading_hours:
             if time_range.start <= time <= time_range.end:
@@ -389,7 +381,7 @@ def trading_code(self):
 
     @cached_property
     def trade_at_night(self):
-        return any(r.start <= datetime.time(4, 0) or r.end >= datetime.time(19, 0) for r in (self.trading_hours or []))
+        return any(r.start <= time(4, 0) or r.end >= time(19, 0) for r in (self.trading_hours or []))
 
     @cached_property
     def min_order_quantity(self):
@@ -455,21 +447,21 @@ def tick_size(self):
             raise NotImplementedError
 
     @lru_cache(8)
-    def get_long_margin_ratio(self, dt: datetime.date) -> float:
+    def get_long_margin_ratio(self, dt: date) -> float:
         """
         获取多头保证金率（期货专用）
         """
         return Environment.get_instance().data_proxy.get_futures_trading_parameters(self.order_book_id, dt).long_margin_ratio
 
     @lru_cache(8)
-    def get_short_margin_ratio(self, dt: datetime.date) -> float:
+    def get_short_margin_ratio(self, dt: date) -> float:
         """
         获取空头保证金率（期货专用）
         """
         return Environment.get_instance().data_proxy.get_futures_trading_parameters(self.order_book_id, dt).short_margin_ratio
 
     def calc_cash_occupation(self, price, quantity, direction, dt):
-        # type: (float, int, POSITION_DIRECTION, datetime.date) -> float
+        # type: (float, int, POSITION_DIRECTION, date) -> float
         if self.market != MARKET.CN:
             exchagne_rate = Environment.get_instance().data_proxy.get_exchange_rate(dt, self.market)
             price = price * exchagne_rate.ask_reference
diff --git a/rqalpha/utils/arg_checker.py b/rqalpha/utils/arg_checker.py
diff --git a/rqalpha/utils/exception.py b/rqalpha/utils/exception.py
