alpaca-py-nopandas 0.1.0__py3-none-any.whl

alpaca/common/utils.py

@@ -0,0 +1,89 @@
+from typing import Union, Optional
+from uuid import UUID
+from datetime import datetime
+
+
+def validate_uuid_id_param(
+    id: Union[UUID, str],
+    var_name: Optional[str] = None,
+) -> UUID:
+    """
+    A small helper function to eliminate duplicate checks of various id parameters to ensure they are
+    valid UUIDs. Upcasts str instances that are valid UUIDs into UUID instances.
+
+    Args:
+        id (Union[UUID, str]): The parameter to be validated
+        var_name (Optional[str]): the name of the parameter you'd like to generate in the error message. Defaults to
+          using `account_id` due to it being the most commonly needed case
+
+    Returns:
+        UUID: The valid UUID instance
+    """
+
+    if var_name is None:
+        var_name = "account_id"
+
+    # should raise ValueError
+    if type(id) == str:
+        id = UUID(id)
+    elif type(id) != UUID:
+        raise ValueError(f"{var_name} must be a UUID or a UUID str")
+
+    return id
+
+
+def validate_symbol_or_asset_id(
+    symbol_or_asset_id: Union[UUID, str]
+) -> Union[UUID, str]:
+    """
+    A helper function to eliminate duplicate checks of symbols or asset ids.
+
+    If the argument given is a string, assumed to be a symbol name. If a UUID object, assumed to be an asset id.
+    ValueError if neither type.
+
+    Args:
+        symbol_or_asset_id: String representing a symbol name or a UUID representing an asset id.
+
+    Returns:
+        String if symbol, UUID if asset id.
+    """
+    if isinstance(symbol_or_asset_id, (UUID, str)):
+        return symbol_or_asset_id
+    raise ValueError(
+        "symbol_or_asset_id must be a UUID of an asset id or a string of a symbol."
+    )
+
+
+def validate_symbol_or_contract_id(
+    symbol_or_contract_id: Union[UUID, str]
+) -> Union[UUID, str]:
+    """
+    A helper function to eliminate duplicate checks of symbols or contract id.
+
+    If the argument given is a string, assumed to be a symbol name. If a UUID object, assumed to be a contract id.
+    ValueError if neither type.
+
+    Args:
+        symbol_or_contract_id: String representing a symbol name or a UUID representing a contract id.
+
+    Returns:
+        String if symbol, UUID if contract id.
+    """
+    if isinstance(symbol_or_contract_id, (UUID, str)):
+        return symbol_or_contract_id
+    raise ValueError(
+        "symbol_or_contract_id must be a UUID of a contract id or a string of a symbol."
+    )
+
+
+def tz_aware(dt: datetime) -> bool:
+    """
+    Returns if a given datetime is timezone aware
+
+    Args:
+        dt: the datetime to bo checked
+
+    Returns: timezone awareness
+
+    """
+    return dt.tzinfo is not None and dt.tzinfo.utcoffset(dt) is not None

alpaca/data/__init__.py

@@ -0,0 +1,5 @@
+from alpaca.data.enums import *
+from alpaca.data.models import *
+from alpaca.data.timeframe import *
+from alpaca.data.requests import *
+from alpaca.data.historical import *

alpaca/data/enums.py

