firstrade 0.0.34__py3-none-any.whl → 0.0.37__py3-none-any.whl

firstrade/account.py

@@ -1,21 +1,22 @@
 import json
-import os
-import pickle
+from pathlib import Path
 
 import pyotp
+import logging
 import requests
 
 from firstrade import urls
 from firstrade.exceptions import (
     AccountResponseError,
+    LoginError,
     LoginRequestError,
     LoginResponseError,
 )
 
+logger = logging.getLogger(__name__)
 
 class FTSession:
-    """
-    Class creating a session for Firstrade.
+    """Class creating a session for Firstrade.
 
     This class handles the creation and management of a session for logging into the Firstrade platform.
     It supports multi-factor authentication (MFA) and can save session cookies for persistent logins.
@@ -23,18 +24,19 @@ class FTSession:
     Attributes:
         username (str): Firstrade login username.
         password (str): Firstrade login password.
-        pin (str): Firstrade login pin.
+        pin (str, optional): Firstrade login pin.
         email (str, optional): Firstrade MFA email.
         phone (str, optional): Firstrade MFA phone number.
         mfa_secret (str, optional): Secret key for generating MFA codes.
         profile_path (str, optional): The path where the user wants to save the cookie pkl file.
+        debug (bool, optional): Log HTTP requests/responses if true. DO NOT POST YOUR LOGS ONLINE.
         t_token (str, optional): Token used for MFA.
         otp_options (dict, optional): Options for OTP (One-Time Password) if MFA is enabled.
         login_json (dict, optional): JSON response from the login request.
         session (requests.Session): The requests session object used for making HTTP requests.
 
     Methods:
-        __init__(username, password, pin=None, email=None, phone=None, mfa_secret=None, profile_path=None):
+        __init__(username, password, pin=None, email=None, phone=None, mfa_secret=None, profile_path=None, debug=False):
             Initializes a new instance of the FTSession class.
         login():
             Validates and logs into the Firstrade platform.
@@ -50,44 +52,58 @@ class FTSession:
             Masks the email for use in the API.
         _handle_mfa():
             Handles multi-factor authentication.
+        _request(method, url, **kwargs):
+            HTTP requests wrapper to the API.
+
     """
 
     def __init__(
         self,
-        username,
-        password,
-        pin=None,
-        email=None,
-        phone=None,
-        mfa_secret=None,
-        profile_path=None,
-    ):
-        """
-        Initializes a new instance of the FTSession class.
+        username: str,
+        password: str,
+        pin: str = "",
+        email: str = "",
+        phone: str = "",
+        mfa_secret: str = "",
+        profile_path: str | None = None,
+        debug: bool = False
+    ) -> None:
+        """Initialize a new instance of the FTSession class.
 
         Args:
             username (str): Firstrade login username.
             password (str): Firstrade login password.
-            pin (str): Firstrade login pin.
+            pin (str, optional): Firstrade login pin.
             email (str, optional): Firstrade MFA email.
             phone (str, optional): Firstrade MFA phone number.
+            mfa_secret (str, optional): Firstrade MFA secret key to generate TOTP.
             profile_path (str, optional): The path where the user wants to save the cookie pkl file.
+            debug (bool, optional): Log HTTP requests/responses if true. DO NOT POST YOUR LOGS ONLINE.
+
         """
-        self.username = username
-        self.password = password
-        self.pin = pin
-        self.email = FTSession._mask_email(email) if email is not None else None
-        self.phone = phone
-        self.mfa_secret = mfa_secret
-        self.profile_path = profile_path
-        self.t_token = None
-        self.otp_options = None
-        self.login_json = None
+        self.username: str = username
+        self.password: str = password
+        self.pin: str = pin
+        self.email: str = FTSession._mask_email(email) if email else ""
+        self.phone: str = phone
+        self.mfa_secret: str = mfa_secret
+        self.profile_path: str | None = profile_path
+        self.debug: bool = debug
+        if self.debug:
+            logging.basicConfig(level=logging.DEBUG)
+            # Enable HTTP connection debug output
+            import http.client as http_client
+            http_client.HTTPConnection.debuglevel = 1
+            # requests logging too
+            logging.getLogger("requests.packages.urllib3").setLevel(logging.DEBUG)
+            logging.getLogger("requests.packages.urllib3").propagate = True
+        self.t_token: str | None = None
+        self.otp_options: list[dict[str, str]] | None = None
+        self.login_json: dict[str, str] = {}
         self.session = requests.Session()
 
-    def login(self):
-        """
-        Validates and logs into the Firstrade platform.
+    def login(self) -> bool:
+        """Validate and log into the Firstrade platform.
 
         This method sets up the session headers, loads cookies if available, and performs the login request.
         It handles multi-factor authentication (MFA) if required.
@@ -95,43 +111,42 @@ class FTSession:
         Raises:
             LoginRequestError: If the login request fails with a non-200 status code.
             LoginResponseError: If the login response contains an error message.
