Add IPOs support (#816)

Author: justinpolygon

examples/rest/stocks-ipos.py

@@ -0,0 +1,13 @@
+from polygon import RESTClient
+
+# docs
+# https://polygon.io/docs/stocks/get_vx_reference_ipos
+
+# client = RESTClient("XXXXXX") # hardcoded api_key is used
+client = RESTClient()  # POLYGON_API_KEY environment variable is used
+
+ipos = []
+for ipo in client.vx.list_ipos(ticker="RDDT"):
+    ipos.append(ipo)
+
+print(ipos)

polygon/rest/models/tickers.py

@@ -253,3 +253,60 @@ class TickerChangeResults:
     @staticmethod
     def from_dict(d):
         return TickerChangeResults(**d)
+
+
+from typing import Optional
+from ...modelclass import modelclass
+
+
+@modelclass
+class IPOListing:
+    """
+    IPO Listing data as returned by the /vX/reference/ipos endpoint.
+    """
+
+    announced_date: Optional[str] = None
+    currency_code: Optional[str] = None
+    final_issue_price: Optional[float] = None
+    highest_offer_price: Optional[float] = None
+    ipo_status: Optional[str] = None
+    isin: Optional[str] = None
+    issuer_name: Optional[str] = None
+    last_updated: Optional[str] = None
+    listing_date: Optional[str] = None
+    lot_size: Optional[int] = None
+    lowest_offer_price: Optional[float] = None
+    max_shares_offered: Optional[int] = None
+    min_shares_offered: Optional[int] = None
+    primary_exchange: Optional[str] = None
+    security_description: Optional[str] = None
+    security_type: Optional[str] = None
+    shares_outstanding: Optional[int] = None
+    ticker: Optional[str] = None
+    total_offer_size: Optional[float] = None
+    us_code: Optional[str] = None
+
+    @staticmethod
+    def from_dict(d):
+        return IPOListing(
+            announced_date=d.get("announced_date"),
+            currency_code=d.get("currency_code"),
+            final_issue_price=d.get("final_issue_price"),
+            highest_offer_price=d.get("highest_offer_price"),
+            ipo_status=d.get("ipo_status"),
+            isin=d.get("isin"),
+            issuer_name=d.get("issuer_name"),
+            last_updated=d.get("last_updated"),
+            listing_date=d.get("listing_date"),
+            lot_size=d.get("lot_size"),
+            lowest_offer_price=d.get("lowest_offer_price"),
+            max_shares_offered=d.get("max_shares_offered"),
+            min_shares_offered=d.get("min_shares_offered"),
+            primary_exchange=d.get("primary_exchange"),
+            security_description=d.get("security_description"),
+            security_type=d.get("security_type"),
+            shares_outstanding=d.get("shares_outstanding"),
+            ticker=d.get("ticker"),
+            total_offer_size=d.get("total_offer_size"),
+            us_code=d.get("us_code"),
+        )

polygon/rest/vX.py

@@ -1,6 +1,6 @@
 from .base import BaseClient
-from typing import Optional, Any, Dict, Union, Iterator
-from .models import StockFinancial, Timeframe, Sort, Order
+from typing import Optional, Any, Dict, List, Union, Iterator
+from .models import StockFinancial, IPOListing, Timeframe, Sort, Order
 from urllib3 import HTTPResponse
 from datetime import datetime, date
 
@@ -70,3 +70,44 @@ def list_stock_financials(
             deserializer=StockFinancial.from_dict,
             options=options,
         )
+
+    def list_ipos(
+        self,
+        ticker: Optional[str] = None,
+        us_code: Optional[str] = None,
+        isin: Optional[str] = None,
+        listing_date: Optional[str] = None,
+        ipo_status: Optional[str] = None,
+        limit: Optional[int] = None,
+        sort: Optional[Union[str, Sort]] = None,
+        order: Optional[Union[str, Order]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        raw: bool = False,
+        options: Optional[RequestOptionBuilder] = None,
+    ) -> Union[List[IPOListing], HTTPResponse]:
+        """
+        Retrieve upcoming or historical IPOs.
+
+        :param ticker: Filter by a case-sensitive ticker symbol.
+        :param us_code: Filter by a US code (unique identifier for a North American financial security).
+        :param isin: Filter by an International Securities Identification Number (ISIN).
+        :param listing_date: Filter by the listing date (YYYY-MM-DD).
+        :param ipo_status: Filter by IPO status (e.g. "new", "pending", "history", etc.).
+        :param limit: Limit the number of results per page. Default 10, max 1000.
+        :param sort: Field to sort by. Default is "listing_date".
+        :param order: Order results based on the sort field ("asc" or "desc"). Default "desc".
+        :param params: Additional query params.
+        :param raw: Return raw HTTPResponse object if True, else return List[IPOListing].
+        :param options: RequestOptionBuilder for additional headers or params.
+        :return: A list of IPOListing objects or HTTPResponse if raw=True.
+        """
+        url = "/vX/reference/ipos"
+
+        return self._paginate(
+            path=url,
+            params=self._get_params(self.list_ipos, locals()),
+            deserializer=IPOListing.from_dict,
+            raw=raw,
+            result_key="results",
+            options=options,
+        )