kensho-kfinance 2.4.2__py3-none-any.whl → 2.6.1__py3-none-any.whl

kfinance/kfinance.py

@@ -4,7 +4,6 @@ from collections.abc import Sequence
 from concurrent.futures import ThreadPoolExecutor
 from copy import deepcopy
 from datetime import date, datetime, timezone
-from functools import cached_property
 from io import BytesIO
 import logging
 import re
@@ -80,8 +79,9 @@ class TradingItem:
         """
         self.kfinance_api_client = kfinance_api_client
         self.trading_item_id = trading_item_id
-        self.ticker: Optional[str] = None
-        self.exchange_code: Optional[str] = None
+
+        self._ticker: str | None = None
+        self._history_metadata: HistoryMetadata | None = None
 
     def __str__(self) -> str:
         """String representation for the company object"""
@@ -104,36 +104,35 @@ class TradingItem:
             "trading_item_id"
         ]
         trading_item = TradingItem(kfinance_api_client, trading_item_id)
-        trading_item.ticker = ticker
-        trading_item.exchange_code = exchange_code
+        trading_item._ticker = ticker
         return trading_item
 
-    @cached_property
-    def trading_item_id(self) -> int:
-        """Get the trading item id for the object
-
-        :return: the CIQ trading item id
-        :rtype: int
-        """
-        return self.trading_item_id
-
-    @cached_property
+    @property
     def history_metadata(self) -> HistoryMetadata:
         """Get information about exchange and quotation
 
         :return: A dict containing data about the currency, symbol, exchange, type of instrument, and the first trading date
         :rtype: HistoryMetadata
         """
-        metadata = self.kfinance_api_client.fetch_history_metadata(self.trading_item_id)
-        if self.exchange_code is None:
-            self.exchange_code = metadata["exchange_name"]
-        return {
-            "currency": metadata["currency"],
-            "symbol": metadata["symbol"],
-            "exchange_name": metadata["exchange_name"],
-            "instrument_type": metadata["instrument_type"],
-            "first_trade_date": datetime.strptime(metadata["first_trade_date"], "%Y-%m-%d").date(),
-        }
+        if self._history_metadata is None:
+            metadata = self.kfinance_api_client.fetch_history_metadata(self.trading_item_id)
+            self._history_metadata = HistoryMetadata(
+                currency=metadata["currency"],
+                symbol=metadata["symbol"],
+                exchange_name=metadata["exchange_name"],
+                instrument_type=metadata["instrument_type"],
+                first_trade_date=datetime.strptime(metadata["first_trade_date"], "%Y-%m-%d").date(),
+            )
+        return self._history_metadata
+
+    @property
+    def exchange_code(self) -> str:
+        """Return the exchange_code of the trading item
+
+        :return: The exchange code of the trading item.
+        :rtype: str
+        """
+        return self.history_metadata["exchange_name"]
 
     def history(
         self,
@@ -307,7 +306,12 @@ class Company(CompanyFunctionsMetaClass):
     :type company_id: int
     """
 
-    def __init__(self, kfinance_api_client: KFinanceApiClient, company_id: int):
+    def __init__(
+        self,
+        kfinance_api_client: KFinanceApiClient,
+        company_id: int,
+        company_name: str | None = None,
+    ):
         """Initialize the Company object
 
         :param kfinance_api_client: The KFinanceApiClient used to fetch data
@@ -317,45 +321,69 @@ class Company(CompanyFunctionsMetaClass):
         """
         super().__init__()
         self.kfinance_api_client = kfinance_api_client
-        self.company_id = company_id
+        self._company_id = company_id
         self._all_earnings: list[Earnings] | None = None
+        self._mergers_for_company: dict[str, MergersAndAcquisitions] | None = None
+        self._company_name = company_name
+
+        self._securities: Securities | None = None
+        self._primary_security: Security | None = None
+        self._info: dict | None = None
+        self._earnings_call_datetimes: list[datetime] | None = None
+
+    @property
+    def company_id(self) -> int:
+        """Return the company_id of the company.
+
+        :return: the company_id of the company
+        :rtype: int
+        """
+        return self._company_id
 
     def __str__(self) -> str:
         """String representation for the company object"""
         return f"{type(self).__module__}.{type(self).__qualname__} of {self.company_id}"
 
