Merge branch 'fix_timeline_history' into 'master'

fix timeline history

See merge request server/openapi/openapi-python-sdk!256

Author: tigersk

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 3.4.7 (2025-09-23)
+### Fix
+- `QuoteClient.get_timeline_history` 解析盘前盘后分时数据问题
+### Breaking
+`QuoteClient.get_timeline` 返回的 DataFrame 中原来的 `tradingSession` 列改为 `trade_session`, 值改为 `TradingSession` 枚举值字符串
+
 ## 3.4.6 (2025-08-28)
 ### New
 - `TradeClient.get_positions` 持仓合约增加字段 `name`, `underlying_contract_name`

README.md

@@ -24,7 +24,7 @@ python setup.py install
 - 接入前需要在[开放平台](https://quant.itiger.com/#openapi)登记开发者信息
 - 详情查看[接入说明](https://quant.itiger.com/openapi/zh/python/overview/introduction.html)
 
-###### 注: 本SDK当前支持 Python3.4 及以上版本
+###### 注: 本SDK当前支持 Python3.8 及以上版本
 
 ---
 
@@ -47,14 +47,10 @@ from tigeropen.trade.trade_client import TradeClient
 
 def get_client_config():
     """
-    :return:
+    Get client config.
     """
-    is_sandbox = False
-    client_config = TigerOpenClientConfig(sandbox_debug=is_sandbox)
-    client_config.private_key = read_private_key('your private key file path')
-    client_config.tiger_id = 'your tiger id'
-    client_config.account = 'your account'
-    client_config.language = Language.en_US
+    # First, get properties config file from the developer's website, then save it to local disk, such as /Users/demo/props/
+    client_config = TigerOpenClientConfig(props_path='/Users/demo/props/')
     return client_config
 
 def get_account_info():

setup.py

@@ -31,8 +31,6 @@
         'Programming Language :: Python',
         'Operating System :: Microsoft :: Windows',
         'Operating System :: Unix',
-        'Programming Language :: Python :: 3.6',
-        'Programming Language :: Python :: 3.7',
         'Programming Language :: Python :: 3.8',
         'Programming Language :: Python :: 3.9',
         'Programming Language :: Python :: 3.10',

tests/test_quote_client.py

@@ -369,15 +369,15 @@ def test_get_timeline(self):
             self.assertIn('avg_price', result.columns)
             self.assertIn('pre_close', result.columns)
             self.assertIn('volume', result.columns)
-            self.assertIn('trading_session', result.columns)
+            self.assertIn('trade_session', result.columns)
             first_row = result.iloc[0]
             self.assertEqual(first_row['symbol'], 'AAPL')
             self.assertEqual(first_row['time'], 1754919000000)
             self.assertAlmostEqual(first_row['price'], 226.75, places=2)
             self.assertAlmostEqual(first_row['avg_price'], 227.75438, places=5)
             self.assertEqual(first_row['pre_close'], 229.09)
             self.assertEqual(first_row['volume'], 1656620)
-            self.assertEqual(first_row['trading_session'], 'regular')
+            self.assertEqual(first_row['trade_session'], 'Regular')
         else:
             result = self.client.get_timeline(symbols=['AAPL'],
                                               # trade_session=TradingSession.OverNight
@@ -417,7 +417,7 @@ def test_get_timeline_history(self):
         else:
             result = self.client.get_timeline_history(symbols=['AAPL'],
                                                       date="2025-08-21",
-                                                      # trade_session=TradingSession.OverNight
+                                                      trade_session=TradingSession.OverNight
                                                       )
             logger.debug(f"Timeline History (real):\n {result}")
 

tigeropen/__init__.py

@@ -4,4 +4,4 @@
 
 @author: gaoan
 """
-__VERSION__ = '3.4.6'
+__VERSION__ = '3.4.7'

tigeropen/examples/ai/mcp_server/tigermcp/server.py

@@ -734,7 +734,7 @@ def place_order(action: str = Field(..., description="Order action. BUY/SELL", p
     @staticmethod
     @server.tool(description="Cancel Order")
     @ApiHelper.handle_result
-    def cancel_order(id: str = Field(..., description='Order.id, like 38000878710423552')) -> Any:
+    def cancel_order(id: str = Field(..., description='Order.id, a multi digit number')) -> Any:
         """
         Cancel order
         撤销订单
@@ -786,7 +786,7 @@ def get_orders(symbol: Optional[str] = None,
     @staticmethod
     @server.tool(description="Get detailed information for a specified order.")
     @ApiHelper.handle_result
-    def get_order(id: str = Field(..., description='Order.id, a multi digit number, like 38000878710423552')) -> Any:
+    def get_order(id: str = Field(..., description='Order.id, a multi digit number')) -> Any:
         """
         Get order
         获取订单详情

tigeropen/quote/quote_client.py

@@ -86,6 +86,7 @@
 from tigeropen.quote.response.quote_grab_permission_response import QuoteGrabPermissionResponse
 from tigeropen.quote.response.quote_overnight_response import QuoteOvernightResponse
 from tigeropen.quote.response.quote_ticks_response import TradeTickResponse
+from tigeropen.quote.response.quote_timeline_history_response import QuoteTimelineHistoryResponse
 from tigeropen.quote.response.quote_timeline_response import QuoteTimelineResponse
 from tigeropen.quote.response.stock_briefs_response import StockBriefsResponse
 from tigeropen.quote.response.stock_broker_response import StockBrokerResponse
@@ -517,12 +518,15 @@ def get_timeline(self,
             - avg_price: volume weighted avg price up to now 加权均价
             - pre_close: previous close 昨日收盘价
             - volume: volume of the minute 该分钟成交量
-            - trading_session: trading session 交易时段
+            - trade_session: trading session 交易时段
 
         :return example:
-            symbol           time     price  avg_price  pre_close   volume trading_session
-        0     AAPL  1754919000000  226.7500  227.75438     229.09  1656620         regular
-        1     AAPL  1754919060000  226.6000  227.51157     229.09   426781         regular
+            symbol  pre_close trade_session           time    volume      price  avg_price
+        0     AAPL      245.5     PreMarket  1758528000000     13203  245.35000  245.70515
+        1     AAPL      245.5     PreMarket  1758528060000      2568  245.50000  245.66475
+        2     AAPL      245.5     PreMarket  1758528120000     16896  245.20000  245.47733
+        3     AAPL      245.5     PreMarket  1758528180000      8056  245.11000  245.43240
+        4     AAPL      245.5     PreMarket  1758528240000      2378  245.16000  245.41733
         """
         params = MultipleQuoteParams()
         params.symbols = self._format_to_list(symbols)
@@ -542,7 +546,7 @@ def get_timeline(self,
             response = QuoteTimelineResponse()
             response.parse_response_content(response_content)
             if response.is_success():
-                return response.timelines
+                return response.result
             else:
                 raise ApiException(response.code, response.message)
 
@@ -566,12 +570,12 @@ def get_timeline_history(
             - avg_price: volume weighted avg price up to now 加权均价
             
         Example:
-             symbol           time   volume     price  avg_price
-        0     AAPL  1698845400000   654691  171.1000  171.04840
-        1     AAPL  1698845460000   175598  170.5950  171.01788
-        2     AAPL  1698845520000   186093  170.5350  170.95750
-        3     AAPL  1698845580000   145550  170.2719  170.90828
-        4     AAPL  1698845640000   221063  170.4100  170.82759
+            symbol trade_session           time    volume      price   avg_price
+        0     NVDA       Regular  1744378200000   2734029  109.03000  108.544205
+        1     NVDA       Regular  1744378260000   1174433  108.70000  108.564995
+        2     NVDA       Regular  1744378320000   1209217  108.09000  108.557440
+        3     NVDA       Regular  1744378380000   1087583  108.42500  108.543790
+        4     NVDA       Regular  1744378440000    958574  108.43500  108.532360
         """
         params = MultipleQuoteParams()
         params.symbols = self._format_to_list(symbols)
@@ -582,7 +586,7 @@ def get_timeline_history(
         request = OpenApiRequest(HISTORY_TIMELINE, biz_model=params)
         response_content = self.__fetch_data(request)
         if response_content:
-            response = QuoteDataframeResponse()
+            response = QuoteTimelineHistoryResponse()
             response.parse_response_content(response_content)
             if response.is_success():
                 return response.result

tigeropen/quote/response/quote_timeline_history_response.py

@@ -0,0 +1,65 @@
+
+import pandas as pd
+
+from tigeropen.common.consts import TradingSession
+from tigeropen.common.response import TigerResponse
+from tigeropen.common.util.string_utils import camel_to_underline_obj, camel_to_underline
+
+FIELD_PREMARKET = 'preMarket'
+FIELD_ITEMS = 'items'
+FIELD_AFTERHOURS = 'afterHours'
+FIELD_OVERNIGHT = 'overnight'
+COLUMN_TRADE_SESSION = 'trade_session'
+
+class QuoteTimelineHistoryResponse(TigerResponse):
+    def __init__(self):
+        super(QuoteTimelineHistoryResponse, self).__init__()
+        self.result = None
+        self._is_success = None
+
+    def parse_response_content(self, response_content):
+        response = super(QuoteTimelineHistoryResponse, self).parse_response_content(response_content)
+        if 'is_success' in response:
+            self._is_success = response['is_success']
+
+        if self.data and isinstance(self.data, list):
+            timeline_items = []
+            for symbol_item in self.data:
+                symbol = symbol_item.get('symbol')
+                if FIELD_PREMARKET in symbol_item:  # 盘前
+                    pre_markets = symbol_item[FIELD_PREMARKET]
+                    if pre_markets:
+                        for item in pre_markets:
+                            item_values = self.parse_timeline(item, symbol, TradingSession.PreMarket.value)
+                            timeline_items.append(camel_to_underline_obj(item_values))
+                if FIELD_ITEMS in symbol_item:
+                    regulars = symbol_item[FIELD_ITEMS]
+                    if regulars:
+                        for item in regulars:
+                            item_values = self.parse_timeline(item, symbol,  TradingSession.Regular.value)
+                            timeline_items.append(camel_to_underline_obj(item_values))
+                if FIELD_AFTERHOURS in symbol_item:  # 盘后
+                    after_hours = symbol_item[FIELD_AFTERHOURS]
+                    if after_hours:
+                        for item in after_hours:
+                            item_values = self.parse_timeline(item, symbol, TradingSession.AfterHours.value)
+                            timeline_items.append(camel_to_underline_obj(item_values))
+                if FIELD_OVERNIGHT in symbol_item:  # 夜盘
+                    overnights = symbol_item[FIELD_OVERNIGHT]
+                    if overnights:
+                        for item in overnights:
+                            item_values = self.parse_timeline(item, symbol, TradingSession.OverNight.value)
+                            timeline_items.append(camel_to_underline_obj(item_values))
+
+            self.result = pd.DataFrame(timeline_items)
+
+    @staticmethod
+    def parse_timeline(item, symbol, trading_session):
+        item_values = {'symbol': symbol, COLUMN_TRADE_SESSION: trading_session}
+        for key, value in item.items():
+            if value is None:
+                continue
+            tag = camel_to_underline(key)
+            item_values[tag] = value
+
+        return item_values

tigeropen/quote/response/quote_timeline_response.py

@@ -7,16 +7,23 @@
 
 import pandas as pd
 
+from tigeropen.common.consts import TradingSession
 from tigeropen.common.response import TigerResponse
+from tigeropen.common.util.string_utils import camel_to_underline
 
-COLUMNS = ['symbol', 'time', 'price', 'avg_price', 'pre_close', 'volume', 'trading_session']
-TIMELINE_FIELD_MAPPINGS = {'avgPrice': 'avg_price'}
+FIELD_PREMARKET = 'preMarket'
+FIELD_ITEMS = 'items'
+FIELD_INTRADAY = 'intraday'
+FIELD_AFTERHOURS = 'afterHours'
+FIELD_OVERNIGHT = 'overnight'
+COLUMN_TRADE_SESSION = 'trade_session'
+COLUMN_PRE_CLOSE = 'pre_close'
 
 
 class QuoteTimelineResponse(TigerResponse):
     def __init__(self):
         super(QuoteTimelineResponse, self).__init__()
-        self.timelines = None
+        self.result = None
         self._is_success = None
 
     def parse_response_content(self, response_content):
@@ -29,40 +36,46 @@ def parse_response_content(self, response_content):
             for symbol_item in self.data:
                 symbol = symbol_item.get('symbol')
                 pre_close = symbol_item.get('preClose')
-                if 'preMarket' in symbol_item:  # 盘前
-                    pre_markets = symbol_item['preMarket'].get('items')
+                if FIELD_PREMARKET in symbol_item:  # 盘前
+                    pre_markets = symbol_item[FIELD_PREMARKET].get('items')
                     if pre_markets:
                         for item in pre_markets:
-                            item_values = self.parse_timeline(item, symbol, pre_close, 'pre_market')
-                            timeline_items.append([item_values.get(tag) for tag in COLUMNS])
+                            item_values = self.parse_timeline(item, symbol, pre_close, TradingSession.PreMarket.value)
+                            timeline_items.append(item_values)
 
-                if 'intraday' in symbol_item:  # 盘中
-                    regulars = symbol_item['intraday'].get('items')
-                elif 'items' in symbol_item:
-                    regulars = symbol_item['items'][0].get('items')
+                if FIELD_INTRADAY in symbol_item:  # 盘中
+                    regulars = symbol_item[FIELD_INTRADAY].get('items')
+                elif FIELD_ITEMS in symbol_item:
+                    regulars = symbol_item[FIELD_ITEMS][0].get('items')
                 else:
                     regulars = None
                 if regulars:
                     for item in regulars:
-                        item_values = self.parse_timeline(item, symbol, pre_close, 'regular')
-                        timeline_items.append([item_values.get(tag) for tag in COLUMNS])
+                        item_values = self.parse_timeline(item, symbol, pre_close, TradingSession.Regular.value)
+                        timeline_items.append(item_values)
 
-                if 'afterHours' in symbol_item:  # 盘后
-                    after_hours = symbol_item['afterHours'].get('items')
+                if FIELD_AFTERHOURS in symbol_item:  # 盘后
+                    after_hours = symbol_item[FIELD_AFTERHOURS].get('items')
                     if after_hours:
                         for item in after_hours:
-                            item_values = self.parse_timeline(item, symbol, pre_close, 'after_hours')
-                            timeline_items.append([item_values.get(tag) for tag in COLUMNS])
+                            item_values = self.parse_timeline(item, symbol, pre_close, TradingSession.AfterHours.value)
+                            timeline_items.append(item_values)
+                if FIELD_OVERNIGHT in symbol_item:  # 夜盘
+                    overnights = symbol_item[FIELD_OVERNIGHT].get('items')
+                    if overnights:
+                        for item in overnights:
+                            item_values = self.parse_timeline(item, symbol, pre_close, TradingSession.OverNight.value)
+                            timeline_items.append(item_values)
 
-            self.timelines = pd.DataFrame(timeline_items, columns=COLUMNS)
+            self.result = pd.DataFrame(timeline_items)
 
     @staticmethod
     def parse_timeline(item, symbol, pre_close, trading_session):
-        item_values = {'symbol': symbol, 'pre_close': pre_close, 'trading_session': trading_session}
+        item_values = {'symbol': symbol, COLUMN_PRE_CLOSE: pre_close, COLUMN_TRADE_SESSION: trading_session}
         for key, value in item.items():
             if value is None:
                 continue
-            tag = TIMELINE_FIELD_MAPPINGS[key] if key in TIMELINE_FIELD_MAPPINGS else key
+            tag = camel_to_underline(key)
             item_values[tag] = value
 
         return item_values

tigeropen/tiger_open_config.py

@@ -27,6 +27,7 @@
 TIGEROPEN_ACCOUNT = ENV_PREFIX + 'ACCOUNT'
 TIGEROPEN_SECRET_KEY = ENV_PREFIX + 'SECRET_KEY'
 TIGEROPEN_PRIVATE_KEY = ENV_PREFIX + 'PRIVATE_KEY'
+TIGEROPEN_LICENSE = ENV_PREFIX + 'LICENSE'
 TIGEROPEN_PROPS_PATH = ENV_PREFIX + 'PROPS_PATH'
 
 DEFAULT_DOMAIN = 'openapi.tigerfintech.com'
@@ -321,20 +322,14 @@ def _get_props_path(self, filename):
         return None
 
     def _load_env_vars(self):
-        """
-        从环境变量加载配置
-        """
-        # 读取 props_path
         if os.environ.get(TIGEROPEN_PROPS_PATH):
             self.props_path = os.environ.get(TIGEROPEN_PROPS_PATH)
 
-        # 读取核心配置
         if not self.tiger_id and os.environ.get(TIGEROPEN_TIGER_ID):
             self.tiger_id = os.environ.get(TIGEROPEN_TIGER_ID)
 
         if not self.private_key and os.environ.get(TIGEROPEN_PRIVATE_KEY):
             private_key_content = os.environ.get(TIGEROPEN_PRIVATE_KEY)
-            # 检查是否是文件路径
             if os.path.exists(private_key_content):
                 self.private_key = read_private_key(private_key_content)
             else:
@@ -346,11 +341,10 @@ def _load_env_vars(self):
         if not self.secret_key and os.environ.get(TIGEROPEN_SECRET_KEY):
             self.secret_key = os.environ.get(TIGEROPEN_SECRET_KEY)
 
+        if not self.license and os.environ.get(TIGEROPEN_LICENSE):
+            self.license = os.environ.get(TIGEROPEN_LICENSE)
+
     def _load_props(self):
-        """
-        从配置文件读取配置
-        """
-        # 从配置文件读取剩余配置或未在环境变量中指定的配置
         full_path = self._get_props_path(DEFAULT_PROPS_FILE)
         if full_path and os.path.exists(full_path):
             try: