firstrade 0.0.20__py3-none-any.whl → 0.0.30__py3-none-any.whl

firstrade/order.py

@@ -1,15 +1,20 @@
 from enum import Enum
 
-from bs4 import BeautifulSoup
-
 from firstrade import urls
 from firstrade.account import FTSession
 
 
 class PriceType(str, Enum):
     """
-    This is an :class: 'enum.Enum'
-    that contains the valid price types for an order.
+    Enum for valid price types in an order.
+
+    Attributes:
+        MARKET (str): Market order, executed at the current market price.
+        LIMIT (str): Limit order, executed at a specified price or better.
+        STOP (str): Stop order, becomes a market order once a specified price is reached.
+        STOP_LIMIT (str): Stop-limit order, becomes a limit order once a specified price is reached.
+        TRAILING_STOP_DOLLAR (str): Trailing stop order with a specified dollar amount.
+        TRAILING_STOP_PERCENT (str): Trailing stop order with a specified percentage.
     """
 
     LIMIT = "2"
@@ -22,8 +27,14 @@ class PriceType(str, Enum):
 
 class Duration(str, Enum):
     """
-    This is an :class:'~enum.Enum'
-    that contains the valid durations for an order.
+    Enum for valid order durations.
+
+    Attributes:
+        DAY (str): Day order.
+        GT90 (str): Good till 90 days order.
+        PRE_MARKET (str): Pre-market order.
+        AFTER_MARKET (str): After-market order.
+        DAY_EXT (str): Day extended order.
     """
 
     DAY = "0"
@@ -35,220 +46,202 @@ class Duration(str, Enum):
 
 class OrderType(str, Enum):
     """
-    This is an :class:'~enum.Enum'
-    that contains the valid order types for an order.
+    Enum for valid order types.
+
+    Attributes:
+        BUY (str): Buy order.
+        SELL (str): Sell order.
+        SELL_SHORT (str): Sell short order.
+        BUY_TO_COVER (str): Buy to cover order.
+        BUY_OPTION (str): Buy option order.
+        SELL_OPTION (str): Sell option order.
     """
 
     BUY = "B"
     SELL = "S"
     SELL_SHORT = "SS"
     BUY_TO_COVER = "BC"
+    BUY_OPTION = "BO"
+    SELL_OPTION = "SO"
+
+
+class OrderInstructions(str, Enum):
+    """
+    Enum for valid order instructions.
+
+    Attributes:
+        AON (str): All or none.
+        OPG (str): At the Open.
+        CLO (str): At the Close.
+    """
+
+    AON = "1"
+    OPG = "4"
+    CLO = "5"
+
+
+class OptionType(str, Enum):
+    """
+    Enum for valid option types.
+
+    Attributes:
+        CALL (str): Call option.
+        PUT (str): Put option.
+    """
+
+    CALL = "C"
+    PUT = "P"
 
 
 class Order:
     """
-    This class contains information about an order.
-    It also contains a method to place an order.
+    Represents an order with methods to place it.
+
+    Attributes:
+        ft_session (FTSession): The session object for placing orders.
     """
 
     def __init__(self, ft_session: FTSession):
         self.ft_session = ft_session