-    @cached_property
+    @property
     def primary_security(self) -> Security:
         """Return the primary security item for the Company object
 
         :return: a Security object of the primary security of company_id
         :rtype: Security
         """
-        primary_security_id = self.kfinance_api_client.fetch_primary_security(self.company_id)[
-            "primary_security"
-        ]
-        return Security(
-            kfinance_api_client=self.kfinance_api_client, security_id=primary_security_id
-        )
+        if self._primary_security is None:
+            primary_security_id = self.kfinance_api_client.fetch_primary_security(self.company_id)[
+                "primary_security"
+            ]
+            self._primary_security = Security(
+                kfinance_api_client=self.kfinance_api_client, security_id=primary_security_id
+            )
+        return self._primary_security
 
-    @cached_property
+    @property
     def securities(self) -> Securities:
         """Return the security items for the Company object
 
         :return: a Securities object containing the list of securities of company_id
         :rtype: Securities
         """
-        security_ids = self.kfinance_api_client.fetch_securities(self.company_id)["securities"]
-        return Securities(kfinance_api_client=self.kfinance_api_client, security_ids=security_ids)
+        if self._securities is None:
+            security_ids = self.kfinance_api_client.fetch_securities(self.company_id)["securities"]
+            self._securities = Securities(
+                kfinance_api_client=self.kfinance_api_client, security_ids=security_ids
+            )
+        return self._securities
 
-    @cached_property
+    @property
     def info(self) -> dict:
         """Get the company info
 
         :return: a dict with containing: name, status, type, simple industry, number of employees (if available), founding date, webpage, address, city, zip code, state, country, & iso_country
         :rtype: dict
         """
-        return self.kfinance_api_client.fetch_info(self.company_id)
+        if self._info is None:
+            self._info = self.kfinance_api_client.fetch_info(self.company_id)
+        return self._info
 
     @property
     def name(self) -> str:
@@ -364,7 +392,7 @@ class Company(CompanyFunctionsMetaClass):
         :return: The company name
         :rtype: str
         """
-        return self.info["name"]
+        return self._company_name if self._company_name else self.info["name"]
 
     @property
     def status(self) -> str:
@@ -474,19 +502,21 @@ class Company(CompanyFunctionsMetaClass):
         """
         return self.info["iso_country"]
 
-    @cached_property
+    @property
     def earnings_call_datetimes(self) -> list[datetime]:
         """Get the datetimes of the companies earnings calls
 
         :return: a list of datetimes for the companies earnings calls
         :rtype: list[datetime]
         """
