Feature: Earning Calendar (& other calendars)

doc/source/reference/examples/calendars.py

@@ -0,0 +1,38 @@
+import yfinance as yf
+from datetime import datetime, timedelta
+
+# Default init (today + 7 days)
+calendar = yf.Calendars()
+
+# Today's events: calendar of 1 day
+tomorrow = datetime.now() + timedelta(days=1)
+calendar = yf.Calendars(end=tomorrow)
+
+# Default calendar queries - accessing the properties will fetch the data from YF
+calendar.earnings_calendar
+calendar.ipo_info_calendar
+calendar.splits_calendar
+calendar.economic_events_calendar
+
+# Manual queries
+calendar.get_earnings_calendar()
+calendar.get_ipo_info_calendar()
+calendar.get_splits_calendar()
+calendar.get_economic_events_calendar()
+
+# Earnings calendar custom filters
+calendar.get_earnings_calendar(
+    market_cap=100_000_000,  # filter out small-cap 
+    filter_most_active=True,  # show only actively traded. Uses: `screen(query="MOST_ACTIVES")`
+)
+
+# Example of real use case:
+# Get inminent unreported earnings events
+today = datetime.now()
+is_friday = today.weekday() == 4
+day_after_tomorrow = today + timedelta(days=4 if is_friday else 2)
+
+calendar = yf.Calendars(today, day_after_tomorrow)
+df = calendar.get_earnings_calendar(limit=100)
+
+unreported_df = df[df["Reported EPS"].isnull()]

doc/source/reference/index.rst

@@ -16,6 +16,7 @@ The following are the publicly available classes, and functions exposed by the `
 - :attr:`Ticker <yfinance.Ticker>`: Class for accessing single ticker data.
 - :attr:`Tickers <yfinance.Tickers>`: Class for handling multiple tickers.
 - :attr:`Market <yfinance.Market>`: Class for accessing market summary.
+- :attr:`Calendars <yfinance.Calendars>`: Class for accessing calendar events data.
 - :attr:`download <yfinance.download>`: Function to download market data for multiple tickers.
 - :attr:`Search <yfinance.Search>`: Class for accessing search results.
 - :attr:`Lookup <yfinance.Lookup>`: Class for looking up tickers.
@@ -38,6 +39,7 @@ The following are the publicly available classes, and functions exposed by the `
    yfinance.ticker_tickers
    yfinance.stock
    yfinance.market
+   yfinance.calendars
    yfinance.financials
    yfinance.analysis
    yfinance.market

doc/source/reference/yfinance.calendars.rst

@@ -0,0 +1,21 @@
+=====================
+Calendars
+=====================
+
+.. currentmodule:: yfinance
+
+
+Class
+------------
+The `Calendars` class allows you to get information about upcoming events, for example, earning events.
+
+.. autosummary::
+   :toctree: api/
+
+   Calendars
+
+Sample Code
+------------------
+
+.. literalinclude:: examples/calendars.py
+   :language: python

tests/test_calendars.py

@@ -0,0 +1,46 @@
+import unittest
+
+import pandas as pd
+
+from tests.context import yfinance as yf, session_gbl
+
+
+class TestCalendars(unittest.TestCase):
+    def setUp(self):
+        self.calendars = yf.Calendars(session=session_gbl)
+
+    def test_get_earnings_calendar(self):
+        result = self.calendars.get_earnings_calendar(limit=5)
+        tickers = self.calendars.earnings_tickers
+
+        self.assertIsInstance(result, pd.DataFrame)
+        self.assertEqual(len(result), 5)
+        self.assertIsInstance(tickers, list)
+        self.assertEqual(len(tickers), len(result))
+        self.assertEqual(tickers, result.index.tolist())
+
+        first_ticker = result.index[0]
+        result = self.calendars.get_earnings_ticker(first_ticker)
+        self.assertIn(first_ticker, result.index.tolist())
+
+    def test_get_ipo_info_calendar(self):
+        result = self.calendars.get_ipo_info_calendar(limit=5)
+
+        self.assertIsInstance(result, pd.DataFrame)
+        self.assertEqual(len(result), 5)
+
+    def test_get_economic_events_calendar(self):
+        result = self.calendars.get_economic_events_calendar(limit=5)
+
+        self.assertIsInstance(result, pd.DataFrame)
+        self.assertEqual(len(result), 5)
+
+    def test_get_splits_calendar(self):
+        result = self.calendars.get_splits_calendar(limit=5)
+
+        self.assertIsInstance(result, pd.DataFrame)
+        self.assertEqual(len(result), 5)
+
+
+if __name__ == "__main__":
+    unittest.main()

yfinance/__init__.py

@@ -23,6 +23,7 @@
 from .search import Search
 from .lookup import Lookup
 from .ticker import Ticker
+from .calendars import Calendars
 from .tickers import Tickers
 from .multi import download
 from .live import WebSocket, AsyncWebSocket
@@ -42,7 +43,7 @@
 import warnings
 warnings.filterwarnings('default', category=DeprecationWarning, module='^yfinance')
 
-__all__ = ['download', 'Market', 'Search', 'Lookup', 'Ticker', 'Tickers', 'enable_debug_mode', 'set_tz_cache_location', 'Sector', 'Industry', 'WebSocket', 'AsyncWebSocket']
+__all__ = ['download', 'Market', 'Search', 'Lookup', 'Ticker', 'Tickers', 'enable_debug_mode', 'set_tz_cache_location', 'Sector', 'Industry', 'WebSocket', 'AsyncWebSocket', 'Calendars']
 # screener stuff:
 __all__ += ['EquityQuery', 'FundQuery', 'screen', 'PREDEFINED_SCREENER_QUERIES']