-        self.order_confirmation = {}
 
     def place_order(
         self,
-        account,
-        symbol,
+        account: str,
+        symbol: str,
         price_type: PriceType,
         order_type: OrderType,
-        quantity,
         duration: Duration,
-        price=0.00,
-        dry_run=True,
-        notional=False,
+        quantity: int = 0,
+        price: float = 0.00,
+        stop_price: float = None,
+        dry_run: bool = True,
+        notional: bool = False,
+        order_instruction: OrderInstructions = "0",
     ):
         """
         Builds and places an order.
-        :attr: 'order_confirmation`
-        contains the order confirmation data after order placement.
 
         Args:
-            account (str): Account number of the account to place the order in.
-            symbol (str): Ticker to place the order for.
-            order_type (PriceType): Price Type i.e. LIMIT, MARKET, STOP, etc.
-            quantity (float): The number of shares to buy.
-            duration (Duration): Duration of the order i.e. DAY, GT90, etc.
-            price (float, optional): The price to buy the shares at. Defaults to 0.00.
-            dry_run (bool, optional): Whether you want the order to be placed or not.
-                                      Defaults to True.
+            account (str): The account number to place the order in.
+            symbol (str): The ticker symbol for the order.
+            price_type (PriceType): The price type for the order (e.g., LIMIT, MARKET, STOP).
+            order_type (OrderType): The type of order (e.g., BUY, SELL).
+            duration (Duration): The duration of the order (e.g., DAY, GT90).
+            quantity (int, optional): The number of shares to buy or sell. Defaults to 0.
+            price (float, optional): The price at which to buy or sell the shares. Defaults to 0.00.
+            stop_price (float, optional): The stop price for stop orders. Defaults to None.
+            dry_run (bool, optional): If True, the order will not be placed but will be built and validated. Defaults to True.
+            notional (bool, optional): If True, the order will be placed based on a notional dollar amount rather than share quantity. Defaults to False.
+            order_instruction (OrderInstructions, optional): Additional order instructions (e.g., AON, OPG). Defaults to "0".
+
+        Raises:
+            ValueError: If AON orders are not limit orders or if AON orders have a quantity of 100 shares or less.
+            PreviewOrderError: If the order preview fails.
+            PlaceOrderError: If the order placement fails.
 
         Returns:
-            Order:order_confirmation: Dictionary containing the order confirmation data.
+            dict: A dictionary containing the order confirmation data.
         """
 
-        if price_type == PriceType.MARKET:
+        if price_type == PriceType.MARKET and not notional:
             price = ""
-
+        if order_instruction == OrderInstructions.AON and price_type != PriceType.LIMIT:
+            raise ValueError("AON orders must be a limit order.")
+        if order_instruction == OrderInstructions.AON and quantity <= 100:
+            raise ValueError("AON orders must be greater than 100 shares.")
+ 
         data = {
-            "submiturl": "/cgi-bin/orderbar",
-            "orderbar_clordid": "",
-            "orderbar_accountid": "",
-            "notional": "yes" if notional else "",
-            "stockorderpage": "yes",
-            "submitOrders": "",
-            "previewOrders": "1",
-            "lotMethod": "1",
-            "accountType": "1",
-            "quoteprice": "",
-            "viewederror": "",
-            "stocksubmittedcompanyname1": "",
-            "accountId": account,
-            "transactionType": order_type,
-            "quantity": quantity,
             "symbol": symbol,
-            "priceType": price_type,
-            "limitPrice": price,
+            "transaction": order_type,
+            "shares": quantity,
             "duration": duration,
-            "qualifier": "0",
-            "cond_symbol0_0": "",
-            "cond_type0_0": "2",
-            "cond_compare_type0_0": "2",
-            "cond_compare_value0_0": "",
-            "cond_and_or0": "1",
-            "cond_symbol0_1": "",
-            "cond_type0_1": "2",
-            "cond_compare_type0_1": "2",
-            "cond_compare_value0_1": "",
+            "preview": "true",
+            "instructions": order_instruction,
+            "account": account,
+            "price_type": price_type,
+            "limit_price": "0",
         }