-        return [
-            datetime.fromisoformat(earnings_call).replace(tzinfo=timezone.utc)
-            for earnings_call in self.kfinance_api_client.fetch_earnings_dates(self.company_id)[
-                "earnings"
+        if self._earnings_call_datetimes is None:
+            self._earnings_call_datetimes = [
+                datetime.fromisoformat(earnings_call).replace(tzinfo=timezone.utc)
+                for earnings_call in self.kfinance_api_client.fetch_earnings_dates(self.company_id)[
+                    "earnings"
+                ]
             ]
-        ]
+        return self._earnings_call_datetimes
 
     @property
     def all_earnings(self) -> list[Earnings]:
@@ -603,6 +633,103 @@ class Company(CompanyFunctionsMetaClass):
         # Sort by datetime ascending and get the earliest
         return min(future_earnings, key=lambda x: x.datetime)
 
+    @property
+    def mergers_and_acquisitions(self) -> dict[str, MergersAndAcquisitions]:
+        """Get the mergers and acquisitions this company has been party to.
+
+        :return: three lists of transactions, one each for 'target', 'buyer', and 'seller'
+        :rtype: dict[str, MergersAndAcquisitions]
+        """
+        if self._mergers_for_company is None:
+            mergers_for_company = self.kfinance_api_client.fetch_mergers_for_company(
+                company_id=self.company_id
+            )
+            output: dict = {}
+            for literal in ["target", "buyer", "seller"]:
+                output[literal] = MergersAndAcquisitions(
+                    self.kfinance_api_client, mergers_for_company[literal]
+                )
+            self._mergers_for_company = output
+        return self._mergers_for_company
+
+
+class AdvisedCompany(Company):
+    """A Company that has been involved in a transaction is a company that may have been advised."""
+
+    def __init__(
+        self,
+        kfinance_api_client: KFinanceApiClient,
+        company_id: int,
+        transaction_id: int,
+        company_name: str | None = None,
+    ):
+        """Initialize the AdvisedCompany object
+
+        :param kfinance_api_client: The KFinanceApiClient used to fetch data
+        :type kfinance_api_client: KFinanceApiClient
+        :param company_id: The S&P Global CIQ Company Id
+        :type company_id: int
+        :param transaction_id: The S&P Global CIP Transaction Id
+        :type transaction_id: int
+        """
+
+        super().__init__(
+            kfinance_api_client=kfinance_api_client,
+            company_id=company_id,
+            company_name=company_name,
+        )
+        self.transaction_id = transaction_id
+
+    @property
+    def advisors(self) -> Companies | None:
+        """Get the companies that advised this company during the current transaction."""
+        advisors = self.kfinance_api_client.fetch_advisors_for_company_in_merger(
+            transaction_id=self.transaction_id, advised_company_id=self.company_id
+        )["advisors"]
+        companies = [
+            AdvisorCompany(
+                kfinance_api_client=self.kfinance_api_client,
+                company_id=int(advisor["advisor_company_id"]),
+                company_name=str(advisor["advisor_company_name"]),
+                advisor_type_name=str(advisor["advisor_type_name"]),
+            )
+            for advisor in advisors
+        ]
+        return Companies(kfinance_api_client=self.kfinance_api_client, companies=companies)
+
+
+class AdvisorCompany(Company):
+    """A company that advised another company during a transaction."""
+
+    def __init__(
+        self,
+        kfinance_api_client: KFinanceApiClient,
+        company_id: int,
+        advisor_type_name: str,
+        company_name: str | None = None,
+    ):
+        """Initialize the AdvisorCompany object
+
+        :param kfinance_api_client: The KFinanceApiClient used to fetch data
+        :type kfinance_api_client: KFinanceApiClient
+        :param company_id: The S&P Global CIQ Company Id
+        :type company_id: int
+        :param advisor_type_name: The type of the advisor company
+        :type advisor_type_name: str
+        """
+
+        super().__init__(
+            kfinance_api_client=kfinance_api_client,
+            company_id=company_id,
+            company_name=company_name,
+        )
+        self._advisor_type_name = advisor_type_name
+
+    @property
+    def advisor_type_name(self) -> str | None:
+        """When this company advised another during a transaction, get the advisor type name."""
+        return self._advisor_type_name
+
 
 class Security:
     """Security class
@@ -628,57 +755,69 @@ class Security:
         self.kfinance_api_client = kfinance_api_client
         self.security_id = security_id
 
+        self._cusip: str | None = None
+        self._isin: str | None = None
+        self._primary_trading_item: TradingItem | None = None
+        self._trading_items: TradingItems | None = None
+
     def __str__(self) -> str:
         """String representation for the security object"""
         return f"{type(self).__module__}.{type(self).__qualname__} of {self.security_id}"
 
-    @cached_property
+    @property
     def isin(self) -> str:
         """Get the ISIN for the object
 
         :return: The ISIN
         :rtype: str
         """
-        return self.kfinance_api_client.fetch_isin(self.security_id)["isin"]
+        if self._isin is None:
+            self._isin = self.kfinance_api_client.fetch_isin(self.security_id)["isin"]
+        return self._isin
 
-    @cached_property
+    @property
     def cusip(self) -> str:
         """Get the CUSIP for the object
 
         :return: The CUSIP
         :rtype: str
         """
-        return self.kfinance_api_client.fetch_cusip(self.security_id)["cusip"]
+        if self._cusip is None:
+            self._cusip = self.kfinance_api_client.fetch_cusip(self.security_id)["cusip"]
+        return self._cusip
 
-    @cached_property
+    @property
     def primary_trading_item(self) -> TradingItem:
         """Return the primary trading item for the Security object
 
         :return: a TradingItem object of the primary trading item of security_id
         :rtype: TradingItem
         """
-        primary_trading_item_id = self.kfinance_api_client.fetch_primary_trading_item(
-            self.security_id
-        )["primary_trading_item"]
-        self.primary_trading_item = TradingItem(
-            kfinance_api_client=self.kfinance_api_client, trading_item_id=primary_trading_item_id
-        )
-        return self.primary_trading_item
+        if self._primary_trading_item is None:
+            primary_trading_item_id = self.kfinance_api_client.fetch_primary_trading_item(
+                self.security_id
+            )["primary_trading_item"]
+            self._primary_trading_item = TradingItem(
+                kfinance_api_client=self.kfinance_api_client,
+                trading_item_id=primary_trading_item_id,
+            )
+        return self._primary_trading_item
 
-    @cached_property
+    @property
     def trading_items(self) -> TradingItems:
         """Return the trading items for the Security object
 
         :return: a TradingItems object containing the list of trading items of security_id
         :rtype: TradingItems
         """
-        trading_item_ids = self.kfinance_api_client.fetch_trading_items(self.security_id)[
-            "trading_items"
-        ]
-        self.trading_items = TradingItems(
-            kfinance_api_client=self.kfinance_api_client, trading_item_ids=trading_item_ids
-        )
-        return self.trading_items
+        if self._trading_items is None:
+            trading_item_ids = self.kfinance_api_client.fetch_trading_items(self.security_id)[
+                "trading_items"
+            ]
+            self._trading_items = TradingItems(
+                kfinance_api_client=self.kfinance_api_client, trading_item_ids=trading_item_ids
+            )
+        return self._trading_items
 
 
 class Ticker(DelegatedCompanyFunctionsMetaClass):
@@ -740,6 +879,11 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
                 "Neither an identifier nor an identification triple (company id, security id, & trading item id) were passed in"
             )
 
+        self._primary_security: Security | None = None
+        self._primary_trading_item: TradingItem | None = None
+        self._company: Company | None = None
+        self._history_metadata: HistoryMetadata | None = None
+
     @property
     def id_triple(self) -> IdentificationTriple:
         """Returns a unique identification triple for the Ticker object.
@@ -823,44 +967,46 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         """
         return self.id_triple.trading_item_id
 
-    @cached_property
+    @property
     def primary_security(self) -> Security:
         """Set and return the primary security for the object
 
         :return: The primary security as a Security object
         :rtype: Security
         """
+        if self._primary_security is None:
+            self._primary_security = Security(
+                kfinance_api_client=self.kfinance_api_client, security_id=self.security_id
+            )
+        return self._primary_security
 
-        self.primary_security = Security(
-            kfinance_api_client=self.kfinance_api_client, security_id=self.security_id
-        )
-        return self.primary_security
-
-    @cached_property
+    @property
     def company(self) -> Company:
         """Set and return the company for the object
 
         :return: The company returned as Company object
         :rtype: Company
         """
-        self.company = Company(
-            kfinance_api_client=self.kfinance_api_client, company_id=self.company_id
-        )
-        return self.company
+        if self._company is None:
+            self._company = Company(
+                kfinance_api_client=self.kfinance_api_client, company_id=self.company_id
+            )
+        return self._company
 
-    @cached_property
+    @property
     def primary_trading_item(self) -> TradingItem:
         """Set and return the trading item for the object
 
         :return: The trading item returned as TradingItem object
         :rtype: TradingItem
         """
-        self.primary_trading_item = TradingItem(
-            kfinance_api_client=self.kfinance_api_client, trading_item_id=self.trading_item_id
-        )
-        return self.primary_trading_item
+        if self._primary_trading_item is None:
+            self._primary_trading_item = TradingItem(
+                kfinance_api_client=self.kfinance_api_client, trading_item_id=self.trading_item_id
+            )
+        return self._primary_trading_item
 
-    @cached_property
+    @property
     def isin(self) -> str:
         """Get the ISIN for the object
 
@@ -873,7 +1019,7 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         self._isin = isin
         return isin
 
-    @cached_property
+    @property
     def cusip(self) -> str:
         """Get the CUSIP for the object
 
@@ -886,7 +1032,7 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         self._cusip = cusip
         return cusip
 
-    @cached_property
+    @property
     def info(self) -> dict:
         """Get the company info for the ticker
 
@@ -1012,7 +1158,7 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         """
         return self.company.iso_country
 
-    @cached_property
+    @property
     def earnings_call_datetimes(self) -> list[datetime]:
         """Get the datetimes of the companies earnings calls
 
@@ -1021,7 +1167,7 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         """
         return self.company.earnings_call_datetimes
 
-    @cached_property
+    @property
     def history_metadata(self) -> HistoryMetadata:
         """Get information about exchange and quotation
 
@@ -1035,7 +1181,7 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
             self._ticker = metadata["symbol"]
         return metadata
 
-    @cached_property
+    @property
     def ticker(self) -> str:
         """Get the ticker if it isn't available from initialization"""
         if self._ticker is not None:
@@ -1111,20 +1257,146 @@ class BusinessRelationships(NamedTuple):
         return f"{type(self).__module__}.{type(self).__qualname__} of {str(dictionary)}"
 
 
+class MergerOrAcquisition:
+    """An object that represents a merger or an acquisition of a company."""
+
+    def __init__(
+        self, kfinance_api_client: KFinanceApiClient, transaction_id: int, merger_title: str | None
+    ) -> None:
+        """MergerOrAcqusition initializer.
+
+        :param kfinance_api_client: The KFinanceApiClient used to retrieve data.
+        :type kfinance_api_client: KFinanceApiClient
+
+        """
+        self.kfinance_api_client = kfinance_api_client
+        self.transaction_id = transaction_id
+        self.merger_title = merger_title
+        self._merger_info: dict | None = None
+
+    @property
+    def merger_info(self) -> dict:
+        """Property for the combined information in the merger."""
+        if not self._merger_info:
+            self._merger_info = self.kfinance_api_client.fetch_merger_info(self.transaction_id)
+            timeline = pd.DataFrame(self.merger_info["timeline"])
+            timeline["date"] = pd.to_datetime(timeline["date"])
+            self._merger_info["timeline"] = timeline
+            details = pd.DataFrame(self.merger_info["consideration"]["details"])
+            self._merger_info["consideration"]["details"] = details
+        return self._merger_info
+
+    @property
+    def get_merger_title(self) -> str | None:
+        """The merger title includes the status of the merger and its target."""
+        return self.merger_title
+
+    @property
+    def get_timeline(self) -> pd.DataFrame:
+        """The timeline of the merger includes every new status, along with the dates of each status change."""
+        return self.merger_info["timeline"]
+
+    @property
+    def get_participants(self) -> dict:
+        """A merger's participants are organized into categories: the target, the buyer or buyers, and the seller or sellers.
+
+        Each category is a single Company or a list of Companies.
+        """
+        return {
+            "target": AdvisedCompany(
+                kfinance_api_client=self.kfinance_api_client,
+                company_id=self.merger_info["participants"]["target"]["company_id"],
+                company_name=self.merger_info["participants"]["target"]["company_name"],
+                transaction_id=self.transaction_id,
+            ),
+            "buyers": Companies(
+                kfinance_api_client=self.kfinance_api_client,
+                companies=[
+                    AdvisedCompany(
+                        kfinance_api_client=self.kfinance_api_client,
+                        company_id=company["company_id"],
+                        company_name=company["company_name"],
+                        transaction_id=self.transaction_id,
+                    )
+                    for company in self.merger_info["participants"]["buyers"]
+                ],
+            ),
+            "sellers": Companies(
+                kfinance_api_client=self.kfinance_api_client,
+                companies=[
+                    AdvisedCompany(
+                        kfinance_api_client=self.kfinance_api_client,
+                        company_id=company["company_id"],
+                        company_name=company["company_name"],
+                        transaction_id=self.transaction_id,
+                    )
+                    for company in self.merger_info["participants"]["sellers"]
+                ],
+            ),
+        }
+
+    @property
+    def get_consideration(self) -> dict:
+        """A merger's consideration is the assets exchanged for the target company.
+
+        Properties in the consideration include:
+            - The currency of the consideration.
+            - The current gross total value of the consideration.
+            - The current implied equity value of the consideration.
+            - The current implied enterprise value of the consideration.
+            - A list of the consideration's details (sub-components of the consideration), where each consideration detail contains:
+                - The detail scenario.
+                - The detail subtype.
+                - The cash or cash equivalent offered per share.
+                - The number of shares in the target company.
+                - The current gross total of the consideration detail.
+        """
+        return self.merger_info["consideration"]
+
+
 @add_methods_of_singular_class_to_iterable_class(Company)
 class Companies(set):
     """Base class for representing a set of Companies"""
 
-    def __init__(self, kfinance_api_client: KFinanceApiClient, company_ids: Iterable[int]) -> None:
+    def __init__(
+        self,
+        kfinance_api_client: KFinanceApiClient,
+        company_ids: Optional[Iterable[int]] = None,
+        transaction_id: Optional[int] = None,
+        companies: Optional[Iterable[Company]] = None,
+    ) -> None:
         """Initialize the Companies object
 
         :param kfinance_api_client: The KFinanceApiClient used to fetch data
         :type kfinance_api_client: KFinanceApiClient
         :param company_ids: An iterable of S&P CIQ Company ids
         :type company_ids: Iterable[int]
+        :param transaction_id: If the companies were party to a transaction, the S&P CIQ Transaction Id
+        :type transaction_id: Optional[int]
+        :param companies: If there's already an iterable of Company objects
+        :type companies: Iterable[Company]
         """
         self.kfinance_api_client = kfinance_api_client
-        super().__init__(Company(kfinance_api_client, company_id) for company_id in company_ids)
+        if companies is not None:
+            super().__init__(company for company in companies)
+        elif company_ids is not None:
+            if transaction_id is not None:
+                super().__init__(
+                    AdvisedCompany(
+                        kfinance_api_client=kfinance_api_client,
+                        company_id=company_id,
+                        transaction_id=transaction_id,
+                    )
+                    for company_id in company_ids
+                )
+            else:
+                super().__init__(
+                    Company(
+                        kfinance_api_client=kfinance_api_client,
+                        company_id=company_id,
+                    )
+                    for company_id in company_ids
+                )
 
 
 @add_methods_of_singular_class_to_iterable_class(Security)
@@ -1241,6 +1513,29 @@ class Tickers(set):
         )
 
 
