etrade-python 1.0.0__py3-none-any.whl

etrade_python/__init__.py

@@ -0,0 +1,264 @@
+"""Unofficial async E*TRADE client."""
+
+from etrade_python._version import __version__ as __version__
+from etrade_python.accounts import (
+    Account,
+    AccountBalanceRequest,
+    AccountBalanceResponse,
+    AccountListResponse,
+    AccountsService,
+)
+from etrade_python.alerts import (
+    Alert,
+    AlertDetailsRequest,
+    AlertDetailsResponse,
+    AlertsRequest,
+    AlertsResponse,
+    AlertsService,
+    DeleteAlertsResponse,
+    FailedAlerts,
+)
+from etrade_python.auth import (
+    AuthorizationUrl,
+    CredentialStore,
+    ETradeCredentials,
+    KeyringCredentialStore,
+    MemoryCredentialStore,
+    OAuthClient,
+    RenewalResult,
+    RequestToken,
+    RevocationResult,
+    SessionAuthenticator,
+    SessionManager,
+    TokenStatus,
+)
+from etrade_python.client import ETradeClient
+from etrade_python.config import ETradeSettings
+from etrade_python.enums import Environment
+from etrade_python.exceptions import (
+    AuthenticationRequired,
+    AuthorizationExpired,
+    ETradeApiError,
+    ETradeAuthenticationError,
+    ETradeError,
+    ETradeHttpAuthenticationError,
+    ETradeNotFoundError,
+    ETradeOrderError,
+    ETradeRateLimitError,
+    ETradeResponseError,
+    ETradeTransportError,
+    ETradeUnavailableError,
+    ETradeValidationError,
+)
+from etrade_python.market import (
+    ExtendedHourQuoteDetails,
+    LookupProduct,
+    MarketService,
+    MutualFundQuoteDetails,
+    NetAsset,
+    OptionChainPair,
+    OptionChainRequest,
+    OptionChainResponse,
+    OptionContract,
+    OptionDeliverable,
+    OptionExpiration,
+    OptionExpirationsRequest,
+    OptionExpirationsResponse,
+    OptionGreeks,
+    Product,
+    ProductLookupRequest,
+    ProductLookupResponse,
+    Quote,
+    QuoteDetails,
+    QuoteMessage,
+    QuoteMessages,
+    QuotesRequest,
+    QuotesResponse,
+    Redemption,
+    RedemptionValues,
+    SaleChargeValues,
+)
+from etrade_python.orders import (
+    CancelOrderRequest,
+    CancelOrderResponse,
+    CashBuyingPowerDetails,
+    Disclosure,
+    DtBuyingPowerDetails,
+    Events,
+    MarginBuyingPowerDetails,
+    Message,
+    Messages,
+    MFQuantity,
+    Order,
+    OrderBuilder,
+    OrderBuyPowerEffect,
+    OrderDetail,
+    OrderDetailRequest,
+    OrderEvent,
+    OrderId,
+    OrderInstrument,
+    OrderInstrumentRequest,
+    OrderLot,
+    OrderLots,
+    OrderProduct,
+    OrderProductId,
+    OrderResponseId,
+    OrderResponseProduct,
+    OrdersRequest,
+    OrdersResponse,
+    OrdersService,
+    PlaceOrderRequest,
+    PlaceOrderResponse,
+    PortfolioMargin,
+    PreviewId,
+    PreviewOrderRequest,
+    PreviewOrderResponse,
+    PreviewResponseId,
+)
+from etrade_python.portfolio import (
+    AccountPortfolio,
+    CompleteView,
+    FundamentalView,
+    OptionsWatchView,
+    PerformanceView,
+    PortfolioProduct,
+    PortfolioRequest,
+    PortfolioResponse,
+    PortfolioService,
+    PortfolioTotals,
+    Position,
+    PositionLot,
+    QuickView,
+)
+from etrade_python.transactions import (
+    Transaction,
+    TransactionDetailsRequest,
+    TransactionDetailsResponse,
+    TransactionsRequest,
+    TransactionsResponse,
+    TransactionsService,
+)
+
+__all__ = [
+    "PreviewResponseId",
+    "OrderResponseId",
+    "OrderResponseProduct",
+    "QuickView",
+    "PortfolioTotals",
+    "PortfolioProduct",
+    "PerformanceView",
+    "OptionsWatchView",
+    "FundamentalView",
+    "CompleteView",
+    "AccountPortfolio",
+    "PortfolioMargin",
+    "OrderProductId",
+    "MarginBuyingPowerDetails",
+    "DtBuyingPowerDetails",
+    "CashBuyingPowerDetails",
+    "SaleChargeValues",
+    "RedemptionValues",
+    "Redemption",
+    "QuoteMessages",
+    "QuoteMessage",
+    "OptionDeliverable",
+    "NetAsset",
+    "MutualFundQuoteDetails",
+    "ExtendedHourQuoteDetails",
+    "Alert",
+    "AlertDetailsRequest",
+    "AlertDetailsResponse",
+    "AlertsRequest",
+    "AlertsResponse",
+    "AlertsService",
+    "DeleteAlertsResponse",
+    "FailedAlerts",
+    "OrderBuilder",
+    "PreviewOrderResponse",
+    "PreviewOrderRequest",
+    "PreviewId",
+    "PlaceOrderResponse",
+    "PlaceOrderRequest",
+    "OrdersService",
+    "OrdersResponse",
+    "OrdersRequest",
+    "OrderProduct",
+    "OrderLots",
+    "OrderLot",
+    "OrderInstrumentRequest",
+    "OrderInstrument",
+    "OrderId",
+    "OrderEvent",
+    "OrderDetailRequest",
+    "OrderDetail",
+    "OrderBuyPowerEffect",
+    "Order",
+    "MFQuantity",
+    "Messages",
+    "Message",
+    "Events",
+    "Disclosure",
+    "CancelOrderResponse",
+    "CancelOrderRequest",
+    "AuthenticationRequired",
+    "Account",
+    "AccountBalanceRequest",
+    "AccountBalanceResponse",
+    "AccountListResponse",
+    "AccountsService",
+    "AuthorizationUrl",
+    "AuthorizationExpired",
+    "CredentialStore",
+    "ETradeApiError",
+    "ETradeAuthenticationError",
+    "ETradeClient",
+    "ETradeCredentials",
+    "ETradeError",
+    "ETradeHttpAuthenticationError",
+    "ETradeNotFoundError",
+    "ETradeOrderError",
+    "ETradeRateLimitError",
+    "ETradeResponseError",
+    "ETradeSettings",
+    "ETradeTransportError",
+    "ETradeUnavailableError",
+    "ETradeValidationError",
+    "Environment",
+    "KeyringCredentialStore",
+    "LookupProduct",
+    "MarketService",
+    "OptionChainPair",
+    "OptionChainRequest",
+    "OptionChainResponse",
+    "OptionContract",
+    "OptionExpiration",
+    "OptionExpirationsRequest",
+    "OptionExpirationsResponse",
+    "OptionGreeks",
+    "Product",
+    "ProductLookupRequest",
+    "ProductLookupResponse",
+    "Quote",
+    "QuoteDetails",
+    "QuotesRequest",
+    "QuotesResponse",
+    "MemoryCredentialStore",
+    "PortfolioRequest",
+    "PortfolioResponse",
+    "PortfolioService",
+    "Position",
+    "PositionLot",
+    "Transaction",
+    "TransactionDetailsRequest",
+    "TransactionDetailsResponse",
+    "TransactionsRequest",
+    "TransactionsResponse",
+    "TransactionsService",
+    "OAuthClient",
+    "RenewalResult",
+    "RequestToken",
+    "RevocationResult",
+    "SessionAuthenticator",
+    "SessionManager",
+    "TokenStatus",
+]

