p123api 2.2.0__tar.gz → 2.4.0__tar.gz

{p123api-2.2.0 → p123api-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: p123api
-Version: 2.2.0
+Version: 2.4.0
 Summary: Portfolio123 API wrapper
 Home-page: https://github.com/portfolio-123/p123api-py
 Author: Portfolio123

p123api-2.4.0/p123api/__init__.py

@@ -0,0 +1 @@
+from .client import Client, ClientException, ClientItemNotFoundException

{p123api-2.2.0 → p123api-2.4.0}/p123api/client.py

@@ -3,8 +3,19 @@ import requests
 import time
 import pandas
 from string import Template
-from typing import IO, Callable, List, Literal, Optional, Union
-
+from typing import IO, Callable, List, Literal, Optional, Union, overload
+from typing_extensions import deprecated
+
+from .types import (
+    DataSeriesInfoResult,
+    DataSeriesResult,
+    IdResult,
+    RankInfoResult,
+    RankingMethod,
+    StockFactorInfoResult,
+    StockFactorResult,
+    StrategyInfoResult,
+)
 
 ENDPOINT = "https://api.portfolio123.com"
 AUTH_PATH = "/auth"
@@ -13,10 +24,11 @@ SCREEN_BACKTEST_PATH = "/screen/backtest"
 SCREEN_RUN_PATH = "/screen/run"
 UNIVERSE_PATH = "/universe"
 RANK_PATH = "/rank"
-DATA_PATH = "/data"
 RANK_RANKS_PATH = "/rank/ranks"
 RANK_PERF_PATH = "/rank/performance"
 RANK_TOUCH_PATH = Template("/rank/$id/touch")
+RANK_CREATE = "/rank/create"
+DATA_PATH = "/data"
 DATA_UNIVERSE_PATH = "/data/universe"
 DATA_PRICES_PATH = Template("/data/prices/$identifier")
 STRATEGY_DETAILS_PATH = Template("/strategy/$id")
@@ -25,40 +37,54 @@ STRATEGY_TRADING_SYSTEM_PATH = Template("/strategy/$id/trading-system")
 BOOK_TRADING_SYSTEM_PATH = Template("/strategy/$id/book-trading-system")
 SIM_RERUN_PATH = Template("/strategy/$id/rerun")
 BOOK_SIM_RERUN_PATH = Template("/strategy/$id/book-rerun")
+STRATEGY_INFO_PATH = "/strategy"
 STRATEGY_REBALANCE_PATH = Template("/strategy/$id/rebalance")
 STRATEGY_REBALANCE_COMMIT_PATH = Template("/strategy/$id/rebalance/commit")
 STRATEGY_TRANS_PATH = Template("/strategy/$id/transactions")
+STRATEGY_COPY_PATH = Template("/strategy/$id/copy")
+BOOK_COPY_PATH = Template("/strategy/$id/copy-book")
 STOCK_FACTOR_UPLOAD_PATH = Template("/stockFactor/upload/$id")
 STOCK_FACTOR_CREATE_UPDATE_PATH = "/stockFactor"
 STOCK_FACTOR_DOWNLOAD_PATH = Template("/stockFactor/$id")
-STOCK_FACTOR_DELETE_PATH = STOCK_FACTOR_DOWNLOAD_PATH
+STOCK_FACTOR_DELETE_PATH = Template("/stockFactor/$id")
+STOCK_FACTOR_INFO_PATH = "/stockFactor"
 DATA_SERIES_UPLOAD_PATH = Template("/dataSeries/upload/$id")
 DATA_SERIES_CREATE_UPDATE_PATH = "/dataSeries"
+DATA_SERIES_INFO_PATH = "/dataSeries"
 DATA_SERIES_DELETE_PATH = Template("/dataSeries/$id")
 AIFACTOR_PREDICT_PATH = Template("/aiFactor/predict/$id")
 
 
 class ClientException(Exception):
-    def __init__(self, message, *, resp=None, exception=None):
+    def __init__(self, message, *, resp: Union[requests.Response, None] = None, exception: Union[Exception, None] = None):
         super().__init__(message)
         self._resp = resp
         self._exception = exception
 
-    def get_resp(self) -> requests.Response:
+    def get_resp(self):
         return self._resp
 
-    def get_cause(self) -> Exception:
+    def get_cause(self):
         return self._exception
 
+    @staticmethod
+    def build(message, resp: requests.Response):
+        if resp.status_code == 404:
+            return ClientItemNotFoundException(resp=resp)
+        return ClientException(message=message, resp=resp)
+
+
+class ClientItemNotFoundException(ClientException):
+    def __init__(self, resp: requests.Response):
+        super().__init__("Item not found", resp=resp)
+
 
 class Client:
     """
     class for interfacing with P123 API
     """
 
-    def __init__(
-        self, *, api_id, api_key, auth_extra={}, endpoint=ENDPOINT, verify_requests=True
-    ):
+    def __init__(self, *, api_id, api_key, auth_extra={}, endpoint=ENDPOINT, verify_requests=True):
         self._endpoint = endpoint
         self._verify_requests = verify_requests
         self._max_req_retries = 5
@@ -72,6 +98,7 @@ class Client:
 
         self._auth_params = {"apiId": api_id, "apiKey": api_key, **auth_extra}
         self._session = requests.Session()
+        self._method_map = {"GET": self._session.get, "POST": self._session.post, "DELETE": self._session.delete}
 
     def __enter__(self):
         return self
@@ -103,18 +130,19 @@ class Client:
         :return: bool
         """
         self._session.headers.clear()
-        resp = req_with_retry(
+        with req_with_retry(
             self._session.post,
             self._max_req_retries,
             url=self._endpoint + AUTH_PATH,
             json=self._auth_params,
             verify=self._verify_requests,
             timeout=30,
-        )
-        if resp.status_code == 200:
-            self._token = resp.text
-            self._session.headers.update({"Authorization": f"Bearer {resp.text}"})
-        else:
+        ) as resp:
+            if resp.status_code == 200:
+                self._token = resp.text
+                self._session.headers.update({"Authorization": f"Bearer {resp.text}"})
+                return
+
             if resp.status_code == 406:
                 message = "user account inactive"
             elif resp.status_code == 402:
@@ -130,79 +158,49 @@ class Client:
             raise ClientException(f"API authentication failed{message}", resp=resp)
 
     def _req_with_auth_fallback(
-        self,
-        *,
-        name: str,
-        method: str = "POST",
-        url: str,
-        json=None,
-        params=None,
-        data=None,
-        headers=None,
-        stop: bool = False,
-    ) -> Optional[requests.Response]:
+        self, *, method: Literal["GET", "POST", "DELETE"] = "POST", url: str, json=None, params=None, data=None, headers=None
+    ):
         """
         Request with authentication fallback, used by all requests (except authentication)
-        :param name: request action
         :param method: request method
         :param url: request url
         :param json: request json
         :param params: request params
         :param data: request data
         :param headers: request headers
-        :param stop: flag to stop infinite authentication recursion
         :return: request response object
         """
-        resp = None
-        if self._session.headers.get("Authorization") is not None:
-            if method == "POST":
-                resp = req_with_retry(
-                    self._session.post,
-                    self._max_req_retries,
-                    url=url,
-                    json=json,
-                    params=params,
-                    verify=self._verify_requests,
-                    timeout=self._timeout,
-                    data=data,
-                    headers=headers,
-                )
-            else:
-                req_type = (
-                    self._session.delete if method == "DELETE" else self._session.get
-                )
-                resp = req_with_retry(
-                    req_type,
-                    self._max_req_retries,
-                    url=url,
-                    json=json,
-                    params=params,
-                    verify=self._verify_requests,
-                    timeout=self._timeout,
-                    headers=headers,
-                )
-        if resp is None or resp.status_code == 401 or resp.status_code == 403:
-            if not stop:
+        reauth = False
+        while True:
+            if self._session.headers.get("Authorization") is None:
                 self.auth()
-                return self._req_with_auth_fallback(
-                    name=name,
-                    method=method,
-                    url=url,
-                    json=json,
-                    params=params,
-                    data=data,
-                    headers=headers,
-                    stop=True,
-                )
-        elif resp.status_code == 200:
-            return resp
-        else:
-            message = resp.text
-            if not message and resp.status_code == 402:
-                message = "request quota exhausted"
-            if message:
-                message = ": " + message
-            raise ClientException(f"API request failed{message}", resp=resp)
+            with req_with_retry(
+                self._method_map[method],
+                self._max_req_retries,
+                url=url,
+                json=json,
+                params=params,
+                verify=self._verify_requests,
+                timeout=self._timeout,
+                data=data,
+                headers=headers,
+            ) as resp:
+
+                if resp.status_code == 200:
+                    return resp.json()
+
+                if resp.status_code == 401 or resp.status_code == 403:
+                    del self._session.headers["Authorization"]
+                    if not reauth:
+                        reauth = True
+                        continue
+
+                message = resp.text
+                if not message and resp.status_code == 402:
+                    message = "request quota exhausted"
+                if message:
+                    message = ": " + message
+                raise ClientException.build(f"API request failed{message}", resp=resp)
 
     def screen_rolling_backtest(self, params: dict, to_pandas=False):
         """
@@ -211,11 +209,7 @@ class Client:
         :param to_pandas:
         :return:
         """
-        ret = self._req_with_auth_fallback(
-            name="screen rolling backtest",
-            url=self._endpoint + SCREEN_ROLLING_BACKTEST_PATH,
-            json=params,
-        ).json()
+        ret = self._req_with_auth_fallback(url=self._endpoint + SCREEN_ROLLING_BACKTEST_PATH, json=params)
 
         if to_pandas:
             rows = ret["rows"]
@@ -236,11 +230,7 @@ class Client:
         :param to_pandas:
         :return:
         """
-        ret = self._req_with_auth_fallback(
-            name="screen backtest",
-            url=self._endpoint + SCREEN_BACKTEST_PATH,
-            json=params,
-        ).json()
+        ret = self._req_with_auth_fallback(url=self._endpoint + SCREEN_BACKTEST_PATH, json=params)
 
         if to_pandas:
             columns = [
@@ -296,28 +286,14 @@ class Client:
             rows.append(ret["results"]["upMarkets"])
             ret["results"]["downMarkets"][0] = "Down Markets"
             rows.append(ret["results"]["downMarkets"])
-            panda_results = pandas.DataFrame(
-                data=rows, columns=ret["results"]["columns"]
-            )
+            panda_results = pandas.DataFrame(data=rows, columns=ret["results"]["columns"])
 
-            columns = [
-                "Date",
-                "Screen Return",
-                "Bench Return",
-                "Turnover %",
-                "Position Count",
-            ]
+            columns = ["Date", "Screen Return", "Bench Return", "Turnover %", "Position Count"]
             chart = ret["chart"]
             rows = []
             for idx, date in enumerate(chart["dates"]):
                 rows.append(
-                    [
-                        date,
-                        chart["screenReturns"][idx],
-                        chart["benchReturns"][idx],
-                        chart["turnoverPct"][idx],
-                        chart["positionCnt"][idx],
-                    ]
+                    [date, chart["screenReturns"][idx], chart["benchReturns"][idx], chart["turnoverPct"][idx], chart["positionCnt"][idx]]
                 )
             panda_chart = pandas.DataFrame(data=rows, columns=columns)
 
@@ -332,9 +308,7 @@ class Client:
         :param to_pandas:
         :return:
         """
-        ret = self._req_with_auth_fallback(
-            name="screen backtest", url=self._endpoint + SCREEN_RUN_PATH, json=params
-        ).json()
+        ret = self._req_with_auth_fallback(url=self._endpoint + SCREEN_RUN_PATH, json=params)
 
         if to_pandas:
             ret = pandas.DataFrame(data=ret["rows"], columns=ret["columns"])
@@ -347,9 +321,7 @@ class Client:
         :param params:
         :return:
         """
-        return self._req_with_auth_fallback(
-            name="universe update", url=self._endpoint + UNIVERSE_PATH, json=params
-        ).json()
+        return self._req_with_auth_fallback(url=self._endpoint + UNIVERSE_PATH, json=params)
 
     def rank_update(self, params: dict):
         """
@@ -357,9 +329,7 @@ class Client:
         :param params:
         :return:
         """
-        return self._req_with_auth_fallback(
-            name="ranking system update", url=self._endpoint + RANK_PATH, json=params
-        ).json()
+        return self._req_with_auth_fallback(url=self._endpoint + RANK_PATH, json=params)
 
     def data(self, params: dict, to_pandas=False):
         """
@@ -368,9 +338,7 @@ class Client:
         :param to_pandas:
         :return:
         """
-        ret = self._req_with_auth_fallback(
-            name="data", url=self._endpoint + DATA_PATH, json=params
-        ).json()
+        ret = self._req_with_auth_fallback(url=self._endpoint + DATA_PATH, json=params)
 
         if to_pandas:
             raw_obj = dict(ret)
@@ -406,9 +374,7 @@ class Client:
         :param to_pandas:
         :return:
         """
-        ret = self._req_with_auth_fallback(
-            name="data universe", url=self._endpoint + DATA_UNIVERSE_PATH, json=params
-        ).json()
+        ret = self._req_with_auth_fallback(url=self._endpoint + DATA_UNIVERSE_PATH, json=params)
 
         if to_pandas:
             raw_obj = ret
@@ -416,11 +382,7 @@ class Client:
             f_indices = range(len(params["formulas"]))
             if params.get("asOfDt"):
                 for formula_idx in f_indices:
-                    name = (
-                        names[formula_idx]
-                        if names is not None
-                        else f"formula{formula_idx + 1}"
-                    )
+                    name = names[formula_idx] if names is not None else f"formula{formula_idx + 1}"
                     ret[name] = ret["data"][formula_idx]
                 del ret["dt"], ret["cost"], ret["quotaRemaining"], ret["data"]
                 ret = pandas.DataFrame(ret)
@@ -436,9 +398,7 @@ class Client:
                     includeFigi = True
                 formulas = defaultdict(list)
                 for dtObj in ret["dates"]:
-                    data["dates"].extend(
-                        dtObj["dt"] for _ in range(len(dtObj["p123Uids"]))
-                    )
+                    data["dates"].extend(dtObj["dt"] for _ in range(len(dtObj["p123Uids"])))
                     data["p123Uids"].extend(dtObj["p123Uids"])
                     data["tickers"].extend(dtObj["tickers"])
                     if includeNames:
@@ -448,11 +408,7 @@ class Client:
                     for formula_idx in f_indices:
                         formulas[formula_idx].extend(dtObj["data"][formula_idx])
                 for formula_idx in f_indices:
-                    name = (
-                        names[formula_idx]
-                        if names is not None
-                        else f"formula{formula_idx + 1}"
-                    )
+                    name = names[formula_idx] if names is not None else f"formula{formula_idx + 1}"
                     data[name] = formulas[formula_idx]
                 ret = pandas.DataFrame(data)
             ret.attrs["raw_obj"] = raw_obj
@@ -466,11 +422,7 @@ class Client:
         :param to_pandas:
         :return:
         """
-        ret = self._req_with_auth_fallback(
-            name="ranking system ranks",
-            url=self._endpoint + RANK_RANKS_PATH,
-            json=params,
-        ).json()
+        ret = self._req_with_auth_fallback(url=self._endpoint + RANK_RANKS_PATH, json=params)
 
         if to_pandas:
             names = dict()
@@ -510,23 +462,63 @@ class Client:
         :param params:
         :return:
         """
-        return self._req_with_auth_fallback(
-            name="ranking system performance",
-            url=self._endpoint + RANK_PERF_PATH,
-            json=params,
-        ).json()
+        return self._req_with_auth_fallback(url=self._endpoint + RANK_PERF_PATH, json=params)
 
     def rank_touch(self, rank_id: int):
         """
         Rank touch
         :param rank_id:
         """
-        self._req_with_auth_fallback(
-            name="rank touch",
+        self._req_with_auth_fallback(method="POST", url=self._endpoint + RANK_TOUCH_PATH.substitute(id=rank_id))
+
+    def rank_create(
+        self,
+        name: str,
+        nodes: str,
+        *,
+        rankingMethod=RankingMethod.PERCENTILE_NA_NEGATIVE,
+        type: Literal["Stock", "ETF"] = "Stock",
+        currency="USD",
+    ) -> IdResult:
+        """
+        Creates Ranking System
+
+        :param name: Rank name
+        :param nodes: Rank nodes XML
+        :param rankingMethod: Ranking method
+        :param type: Ranking method type ["Stock", "ETF"]
+        :param currency: Ranking method currency. Example: USD
+        :return: rank_id:
+        """
+        return self._req_with_auth_fallback(
             method="POST",
-            url=self._endpoint + RANK_TOUCH_PATH.substitute(id=rank_id),
+            url=self._endpoint + RANK_CREATE,
+            json={"name": name, "nodes": nodes, "currency": currency, "type": type, "rankingMethod": rankingMethod},
         )
 
+    @overload
+    def rank_get(self, *, id: int) -> RankInfoResult: ...
+    @overload
+    def rank_get(self, *, name: str) -> RankInfoResult: ...
+    def rank_get(self, *, id: Optional[int] = None, name: Optional[str] = None) -> RankInfoResult:
+        """
+        Gets Rank info
+
+        :param id: Rank Id
+        :param name: Rank name
+        :return: RankInfoResult object containing:
+        - name (str)
+        - id (int)
+        - xml (str)
+        - currency (str)
+        - description (str)
+        - rankingMethod (int)
+        - type (Literal["Stock", "ETF"])
+        - groupUid (int)
+        - resolveGroupUid (int)
+        """
+        return self._req_with_auth_fallback(method="GET", url=self._endpoint + RANK_PATH, params={"id": id, "name": name})
+
     def strategy(self, strategy_id: int):
         """
         Strategy details
@@ -534,15 +526,35 @@ class Client:
         :return:
         """
 
+        return self._req_with_auth_fallback(method="GET", url=self._endpoint + STRATEGY_DETAILS_PATH.substitute(id=strategy_id))
+
+    def strategy_copy(self, id: int, name: str, type: Optional[Literal["PTF", "SIM"]] = None) -> IdResult:
+        """
+        Strategy copy
+
+        :param id: Strategy Id
+        :param name: name of the strategy copy
+        :param type: type of the strategy copy ("PTF"|"SIM")
+        :return: id
+        """
         return self._req_with_auth_fallback(
-            name="strategy details",
-            method="GET",
-            url=self._endpoint + STRATEGY_DETAILS_PATH.substitute(id=strategy_id),
-        ).json()
+            method="POST", url=self._endpoint + STRATEGY_COPY_PATH.substitute(id=id), json={"name": name, "type": type}
+        )
 
-    def strategy_transactions(
-        self, strategy_id: int, start: str, end: str, to_pandas=False
-    ):
+    def book_copy(self, id: int, name: str, type: Optional[Literal["BOOK", "BOOKSIM"]] = None) -> IdResult:
+        """
+        Book copy
+
+        :param book_id:
+        :param name: name of the book copy
+        :param type: type of the book copy ("BOOK"|"BOOKSIM")
+        :return: id
+        """
+        return self._req_with_auth_fallback(
+            method="POST", url=self._endpoint + BOOK_COPY_PATH.substitute(id=id), json={"name": name, "type": type}
+        )
+
+    def strategy_transactions(self, strategy_id: int, start: str, end: str, to_pandas=False):
         """
         Strategy transactions
         :param strategy_id:
@@ -552,11 +564,8 @@ class Client:
         """
 
         ret = self._req_with_auth_fallback(
-            name="strategy transactions",
-            method="GET",
-            url=self._endpoint + STRATEGY_TRANS_PATH.substitute(id=strategy_id),
-            params=[("start", start), ("end", end)],
-        ).json()
+            method="GET", url=self._endpoint + STRATEGY_TRANS_PATH.substitute(id=strategy_id), params=[("start", start), ("end", end)]
+        )
         return pandas.DataFrame(ret["trans"]) if to_pandas else ret
 
     def strategy_transaction_import(
@@ -584,18 +593,13 @@ class Client:
             get_params.append(("makeRebalDtCurr", "1"))
 
         return self._req_with_auth_fallback(
-            name="strategy transaction import",
             url=self._endpoint + STRATEGY_TRANS_PATH.substitute(id=strategy_id),
             params=get_params,
             data=data,
             headers={"Content-Type": content_type},
-        ).json()
+        )
 
-    def strategy_transaction_delete(
-        self,
-        strategy_id: int,
-        params: List[int],
-    ):
+    def strategy_transaction_delete(self, strategy_id: int, params: List[int]):
         """
         Strategy transaction delete
         :param strategy_id:
@@ -603,15 +607,10 @@ class Client:
         :return:
         """
         return self._req_with_auth_fallback(
-            name="strategy transaction delete",
-            method="DELETE",
-            url=self._endpoint + STRATEGY_TRANS_PATH.substitute(id=strategy_id),
-            json=params,
-        ).json()
+            method="DELETE", url=self._endpoint + STRATEGY_TRANS_PATH.substitute(id=strategy_id), json=params
+        )
 
-    def strategy_holdings(
-        self, strategy_id: int, date: Optional[str] = None, to_pandas=False
-    ):
+    def strategy_holdings(self, strategy_id: int, date: Optional[str] = None, to_pandas=False):
         """
         Strategy holdings
         :param strategy_id:
@@ -622,29 +621,20 @@ class Client:
         get_params = [("date", date)] if date is not None else []
 
         ret = self._req_with_auth_fallback(
-            name="strategy hldings",
-            method="GET",
-            url=self._endpoint + STRATEGY_HOLDINGS_PATH.substitute(id=strategy_id),
-            params=get_params,
-        ).json()
+            method="GET", url=self._endpoint + STRATEGY_HOLDINGS_PATH.substitute(id=strategy_id), params=get_params
+        )
 
         return pandas.DataFrame(ret["holdings"]) if to_pandas else ret
-    
-    def strategy_trading_system(
-        self, strategy_id: int
-    ):
+
+    def strategy_trading_system(self, strategy_id: int):
         """
         Strategy trading system
         :param strategy_id:
         :return:
         """
 
-        return self._req_with_auth_fallback(
-            name="strategy trading system",
-            method="GET",
-            url=self._endpoint + STRATEGY_TRADING_SYSTEM_PATH.substitute(id=strategy_id)
-        ).json()
-    
+        return self._req_with_auth_fallback(method="GET", url=self._endpoint + STRATEGY_TRADING_SYSTEM_PATH.substitute(id=strategy_id))
+
     def strategy_trading_system_update(self, strategy_id: int, params: dict):
         """
         Live strategy trading system update
@@ -653,12 +643,8 @@ class Client:
         :return:
         """
 
-        return self._req_with_auth_fallback(
-            name="live strategy trading system update",
-            url=self._endpoint + STRATEGY_TRADING_SYSTEM_PATH.substitute(id=strategy_id),
-            json=params,
-        ).json()
-    
+        return self._req_with_auth_fallback(url=self._endpoint + STRATEGY_TRADING_SYSTEM_PATH.substitute(id=strategy_id), json=params)
+
     def book_trading_system_update(self, strategy_id: int, params: dict):
         """
         Live book trading system update
@@ -667,12 +653,8 @@ class Client:
         :return:
         """
 
-        return self._req_with_auth_fallback(
-            name="live book trading system update",
-            url=self._endpoint + BOOK_TRADING_SYSTEM_PATH.substitute(id=strategy_id),
-            json=params,
-        ).json()
-    
+        return self._req_with_auth_fallback(url=self._endpoint + BOOK_TRADING_SYSTEM_PATH.substitute(id=strategy_id), json=params)
+
     def strategy_rerun(self, strategy_id: int, params: dict):
         """
         Simulated strategy rerun
@@ -681,12 +663,8 @@ class Client:
         :return:
         """
 
-        return self._req_with_auth_fallback(
-            name="simulated strategy rerun",
-            url=self._endpoint + SIM_RERUN_PATH.substitute(id=strategy_id),
-            json=params,
-        ).json()
-    
+        return self._req_with_auth_fallback(url=self._endpoint + SIM_RERUN_PATH.substitute(id=strategy_id), json=params)
+
     def book_rerun(self, strategy_id: int, params: dict):
         """
         Simulated book rerun
@@ -695,11 +673,7 @@ class Client:
         :return:
         """
 
-        return self._req_with_auth_fallback(
-            name="simulated book rerun",
-            url=self._endpoint + BOOK_SIM_RERUN_PATH.substitute(id=strategy_id),
-            json=params,
-        ).json()
+        return self._req_with_auth_fallback(url=self._endpoint + BOOK_SIM_RERUN_PATH.substitute(id=strategy_id), json=params)
 
     def strategy_rebalance(self, strategy_id: int, params: dict):
         """
@@ -709,11 +683,7 @@ class Client:
         :return:
         """
 
-        ret = self._req_with_auth_fallback(
-            name="strategy rebalance",
-            url=self._endpoint + STRATEGY_REBALANCE_PATH.substitute(id=strategy_id),
-            json=params,
-        ).json()
+        ret = self._req_with_auth_fallback(url=self._endpoint + STRATEGY_REBALANCE_PATH.substitute(id=strategy_id), json=params)
 
         return ret
 
@@ -725,12 +695,7 @@ class Client:
         :return:
         """
 
-        ret = self._req_with_auth_fallback(
-            name="strategy rebalance commit",
-            url=self._endpoint
-            + STRATEGY_REBALANCE_COMMIT_PATH.substitute(id=strategy_id),
-            json=params,
-        ).json()
+        ret = self._req_with_auth_fallback(url=self._endpoint + STRATEGY_REBALANCE_COMMIT_PATH.substitute(id=strategy_id), json=params)
 
         return ret
 
@@ -738,12 +703,12 @@ class Client:
         self,
         factor_id: int,
         data: Union[str, IO[str]],
-        column_separator: str = None,
-        existing_data: str = None,
-        date_format: str = None,
-        decimal_separator: str = None,
-        ignore_errors: bool = None,
-        ignore_duplicates: bool = None,
+        column_separator: Union[str, None] = None,
+        existing_data: Union[str, None] = None,
+        date_format: Union[str, None] = None,
+        decimal_separator: Union[str, None] = None,
+        ignore_errors: Union[bool, None] = None,
+        ignore_duplicates: Union[bool, None] = None,
     ):
         """
         Stock factor data upload
@@ -769,27 +734,18 @@ class Client:
         if ignore_errors is not None:
             get_params.append(("onError", "continue" if ignore_errors else "stop"))
         if ignore_duplicates is not None:
-            get_params.append(
-                ("onDuplicates", "continue" if ignore_duplicates else "stop")
-            )
+            get_params.append(("onDuplicates", "continue" if ignore_duplicates else "stop"))
         return self._req_with_auth_fallback(
-            name="stock factor data upload",
-            url=self._endpoint + STOCK_FACTOR_UPLOAD_PATH.substitute(id=factor_id),
-            params=get_params,
-            data=data,
-        ).json()
+            url=self._endpoint + STOCK_FACTOR_UPLOAD_PATH.substitute(id=factor_id), params=get_params, data=data
+        )
 