@@ -0,0 +1,184 @@
+from enum import Enum
+
+
+class Exchange(str, Enum):
+    """The exchanges that provide data feeds to Alpaca.
+
+    Attributes:
+        Z (str): Cboe BZ
+        I (str): International Securities Exchange
+        M (str): Chicago Stock Exchange
+        U (str): Members Exchange
+        L (str): Long Term Stock Exchange
+        W (str): CBOE
+        X (str): NASDAQ OMX PSX
+        B (str): NASDAQ OMX BX
+        D (str): FINRA ADF
+        J (str): Cboe EDGA
+        P (str): NYSE Arca
+        Q (str): NASDAQ OMX
+        S (str): NASDAQ Small Cap
+        V (str): IEX
+        A (str): NYSE American (AMEX)
+        E (str): Market Independent
+        N (str): New York Stock Exchange
+        T (str): NASDAQ Int
+        Y (str): Cboe BYX
+        C (str): National Stock Exchange
+        H (str): MIAX
+        K (str): Cboe EDGX
+    """
+
+    Z = "Z"
+    I = "I"
+    M = "M"
+    U = "U"
+    L = "L"
+    W = "W"
+    X = "X"
+    B = "B"
+    D = "D"
+    J = "J"
+    P = "P"
+    Q = "Q"
+    S = "S"
+    V = "V"
+    A = "A"
+    E = "E"
+    N = "N"
+    T = "T"
+    Y = "Y"
+    C = "C"
+    H = "H"
+    K = "K"
+
+
+class DataFeed(str, Enum):
+    """Equity market data feeds. OTC and SIP are available with premium data subscriptions.
+
+    Attributes:
+        IEX (str): Investor's exchange data feed
+        SIP (str): Securities Information Processor feed
+        DELAYED_SIP (str): SIP data with a 15 minute delay
+        OTC (str): Over the counter feed
+        BOATS (str): Blue Ocean, overnight US trading data
+        OVERNIGHT (str): derived overnight US trading data
+    """
+
+    IEX = "iex"
+    SIP = "sip"
+    DELAYED_SIP = "delayed_sip"
+    OTC = "otc"
+    BOATS = "boats"
+    OVERNIGHT = "overnight"
+
+
+class Adjustment(str, Enum):
+    """Data normalization based on types of corporate actions.
+
+    Attributes:
+        RAW (str): Unadjusted data
+        SPLIT (str): Stock-split adjusted data
+        DIVIDEND (str): Dividend adjusted data
+        ALL (str): Data adjusted for all corporate actions
+    """
+
+    RAW = "raw"
+    SPLIT = "split"
+    DIVIDEND = "dividend"
+    ALL = "all"
+
+
+class CryptoFeed(str, Enum):
+    """
+    Crypto location
+
+    Attributes:
+        US (str): United States crypto feed
+    """
+
+    US = "us"
+
+
+class OptionsFeed(str, Enum):
+    """
+    The source feed of the data.
+    `opra` requires subscription
+
+    Attributes:
+        OPRA (str): Options Price Reporting Authority
+        INDICATIVE (str): Indicative data
+    """
+
+    OPRA = "opra"
+    INDICATIVE = "indicative"
+
+
+class MostActivesBy(str, Enum):
+    """
+    Most actives possible filters.
+
+    Attributes:
+        volume (str):
+            Retrieve most actives by trading volume.
+        trades (str):
+            Retrieve most actives by number of trades.
+    """
+
+    VOLUME = "volume"
+    TRADES = "trades"
+
+
+class MarketType(str, Enum):
+    """
+    Most actives possible filters.
+
+    Attributes:
+        stocks (str)
+        crypto (str)
+    """
+
+    STOCKS = "stocks"
+    CRYPTO = "crypto"
+
+
+class NewsImageSize(str, Enum):
+    THUMB = "thumb"
+    SMALL = "small"
+    LARGE = "large"
+
+
+class CorporateActionsType(str, Enum):
+    """
+    The type of corporate action.
+    ref. https://docs.alpaca.markets/reference/corporateactions-1
+
+    Attributes:
+        REVERSE_SPLIT (str): Reverse split
+        FORWARD_SPLIT (str): Forward split
+        UNIT_SPLIT (str): Unit split
+        CASH_DIVIDEND (str): Cash dividend
+        STOCK_DIVIDEND (str): Stock dividend
+        SPIN_OFF (str): Spin off
+        CASH_MERGER (str): Cash merger
+        STOCK_MERGER (str): Stock merger
+        STOCK_AND_CASH_MERGER (str): Stock and cash merger
+        REDEMPTION (str): Redemption
+        NAME_CHANGE (str): Name change
+        WORTHLESS_REMOVAL (str): Worthless removal
+        RIGHTS_DISTRIBUTION (str): Rights distribution
+    """
+
+    REVERSE_SPLIT = "reverse_split"
+    FORWARD_SPLIT = "forward_split"
+    UNIT_SPLIT = "unit_split"
+    CASH_DIVIDEND = "cash_dividend"
+    STOCK_DIVIDEND = "stock_dividend"
+    SPIN_OFF = "spin_off"
+    CASH_MERGER = "cash_merger"
+    STOCK_MERGER = "stock_merger"
+    STOCK_AND_CASH_MERGER = "stock_and_cash_merger"
+    REDEMPTION = "redemption"
+    NAME_CHANGE = "name_change"
+    WORTHLESS_REMOVAL = "worthless_removal"
+    RIGHTS_DISTRIBUTION = "rights_distribution"

alpaca/data/historical/__init__.py

@@ -0,0 +1,13 @@
+from alpaca.data.historical.crypto import CryptoHistoricalDataClient
+from alpaca.data.historical.news import NewsClient
+from alpaca.data.historical.option import OptionHistoricalDataClient
+from alpaca.data.historical.screener import ScreenerClient
+from alpaca.data.historical.stock import StockHistoricalDataClient
+
+__all__ = [
+    "CryptoHistoricalDataClient",
+    "StockHistoricalDataClient",
+    "NewsClient",
+    "OptionHistoricalDataClient",
+    "ScreenerClient",
+]