etrade_python/_dates.py

@@ -0,0 +1,152 @@
+"""Internal helpers for parsing broker date/time values."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, date, datetime, time, timedelta, timezone
+from typing import Any
+
+# E*TRADE's Getting Started guide specifies US Eastern Time (EST/EDT),
+# but its quote documentation includes a PDT example. Additional abbreviations
+# and numeric offsets improve compatibility; this is not universal timezone support.
+# Abbreviations use their US meanings; explicit labels determine the offset.
+_QUOTE_TIMEZONE_HOURS = {
+    "EST": -5,
+    "EDT": -4,
+    "CST": -6,
+    "CDT": -5,
+    "MST": -7,
+    "MDT": -6,
+    "PST": -8,
+    "PDT": -7,
+    "UTC": 0,
+    "GMT": 0,
+}
+
+
+def parse_broker_datetime(value: Any) -> datetime | None:
+    """Parse an E*TRADE date/time value into a timezone-aware datetime.
+
+    E*TRADE responses commonly encode date/time fields as epoch milliseconds,
+    epoch seconds, compact numeric dates, or broker-specific timestamp strings.
+    """
+    if value is None or value == "":
+        return None
+
+    if isinstance(value, datetime):
+        return _ensure_timezone(value)
+
+    if isinstance(value, date):
+        return datetime.combine(value, time.min, tzinfo=UTC)
+
+    if isinstance(value, int | float):
+        return _parse_numeric_datetime(value)
+
+    if isinstance(value, str):
+        trimmed = value.strip()
+        if not trimmed:
+            return None
+        if _is_numeric_string(trimmed):
+            return _parse_numeric_datetime(int(trimmed))
+        return _parse_string_datetime(trimmed)
+
+    return None
+
+
+def parse_broker_date(value: Any) -> date | None:
+    """Parse an E*TRADE date/time value into a date."""
+    parsed = parse_broker_datetime(value)
+    if parsed is None:
+        return None
+    return parsed.date()
+
+
+def _parse_numeric_datetime(value: int | float) -> datetime | None:
+    integer = int(value)
+    if integer == 0:
+        return None
+
+    digits = str(abs(integer))
+    length = len(digits)
+
+    if length >= 13:
+        return datetime.fromtimestamp(integer / 1000, tz=UTC)
+
+    if length == 8:
+        try:
+            parsed_date = datetime.strptime(digits, "%Y%m%d").date()
+        except ValueError:
+            return None
+        return datetime.combine(parsed_date, time.min, tzinfo=UTC)
+
+    if length in {4, 6}:
+        time_format = "%H%M%S" if length == 6 else "%H%M"
+        try:
+            parsed_time = datetime.strptime(digits, time_format).time()
+        except ValueError:
+            return None
+        return datetime.combine(date.today(), parsed_time, tzinfo=UTC)
+
+    return datetime.fromtimestamp(integer, tz=UTC)
+
+
+def _parse_string_datetime(value: str) -> datetime | None:
+    for candidate in _string_datetime_candidates(value):
+        try:
+            parsed = datetime.fromisoformat(candidate)
+        except ValueError:
+            continue
+        return _ensure_timezone(parsed)
+
+    quote_datetime = _parse_quote_datetime(value)
+    if quote_datetime is not None:
+        return quote_datetime
+
+    for fmt in ("%Y-%m-%d", "%m/%d/%Y", "%m-%d-%Y"):
+        try:
+            parsed = datetime.strptime(value, fmt)
+        except ValueError:
+            continue
+        return _ensure_timezone(parsed)
+
+    return None
+
+
+def _parse_quote_datetime(value: str) -> datetime | None:
+    parts = value.split()
+    if len(parts) != 3:
+        return None
+    try:
+        parsed = datetime.strptime(f"{parts[0]} {parts[2]}", "%H:%M:%S %m-%d-%Y")
+    except ValueError:
+        return None
+    label = parts[1]
+    if label in _QUOTE_TIMEZONE_HOURS:
+        offset = timedelta(hours=_QUOTE_TIMEZONE_HOURS[label])
+    else:
+        match = re.fullmatch(r"([+-])([0-9]{2}):?([0-9]{2})", label)
+        if match is None:
+            raise ValueError("Unsupported or invalid quote timestamp timezone")
+        hours, minutes = int(match[2]), int(match[3])
+        if hours > 23 or minutes > 59:
+            raise ValueError("Unsupported or invalid quote timestamp timezone")
+        offset = timedelta(hours=hours, minutes=minutes)
+        if match[1] == "-":
+            offset = -offset
+    return parsed.replace(tzinfo=timezone(offset)).astimezone(UTC)
+
+
+def _string_datetime_candidates(value: str) -> tuple[str, ...]:
+    if value.endswith("Z"):
+        return (value[:-1] + "+00:00", value)
+    return (value,)
+
+
+def _ensure_timezone(value: datetime) -> datetime:
+    if value.tzinfo is None:
+        return value.replace(tzinfo=UTC)
+    return value.astimezone(UTC)
+
+
+def _is_numeric_string(value: str) -> bool:
+    return value.isdecimal() or (value.startswith("-") and value[1:].isdecimal())

etrade_python/_version.py

@@ -0,0 +1,3 @@
+"""Runtime version shared by the public package and HTTP transport."""
+
+__version__ = "1.0.0"

etrade_python/accounts/__init__.py

@@ -0,0 +1,31 @@
+"""Accounts API service and models."""
+
+from etrade_python.accounts.models import (
+    Account,
+    AccountBalanceRequest,
+    AccountBalanceResponse,
+    AccountListResponse,
+    CashBalance,
+    ComputedBalance,
+    LendingBalance,
+    MarginBalance,
+    OpenCalls,
+    PortfolioMargin,
+    RealTimeValues,
+)
+from etrade_python.accounts.service import AccountsService
+
+__all__ = [
+    "Account",
+    "AccountBalanceRequest",
+    "AccountBalanceResponse",
+    "AccountListResponse",
+    "AccountsService",
+    "CashBalance",
+    "ComputedBalance",
+    "LendingBalance",
+    "MarginBalance",
+    "OpenCalls",
+    "PortfolioMargin",
+    "RealTimeValues",
+]

etrade_python/accounts/models.py

@@ -0,0 +1,204 @@
+"""Typed account request and response models."""
+
+from datetime import date
+from decimal import Decimal
+from typing import Any, cast
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from etrade_python._dates import parse_broker_date
+
+
+class BrokerModel(BaseModel):
+    """Base response model that discards unmodeled broker fields."""
+
+    model_config = ConfigDict(extra="ignore", frozen=True, populate_by_name=True)
+
+
+class AccountBalanceRequest(BaseModel):
+    """Query parameters for the account balance endpoint."""
+
+    model_config = ConfigDict(frozen=True)
+
+    inst_type: str = "BROKERAGE"
+    account_type: str | None = None
+    real_time_nav: bool = False
+
+    @field_validator("inst_type", "account_type")
+    @classmethod
+    def nonempty_string(cls, value: str | None) -> str | None:
+        if value is not None and not value.strip():
+            raise ValueError("A nonempty value is required")
+        return value
+
+    def query_params(self) -> dict[str, str | bool | None]:
+        return {
+            "instType": self.inst_type,
+            "accountType": self.account_type,
+            "realTimeNAV": self.real_time_nav,
+        }
+
+
+class Account(BrokerModel):
+    inst_no: int | None = Field(default=None, alias="instNo")
+    account_id: str = Field(alias="accountId")
+    account_id_key: str = Field(alias="accountIdKey")
+    account_mode: str | None = Field(default=None, alias="accountMode")
+    account_desc: str | None = Field(default=None, alias="accountDesc")
+    account_name: str | None = Field(default=None, alias="accountName")
+    account_type: str | None = Field(default=None, alias="accountType")
+    institution_type: str | None = Field(default=None, alias="institutionType")
+    account_status: str | None = Field(default=None, alias="accountStatus")
+    closed_date: date | None = Field(default=None, alias="closedDate")
+    shareworks_account: bool | None = Field(default=None, alias="shareWorksAccount")
+    shareworks_source: str | None = Field(default=None, alias="shareWorksSource")
+    fc_managed_mssb_closed_account: bool | None = Field(
+        default=None, alias="fcManagedMssbClosedAccount"
+    )
+
+    @field_validator("closed_date", mode="before")
+    @classmethod
+    def parse_closed_date(cls, value: object) -> date | None:
+        return parse_broker_date(value)
+
+
+def _empty_accounts() -> list[Account]:
+    return []
+
+
+class AccountListResponse(BrokerModel):
+    accounts: list[Account] = Field(default_factory=_empty_accounts)
+
+
+class CashBalance(BrokerModel):
+    funds_for_open_orders_cash: Decimal | None = Field(default=None, alias="fundsForOpenOrdersCash")
+    money_market_balance: Decimal | None = Field(default=None, alias="moneyMktBalance")
+
+
+class OpenCalls(BrokerModel):
+    min_equity_call: Decimal | None = Field(default=None, alias="minEquityCall")
+    fed_call: Decimal | None = Field(default=None, alias="fedCall")
+    cash_call: Decimal | None = Field(default=None, alias="cashCall")
+    house_call: Decimal | None = Field(default=None, alias="houseCall")
+
+
+class RealTimeValues(BrokerModel):
+    total_account_value: Decimal | None = Field(default=None, alias="totalAccountValue")
+    net_market_value: Decimal | None = Field(default=None, alias="netMv")
+    net_market_value_long: Decimal | None = Field(default=None, alias="netMvLong")
+    net_market_value_short: Decimal | None = Field(default=None, alias="netMvShort")
+    total_long_value: Decimal | None = Field(default=None, alias="totalLongValue")
+
+
+class PortfolioMargin(BrokerModel):
+    dt_cash_open_order_reserve: Decimal | None = Field(default=None, alias="dtCashOpenOrderReserve")
+    dt_margin_open_order_reserve: Decimal | None = Field(
+        default=None, alias="dtMarginOpenOrderReserve"
+    )
+    liquidating_equity: Decimal | None = Field(default=None, alias="liquidatingEquity")
+    house_excess_equity: Decimal | None = Field(default=None, alias="houseExcessEquity")
+    total_house_requirement: Decimal | None = Field(default=None, alias="totalHouseRequirement")
+    excess_equity_minus_requirement: Decimal | None = Field(
+        default=None, alias="excessEquityMinusRequirement"
+    )
+    total_margin_requirements: Decimal | None = Field(default=None, alias="totalMarginRqmts")
+    available_excess_equity: Decimal | None = Field(default=None, alias="availExcessEquity")
+    excess_equity: Decimal | None = Field(default=None, alias="excessEquity")
+    open_order_reserve: Decimal | None = Field(default=None, alias="openOrderReserve")
+    funds_on_hold: Decimal | None = Field(default=None, alias="fundsOnHold")
+
+
+class ComputedBalance(BrokerModel):
+    cash_available_for_investment: Decimal | None = Field(
+        default=None, alias="cashAvailableForInvestment"
+    )
+    cash_available_for_withdrawal: Decimal | None = Field(
+        default=None, alias="cashAvailableForWithdrawal"
+    )
+    total_available_for_withdrawal: Decimal | None = Field(
+        default=None, alias="totalAvailableForWithdrawal"
+    )
+    net_cash: Decimal | None = Field(default=None, alias="netCash")
+    cash_balance: Decimal | None = Field(default=None, alias="cashBalance")
+    settled_cash_for_investment: Decimal | None = Field(
+        default=None, alias="settledCashForInvestment"
+    )
+    unsettled_cash_for_investment: Decimal | None = Field(
+        default=None, alias="unSettledCashForInvestment"
+    )
+    funds_withheld_from_purchase_power: Decimal | None = Field(
+        default=None, alias="fundsWithheldFromPurchasePower"
+    )
+    funds_withheld_from_withdrawal: Decimal | None = Field(
+        default=None, alias="fundsWithheldFromWithdrawal"
+    )
+    margin_buying_power: Decimal | None = Field(default=None, alias="marginBuyingPower")
+    cash_buying_power: Decimal | None = Field(default=None, alias="cashBuyingPower")
+    day_trade_margin_buying_power: Decimal | None = Field(default=None, alias="dtMarginBuyingPower")
+    day_trade_cash_buying_power: Decimal | None = Field(default=None, alias="dtCashBuyingPower")
+    margin_balance: Decimal | None = Field(default=None, alias="marginBalance")
+    short_adjust_balance: Decimal | None = Field(default=None, alias="shortAdjustBalance")
+    regulation_t_equity: Decimal | None = Field(default=None, alias="regtEquity")
+    regulation_t_equity_percent: Decimal | None = Field(default=None, alias="regtEquityPercent")
+    account_balance: Decimal | None = Field(default=None, alias="accountBalance")
+    open_calls: OpenCalls | None = Field(default=None, alias="openCalls")
+    real_time_values: RealTimeValues | None = Field(default=None, alias="realTimeValues")
+    portfolio_margin: PortfolioMargin | None = Field(default=None, alias="portfolioMargin")
+
+
+class LendingBalance(BrokerModel):
+    current_balance: Decimal | None = Field(default=None, alias="currentBalance")
+    credit_line: Decimal | None = Field(default=None, alias="creditLine")
+    outstanding_balance: Decimal | None = Field(default=None, alias="outstandingBalance")
+    minimum_payment_due: Decimal | None = Field(default=None, alias="minPaymentDue")
+    amount_past_due: Decimal | None = Field(default=None, alias="amountPastDue")
+    available_credit: Decimal | None = Field(default=None, alias="availableCredit")
+    ytd_interest_paid: Decimal | None = Field(default=None, alias="ytdInterestPaid")
+    last_ytd_interest_paid: Decimal | None = Field(default=None, alias="lastYtdInterestPaid")
+    payment_due_date: date | None = Field(default=None, alias="paymentDueDate")
+    last_payment_received_date: date | None = Field(default=None, alias="lastPaymentReceivedDate")
+    payment_received_month_to_date: Decimal | None = Field(default=None, alias="paymentReceivedMtd")
+
+    @field_validator("payment_due_date", "last_payment_received_date", mode="before")
+    @classmethod
+    def parse_lending_dates(cls, value: object) -> date | None:
+        return parse_broker_date(value)
+
+
+class MarginBalance(BrokerModel):
+    dt_cash_open_order_reserve: Decimal | None = Field(default=None, alias="dtCashOpenOrderReserve")
+    dt_margin_open_order_reserve: Decimal | None = Field(
+        default=None, alias="dtMarginOpenOrderReserve"
+    )
+
+
+class AccountBalanceResponse(BrokerModel):
+    account_id: str = Field(alias="accountId")
+    institution_type: str | None = Field(default=None, alias="institutionType")
+    as_of_date: date | None = Field(default=None, alias="asOfDate")
+    account_type: str | None = Field(default=None, alias="accountType")
+    option_level: str | None = Field(default=None, alias="optionLevel")
+    account_description: str | None = Field(default=None, alias="accountDescription")
+    quote_mode: int | None = Field(default=None, alias="quoteMode")
+    day_trader_status: str | None = Field(default=None, alias="dayTraderStatus")
+    account_mode: str | None = Field(default=None, alias="accountMode")
+    account_desc: str | None = Field(default=None, alias="accountDesc")
+    open_calls: list[OpenCalls] = Field(default_factory=lambda: [], alias="openCalls")
+    cash: CashBalance | None = Field(default=None, alias="cash")
+    margin: MarginBalance | None = Field(default=None, alias="margin")
+    lending: LendingBalance | None = Field(default=None, alias="lending")
+    computed_balance: ComputedBalance | None = Field(default=None, alias="computedBalance")
+
+    @field_validator("as_of_date", mode="before")
+    @classmethod
+    def parse_as_of_date(cls, value: object) -> date | None:
+        return parse_broker_date(value)
+
+    @field_validator("open_calls", mode="before")
+    @classmethod
+    def normalize_open_calls(cls, value: object) -> object:
+        if value is None:
+            return []
+        if isinstance(value, dict):
+            return [cast(dict[str, Any], value)]
+        return value