-    def stock_factor_create_update(self, params: dict):
+    def stock_factor_create_update(self, params: dict) -> StockFactorResult:
         """
         Stock factor create/update
         :param params:
         :return:
         """
-        return self._req_with_auth_fallback(
-            name="stock factor create/update",
-            url=self._endpoint + STOCK_FACTOR_CREATE_UPDATE_PATH,
-            json=params,
-        ).json()
+        return self._req_with_auth_fallback(url=self._endpoint + STOCK_FACTOR_CREATE_UPDATE_PATH, json=params)
 
     def stock_factor_delete(self, factor_id: int):
         """
@@ -797,27 +753,23 @@ class Client:
         :param factor_id: id of the data stock factor to delete
         :return:
         """
-        return self._req_with_auth_fallback(
-            name="stock factor delete",
-            method="DELETE",
-            url=self._endpoint + STOCK_FACTOR_DELETE_PATH.substitute(id=factor_id),
-        ).json()
+        return self._req_with_auth_fallback(url=self._endpoint + STOCK_FACTOR_DELETE_PATH.substitute(id=factor_id), method="DELETE")
 
     def data_series_upload(
         self,
         series_id: int,
         data: Union[str, IO[str]],
-        existing_data: str = None,
-        date_format: str = None,
-        decimal_separator: str = None,
-        ignore_errors: bool = None,
-        ignore_duplicates: bool = None,
-        contains_header_row: bool = None,
+        existing_data: Union[str, None] = None,
+        date_format: Union[str, None] = None,
+        decimal_separator: Union[str, None] = None,
+        ignore_errors: Union[bool, None] = None,
+        ignore_duplicates: Union[bool, None] = None,
+        contains_header_row: Union[bool, None] = None,
     ):
         """
         Data series upload
         :param series_id:
-        :param file:
+        :param data:
         :param existing_data: overwrite, skip or delete
         :param date_format: dd for day, mm for month and yyyy for year, any separator allowed (defaults to yyyy-mm-dd)
         :param decimal_separator: . or ,
@@ -836,29 +788,20 @@ class Client:
         if ignore_errors is not None:
             get_params.append(("onError", "continue" if ignore_errors else "stop"))
         if ignore_duplicates is not None:
-            get_params.append(
-                ("onDuplicates", "continue" if ignore_duplicates else "stop")
-            )
+            get_params.append(("onDuplicates", "continue" if ignore_duplicates else "stop"))
         if contains_header_row is not None:
             get_params.append(("headerRow", contains_header_row))
         return self._req_with_auth_fallback(
-            name="data series upload",
-            url=self._endpoint + DATA_SERIES_UPLOAD_PATH.substitute(id=series_id),
-            params=get_params,
-            data=data,
-        ).json()
+            url=self._endpoint + DATA_SERIES_UPLOAD_PATH.substitute(id=series_id), params=get_params, data=data
+        )
 
-    def data_series_create_update(self, params: dict):
+    def data_series_create_update(self, params: dict) -> DataSeriesResult:
         """
         Data series create/update
         :param params:
         :return:
         """
-        return self._req_with_auth_fallback(
-            name="data series create/update",
-            url=self._endpoint + DATA_SERIES_CREATE_UPDATE_PATH,
-            json=params,
-        ).json()
+        return self._req_with_auth_fallback(url=self._endpoint + DATA_SERIES_CREATE_UPDATE_PATH, json=params)
 
     def data_series_delete(self, series_id: int):
         """
