added planned function signatures, docstrings, and corresponding test case

src/mwfin/functions.py

@@ -0,0 +1,88 @@
+from typing import Union
+
+from aiohttp.client import ClientSession
+from bs4 import BeautifulSoup
+from bs4.element import ResultSet, Tag
+
+
+# The resulting dictionary's keys correspond to the name of the item (row) in the financial statement,
+# while its values will always be tuples with a length corresponding to the number of periods (columns)
+# and elements being the actual numbers, with the exception of the first key-value-pair, which will represent
+# the end dates of the reporting periods as strings (either years or quarters).
+ResultDict = dict[str, Union[tuple[int], tuple[str]]]
+
+
+async def soup_from_url(url: str, session: ClientSession = None) -> BeautifulSoup:
+    """
+    Requests a web page and turns the response text into BeautifulSoup.
+    """
+    pass
+
+
+def extract_end_dates(soup: BeautifulSoup) -> tuple[str]:
+    """
+    Finds and returns the end dates of the reporting periods as strings (either years or quarters) from the page of a
+    financial statement.
+    """
+    pass
+
+
+def find_relevant_table_rows(soup: BeautifulSoup) -> ResultSet:
+    """
+    Returns the table rows containing the data of interest.
+    """
+    pass
+
+
+def convert_number(num_str: str) -> int:
+    """
+    Takes a string like e.g. "420.69M" and returns 42069000000.
+    """
+    pass
+
+
+def extract_row_data(tr: Tag) -> tuple[str, tuple[int]]:
+    """
+    Returns the name of the item displayed in the table row (of a financial statement)
+    as well as a number for each reporting period.
+    """
+    pass
+
+
+def extract_all_data(soup: BeautifulSoup) -> ResultDict:
+    """
+    Extracts financials from the page.
+    """
+    pass
+
+
+async def get_balance_sheet(ticker_symbol: str, yearly: bool = True, quarterly: bool = True,
+                            session: ClientSession = None) -> ResultDict:
+    """
+    Returns data from the balance sheet of the specified company.
+    """
+    pass
+
+
+async def get_income_statement(ticker_symbol: str, yearly: bool = True, quarterly: bool = True,
+                               session: ClientSession = None) -> ResultDict:
+    """
+    Returns data from the income statement of the specified company.
+    """
+    pass
+
+
+async def get_cash_flow_statement(ticker_symbol: str, yearly: bool = True, quarterly: bool = True,
+                                  session: ClientSession = None) -> ResultDict:
+    """
+    Returns data from the cash flow statement of the specified company.
+    """
+    pass
+
+
+async def get_company_financials(ticker_symbol: str, yearly: bool = True, quarterly: bool = True,
+                                 session: ClientSession = None) -> ResultDict:
+    """
+    Returns all fundamentals (balance sheet, income statement and cash flow statement) of the specified company.
+    """
+    pass

tests/test_functions.py

@@ -0,0 +1,34 @@
+from unittest import IsolatedAsyncioTestCase
+
+
+class FunctionsTestCase(IsolatedAsyncioTestCase):
+
+    def test_soup_from_url(self):
+        pass
+
+    def test_extract_end_dates(self):
+        pass
+
+    def test_find_relevant_table_rows(self):
+        pass
+
+    def test_convert_number(self):
+        pass
+
+    def test_extract_row_data(self):
+        pass
+
+    def test_extract_all_data(self):
+        pass
+
+    async def test_get_balance_sheet(self):
+        pass
+
+    async def test_get_income_statement(self):
+        pass
+
+    async def test_get_cash_flow_statement(self):
+        pass
+
+    async def test_get_company_financials(self):
+        pass