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 of RuntimeCache.
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, and when. 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, and when 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, and when 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, and when. 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, and when 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, and when and a row for each announcement.