API¶
Package contents¶
A package for getting a US equity earnings announcement calendar.
-
ecal.
get
(start_date_str, end_date_str=None, fetcher=None, cache=None)¶ This function returns an earnings announcement calendar as a DataFrame.
- Args:
- fetcher (AbstractFetcher):
- The fetcher to use for downloading data. If no fetcher is provided, it will use an instance of
ECNFetcher
. cache (AbstractCache): The cache to use for storing data. If no cache is provided, it will use an instance ofRuntimeCache
. - start_date_str (str):
- The start date of the earnings calendar in the format
YYYY-MM-DD
. - end_date_str (str):
- The end date of the earnings calendar in the format
YYYY-MM-DD
. If left out, we will fetch only the announcements for the start date.
- Returns:
- DataFrame:
Returns a pandas DataFrame indexed by
date
and that has columns:ticker
, andwhen
. Each row represents a single announcement. For example:ticker when date 2018-01-04 CMC bmo 2018-01-04 LNDC amc 2018-01-04 NEOG bmo 2018-01-04 RAD amc 2018-01-04 RECN amc 2018-01-04 UNF bmo
-
class
ecal.
AbstractFetcher
¶ Bases:
object
Abstract base class for earnings calendar fetchers.
-
fetch_calendar
(start_date_str, end_date_str=None)¶ Implement this method! Your method should return a pandas DataFrame.
- Args:
- start_date_str (str):
- The start date of the earnings calendar in the format
YYYY-MM-DD
. - end_date_str (str):
- The end date of the earnings calendar in the format
YYYY-MM-DD
. If left out, we will fetch only the announcements for the start date.
- Returns:
- DataFrame:
- Returns a pandas DataFrame indexed by
date
, that has columns:ticker
, andwhen
and a row for each announcement.
-
-
class
ecal.
ECNFetcher
(rate_limit=1.5)¶ Bases:
ecal.abstract_fetcher.AbstractFetcher
This class fetches earnings announcements from
api.earningscalendar.net
.One of the main things ECNFetcher does is prevent calling the API too many times to prevent throttling.
-
fetch_calendar
(start_date_str, end_date_str=None)¶ Returns the earnings calendar as a pandas DataFrame.
- Args:
- start_date_str (str):
- The start date of the earnings calendar in the format
YYYY-MM-DD
. - end_date_str (str):
- The end date of the earnings calendar in the format
YYYY-MM-DD
. If left out, we will fetch only the announcements for the start date.
- Returns:
- DataFrame:
- Returns a pandas DataFrame indexed by
date
, that has columns:ticker
, andwhen
and a row for each announcement.
-
-
class
ecal.
AbstractCache
¶ Bases:
object
AbstractCache is the base class for all cache classes.
- Derived classes must implement:
- check_for_missing_dates
- add
- fetch_calendar
-
add
(missing_dates, uncached_announcements)¶ Add the uncached announcements to the cache.
- Args:
- missing_dates (list):
- The dates that were fetched and should be added to the cache index. Even dates that have no data should be added to the cache index so that if requested again, we return nothing for them without using the fetcher.
- uncached_announcements (DataFrame):
- A DataFrame containing uncached announcements that should be added to the cache.
-
check_for_missing_dates
(date_list)¶ Look in the cache for dates and return the dates that aren’t in the cache.
- Args:
- date_list (list):
- The list of dates to check the cache for.
- Returns:
- list:
- The dates from the date_list that are not in the cache.
-
fetch_calendar
(start_date_str, end_date_str=None)¶ Returns the earnings calendar from the cache as a pandas DataFrame.
- Args:
- start_date_str (str):
- The start date of the earnings calendar in the format
YYYY-MM-DD
. - end_date_str (str):
- The end date of the earnings calendar in the format
YYYY-MM-DD
. If left out, we will fetch only the announcements for the start date.
- Returns:
- DataFrame:
- Returns a pandas DataFrame indexed by
date
, that has columns:ticker
, andwhen
. Each row represents a single earnings announcement.
-
class
ecal.
RuntimeCache
¶ Bases:
ecal.abstract_cache.AbstractCache
RuntimeCache keeps a DataFrame of earnings announcements in memory so that repeated calls to ecal.get are fast.
- Attributes:
- _cache_df (DataFrame):
- DataFrame storing all the earnings announcements that have been fetched.
- _index_set (set):
- Set containing all the dates that earnings announcements have been fetched for. This set is needed because some days don’t have earnings announcements (so they won’t appear in the cache.
-
add
(missing_dates, uncached_announcements)¶ Add the uncached announcements to the cache.
- Args:
- missing_dates (list):
- The dates that were fetched and should be added to the cache index. Even dates that have no data should be added to the cache index so that if requested again, we return nothing for them without using the fetcher.
- uncached_announcements (DataFrame):
- A Dataframe containing uncached announcements that should be added to the cache.
-
check_for_missing_dates
(date_list)¶ Look in the cache for dates and return the dates that aren’t in the cache.
- Args:
- date_list (list):
- The list of dates to check the cache for.
- Returns:
- list:
- The dates from the date_list that are not in the cache.
-
fetch_calendar
(start_date_str, end_date_str=None)¶ Returns the earnings calendar from the cache as a pandas DataFrame.
- Args:
- start_date_str (str):
- The start date of the earnings calendar in the format
YYYY-MM-DD
. - end_date_str (str):
- The end date of the earnings calendar in the format
YYYY-MM-DD
. If left out, we will fetch only the announcements for the start date.
- Returns:
- DataFrame:
- Returns a pandas DataFrame indexed by
date
, that has columns:ticker
, andwhen
and a row for each announcement.
-
class
ecal.
SqliteCache
(db_file_path='ecal.db')¶ Bases:
ecal.abstract_cache.AbstractCache
SqliteCache provides persistent storage for earnings announcements so repeated calls to
ecal.get()
are fast.- Attributes:
- _conn (Connection):
- The sqlite3 database connection.
-
add
(missing_dates, uncached_announcements_df)¶ Add the uncached announcements to the cache.
- Args:
- missing_dates (list):
- The dates that were fetched and should be added to the cache index. Even dates that have no data should be added to the cache index so that if requested again, we return nothing for them without using the fetcher.
- uncached_announcements_df (DataFrame):
- A Dataframe containing uncached announcements that should be added to the cache.
-
check_for_missing_dates
(date_list)¶ Look in the cache for dates and return the dates that aren’t in the cache.
- Args:
- date_list (list):
- The list of dates to check the cache for.
- Returns:
- list:
- The dates from the date_list that are not in the cache.
-
fetch_calendar
(start_date_str, end_date_str=None)¶ Returns the earnings calendar from the cache as a pandas DataFrame.
- Args:
- start_date_str (str):
- The start date of the earnings calendar in the format
YYYY-MM-DD
. - end_date_str (str):
- The end date of the earnings calendar in the format
YYYY-MM-DD
. If left out, we will fetch only the announcements for the start date.
- Returns:
- DataFrame:
- Returns a pandas DataFrame indexed by
date
, that has columns:ticker
, andwhen
and a row for each announcement.