+
         """
-        self.session.headers = urls.session_headers()
-        ftat = self._load_cookies()
-        if ftat != "":
+        self.session.headers.update(urls.session_headers())
+        ftat: str = self._load_cookies()
+        if ftat:
             self.session.headers["ftat"] = ftat
-        response = self.session.get(url="https://api3x.firstrade.com/", timeout=10)
+        response: requests.Response = self._request("get", url="https://api3x.firstrade.com/", timeout=10)
         self.session.headers["access-token"] = urls.access_token()
 
-        data = {
+        data: dict[str, str] = {
             "username": r"" + self.username,
             "password": r"" + self.password,
         }
 
-        response = self.session.post(
+        response: requests.Response = self._request(
+            "post",
             url=urls.login(),
             data=data,
         )
         try:
-            self.login_json = response.json()
-        except json.decoder.JSONDecodeError:
-            raise LoginResponseError("Invalid JSON is your account funded?")
-        if (
-            "mfa" not in self.login_json
-            and "ftat" in self.login_json
-            and self.login_json["error"] == ""
-        ):
+            self.login_json: dict[str, str] = response.json()
+        except json.decoder.JSONDecodeError as exc:
+            error_msg = "Invalid JSON is your account funded?"
+            raise LoginResponseError(error_msg) from exc
+        if "mfa" not in self.login_json and "ftat" in self.login_json and not self.login_json["error"]:
             self.session.headers["sid"] = self.login_json["sid"]
             return False
-        self.t_token = self.login_json.get("t_token")
-        if self.mfa_secret is None:
-            self.otp_options = self.login_json.get("otp")
+        self.t_token: str | None = self.login_json.get("t_token")
+        if not self.mfa_secret:
+            self.otp_options: str | None = self.login_json.get("otp")
         if response.status_code != 200:
             raise LoginRequestError(response.status_code)
-        if self.login_json["error"] != "":
+        if self.login_json["error"]:
             raise LoginResponseError(self.login_json["error"])
-        need_code = self._handle_mfa()
-        if self.login_json["error"] != "":
+        need_code: bool | None = self._handle_mfa()
+        if self.login_json["error"]:
             raise LoginResponseError(self.login_json["error"])
         if need_code:
             return True
@@ -140,144 +155,183 @@ class FTSession:
         self._save_cookies()
         return False
 
-    def login_two(self, code):
-        """Method to finish login to the Firstrade platform."""
-        data = {
+    def login_two(self, code: str) -> None:
+        """Finish login to the Firstrade platform."""
+        data: dict[str, str | None] = {
             "otpCode": code,
             "verificationSid": self.session.headers["sid"],
             "remember_for": "30",
             "t_token": self.t_token,
         }
-        response = self.session.post(urls.verify_pin(), data=data)
-        self.login_json = response.json()
-        if self.login_json["error"] != "":
+        response: requests.Response = self._request("post", urls.verify_pin(), data=data)
+        self.login_json: dict[str, str] = response.json()
+        if not self.login_json["error"]:
             raise LoginResponseError(self.login_json["error"])
         self.session.headers["ftat"] = self.login_json["ftat"]
         self.session.headers["sid"] = self.login_json["sid"]
         self._save_cookies()
 
-    def delete_cookies(self):
-        """Deletes the session cookies."""
-        if self.profile_path is not None:
-            path = os.path.join(self.profile_path, f"ft_cookies{self.username}.pkl")
-        else:
-            path = f"ft_cookies{self.username}.pkl"
-        os.remove(path)
+    def delete_cookies(self) -> None:
+        """Delete the session cookies."""
+        path: Path = Path(self.profile_path) / f"ft_cookies{self.username}.json" if self.profile_path is not None else Path(f"ft_cookies{self.username}.json")
+        path.unlink()
 
-    def _load_cookies(self):
-        """
-        Checks if session cookies were saved.
+    def _load_cookies(self) -> str:
+        """Check if session cookies were saved.
 
         Returns:
             str: The saved session token.
-        """
 
+        """
         ftat = ""
-        directory = (
-            os.path.abspath(self.profile_path) if self.profile_path is not None else "."
-        )
-        if not os.path.exists(directory):
-            os.makedirs(directory)
-
-        for filename in os.listdir(directory):
-            if filename.endswith(f"{self.username}.pkl"):
-                filepath = os.path.join(directory, filename)
-                with open(filepath, "rb") as f:
-                    ftat = pickle.load(f)
+        directory: Path = Path(self.profile_path) if self.profile_path is not None else Path()
+        if not directory.exists():
+            directory.mkdir(parents=True)
+
+        for filepath in directory.iterdir():
+            if filepath.name.endswith(f"{self.username}.json"):
+                with filepath.open(mode="r") as f:
+                    ftat: str = json.load(fp=f)
         return ftat
 
-    def _save_cookies(self):
-        """Saves session cookies to a file."""
+    def _save_cookies(self) -> str | None:
+        """Save session cookies to a file."""
         if self.profile_path is not None:
-            directory = os.path.abspath(self.profile_path)
-            if not os.path.exists(directory):
-                os.makedirs(directory)
-            path = os.path.join(self.profile_path, f"ft_cookies{self.username}.pkl")
+            directory = Path(self.profile_path)
+            if not directory.exists():
+                directory.mkdir(parents=True)
+            path: Path = directory / f"ft_cookies{self.username}.json"
         else:
-            path = f"ft_cookies{self.username}.pkl"
-        with open(path, "wb") as f:
-            ftat = self.session.headers.get("ftat")
-            pickle.dump(ftat, f)
+            path = Path(f"ft_cookies{self.username}.json")
+        with path.open("w") as f:
+            ftat: str | None = self.session.headers.get("ftat")
+            json.dump(obj=ftat, fp=f)
 
     @staticmethod
-    def _mask_email(email):
-        """
-        Masks the email for use in the API.
+    def _mask_email(email: str) -> str:
+        """Mask the email for use in the API.
 
         Args:
             email (str): The email address to be masked.
 
         Returns:
             str: The masked email address.
+
         """