@@ -866,11 +809,7 @@ class Client:
         :param series_id: id of the data series to delete
         :return:
         """
-        return self._req_with_auth_fallback(
-            name="data series delete",
-            method="DELETE",
-            url=self._endpoint + DATA_SERIES_DELETE_PATH.substitute(id=series_id),
-        ).json()
+        return self._req_with_auth_fallback(method="DELETE", url=self._endpoint + DATA_SERIES_DELETE_PATH.substitute(id=series_id))
 
     def get_api_id(self):
         return self._auth_params["apiId"]
@@ -882,11 +821,7 @@ class Client:
         :param params:
         :return:
         """
-        ret = self._req_with_auth_fallback(
-            name="AI Factor predict",
-            url=self._endpoint + AIFACTOR_PREDICT_PATH.substitute(id=predictor_id),
-            json=params,
-        ).json()
+        ret = self._req_with_auth_fallback(url=self._endpoint + AIFACTOR_PREDICT_PATH.substitute(id=predictor_id), json=params)
 
         if to_pandas:
             data = {"p123Uid": ret["p123Uids"], "ticker": ret["tickers"]}
@@ -901,16 +836,7 @@ class Client:
                     [
                         df,
                         pandas.DataFrame(ret["data"], columns=ret["features"]),
-                        *(
-                            (
-                                pandas.DataFrame(
-                                    ret["rawData"],
-                                    columns=["raw " + x for x in ret["features"]],
-                                ),
-                            )
-                            if "rawData" in ret
-                            else ()
-                        ),
+                        *((pandas.DataFrame(ret["rawData"], columns=["raw " + x for x in ret["features"]]),) if "rawData" in ret else ()),
                     ],
                     axis="columns",
                 )