+@add_methods_of_singular_class_to_iterable_class(MergerOrAcquisition)
+class MergersAndAcquisitions(set):
+    def __init__(
+        self, kfinance_api_client: KFinanceApiClient, ids_and_titles: Iterable[dict]
+    ) -> None:
+        """MergersAndAcquisitions initializer.
+
+        :param kfinance_api_client: The KFinanceApiClient used to fetch data.
+        :type kfinance_api_client: KFinanceApiClient
+        :param ids_and_titles: A iterable of transaction IDs and merger titles.
+        :type ids_and_titles: Iterable[dict]
+        """
+        self.kfinance_api_client = kfinance_api_client
+        super().__init__(
+            MergerOrAcquisition(
+                kfinance_api_client=kfinance_api_client,
+                transaction_id=id_and_title["transaction_id"],
+                merger_title=id_and_title["merger_title"],
+            )
+            for id_and_title in ids_and_titles
+        )
+
+
 class Client:
     """Client class with LLM tools and a pre-credentialed Ticker object
 
@@ -1561,6 +1856,24 @@ class Client:
         transcript_data = self.kfinance_api_client.fetch_transcript(key_dev_id)
         return Transcript(transcript_data["transcript"])
 
+    def mergers_and_acquisitions(self, company_id: int) -> dict[str, MergersAndAcquisitions]:
+        """Generate 3 named lists of MergersAndAcquisitions objects from company_id.
+
+        :param company_id: S&P Global company ID
+        :type company_id: int
+        :return: A dictionary of three keys ('target', 'buyer', and 'seller'), each of whose values is a MergersAndAcquisitions.
+        :rtype: dict[str, MergersAndAcquisitions]
+        """
+        mergers_for_company = self.kfinance_api_client.fetch_mergers_for_company(
+            company_id=company_id
+        )
+        output: dict = {}
+        for literal in ["target", "buyer", "seller"]:
+            output[literal] = MergersAndAcquisitions(
+                self.kfinance_api_client, mergers_for_company[literal]
+            )
+        return output
+
     @staticmethod
     def get_latest(use_local_timezone: bool = True) -> LatestPeriods:
         """Get the latest annual reporting year, latest quarterly reporting quarter and year, and current date.