-        local, domain = email.split("@")
-        masked_local = local[0] + "*" * 4
+        local, domain = email.split(sep="@")
+        masked_local: str = local[0] + "*" * 4
         domain_name, tld = domain.split(".")
-        masked_domain = domain_name[0] + "*" * 4
+        masked_domain: str = domain_name[0] + "*" * 4
         return f"{masked_local}@{masked_domain}.{tld}"
 
-    def _handle_mfa(self):
-        """
-        Handles multi-factor authentication.
+    def _handle_mfa(self) -> bool:
+        """Handle multi-factor authentication.
 
         This method processes the MFA requirements based on the login response and user-provided details.
 
-        Raises:
-            LoginRequestError: If the MFA request fails with a non-200 status code.
-            LoginResponseError: If the MFA response contains an error message.
         """
-        if not self.login_json["mfa"] and self.pin is not None:
-            data = {
-                "pin": self.pin,
-                "remember_for": "30",
-                "t_token": self.t_token,
-            }
-            response = self.session.post(urls.verify_pin(), data=data)
-            self.login_json = response.json()
-        elif not self.login_json["mfa"] and (
-            self.email is not None or self.phone is not None
-        ):
-            for item in self.otp_options:
-                if item["channel"] == "sms" and self.phone is not None:
-                    if self.phone in item["recipientMask"]:
-                        data = {
-                            "recipientId": item["recipientId"],
-                            "t_token": self.t_token,
-                        }
-                        break
-                elif item["channel"] == "email" and self.email is not None:
-                    if self.email == item["recipientMask"]:
-                        data = {
-                            "recipientId": item["recipientId"],
-                            "t_token": self.t_token,
-                        }
-                        break
-            response = self.session.post(urls.request_code(), data=data)
-        elif self.login_json["mfa"] and self.mfa_secret is not None:
-            mfa_otp = pyotp.TOTP(self.mfa_secret).now()
-            data = {
-                "mfaCode": mfa_otp,
-                "remember_for": "30",
-                "t_token": self.t_token,
-            }
-            response = self.session.post(urls.verify_pin(), data=data)
+        response: requests.Response | None = None
+        data: dict[str, str | None] = {}
+
+        if self.pin:
+            response: requests.Response = self._handle_pin_mfa(data)
+        elif (self.email or self.phone) and not self.mfa_secret:
+            response: requests.Response = self._handle_otp_mfa(data)
+        elif self.mfa_secret:
+            response: requests.Response = self._handle_secret_mfa(data)
+        else:
+            error_msg = "MFA required but no valid MFA method was provided (pin, email/phone, or mfa_secret)."
+            raise LoginError(error_msg)
+
         self.login_json = response.json()
-        if self.login_json["error"] == "":
-            if self.pin or self.mfa_secret is not None:
-                self.session.headers["sid"] = self.login_json["sid"]
-                return False
-            self.session.headers["sid"] = self.login_json["verificationSid"]
-            return True
+        if self.login_json["error"]:
+            raise LoginResponseError(self.login_json["error"])
 
-    def __getattr__(self, name):
-        """
-        Forwards unknown attribute access to session object.
+        if self.pin or self.mfa_secret:
+            self.session.headers["sid"] = self.login_json["sid"]
+            return False
+        self.session.headers["sid"] = self.login_json["verificationSid"]
+        return True
+
+    def _handle_pin_mfa(self, data: dict[str, str | None]) -> requests.Response:
+        """Handle PIN-based MFA."""
+        data.update({
+            "pin": self.pin,
+            "remember_for": "30",
+            "t_token": self.t_token,
+        })
+        return self._request("post", urls.verify_pin(), data=data)
+
+    def _handle_otp_mfa(self, data: dict[str, str | None]) -> requests.Response:
+        """Handle email/phone OTP-based MFA."""
+        if not self.otp_options:
+            error_msg = "No OTP options available."
+            raise LoginResponseError(error_msg)
+
+        for item in self.otp_options:
+            if (item["channel"] == "sms" and self.phone and self.phone in item["recipientMask"]) or (item["channel"] == "email" and self.email and self.email == item["recipientMask"]):
+                data.update({
+                    "recipientId": item["recipientId"],
+                    "t_token": self.t_token,
+                })
+                break
+
+        return self._request("post", urls.request_code(), data=data)
+
+    def _handle_secret_mfa(self, data: dict[str, str | None]) -> requests.Response:
+        """Handle MFA secret-based authentication."""
+        mfa_otp = pyotp.TOTP(self.mfa_secret).now()
+        data.update({
+            "mfaCode": mfa_otp,
+            "remember_for": "30",
+            "t_token": self.t_token,
+        })
+        return self._request("post", urls.verify_pin(), data=data)
+
+    def _request(self, method, url, **kwargs):
+        """Send HTTP request and log the full response content if debug=True."""
+        resp = self.session.request(method, url, **kwargs)
+
+        if self.debug:
+            # Suppress urllib3 / http.client debug so we only see this log
+            logging.getLogger("urllib3").setLevel(logging.WARNING)
+
+            # Basic request info
+            logger.debug(f">>> {method.upper()} {url}")
+            logger.debug(f"<<< Status: {resp.status_code}")
+            logger.debug(f"<<< Headers: {resp.headers}")
+
+            # Log raw bytes length
+            try:
+                logger.debug(f"<<< Raw bytes length: {len(resp.content)}")
+            except Exception as e:
+                logger.debug(f"<<< Could not read raw bytes: {e}")
+
+            # Log pretty JSON (if any)
+            try:
+                import json as pyjson
+                # This automatically uses requests decompression if gzip is set
+                json_body = resp.json()
+                pretty = pyjson.dumps(json_body, indent=2)
+                logger.debug(f"<<< JSON body:\n{pretty}")
+            except Exception as e:
+                # If JSON decoding fails, fallback to raw text
+                try:
+                    logger.debug(f"<<< Body (text):\n{resp.text}")
+                except Exception as e2:
+                    logger.debug(f"<<< Could not read body text: {e2}")
+
+        return resp
+
+    def __getattr__(self, name: str) -> object:
+        """Forward unknown attribute access to session object.
 
         Args:
             name (str): The name of the attribute to be accessed.
 
         Returns:
             The value of the requested attribute from the session object.
+
         """
         return getattr(self.session, name)
 