@@ -920,45 +846,84 @@ class Client:
 
     def stock_factor_download(self, factor_id: int):
         """
-        Strategy details
-        :param strategy_id:
+        Stock factor download
+        :param factor_id:
         :return:
         """
-        return self._req_with_auth_fallback(
-            name="stock factor download",
-            method="GET",
-            url=self._endpoint + STOCK_FACTOR_DOWNLOAD_PATH.substitute(id=factor_id),
-        ).json()
-    
+        return self._req_with_auth_fallback(method="GET", url=self._endpoint + STOCK_FACTOR_DOWNLOAD_PATH.substitute(id=factor_id))
+
     def data_prices(self, identifier: Union[int, str], start: str, end: Optional[str], to_pandas=False):
-        """
-        """
+        """ """
         get_params = [("start", start)]
         if end is not None:
             get_params.append(("end", end))
         ret = self._req_with_auth_fallback(
-            name="download security prices",
-            method="GET",
-            url=self._endpoint + DATA_PRICES_PATH.substitute(identifier=identifier),
-            params=get_params
-        ).json()
+            method="GET", url=self._endpoint + DATA_PRICES_PATH.substitute(identifier=identifier), params=get_params
+        )
         return pandas.DataFrame(ret["prices"]) if to_pandas else ret
 