alpaca/data/historical/corporate_actions.py

@@ -0,0 +1,76 @@
+from typing import Optional, Union
+
+from alpaca.common.enums import BaseURL
+from alpaca.common.rest import RESTClient
+from alpaca.common.types import RawData
+from alpaca.data.models.corporate_actions import CorporateActionsSet
+from alpaca.data.requests import CorporateActionsRequest
+
+
+class CorporateActionsClient(RESTClient):
+    """
+    The REST client for interacting with Alpaca Corporate Actions API endpoints.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        oauth_token: Optional[str] = None,
+        use_basic_auth: bool = False,
+        raw_data: bool = False,
+        url_override: Optional[str] = None,
+    ) -> None:
+        """
+        Instantiates a Corporate Actions Client.
+
+        Args:
+            api_key (Optional[str], optional): Alpaca API key. Defaults to None.
+            secret_key (Optional[str], optional): Alpaca API secret key. Defaults to None.
+            oauth_token (Optional[str]): The oauth token if authenticating via OAuth. Defaults to None.
+            use_basic_auth (bool, optional): If true, API requests will use basic authorization headers.
+            raw_data (bool, optional): If true, API responses will not be wrapped and raw responses will be returned from
+              methods. Defaults to False. This has not been implemented yet.
+            url_override (Optional[str], optional): If specified allows you to override the base url the client points
+              to for proxy/testing.
+        """
+        super().__init__(
+            api_key=api_key,
+            secret_key=secret_key,
+            oauth_token=oauth_token,
+            use_basic_auth=use_basic_auth,
+            api_version="v1",
+            base_url=url_override if url_override is not None else BaseURL.DATA,
+            sandbox=False,
+            raw_data=raw_data,
+        )
+
+    def get_corporate_actions(
+        self, request_params: CorporateActionsRequest
+    ) -> Union[RawData, CorporateActionsSet]:
+        """Returns corporate actions data
+
+        Args:
+            request_params (CorporateActionsRequest): The request params to filter the corporate actions data
+        """
+        params = request_params.to_request_fields()
+
+        if request_params.symbols:
+            params["symbols"] = ",".join(request_params.symbols)
+        if request_params.cusips:
+            params["cusips"] = ",".join(request_params.cusips)
+        if request_params.types:
+            params["types"] = ",".join(request_params.types)
+        if request_params.ids:
+            params["ids"] = ",".join(request_params.ids)
+
+        response = self._get_marketdata(
+            path="/corporate-actions",
+            params=params,
+            page_limit=1000,
+            page_size=1000,
+        )
+        if self._use_raw_data:
+            return response
+
+        return CorporateActionsSet(response)

alpaca/data/historical/crypto.py

@@ -0,0 +1,299 @@
+from typing import Dict, Optional, Union
+
+from alpaca.common.enums import BaseURL
+from alpaca.common.rest import RESTClient
+from alpaca.common.types import Credentials, RawData
+from alpaca.data import Bar, Snapshot
+from alpaca.data.enums import CryptoFeed
+from alpaca.data.historical.utils import (
+    parse_obj_as_symbol_dict,
+)
+from alpaca.data.models import BarSet, Orderbook, Quote, QuoteSet, Trade, TradeSet
+from alpaca.data.requests import (
+    CryptoBarsRequest,
+    CryptoLatestBarRequest,
+    CryptoLatestOrderbookRequest,
+    CryptoLatestQuoteRequest,
+    CryptoLatestTradeRequest,
+    CryptoQuoteRequest,
+    CryptoSnapshotRequest,
+    CryptoTradesRequest,
+)
+
+
+class CryptoHistoricalDataClient(RESTClient):
+    """
+    A REST client for retrieving crypto market data.
+
+    This client does not need any authentication to use.
+    You can instantiate it with or without API keys.
+
+    However, authenticating increases your data rate limit.
+
+    Learn more about crypto historical data here:
+    https://alpaca.markets/docs/api-references/market-data-api/crypto-pricing-data/historical/
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        oauth_token: Optional[str] = None,
+        raw_data: bool = False,
+        url_override: Optional[str] = None,
+        use_basic_auth: bool = False,
+        sandbox: bool = False,
+    ) -> None:
+        """
+        Instantiates a Historical Data Client for Crypto Data.
+
+        Args:
+            api_key (Optional[str], optional): Alpaca API key. Defaults to None.
+            secret_key (Optional[str], optional): Alpaca API secret key. Defaults to None.
+            oauth_token (Optional[str]): The oauth token if authenticating via OAuth. Defaults to None.
+            raw_data (bool, optional): If true, API responses will not be wrapped and raw responses will be returned from
+              methods. Defaults to False. This has not been implemented yet.
+            url_override (Optional[str], optional): If specified allows you to override the base url the client points
+              to for proxy/testing.
+            use_basic_auth (bool, optional): If true, API requests will use basic authorization headers. Set to true if using
+              broker api sandbox credentials
+            sandbox (bool): True if using sandbox mode. Defaults to False.
+        """
+
+        base_url = (
+            url_override
+            if url_override is not None
+            else BaseURL.DATA_SANDBOX if sandbox else BaseURL.DATA
+        )
+
+        super().__init__(
+            api_key=api_key,
+            secret_key=secret_key,
+            oauth_token=oauth_token,
+            api_version="v1beta3",
+            base_url=base_url,
+            sandbox=sandbox,
+            raw_data=raw_data,
+            use_basic_auth=use_basic_auth,
+        )
+
+    def get_crypto_bars(
+        self, request_params: CryptoBarsRequest, feed: CryptoFeed = CryptoFeed.US
+    ) -> Union[BarSet, RawData]:
+        """Gets bar/candle data for a cryptocurrency or list of cryptocurrencies.
+
+        Args:
+            request_params (CryptoBarsRequest): The parameters for the request.
+            feed (CryptoFeed): The data feed for crypto bars.
+
+        Returns:
+            Union[BarSet, RawData]: The crypto bar data either in raw or wrapped form
+        """
+
+        # paginated get request for crypto market data api
+        raw_bars = self._get_marketdata(
+            path=f"/crypto/{feed.value}/bars",
+            params=request_params.to_request_fields(),
+            page_size=10_000,
+        )
+
+        if self._use_raw_data:
+            return raw_bars
+
+        return BarSet(raw_bars)
+
+    def get_crypto_quotes(
+        self, request_params: CryptoQuoteRequest, feed: CryptoFeed = CryptoFeed.US
+    ) -> Union[QuoteSet, RawData]:
+        """Returns the quote data for a cryptocurrency or list of cryptocurrencies.
+
+        Args:
+            request_params (CryptoQuoteRequest): The parameters for the request.
+            feed (CryptoFeed): The data feed for crypto quotes.
+
+        Returns:
+            Union[QuoteSet, RawData]: The crypto quote data either in raw or wrapped form
+        """
+
+        # paginated get request for market data api
+        raw_quotes = self._get_marketdata(
+            path=f"/crypto/{feed.value}/quotes",
+            params=request_params.to_request_fields(),
+            page_size=10_000,
+        )
+
+        if self._use_raw_data:
+            return raw_quotes
+
+        return QuoteSet(raw_quotes)
+
+    def get_crypto_trades(
+        self, request_params: CryptoTradesRequest, feed: CryptoFeed = CryptoFeed.US
+    ) -> Union[TradeSet, RawData]:
+        """Returns the price and sales history over a given time period for a cryptocurrency
+        or list of cryptocurrencies.
+
+        Args:
+            request_params (CryptoTradesRequest): The parameters for the request.
+            feed (CryptoFeed): The data feed for crypto trades.
+
+        Returns:
+            Union[TradeSet, RawData]: The trade data either in raw or wrapped form
+        """
+
+        # paginated get request for market data api
+        raw_trades = self._get_marketdata(
+            path=f"/crypto/{feed.value}/trades",
+            params=request_params.to_request_fields(),
+            page_size=10_000,
+        )
+
+        if self._use_raw_data:
+            return raw_trades
+
+        return TradeSet(raw_trades)
+
+    def get_crypto_latest_trade(
+        self, request_params: CryptoLatestTradeRequest, feed: CryptoFeed = CryptoFeed.US
+    ) -> Union[Dict[str, Trade], RawData]:
+        """Returns the latest trade for a coin.
+
+        Args:
+            request_params (CryptoLatestTradeRequest): The parameters for the request.
+            feed (CryptoFeed): The data feed for the latest crypto trade.
+
+        Returns:
+            Union[Dict[str, Trade], RawData]: The latest trade in raw or wrapped format
+        """
+
+        raw_trades = self._get_marketdata(
+            path=f"/crypto/{feed.value}/latest/trades",
+            params=request_params.to_request_fields(),
+        )
+
+        if self._use_raw_data:
+            return raw_trades
+
+        return parse_obj_as_symbol_dict(Trade, raw_trades)
+
+    def get_crypto_latest_quote(
+        self, request_params: CryptoLatestQuoteRequest, feed: CryptoFeed = CryptoFeed.US
+    ) -> Union[Dict[str, Quote], RawData]:
+        """Returns the latest quote for a coin.
+
+        Args:
+            request_params (CryptoLatestQuoteRequest): The parameters for the request.
+            feed (CryptoFeed): The data feed for the latest crypto quote.
+
+        Returns:
+            Union[Dict[str, Quote], RawData]: The latest quote in raw or wrapped format
+        """
+
+        raw_quotes = self._get_marketdata(
+            path=f"/crypto/{feed.value}/latest/quotes",
+            params=request_params.to_request_fields(),
+        )
+
+        if self._use_raw_data:
+            return raw_quotes
+
+        return parse_obj_as_symbol_dict(Quote, raw_quotes)
+
+    def get_crypto_latest_bar(
+        self, request_params: CryptoLatestBarRequest, feed: CryptoFeed = CryptoFeed.US
+    ) -> Union[Dict[str, Bar], RawData]:
+        """Returns the latest minute bar for a coin.
+
+        Args:
+            request_params (CryptoLatestBarRequest): The parameters for the request.
+            feed (CryptoFeed): The data feed for the latest crypto bar.
+
+        Returns:
+            Union[Dict[str, Bar], RawData]: The latest bar in raw or wrapped format
+        """
+
+        raw_bars = self._get_marketdata(
+            path=f"/crypto/{feed.value}/latest/bars",
+            params=request_params.to_request_fields(),
+        )
+
+        if self._use_raw_data:
+            return raw_bars
+
+        return parse_obj_as_symbol_dict(Bar, raw_bars)
+
+    def get_crypto_latest_orderbook(
+        self,
+        request_params: CryptoLatestOrderbookRequest,
+        feed: CryptoFeed = CryptoFeed.US,
+    ) -> Union[Dict[str, Orderbook], RawData]:
+        """
+        Returns the latest orderbook state for the queried crypto symbols.
+
+        Args:
+            request_params (CryptoOrderbookRequest): The parameters for the orderbook request.
+            feed (CryptoFeed): The data feed for the latest crypto orderbook.
+
+        Returns:
+            Union[Dict[str, Orderbook], RawData]: The orderbook data either in raw or wrapped form.
+        """
+
+        raw_orderbooks = self._get_marketdata(
+            path=f"/crypto/{feed.value}/latest/orderbooks",
+            params=request_params.to_request_fields(),
+        )
+
+        if self._use_raw_data:
+            return raw_orderbooks
+
+        return parse_obj_as_symbol_dict(Orderbook, raw_orderbooks)
+
+    def get_crypto_snapshot(
+        self, request_params: CryptoSnapshotRequest, feed: CryptoFeed = CryptoFeed.US
+    ) -> Union[Snapshot, RawData]:
+        """Returns snapshots of queried crypto symbols. Snapshots contain latest trade, latest quote, latest minute bar,
+        latest daily bar and previous daily bar data for the queried symbols.
+
+        Args:
+            request_params (CryptoSnapshotRequest): The parameters for the snapshot request.
+            feed (CryptoFeed): The data feed for crypto snapshots.
+
+        Returns:
+            Union[SnapshotSet, RawData]: The snapshot data either in raw or wrapped form
+        """
+
+        raw_snapshots = self._get_marketdata(
+            path=f"/crypto/{feed.value}/snapshots",
+            params=request_params.to_request_fields(),
+        )
+
+        if self._use_raw_data:
+            return raw_snapshots
+
+        return parse_obj_as_symbol_dict(Snapshot, raw_snapshots)
+
+    # We override the _validate_credentials static method for crypto,
+    # because crypto does not actually require authentication.
+    @staticmethod
+    def _validate_credentials(
+        api_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        oauth_token: Optional[str] = None,
+    ) -> Credentials:
+        """Gathers API credentials from parameters and environment variables, and validates them.
+        Args:
+            api_key (Optional[str]): The API key for authentication. Defaults to None.
+            secret_key (Optional[str]): The secret key for authentication. Defaults to None.
+            oauth_token (Optional[str]): The oauth token if authenticating via OAuth. Defaults to None.
+        Raises:
+             ValueError: If the combination of keys and tokens provided are not valid.
+        Returns:
+            Credentials: The set of validated authentication keys
+        """
+
+        if oauth_token and (api_key or secret_key):
+            raise ValueError(
+                "Either an oauth_token or an api_key may be supplied, but not both"
+            )
+
+        return api_key, secret_key, oauth_token