+        if notional:
+            data["dollar_amount"] = price
+            del data["shares"]
+        if price_type in [PriceType.LIMIT, PriceType.STOP_LIMIT]:
+            data["limit_price"] = price
+        if price_type in [PriceType.STOP, PriceType.STOP_LIMIT]:
+            data["stop_price"] = stop_price
+        response = self.ft_session.post(url=urls.order(), data=data)
+        if response.status_code != 200 or response.json()["error"] != "":
+            return response.json()
+        preview_data = response.json()
+        if dry_run:
+            return preview_data
+        data["preview"] = "false"
+        data["stage"] = "P"
+        response = self.ft_session.post(url=urls.order(), data=data)
+        return response.json()
+
+    def place_option_order(
+            self,
+            account: str,
+            option_symbol: str,
+            price_type: PriceType, 
+            order_type: OrderType,
+            contracts: int,
+            duration: Duration,
+            stop_price: float = None,
+            price: float = 0.00,
+            dry_run: bool = True,
+            order_instruction: OrderInstructions = "0",
+    ):
+        """
+        Builds and places an option order.
 
-        order_data = BeautifulSoup(
-            self.ft_session.post(
-                url=urls.orderbar(), headers=urls.session_headers(), data=data
-            ).text,
-            "xml",
-        )
-        order_confirmation = {}
-        cdata = order_data.find("actiondata").string
-        cdata_soup = BeautifulSoup(cdata, "html.parser")
-        span = (
-            cdata_soup.find("div", class_="msg_bg")
-            .find("div", class_="yellow box")
-            .find("div", class_="error_msg")
-            .find("div", class_="outbox")
-            .find("div", class_="inbox")
-            .find("span")
-        )
-        if span:
-            order_warning = span.text.strip()
-            order_confirmation["warning"] = order_warning
-            data["viewederror"] = "1"
-        if not dry_run:
-            data["previewOrders"] = ""
-            data["submitOrders"] = "1"
-            order_data = BeautifulSoup(
-                self.ft_session.post(
-                    url=urls.orderbar(), headers=urls.session_headers(), data=data
-                ).text,
-                "xml",
-            )
-
-        order_success = order_data.find("success").text.strip()
-        order_confirmation["success"] = order_success
-        action_data = order_data.find("actiondata").text.strip()
-        if order_success != "No":
-            # Extract the table data
-            table_start = action_data.find("<table")
-            table_end = action_data.find("</table>") + len("</table>")
-            table_data = action_data[table_start:table_end]
-            table_data = BeautifulSoup(table_data, "xml")
-            titles = table_data.find_all("th")
-            data = table_data.find_all("td")
-            for i, title in enumerate(titles):
-                order_confirmation[f"{title.get_text()}"] = data[i].get_text()
-            if not dry_run:
-                start_index = action_data.find(
-                    "Your order reference number is: "
-                ) + len("Your order reference number is: ")
-                end_index = action_data.find("</div>", start_index)
-                order_number = action_data[start_index:end_index]
-            else:
-                start_index = action_data.find('id="') + len('id="')
-                end_index = action_data.find('" style=', start_index)
-                order_number = action_data[start_index:end_index]
-            order_confirmation["orderid"] = order_number
-        else:
-            order_confirmation["actiondata"] = action_data
-        order_confirmation["errcode"] = order_data.find("errcode").text.strip()
-        self.order_confirmation = order_confirmation
-
-
-def get_orders(ft_session, account):
-    """
-    Retrieves existing order data for a given account.
-
-    Args:
-        ft_session (FTSession): The session object used for making HTTP requests to Firstrade.
-        account (str): Account number of the account to retrieve orders for.
-
-    Returns:
-        list: A list of dictionaries, each containing details about an order.
-    """
+        Args:
+            account (str): The account number to place the order in.
+            option_symbol (str): The option ticker symbol for the order.
+            price_type (PriceType): The price type for the order (e.g., LIMIT, MARKET, STOP).
+            order_type (OrderType): The type of order (e.g., BUY, SELL).
+            contracts (int): The number of option contracts to buy or sell.
+            duration (Duration): The duration of the order (e.g., DAY, GT90).
+            stop_price (float, optional): The stop price for stop orders. Defaults to None.
+            price (float, optional): The price at which to buy or sell the option contracts. Defaults to 0.00.
+            dry_run (bool, optional): If True, the order will not be placed but will be built and validated. Defaults to True.
+            order_instruction (OrderInstructions, optional): Additional order instructions (e.g., AON, OPG). Defaults to "0".
+
+        Raises:
+            ValueError: If AON orders are not limit orders or if AON orders have a quantity of 100 contracts or less.
+            PreviewOrderError: If there is an error during the preview of the order.
+            PlaceOrderError: If there is an error during the placement of the order.
 
-    # Data dictionary to send with the request
-    data = {
-        "accountId": account,
-    }
-
-    # Post request to retrieve the order data
-    response = ft_session.post(
-        url=urls.order_list(), headers=urls.session_headers(), data=data
-    ).text
-
-    # Parse the response using BeautifulSoup
-    soup = BeautifulSoup(response, "html.parser")
-
-    # Find the table containing orders
-    table = soup.find("table", class_="tablesorter")
-    if not table:
-        return []
-
-    rows = table.find_all("tr")[1:]  # skip the header row
-
-    orders = []
-    for row in rows:
-        try:
-            cells = row.find_all("td")
-            tooltip_content = row.find("a", {"class": "info"}).get("onmouseover")
-            tooltip_soup = BeautifulSoup(
-                tooltip_content.split("tooltip.show(")[1].strip("');"), "html.parser"
-            )
-            order_ref = tooltip_soup.find(text=lambda text: "Order Ref" in text)
-            order_ref_number = order_ref.split("#: ")[1] if order_ref else None
-            status = cells[8]
-            # print(status)
-            sub_status = status.find("strong")
-            # print(sub_status)
-            sub_status = sub_status.get_text(strip=True)
-            # print(sub_status)
-            status = (
-                status.find("strong").get_text(strip=True)
-                if status.find("strong")
-                else status.get_text(strip=True)
-            )
-            order = {
-                "Date/Time": cells[0].get_text(strip=True),
-                "Reference": order_ref_number,
-                "Transaction": cells[1].get_text(strip=True),
-                "Quantity": int(cells[2].get_text(strip=True)),
-                "Symbol": cells[3].get_text(strip=True),
-                "Type": cells[4].get_text(strip=True),
-                "Price": float(cells[5].get_text(strip=True)),
-                "Duration": cells[6].get_text(strip=True),
-                "Instr.": cells[7].get_text(strip=True),
-                "Status": status,
-            }
-            orders.append(order)
-        except Exception as e:
-            print(f"Error parsing order: {e}")
-
-    return orders
+        Returns:
+            dict: A dictionary containing the order confirmation data.
+        """
+        
+        if order_instruction == OrderInstructions.AON and price_type != PriceType.LIMIT:
+            raise ValueError("AON orders must be a limit order.")
+        if order_instruction == OrderInstructions.AON and contracts <= 100:
+            raise ValueError("AON orders must be greater than 100 shares.")
+            
+        
+        data = {
+            "duration": duration,
+            "instructions": order_instruction,
+            "transaction": order_type,
+            "contracts": contracts,
+            "symbol": option_symbol,
+            "preview": "true",
+            "account": account,
+            "price_type": price_type,
+        }
+        if price_type in [PriceType.LIMIT, PriceType.STOP_LIMIT]:
+                data["limit_price"] = price
+        if price_type in [PriceType.STOP, PriceType.STOP_LIMIT]:
+            data["stop_price"] = stop_price
+
+        response = self.ft_session.post(url=urls.option_order(), data=data)
+        if response.status_code != 200 or response.json()["error"] != "":
+            return response.json()
+        if dry_run:
+            return response.json()
+        data["preview"] = "false"
+        response = self.ft_session.post(url=urls.option_order(), data=data)
+        return response.json()