+    @overload
+    def stock_factor_info(self, *, id: int) -> StockFactorInfoResult: ...
+    @overload
+    @deprecated("use overload accepting `id` parameter instead")
+    def stock_factor_info(self, *, factor_id: int) -> StockFactorInfoResult: ...
+    @overload
+    def stock_factor_info(self, *, name: str) -> StockFactorInfoResult: ...
+    def stock_factor_info(
+        self, *, id: Optional[int] = None, factor_id: Optional[int] = None, name: Optional[str] = None
+    ) -> StockFactorInfoResult:
+        """
+        Stock factor info, only specify factor_id or name
+        """
+        if id is not None:
+            params = {"id": id}
+        elif factor_id is not None:
+            params = {"id": factor_id}
+        else:
+            params = {"name": name}
+        return self._req_with_auth_fallback(method="GET", url=self._endpoint + STOCK_FACTOR_INFO_PATH, params=params)
+
+    @overload
+    def data_series_info(self, *, id: int) -> DataSeriesInfoResult: ...
+    @overload
+    def data_series_info(self, *, name: str) -> DataSeriesInfoResult: ...
+    def data_series_info(self, *, id: Optional[int] = None, name: Optional[str] = None) -> DataSeriesInfoResult:
+        """
+        Data series info, only specify factor_id or name
+        """
+        return self._req_with_auth_fallback(
+            method="GET", url=self._endpoint + DATA_SERIES_INFO_PATH, params={"name": name} if id is None else {"id": id}
+        )
+
+    @overload
+    def strategy_info(self, *, id: int) -> StrategyInfoResult: ...
+    @overload
+    def strategy_info(self, *, name: str) -> StrategyInfoResult: ...
+    def strategy_info(self, *, id: Optional[int] = None, name: Optional[str] = None) -> StrategyInfoResult:
+        """
+        Strategy info, only specify factor_id or name
+        """
+        return self._req_with_auth_fallback(
+            method="GET", url=self._endpoint + STRATEGY_INFO_PATH, params={"name": name} if id is None else {"id": id}
+        )
 