@@ -285,21 +339,20 @@ class FTSession:
 class FTAccountData:
     """Dataclass for storing account information."""
 
-    def __init__(self, session):
-        """
-        Initializes a new instance of the FTAccountData class.
+    def __init__(self, session: requests.Session) -> None:
+        """Initialize a new instance of the FTAccountData class.
 
         Args:
-            session (requests.Session):
-            The session object used for making HTTP requests.
+            session (requests.Session): The session object used for making HTTP requests.
+
         """
-        self.session = session
-        self.all_accounts = []
-        self.account_numbers = []
-        self.account_balances = {}
-        response = self.session.get(url=urls.user_info())
-        self.user_info = response.json()
-        response = self.session.get(urls.account_list())
+        self.session: requests.Session = session
+        self.all_accounts: list[dict[str, object]] = []
+        self.account_numbers: list[str] = []
+        self.account_balances: dict[str, object] = {}
+        response: requests.Response = self.session._request("get", url=urls.user_info())
+        self.user_info: dict[str, object] = response.json()
+        response: requests.Response = self.session._request("get", urls.account_list())
         if response.status_code != 200 or response.json()["error"] != "":
             raise AccountResponseError(response.json()["error"])
         self.all_accounts = response.json()
@@ -307,90 +360,93 @@ class FTAccountData:
             self.account_numbers.append(item["account"])
             self.account_balances[item["account"]] = item["total_value"]
 
-    def get_account_balances(self, account):
-        """Gets account balances for a given account.
+    def get_account_balances(self, account: str) -> dict[str, object]:
+        """Get account balances for a given account.
 
         Args:
             account (str): Account number of the account you want to get balances for.
 
         Returns:
             dict: Dict of the response from the API.
+
         """
-        response = self.session.get(urls.account_balances(account))
+        response: requests.Response = self.session._request("get", urls.account_balances(account))
         return response.json()
 
-    def get_positions(self, account):
-        """Gets currently held positions for a given account.
+    def get_positions(self, account: str) -> dict[str, object]:
+        """Get currently held positions for a given account.
 
         Args:
             account (str): Account number of the account you want to get positions for.
 
         Returns:
             dict: Dict of the response from the API.
-        """
 
-        response = self.session.get(urls.account_positions(account))
+        """
+        response = self.session._request("get", urls.account_positions(account))
         return response.json()
 
-    def get_account_history(self, account, date_range="ytd", custom_range=None):
-        """Gets account history for a given account.
+    def get_account_history(
+        self,
+        account: str,
+        date_range: str = "ytd",
+        custom_range: list[str] | None = None,
+    ) -> dict[str, object]:
+        """Get account history for a given account.
 
         Args:
             account (str): Account number of the account you want to get history for.
-            range (str): The range of the history. Defaults to "ytd".
+            date_range (str): The range of the history. Defaults to "ytd".
                          Available options are
                          ["today", "1w", "1m", "2m", "mtd", "ytd", "ly", "cust"].
-            custom_range (str): The custom range of the history.
+            custom_range (list[str] | None): The custom range of the history.
                                 Defaults to None. If range is "cust",
                                 this parameter is required.
                                 Format: ["YYYY-MM-DD", "YYYY-MM-DD"].
 
         Returns:
             dict: Dict of the response from the API.
+
         """
         if date_range == "cust" and custom_range is None:
-            raise ValueError("Custom range is required when date_range is 'cust'.")
-        response = self.session.get(
-            urls.account_history(account, date_range, custom_range)
+            raise ValueError("Custom range required.")
+        response: requests.Response = self.session._request(
+            "get", urls.account_history(account, date_range, custom_range),
         )
         return response.json()
 
-    def get_orders(self, account):
-        """
-        Retrieves existing order data for a given account.
+    def get_orders(self, account: str) -> list[dict[str, object]]:
+        """Retrieve 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.
-        """
 
