etrade-python 1.0.0__py3-none-any.whl

etrade_python/client.py

@@ -0,0 +1,84 @@
+"""The client composition root."""
+
+import httpx
+
+from etrade_python.accounts.service import AccountsService
+from etrade_python.alerts.service import AlertsService
+from etrade_python.auth.oauth import OAuthClient
+from etrade_python.auth.session import SessionAuthenticator, SessionManager
+from etrade_python.auth.stores import CredentialStore, KeyringCredentialStore
+from etrade_python.config import ETradeSettings
+from etrade_python.exceptions import ETradeValidationError
+from etrade_python.market.service import MarketService
+from etrade_python.orders.service import OrdersService
+from etrade_python.portfolio.service import PortfolioService
+from etrade_python.transactions.service import TransactionsService
+from etrade_python.transport.auth import RequestAuthenticator
+from etrade_python.transport.http import ApiTransport
+from etrade_python.transport.retry import RetryPolicy
+
+
+class ETradeClient:
+    """Async client lifecycle with one HTTP client shared by auth and services."""
+
+    def __init__(
+        self,
+        settings: ETradeSettings,
+        *,
+        authenticator: RequestAuthenticator | None = None,
+        credential_store: CredentialStore | None = None,
+        profile: str = "default",
+        http_client: httpx.AsyncClient | None = None,
+        http_transport: httpx.AsyncBaseTransport | None = None,
+        retry_policy: RetryPolicy | None = None,
+    ) -> None:
+        if http_client is not None and http_transport is not None:
+            raise ETradeValidationError("Supply either http_client or http_transport, not both")
+        self._owns_client = http_client is None
+        self._http_client = http_client or httpx.AsyncClient(
+            transport=http_transport,
+            timeout=settings.request_timeout_seconds,
+            follow_redirects=False,
+            trust_env=False,
+        )
+        self.oauth = OAuthClient(settings, http_client=self._http_client)
+        self.session = SessionManager(
+            settings=settings,
+            oauth_client=self.oauth,
+            credential_store=credential_store or KeyringCredentialStore(),
+            profile=profile,
+        )
+        active_authenticator = authenticator or SessionAuthenticator(self.session, self.oauth)
+        self._transport = ApiTransport(
+            settings,
+            authenticator=active_authenticator,
+            http_client=self._http_client,
+            retry_policy=retry_policy,
+        )
+        self.accounts = AccountsService(self._transport)
+        self.portfolio = PortfolioService(self._transport)
+        self.transactions = TransactionsService(self._transport)
+        self.market = MarketService(self._transport)
+        self.orders = OrdersService(self._transport)
+        self.alerts = AlertsService(self._transport)
+        self._closed = False
+
+    @classmethod
+    def from_environment(cls) -> "ETradeClient":
+        """Load ETRADE_ variables; does not read .env files or authenticate."""
+        return cls(ETradeSettings())
+
+    async def __aenter__(self) -> "ETradeClient":
+        await self._transport.__aenter__()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if not self._closed:
+            self._closed = True
+            await self._transport.aclose()
+            await self.oauth.aclose()
+            if self._owns_client:
+                await self._http_client.aclose()

etrade_python/config.py

@@ -0,0 +1,43 @@
+"""Validated settings; dotenv loading is always explicit."""
+
+from typing import Any
+
+from pydantic import Field, SecretStr, ValidationError, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from etrade_python.enums import Environment
+from etrade_python.exceptions import ETradeValidationError
+
+
+class ETradeSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="ETRADE_", env_file=None, extra="ignore", frozen=True, hide_input_in_errors=True
+    )
+
+    consumer_key: SecretStr = Field(repr=False)
+    consumer_secret: SecretStr = Field(repr=False)
+    environment: Environment = Environment.SANDBOX
+    request_timeout_seconds: float = Field(default=30.0, gt=0, allow_inf_nan=False)
+    inactivity_buffer_seconds: int = Field(default=300, ge=0, lt=7200)
+
+    def __init__(self, **values: Any) -> None:
+        # Do not expose Pydantic error inputs through the normal constructor.
+        try:
+            super().__init__(**values)
+        except ValidationError as exc:
+            fields = sorted(
+                {
+                    str(part)
+                    for error in exc.errors(include_input=False, include_context=False)
+                    for part in error["loc"]
+                    if part in type(self).model_fields
+                }
+            )
+            raise ETradeValidationError("Invalid E*TRADE settings: " + ", ".join(fields)) from None
+
+    @field_validator("consumer_key", "consumer_secret")
+    @classmethod
+    def nonempty_secret(cls, value: SecretStr) -> SecretStr:
+        if not value.get_secret_value().strip():
+            raise ValueError("A nonempty credential is required")
+        return value

