Added optional flat format output param on YahooFinancial class.

Added get_insight() and get_recommendations() methods.

Cleaned up debug loggers.

CHANGES

@@ -59,3 +59,6 @@
 1.18 12/09/2023 -- Merged in branch from shaunpatterson to fix #164.
 1.19 12/12/2023 -- Refactored session management system to handle cookie and crumbs better.
 1.19 12/12/2023 -- Added fixes for #167, #166, #160.
+1.20 12/16/2023 -- Merged in pull request #171 from bjosun.
+1.20 12/17/2023 -- Added optional flat format output param on YahooFinancial class.
+1.20 12/17/2023 -- Added get_insight() and get_recommendations() methods.

README.rst

@@ -16,16 +16,70 @@ A python module that returns stock, cryptocurrency, forex, mutual fund, commodit
 .. image:: https://static.pepy.tech/badge/yahoofinancials/week
  :target: https://pepy.tech/project/yahoofinancials
 
-Current Version: v1.19
+Current Version: v1.20
 
-Version Released: 12/12/2023
+Version Released: 12/17/2023
 
 Report any bugs by opening an issue here: https://github.com/JECSand/yahoofinancials/issues
 
 Overview
 --------
 A powerful financial data module used for pulling both fundamental and technical data from Yahoo Finance.
 
+- New analytic methods in v1.20:
+ - get_insights()
+ - returns data for:
+ - 'instrumentInfo'
+ - 'companySnapshot'
+ - 'recommendation'
+ - 'sigDevs'
+ - 'secReports'
+ - get_recommendations()
+
+- Example:
+
+.. code-block:: python
+
+ print(YahooFinancials('C').get_recommendations())
+
+- Example Output:
+.. code-block:: javascript
+
+ {
+ "C": [
+ {
+ "recommendedSymbols": [
+ {
+ "score": 0.239602,
+ "symbol": "BAC"
+ },
+ {
+ "score": 0.225134,
+ "symbol": "JPM"
+ },
+ {
+ "score": 0.167669,
+ "symbol": "WFC"
+ },
+ {
+ "score": 0.145864,
+ "symbol": "GS"
+ },
+ {
+ "score": 0.134071,
+ "symbol": "F"
+ }
+ ],
+ "symbol": "C"
+ }
+ ]
+ }
+
+- As of Version 1.20, YahooFinancials supports a new optional parameter called flat_format.
+ - When `YahooFinancials(flat_format=True)`, financial statement data will return in a dict instead of a list. The keys of the dict will be the reporting dates.
+ - Default is False, to ensure backwards compatibility.
+
+
 - As of Version 1.9, YahooFinancials supports optional parameters for asynchronous execution, proxies, and international requests.
 
 .. code-block:: python
@@ -41,10 +95,6 @@ A powerful financial data module used for pulling both fundamental and technical
  balance_sheet_data_qt = yahoo_financials.get_financial_stmts('quarterly', 'balance')
  print(balance_sheet_data_qt)
 
-- New methods in Version 1.13:
- - get_esg_score_data()
-
-
 Installation
 -------------
 - yahoofinancials runs on Python 3.7, 3.8, 3.9, 3.10, 3.11, and 3.12
@@ -91,7 +141,7 @@ Module Methods
 --------------
 - The financial data from all methods is returned as JSON.
 - You can run multiple symbols at once using an inputted array or run an individual symbol using an inputted string.
-- YahooFinancials works with Python 3.6, 3.7, 3.8, 3.9, 3.10, and 3.11 and runs on all operating systems. (Windows, Mac, Linux).
+- YahooFinancials works with Python 3.7, 3.8, 3.9, 3.10, 3.11 and 3.12 and runs on all operating systems. (Windows, Mac, Linux).
 
 Featured Methods
 ^^^^^^^^^^^^^^^^
@@ -134,6 +184,7 @@ Additional Module Methods
 - get_cost_of_revenue()
 - get_income_before_tax()
 - get_income_tax_expense()