-        response = self.session.get(url=urls.order_list(account))
+        """
+        response = self.session._request("get", url=urls.order_list(account))
         return response.json()
 
-    def cancel_order(self, order_id):
-        """
-        Cancels an existing order.
+    def cancel_order(self, order_id: str) -> dict[str, object]:
+        """Cancel an existing order.
 
         Args:
             order_id (str): The order ID to cancel.
 
         Returns:
             dict: A dictionary containing the response data.
-        """
 
+        """
         data = {
             "order_id": order_id,
         }
 
-        response = self.session.post(url=urls.cancel_order(), data=data)
+        response = self.session._request("post", url=urls.cancel_order(), data=data)
         return response.json()
 
-    def get_balance_overview(self, account, keywords=None):
-        """
-        Returns a filtered, flattened view of useful balance fields.
+    def get_balance_overview(self, account: str, keywords: list[str] | None = None) -> dict[str, object]:
+        """Return a filtered, flattened view of useful balance fields.
 
         This is a convenience helper over `get_account_balances` to quickly
         surface likely relevant numbers such as cash, available cash, and
@@ -404,6 +460,7 @@ class FTAccountData:
         Returns:
             dict: A dict mapping dot-notated keys to values from the balances
                   response where the key path contains any of the keywords.
+
         """
         if keywords is None:
             keywords = [
@@ -417,22 +474,22 @@ class FTAccountData:
                 "margin",
             ]
 
-        payload = self.get_account_balances(account)
+        payload: dict[str, object] = self.get_account_balances(account)
 
-        filtered = {}
+        filtered: dict[str, object] = {}
 
-        def _walk(node, path):
+        def _walk(node: object, path: list[str]) -> None:
             if isinstance(node, dict):
                 for k, v in node.items():
-                    _walk(v, path + [str(k)])
+                    _walk(node=v, path=[*path, str(object=k)])
             elif isinstance(node, list):
-                for i, v in enumerate(node):
-                    _walk(v, path + [str(i)])
+                for i, v in enumerate(iterable=node):
+                    _walk(node=v, path=[*path, str(object=i)])
             else:
-                key_path = ".".join(path)
-                low = key_path.lower()
+                key_path: str = ".".join(path)
+                low: str = key_path.lower()
                 if any(sub in low for sub in keywords):
                     filtered[key_path] = node
 
-        _walk(payload, [])
+        _walk(node=payload, path=[])
         return filtered

firstrade/exceptions.py

@@ -36,10 +36,9 @@ class LoginRequestError(LoginError):
 class LoginResponseError(LoginError):
     """Exception raised for errors in the API response during login."""
 
-    def __init__(self, error_message):
-        self.message = (
-            f"Failed to login. API returned the following error: {error_message}"
-        )
+    def __init__(self, error_message: str) -> None:
+        """Raise error for login response issues."""
+        self.message = f"Failed to login. API returned the following error: {error_message}"
         super().__init__(self.message)
 
 

firstrade/order.py

@@ -1,12 +1,11 @@
-from enum import Enum
+import enum
 
 from firstrade import urls
 from firstrade.account import FTSession
 
 
-class PriceType(str, Enum):
-    """
-    Enum for valid price types in an order.
+class PriceType(enum.StrEnum):
+    """Enum for valid price types in an order.
 
     Attributes:
         MARKET (str): Market order, executed at the current market price.
@@ -15,6 +14,7 @@ class PriceType(str, Enum):
         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"
@@ -25,9 +25,8 @@ class PriceType(str, Enum):
     TRAILING_STOP_PERCENT = "6"
 
 
-class Duration(str, Enum):
-    """
-    Enum for valid order durations.
+class Duration(enum.StrEnum):
+    """Enum for valid order durations.
 
     Attributes:
         DAY (str): Day order.
@@ -35,6 +34,7 @@ class Duration(str, Enum):
         PRE_MARKET (str): Pre-market order.
         AFTER_MARKET (str): After-market order.
         DAY_EXT (str): Day extended order.
+
     """
 
     DAY = "0"
@@ -44,9 +44,8 @@ class Duration(str, Enum):
     DAY_EXT = "D"
 
 
-class OrderType(str, Enum):
-    """
-    Enum for valid order types.
+class OrderType(enum.StrEnum):
+    """Enum for valid order types.
 
     Attributes:
         BUY (str): Buy order.
@@ -55,6 +54,7 @@ class OrderType(str, Enum):
         BUY_TO_COVER (str): Buy to cover order.
         BUY_OPTION (str): Buy option order.
         SELL_OPTION (str): Sell option order.
+
     """
 
     BUY = "B"
@@ -65,28 +65,30 @@ class OrderType(str, Enum):
     SELL_OPTION = "SO"
 
 
-class OrderInstructions(str, Enum):
-    """
-    Enum for valid order instructions.
+class OrderInstructions(enum.StrEnum):
+    """Enum for valid order instructions.
 
     Attributes:
+        NONE (str): No special instruction.
         AON (str): All or none.
         OPG (str): At the Open.
         CLO (str): At the Close.
+
     """
 
+    NONE = "0"
     AON = "1"
     OPG = "4"
     CLO = "5"
 
 
-class OptionType(str, Enum):
-    """
-    Enum for valid option types.
+class OptionType(enum.StrEnum):
+    """Enum for valid option types.
 
     Attributes:
         CALL (str): Call option.
         PUT (str): Put option.
+
     """
 
     CALL = "C"
