stock screener

Author: tigersk

setup.py

@@ -16,6 +16,8 @@
     name='tigeropen',
     version=__VERSION__,
     description='TigerBrokers Open API',
+    long_description = file: README.md
+    long_description_content_type = text/markdown
     packages=find_packages(exclude=[]),
     author='TigerBrokers',
     author_email='[email protected]',

tigeropen/common/consts/__init__.py

@@ -140,3 +140,10 @@ class IndustryLevel(Enum):
     GGROUP = 'GGROUP'
     GIND = 'GIND'
     GSUBIND = 'GSUBIND'
+
+
+@unique
+class SortDirection(Enum):
+    ASC = 'ASC'
+    DESC = 'DESC'
+

tigeropen/common/consts/fundamental_fields.py

@@ -1,10 +1,12 @@
 # -*- coding: utf-8 -*-
 
-from enum import Enum, unique
+from enum import unique
+
+from tigeropen.common.model import Field
 
 
 @unique
-class Valuation(Enum):
+class Valuation(Field):
     """
     估值指标
     tev: total enterprice value
@@ -30,7 +32,7 @@ class Valuation(Enum):
 
 
 @unique
-class Income(Enum):
+class Income(Field):
     """
     利润表
     """
@@ -187,7 +189,7 @@ class Income(Enum):
 
 
 @unique
-class Balance(Enum):
+class Balance(Field):
     """
     资产负债表
     """
@@ -316,7 +318,7 @@ class Balance(Enum):
 
 
 @unique
-class CashFlow(Enum):
+class CashFlow(Field):
     """
     现金流量表
     """
@@ -405,7 +407,7 @@ class CashFlow(Enum):
 
 
 @unique
-class BalanceSheetRatio(Enum):
+class BalanceSheetRatio(Field):
     """
     资产负债表相关比率
     """
@@ -422,7 +424,7 @@ class BalanceSheetRatio(Enum):
 
 
 @unique
-class Growth(Enum):
+class Growth(Field):
     """
     成长能力
     """
@@ -549,7 +551,7 @@ class Growth(Enum):
 
 
 @unique
-class Leverage(Enum):
+class Leverage(Field):
     """
     财务杠杆
     """
@@ -571,7 +573,7 @@ class Leverage(Enum):
 
 
 @unique
-class Profitability(Enum):
+class Profitability(Field):
     """
     盈利能力
     """
@@ -590,4 +592,3 @@ class Profitability(Enum):
     levered_free_cash_flow_margin = "levered_free_cash_flow_margin"
     unlevered_free_cash_flow_margin = "unlevered_free_cash_flow_margin"
     normalized_net_income_margin = "normalized_net_income_margin"
-

tigeropen/common/consts/service_types.py

@@ -44,6 +44,7 @@
 QUOTE_STOCK_TRADE = "quote_stock_trade"
 QUOTE_DEPTH = "quote_depth"  # level2 深度行情
 GRAB_QUOTE_PERMISSION = "grab_quote_permission"  # 抢占行情
+STOCK_SCREENER = "stock_screener"  # 选股器
 
 # 期权行情
 OPTION_EXPIRATION = "option_expiration"

tigeropen/common/model.py

@@ -2,6 +2,8 @@
 # 
 # @Date    : 2021/11/12
 # @Author  : sukai
+from enum import Enum
+
 
 class BaseParams:
     def __init__(self):
@@ -13,4 +15,8 @@ def version(self):
 
     @version.setter
     def version(self, value):
-        self._version = value
+        self._version = value
+
+
+class Field(Enum):
+    pass

tigeropen/quote/domain/filter.py

@@ -2,6 +2,8 @@
 # 
 # @Date    : 2021/11/15
 # @Author  : sukai
+from tigeropen.common.consts import SortDirection
+from tigeropen.common.model import Field
 
 GREEKS = ['delta', 'gamma', 'theta', 'vega', 'rho']
 
@@ -56,3 +58,29 @@ def _get_greeks(self):
 
     def _min_max(self, k):
         return {'min': getattr(self, k + '_min'), 'max': getattr(self, k + '_max')}
+
+
+class StockFilter:
+    def __init__(self, field, min_value=None, max_value=None, sort=None, enable=True):
+        """
+        stock filter
+        :param field: filter field. subclass of tigeropen.common.consts.Field, or field name string
+        :param min_value:
+        :param max_value:
+        :param sort: tigeropen.common.consts.SortDirection. ASC or DESC
+        :param enable:
+        """
+        self.field = field
+        self.min_value = min_value
+        self.max_value = max_value
+        self.sort = sort
+        self.enable = enable
+
+    def to_dict(self):
+        return {'field': self.field.name if isinstance(self.field, Field) else self.field,
+                'min_value': self.min_value,
+                'max_value': self.max_value,
+                'sort_direction': self.sort.value if isinstance(self.sort, SortDirection) else self.sort,
+                }
+
+

tigeropen/quote/quote_client.py

@@ -12,7 +12,7 @@
 
 from tigeropen.common.consts import Market, Language, QuoteRight, BarPeriod, OPEN_API_SERVICE_VERSION_V3
 from tigeropen.common.consts import THREAD_LOCAL, SecurityType, CorporateActionType, IndustryLevel
-from tigeropen.common.consts.service_types import GRAB_QUOTE_PERMISSION
+from tigeropen.common.consts.service_types import GRAB_QUOTE_PERMISSION, STOCK_SCREENER
 from tigeropen.common.consts.service_types import MARKET_STATE, ALL_SYMBOLS, ALL_SYMBOL_NAMES, BRIEF, \
     TIMELINE, KLINE, TRADE_TICK, OPTION_EXPIRATION, OPTION_CHAIN, FUTURE_EXCHANGE, OPTION_BRIEF, \
     OPTION_KLINE, OPTION_TRADE_TICK, FUTURE_KLINE, FUTURE_TICK, FUTURE_CONTRACT_BY_EXCHANGE_CODE, \
@@ -35,7 +35,7 @@
 from tigeropen.quote.request import OpenApiRequest
 from tigeropen.quote.request.model import MarketParams, MultipleQuoteParams, MultipleContractParams, \
     FutureQuoteParams, FutureExchangeParams, FutureTypeParams, FutureTradingTimeParams, SingleContractParams, \
-    SingleOptionQuoteParams, DepthQuoteParams, OptionChainParams
+    SingleOptionQuoteParams, DepthQuoteParams, OptionChainParams, StockScreenerParams
 from tigeropen.quote.response.future_briefs_response import FutureBriefsResponse
 from tigeropen.quote.response.future_contract_response import FutureContractResponse
 from tigeropen.quote.response.future_exchange_response import FutureExchangeResponse
@@ -54,6 +54,7 @@
 from tigeropen.quote.response.quote_grab_permission_response import QuoteGrabPermissionResponse
 from tigeropen.quote.response.quote_ticks_response import TradeTickResponse
 from tigeropen.quote.response.quote_timeline_response import QuoteTimelineResponse
+from tigeropen.quote.response.screened_stocks_response import ScreenedStocksResponse
 from tigeropen.quote.response.stock_briefs_response import StockBriefsResponse
 from tigeropen.quote.response.stock_details_response import StockDetailsResponse
 from tigeropen.quote.response.stock_short_interest_response import ShortInterestResponse
@@ -1139,6 +1140,31 @@ def get_stock_industry(self, symbol, market=Market.US):
             else:
                 raise ApiException(response.code, response.message)
 
+    def get_screened_stocks(self, market=Market.US, stock_filters=None, page=None, limit=None):
+        """
+        screen stocks
+        :param market: tigeropen.common.consts.Market
+        :param stock_filters: tigeropen.quote.domain.filter.StockFilter or list of StockFilter
+        :param page: page begin number
+        :param limit: page size limit
+        :return:
+        """
+        params = StockScreenerParams()
+        params.market = market.value
+        if stock_filters is not None:
+            params.stock_filters = stock_filters if isinstance(stock_filters, list) else [stock_filters]
+        params.page = page
+        params.limit = limit
+        request = OpenApiRequest(STOCK_SCREENER, biz_model=params)
+        response_content = self.__fetch_data(request)
+        if response_content:
+            response = ScreenedStocksResponse()
+            response.parse_response_content(response_content)
+            if response.is_success():
+                return response.stocks
+            else:
+                raise ApiException(response.code, response.message)
+
     def grab_quote_permission(self):
         """
         抢占行情权限

