diff --git a/polygon/rest/__init__.py b/polygon/rest/__init__.py index a04cf1d0..a101edf1 100644 --- a/polygon/rest/__init__.py +++ b/polygon/rest/__init__.py @@ -1,10 +1,16 @@ from .aggs import AggsClient from .trades import TradesClient from .quotes import QuotesClient -from .reference import MarketsClient, TickersClient, SplitsClient +from .reference import MarketsClient, TickersClient, SplitsClient, DividendsClient class RESTClient( - AggsClient, TradesClient, QuotesClient, MarketsClient, TickersClient, SplitsClient + AggsClient, + TradesClient, + QuotesClient, + MarketsClient, + TickersClient, + SplitsClient, + DividendsClient, ): pass diff --git a/polygon/rest/models/__init__.py b/polygon/rest/models/__init__.py index 914cc3a6..a6a9c916 100644 --- a/polygon/rest/models/__init__.py +++ b/polygon/rest/models/__init__.py @@ -4,6 +4,7 @@ from .markets import * from .tickers import * from .splits import * +from .dividends import * from enum import Enum diff --git a/polygon/rest/models/dividends.py b/polygon/rest/models/dividends.py new file mode 100644 index 00000000..b691812a --- /dev/null +++ b/polygon/rest/models/dividends.py @@ -0,0 +1,35 @@ +from typing import Optional +from enum import Enum +from dataclasses import dataclass + + +class DividendType(Enum): + CD = "CD" + SC = "SC" + LT = "LT" + ST = "ST" + + +class Frequency(Enum): + OneTime = 0 + Anually = 1 + BiAnually = 2 + Quarterly = 4 + Monthly = 12 + + +@dataclass +class Dividend: + "Dividend contains data for a historical cash dividend, including the ticker symbol, declaration date, ex-dividend date, record date, pay date, frequency, and amount." + cash_amount: Optional[float] = None + declaration_date: Optional[str] = None + dividend_type: Optional[DividendType] = None + ex_dividend_date: Optional[str] = None + frequency: Optional[Frequency] = None + pay_date: Optional[str] = None + record_date: Optional[str] = None + ticker: Optional[str] = None + + @staticmethod + def from_dict(d): + return Dividend(**d) diff --git a/polygon/rest/reference.py b/polygon/rest/reference.py index 40c915f2..bcf0a8ac 100644 --- a/polygon/rest/reference.py +++ b/polygon/rest/reference.py @@ -1,3 +1,4 @@ +from polygon.rest.models.dividends import DividendType from .base import BaseClient from typing import Optional, Any, Dict, List, Union, Iterator from .models import ( @@ -12,6 +13,8 @@ AssetClass, Locale, Split, + Dividend, + Frequency, ) from urllib3 import HTTPResponse @@ -187,10 +190,10 @@ def list_splits( ticker_gt: Optional[str] = None, ticker_gte: Optional[str] = None, execution_date: Optional[str] = None, - execution_lt: Optional[str] = None, - execution_lte: Optional[str] = None, - execution_gt: Optional[str] = None, - execution_gte: Optional[str] = None, + execution_date_lt: Optional[str] = None, + execution_date_lte: Optional[str] = None, + execution_date_gt: Optional[str] = None, + execution_date_gte: Optional[str] = None, reverse_split: Optional[bool] = None, limit: Optional[int] = None, sort: Optional[Union[str, Sort]] = None, @@ -227,3 +230,92 @@ def list_splits( raw=raw, deserializer=Split.from_dict, ) + + +class DividendsClient(BaseClient): + def list_dividends( + self, + ticker: Optional[str] = None, + ticker_lt: Optional[str] = None, + ticker_lte: Optional[str] = None, + ticker_gt: Optional[str] = None, + ticker_gte: Optional[str] = None, + ex_dividend_date: Optional[str] = None, + ex_dividend_date_lt: Optional[str] = None, + ex_dividend_date_lte: Optional[str] = None, + ex_dividend_date_gt: Optional[str] = None, + ex_dividend_date_gte: Optional[str] = None, + record_date: Optional[str] = None, + record_date_lt: Optional[str] = None, + record_date_lte: Optional[str] = None, + record_date_gt: Optional[str] = None, + record_date_gte: Optional[str] = None, + declaration_date: Optional[str] = None, + declaration_date_lt: Optional[str] = None, + declaration_date_lte: Optional[str] = None, + declaration_date_gt: Optional[str] = None, + declaration_date_gte: Optional[str] = None, + pay_date: Optional[str] = None, + pay_date_lt: Optional[str] = None, + pay_date_lte: Optional[str] = None, + pay_date_gt: Optional[str] = None, + pay_date_gte: Optional[str] = None, + frequency: Optional[Frequency] = None, + cash_amount: Optional[float] = None, + cash_amount_lt: Optional[float] = None, + cash_amount_lte: Optional[float] = None, + cash_amount_gt: Optional[float] = None, + cash_amount_gte: Optional[float] = None, + dividend_type: Optional[DividendType] = None, + limit: Optional[int] = None, + sort: Optional[Union[str, Sort]] = None, + order: Optional[Union[str, Order]] = None, + params: Optional[Dict[str, Any]] = None, + raw: bool = False, + ) -> Union[Iterator[Dividend], HTTPResponse]: + """ + Get a list of historical cash dividends, including the ticker symbol, declaration date, ex-dividend date, record date, pay date, frequency, and amount. + + :param ticker: Return the dividends that contain this ticker. + :param ticker_lt: Ticker less than + :param ticker_lte: Ticker less than or equal to + :param ticker_gt: Ticker greater than + :param ticker_gte: Ticker greater than or equal to + :param ex_dividend_date: Query by ex-dividend date with the format YYYY-MM-DD. + :param ex_dividend_date_lt: Ex-dividend date less than + :param ex_dividend_date_lte: Ex-dividend date less than or equal to + :param ex_dividend_date_gt: Ex-dividend date greater than + :param ex_dividend_date_gte: Ex-dividend date greater than or equal to + :param record_date: Query by record date with the format YYYY-MM-DD. + :param record_date_lt: Record date less than + :param record_date_lte: Record date less than or equal to + :param record_date_gt: Record date greater than + :param record_date_gte: Record date greater than or equal to + :param declaration_date: Query by declaration date with the format YYYY-MM-DD. + :param declaration_date_lt: Declaration date less than + :param declaration_date_lte: Declaration date less than or equal to + :param declaration_date_gt: Declaration date greater than + :param declaration_date_gte: Declaration date greater than or equal to + :param pay_date: Query by pay date with the format YYYY-MM-DD. + :param pay_date_lt: Pay date less than + :param pay_date_lte: Pay date less than or equal to + :param pay_date_gt: Pay date greater than + :param pay_date_gte: Pay date greater than or equal to + :param frequency: Query by the number of times per year the dividend is paid out. Possible values are 0 (one-time), 1 (annually), 2 (bi-annually), 4 (quarterly), and 12 (monthly). + :param cash_amount: Query by the cash amount of the dividend. + :param dividend_type: Query by the type of dividend. Dividends that have been paid and/or are expected to be paid on consistent schedules are denoted as CD. Special Cash dividends that have been paid that are infrequent or unusual, and/or can not be expected to occur in the future are denoted as SC. + :param limit: Limit the number of results returned, default is 10 and max is 1000. + :param sort: Sort field used for ordering. + :param order: Order results based on the sort field. + :param params: Any additional query params + :param raw: Return raw object instead of results object + :return: List of dividends + """ + url = "/v3/reference/dividends" + + return self._paginate( + path=url, + params=self._get_params(self.list_dividends, locals()), + raw=raw, + deserializer=Dividend.from_dict, + )