etrade_python/enums.py

@@ -0,0 +1,19 @@
+"""Configuration enums shared across API domains."""
+
+from enum import StrEnum
+
+
+class Environment(StrEnum):
+    SANDBOX = "sandbox"
+    PRODUCTION = "production"
+
+    @property
+    def api_base_url(self) -> str:
+        if self is Environment.PRODUCTION:
+            return "https://api.etrade.com"
+        return "https://apisb.etrade.com"
+
+
+# E*TRADE uses the same OAuth server for sandbox and production keys.
+OAUTH_BASE_URL = "https://api.etrade.com"
+AUTHORIZATION_URL = "https://us.etrade.com/e/t/etws/authorize"

etrade_python/exceptions.py

@@ -0,0 +1,68 @@
+"""Stable public errors. Never attach raw HTTP requests or responses."""
+
+
+class ETradeError(Exception):
+    """Base class for library failures."""
+
+
+class ETradeAuthenticationError(ETradeError):
+    """Authentication failed or is unavailable."""
+
+
+class AuthenticationRequired(ETradeAuthenticationError):
+    """Human authorization or an authentication provider is required."""
+
+
+class AuthorizationExpired(ETradeAuthenticationError):
+    """The daily authorization has expired."""
+
+
+class ETradeValidationError(ETradeError):
+    """Local settings or request arguments are invalid."""
+
+
+class ETradeApiError(ETradeError):
+    """Broker failure with sanitized diagnostic metadata."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        broker_code: str | None = None,
+        broker_message: str | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.broker_code = broker_code
+        self.broker_message = broker_message
+        self.request_id = request_id
+
+
+class ETradeRateLimitError(ETradeApiError):
+    """The broker rejected a request because of a rate limit."""
+
+
+class ETradeNotFoundError(ETradeApiError):
+    """The requested resource was not found."""
+
+
+class ETradeUnavailableError(ETradeApiError):
+    """The broker is temporarily unavailable."""
+
+
+class ETradeOrderError(ETradeApiError):
+    """An order operation was rejected."""
+
+
+class ETradeTransportError(ETradeError):
+    """The HTTP exchange failed; a mutation's outcome may be unknown."""
+
+
+class ETradeResponseError(ETradeApiError):
+    """The broker returned an invalid or unexpected response."""
+
+
+class ETradeHttpAuthenticationError(ETradeAuthenticationError, ETradeApiError):
+    """An HTTP authentication rejection, including sanitized broker metadata."""

etrade_python/market/__init__.py

@@ -0,0 +1,59 @@
+"""Market data service and models."""
+
+from etrade_python.market.models import (
+    ExtendedHourQuoteDetails,
+    LookupProduct,
+    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.market.service import MarketService
+
+__all__ = [
+    "SaleChargeValues",
+    "RedemptionValues",
+    "Redemption",
+    "QuoteMessages",
+    "QuoteMessage",
+    "OptionDeliverable",
+    "NetAsset",
+    "MutualFundQuoteDetails",
+    "ExtendedHourQuoteDetails",
+    "LookupProduct",
+    "MarketService",
+    "OptionChainPair",
+    "OptionChainRequest",
+    "OptionChainResponse",
+    "OptionContract",
+    "OptionExpiration",
+    "OptionExpirationsRequest",
+    "OptionExpirationsResponse",
+    "OptionGreeks",
+    "Product",
+    "ProductLookupRequest",
+    "ProductLookupResponse",
+    "Quote",
+    "QuoteDetails",
+    "QuotesRequest",
+    "QuotesResponse",
+]