firstrade/symbols.py

@@ -1,77 +1,172 @@
-from bs4 import BeautifulSoup
-
 from firstrade import urls
 from firstrade.account import FTSession
+from firstrade.exceptions import QuoteRequestError, QuoteResponseError
 
 
 class SymbolQuote:
     """
-    Dataclass containing quote information for a symbol.
+    Data class representing a stock quote for a given symbol.
 
     Attributes:
-        ft_session (FTSession):
-            The session object used for making HTTP requests to Firstrade.
+        ft_session (FTSession): The session object used for making HTTP requests to Firstrade.
         symbol (str): The symbol for which the quote information is retrieved.
-        exchange (str): The exchange where the symbol is traded.
-        bid (float): The bid price for the symbol.
-        ask (float): The ask price for the symbol.
+        sec_type (str): The security type of the symbol.
+        tick (str): The tick size of the symbol.
+        bid (int): The bid price for the symbol.
+        bid_size (int): The size of the bid.
+        ask (int): The ask price for the symbol.
+        ask_size (int): The size of the ask.
         last (float): The last traded price for the symbol.
         change (float): The change in price for the symbol.
         high (float): The highest price for the symbol during the trading day.
         low (float): The lowest price for the symbol during the trading day.
+        bid_mmid (str): The market maker ID for the bid.
+        ask_mmid (str): The market maker ID for the ask.
+        last_mmid (str): The market maker ID for the last trade.
+        last_size (int): The size of the last trade.
+        change_color (str): The color indicating the change in price.
         volume (str): The volume of shares traded for the symbol.
+        today_close (float): The closing price for the symbol today.
+        open (str): The opening price for the symbol.
+        quote_time (str): The time of the quote.
+        last_trade_time (str): The time of the last trade.
         company_name (str): The name of the company associated with the symbol.
-        real_time (bool): If the quote is real-time or not
-        fractional (bool):  If the stock can be traded fractionally, or not
+        exchange (str): The exchange where the symbol is traded.
+        has_option (bool): Indicates if the symbol has options.
+        is_etf (bool): Indicates if the symbol is an ETF.
+        is_fractional (bool): Indicates if the stock can be traded fractionally.
+        realtime (str): Indicates if the quote is real-time.
+        nls (str): Nasdaq last sale.
+        shares (int): The number of shares.
     """
 