-def req_with_retry(req: Callable[..., requests.Response], max_tries=None, **kwargs):
+
+def req_with_retry(req: Callable[..., requests.Response], max_tries=5, **kwargs):
     tries = 0
-    if max_tries is None:
-        max_tries = 5
-    resp = None
-    while tries < max_tries:
+    while True:
         if tries > 0:
             time.sleep(2 * tries)
         try:
             resp = req(**kwargs)
-            if resp.status_code < 500:
-                break
+            exception = None
         except requests.ConnectionError as e:
-            if tries + 1 == max_tries:
-                raise ClientException("Cannot connect to API", exception=e)
+            resp = None
+            exception = e
+        if resp is not None:
+            if resp.status_code < 500:
+                return resp
+            resp.close()
         tries += 1
-    return resp
+        if tries >= max_tries:
+            break
+    raise ClientException("Cannot connect to API", exception=exception)

p123api-2.4.0/p123api/types.py

@@ -0,0 +1,53 @@
+from enum import IntEnum
+from typing import Literal, Optional, TypedDict
+
+
+class SharedResult(TypedDict):
+    cost: int
+    quotaRemaining: str
+
+
+class IdResult(SharedResult):
+    id: int
+
+
+class DataSeriesResult(SharedResult):
+    dataSeriesId: int
+
+
+class DataSeriesInfoResult(DataSeriesResult):
+    name: str
+    description: str
+
+
+class StockFactorResult(SharedResult):
+    factorId: int
+
+
+class StockFactorInfoResult(StockFactorResult):
+    name: str
+    description: str
+
+
+class RankInfoResult(SharedResult):
+    name: str
+    id: int
+    xml: str
+    currency: str
+    rankingMethod: int
+    type: Literal["Stock", "ETF"]
+    description: Optional[str]
+    groupUid: int
+    resolveGroupUid: int
+
+
+class RankingMethod(IntEnum):
+    PERCENTILE_NA_NEGATIVE = 2
+    PERCENTILE_NA_NEUTRAL = 4
+    NORMAL_DISTRIBUTION = 1
+
+
+class StrategyInfoResult(TypedDict):
+    strategyId: int
+    name: str
+    description: str