+- get_esg_score_data()
 - get_gross_profit()
 - get_net_income_from_continuing_ops()
 - get_research_and_development()

setup.py

@@ -10,11 +10,11 @@
 
 setup(
  name='yahoofinancials',
- version='1.19',
+ version='1.20',
  description='A powerful financial data module used for pulling both fundamental and technical data from Yahoo Finance',
  long_description=long_description,
  url='https://github.com/JECSand/yahoofinancials',
- download_url='https://github.com/JECSand/yahoofinancials/archive/1.19.tar.gz',
+ download_url='https://github.com/JECSand/yahoofinancials/archive/1.20.tar.gz',
  author='Connor Sanders',
  author_email='[email protected]',
  license='MIT',

test/test_yahoofinancials.py

@@ -1,7 +1,7 @@
-# YahooFinancials Unit Tests v1.19
-# Version Released: 12/12/2023
+# YahooFinancials Unit Tests v1.20
+# Version Released: 12/17/2023
 # Author: Connor Sanders
-# Tested on Python 3.7, 3.8, 3.9, 3.10, and 3.11
+# Tested on Python 3.7, 3.8, 3.9, 3.10, 3.11, and 3.12
 # Copyright (c) 2023 Connor Sanders <[email protected]>
 # MIT License
 
@@ -42,6 +42,7 @@ def setUp(self):
  self.test_yf_treasuries_multi = yf(us_treasuries)
  self.test_yf_currencies = yf(currencies)
  self.test_yf_concurrent = yf(stocks, concurrent=True)
+ self.test_yf_stock_flat = yf('C', flat_format=True)
 
  # Fundamentals Test
  def test_yf_fundamentals(self):
@@ -103,6 +104,35 @@ def test_yf_concurrency(self):
  result = check_fundamental(multi_all_statement_data_qt, 'all')
  self.assertEqual(result, True)
 
+ # Fundamentals in Flat Format Test
+ def test_yf_fundamentals_flat(self):
+ # Single stock test
+ single_all_statement_data_qt = self.test_yf_stock_flat.get_financial_stmts('quarterly',
+ ['income', 'cash', 'balance'])
+ if ((isinstance(single_all_statement_data_qt.get("incomeStatementHistoryQuarterly").get("C"), dict) and
+ isinstance(single_all_statement_data_qt.get("balanceSheetHistoryQuarterly").get("C"), dict)) and
+ isinstance(single_all_statement_data_qt.get("cashflowStatementHistoryQuarterly").get("C"), dict)):
+ self.assertEqual(True, True)
+ else:
+ self.assertEqual(False, True)
+
+ # Analytic Methods Test
+ def test_yf_analytic_methods(self):
+
+ # Get Insights
+ out = self.test_yf_stock_single.get_insights()
+ if out.get("C").get("instrumentInfo").get("technicalEvents").get("sector") == "Financial Services":
+ self.assertEqual(True, True)
+ else:
+ self.assertEqual(False, True)
+
+ # Get Recommendations
+ out = self.test_yf_stock_single.get_recommendations()
+ if isinstance(out.get("C"), list):
+ self.assertEqual(True, True)
+ else:
+ self.assertEqual(False, True)
+
  # Extra Module Methods Test
  def test_yf_module_methods(self):
 

yahoofinancials/cache.py

@@ -360,7 +360,6 @@ def initialise(self):
  continue
  self.initialised = 0 # failure
 
-
  def lookup(self, strategy):
  if self.dummy:
  return None

yahoofinancials/etl.py → yahoofinancials/data.py

@@ -60,7 +60,7 @@ def get_data(self, session, url, request_headers=None, params=None, proxy=None,
  return response
 
 
-class YahooFinanceETL(object):
+class YahooFinanceData(object):
 
  def __init__(self, ticker, **kwargs):
  self.ticker = ticker.upper() if isinstance(ticker, str) else [t.upper() for t in ticker]
@@ -72,6 +72,7 @@ def __init__(self, ticker, **kwargs):
  self.timeout = kwargs.get("timeout", 30)
  self.proxies = kwargs.get("proxies")
  self.session = kwargs.pop("session", None)
+ self.flat_format = kwargs.get("flat_format", False)
  self._cache = {}
 
  # Minimum interval between Yahoo Finance requests for this instance
@@ -167,9 +168,15 @@ def _construct_url(self, symbol, config, params, freq, request_type):
  params.update({k: v['options'][request_type].get(freq)})
  elif k == "modules" and request_type in v['options']:
  params.update({k: request_type})
+ elif k == "symbol":
+ params.update({k: symbol.lower()})
  elif k not in params:
+ if k == 'reportsCount' and v is None:
+ continue
  params.update({k: v['default']})
  for k, v in _default_query_params.items(): # general defaults
+ if k == 'reportsCount' and v is None:
+ continue
  if k not in params:
  params.update({k: v})
  if params.get("type"):
@@ -183,6 +190,8 @@ def _construct_url(self, symbol, config, params, freq, request_type):
  for k, v in params.items():
  if k != "modules":
  url += "&" + k + "=" + str(v)
+ elif params.get("symbol"):
+ url += "?symbol=" + params.get("symbol")
  return url
 
  # Private method to execute a web scrape request and decrypt the return
@@ -269,6 +278,11 @@ def _get_historical_data(self, url, config, tech_type, statement_type):
  data = self._cache[url]
  if tech_type == '' and statement_type in ["income", "balance", "cash"]:
  data = self._format_raw_fundamental_data(data)
+ elif statement_type == 'analytic':
+ data = data.get("result")
+ if tech_type == "recommendations":
+ if isinstance(data, list) and len(data) > 0:
+ data[0].get("recommendedSymbols")
  else:
  data = self._format_raw_module_data(data, tech_type)
  return data
@@ -519,7 +533,9 @@ def _create_dict_ent(self, up_ticker, statement_type, tech_type, report_name, hi
  dict_ent = {}
  params = {}
  r_map = get_request_config(tech_type, REQUEST_MAP)
- r_cat = get_request_category(tech_type, self.YAHOO_FINANCIAL_TYPES, statement_type)
+ r_cat = None
+ if statement_type != 'analytic':
+ r_cat = get_request_category(tech_type, self.YAHOO_FINANCIAL_TYPES, statement_type)
  YAHOO_URL = self._construct_url(
  up_ticker.lower(),
  r_map,
@@ -568,8 +584,22 @@ def _reformat_stmt_data_process(raw_data):
  else:
  return raw_data
 
+ # Private Method for the Flat Reformat Process
+ @staticmethod
+ def _reformat_stmt_data_process_flat(raw_data):
+ final_data = {}
+ if raw_data is not None:
+ for date_key, data_item in raw_data.items():
+ final_data.update({date_key: data_item})
+ return final_data
+ else:
+ return raw_data
+
  # Private Method to return subdict entry for the statement reformat process
  def _get_sub_dict_ent(self, ticker, raw_data):
+ if self.flat_format:
+ form_data_dict = self._reformat_stmt_data_process_flat(raw_data[ticker])
+ return {ticker: form_data_dict}
  form_data_list = self._reformat_stmt_data_process(raw_data[ticker])
  return {ticker: form_data_list}
 

yahoofinancials/maps.py

@@ -2375,6 +2375,19 @@
  "padTimeSeries": {"required": False, "default": False},
  },
  },
+ "insights": {
+ "path": "https://query1.finance.yahoo.com/ws/insights/v2/finance/insights",
+ "response_field": "finance",
+ "request": {
+ "symbol": {"required": True, "default": None},
+ "reportsCount": {"required": False, "default": None},
+ },
+ },
+ "recommendations": {
+ "path": "https://query1.finance.yahoo.com/v6/finance/recommendationsbysymbol/{symbol}",
+ "response_field": "finance",
+ "request": {},
+ },
 }
 
 USER_AGENTS = [