-    def __init__(self, ft_session: FTSession, symbol: str):
+    def __init__(self, ft_session: FTSession, account: str, symbol: str):
         """
         Initializes a new instance of the SymbolQuote class.
 
+        Args:
+            ft_session (FTSession): The session object used for making HTTP requests to Firstrade.
+            account (str): The account number for which the quote information is retrieved.
+            symbol (str): The symbol for which the quote information is retrieved.
+
+        Raises:
+            QuoteRequestError: If the quote request fails with a non-200 status code.
+            QuoteResponseError: If the quote response contains an error message.
+        """
+        self.ft_session = ft_session
+        response = self.ft_session.get(url=urls.quote(account, symbol))
+        if response.status_code != 200:
+            raise QuoteRequestError(response.status_code)
+        if response.json().get("error", "") != "":
+            raise QuoteResponseError(symbol, response.json()["error"])
+        self.symbol = response.json()["result"]["symbol"]
+        self.sec_type = response.json()["result"]["sec_type"]
+        self.tick = response.json()["result"]["tick"]
+        self.bid = response.json()["result"]["bid"]
+        self.bid_size = response.json()["result"]["bid_size"]
+        self.ask = response.json()["result"]["ask"]
+        self.ask_size = response.json()["result"]["ask_size"]
+        self.last = response.json()["result"]["last"]
+        self.change = response.json()["result"]["change"]
+        self.high = response.json()["result"]["high"]
+        self.low = response.json()["result"]["low"]
+        self.bid_mmid = response.json()["result"]["bid_mmid:"]
+        self.ask_mmid = response.json()["result"]["ask_mmid:"]
+        self.last_mmid = response.json()["result"]["last_mmid:"]
+        self.last_size = response.json()["result"]["last_size"]
+        self.change_color = response.json()["result"]["change_color"]
+        self.volume = response.json()["result"]["vol"]
+        self.today_close = response.json()["result"]["today_close"]
+        self.open = response.json()["result"]["open"]
+        self.quote_time = response.json()["result"]["quote_time"]
+        self.last_trade_time = response.json()["result"]["last_trade_time"]
+        self.company_name = response.json()["result"]["company_name"]
+        self.exchange = response.json()["result"]["exchange"]
+        self.has_option = response.json()["result"]["has_option"]
+        self.is_etf = bool(response.json()["result"]["is_etf"])
+        self.is_fractional = bool(response.json()["result"]["is_fractional"])
+        self.realtime = response.json()["result"]["realtime"]
+        self.nls = response.json()["result"]["nls"]
+        self.shares = response.json()["result"]["shares"]
+        
+
+class OptionQuote:
+    """
+    Data class representing an option quote for a given symbol.
+
+    Attributes:
+        ft_session (FTSession): The session object used for making HTTP requests to Firstrade.
+        symbol (str): The symbol for which the option quote information is retrieved.
+        option_dates (dict): A dict of expiration dates for options on the given symbol.
+    """
+
+    def __init__(self, ft_session: FTSession, symbol: str):
+        """
+        Initializes a new instance of the OptionQuote class.
+
         Args:
             ft_session (FTSession):
                 The session object used for making HTTP requests to Firstrade.
-            symbol (str): The symbol for which the quote information is retrieved.
+            symbol (str): The symbol for which the option quote information is retrieved.
         """
         self.ft_session = ft_session
         self.symbol = symbol