{p123api-2.2.0 → p123api-2.4.0}/p123api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: p123api
-Version: 2.2.0
+Version: 2.4.0
 Summary: Portfolio123 API wrapper
 Home-page: https://github.com/portfolio-123/p123api-py
 Author: Portfolio123

{p123api-2.2.0 → p123api-2.4.0}/p123api.egg-info/SOURCES.txt

@@ -1,8 +1,10 @@
 LICENSE
 README.md
+pyproject.toml
 setup.py
 p123api/__init__.py
 p123api/client.py
+p123api/types.py
 p123api.egg-info/PKG-INFO
 p123api.egg-info/SOURCES.txt
 p123api.egg-info/dependency_links.txt

p123api-2.4.0/pyproject.toml

@@ -0,0 +1,12 @@
+[tool.black]
+line-length = 140
+skip-magic-trailing-comma = true
+
+[tool.pyright]
+pythonVersion = "3.6"
+typeCheckingMode = "basic"
+deprecateTypingAliases = true
+disableBytesTypePromotions = true
+strictDictionaryInference = true
+strictListInference = true
+strictSetInference = true

{p123api-2.2.0 → p123api-2.4.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as fh:
 
 setuptools.setup(
     name="p123api",
-    version="2.2.0",
+    version="2.4.0",
     author="Portfolio123",
     author_email="info@portfolio123.com",
     description="Portfolio123 API wrapper",
@@ -13,11 +13,7 @@ setuptools.setup(
     long_description_content_type="text/markdown",
     url="https://github.com/portfolio-123/p123api-py",
     packages=setuptools.find_packages(),
-    classifiers=[
-        "Programming Language :: Python :: 3",
-        "License :: OSI Approved :: MIT License",
-        "Operating System :: OS Independent",
-    ],
+    classifiers=["Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent"],
     python_requires=">=3.6",
     install_requires=["pandas", "requests"],
 )

p123api-2.2.0/p123api/__init__.py

@@ -1 +0,0 @@
-from .client import Client, ClientException