@@ -94,15 +96,16 @@ class OptionType(str, Enum):
 
 
 class Order:
-    """
-    Represents an order with methods to place it.
+    """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
+    def __init__(self, ft_session: FTSession) -> None:
+        """Initialize the Order with a FirstTrade session."""
+        self.ft_session: FTSession = ft_session
 
     def place_order(
         self,
@@ -113,13 +116,13 @@ class Order:
         duration: Duration,
         quantity: int = 0,
         price: float = 0.00,
-        stop_price: float = None,
+        stop_price: float | None = None,
+        *,
         dry_run: bool = True,
         notional: bool = False,
-        order_instruction: OrderInstructions = "0",
+        order_instruction: OrderInstructions = OrderInstructions.NONE,
     ):
-        """
-        Builds and places an order.
+        """Build and place an order.
 
         Args:
             account (str): The account number to place the order in.
@@ -134,15 +137,10 @@ class Order:
             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:
             dict: A dictionary containing the order confirmation data.
-        """
 
+        """
         if price_type == PriceType.MARKET and not notional:
             price = ""
         if order_instruction == OrderInstructions.AON and price_type != PriceType.LIMIT:
@@ -164,11 +162,11 @@ class Order:
         if notional:
             data["dollar_amount"] = price
             del data["shares"]
-        if price_type in [PriceType.LIMIT, PriceType.STOP_LIMIT]:
+        if price_type in {PriceType.LIMIT, PriceType.STOP_LIMIT}:
             data["limit_price"] = price
-        if price_type in [PriceType.STOP, PriceType.STOP_LIMIT]:
+        if price_type in {PriceType.STOP, PriceType.STOP_LIMIT}:
             data["stop_price"] = stop_price
-        response = self.ft_session.post(url=urls.order(), data=data)
+        response: requests.Response = self.ft_session._request("post", url=urls.order(), data=data)
         if response.status_code != 200 or response.json()["error"] != "":
             return response.json()
         preview_data = response.json()
@@ -176,7 +174,7 @@ class Order:
             return preview_data
         data["preview"] = "false"
         data["stage"] = "P"
-        response = self.ft_session.post(url=urls.order(), data=data)
+        response = self.ft_session._request("post", url=urls.order(), data=data)
         return response.json()
 
     def place_option_order(
@@ -187,13 +185,13 @@ class Order:
         order_type: OrderType,
         contracts: int,
         duration: Duration,
-        stop_price: float = None,
+        stop_price: float | None = None,
         price: float = 0.00,
+        *,
         dry_run: bool = True,
-        order_instruction: OrderInstructions = "0",
+        order_instruction: OrderInstructions = OrderInstructions.NONE,
     ):
-        """
-        Builds and places an option order.
+        """Build and place an option order.
 
         Args:
             account (str): The account number to place the order in.
@@ -209,13 +207,11 @@ class Order:
 
         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.
 
         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:
@@ -231,16 +227,16 @@ class Order:
             "account": account,
             "price_type": price_type,
         }
-        if price_type in [PriceType.LIMIT, PriceType.STOP_LIMIT]:
+        if price_type in {PriceType.LIMIT, PriceType.STOP_LIMIT}:
             data["limit_price"] = price
-        if price_type in [PriceType.STOP, PriceType.STOP_LIMIT]:
+        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)
+        response = self.ft_session._request("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)
+        response = self.ft_session._request("post", url=urls.option_order(), data=data)
         return response.json()

firstrade/symbols.py

@@ -1,11 +1,12 @@
+from typing import Any
+
 from firstrade import urls
 from firstrade.account import FTSession
 from firstrade.exceptions import QuoteRequestError, QuoteResponseError
 
 
 class SymbolQuote:
-    """
-    Data class representing a stock quote for a given 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.
@@ -38,11 +39,11 @@ class SymbolQuote:
         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, account: str, symbol: str):
-        """
-        Initializes a new instance of the SymbolQuote class.
+        """Initialize a new instance of the SymbolQuote class.
 
         Args:
             ft_session (FTSession): The session object used for making HTTP requests to Firstrade.
@@ -52,70 +53,70 @@ class SymbolQuote:
         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))
+        self.ft_session: FTSession = ft_session
+        response = self.ft_session._request("get", url=urls.quote(account, symbol))
         if response.status_code != 200:
             raise QuoteRequestError(response.status_code)
-        if response.json().get("error", "") != "":
+        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.symbol: str = response.json()["result"]["symbol"]
+        self.sec_type: str = response.json()["result"]["sec_type"]
+        self.tick: str = response.json()["result"]["tick"]
+        self.bid: str = response.json()["result"]["bid"]
+        self.bid_size: str = response.json()["result"]["bid_size"]
+        self.ask: str = response.json()["result"]["ask"]
+        self.ask_size: str = response.json()["result"]["ask_size"]
+        self.last: str = response.json()["result"]["last"]
+        self.change: str = response.json()["result"]["change"]
+        self.high: str = response.json()["result"]["high"]
+        self.low: str = response.json()["result"]["low"]
+        self.bid_mmid: str = response.json()["result"]["bid_mmid"]
+        self.ask_mmid: str = response.json()["result"]["ask_mmid"]
+        self.last_mmid: str = response.json()["result"]["last_mmid"]
+        self.last_size: int = response.json()["result"]["last_size"]
+        self.change_color: str = response.json()["result"]["change_color"]
+        self.volume: str = response.json()["result"]["vol"]
+        self.today_close: float = response.json()["result"]["today_close"]
+        self.open: str = response.json()["result"]["open"]
+        self.quote_time: str = response.json()["result"]["quote_time"]
+        self.last_trade_time: str = response.json()["result"]["last_trade_time"]
+        self.company_name: str = response.json()["result"]["company_name"]
+        self.exchange: str = response.json()["result"]["exchange"]
+        self.has_option: str = response.json()["result"]["has_option"]
+        self.is_etf: bool = 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"]
+        self.realtime: str = response.json()["result"]["realtime"]
+        self.nls: str = response.json()["result"]["nls"]
+        self.shares: str = response.json()["result"]["shares"]
 
 
 class OptionQuote:
-    """
-    Data class representing an option quote for a given symbol.
+    """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.
+        """Initialize 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 option quote information is retrieved.
+
         """
         self.ft_session = ft_session
         self.symbol = symbol
         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.
+        """Retrieve the expiration dates for options on a given symbol.
 
         Args:
             symbol (str): The symbol for which the expiration dates are retrieved.
@@ -123,16 +124,12 @@ class OptionQuote:
         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))
