p123api 2.4.2__tar.gz → 3.0.0a2__tar.gz

{p123api-2.4.2 → p123api-3.0.0a2}/PKG-INFO

@@ -1,18 +1,20 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: p123api
-Version: 2.4.2
+Version: 3.0.0a2
 Summary: Portfolio123 API wrapper
-Home-page: https://github.com/portfolio-123/p123api-py
-Author: Portfolio123
-Author-email: info@portfolio123.com
-License: UNKNOWN
-Platform: UNKNOWN
+Author-email: Portfolio123 <info@portfolio123.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/portfolio-123/p123api-py
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: typing_extensions
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == "pandas"
+Dynamic: license-file
 
 # Portfolio123 API Wrapper
 
@@ -25,5 +27,3 @@ with p123api.Client(api_id='your api id', api_key='your api key') as client:
     except p123api.ClientException as e:
         print(e)
 ``` 
-
-

p123api-3.0.0a2/p123api/__init__.py

@@ -0,0 +1,2 @@
+from p123api.client import Client, ClientException, ClientItemNotFoundException
+from p123api.types import IdResult, DataSeriesInfoResult, DataSeriesResult, StockFactorResult, StockFactorInfoResult, StrategyInfoResult

{p123api-2.4.2 → p123api-3.0.0a2}/p123api/client.py

@@ -1,15 +1,11 @@
-from collections import defaultdict
+from collections.abc import Callable
 import requests
 import time
-import pandas
 from string import Template
-from typing import IO, Callable, List, Literal, Optional, Union, overload
+from typing import IO, Any, Literal, overload
 from typing_extensions import deprecated
-import numpy
 
-numpy.any(32)
-
-from .types import (
+from p123api.types import (
     DataSeriesInfoResult,
     DataSeriesResult,
     IdResult,
@@ -59,16 +55,15 @@ AIFACTOR_PREDICT_PATH = Template("/aiFactor/predict/$id")
 
 
 class ClientException(Exception):
-    def __init__(self, message, *, resp: Union[requests.Response, None] = None, exception: Union[Exception, None] = None):
+    def __init__(self, message, *, resp: requests.Response | None = None):
         super().__init__(message)
         self._resp = resp
-        self._exception = exception
 
     def get_resp(self):
         return self._resp
 
     def get_cause(self):
-        return self._exception
+        return self.__cause__
 
     @staticmethod
     def build(message, resp: requests.Response):
@@ -87,19 +82,19 @@ 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: str | int, api_key: str, auth_extra={}, endpoint=ENDPOINT, verify_requests=True):
         self._endpoint = endpoint
         self._verify_requests = verify_requests
         self._max_req_retries = 5
         self._timeout = 300
         self._token = None
 
-        if not isinstance(api_id, str) or not api_id:
-            raise ClientException("api_id needs to be a non-empty str")
-        if not isinstance(api_key, str) or not api_key:
-            raise ClientException("api_key needs to be a non-empty str")
+        if not isinstance(api_id, (str, int)):
+            raise ClientException("api_id must be str or int")
+        if not isinstance(api_key, str):
+            raise ClientException("api_key must be str")
 
-        self._auth_params = {"apiId": api_id, "apiKey": api_key, **auth_extra}
+        self._auth_params = {"apiId": str(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}
 
@@ -112,12 +107,12 @@ class Client:
     def close(self):
         self._session.close()
 
-    def set_max_request_retries(self, retries):
+    def set_max_request_retries(self, retries: int):
         if not isinstance(retries, int) or retries < 1 or retries > 10:
             raise ClientException("retries needs to be an int between 1 and 10")
         self._max_req_retries = retries
 
-    def set_timeout(self, timeout):
+    def set_timeout(self, timeout: int):
         if not isinstance(timeout, int) or timeout < 1:
             raise ClientException("timeout needs to be an int greater than 0")
         self._timeout = timeout
@@ -161,7 +156,15 @@ class Client:
             raise ClientException(f"API authentication failed{message}", resp=resp)
 
     def _req_with_auth_fallback(
-        self, *, method: Literal["GET", "POST", "DELETE"] = "POST", url: str, json=None, params=None, data=None, headers=None
+        self,
+        *,
+        method: Literal["GET", "POST", "DELETE"] = "POST",
+        url: str,
+        json: Any = None,
+        params: list[tuple[str, Any]] | None = None,
+        data: str | IO | None = None,
+        headers: dict[str, str] | None = None,
+        result_type: type | None = None,
     ):
         """
         Request with authentication fallback, used by all requests (except authentication)
@@ -190,7 +193,8 @@ class Client:
             ) as resp:
 
                 if resp.status_code == 200:
-                    return resp.json()
+                    json = resp.json()
+                    return result_type(json) if result_type is not None else json
 
                 if resp.status_code == 401 or resp.status_code == 403:
                     del self._session.headers["Authorization"]
@@ -215,6 +219,8 @@ class Client:
         ret = self._req_with_auth_fallback(url=self._endpoint + SCREEN_ROLLING_BACKTEST_PATH, json=params)
 
         if to_pandas:
+            import pandas
+
             rows = ret["rows"]
             ret["average"][0] = "Average"
             rows.append(ret["average"])
@@ -236,6 +242,8 @@ class Client:
         ret = self._req_with_auth_fallback(url=self._endpoint + SCREEN_BACKTEST_PATH, json=params)
 
         if to_pandas:
+            import pandas
+
             columns = [
                 "",
                 "Total Return",
@@ -314,6 +322,8 @@ class Client:
         ret = self._req_with_auth_fallback(url=self._endpoint + SCREEN_RUN_PATH, json=params)
 
         if to_pandas:
+            import pandas
+
             ret = pandas.DataFrame(data=ret["rows"], columns=ret["columns"])
 
         return ret
@@ -344,6 +354,8 @@ class Client:
         ret = self._req_with_auth_fallback(url=self._endpoint + DATA_PATH, json=params)
 
         if to_pandas:
+            import pandas
+
             raw_obj = dict(ret)
             with_cusips = params.get("cusips") is not None
             with_name = params.get("includeNames")
@@ -380,28 +392,38 @@ class Client:
         ret = self._req_with_auth_fallback(url=self._endpoint + DATA_UNIVERSE_PATH, json=params)
 
         if to_pandas:
+            import pandas
+
             raw_obj = ret
-            names = params.get("names")
             f_indices = range(len(params["formulas"]))
+
+            names = params.get("names")
+            if names is None:
+                names = [f"formula{i + 1}" for i in f_indices]
+
             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]
                     ret[name] = ret["data"][formula_idx]
                 del ret["dt"], ret["cost"], ret["quotaRemaining"], ret["data"]
                 ret = pandas.DataFrame(ret)
             else:
+                includeNames = bool(params.get("includeNames"))
+                includeFigi = bool(params.get("figi"))
+
                 data = {"dates": [], "p123Uids": [], "tickers": []}
-                includeNames = False
-                if params.get("includeNames"):
+                if includeNames:
                     data["names"] = []
-                    includeNames = True
-                includeFigi = False
-                if params.get("figi"):
+                if includeFigi:
                     data["figi"] = []
-                    includeFigi = True
-                formulas = defaultdict(list)
+
+                date_data = [[] for _ in f_indices]
+
+                for formula_idx in f_indices:
+                    data[names[formula_idx]] = []
+
                 for dtObj in ret["dates"]:
-                    data["dates"].extend(dtObj["dt"] for _ in range(len(dtObj["p123Uids"])))
+                    data["dates"].extend([dtObj["dt"]] * len(dtObj["p123Uids"]))
                     data["p123Uids"].extend(dtObj["p123Uids"])
                     data["tickers"].extend(dtObj["tickers"])
                     if includeNames:
@@ -409,10 +431,7 @@ class Client:
                     if includeFigi:
                         data["figi"].extend(dtObj["figi"])
                     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}"
-                    data[name] = formulas[formula_idx]
+                        date_data[formula_idx].extend(dtObj["data"][formula_idx])
                 ret = pandas.DataFrame(data)
             ret.attrs["raw_obj"] = raw_obj
 
@@ -428,6 +447,8 @@ class Client:
         ret = self._req_with_auth_fallback(url=self._endpoint + RANK_RANKS_PATH, json=params)
 
         if to_pandas:
+            import pandas
+
             names = dict()
             raw_obj = dict(ret)
             del ret["cost"], ret["quotaRemaining"], ret["dt"]
@@ -577,8 +598,10 @@ class Client:
         """
         ...
 
-    def rank_get(self, *, id: Optional[int] = None, name: Optional[str] = None) -> RankInfoResult:
-        return self._req_with_auth_fallback(method="GET", url=self._endpoint + RANK_PATH, params={"id": id, "name": name})
+    def rank_get(self, *, id: int | None = None, name: str | None = None) -> RankInfoResult:
+        return self._req_with_auth_fallback(
+            method="GET", url=self._endpoint + RANK_PATH, params=[("id", id), ("name", name)], result_type=RankInfoResult
+        )
 
     def strategy(self, strategy_id: int):
         """
@@ -612,7 +635,10 @@ class Client:
             }
         """
         return self._req_with_auth_fallback(
-            method="POST", url=self._endpoint + STRATEGY_COPY_PATH.substitute(id=id), json={"name": name, "type": type}
+            method="POST",
+            url=self._endpoint + STRATEGY_COPY_PATH.substitute(id=id),
+            json={"name": name, "type": type},
+            result_type=IdResult,
         )
 
     def book_copy(self, id: int, name: str, type: Literal["BOOK", "BOOKSIM"]) -> IdResult:
@@ -638,7 +664,7 @@ class Client:
             }
         """
         return self._req_with_auth_fallback(
-            method="POST", url=self._endpoint + BOOK_COPY_PATH.substitute(id=id), json={"name": name, "type": type}
+            method="POST", url=self._endpoint + BOOK_COPY_PATH.substitute(id=id), json={"name": name, "type": type}, result_type=IdResult
         )
 
     def strategy_transactions(self, strategy_id: int, start: str, end: str, to_pandas=False):
@@ -653,12 +679,18 @@ class Client:
         ret = self._req_with_auth_fallback(
             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
+
+        if to_pandas:
+            import pandas
+
+            return pandas.DataFrame(ret["trans"])
+
+        return ret
 
     def strategy_transaction_import(
         self,
         strategy_id: int,
-        data: Union[str, IO[str]],
+        data: str | IO[str],
         content_type: Literal["text/csv", "text/tsv"] = "text/csv",
         update_existing=False,
         make_rebal_dt_curr=False,
@@ -686,7 +718,7 @@ class Client:
             headers={"Content-Type": content_type},
         )
 
-    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:
@@ -697,7 +729,7 @@ class Client:
             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: str | None = None, to_pandas=False):
         """
         Strategy holdings
         :param strategy_id:
@@ -711,7 +743,12 @@ class Client:
             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
+        if to_pandas:
+            import pandas
+
+            return pandas.DataFrame(ret["holdings"])
+
+        return ret
 
     def strategy_trading_system(self, strategy_id: int):
         """
@@ -789,39 +826,70 @@ class Client:
     def stock_factor_upload(
         self,
         factor_id: int,
-        data: Union[str, IO[str]],
-        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,
+        data: str | IO[str],
+        column_separator: Literal[",", ";", "\t"] = ",",
+        existing_data: Literal["overwrite", "skip", "delete"] = "overwrite",
+        date_format="yyyy-mm-dd",
+        decimal_separator: Literal[".", ","] = ".",
+        ignore_errors=False,
+        ignore_duplicates=False,
     ):
         """
-        Stock factor data upload
-        :param factor_id:
-        :param data:
-        :param column_separator: comma, semicolon or tab
-        :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 ,
-        :param ignore_errors:
-        :param ignore_duplicates:
-        :return:
-        """
-        get_params = []
-        if column_separator is not None:
-            get_params.append(("columnSeparator", column_separator))
-        if existing_data is not None:
-            get_params.append(("existingData", existing_data))
-        if date_format is not None:
-            get_params.append(("dateFormat", date_format))
-        if decimal_separator is not None:
-            get_params.append(("decimalSeparator", decimal_separator))
-        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"))
+        Upload stock factor data.
+
+        Uploads delimited content to the specified stock factor.
+
+        The uploaded content must contain a header row.
+        Only the first three columns are processed and must contain ``date``, ``<identifier>``, and ``value``.
+
+        ``<identifier>`` may be one of ``id`` (Portfolio123 stock ID), ``ticker`` (Portfolio123 ticker), ``gvkey``, ``cik``, or ``figi``.
+
+        The ``value`` column may specify ``na``, ``nan``, or ``null`` (case-insensitive) to clear a prior value on an observation date.
+
+        Example input::
+
+            date,ticker,value
+            2026-01-31,AAPL:USA,1.25
+            2026-01-31,MSFT:USA,0.83
+            2026-02-28,MSFT:USA,na
+
+        Note that some types of identifiers may resolve to multiple stocks.
+        For example, the FIGI ``BBG001SG1LP6`` resolves to both ``UMC:USA`` and ``UMCB:DEU``.
+
+        Identifier resolution is performed at the time of the upload. If identifier relationships ever change or coverage expands,
+        the stock factor data will still reflect the original resolution.
+
+        Args:
+            factor_id: Unique identifier of the stock factor.
+            data: Delimited content string or file-like containing delimited content. Must not exceed 100 MB or 5 million lines.
+            column_separator: Separator character between columns. Defaults to comma.
+            existing_data: Policy for dealing with collisions against stored (date, stock ID) pairs. Defaults to ``overwrite``.
+                - ``overwrite``: Overwrite stored values.
+                - ``skip``: Retaine stored values.
+                - ``delete``: Clear before storing uploaded data.
+            date_format: Date format. Defaults to ``yyyy-mm-dd``.
+            decimal_separator: Decimal separator. Defaults to period. If comma is used, the thousands separator, if used, is assumed to be period.
+            ignore_errors: If ``True``, lines in the data with errors will be silently discarded.
+            ignore_duplicates: If ``True``, additional occurrences of a (date, identifier) pair in the data are skipped.
+        """
+
+        # COMPAT: column_separator originally accepted 'comma', 'semicolon', 'tab' which matches the API.
+        actual_column_separator: str = column_separator
+        if column_separator == ",":
+            actual_column_separator = "comma"
+        elif column_separator == ";":
+            actual_column_separator = "semicolon"
+        elif column_separator == "\t":
+            actual_column_separator = "tab"
+
+        get_params = [
+            ("columnSeparator", actual_column_separator),
+            ("existingData", existing_data),
+            ("dateFormat", date_format),
+            ("decimalSeparator", decimal_separator),
+            ("onError", "continue" if ignore_errors else "stop"),
+            ("onDuplicates", "continue" if ignore_duplicates else "stop"),
+        ]
         return self._req_with_auth_fallback(
             url=self._endpoint + STOCK_FACTOR_UPLOAD_PATH.substitute(id=factor_id), params=get_params, data=data
         )
@@ -832,7 +900,9 @@ class Client:
         :param params:
         :return:
         """
-        return self._req_with_auth_fallback(url=self._endpoint + STOCK_FACTOR_CREATE_UPDATE_PATH, json=params)
+        return self._req_with_auth_fallback(
+            url=self._endpoint + STOCK_FACTOR_CREATE_UPDATE_PATH, json=params, result_type=StockFactorResult
+        )
 
     def stock_factor_delete(self, factor_id: int):
         """
@@ -845,39 +915,51 @@ class Client:
     def data_series_upload(
         self,
         series_id: int,
-        data: Union[str, IO[str]],
-        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: str | IO[str],
+        existing_data: Literal["overwrite", "skip", "delete"] = "overwrite",
+        date_format="yyyy-mm-dd",
+        decimal_separator: Literal[".", ","] = ".",
+        ignore_errors=False,
+        ignore_duplicates=False,
+        contains_header_row=True,
     ):
         """
-        Data series upload
-        :param series_id:
-        :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 ,
-        :param ignore_errors:
-        :param ignore_duplicates:
-        :param contains_header_row:
-        :return:
-        """
-        get_params = []
-        if existing_data is not None:
-            get_params.append(("existingData", existing_data))
-        if date_format is not None:
-            get_params.append(("dateFormat", date_format))
-        if decimal_separator is not None:
-            get_params.append(("decimalSeparator", decimal_separator))
-        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"))
-        if contains_header_row is not None:
-            get_params.append(("headerRow", contains_header_row))
+        Upload data series data.
+
+        Uploads delimited content to the specified data series.
+
+        The data must contain dates in the first column and values in the second column.
+        If the data includes a header row, the names are not processed.
+
+        The ``value`` column may specify ``na``, ``nan``, or ``null`` (case-insensitive) to clear a prior value on an observation date.
+
+        Example input::
+
+            date,value
+            2026-01-31,1.25
+            2026-02-28,na
+
+        Args:
+            series_id: Unique identifier of the data series.
+            data: Delimited content string or file-like containing delimited content. Must not exceed 100 MB.
+            existing_data: Policy for dealing with collisions against stored dates. Defaults to ``overwrite``.
+                - ``overwrite``: Overwrite stored values.
+                - ``skip``: Retaine stored values.
+                - ``delete``: Clear before storing uploaded data.
+            date_format: Date format. Defaults to ``yyyy-mm-dd``.
+            decimal_separator: Decimal separator. Defaults to period. If comma is used, the thousands separator, if used, is assumed to be period.
+            ignore_errors: If ``True``, lines in the data with errors will be silently discarded.
+            ignore_duplicates: If ``True``, additional occurrences of a date in the data are skipped.
+            contains_header_row: If ``True``, the first line of the uploaded data will be skipped.
+        """
+        get_params = [
+            ("existingData", existing_data),
+            ("dateFormat", date_format),
+            ("decimalSeparator", decimal_separator),
+            ("onError", "continue" if ignore_errors else "stop"),
+            ("onDuplicates", "continue" if ignore_duplicates else "stop"),
+            ("headerRow", contains_header_row),
+        ]
         return self._req_with_auth_fallback(
             url=self._endpoint + DATA_SERIES_UPLOAD_PATH.substitute(id=series_id), params=get_params, data=data
         )
@@ -888,7 +970,7 @@ class Client:
         :param params:
         :return:
         """
-        return self._req_with_auth_fallback(url=self._endpoint + DATA_SERIES_CREATE_UPDATE_PATH, json=params)
+        return self._req_with_auth_fallback(url=self._endpoint + DATA_SERIES_CREATE_UPDATE_PATH, json=params, result_type=DataSeriesResult)
 
     def data_series_delete(self, series_id: int):
         """
@@ -911,6 +993,8 @@ class Client:
         ret = self._req_with_auth_fallback(url=self._endpoint + AIFACTOR_PREDICT_PATH.substitute(id=predictor_id), json=params)
 
         if to_pandas:
+            import pandas
+
             data = {"p123Uid": ret["p123Uids"], "ticker": ret["tickers"]}
             if "names" in ret:
                 data["name"] = ret["names"]
@@ -939,7 +1023,7 @@ class Client:
         """
         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):
+    def data_prices(self, identifier: int | str, start: str, end: str | None, to_pandas=False):
         """ """
         get_params = [("start", start)]
         if end is not None:
@@ -947,7 +1031,13 @@ class Client:
         ret = self._req_with_auth_fallback(
             method="GET", url=self._endpoint + DATA_PRICES_PATH.substitute(identifier=identifier), params=get_params
         )
-        return pandas.DataFrame(ret["prices"]) if to_pandas else ret
+
+        if to_pandas:
+            import pandas
+
+            return pandas.DataFrame(ret["prices"])
+
+        return ret
 
     @overload
     def stock_factor_info(self, *, id: int) -> StockFactorInfoResult:
@@ -963,9 +1053,9 @@ class Client:
         Examples:
             >>> client.stock_factor_info(id=123)
             {
-                factorId: 123,
-                name: 'Stock factor name',
-                description: 'Stock factor description'
+                'factorId': 123,
+                'name': 'Stock factor name',
+                'description': 'Stock factor description'
             }
         """
         ...
@@ -984,9 +1074,9 @@ class Client:
         Examples:
             >>> client.stock_factor_info(name='Stock factor name')
             {
-                factorId: 123,
-                name: 'Stock factor name',
-                description: 'Stock factor description'
+                'factorId': 123,
+                'name': 'Stock factor name',
+                'description': 'Stock factor description'
             }
         """
         ...
@@ -1009,23 +1099,23 @@ class Client:
         Examples:
             >>> client.stock_factor_info(factor_id=123)
             {
-                factorId: 123,
-                name: 'Stock factor name',
-                description: 'Stock factor description'
+                'factorId': 123,
+                'name': 'Stock factor name',
+                'description': 'Stock factor description'
             }
         """
         ...
 
-    def stock_factor_info(
-        self, *, id: Optional[int] = None, factor_id: Optional[int] = None, name: Optional[str] = None
-    ) -> StockFactorInfoResult:
+    def stock_factor_info(self, *, id: int | None = None, factor_id: int | None = None, name: str | None = None) -> StockFactorInfoResult:
         if id is not None:
-            params = {"id": id}
+            params = [("id", id)]
         elif factor_id is not None:
-            params = {"id": factor_id}
+            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)
+            params = [("name", name)]
+        return self._req_with_auth_fallback(
+            method="GET", url=self._endpoint + STOCK_FACTOR_INFO_PATH, params=params, result_type=StockFactorInfoResult
+        )
 
     @overload
     def data_series_info(self, *, id: int) -> DataSeriesInfoResult:
@@ -1041,9 +1131,9 @@ class Client:
         Examples:
             >>> client.data_series_info(id=123)
             {
-                dataSeriesId: 123,
-                name: 'Data series name',
-                description: 'Data series description'
+                'dataSeriesId': 123,
+                'name': 'Data series name',
+                'description': 'Data series description'
             }
         """
         ...
@@ -1062,16 +1152,19 @@ class Client:
         Examples:
             >>> client.data_series_info(name='Data series name')
             {
-                dataSeriesId: 123,
-                name: 'Data series name',
-                description: 'Data series description'
+                'dataSeriesId': 123,
+                'name': 'Data series name',
+                'description': 'Data series description'
             }
         """
         ...
 
-    def data_series_info(self, *, id: Optional[int] = None, name: Optional[str] = None) -> DataSeriesInfoResult:
+    def data_series_info(self, *, id: int | None = None, name: str | None = None) -> DataSeriesInfoResult:
         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}
+            method="GET",
+            url=self._endpoint + DATA_SERIES_INFO_PATH,
+            params=[("name", name)] if id is None else [("id", id)],
+            result_type=DataSeriesInfoResult,
         )
 
     @overload
@@ -1088,9 +1181,9 @@ class Client:
         Examples:
             >>> client.strategy_info(id=123)
             {
-                strategyId: 123,
-                name: 'Strategy name',
-                description: 'Strategy description'
+                'strategyId': 123,
+                'name': 'Strategy name',
+                'description': 'Strategy description'
             }
         """
         ...
@@ -1109,16 +1202,19 @@ class Client:
         Examples:
             >>> client.strategy_info(name='Strategy name')
             {
-                strategyId: 123,
-                name: 'Strategy name',
-                description: 'Strategy description'
+                'strategyId': 123,
+                'name': 'Strategy name',
+                'description': 'Strategy description'
             }
         """
         ...
 
-    def strategy_info(self, *, id: Optional[int] = None, name: Optional[str] = None) -> StrategyInfoResult:
+    def strategy_info(self, *, id: int | None = None, name: str | None = None) -> StrategyInfoResult:
         return self._req_with_auth_fallback(
-            method="GET", url=self._endpoint + STRATEGY_INFO_PATH, params={"name": name} if id is None else {"id": id}
+            method="GET",
+            url=self._endpoint + STRATEGY_INFO_PATH,
+            params=[("name", name)] if id is None else [("id", id)],
+            result_type=StrategyInfoResult,
         )
 
 
@@ -1140,4 +1236,4 @@ def req_with_retry(req: Callable[..., requests.Response], max_tries=5, **kwargs)
         tries += 1
         if tries >= max_tries:
             break
-    raise ClientException("Cannot connect to API", exception=exception)
+    raise ClientException("Cannot connect to API") from exception

p123api-3.0.0a2/p123api/types.py

@@ -0,0 +1,110 @@
+from enum import Enum, IntEnum
+import inspect
+import typing
+from typing import Literal
+
+
+def _create_fn(name, args, body, globals_dict=None):
+    """Executes a string of code to build a highly optimized function."""
+    args_str = ", ".join(args)
+    body_str = "\n        ".join(body)
+
+    txt = f"""
+def __builder__():
+    def {name}({args_str}):
+        {body_str}
+    return {name}
+"""
+    namespace = {}
+    exec(txt, globals_dict or {}, namespace)
+    return namespace["__builder__"]()
+
+
+def _slow_init(self, d: dict):
+    cls = type(self)
+    annotations = typing.get_type_hints(cls)
+
+    globals_dict = {}
+    for hint in annotations.values():
+        if inspect.isclass(hint) and issubclass(hint, Enum):
+            globals_dict[hint.__name__] = hint
+
+    init_args = ["self", "d"]
+    init_body = []
+
+    for key, expected_type in annotations.items():
+        if inspect.isclass(expected_type) and issubclass(expected_type, Enum):
+            init_body.append(f"self.{key} = {expected_type.__name__}(v) if (v := d.get({key!r})) is not None else None")
+        else:
+            init_body.append(f"self.{key} = d.get({key!r})")
+
+    init = cls.__init__ = _create_fn("__init__", init_args, init_body, globals_dict)
+    init(self, d)
+
+
+def _slow_repr(self):
+    cls = type(self)
+    annotations = typing.get_type_hints(cls)
+
+    repr = cls.__repr__ = _create_fn(
+        "__repr__", ["self"], [f"return f'{cls.__name__}({', '.join(f'{k}={{self.{k}!r}}' for k in annotations)})'"]
+    )
+    return repr(self)
+
+
+def api_result(cls):
+    cls.__init__ = _slow_init
+    cls.__repr__ = _slow_repr
+    return cls
+
+
+@api_result
+class IdResult:
+    id: int
+
+
+@api_result
+class DataSeriesResult:
+    dataSeriesId: int
+
+
+@api_result
+class DataSeriesInfoResult:
+    dataSeriesId: int
+    name: str
+
+
+@api_result
+class StockFactorResult:
+    factorId: int
+
+
+@api_result
+class StockFactorInfoResult:
+    factorId: int
+    name: str
+
+
+class RankingMethod(IntEnum):
+    PERCENTILE_NA_NEGATIVE = 2
+    PERCENTILE_NA_NEUTRAL = 4
+    NORMAL_DISTRIBUTION = 1
+
+
+@api_result
+class RankInfoResult:
+    name: str
+    id: int
+    xml: str
+    currency: str
+    rankingMethod: RankingMethod
+    type: Literal["Stock", "ETF"]
+    description: str | None
+    groupUid: int
+    resolveGroupUid: int
+
+
+@api_result
+class StrategyInfoResult:
+    strategyId: int
+    name: str

{p123api-2.4.2 → p123api-3.0.0a2}/p123api.egg-info/PKG-INFO

@@ -1,18 +1,20 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: p123api
-Version: 2.4.2
+Version: 3.0.0a2
 Summary: Portfolio123 API wrapper
-Home-page: https://github.com/portfolio-123/p123api-py
-Author: Portfolio123
-Author-email: info@portfolio123.com
-License: UNKNOWN
-Platform: UNKNOWN
+Author-email: Portfolio123 <info@portfolio123.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/portfolio-123/p123api-py
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: typing_extensions
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == "pandas"
+Dynamic: license-file
 
 # Portfolio123 API Wrapper
 
@@ -25,5 +27,3 @@ with p123api.Client(api_id='your api id', api_key='your api key') as client:
     except p123api.ClientException as e:
         print(e)
 ``` 