-        symbol_data = self.ft_session.get(
-            url=urls.quote(self.symbol), headers=urls.session_headers()
-        )
-        soup = BeautifulSoup(symbol_data.text, "xml")
-        quote = soup.find("quote")
-        self.symbol = quote.find("symbol").text
-        self.underlying_symbol = quote.find("underlying_symbol").text
-        self.tick = quote.find("tick").text
-        self.exchange = quote.find("exchange").text
-        self.bid = float(quote.find("bid").text.replace(",", ""))
-        self.ask = float(quote.find("ask").text.replace(",", ""))
-        self.last = float(quote.find("last").text.replace(",", ""))
-        temp_store = quote.find("bidsize").text.replace(",", "")
-        self.bid_size = int(temp_store) if temp_store.isdigit() else 0
-        temp_store = quote.find("asksize").text.replace(",", "")
-        self.ask_size = int(temp_store) if temp_store.isdigit() else 0
-        temp_store = quote.find("lastsize").text.replace(",", "")
-        self.last_size = int(temp_store) if temp_store.isdigit() else 0
-        self.bid_mmid = quote.find("bidmmid").text
-        self.ask_mmid = quote.find("askmmid").text
-        self.last_mmid = quote.find("lastmmid").text
-        self.change = float(quote.find("change").text.replace(",", ""))
-        if quote.find("high").text == "N/A":
-            self.high = None
-        else:
-            self.high = float(quote.find("high").text.replace(",", ""))
-        if quote.find("low").text == "N/A":
-            self.low = "None"
-        else:
-            self.low = float(quote.find("low").text.replace(",", ""))
-        self.change_color = quote.find("changecolor").text
-        self.volume = quote.find("vol").text
-        self.bidxask = quote.find("bidxask").text
-        self.quote_time = quote.find("quotetime").text
-        self.last_trade_time = quote.find("lasttradetime").text
-        self.real_time = quote.find("realtime").text == "T"
-        self.fractional = quote.find("fractional").text == "T"
-        self.err_code = quote.find("errcode").text
-        self.company_name = quote.find("companyname").text
+        self.option_dates = self.get_option_dates(symbol)
+        
+    def get_option_dates(self, symbol: str):
+        """
+        Retrieves the expiration dates for options on a given symbol.
+
+        Args:
+            symbol (str): The symbol for which the expiration dates are retrieved.
+
+        Returns:
+            dict: A dict of expiration dates and other information for options on the given symbol.
+
+        Raises:
+            QuoteRequestError: If the request for option dates fails with a non-200 status code.
+            QuoteResponseError: If the response for option dates contains an error message.
+        """
+        response = self.ft_session.get(url=urls.option_dates(symbol))
+        return response.json()
+    
+    def get_option_quote(self, symbol: str, date: str):
+        """
+        Retrieves the quote for a given option symbol.
+
+        Args:
+            symbol (str): The symbol for which the quote is retrieved.
+
+        Returns:
+            dict: A dictionary containing the quote  and other information for the given option symbol.
+
+        Raises:
+            QuoteRequestError: If the request for the option quote fails with a non-200 status code.
+            QuoteResponseError: If the response for the option quote contains an error message.
+        """
+        response = self.ft_session.get(url=urls.option_quotes(symbol, date))
+        return response.json()
+    
+    def get_greek_options(self, symbol: str, exp_date: str):
+        """
+        Retrieves the greeks for options on a given symbol.
+
+        Args:
+            symbol (str): The symbol for which the greeks are retrieved.
+            exp_date (str): The expiration date of the options.
+
+        Returns:
+            dict: A dictionary containing the greeks for the options on the given symbol.
+
+        Raises:
+            QuoteRequestError: If the request for the greeks fails with a non-200 status code.
+            QuoteResponseError: If the response for the greeks contains an error message.
+        """
+        data = {
+            "type": "chain",
+            "chains_range": "A",
+            "root_symbol": symbol,
+            "exp_date": exp_date,
+        }
+        response = self.ft_session.post(url=urls.greek_options(), data=data)
+        return response.json()