+        response = self.ft_session._request("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.
+    def get_option_quote(self, symbol: str, date: str) -> dict[Any, Any]:
+        """Retrieve the quote for a given option symbol.
 
         Args:
             symbol (str): The symbol for which the quote is retrieved.
@@ -140,16 +137,12 @@ class OptionQuote:
         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))
+        response = self.ft_session._request("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.
+        """Retrieve the greeks for options on a given symbol.
 
         Args:
             symbol (str): The symbol for which the greeks are retrieved.
@@ -158,9 +151,6 @@ class OptionQuote:
         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",
@@ -168,5 +158,5 @@ class OptionQuote:
             "root_symbol": symbol,
             "exp_date": exp_date,
         }
-        response = self.ft_session.post(url=urls.greek_options(), data=data)
+        response = self.ft_session._request("post", url=urls.greek_options(), data=data)
         return response.json()

firstrade/urls.py

@@ -1,73 +1,88 @@
-def login():
+def login() -> str:
+    """Login URL for FirstTrade API."""
     return "https://api3x.firstrade.com/sess/login"
 
 
-def request_code():
+def request_code() -> str:
+    """Request PIN/MFA option for FirstTrade API."""
     return "https://api3x.firstrade.com/sess/request_code"
 
 
-def verify_pin():
+def verify_pin() -> str:
+    """Request PIN/MFA verification for FirstTrade API."""
     return "https://api3x.firstrade.com/sess/verify_pin"
 
 
-def user_info():
+def user_info() -> str:
+    """Retrieve user information URL for FirstTrade API."""
     return "https://api3x.firstrade.com/private/userinfo"
 
 
-def account_list():
+def account_list() -> str:
+    """Retrieve account list URL for FirstTrade API."""
     return "https://api3x.firstrade.com/private/acct_list"
 
 
-def account_balances(account):
+def account_balances(account: str) -> str:
+    """Retrieve account balances URL for FirstTrade API."""
     return f"https://api3x.firstrade.com/private/balances?account={account}"
 
 
-def account_positions(account):
-    return (
-        f"https://api3x.firstrade.com/private/positions?account={account}&per_page=200"
-    )
+def account_positions(account: str) -> str:
+    """Retrieve account positions URL for FirstTrade API."""
+    return f"https://api3x.firstrade.com/private/positions?account={account}&per_page=200"
 
 
-def quote(account, symbol):
+def quote(account: str, symbol: str) -> str:
+    """Symbol quote URL for FirstTrade API."""
     return f"https://api3x.firstrade.com/public/quote?account={account}&q={symbol}"
 
 
-def order():
+def order() -> str:
+    """Place equity order URL for FirstTrade API."""
     return "https://api3x.firstrade.com/private/stock_order"
 
 
-def order_list(account):
+def order_list(account: str) -> str:
+    """Retrieve placed order list URL for FirstTrade API."""
     return f"https://api3x.firstrade.com/private/order_status?account={account}"
 
 
-def account_history(account, date_range, custom_range):
+def account_history(account: str, date_range: str, custom_range: list[str] | None) -> str:
+    """Retrieve account history URL for FirstTrade API."""
     if custom_range is None:
         return f"https://api3x.firstrade.com/private/account_history?range={date_range}&page=1&account={account}&per_page=1000"
     return f"https://api3x.firstrade.com/private/account_history?range={date_range}&range_arr[]={custom_range[0]}&range_arr[]={custom_range[1]}&page=1&account={account}&per_page=1000"
 
 
-def cancel_order():
+def cancel_order() -> str:
+    """Cancel placed order URL for FirstTrade API."""
     return "https://api3x.firstrade.com/private/cancel_order"
 
 
-def option_dates(symbol):
+def option_dates(symbol: str) -> str:
+    """Option dates URL for FirstTrade API."""
     return f"https://api3x.firstrade.com/public/oc?m=get_exp_dates&root_symbol={symbol}"
 
 