-
-

{p123api-2.4.2 → p123api-3.0.0a2}/p123api.egg-info/SOURCES.txt

@@ -1,7 +1,6 @@
 LICENSE
 README.md
 pyproject.toml
-setup.py
 p123api/__init__.py
 p123api/client.py
 p123api/types.py

p123api-3.0.0a2/p123api.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests
+typing_extensions
+
+[pandas]
+pandas

p123api-3.0.0a2/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "p123api"
+version = "3.0.0a2"
+description = "Portfolio123 API wrapper"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    {name = "Portfolio123", email = "info@portfolio123.com"}
+]
+
+dependencies = [
+    "requests",
+    "typing_extensions",
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+pandas = [
+    "pandas",
+]
+
+[project.urls]
+Homepage = "https://github.com/portfolio-123/p123api-py"
+
+[tool.setuptools.packages.find]
+include = ["p123api*"]
+
+[tool.black]
+line-length = 140
+skip-magic-trailing-comma = true
+
+[tool.pyright]
+pythonVersion = "3.10"
+typeCheckingMode = "basic"
+deprecateTypingAliases = true
+disableBytesTypePromotions = true
+strictDictionaryInference = true
+strictListInference = true
+strictSetInference = true

p123api-2.4.2/p123api/__init__.py

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

p123api-2.4.2/p123api/types.py

@@ -1,53 +0,0 @@
-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(SharedResult):
-    strategyId: int
-    name: str
-    description: str

p123api-2.4.2/p123api.egg-info/requires.txt

@@ -1,2 +0,0 @@
-pandas
-requests

p123api-2.4.2/pyproject.toml

@@ -1,12 +0,0 @@
-[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.4.2/setup.py

@@ -1,19 +0,0 @@
-import setuptools
-
-with open("README.md", "r") as fh:
-    long_description = fh.read()
-
-setuptools.setup(
-    name="p123api",
-    version="2.4.2",
-    author="Portfolio123",
-    author_email="info@portfolio123.com",
-    description="Portfolio123 API wrapper",
-    long_description=long_description,
-    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"],
-    python_requires=">=3.6",
-    install_requires=["pandas", "requests"],
-)