tigeropen/quote/request/model.py

@@ -741,3 +741,59 @@ def to_openapi_dict(self):
         if self.option_filter:
             params['option_filter'] = self.option_filter.to_dict()
         return params
+
+
+class StockScreenerParams(BaseParams):
+    def __init__(self):
+        super(StockScreenerParams, self).__init__()
+        self._market = None
+        self._stock_filters = None
+        self._page = None
+        self._limit = None
+
+    @property
+    def market(self):
+        return self._market
+
+    @market.setter
+    def market(self, value):
+        self._market = value
+
+    @property
+    def stock_filters(self):
+        return self._stock_filters
+
+    @stock_filters.setter
+    def stock_filters(self, value):
+        self._stock_filters = value
+
+    @property
+    def page(self):
+        return self._page
+
+    @page.setter
+    def page(self, value):
+        self._page = value
+
+    @property
+    def limit(self):
+        return self._limit
+
+    @limit.setter
+    def limit(self, value):
+        self._limit = value
+
+    def to_openapi_dict(self):
+        params = dict()
+        if self.market:
+            params['market'] = self.market
+        if self.stock_filters:
+            params['filters'] = list()
+            for item in self.stock_filters:
+                if item.enable:
+                    params['filters'].append(item.to_dict())
+        if self.page:
+            params['page'] = self.page
+        if self.limit:
+            params['limit'] = self.limit
+        return params

tigeropen/quote/response/screened_stocks_response.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+# 
+# @Date    : 2021/11/18
+# @Author  : sukai
+from tigeropen.common.response import TigerResponse
+
+
+class ScreenedStocksResponse(TigerResponse):
+    def __init__(self):
+        super(ScreenedStocksResponse, self).__init__()
+        self.stocks = None
+        self._is_success = None
+
+    def parse_response_content(self, response_content):
+        response = super(ScreenedStocksResponse, 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):
+            stocks = []