-def option_quotes(symbol, date):
+def option_quotes(symbol: str, date: str) -> str:
+    """Option quotes URL for FirstTrade API."""
     return f"https://api3x.firstrade.com/public/oc?m=get_oc&root_symbol={symbol}&exp_date={date}&chains_range=A"
 
 
-def greek_options():
+def greek_options() -> str:
+    """Greek options analytical data URL for FirstTrade API."""
     return "https://api3x.firstrade.com/private/greekoptions/analytical"
 
 
-def option_order():
+def option_order() -> str:
+    """Place option order URL for FirstTrade API."""
     return "https://api3x.firstrade.com/private/option_order"
 
 
-def session_headers():
-    headers = {
+def session_headers() -> dict[str, str]:
+    """Session headers for FirstTrade API."""
+    headers: dict[str, str] = {
         "Accept-Encoding": "gzip",
         "Connection": "Keep-Alive",
         "Host": "api3x.firstrade.com",
@@ -76,5 +91,6 @@ def session_headers():
     return headers
 
 
-def access_token():
+def access_token() -> str:
+    """Access token for FirstTrade API."""
     return "833w3XuIFycv18ybi"

{firstrade-0.0.34.dist-info → firstrade-0.0.37.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: firstrade
-Version: 0.0.34
+Version: 0.0.37
 Summary: An unofficial API for Firstrade
 Home-page: https://github.com/MaxxRK/firstrade-api
-Download-URL: https://github.com/MaxxRK/firstrade-api/archive/refs/tags/0034.tar.gz
+Download-URL: https://github.com/MaxxRK/firstrade-api/archive/refs/tags/0037.tar.gz
 Author: MaxxRK
 Author-email: maxxrk@pm.me
 License: MIT
@@ -13,8 +13,6 @@ Classifier: Intended Audience :: Developers
 Classifier: Topic :: Internet :: WWW/HTTP :: Session
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -22,8 +20,7 @@ Classifier: Programming Language :: Python :: 3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests
-Requires-Dist: beautifulsoup4
-Requires-Dist: lxml
+Requires-Dist: pyotp
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

firstrade-0.0.37.dist-info/RECORD

@@ -0,0 +1,11 @@
+firstrade/__init__.py,sha256=fNiWYgSTjElY1MNv0Ug-sVLMTR2z_Ngri_FY7Pekdrw,95
+firstrade/account.py,sha256=U_-4Kg0veehd1-wo_KHNmScfD_xLFTilFZjIWUlByQM,19270
+firstrade/exceptions.py,sha256=17speAxfarT1U-k_HWvfUanpUk6U2bCZ2ag49MdWbw0,1928
+firstrade/order.py,sha256=K1-mpvu2ooUBxNtXkX_H8mdJMoRiUG1JDqsmpzfdFBQ,8530
+firstrade/symbols.py,sha256=v6ejLCLo3L_JzPRN3B2yMYn-5qBVCRG-3cx6Y7IMrb0,7466
+firstrade/urls.py,sha256=atalvLvevb1CAOBOdUIX3HAebw3TSRuIhCYFhSXIbQ8,3294
+firstrade-0.0.37.dist-info/licenses/LICENSE,sha256=wPEQjDqm5zMBmEcZp219Labmq_YIjhudpZiUzyVKaFA,1057
+firstrade-0.0.37.dist-info/METADATA,sha256=kpZfe0iUMNulPdNO0THdcOeRYFJBA6nKLsSGU7vaTr8,3238
+firstrade-0.0.37.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+firstrade-0.0.37.dist-info/top_level.txt,sha256=tdA8v-KDxU1u4VV6soiNWGBlni4ojv_t_j2wFn5nZcs,10
+firstrade-0.0.37.dist-info/RECORD,,

{firstrade-0.0.34.dist-info → firstrade-0.0.37.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

firstrade-0.0.34.dist-info/RECORD

@@ -1,11 +0,0 @@
-firstrade/__init__.py,sha256=fNiWYgSTjElY1MNv0Ug-sVLMTR2z_Ngri_FY7Pekdrw,95
-firstrade/account.py,sha256=4tS-m_85RW6E5YM6Srn9Wn-6TJKV0fDZYnMId7Rb5B4,15870
-firstrade/exceptions.py,sha256=OrWB83rc33LSxrI7WxXo4o7FcIfmvPSC9bAY8K1pn7U,1886
-firstrade/order.py,sha256=_b1SnqagwBu7KUmvzSUcp8iMOC3I3k-QDjiDLhlVk7E,8710
-firstrade/symbols.py,sha256=RH36QLx5v3rKPpBidyJFwGJSDkF5u5f2ILTSZNAGXGQ,7903
-firstrade/urls.py,sha256=Iw10isyvoqKwiSl3TVuIbos5INZzIEwpln3HcZ7P5aw,2125
-firstrade-0.0.34.dist-info/licenses/LICENSE,sha256=wPEQjDqm5zMBmEcZp219Labmq_YIjhudpZiUzyVKaFA,1057
-firstrade-0.0.34.dist-info/METADATA,sha256=cEo6oLxI6nGGQGTOM1wAfISYjt-5jZ1B_WirQsalSdc,3367
-firstrade-0.0.34.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-firstrade-0.0.34.dist-info/top_level.txt,sha256=tdA8v-KDxU1u4VV6soiNWGBlni4ojv_t_j2wFn5nZcs,10
-firstrade-0.0.34.dist-info/RECORD,,