feat: earning calendar first commit

bringing Calendar class to yfinance, already working, still need to verify some stuff and integrate with rest of yfinance

rename to calendars: introduce the idea of multiple calendars

refactor: more types of calendar (ipo, splits, etc)

added custom class Operand for query building

documentation and example reference

 rename Operand to CalendarQuery

input dates support date and str, improved col names, improved cache management, rm useless helper functions, rm col names from docstring

added support for timestamps

utils._parse_user_dt has default tz=utc

Author: ianmihura

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,55 @@
+from datetime import datetime, timedelta, timezone
+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_calendar.index.tolist()
+
+        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.tolist()[0]
+        result_first_ticker = self.calendars.earnings_calendar.loc[first_ticker].name
+        self.assertEqual(first_ticker, result_first_ticker)
+
+    def test_get_earnings_calendar_init_params(self):
+        result = self.calendars.get_earnings_calendar(limit=5)
+        self.assertGreaterEqual(result['Event Start Date'].iloc[0], pd.to_datetime(datetime.now(tz=timezone.utc)))
+
+        start = datetime.now(tz=timezone.utc) - timedelta(days=7)
+        result = yf.Calendars(start=start).get_earnings_calendar(limit=5)
+        self.assertGreaterEqual(result['Event Start Date'].iloc[0], pd.to_datetime(start))
+
+    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']